Skip to content

Commit 47df72b

Browse files
LasimLasim
authored
Merge pull request #294 from deploystackio/feat/ui-siteheader
docs: Enhance global settings documentation with SMTP settings detail…
2 parents 8c324ed + 7e62197 commit 47df72b

File tree

3 files changed

+153
-2
lines changed

3 files changed

+153
-2
lines changed

‎development/backend/global-settings.mdx‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -618,14 +618,18 @@ export const smtpSettings: GlobalSettingsModule = {
618618
settings: [
619619
{
620620
key: 'smtp.host',
621+
name: 'SMTP Host',
621622
defaultValue: '',
623+
type: 'string',
622624
description: 'SMTP server hostname (e.g., smtp.gmail.com)',
623625
encrypted: false,
624626
required: true
625627
},
626628
{
627629
key: 'smtp.password',
630+
name: 'SMTP Password',
628631
defaultValue: '',
632+
type: 'string',
629633
description: 'SMTP authentication password',
630634
encrypted: true,
631635
required: true
@@ -635,6 +639,20 @@ export const smtpSettings: GlobalSettingsModule = {
635639
};
636640
```
637641

642+
### Setting Properties
643+
644+
Each setting in the `settings` array requires these properties:
645+
646+
| Property | Type | Required | Description |
647+
|----------|------|----------|-------------|
648+
| `key` | `string` | Yes | Unique identifier using dot notation (e.g., `smtp.host`) |
649+
| `name` | `string` | Yes | Human-readable label for frontend display (e.g., `SMTP Host`) |
650+
| `defaultValue` | `string \| number \| boolean` | Yes | Default value when setting is created |
651+
| `type` | `'string' \| 'number' \| 'boolean'` | Yes | Value type for validation and UI rendering |
652+
| `description` | `string` | Yes | Help text explaining what the setting does |
653+
| `encrypted` | `boolean` | Yes | Whether to encrypt the value in the database |
654+
| `required` | `boolean` | Yes | Whether the setting must have a non-empty value |
655+
638656
### Startup Behavior
639657

640658
When the server starts:
@@ -750,14 +768,18 @@ export const myServiceSettings: GlobalSettingsModule = {
750768
settings: [
751769
{
752770
key: 'my-service.api_key',
771+
name: 'API Key',
753772
defaultValue: '',
773+
type: 'string',
754774
description: 'API key for My Service',
755775
encrypted: true,
756776
required: true
757777
},
758778
{
759779
key: 'my-service.enabled',
760-
defaultValue: 'false',
780+
name: 'Enable Service',
781+
defaultValue: false,
782+
type: 'boolean',
761783
description: 'Enable My Service integration',
762784
encrypted: false,
763785
required: false

‎development/frontend/ui/siteHeader-with-breadcrumbs.mdx‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: SiteHeader with Breadcrumbs
3+
description: Guide for implementing dynamic breadcrumb navigation in the dashboard header.
4+
---
5+
6+
7+
The SiteHeader component displays a sidebar toggle and breadcrumb navigation at the top of each dashboard page. Views set their breadcrumbs using the `useBreadcrumbs` composable.
8+
9+
## Component Locations
10+
11+
```
12+
services/frontend/src/
13+
├─ composables/
14+
 └─ useBreadcrumbs.ts # Shared breadcrumb state management
15+
├─ components/
16+
 ├─ SiteHeader.vue # Header with sidebar trigger + breadcrumbs
17+
 └─ DashboardLayout.vue # Layout wrapper that includes SiteHeader
18+
```
19+
20+
## Composable API
21+
22+
The `useBreadcrumbs` composable manages breadcrumb state across all views.
23+
24+
### BreadcrumbItem Interface
25+
26+
```typescript
27+
interface BreadcrumbItem {
28+
label: string // Display text
29+
href?: string // Optional link - omit for current page
30+
}
31+
```
32+
33+
### Returned Values
34+
35+
| Property | Type | Description |
36+
|----------|------|-------------|
37+
| `breadcrumbs` | `Readonly<Ref<BreadcrumbItem[]>>` | Current breadcrumb items |
38+
| `setBreadcrumbs` | `(items: BreadcrumbItem[]) => void` | Set the breadcrumb trail |
39+
| `clearBreadcrumbs` | `() => void` | Clear all breadcrumbs |
40+
41+
## Usage Patterns
42+
43+
### Static Pages
44+
45+
For pages with fixed titles like Dashboard or Settings:
46+
47+
```vue
48+
<script setup lang="ts">
49+
import { onMounted } from 'vue'
50+
import { useBreadcrumbs } from '@/composables/useBreadcrumbs'
51+
52+
const { setBreadcrumbs } = useBreadcrumbs()
53+
54+
onMounted(() => {
55+
setBreadcrumbs([{ label: 'Dashboard' }])
56+
})
57+
</script>
58+
```
59+
60+
### Detail Pages with Dynamic Data
61+
62+
For pages that load data (team detail, server view), set breadcrumbs twice:
63+
64+
```vue
65+
<script setup lang="ts">
66+
import { onMounted, ref } from 'vue'
67+
import { useRoute } from 'vue-router'
68+
import { useBreadcrumbs } from '@/composables/useBreadcrumbs'
69+
import { TeamService } from '@/services/teamService'
70+
71+
const route = useRoute()
72+
const { setBreadcrumbs } = useBreadcrumbs()
73+
const team = ref(null)
74+
75+
onMounted(async () => {
76+
// Initial loading state
77+
setBreadcrumbs([
78+
{ label: 'Teams', href: '/teams' },
79+
{ label: 'Loading...' }
80+
])
81+
82+
// Fetch and update with actual name
83+
team.value = await TeamService.getTeam(route.params.id)
84+
setBreadcrumbs([
85+
{ label: 'Teams', href: '/teams' },
86+
{ label: team.value.name }
87+
])
88+
})
89+
</script>
90+
```
91+
92+
### Nested Pages
93+
94+
For deeply nested pages, include the full path:
95+
96+
```vue
97+
setBreadcrumbs([
98+
{ label: 'MCP Catalog', href: '/admin/mcp-server-catalog' },
99+
{ label: server.name, href: `/admin/mcp-server-catalog/view/${serverId}` },
100+
{ label: 'Edit' }
101+
])
102+
```
103+
104+
## Header Layout
105+
106+
The SiteHeader renders in this order:
107+
1. **SidebarTrigger** - Toggle button for collapsing/expanding sidebar
108+
2. **Separator** - Vertical divider
109+
3. **Breadcrumbs** - Navigation trail with responsive visibility
110+
111+
On mobile, intermediate breadcrumb items are hidden, showing only the current page.
112+
113+
## View Template
114+
115+
Views no longer pass a `:title` prop to DashboardLayout:
116+
117+
```vue
118+
<template>
119+
<DashboardLayout>
120+
<!-- Page content -->
121+
</DashboardLayout>
122+
</template>
123+
```
124+
125+
## Related Documentation
126+
127+
- [UI Design System](/development/frontend/ui/) - Component design patterns
128+
- [Frontend Architecture](/development/frontend/architecture) - View and composable guidelines

‎docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,8 @@
9999
"/development/frontend/ui/design-system-pagination",
100100
"/development/frontend/ui/design-system-structured-data",
101101
"/development/frontend/ui/design-system-table",
102-
"/development/frontend/ui/custom-ui-components"
102+
"/development/frontend/ui/custom-ui-components",
103+
"/development/frontend/ui/siteHeader-with-breadcrumbs"
103104
]
104105
}
105106
]

0 commit comments

Comments
 (0)