ReviewOS

also looking at this

loghqorg/loghq

Add BunPress guide and pre-E2E quality gates

#4
Merged glennmichael123 wants to merge docs/bunpress-product-guide into main
246 files +1744 -64381
docs/basics/components.mddeleted+0-614
Changes to docs/basics/components.md
@@ -1,614 +0,0 @@
1# Components
2
3Stacks provides a powerful component system for building reusable UI elements. Components in Stacks use a Vue-like syntax with TypeScript support, compiled through the Stacks templating engine.
4
5## Overview
6
7The component system helps you:
8
9- **Build reusable UI** - Create modular, composable interfaces
10- **Maintain consistency** - Shared components ensure UI uniformity
11- **Type-safe props** - Full TypeScript support for component APIs
12- **Scoped styles** - CSS isolated to components
13
14## Quick Start
15
16### Creating a Component
17
18Components live in `resources/components/`:
19
20```html
21<!-- resources/components/Button.stx -->
22<script setup lang="ts">
23interface Props {
24 variant?: 'primary' | 'secondary' | 'danger'
25 size?: 'sm' | 'md' | 'lg'
26 disabled?: boolean
27}
28
29const props = withDefaults(defineProps<Props>(), {
30 variant: 'primary',
31 size: 'md',
32 disabled: false,
33})
34
35const emit = defineEmits<{
36 click: [event: MouseEvent]
37}>()
38</script>
39
40<template>
41 <button
42 :class="['btn', `btn-${props.variant}`, `btn-${props.size}`]"
43 :disabled="props.disabled"
44 @click="emit('click', $event)"
45 >
46 <slot />
47 </button>
48</template>
49
50<style scoped>
51.btn {
52 border-radius: 0.375rem;
53 font-weight: 500;
54 cursor: pointer;
55 transition: all 0.15s ease;
56}
57
58.btn-primary {
59 background: #3b82f6;
60 color: white;
61}
62
63.btn-secondary {
64 background: #6b7280;
65 color: white;
66}
67
68.btn-danger {
69 background: #ef4444;
70 color: white;
71}
72
73.btn-sm { padding: 0.25rem 0.5rem; font-size: 0.875rem; }
74.btn-md { padding: 0.5rem 1rem; font-size: 1rem; }
75.btn-lg { padding: 0.75rem 1.5rem; font-size: 1.125rem; }
76
77.btn:disabled {
78 opacity: 0.5;
79 cursor: not-allowed;
80}
81</style>
82```
83
84### Using Components
85
86```html
87<!-- resources/views/pages/index.stx -->
88<template>
89 <div class="container">
90 <Button variant="primary" @click="handleClick">
91 Click Me
92 </Button>
93
94 <Button variant="secondary" size="sm">
95 Small Button
96 </Button>
97
98 <Button variant="danger" :disabled="isLoading">
99 Delete
100 </Button>
101 </div>
102</template>
103
104<script setup lang="ts">
105import { ref } from 'vue'
106
107const isLoading = ref(false)
108
109function handleClick(event: MouseEvent) {
110 console.log('Button clicked!', event)
111}
112</script>
113```
114
115## Component Props
116
117### Defining Props
118
119```html
120<script setup lang="ts">
121// Simple props
122const props = defineProps<{
123 title: string
124 count: number
125 active: boolean
126}>()
127
128// With defaults
129interface Props {
130 title: string
131 count?: number
132 active?: boolean
133}
134
135const props = withDefaults(defineProps<Props>(), {
136 count: 0,
137 active: false,
138})
139</script>
140```
141
142### Complex Props
143
144```html
145<script setup lang="ts">
146interface User {
147 id: number
148 name: string
149 email: string
150 avatar?: string
151}
152
153interface Props {
154 user: User
155 permissions: string[]
156 config: Record<string, unknown>
157}
158
159const props = defineProps<Props>()
160</script>
161
162<template>
163 <div class="user-card">
164 <img :src="props.user.avatar ?? '/default-avatar.png'" />
165 <h3>{{ props.user.name }}</h3>
166 <p>{{ props.user.email }}</p>
167 </div>
168</template>
169```
170
171### Prop Validation
172
173```html
174<script setup lang="ts">
175const props = defineProps({
176 // Required string
177 title: {
178 type: String,
179 required: true,
180 },
181 // Number with default
182 count: {
183 type: Number,
184 default: 0,
185 },
186 // Enum-like validation
187 status: {
188 type: String,
189 validator: (value: string) => {
190 return ['pending', 'active', 'completed'].includes(value)
191 },
192 },
193})
194</script>
195```
196
197## Component Events
198
199### Emitting Events
200
201```html
202<script setup lang="ts">
203// Define emitted events with types
204const emit = defineEmits<{
205 'update:modelValue': [value: string]
206 'submit': [data: FormData]
207 'cancel': []
208}>()
209
210function handleSubmit() {
211 const formData = new FormData()
212 emit('submit', formData)
213}
214
215function handleCancel() {
216 emit('cancel')
217}
218</script>
219
220<template>
221 <form @submit.prevent="handleSubmit">
222 <input
223 :value="modelValue"
224 @input="emit('update:modelValue', ($event.target as HTMLInputElement).value)"
225 />
226 <button type="submit">Submit</button>
227 <button type="button" @click="handleCancel">Cancel</button>
228 </form>
229</template>
230```
231
232### v-model Support
233
234```html
235<!-- Input.stx -->
236<script setup lang="ts">
237const props = defineProps<{
238 modelValue: string
239 placeholder?: string
240}>()
241
242const emit = defineEmits<{
243 'update:modelValue': [value: string]
244}>()
245</script>
246
247<template>
248 <input
249 :value="props.modelValue"
250 :placeholder="props.placeholder"
251 @input="emit('update:modelValue', ($event.target as HTMLInputElement).value)"
252 />
253</template>
254
255<!-- Usage -->
256<template>
257 <Input v-model="searchQuery" placeholder="Search..." />
258</template>
259```
260
261## Slots
262
263### Default Slot
264
265```html
266<!-- Card.stx -->
267<template>
268 <div class="card">
269 <slot />
270 </div>
271</template>
272
273<!-- Usage -->
274<Card>
275 <h2>Card Title</h2>
276 <p>Card content goes here.</p>
277</Card>
278```
279
280### Named Slots
281
282```html
283<!-- Modal.stx -->
284<template>
285 <div class="modal">
286 <header class="modal-header">
287 <slot name="header">
288 Default Header
289 </slot>
290 </header>
291
292 <main class="modal-body">
293 <slot />
294 </main>
295
296 <footer class="modal-footer">
297 <slot name="footer">
298 <button @click="$emit('close')">Close</button>
299 </slot>
300 </footer>
301 </div>
302</template>
303
304<!-- Usage -->
305<Modal @close="handleClose">
306 <template #header>
307 <h2>Custom Header</h2>
308 </template>
309
310 <p>Modal content here.</p>
311
312 <template #footer>
313 <Button @click="save">Save</Button>
314 <Button variant="secondary" @click="cancel">Cancel</Button>
315 </template>
316</Modal>
317```
318
319### Scoped Slots
320
321```html
322<!-- DataList.stx -->
323<script setup lang="ts">
324interface Props {
325 items: any[]
326}
327
328const props = defineProps<Props>()
329</script>
330
331<template>
332 <ul class="data-list">
333 <li v-for="(item, index) in props.items" :key="index">
334 <slot :item="item" :index="index">
335 {{ item }}
336 </slot>
337 </li>
338 </ul>
339</template>
340
341<!-- Usage -->
342<DataList :items="users">
343 <template #default="{ item: user, index }">
344 <span>{{ index + 1 }}. {{ user.name }} ({{ user.email }})</span>
345 </template>
346</DataList>
347```
348
349## Composition
350
351### Using Composables
352
353```html
354<script setup lang="ts">
355import { useAuth } from '@/composables/useAuth'
356import { useFetch } from '@/composables/useFetch'
357
358const { user, isAuthenticated, logout } = useAuth()
359const { data: posts, loading, error, refresh } = useFetch('/api/posts')
360</script>
361
362<template>
363 <div v-if="isAuthenticated">
364 <p>Welcome, {{ user.name }}</p>
365 <button @click="logout">Logout</button>
366
367 <div v-if="loading">Loading posts...</div>
368 <div v-else-if="error">Error: {{ error.message }}</div>
369 <ul v-else>
370 <li v-for="post in posts" :key="post.id">
371 {{ post.title }}
372 </li>
373 </ul>
374 </div>
375</template>
376```
377
378### Creating Composables
379
380```typescript
381// composables/useCounter.ts
382import { computed, ref } from 'vue'
383
384export function useCounter(initial = 0) {
385 const count = ref(initial)
386
387 const doubled = computed(() => count.value * 2)
388
389 function increment() {
390 count.value++
391 }
392
393 function decrement() {
394 count.value--
395 }
396
397 function reset() {
398 count.value = initial
399 }
400
401 return {
402 count,
403 doubled,
404 increment,
405 decrement,
406 reset,
407 }
408}
409```
410
411## Component Patterns
412
413### Container/Presenter Pattern
414
415```html
416<!-- UserListContainer.stx (Smart Component) -->
417<script setup lang="ts">
418import { onMounted, ref } from 'vue'
419import UserList from './UserList.stx'
420
421const users = ref([])
422const loading = ref(true)
423
424onMounted(async () => {
425 users.value = await fetchUsers()
426 loading.value = false
427})
428</script>
429
430<template>
431 <UserList :users="users" :loading="loading" />
432</template>
433
434<!-- UserList.stx (Presentational Component) -->
435<script setup lang="ts">
436interface User {
437 id: number
438 name: string
439}
440
441defineProps<{
442 users: User[]
443 loading: boolean
444}>()
445</script>
446
447<template>
448 <div v-if="loading">Loading...</div>
449 <ul v-else>
450 <li v-for="user in users" :key="user.id">
451 {{ user.name }}
452 </li>
453 </ul>
454</template>
455```
456
457### Compound Components
458
459```html
460<!-- Tabs.stx -->
461<script setup lang="ts">
462import { provide, ref } from 'vue'
463
464const activeTab = ref(0)
465
466provide('tabs', {
467 activeTab,
468 setActiveTab: (index: number) => {
469 activeTab.value = index
470 },
471})
472</script>
473
474<template>
475 <div class="tabs">
476 <slot />
477 </div>
478</template>
479
480<!-- TabList.stx -->
481<template>
482 <div class="tab-list" role="tablist">
483 <slot />
484 </div>
485</template>
486
487<!-- Tab.stx -->
488<script setup lang="ts">
489import { inject } from 'vue'
490
491const props = defineProps<{ index: number }>()
492const { activeTab, setActiveTab } = inject('tabs')
493</script>
494
495<template>
496 <button
497 :class="['tab', { active: activeTab === props.index }]"
498 @click="setActiveTab(props.index)"
499 >
500 <slot />
501 </button>
502</template>
503
504<!-- TabPanels.stx -->
505<script setup lang="ts">
506import { inject } from 'vue'
507const { activeTab } = inject('tabs')
508</script>
509
510<template>
511 <div class="tab-panels">
512 <slot :activeTab="activeTab" />
513 </div>
514</template>
515
516<!-- Usage -->
517<Tabs>
518 <TabList>
519 <Tab :index="0">Profile</Tab>
520 <Tab :index="1">Settings</Tab>
521 <Tab :index="2">Notifications</Tab>
522 </TabList>
523
524 <TabPanels v-slot="{ activeTab }">
525 <div v-show="activeTab === 0">Profile content</div>
526 <div v-show="activeTab === 1">Settings content</div>
527 <div v-show="activeTab === 2">Notifications content</div>
528 </TabPanels>
529</Tabs>
530```
531
532## Styling Components
533
534### Scoped Styles
535
536```html
537<template>
538 <div class="card">
539 <h2 class="title">{{ title }}</h2>
540 </div>
541</template>
542
543<style scoped>
544/* Only applies to this component */
545.card {
546 padding: 1rem;
547 border-radius: 0.5rem;
548 box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
549}
550
551.title {
552 font-size: 1.25rem;
553 margin-bottom: 0.5rem;
554}
555</style>
556```
557
558### CSS Variables
559
560```html
561<style scoped>
562.btn {
563 --btn-bg: var(--color-primary, #3b82f6);
564 --btn-color: var(--color-white, #ffffff);
565
566 background: var(--btn-bg);
567 color: var(--btn-color);
568}
569
570.btn-secondary {
571 --btn-bg: var(--color-gray-500, #6b7280);
572}
573</style>
574```
575
576### Dynamic Classes
577
578```html
579<template>
580 <div
581 :class="[
582 'alert',
583 `alert-${type}`,
584 { 'alert-dismissible': dismissible }
585 ]"
586 >
587 <slot />
588 </div>
589</template>
590```
591
592## Best Practices
593
594### DO
595
596- **Keep components focused** - One responsibility per component
597- **Use TypeScript** - Type props and emits for safety
598- **Document props** - Use JSDoc comments for complex props
599- **Use slots wisely** - Provide flexibility without complexity
600- **Scope styles** - Prevent CSS leaks
601
602### DON'T
603
604- **Don't mutate props** - Use events to communicate changes
605- **Don't over-abstract** - Start simple, extract when needed
606- **Don't deeply nest** - Flatten component hierarchies
607- **Don't use `any`** - Proper types catch bugs early
608
609## Related Documentation
610
611- **[Views](/basics/views)** - Page templates
612- **[Functions](/basics/functions)** - Server-side logic
613- **[Styling](/guide/styling)** - CSS and styling guide
614- **[State Management](/guide/state)** - Managing component state