also looking at this
Add BunPress guide and pre-E2E quality gates
#4
246 files
+1744
-64381
| @@ -1,614 +0,0 @@ | ||
| 1 | # Components | |
| 2 | ||
| 3 | Stacks 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 | ||
| 7 | The 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 | ||
| 18 | Components live in `resources/components/`: | |
| 19 | ||
| 20 | ```html | |
| 21 | <!-- resources/components/Button.stx --> | |
| 22 | <script setup lang="ts"> | |
| 23 | interface Props { | |
| 24 | variant?: 'primary' | 'secondary' | 'danger' | |
| 25 | size?: 'sm' | 'md' | 'lg' | |
| 26 | disabled?: boolean | |
| 27 | } | |
| 28 | ||
| 29 | const props = withDefaults(defineProps<Props>(), { | |
| 30 | variant: 'primary', | |
| 31 | size: 'md', | |
| 32 | disabled: false, | |
| 33 | }) | |
| 34 | ||
| 35 | const 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"> | |
| 105 | import { ref } from 'vue' | |
| 106 | ||
| 107 | const isLoading = ref(false) | |
| 108 | ||
| 109 | function 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 | |
| 122 | const props = defineProps<{ | |
| 123 | title: string | |
| 124 | count: number | |
| 125 | active: boolean | |
| 126 | }>() | |
| 127 | ||
| 128 | // With defaults | |
| 129 | interface Props { | |
| 130 | title: string | |
| 131 | count?: number | |
| 132 | active?: boolean | |
| 133 | } | |
| 134 | ||
| 135 | const 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"> | |
| 146 | interface User { | |
| 147 | id: number | |
| 148 | name: string | |
| 149 | email: string | |
| 150 | avatar?: string | |
| 151 | } | |
| 152 | ||
| 153 | interface Props { | |
| 154 | user: User | |
| 155 | permissions: string[] | |
| 156 | config: Record<string, unknown> | |
| 157 | } | |
| 158 | ||
| 159 | const 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"> | |
| 175 | const 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 | |
| 204 | const emit = defineEmits<{ | |
| 205 | 'update:modelValue': [value: string] | |
| 206 | 'submit': [data: FormData] | |
| 207 | 'cancel': [] | |
| 208 | }>() | |
| 209 | ||
| 210 | function handleSubmit() { | |
| 211 | const formData = new FormData() | |
| 212 | emit('submit', formData) | |
| 213 | } | |
| 214 | ||
| 215 | function 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"> | |
| 237 | const props = defineProps<{ | |
| 238 | modelValue: string | |
| 239 | placeholder?: string | |
| 240 | }>() | |
| 241 | ||
| 242 | const 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"> | |
| 324 | interface Props { | |
| 325 | items: any[] | |
| 326 | } | |
| 327 | ||
| 328 | const 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"> | |
| 355 | import { useAuth } from '@/composables/useAuth' | |
| 356 | import { useFetch } from '@/composables/useFetch' | |
| 357 | ||
| 358 | const { user, isAuthenticated, logout } = useAuth() | |
| 359 | const { 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 | |
| 382 | import { computed, ref } from 'vue' | |
| 383 | ||
| 384 | export 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"> | |
| 418 | import { onMounted, ref } from 'vue' | |
| 419 | import UserList from './UserList.stx' | |
| 420 | ||
| 421 | const users = ref([]) | |
| 422 | const loading = ref(true) | |
| 423 | ||
| 424 | onMounted(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"> | |
| 436 | interface User { | |
| 437 | id: number | |
| 438 | name: string | |
| 439 | } | |
| 440 | ||
| 441 | defineProps<{ | |
| 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"> | |
| 462 | import { provide, ref } from 'vue' | |
| 463 | ||
| 464 | const activeTab = ref(0) | |
| 465 | ||
| 466 | provide('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"> | |
| 489 | import { inject } from 'vue' | |
| 490 | ||
| 491 | const props = defineProps<{ index: number }>() | |
| 492 | const { 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"> | |
| 506 | import { inject } from 'vue' | |
| 507 | const { 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 | |