@maz-ui/mcp 5.0.0-beta.6 → 5.0.0-beta.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/mcp.mjs +1 -1
- package/docs/generated-docs/maz-circular-progress-bar.doc.md +1 -1
- package/docs/generated-docs/maz-code-highlight.doc.md +11 -0
- package/docs/generated-docs/maz-drawer.doc.md +1 -1
- package/docs/generated-docs/maz-fullscreen-loader.doc.md +5 -5
- package/docs/generated-docs/maz-gallery.doc.md +15 -15
- package/docs/generated-docs/maz-sidebar-content.doc.md +5 -0
- package/docs/generated-docs/maz-sidebar-footer.doc.md +5 -0
- package/docs/generated-docs/maz-sidebar-group.doc.md +11 -0
- package/docs/generated-docs/maz-sidebar-header.doc.md +5 -0
- package/docs/generated-docs/maz-sidebar-menu-button.doc.md +26 -0
- package/docs/generated-docs/maz-sidebar-menu-item.doc.md +5 -0
- package/docs/generated-docs/maz-sidebar-menu-sub.doc.md +16 -0
- package/docs/generated-docs/maz-sidebar-menu.doc.md +5 -0
- package/docs/generated-docs/maz-sidebar-separator.doc.md +0 -0
- package/docs/generated-docs/maz-sidebar-trigger.doc.md +11 -0
- package/docs/generated-docs/maz-sidebar.doc.md +33 -0
- package/docs/generated-docs/maz-slider.doc.md +1 -1
- package/docs/generated-docs/maz-spinner.doc.md +4 -4
- package/docs/generated-docs/maz-ticker.doc.md +1 -1
- package/docs/generated-docs/maz-window-mockup.doc.md +23 -0
- package/docs/src/blog/v5.md +1 -3
- package/docs/src/components/maz-code-highlight.md +233 -0
- package/docs/src/components/maz-sidebar.md +621 -0
- package/docs/src/components/maz-timeline.md +60 -0
- package/docs/src/components/maz-window-mockup.md +249 -0
- package/docs/src/directives/click-outside.md +7 -14
- package/docs/src/directives/lazy-img.md +4 -4
- package/docs/src/guide/getting-started.md +13 -11
- package/docs/src/guide/maz-ui-provider.md +6 -3
- package/docs/src/guide/migration-v4.md +7 -3
- package/docs/src/guide/migration-v5.md +67 -12
- package/docs/src/guide/nuxt.md +53 -46
- package/docs/src/guide/tailwind.md +4 -0
- package/docs/src/guide/themes.md +127 -69
- package/docs/src/helpers/capitalize.md +2 -3
- package/docs/src/helpers/currency.md +2 -2
- package/docs/src/helpers/date.md +2 -2
- package/docs/src/helpers/number.md +2 -2
- package/docs/src/plugins/wait.md +1 -1
- package/package.json +3 -3
|
@@ -0,0 +1,621 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: MazSidebar
|
|
3
|
+
description: MazSidebar is a composable sidebar system for dashboard, admin, and SaaS applications. It provides a fully accessible, collapsible navigation with multiple display modes.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# {{ $frontmatter.title }}
|
|
7
|
+
|
|
8
|
+
{{ $frontmatter.description }}
|
|
9
|
+
|
|
10
|
+
<!--@include: ./../../.vitepress/mixins/getting-started.md-->
|
|
11
|
+
|
|
12
|
+
::: tip
|
|
13
|
+
`MazSidebar` shares its state with all sub-components via Vue's `provide`/`inject`. No separate Provider component is needed. All sub-components must be descendants of `MazSidebar`.
|
|
14
|
+
:::
|
|
15
|
+
|
|
16
|
+
::: warning Deferred features (v1.1)
|
|
17
|
+
The following features are planned for a future release and are **not yet available**:
|
|
18
|
+
- `localStorage` state persistence
|
|
19
|
+
- `Cmd/Ctrl+B` keyboard shortcut
|
|
20
|
+
- Automatic mobile drawer under a breakpoint
|
|
21
|
+
:::
|
|
22
|
+
|
|
23
|
+
## Sub-components
|
|
24
|
+
|
|
25
|
+
| Component | Role |
|
|
26
|
+
|---|---|
|
|
27
|
+
| `MazSidebar` | Root container — provides state context |
|
|
28
|
+
| `MazSidebarHeader` | Fixed top area |
|
|
29
|
+
| `MazSidebarContent` | Scrollable central area |
|
|
30
|
+
| `MazSidebarFooter` | Fixed bottom area |
|
|
31
|
+
| `MazSidebarGroup` | Item grouping with optional label |
|
|
32
|
+
| `MazSidebarSeparator` | Visual divider (`<hr>`) |
|
|
33
|
+
| `MazSidebarMenu` | `<ul>` wrapper with `role="menu"` |
|
|
34
|
+
| `MazSidebarMenuItem` | `<li>` item wrapper |
|
|
35
|
+
| `MazSidebarMenuButton` | Clickable item (link or button), supports icon, label, badge, tooltip |
|
|
36
|
+
| `MazSidebarMenuSub` | Collapsible sub-menu |
|
|
37
|
+
| `MazSidebarTrigger` | Toggle button (must be a descendant of `MazSidebar`) |
|
|
38
|
+
|
|
39
|
+
## 1. Basic usage
|
|
40
|
+
|
|
41
|
+
<ComponentDemo>
|
|
42
|
+
<div class="maz:border maz:border-divider maz:overflow-hidden maz:rounded-md maz:h-[25rem] maz:flex">
|
|
43
|
+
<MazSidebar v-model:open="basicOpen" class="maz:h-full">
|
|
44
|
+
<MazSidebarHeader>
|
|
45
|
+
<div class="maz:p-4 maz:font-bold">My App</div>
|
|
46
|
+
</MazSidebarHeader>
|
|
47
|
+
<MazSidebarContent>
|
|
48
|
+
<MazSidebarMenu>
|
|
49
|
+
<MazSidebarMenuItem>
|
|
50
|
+
<MazSidebarMenuButton label="Dashboard" :active="true" />
|
|
51
|
+
</MazSidebarMenuItem>
|
|
52
|
+
<MazSidebarMenuItem>
|
|
53
|
+
<MazSidebarMenuButton label="Settings" />
|
|
54
|
+
</MazSidebarMenuItem>
|
|
55
|
+
</MazSidebarMenu>
|
|
56
|
+
</MazSidebarContent>
|
|
57
|
+
<MazSidebarFooter>
|
|
58
|
+
<div class="maz:p-4">Footer</div>
|
|
59
|
+
</MazSidebarFooter>
|
|
60
|
+
</MazSidebar>
|
|
61
|
+
<main class="maz:flex-1 maz:p-4">Main content</main>
|
|
62
|
+
</div>
|
|
63
|
+
|
|
64
|
+
<template #code>
|
|
65
|
+
|
|
66
|
+
```html
|
|
67
|
+
<div class="maz:flex maz:h-screen">
|
|
68
|
+
<MazSidebar v-model:open="isOpen">
|
|
69
|
+
<MazSidebarHeader>
|
|
70
|
+
<div class="maz:p-4 maz:font-bold">My App</div>
|
|
71
|
+
</MazSidebarHeader>
|
|
72
|
+
<MazSidebarContent>
|
|
73
|
+
<MazSidebarMenu>
|
|
74
|
+
<MazSidebarMenuItem>
|
|
75
|
+
<MazSidebarMenuButton label="Dashboard" :active="true" />
|
|
76
|
+
</MazSidebarMenuItem>
|
|
77
|
+
<MazSidebarMenuItem>
|
|
78
|
+
<MazSidebarMenuButton label="Settings" />
|
|
79
|
+
</MazSidebarMenuItem>
|
|
80
|
+
</MazSidebarMenu>
|
|
81
|
+
</MazSidebarContent>
|
|
82
|
+
<MazSidebarFooter>
|
|
83
|
+
<div class="maz:p-4">Footer</div>
|
|
84
|
+
</MazSidebarFooter>
|
|
85
|
+
</MazSidebar>
|
|
86
|
+
<main class="maz:flex-1 maz:p-4">Main content</main>
|
|
87
|
+
</div>
|
|
88
|
+
|
|
89
|
+
<script setup>
|
|
90
|
+
const isOpen = ref(true)
|
|
91
|
+
</script>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
</template>
|
|
95
|
+
</ComponentDemo>
|
|
96
|
+
|
|
97
|
+
## 2. Groups & dividers
|
|
98
|
+
|
|
99
|
+
<ComponentDemo>
|
|
100
|
+
<div class="maz:border maz:border-divider maz:overflow-hidden maz:rounded-md maz:h-[25rem] maz:flex">
|
|
101
|
+
<MazSidebar v-model:open="groupsOpen" class="maz:h-full">
|
|
102
|
+
<MazSidebarContent>
|
|
103
|
+
<MazSidebarGroup label="Navigation">
|
|
104
|
+
<MazSidebarMenu>
|
|
105
|
+
<MazSidebarMenuItem>
|
|
106
|
+
<MazSidebarMenuButton label="Dashboard" :active="true" />
|
|
107
|
+
</MazSidebarMenuItem>
|
|
108
|
+
<MazSidebarMenuItem>
|
|
109
|
+
<MazSidebarMenuButton label="Projects" />
|
|
110
|
+
</MazSidebarMenuItem>
|
|
111
|
+
</MazSidebarMenu>
|
|
112
|
+
</MazSidebarGroup>
|
|
113
|
+
<MazSidebarSeparator />
|
|
114
|
+
<MazSidebarGroup label="Settings">
|
|
115
|
+
<MazSidebarMenu>
|
|
116
|
+
<MazSidebarMenuItem>
|
|
117
|
+
<MazSidebarMenuButton label="Profile" />
|
|
118
|
+
</MazSidebarMenuItem>
|
|
119
|
+
<MazSidebarMenuItem>
|
|
120
|
+
<MazSidebarMenuButton label="Billing" />
|
|
121
|
+
</MazSidebarMenuItem>
|
|
122
|
+
</MazSidebarMenu>
|
|
123
|
+
</MazSidebarGroup>
|
|
124
|
+
</MazSidebarContent>
|
|
125
|
+
</MazSidebar>
|
|
126
|
+
<main class="maz:flex-1 maz:p-4">Main content</main>
|
|
127
|
+
</div>
|
|
128
|
+
|
|
129
|
+
<template #code>
|
|
130
|
+
|
|
131
|
+
```html
|
|
132
|
+
<MazSidebar v-model:open="isOpen">
|
|
133
|
+
<MazSidebarContent>
|
|
134
|
+
<MazSidebarGroup label="Navigation">
|
|
135
|
+
<MazSidebarMenu>
|
|
136
|
+
<MazSidebarMenuItem>
|
|
137
|
+
<MazSidebarMenuButton label="Dashboard" :active="true" />
|
|
138
|
+
</MazSidebarMenuItem>
|
|
139
|
+
<MazSidebarMenuItem>
|
|
140
|
+
<MazSidebarMenuButton label="Projects" />
|
|
141
|
+
</MazSidebarMenuItem>
|
|
142
|
+
</MazSidebarMenu>
|
|
143
|
+
</MazSidebarGroup>
|
|
144
|
+
<MazSidebarSeparator />
|
|
145
|
+
<MazSidebarGroup label="Settings">
|
|
146
|
+
<MazSidebarMenu>
|
|
147
|
+
<MazSidebarMenuItem>
|
|
148
|
+
<MazSidebarMenuButton label="Profile" />
|
|
149
|
+
</MazSidebarMenuItem>
|
|
150
|
+
</MazSidebarMenu>
|
|
151
|
+
</MazSidebarGroup>
|
|
152
|
+
</MazSidebarContent>
|
|
153
|
+
</MazSidebar>
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
</template>
|
|
157
|
+
</ComponentDemo>
|
|
158
|
+
|
|
159
|
+
## 3. Sub-menus
|
|
160
|
+
|
|
161
|
+
<ComponentDemo>
|
|
162
|
+
<div class="maz:border maz:border-divider maz:overflow-hidden maz:rounded-md maz:h-[25rem] maz:flex">
|
|
163
|
+
<MazSidebar v-model:open="submenusOpen" class="maz:h-full">
|
|
164
|
+
<MazSidebarContent>
|
|
165
|
+
<MazSidebarMenu>
|
|
166
|
+
<MazSidebarMenuItem>
|
|
167
|
+
<MazSidebarMenuButton label="Dashboard" :active="true" />
|
|
168
|
+
</MazSidebarMenuItem>
|
|
169
|
+
<MazSidebarMenuItem>
|
|
170
|
+
<MazSidebarMenuSub label="Products" :default-open="true">
|
|
171
|
+
<MazSidebarMenuItem>
|
|
172
|
+
<MazSidebarMenuButton label="All Products" />
|
|
173
|
+
</MazSidebarMenuItem>
|
|
174
|
+
<MazSidebarMenuItem>
|
|
175
|
+
<MazSidebarMenuButton label="Add Product" />
|
|
176
|
+
</MazSidebarMenuItem>
|
|
177
|
+
</MazSidebarMenuSub>
|
|
178
|
+
</MazSidebarMenuItem>
|
|
179
|
+
<MazSidebarMenuItem>
|
|
180
|
+
<MazSidebarMenuSub label="Reports">
|
|
181
|
+
<MazSidebarMenuItem>
|
|
182
|
+
<MazSidebarMenuButton label="Sales" />
|
|
183
|
+
</MazSidebarMenuItem>
|
|
184
|
+
</MazSidebarMenuSub>
|
|
185
|
+
</MazSidebarMenuItem>
|
|
186
|
+
</MazSidebarMenu>
|
|
187
|
+
</MazSidebarContent>
|
|
188
|
+
</MazSidebar>
|
|
189
|
+
<main class="maz:flex-1 maz:p-4">Main content</main>
|
|
190
|
+
</div>
|
|
191
|
+
|
|
192
|
+
<template #code>
|
|
193
|
+
|
|
194
|
+
```html
|
|
195
|
+
<MazSidebar v-model:open="isOpen">
|
|
196
|
+
<MazSidebarContent>
|
|
197
|
+
<MazSidebarMenu>
|
|
198
|
+
<MazSidebarMenuItem>
|
|
199
|
+
<MazSidebarMenuSub label="Products" :default-open="true">
|
|
200
|
+
<MazSidebarMenuItem>
|
|
201
|
+
<MazSidebarMenuButton label="All Products" />
|
|
202
|
+
</MazSidebarMenuItem>
|
|
203
|
+
<MazSidebarMenuItem>
|
|
204
|
+
<MazSidebarMenuButton label="Add Product" />
|
|
205
|
+
</MazSidebarMenuItem>
|
|
206
|
+
</MazSidebarMenuSub>
|
|
207
|
+
</MazSidebarMenuItem>
|
|
208
|
+
</MazSidebarMenu>
|
|
209
|
+
</MazSidebarContent>
|
|
210
|
+
</MazSidebar>
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
</template>
|
|
214
|
+
</ComponentDemo>
|
|
215
|
+
|
|
216
|
+
## 4. Icon mode with tooltips
|
|
217
|
+
|
|
218
|
+
When `collapsible="icon"` and the sidebar is collapsed, labels fade out and only the icons stay visible. To help users identify items in collapsed state, provide a `tooltip` prop on each `MazSidebarMenuButton`: it uses the `v-tooltip` directive and is always shown on hover.
|
|
219
|
+
|
|
220
|
+
<ComponentDemo>
|
|
221
|
+
<div class="maz:border maz:border-divider maz:overflow-hidden maz:rounded-md maz:h-[25rem] maz:flex">
|
|
222
|
+
<MazSidebar v-model:open="iconModeOpen" collapsible="icon" class="maz:h-full">
|
|
223
|
+
<MazSidebarContent>
|
|
224
|
+
<MazSidebarMenu>
|
|
225
|
+
<MazSidebarMenuItem>
|
|
226
|
+
<MazSidebarMenuButton :icon="MazHome" label="Dashboard" tooltip="Go to Dashboard" :active="true" />
|
|
227
|
+
</MazSidebarMenuItem>
|
|
228
|
+
<MazSidebarMenuItem>
|
|
229
|
+
<MazSidebarMenuButton :icon="MazCog6Tooth" label="Settings" tooltip="Open Settings" />
|
|
230
|
+
</MazSidebarMenuItem>
|
|
231
|
+
</MazSidebarMenu>
|
|
232
|
+
</MazSidebarContent>
|
|
233
|
+
<MazSidebarFooter>
|
|
234
|
+
<MazSidebarTrigger />
|
|
235
|
+
</MazSidebarFooter>
|
|
236
|
+
</MazSidebar>
|
|
237
|
+
<main class="maz:flex-1 maz:flex maz:flex-col maz:gap-4 maz:p-4">
|
|
238
|
+
Click the trigger to collapse/expand
|
|
239
|
+
<MazBtn @click="iconModeOpen = !iconModeOpen">Toggle sidebar</MazBtn>
|
|
240
|
+
</main>
|
|
241
|
+
</div>
|
|
242
|
+
|
|
243
|
+
<template #code>
|
|
244
|
+
|
|
245
|
+
```html
|
|
246
|
+
<script setup>
|
|
247
|
+
import { MazHome } from '@maz-ui/icons/lazy/MazHome'
|
|
248
|
+
import { MazCog6Tooth } from '@maz-ui/icons/lazy/MazCog6Tooth'
|
|
249
|
+
|
|
250
|
+
const isOpen = ref(true)
|
|
251
|
+
</script>
|
|
252
|
+
|
|
253
|
+
<template>
|
|
254
|
+
<MazSidebar v-model:open="isOpen" collapsible="icon">
|
|
255
|
+
<MazSidebarContent>
|
|
256
|
+
<MazSidebarMenu>
|
|
257
|
+
<MazSidebarMenuItem>
|
|
258
|
+
<MazSidebarMenuButton :icon="MazHome" label="Dashboard" tooltip="Go to Dashboard" />
|
|
259
|
+
</MazSidebarMenuItem>
|
|
260
|
+
</MazSidebarMenu>
|
|
261
|
+
</MazSidebarContent>
|
|
262
|
+
<MazSidebarFooter>
|
|
263
|
+
<MazSidebarTrigger />
|
|
264
|
+
</MazSidebarFooter>
|
|
265
|
+
</MazSidebar>
|
|
266
|
+
</template>
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
</template>
|
|
270
|
+
</ComponentDemo>
|
|
271
|
+
|
|
272
|
+
## 5. Offcanvas mode
|
|
273
|
+
|
|
274
|
+
<ComponentDemo>
|
|
275
|
+
<div class="maz:border maz:border-divider maz:overflow-hidden maz:rounded-md maz:h-[20rem] maz:flex">
|
|
276
|
+
<MazSidebar v-model:open="offcanvasOpen" collapsible="offcanvas" class="maz:h-full">
|
|
277
|
+
<MazSidebarContent>
|
|
278
|
+
<MazSidebarMenu>
|
|
279
|
+
<MazSidebarMenuItem>
|
|
280
|
+
<MazSidebarMenuButton label="Home" :active="true" />
|
|
281
|
+
</MazSidebarMenuItem>
|
|
282
|
+
<MazSidebarMenuItem>
|
|
283
|
+
<MazSidebarMenuButton label="About" />
|
|
284
|
+
</MazSidebarMenuItem>
|
|
285
|
+
</MazSidebarMenu>
|
|
286
|
+
</MazSidebarContent>
|
|
287
|
+
</MazSidebar>
|
|
288
|
+
<main class="maz:flex-1 maz:flex maz:flex-col maz:gap-4 maz:p-4">
|
|
289
|
+
<MazBtn @click="offcanvasOpen = !offcanvasOpen">Toggle sidebar</MazBtn>
|
|
290
|
+
Main content — sidebar disappears completely when closed
|
|
291
|
+
</main>
|
|
292
|
+
</div>
|
|
293
|
+
|
|
294
|
+
<template #code>
|
|
295
|
+
|
|
296
|
+
```html
|
|
297
|
+
<MazSidebar v-model:open="isOpen" collapsible="offcanvas">
|
|
298
|
+
<!-- content -->
|
|
299
|
+
</MazSidebar>
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
</template>
|
|
303
|
+
</ComponentDemo>
|
|
304
|
+
|
|
305
|
+
## 6. Overlay vs push mode
|
|
306
|
+
|
|
307
|
+
In `mode="push"` (default), the sidebar is part of the document flow and pushes the main content.
|
|
308
|
+
In `mode="overlay"`, the sidebar floats over the content with a backdrop, escape key support and focus trapping.
|
|
309
|
+
|
|
310
|
+
<ComponentDemo>
|
|
311
|
+
<div class="maz:border maz:border-divider maz:overflow-hidden maz:rounded-md maz:h-[20rem] maz:relative">
|
|
312
|
+
<MazBtn class="maz:absolute maz:top-4 maz:left-4 maz:z-1" @click="overlayOpen = !overlayOpen">
|
|
313
|
+
Toggle overlay sidebar
|
|
314
|
+
</MazBtn>
|
|
315
|
+
<MazSidebar v-model:open="overlayOpen" mode="overlay">
|
|
316
|
+
<MazSidebarHeader>
|
|
317
|
+
<div class="maz:p-4 maz:font-bold">Overlay Sidebar</div>
|
|
318
|
+
</MazSidebarHeader>
|
|
319
|
+
<MazSidebarContent>
|
|
320
|
+
<MazSidebarMenu>
|
|
321
|
+
<MazSidebarMenuItem>
|
|
322
|
+
<MazSidebarMenuButton label="Home" :active="true" />
|
|
323
|
+
</MazSidebarMenuItem>
|
|
324
|
+
</MazSidebarMenu>
|
|
325
|
+
</MazSidebarContent>
|
|
326
|
+
<MazSidebarFooter>
|
|
327
|
+
<MazSidebarTrigger />
|
|
328
|
+
</MazSidebarFooter>
|
|
329
|
+
</MazSidebar>
|
|
330
|
+
</div>
|
|
331
|
+
|
|
332
|
+
<template #code>
|
|
333
|
+
|
|
334
|
+
```html
|
|
335
|
+
<!-- Overlay mode: sidebar floats over content -->
|
|
336
|
+
<MazSidebar v-model:open="isOpen" mode="overlay">
|
|
337
|
+
<!-- content -->
|
|
338
|
+
</MazSidebar>
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
</template>
|
|
342
|
+
</ComponentDemo>
|
|
343
|
+
|
|
344
|
+
## 7. Side end (right)
|
|
345
|
+
|
|
346
|
+
<ComponentDemo>
|
|
347
|
+
<div class="maz:border maz:border-divider maz:overflow-hidden maz:rounded-md maz:h-[20rem] maz:flex">
|
|
348
|
+
<main class="maz:flex-1 maz:p-4">Main content</main>
|
|
349
|
+
<MazSidebar v-model:open="sideEndOpen" side="end" class="maz:h-full">
|
|
350
|
+
<MazSidebarContent>
|
|
351
|
+
<MazSidebarMenu>
|
|
352
|
+
<MazSidebarMenuItem>
|
|
353
|
+
<MazSidebarMenuButton label="Right panel item" />
|
|
354
|
+
</MazSidebarMenuItem>
|
|
355
|
+
</MazSidebarMenu>
|
|
356
|
+
</MazSidebarContent>
|
|
357
|
+
</MazSidebar>
|
|
358
|
+
</div>
|
|
359
|
+
|
|
360
|
+
<template #code>
|
|
361
|
+
|
|
362
|
+
```html
|
|
363
|
+
<div class="maz:flex maz:h-screen">
|
|
364
|
+
<main class="maz:flex-1">Main content</main>
|
|
365
|
+
<MazSidebar v-model:open="isOpen" side="end">
|
|
366
|
+
<!-- content -->
|
|
367
|
+
</MazSidebar>
|
|
368
|
+
</div>
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
</template>
|
|
372
|
+
</ComponentDemo>
|
|
373
|
+
|
|
374
|
+
## 8. Badges
|
|
375
|
+
|
|
376
|
+
`badge` accepts a `string`, a `number`, or a full `MazBadgeProps` object (with an optional `text`) to fine-tune color, size, outlined, etc.
|
|
377
|
+
|
|
378
|
+
<ComponentDemo>
|
|
379
|
+
<div class="maz:border maz:border-divider maz:overflow-hidden maz:rounded-md maz:h-[22rem] maz:flex">
|
|
380
|
+
<MazSidebar v-model:open="badgesOpen" class="maz:h-full">
|
|
381
|
+
<MazSidebarContent>
|
|
382
|
+
<MazSidebarMenu>
|
|
383
|
+
<MazSidebarMenuItem>
|
|
384
|
+
<MazSidebarMenuButton label="Inbox" :badge="12" :active="true" />
|
|
385
|
+
</MazSidebarMenuItem>
|
|
386
|
+
<MazSidebarMenuItem>
|
|
387
|
+
<MazSidebarMenuButton label="Errors" :badge="{ text: 3, color: 'destructive' }" />
|
|
388
|
+
</MazSidebarMenuItem>
|
|
389
|
+
<MazSidebarMenuItem>
|
|
390
|
+
<MazSidebarMenuButton label="Beta" :badge="{ text: 'NEW', color: 'success', outlined: true }" />
|
|
391
|
+
</MazSidebarMenuItem>
|
|
392
|
+
<MazSidebarMenuItem>
|
|
393
|
+
<MazSidebarMenuButton label="Settings" />
|
|
394
|
+
</MazSidebarMenuItem>
|
|
395
|
+
</MazSidebarMenu>
|
|
396
|
+
</MazSidebarContent>
|
|
397
|
+
</MazSidebar>
|
|
398
|
+
<main class="maz:flex-1 maz:flex maz:flex-col maz:gap-4 maz:p-4">
|
|
399
|
+
Badges are hidden in icon-collapsed mode.
|
|
400
|
+
<MazBtn @click="badgesOpen = !badgesOpen">Toggle sidebar</MazBtn>
|
|
401
|
+
</main>
|
|
402
|
+
</div>
|
|
403
|
+
|
|
404
|
+
<template #code>
|
|
405
|
+
|
|
406
|
+
```html
|
|
407
|
+
<!-- Simple: pass a string or number -->
|
|
408
|
+
<MazSidebarMenuButton label="Inbox" :badge="12" />
|
|
409
|
+
|
|
410
|
+
<!-- Full customisation: pass a MazBadgeProps object -->
|
|
411
|
+
<MazSidebarMenuButton
|
|
412
|
+
label="Errors"
|
|
413
|
+
:badge="{ text: 3, color: 'destructive' }"
|
|
414
|
+
/>
|
|
415
|
+
<MazSidebarMenuButton
|
|
416
|
+
label="Beta"
|
|
417
|
+
:badge="{ text: 'NEW', color: 'success', outlined: true }"
|
|
418
|
+
/>
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
</template>
|
|
422
|
+
</ComponentDemo>
|
|
423
|
+
|
|
424
|
+
## 9. User menu in footer
|
|
425
|
+
|
|
426
|
+
<ComponentDemo>
|
|
427
|
+
<div class="maz:border maz:border-divider maz:overflow-hidden maz:rounded-md maz:h-[22rem] maz:flex">
|
|
428
|
+
<MazSidebar v-model:open="userMenuOpen" class="maz:h-full">
|
|
429
|
+
<MazSidebarContent>
|
|
430
|
+
<MazSidebarMenu>
|
|
431
|
+
<MazSidebarMenuItem>
|
|
432
|
+
<MazSidebarMenuButton label="Dashboard" :active="true" />
|
|
433
|
+
</MazSidebarMenuItem>
|
|
434
|
+
</MazSidebarMenu>
|
|
435
|
+
</MazSidebarContent>
|
|
436
|
+
<MazSidebarFooter>
|
|
437
|
+
<div class="maz:flex maz:items-center maz:gap-3 maz:p-3">
|
|
438
|
+
<MazAvatar src="https://placedog.net/100/100" size="0.8rem" />
|
|
439
|
+
<div class="maz:flex-1 maz:min-w-0">
|
|
440
|
+
<p class="maz:m-0 maz:text-md maz:font-semibold">Jane Doe</p>
|
|
441
|
+
<p class="maz:m-0 maz:text-xs maz:text-muted">jane@example.com</p>
|
|
442
|
+
</div>
|
|
443
|
+
</div>
|
|
444
|
+
</MazSidebarFooter>
|
|
445
|
+
</MazSidebar>
|
|
446
|
+
<main class="maz:flex-1 maz:p-4">Main content</main>
|
|
447
|
+
</div>
|
|
448
|
+
|
|
449
|
+
<template #code>
|
|
450
|
+
|
|
451
|
+
```html
|
|
452
|
+
<MazSidebar v-model:open="isOpen">
|
|
453
|
+
<MazSidebarContent><!-- ... --></MazSidebarContent>
|
|
454
|
+
<MazSidebarFooter>
|
|
455
|
+
<div class="maz:flex maz:items-center maz:gap-3 maz:p-3">
|
|
456
|
+
<MazAvatar src="..." size="0.8rem" />
|
|
457
|
+
<div class="maz:flex-1 maz:min-w-0">
|
|
458
|
+
<p class="maz:m-0 maz:text-md maz:font-semibold">Jane Doe</p>
|
|
459
|
+
<p class="maz:m-0 maz:text-xs maz:text-muted">jane@example.com</p>
|
|
460
|
+
</div>
|
|
461
|
+
</div>
|
|
462
|
+
</MazSidebarFooter>
|
|
463
|
+
</MazSidebar>
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
</template>
|
|
467
|
+
</ComponentDemo>
|
|
468
|
+
|
|
469
|
+
## 10. Mobile (static rendering)
|
|
470
|
+
|
|
471
|
+
::: info
|
|
472
|
+
Automatic mobile drawer (drawer auto under a breakpoint with backdrop) is a **deferred v1.1 feature**. For now, control the sidebar visibility programmatically based on viewport.
|
|
473
|
+
:::
|
|
474
|
+
|
|
475
|
+
```html
|
|
476
|
+
<script setup>
|
|
477
|
+
import { useWindowSize } from 'maz-ui'
|
|
478
|
+
|
|
479
|
+
const { width } = useWindowSize()
|
|
480
|
+
const isMobile = computed(() => width.value < 768)
|
|
481
|
+
const isOpen = ref(!isMobile.value)
|
|
482
|
+
|
|
483
|
+
watch(isMobile, (mobile) => {
|
|
484
|
+
isOpen.value = !mobile
|
|
485
|
+
})
|
|
486
|
+
</script>
|
|
487
|
+
|
|
488
|
+
<template>
|
|
489
|
+
<div class="maz:flex maz:h-screen">
|
|
490
|
+
<MazSidebar v-model:open="isOpen" :mode="isMobile ? 'overlay' : 'push'">
|
|
491
|
+
<!-- content -->
|
|
492
|
+
</MazSidebar>
|
|
493
|
+
<main class="maz:flex-1">
|
|
494
|
+
<MazSidebarTrigger />
|
|
495
|
+
<!-- page content -->
|
|
496
|
+
</main>
|
|
497
|
+
</div>
|
|
498
|
+
</template>
|
|
499
|
+
```
|
|
500
|
+
|
|
501
|
+
## 11. Programmatic control (v-model + composable)
|
|
502
|
+
|
|
503
|
+
Use `v-model:open` for two-way binding, or `useSidebar()` inside any descendant component.
|
|
504
|
+
|
|
505
|
+
```html
|
|
506
|
+
<script setup>
|
|
507
|
+
import { useSidebar } from 'maz-ui'
|
|
508
|
+
|
|
509
|
+
// Inside a child component that is a descendant of MazSidebar:
|
|
510
|
+
const sidebar = useSidebar()
|
|
511
|
+
|
|
512
|
+
// sidebar.open.value → boolean
|
|
513
|
+
// sidebar.state.value → 'expanded' | 'collapsed'
|
|
514
|
+
// sidebar.toggle() → toggle open state
|
|
515
|
+
// sidebar.setOpen(true/false) → set explicitly
|
|
516
|
+
</script>
|
|
517
|
+
|
|
518
|
+
<template>
|
|
519
|
+
<MazSidebar v-model:open="isOpen">
|
|
520
|
+
<MazSidebarContent>
|
|
521
|
+
<MazSidebarMenu>
|
|
522
|
+
<MazSidebarMenuItem>
|
|
523
|
+
<MazSidebarMenuButton label="Dashboard" />
|
|
524
|
+
</MazSidebarMenuItem>
|
|
525
|
+
</MazSidebarMenu>
|
|
526
|
+
</MazSidebarContent>
|
|
527
|
+
<!-- MazSidebarTrigger uses useSidebar() internally -->
|
|
528
|
+
<MazSidebarTrigger />
|
|
529
|
+
</MazSidebar>
|
|
530
|
+
</template>
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
## 12. With router (vue-router / NuxtLink)
|
|
534
|
+
|
|
535
|
+
`MazSidebarMenuButton` uses `resolveLinkComponent()` internally — it detects `RouterLink` (vue-router) or a provided `NuxtLink`. Pass the `to` prop for router navigation, `href` for plain anchor links.
|
|
536
|
+
|
|
537
|
+
```html
|
|
538
|
+
<!-- With vue-router -->
|
|
539
|
+
<MazSidebarMenuButton :to="{ name: 'home' }" label="Home" />
|
|
540
|
+
<MazSidebarMenuButton to="/about" label="About" />
|
|
541
|
+
|
|
542
|
+
<!-- With plain href -->
|
|
543
|
+
<MazSidebarMenuButton href="https://maz-ui.com" label="Docs" />
|
|
544
|
+
|
|
545
|
+
<!-- Mark as active manually (useful when router is not available) -->
|
|
546
|
+
<MazSidebarMenuButton label="Dashboard" :active="$route.name === 'dashboard'" />
|
|
547
|
+
```
|
|
548
|
+
|
|
549
|
+
## MazSidebar Props
|
|
550
|
+
|
|
551
|
+
| Prop | Type | Default | Description |
|
|
552
|
+
|---|---|---|---|
|
|
553
|
+
| `id` | `string` | auto-generated | Unique identifier for the sidebar |
|
|
554
|
+
| `v-model:open` | `boolean` | `true` | Controls the open/closed state |
|
|
555
|
+
| `side` | `'start' \| 'end'` | `'start'` | Which side the sidebar appears on |
|
|
556
|
+
| `collapsible` | `'offcanvas' \| 'icon' \| 'none'` | `'offcanvas'` | How the sidebar collapses |
|
|
557
|
+
| `mode` | `'push' \| 'overlay'` | `'push'` | Whether content is pushed or overlaid |
|
|
558
|
+
| `width` | `string` | `'16rem'` | Width when expanded |
|
|
559
|
+
| `iconWidth` | `string` | `'3rem'` | Width in icon-collapsed mode |
|
|
560
|
+
|
|
561
|
+
## MazSidebarMenuButton Props
|
|
562
|
+
|
|
563
|
+
| Prop | Type | Default | Description |
|
|
564
|
+
|---|---|---|---|
|
|
565
|
+
| `to` | `string \| object` | — | Router-link target |
|
|
566
|
+
| `href` | `string` | — | Anchor href |
|
|
567
|
+
| `icon` | `MazIconLike` | — | Icon — value or full `MazIconProps` object |
|
|
568
|
+
| `label` | `string` | — | Text label |
|
|
569
|
+
| `badge` | `string \| number \| MazBadgeProps & { text? }` | — | Badge — value or full `MazBadgeProps` object |
|
|
570
|
+
| `tooltip` | `string` | — | Tooltip text — shown on hover via `v-tooltip` |
|
|
571
|
+
| `active` | `boolean` | — | Force active state (`aria-current="page"`) |
|
|
572
|
+
| `disabled` | `boolean` | `false` | Disable the button |
|
|
573
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
|
|
574
|
+
|
|
575
|
+
## MazSidebarMenuSub Props
|
|
576
|
+
|
|
577
|
+
| Prop | Type | Default | Description |
|
|
578
|
+
|---|---|---|---|
|
|
579
|
+
| `label` | `string` | — | Label for the trigger button |
|
|
580
|
+
| `icon` | `MazIconLike` | — | Icon — value or full `MazIconProps` object |
|
|
581
|
+
| `defaultOpen` | `boolean` | `false` | Open the sub-menu by default |
|
|
582
|
+
|
|
583
|
+
## CSS Variables
|
|
584
|
+
|
|
585
|
+
Customize the sidebar width using these CSS custom properties (also settable via `width` / `iconWidth` props):
|
|
586
|
+
|
|
587
|
+
```css
|
|
588
|
+
:root {
|
|
589
|
+
--maz-sidebar-width: 16rem; /* expanded width */
|
|
590
|
+
--maz-sidebar-icon-width: 3rem; /* icon-mode collapsed width */
|
|
591
|
+
}
|
|
592
|
+
```
|
|
593
|
+
|
|
594
|
+
## Accessibility
|
|
595
|
+
|
|
596
|
+
- The sidebar root element renders as `<aside aria-label="Sidebar">`
|
|
597
|
+
- `MazSidebarMenu` renders as `<ul role="menu">`
|
|
598
|
+
- `MazSidebarMenuItem` renders as `<li role="none">`
|
|
599
|
+
- `MazSidebarTrigger` has `aria-expanded` and `aria-controls` referencing the sidebar `id`
|
|
600
|
+
- `MazSidebarMenuButton` applies `aria-current="page"` on active items and exposes the label via `aria-label`
|
|
601
|
+
- `MazSidebarMenuSub` trigger has `aria-expanded` and `aria-controls`
|
|
602
|
+
- In `mode="overlay"`, pressing `Escape` closes the sidebar and focus is restored to the trigger element
|
|
603
|
+
- In `mode="overlay"`, `Tab`/`Shift+Tab` are trapped within the sidebar
|
|
604
|
+
- All transitions respect `prefers-reduced-motion`
|
|
605
|
+
|
|
606
|
+
<script setup>
|
|
607
|
+
import { ref } from 'vue'
|
|
608
|
+
|
|
609
|
+
import { MazHome } from '@maz-ui/icons/lazy/MazHome'
|
|
610
|
+
import { MazCog6Tooth } from '@maz-ui/icons/lazy/MazCog6Tooth'
|
|
611
|
+
|
|
612
|
+
const overlayOpen = ref(false)
|
|
613
|
+
const offcanvasOpen = ref(true)
|
|
614
|
+
const userMenuOpen = ref(true)
|
|
615
|
+
const badgesOpen = ref(true)
|
|
616
|
+
const sideEndOpen = ref(true)
|
|
617
|
+
const iconModeOpen = ref(true)
|
|
618
|
+
const submenusOpen = ref(true)
|
|
619
|
+
const groupsOpen = ref(true)
|
|
620
|
+
const basicOpen = ref(true)
|
|
621
|
+
</script>
|