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/how-to/extend-dashboard.mddeleted+0-657
Changes to docs/bootcamp/how-to/extend-dashboard.md
@@ -1,657 +0,0 @@
1# Extend Dashboard
2
3This guide covers customizing and extending the Stacks dashboard with custom widgets, pages, themes, and plugins.
4
5## Getting Started
6
7The Stacks dashboard provides a flexible system for building custom admin interfaces and management tools.
8
9```ts
10import { Dashboard } from '@stacksjs/dashboard'
11```
12
13## Custom Widgets
14
15### Creating a Widget
16
17```ts
18// resources/dashboard/widgets/StatsWidget.ts
19import { Widget } from '@stacksjs/dashboard'
20
21export default new Widget({
22 name: 'StatsWidget',
23 title: 'Application Statistics',
24 description: 'Displays key application metrics',
25 size: 'medium', // 'small' | 'medium' | 'large' | 'full'
26 refreshInterval: 60000, // Refresh every minute
27
28 async data() {
29 const [users, orders, revenue] = await Promise.all([
30 User.count(),
31 Order.where('status', '=', 'completed').count(),
32 Order.where('status', '=', 'completed').sum('total'),
33 ])
34
35 return {
36 users,
37 orders,
38 revenue: revenue / 100, // Convert cents to dollars
39 }
40 },
41
42 template: `
43 <div class="grid gap-4 grid-cols-3">
44 <div class="stat-card">
45 <div class="stat-value">{{ users }}</div>
46 <div class="stat-label">Total Users</div>
47 </div>
48 <div class="stat-card">
49 <div class="stat-value">{{ orders }}</div>
50 <div class="stat-label">Completed Orders</div>
51 </div>
52 <div class="stat-card">
53 <div class="stat-value">\${{ revenue.toLocaleString() }}</div>
54 <div class="stat-label">Total Revenue</div>
55 </div>
56 </div>
57 `,
58})
59```
60
61### Chart Widget
62
63```ts
64// resources/dashboard/widgets/RevenueChartWidget.ts
65import { Widget } from '@stacksjs/dashboard'
66
67export default new Widget({
68 name: 'RevenueChartWidget',
69 title: 'Revenue Over Time',
70 size: 'large',
71 refreshInterval: 300000, // 5 minutes
72
73 async data() {
74 const thirtyDaysAgo = new Date()
75 thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30)
76
77 const revenue = await db
78 .selectFrom('orders')
79 .select([
80 sql`DATE(created_at)`.as('date'),
81 sql`SUM(total)`.as('total'),
82 ])
83 .where('created_at', '>=', thirtyDaysAgo)
84 .where('status', '=', 'completed')
85 .groupBy(sql`DATE(created_at)`)
86 .orderBy('date')
87 .execute()
88
89 return {
90 labels: revenue.map(r => r.date),
91 values: revenue.map(r => r.total / 100),
92 }
93 },
94
95 template: `
96 <div class="chart-container">
97 <canvas id="revenue-chart"></canvas>
98 </div>
99 `,
100
101 mounted() {
102 new Chart(document.getElementById('revenue-chart'), {
103 type: 'line',
104 data: {
105 labels: this.data.labels,
106 datasets: [{
107 label: 'Revenue',
108 data: this.data.values,
109 borderColor: '#4F46E5',
110 backgroundColor: 'rgba(79, 70, 229, 0.1)',
111 fill: true,
112 }],
113 },
114 options: {
115 responsive: true,
116 maintainAspectRatio: false,
117 },
118 })
119 },
120})
121```
122
123### Activity Feed Widget
124
125```ts
126// resources/dashboard/widgets/ActivityFeedWidget.ts
127import { Widget } from '@stacksjs/dashboard'
128
129export default new Widget({
130 name: 'ActivityFeedWidget',
131 title: 'Recent Activity',
132 size: 'medium',
133 refreshInterval: 30000,
134
135 async data() {
136 const activities = await Activity
137 .with(['user'])
138 .orderBy('created_at', 'desc')
139 .limit(10)
140 .get()
141
142 return { activities }
143 },
144
145 template: `
146 <div class="activity-feed">
147 <div v-for="activity in activities" :key="activity.id" class="activity-item">
148 <div class="activity-icon" :class="activity.type">
149 <icon :name="getIcon(activity.type)" />
150 </div>
151 <div class="activity-content">
152 <p class="activity-message">{{ activity.message }}</p>
153 <p class="activity-meta">
154 <span class="user">{{ activity.user?.name }}</span>
155 <span class="time">{{ formatTime(activity.created_at) }}</span>
156 </p>
157 </div>
158 </div>
159 </div>
160 `,
161
162 methods: {
163 getIcon(type: string) {
164 const icons: Record<string, string> = {
165 'user.created': 'user-plus',
166 'order.completed': 'shopping-cart',
167 'payment.received': 'credit-card',
168 default: 'activity',
169 }
170 return icons[type] || icons.default
171 },
172
173 formatTime(date: string) {
174 return new Date(date).toLocaleString()
175 },
176 },
177})
178```
179
180## Custom Pages
181
182### Creating a Dashboard Page
183
184```ts
185// resources/dashboard/pages/AnalyticsPage.ts
186import { DashboardPage } from '@stacksjs/dashboard'
187
188export default new DashboardPage({
189 name: 'Analytics',
190 path: '/analytics',
191 icon: 'chart-bar',
192 title: 'Analytics Dashboard',
193
194 // Page-level data
195 async data() {
196 return {
197 metrics: await getAnalyticsMetrics(),
198 }
199 },
200
201 // Widgets to display on this page
202 widgets: [
203 'RevenueChartWidget',
204 'StatsWidget',
205 'ActivityFeedWidget',
206 ],
207
208 template: `
209 <div class="analytics-page">
210 <header class="page-header">
211 <h1>{{ title }}</h1>
212 <div class="actions">
213 <button @click="exportReport">Export Report</button>
214 <date-range-picker v-model="dateRange" />
215 </div>
216 </header>
217
218 <div class="widgets-grid">
219 <widget-container
220 v-for="widget in widgets"
221 :key="widget"
222 :name="widget"
223 />
224 </div>
225 </div>
226 `,
227
228 methods: {
229 async exportReport() {
230 const report = await generateAnalyticsReport(this.dateRange)
231 downloadFile(report, 'analytics-report.pdf')
232 },
233 },
234})
235```
236
237### Custom Settings Page
238
239```ts
240// resources/dashboard/pages/SettingsPage.ts
241import { DashboardPage } from '@stacksjs/dashboard'
242
243export default new DashboardPage({
244 name: 'Settings',
245 path: '/settings',
246 icon: 'cog',
247 title: 'Application Settings',
248
249 async data() {
250 return {
251 settings: await Settings.all(),
252 }
253 },
254
255 template: `
256 <div class="settings-page">
257 <h1>Settings</h1>
258
259 <form @submit.prevent="saveSettings" class="settings-form">
260 <section class="settings-section">
261 <h2>General</h2>
262
263 <div class="form-group">
264 <label>Application Name</label>
265 <input v-model="settings.app_name" type="text" />
266 </div>
267
268 <div class="form-group">
269 <label>Support Email</label>
270 <input v-model="settings.support_email" type="email" />
271 </div>
272
273 <div class="form-group">
274 <label>Timezone</label>
275 <select v-model="settings.timezone">
276 <option v-for="tz in timezones" :value="tz.value">
277 {{ tz.label }}
278 </option>
279 </select>
280 </div>
281 </section>
282
283 <section class="settings-section">
284 <h2>Features</h2>
285
286 <div class="form-group">
287 <label class="toggle">
288 <input type="checkbox" v-model="settings.enable_registration" />
289 <span>Allow User Registration</span>
290 </label>
291 </div>
292
293 <div class="form-group">
294 <label class="toggle">
295 <input type="checkbox" v-model="settings.enable_api" />
296 <span>Enable Public API</span>
297 </label>
298 </div>
299 </section>
300
301 <div class="form-actions">
302 <button type="submit" class="btn-primary">Save Changes</button>
303 </div>
304 </form>
305 </div>
306 `,
307
308 methods: {
309 async saveSettings() {
310 await Settings.update(this.settings)
311 this.notify('Settings saved successfully')
312 },
313 },
314})
315```
316
317## Custom Navigation
318
319### Adding Menu Items
320
321```ts
322// resources/dashboard/navigation.ts
323import { Navigation } from '@stacksjs/dashboard'
324
325export default new Navigation({
326 items: [
327 {
328 label: 'Dashboard',
329 icon: 'home',
330 path: '/',
331 },
332 {
333 label: 'Users',
334 icon: 'users',
335 path: '/users',
336 children: [
337 { label: 'All Users', path: '/users' },
338 { label: 'Roles', path: '/users/roles' },
339 { label: 'Permissions', path: '/users/permissions' },
340 ],
341 },
342 {
343 label: 'Orders',
344 icon: 'shopping-cart',
345 path: '/orders',
346 badge: async () => {
347 const pending = await Order.where('status', '=', 'pending').count()
348 return pending > 0 ? pending.toString() : null
349 },
350 },
351 {
352 label: 'Products',
353 icon: 'box',
354 path: '/products',
355 },
356 {
357 label: 'Analytics',
358 icon: 'chart-bar',
359 path: '/analytics',
360 },
361 {
362 label: 'Settings',
363 icon: 'cog',
364 path: '/settings',
365 position: 'bottom',
366 },
367 ],
368})
369```
370
371### Conditional Navigation
372
373```ts
374export default new Navigation({
375 items: [
376 {
377 label: 'Admin Tools',
378 icon: 'shield',
379 path: '/admin',
380 visible: (user) => user.hasRole('admin'),
381 },
382 {
383 label: 'Developer',
384 icon: 'code',
385 path: '/developer',
386 visible: (user) => user.hasRole('developer'),
387 children: [
388 { label: 'API Tokens', path: '/developer/tokens' },
389 { label: 'Webhooks', path: '/developer/webhooks' },
390 { label: 'Logs', path: '/developer/logs' },
391 ],
392 },
393 ],
394})
395```
396
397## Custom Themes
398
399### Creating a Theme
400
401```ts
402// resources/dashboard/themes/dark.ts
403import { Theme } from '@stacksjs/dashboard'
404
405export default new Theme({
406 name: 'dark',
407 label: 'Dark Mode',
408
409 colors: {
410 primary: '#6366F1',
411 secondary: '#8B5CF6',
412 background: '#1F2937',
413 surface: '#374151',
414 text: '#F9FAFB',
415 textMuted: '#9CA3AF',
416 border: '#4B5563',
417 success: '#10B981',
418 warning: '#F59E0B',
419 error: '#EF4444',
420 },
421
422 typography: {
423 fontFamily: 'Inter, system-ui, sans-serif',
424 fontSize: {
425 xs: '0.75rem',
426 sm: '0.875rem',
427 base: '1rem',
428 lg: '1.125rem',
429 xl: '1.25rem',
430 '2xl': '1.5rem',
431 },
432 },
433
434 spacing: {
435 sidebar: '256px',
436 header: '64px',
437 },
438
439 borderRadius: {
440 sm: '0.25rem',
441 md: '0.375rem',
442 lg: '0.5rem',
443 full: '9999px',
444 },
445})
446```
447
448### Custom CSS
449
450```css
451/_ resources/dashboard/themes/custom.css _/
452:root {
453 --color-primary: #6366F1;
454 --color-primary-hover: #4F46E5;
455 --color-background: #F9FAFB;
456 --color-surface: #FFFFFF;
457 --color-text: #111827;
458 --color-text-muted: #6B7280;
459 --color-border: #E5E7EB;
460}
461
462[data-theme="dark"] {
463 --color-primary: #818CF8;
464 --color-primary-hover: #6366F1;
465 --color-background: #1F2937;
466 --color-surface: #374151;
467 --color-text: #F9FAFB;
468 --color-text-muted: #9CA3AF;
469 --color-border: #4B5563;
470}
471
472.dashboard-sidebar {
473 background: var(--color-surface);
474 border-right: 1px solid var(--color-border);
475}
476
477.dashboard-header {
478 background: var(--color-surface);
479 border-bottom: 1px solid var(--color-border);
480}
481
482.widget-card {
483 background: var(--color-surface);
484 border: 1px solid var(--color-border);
485 border-radius: 0.5rem;
486 box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
487}
488```
489
490## Dashboard Plugins
491
492### Creating a Plugin
493
494```ts
495// resources/dashboard/plugins/notifications.ts
496import { DashboardPlugin } from '@stacksjs/dashboard'
497
498export default new DashboardPlugin({
499 name: 'notifications',
500
501 install(dashboard) {
502 // Add notification system
503 dashboard.notifications = {
504 items: [],
505
506 async fetch() {
507 this.items = await Notification
508 .where('read', '=', false)
509 .orderBy('created_at', 'desc')
510 .limit(20)
511 .get()
512 },
513
514 async markAsRead(id: number) {
515 await Notification.where('id', '=', id).update({ read: true })
516 await this.fetch()
517 },
518
519 async markAllAsRead() {
520 await Notification.where('read', '=', false).update({ read: true })
521 this.items = []
522 },
523 }
524
525 // Add notification bell to header
526 dashboard.addHeaderComponent('NotificationBell', {
527 template: `
528 <div class="notification-bell">
529 <button @click="toggle" class="bell-button">
530 <icon name="bell" />
531 <span v-if="unreadCount" class="badge">{{ unreadCount }}</span>
532 </button>
533
534 <div v-if="open" class="notification-dropdown">
535 <div class="dropdown-header">
536 <h3>Notifications</h3>
537 <button @click="markAllAsRead">Mark all read</button>
538 </div>
539
540 <div class="notification-list">
541 <div
542 v-for="notification in notifications"
543 :key="notification.id"
544 class="notification-item"
545 @click="markAsRead(notification.id)"
546 >
547 <p class="notification-message">{{ notification.message }}</p>
548 <span class="notification-time">
549 {{ formatTime(notification.created_at) }}
550 </span>
551 </div>
552 </div>
553 </div>
554 </div>
555 `,
556
557 data() {
558 return {
559 open: false,
560 }
561 },
562
563 computed: {
564 notifications() {
565 return dashboard.notifications.items
566 },
567 unreadCount() {
568 return this.notifications.length
569 },
570 },
571
572 methods: {
573 toggle() {
574 this.open = !this.open
575 },
576 markAsRead(id: number) {
577 dashboard.notifications.markAsRead(id)
578 },
579 markAllAsRead() {
580 dashboard.notifications.markAllAsRead()
581 },
582 },
583
584 mounted() {
585 dashboard.notifications.fetch()
586 // Poll for new notifications
587 setInterval(() => dashboard.notifications.fetch(), 60000)
588 },
589 })
590 },
591})
592```
593
594### Registering Plugins
595
596```ts
597// config/dashboard.ts
598import notificationsPlugin from '../resources/dashboard/plugins/notifications'
599
600export default {
601 plugins: [
602 notificationsPlugin,
603 ],
604}
605```
606
607## Custom Actions
608
609### Bulk Actions
610
611```ts
612// resources/dashboard/actions/bulk-actions.ts
613import { BulkAction } from '@stacksjs/dashboard'
614
615export const exportUsersAction = new BulkAction({
616 name: 'export',
617 label: 'Export Selected',
618 icon: 'download',
619
620 async execute(selectedIds: number[]) {
621 const users = await User.whereIn('id', selectedIds).get()
622 const csv = generateCSV(users)
623 downloadFile(csv, 'users-export.csv')
624 },
625})
626
627export const deleteUsersAction = new BulkAction({
628 name: 'delete',
629 label: 'Delete Selected',
630 icon: 'trash',
631 confirmMessage: 'Are you sure you want to delete the selected users?',
632 variant: 'danger',
633
634 async execute(selectedIds: number[]) {
635 await User.whereIn('id', selectedIds).delete()
636 return { message: `Deleted ${selectedIds.length} users` }
637 },
638})
639```
640
641## Error Handling
642
643```ts
644try {
645 const widget = await Dashboard.loadWidget('CustomWidget')
646} catch (error) {
647 if (error instanceof WidgetNotFoundError) {
648 console.error('Widget not found:', error.widgetName)
649 } else if (error instanceof WidgetDataError) {
650 console.error('Failed to load widget data:', error.message)
651 } else {
652 console.error('Unknown dashboard error:', error)
653 }
654}
655```
656
657This documentation covers extending the Stacks dashboard with custom widgets, pages, themes, and plugins. Each example is designed for building powerful admin interfaces.