ReviewOS

also looking at this

loghqorg/loghq

Deploy: uniform auth session model (main → production)

#7
Merged glennmichael123 wants to merge main into production
282 files +3028 -64856
docs/basics/views.mddeleted+0-742
Changes to docs/basics/views.md
@@ -1,742 +0,0 @@
1---
2title: Views
3description: Learn about STX templating and view rendering in Stacks applications
4---
5
6```
7
8#### @while
9
10```html
11
12<template>
13 @while(items.length > 0)
14 <div>{{ items.pop() }}</div>
15 @endwhile
16</template>
17
18```
19
20### Loop Variables
21
22Within loops, special variables are available:
23
24```html
25
26<template>
27 @foreach(items as item)
28 <div>
29 <!-- Check if first iteration -->
30 @if($loop.first)
31 <span class="badge">First</span>
32 @endif
33
34 <!-- Check if last iteration -->
35 @if($loop.last)
36 <span class="badge">Last</span>
37 @endif
38
39 <!-- Current iteration index (0-based) -->
40 <span>Index: {{ $loop.index }}</span>
41
42 <!-- Current iteration count (1-based) -->
43 <span>Count: {{ $loop.iteration }}</span>
44
45 <!-- Remaining iterations -->
46 <span>Remaining: {{ $loop.remaining }}</span>
47
48 <!-- Total count -->
49 <span>Total: {{ $loop.count }}</span>
50
51 <!-- Even/Odd -->
52 <div :class="'bg-gray': { } $loop.even">
53 {{ item.name }}
54 </div>
55 </div>
56 @endforeach
57</template>
58
59```
60
61### Including Partials
62
63#### @include
64
65```html
66
67<template>
68 <div class="page">
69 @include('partials/header')
70
71 <main>
72 @include('partials/sidebar', { user: currentUser })
73 <div class="content">
74 {{ content }}
75 </div>
76 </main>
77
78 @include('partials/footer')
79 </div>
80</template>
81
82```
83
84#### @includeIf
85
86Include only if the partial exists:
87
88```html
89
90<template>
91 @includeIf('partials/optional-banner')
92</template>
93
94```
95
96#### @includeWhen
97
98Conditional include:
99
100```html
101
102<template>
103 @includeWhen(user.isAdmin, 'partials/admin-tools')
104 @includeUnless(user.isGuest, 'partials/user-menu')
105</template>
106
107```
108
109#### @includeFirst
110
111Include the first existing partial:
112
113```html
114
115<template>
116 @includeFirst(['custom/header', 'default/header'])
117</template>
118
119```
120
121### Slots
122
123#### @slot / @endslot
124
125```html
126
127<!-- resources/components/Card.stx -->
128<template>
129 <div class="card">
130 <div class="card-header">
131 @slot('header')
132 Default Header
133 @endslot
134 </div>
135
136 <div class="card-body">
137 @slot('default')
138 @endslot
139 </div>
140
141 <div class="card-footer">
142 @slot('footer')
143 @endslot
144 </div>
145 </div>
146</template>
147
148```
149
150Usage:
151
152```html
153
154<template>
155 <Card>
156 <template #header>
157 <h2>Custom Header</h2>
158 </template>
159
160 <p>This is the card content.</p>
161
162 <template #footer>
163 <button>Action</button>
164 </template>
165 </Card>
166</template>
167
168```
169
170### Stack and Push
171
172Collect content from child views:
173
174```html
175
176<!-- Layout -->
177<template>
178 <html>
179 <head>
180 <title>{{ title }}</title>
181 @stack('styles')
182 </head>
183 <body>
184 {{ content }}
185 @stack('scripts')
186 </body>
187 </html>
188</template>
189
190<!-- Child View -->
191<template>
192 @push('styles')
193 <link rel="stylesheet" href="/custom.css">
194 @endpush
195
196 <div>Content here</div>
197
198 @push('scripts')
199 <script src="/custom.js"></script>
200 @endpush
201</template>
202
203```
204
205### Raw Output
206
207#### @verbatim
208
209Prevent STX from processing content:
210
211```html
212
213<template>
214 @verbatim
215 <div>
216 {{ This will not be processed }}
217 @if(this.wont.work)
218 </div>
219 @endverbatim
220</template>
221
222```
223
224### Comments
225
226```html
227
228<template>
229 {{-- This comment will not appear in the rendered HTML --}}
230
231 <!-- This HTML comment will appear in output -->
232</template>
233
234```
235
236## Component Usage
237
238### Importing Components
239
240```html
241
242<template>
243 <div>
244 <Header />
245 <Sidebar :collapsed="sidebarCollapsed" />
246 <MainContent>
247 <slot />
248 </MainContent>
249 <Footer />
250 </div>
251</template>
252
253<script lang="ts">
254import Header from '@/components/Header.stx'
255import Sidebar from '@/components/Sidebar.stx'
256import MainContent from '@/components/MainContent.stx'
257import Footer from '@/components/Footer.stx'
258
259const sidebarCollapsed = ref(false)
260</script>
261
262```
263
264### Passing Props
265
266```html
267
268<!-- Parent -->
269<template>
270 <UserCard
271 :user="currentUser"
272 :show-avatar="true"
273 size="large"
274 @click="handleClick"
275 />
276</template>
277
278<!-- UserCard.stx -->
279<template>
280 <div class="user-card" :class="sizeClass">
281 <img v-if="showAvatar" :src="user.avatar" :alt="user.name">
282 <span>{{ user.name }}</span>
283 </div>
284</template>
285
286<script lang="ts">
287interface Props {
288 user: User
289 showAvatar?: boolean
290 size?: 'small' | 'medium' | 'large'
291}
292
293const props = withDefaults(defineProps<Props>(), {
294 showAvatar: true,
295 size: 'medium',
296})
297
298const sizeClass = computed(() => `size-${props.size}`)
299</script>
300
301```
302
303### Component Slots
304
305```html
306
307<!-- Modal.stx -->
308<template>
309 <div class="modal" v-if="isOpen">
310 <div class="modal-header">
311 <slot name="header">
312 <h2>Default Title</h2>
313 </slot>
314 </div>
315
316 <div class="modal-body">
317 <slot />
318 </div>
319
320 <div class="modal-footer">
321 <slot name="footer">
322 <button @click="close">Close</button>
323 </slot>
324 </div>
325 </div>
326</template>
327
328<script lang="ts">
329interface Props {
330 isOpen: boolean
331}
332
333const props = defineProps<Props>()
334const emit = defineEmits<{
335 close: []
336}>()
337
338function close() {
339 emit('close')
340}
341</script>
342
343```
344
345Usage:
346
347```html
348
349<template>
350 <Modal :is-open="showModal" @close="showModal = false">
351 <template #header>
352 <h2>Confirm Action</h2>
353 </template>
354
355 <p>Are you sure you want to proceed?</p>
356
357 <template #footer>
358 <button @click="cancel">Cancel</button>
359 <button @click="confirm">Confirm</button>
360 </template>
361 </Modal>
362</template>
363
364```
365
366### Scoped Slots
367
368Pass data to slot content:
369
370```html
371
372<!-- DataList.stx -->
373<template>
374 <ul>
375 <li v-for="item in items" :key="item.id">
376 <slot :item="item" :index="$index">
377 {{ item.name }}
378 </slot>
379 </li>
380 </ul>
381</template>
382
383<!-- Usage -->
384<template>
385 <DataList :items="users">
386 <template #default="{ item, index }">
387 <span>{{ index + 1 }}. {{ item.name }} ({{ item.email }})</span>
388 </template>
389 </DataList>
390</template>
391
392```
393
394## Scoped Styles
395
396### Basic Scoped Styles
397
398```html
399
400<style scoped>
401/* These styles only apply to this component */
402.container {
403 padding: 1rem;
404}
405
406h1 {
407 color: blue;
408}
409</style>
410
411```
412
413### Deep Selectors
414
415Target child component elements:
416
417```html
418
419<style scoped>
420/* Target elements inside child components */
421:deep(.child-class) {
422 color: red;
423}
424
425/* Alternative syntax */
426.parent :deep(.child-class) {
427 color: red;
428}
429</style>
430
431```
432
433### Slotted Selectors
434
435Style slotted content:
436
437```html
438
439<style scoped>
440:slotted(p) {
441 color: gray;
442}
443</style>
444
445```
446
447### Global Styles
448
449Apply styles globally from a component:
450
451```html
452
453<style>
454/* Global styles */
455body {
456 font-family: sans-serif;
457}
458</style>
459
460<style scoped>
461/* Component-scoped styles */
462.container {
463 max-width: 800px;
464}
465</style>
466
467```
468
469## TypeScript Integration
470
471### Script Setup
472
473```html
474
475<script setup lang="ts">
476import { ref, computed, onMounted } from 'vue'
477import type { User } from '@/types'
478
479// Props
480interface Props {
481 userId: number
482 initialName?: string
483}
484
485const props = withDefaults(defineProps<Props>(), {
486 initialName: 'Guest',
487})
488
489// Emits
490const emit = defineEmits<{
491 update: [name: string]
492 delete: []
493}>()
494
495// Reactive state
496const name = ref(props.initialName)
497const loading = ref(false)
498
499// Computed
500const displayName = computed(() => name.value.toUpperCase())
501
502// Methods
503async function fetchUser() {
504 loading.value = true
505 try {
506 const user = await api.getUser(props.userId)
507 name.value = user.name
508 } finally {
509 loading.value = false
510 }
511}
512
513// Lifecycle
514onMounted(() => {
515 fetchUser()
516})
517
518// Expose for parent access
519defineExpose({
520 refresh: fetchUser,
521})
522</script>
523
524```
525
526### Type-Safe Templates
527
528```html
529
530<template>
531 <div>
532 <!-- TypeScript provides autocomplete and type checking -->
533 <p>{{ user.name }}</p>
534 <p>{{ user.email }}</p>
535
536 <!-- Error if property doesn't exist -->
537 <!-- <p>{{ user.nonExistent }}</p> -->
538 </div>
539</template>
540
541<script setup lang="ts">
542interface User {
543 id: number
544 name: string
545 email: string
546}
547
548const user = ref<User>({
549 id: 1,
550 name: 'John',
551 email: 'john@example.com',
552})
553</script>
554
555```
556
557## Layouts
558
559### Defining a Layout
560
561```html
562
563<!-- resources/layouts/Default.stx -->
564<template>
565 <div class="app">
566 <Header />
567 <nav>
568 <slot name="nav" />
569 </nav>
570
571 <main>
572 <slot />
573 </main>
574
575 <Footer />
576 </div>
577</template>
578
579<script setup lang="ts">
580import Header from '@/components/Header.stx'
581import Footer from '@/components/Footer.stx'
582</script>
583
584```
585
586### Using a Layout
587
588```html
589
590<!-- resources/views/home.stx -->
591<template>
592 <DefaultLayout>
593 <template #nav>
594 <a href="/">Home</a>
595 <a href="/about">About</a>
596 </template>
597
598 <h1>Welcome Home</h1>
599 <p>This is the home page content.</p>
600 </DefaultLayout>
601</template>
602
603<script setup lang="ts">
604import DefaultLayout from '@/layouts/Default.stx'
605</script>
606
607```
608
609## Edge Cases and Gotchas
610
611### Directive Whitespace
612
613Directives are whitespace-sensitive:
614
615```html
616
617<!-- Correct -->
618@if(condition)
619 Content
620@endif
621
622<!-- Incorrect (no space after @if) -->
623@if (condition)
624 Content
625@endif
626
627```
628
629### Escaping Directive Syntax
630
631Use `@@` to escape directive syntax:
632
633```html
634
635<template>
636 <!-- Outputs: @if(condition) -->
637 @@if(condition)
638
639 <!-- Outputs: {{ variable }} -->
640 @{{ variable }}
641</template>
642
643```
644
645### Component Name Casing
646
647Components can be used in PascalCase or kebab-case:
648
649```html
650
651<template>
652 <!-- Both are valid -->
653 <MyComponent />
654 <my-component />
655</template>
656
657```
658
659### Reactive Props
660
661Props are readonly; use computed or local refs for mutations:
662
663```html
664
665<script setup lang="ts">
666const props = defineProps<{ value: string }>()
667
668// Wrong - props are readonly
669// props.value = 'new value'
670
671// Correct - use local ref
672const localValue = ref(props.value)
673watch(() => props.value, (newVal) => {
674 localValue.value = newVal
675})
676</script>
677
678```
679
680### Async Components
681
682Load components lazily:
683
684```html
685
686<script setup lang="ts">
687import { defineAsyncComponent } from 'vue'
688
689const HeavyComponent = defineAsyncComponent(() =>
690 import('@/components/HeavyComponent.stx')
691)
692</script>
693
694<template>
695 <Suspense>
696 <HeavyComponent />
697 <template #fallback>
698 <LoadingSpinner />
699 </template>
700 </Suspense>
701</template>
702
703```
704
705## API Reference
706
707### Directives
708
709| Directive | Description |
710|-----------|-------------|
711| `@if` / `@elseif` / `@else` | Conditional rendering |
712| `@unless` | Negative conditional |
713| `@isset` / `@empty` | Existence checks |
714| `@foreach` / `@for` | Loop iteration |
715| `@forelse` | Loop with empty state |
716| `@while` | While loop |
717| `@include` | Include partial |
718| `@slot` | Define slot content |
719| `@stack` / `@push` | Stack content |
720| `@verbatim` | Raw output |
721
722### Loop Variables
723
724| Variable | Description |
725|----------|-------------|
726| `$loop.index` | Current index (0-based) |
727| `$loop.iteration` | Current iteration (1-based) |
728| `$loop.remaining` | Remaining iterations |
729| `$loop.count` | Total count |
730| `$loop.first` | Is first iteration |
731| `$loop.last` | Is last iteration |
732| `$loop.even` | Is even iteration |
733| `$loop.odd` | Is odd iteration |
734| `$loop.depth` | Nesting depth |
735| `$loop.parent` | Parent loop |
736
737## Related Documentation
738
739- [Components](/basics/components) - Creating STX components
740- [Routing](/basics/routing) - Route to view binding
741- [Actions](/basics/actions) - Passing data to views
742- [UI Configuration](/config/ui) - UI and styling options