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/bootcamp/frontend.mddeleted+0-575
Changes to docs/bootcamp/frontend.md
@@ -1,575 +0,0 @@
1# Build a Frontend
2
3This tutorial will guide you through building a frontend application with Stacks. You will learn how to create components using STX (Stacks Template Syntax), style them with Headwind CSS utilities, manage state, and set up routing.
4
5## Stacks UI Engine
6
7The Stacks UI engine is responsible for rendering the UI of your application. It is designed to be framework-agnostic, meaning that the built results can be used with any JavaScript or TypeScript framework.
8
9The UI engine handles two core responsibilities:
10
111. **Rendering the Application** - Your main web application
122. **Rendering the Documentation** - Your docs site (powered by BunPress/VitePress)
13
14## Creating Components with STX
15
16STX (Stacks Template Syntax) is a simple, HTML-like syntax for building components. Components live in the `resources/components/` directory.
17
18### Basic Component Structure
19
20An STX component consists of three parts: script, template, and optional styles.
21
22```html
23<!-- resources/components/Greeting.stx -->
24<script server>
25// Props - values passed from parent components
26const name = props.name || 'World'
27const showTime = props.showTime || false
28
29// Computed values
30const greeting = `Hello, ${name}!`
31const currentTime = new Date().toLocaleTimeString()
32</script>
33
34<div class="greeting-card">
35 <h1>{{ greeting }}</h1>
36
37 @if(showTime)
38 <p class="time">Current time: {{ currentTime }}</p>
39 @endif
40</div>
41
42<style scoped>
43.greeting-card {
44 padding: 1rem;
45 border-radius: 0.5rem;
46 background: #f8f9fa;
47}
48
49.time {
50 color: #6c757d;
51 font-size: 0.875rem;
52}
53</style>
54```
55
56### Using Props
57
58Props allow you to pass data from parent to child components:
59
60```html
61<!-- resources/components/Button.stx -->
62<script server>
63// Define props with defaults
64const variant = props.variant || 'solid' // 'solid' | 'outline'
65const color = props.color || 'blue' // 'blue' | 'slate' | 'white'
66const href = props.href || ''
67const customClass = props.customClass || ''
68
69// Style mappings
70const baseStyles = 'inline-flex items-center justify-center rounded-full py-2 px-4 text-sm font-semibold'
71
72const variantStyles = {
73 solid: {
74 blue: 'bg-blue-600 text-white hover:bg-blue-500',
75 slate: 'bg-slate-900 text-white hover:bg-slate-700',
76 },
77 outline: {
78 blue: 'ring-1 ring-blue-200 text-blue-700 hover:ring-blue-300',
79 slate: 'ring-1 ring-slate-200 text-slate-700 hover:ring-slate-300',
80 },
81}
82
83function getClassName() {
84 return `${baseStyles} ${variantStyles[variant]?.[color] || ''} ${customClass}`
85}
86</script>
87
88@if(!href)
89 <button class="{⁠{ }} getClassName()">
90 <slot />
91 </button>
92@else
93 <a href="{⁠{ href }}" class="{⁠{ }} getClassName()">
94 <slot />
95 </a>
96@endif
97```
98
99Using the component:
100
101```html
102<!-- In another component or view -->
103<Button variant="solid" color="blue">Click Me</Button>
104<Button variant="outline" color="slate" href="/about">Learn More</Button>
105```
106
107### Using Slots
108
109Slots allow you to pass content into components:
110
111```html
112<!-- resources/components/Card.stx -->
113<script server>
114const title = props.title || ''
115</script>
116
117<div class="p-6 bg-white rounded-lg shadow-md card">
118 @if(title)
119 <h2 class="mb-4 font-bold text-xl">{{ title }}</h2>
120 @endif
121
122 <div class="card-content">
123 <slot />
124 </div>
125
126 @if(slots.footer)
127 <div class="mt-4 pt-4 border-t card-footer">
128 <slot name="footer" />
129 </div>
130 @endif
131</div>
132```
133
134Using named slots:
135
136```html
137<Card title="My Card">
138 <p>This is the main content.</p>
139
140 <template #footer>
141 <Button>Save</Button>
142 </template>
143</Card>
144```
145
146### Conditionals and Loops
147
148STX provides Blade-like directives for control flow:
149
150```html
151<script server>
152const items = props.items || []
153const showEmpty = props.showEmpty || true
154</script>
155
156<ul class="item-list">
157 @if(items.length > 0)
158 @for(item of items)
159 <li class="item">
160 {{ item.name }}
161
162 @if(item.isNew)
163 <span class="badge">New</span>
164 @endif
165 </li>
166 @endfor
167 @elseif(showEmpty)
168 <li class="empty">No items found</li>
169 @endif
170</ul>
171```
172
173## Styling with Headwind
174
175Stacks uses Headwind, a utility-first CSS framework similar to Tailwind CSS. You can use utility classes directly in your templates.
176
177### Common Utility Classes
178
179```html
180<!-- Layout -->
181<div class="flex items-center justify-between">
182 <div class="grid gap-4 grid-cols-3">
183 <!-- Grid items -->
184 </div>
185</div>
186
187<!-- Spacing -->
188<div class="m-2 mb-4 mt-8 p-4 px-6 py-3">
189 <!-- Content with padding and margin -->
190</div>
191
192<!-- Typography -->
193<h1 class="font-bold text-3xl text-gray-900">Title</h1>
194<p class="leading-relaxed text-gray-600 text-sm">Body text</p>
195
196<!-- Colors -->
197<div class="text-white bg-blue-500">
198 <span class="text-blue-200">Colored text</span>
199</div>
200
201<!-- Borders and Shadows -->
202<div class="border border-gray-200 rounded-lg shadow-md">
203 <!-- Content -->
204</div>
205
206<!-- Responsive -->
207<div class="w-full md:w-1/2 lg:w-1/3">
208 <!-- Responsive width -->
209</div>
210
211<!-- Dark Mode -->
212<div class="text-gray-900 dark:text-white bg-white dark:bg-gray-900">
213 <!-- Dark mode support -->
214</div>
215
216<!-- Hover and Focus States -->
217<button class="bg-blue-500 hover:bg-blue-600 focus:ring-2 focus:ring-blue-300">
218 Hover me
219</button>
220```
221
222### Using Icons
223
224Stacks supports icon classes using the `i-` prefix:
225
226```html
227<i class="h-6 w-6 text-gray-500 i-hugeicons-outline-book-open"></i>
228<i class="h-5 w-5 text-red-500 i-hugeicons-outline-heart"></i>
229```
230
231## State Management
232
233### Local Component State
234
235For simple state within a component, use the script section:
236
237```html
238<script server>
239let count = 0
240
241function increment() {
242 count++
243}
244
245function decrement() {
246 count--
247}
248</script>
249
250<div class="counter">
251 <button onclick="decrement()">-</button>
252 <span>{{ count }}</span>
253 <button onclick="increment()">+</button>
254</div>
255```
256
257### Reactive State
258
259For reactive state that updates the UI:
260
261```html
262<script server>
263import { ref, computed } from '@stacksjs/reactivity'
264
265const count = ref(0)
266const doubled = computed(() => count.value * 2)
267
268function increment() {
269 count.value++
270}
271</script>
272
273<div class="counter">
274 <p>Count: {{ count.value }}</p>
275 <p>Doubled: {{ doubled.value }}</p>
276 <button onclick="increment()">Increment</button>
277</div>
278```
279
280### Shared State
281
282For state shared across components, create a store:
283
284```typescript
285// resources/functions/store.ts
286import { reactive } from '@stacksjs/reactivity'
287
288export const store = reactive({
289 user: null,
290 isAuthenticated: false,
291 theme: 'light',
292})
293
294export function setUser(user) {
295 store.user = user
296 store.isAuthenticated = !!user
297}
298
299export function toggleTheme() {
300 store.theme = store.theme === 'light' ? 'dark' : 'light'
301}
302```
303
304Using the store in components:
305
306```html
307<script server>
308import { store, toggleTheme } from '../functions/store'
309</script>
310
311<div class="theme-toggle">
312 <span>Current theme: {{ store.theme }}</span>
313 <button onclick="toggleTheme()">Toggle Theme</button>
314</div>
315```
316
317## Routing
318
319Stacks supports two routing strategies for your frontend:
320
321### File-based Routing (Default)
322
323With file-based routing, your file structure determines your routes. Files in `resources/views/` automatically become routes.
324
325```
326resources/views/
327├── index.stx # /
328├── about.stx # /about
329├── contact.stx # /contact
330├── blog/
331│ ├── index.stx # /blog
332│ └── [slug].stx # /blog/:slug (dynamic route)
333└── dashboard/
334 ├── index.stx # /dashboard
335 └── settings.stx # /dashboard/settings
336```
337
338#### Dynamic Routes
339
340Use square brackets for dynamic segments:
341
342```html
343<!-- resources/views/blog/[slug].stx -->
344<script server>
345const slug = params.slug
346// Fetch blog post using slug
347</script>
348
349<article>
350 <h1>Blog Post: {{ slug }}</h1>
351</article>
352```
353
354### Laravel-like Routing
355
356For more control, use explicit route definitions:
357
358```typescript
359// routes/web.ts
360import { route } from '@stacksjs/router'
361
362route.get('/', 'HomeController@index')
363route.get('/about', 'AboutController@show')
364route.get('/blog/:slug', 'BlogController@show')
365route.get('/dashboard', 'DashboardController@index').middleware('auth')
366```
367
368### Navigation
369
370Use the Link component or standard anchor tags:
371
372```html
373<!-- Using anchor tags with utility classes -->
374<nav class="flex gap-4">
375 <a href="/" class="text-blue-600 hover:underline">Home</a>
376 <a href="/about" class="text-blue-600 hover:underline">About</a>
377 <a href="/contact" class="text-blue-600 hover:underline">Contact</a>
378</nav>
379```
380
381## Layouts
382
383Create reusable layouts for consistent page structure:
384
385```html
386<!-- resources/layouts/Default.stx -->
387<script server>
388const title = props.title || 'My App'
389</script>
390
391<!DOCTYPE html>
392<html lang="en">
393<head>
394 <meta charset="UTF-8">
395 <meta name="viewport" content="width=device-width, initial-scale=1.0">
396 <title>{{ title }}</title>
397</head>
398<body class="min-h-screen bg-gray-50 dark:bg-gray-900">
399 <header class="bg-white dark:bg-gray-800 shadow">
400 <nav class="mx-auto px-4 py-4 max-w-7xl">
401 <Logo />
402 <!-- Navigation items -->
403 </nav>
404 </header>
405
406 <main class="mx-auto px-4 py-8 max-w-7xl">
407 <slot />
408 </main>
409
410 <footer class="py-8 bg-gray-100 dark:bg-gray-800">
411 <div class="mx-auto px-4 max-w-7xl text-center text-gray-600">
412 &copy; 2024 My App. All rights reserved.
413 </div>
414 </footer>
415</body>
416</html>
417```
418
419Using the layout in a view:
420
421```html
422<!-- resources/views/index.stx -->
423<script server>
424layout = 'Default'
425</script>
426
427<div class="space-y-8">
428 <HelloWorld />
429
430 <section>
431 <h2 class="mb-4 font-bold text-2xl">Welcome to My App</h2>
432 <p class="text-gray-600">Build amazing things with Stacks.</p>
433 </section>
434</div>
435```
436
437## Complete Example: Task Manager
438
439Let us build a simple task manager to demonstrate all concepts:
440
441```html
442<!-- resources/components/TaskItem.stx -->
443<script server>
444const task = props.task
445const onToggle = props.onToggle
446const onDelete = props.onDelete
447</script>
448
449<li class="flex gap-3 items-center p-3 bg-white rounded-lg shadow-sm">
450 <input
451 type="checkbox"
452 checked="{⁠{ task.completed }}"
453 onchange="onToggle(task.id)"
454 class="h-5 w-5 border-gray-300 rounded"
455 />
456
457 <span class="flex-1 text-gray-400' : ? 'line-through 'text-gray-900' {⁠{ }} task.completed">
458 {{ task.title }}
459 </span>
460
461 <button
462 onclick="onDelete(task.id)"
463 class="text-red-500 hover:text-red-700"
464 >
465 <i class="h-5 w-5 i-hugeicons-outline-trash"></i>
466 </button>
467</li>
468```
469
470```html
471<!-- resources/components/TaskList.stx -->
472<script server>
473import { ref } from '@stacksjs/reactivity'
474
475const tasks = ref([
476 { id: 1, title: 'Learn Stacks', completed: false },
477 { id: 2, title: 'Build an app', completed: false },
478 { id: 3, title: 'Deploy to production', completed: false },
479])
480
481const newTaskTitle = ref('')
482
483function addTask() {
484 if (newTaskTitle.value.trim()) {
485 tasks.value.push({
486 id: Date.now(),
487 title: newTaskTitle.value,
488 completed: false,
489 })
490 newTaskTitle.value = ''
491 }
492}
493
494function toggleTask(id) {
495 const task = tasks.value.find(t => t.id === id)
496 if (task) {
497 task.completed = !task.completed
498 }
499}
500
501function deleteTask(id) {
502 tasks.value = tasks.value.filter(t => t.id !== id)
503}
504
505const completedCount = computed(() =>
506 tasks.value.filter(t => t.completed).length
507)
508</script>
509
510<div class="mx-auto p-6 max-w-md">
511 <h1 class="mb-6 font-bold text-2xl">Task Manager</h1>
512
513 <!-- Add Task Form -->
514 <div class="flex gap-2 mb-6">
515 <input
516 type="text"
517 value="{⁠{ newTaskTitle.value }}"
518 oninput="newTaskTitle.value = event.target.value"
519 placeholder="Add a new task..."
520 class="flex-1 px-4 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
521 />
522 <Button variant="solid" color="blue" onclick="addTask()">
523 Add
524 </Button>
525 </div>
526
527 <!-- Task List -->
528 <ul class="space-y-2">
529 @for(task of tasks.value)
530 <TaskItem
531 task="{⁠{ task }}"
532 onToggle="{⁠{ toggleTask }}"
533 onDelete="{⁠{ deleteTask }}"
534 />
535 @endfor
536 </ul>
537
538 <!-- Summary -->
539 <p class="mt-4 text-gray-600 text-sm">
540 {{ completedCount.value }} of {{ tasks.value.length }} tasks completed
541 </p>
542</div>
543```
544
545## Configuration
546
547Configure your STX components in `stx.config.ts`:
548
549```typescript
550// stx.config.ts
551export default {
552 // Components directory - for user-defined components
553 componentsDir: 'resources/components',
554
555 // Layouts directory - for layout templates
556 layoutsDir: 'resources/layouts',
557
558 // Partials directory - for partial templates
559 partialsDir: 'resources/partials',
560}
561```
562
563## Next Steps
564
565Now that you know how to build frontends with Stacks, continue to:
566
567- [Build an API](/bootcamp/api) - Create backend endpoints for your frontend
568- [Authentication How-To](/bootcamp/how-to/authentication) - Add user authentication
569- [Testing How-To](/bootcamp/how-to/testing) - Write tests for your components
570
571## Related Documentation
572
573- [Components Guide](/basics/components)
574- [Views Guide](/basics/views)
575- [Routing Guide](/basics/routing)