maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/components/maz-sidebar.md

@@ -0,0 +1,507 @@
+---
+title: "MazSidebar"
+description: "MazSidebar is a composable sidebar system for dashboard, admin, and SaaS applications. It provides a fully accessible, collapsible navigation with multiple display modes."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-sidebar"
+---
+
+# MazSidebar
+
+> MazSidebar is a composable sidebar system for dashboard, admin, and SaaS applications. It provides a fully accessible, collapsible navigation with multiple display modes.
+
+- Package: `maz-ui`
+- Import: `import MazSidebar from 'maz-ui/components/MazSidebar'` or `import MazSidebarMenuButton from 'maz-ui/components/MazSidebarMenuButton'` or `import MazSidebarMenuSub from 'maz-ui/components/MazSidebarMenuSub'` or `import MazSidebarGroup from 'maz-ui/components/MazSidebarGroup'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-sidebar
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+**Tip:**
+
+`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`.
+
+**Warning: Deferred features (v1.1)**
+
+The following features are planned for a future release and are **not yet available**:
+- `localStorage` state persistence
+- `Cmd/Ctrl+B` keyboard shortcut
+- Automatic mobile drawer under a breakpoint
+
+## Sub-components
+
+| Component              | Role                                                                  |
+| ---------------------- | --------------------------------------------------------------------- |
+| `MazSidebar`           | Root container - provides state context                               |
+| `MazSidebarHeader`     | Fixed top area                                                        |
+| `MazSidebarContent`    | Scrollable central area                                               |
+| `MazSidebarFooter`     | Fixed bottom area                                                     |
+| `MazSidebarGroup`      | Item grouping with optional label                                     |
+| `MazSidebarSeparator`  | Visual divider (`<hr>`)                                               |
+| `MazSidebarMenu`       | `<ul>` wrapper with `role="menu"`                                     |
+| `MazSidebarMenuItem`   | `<li>` item wrapper                                                   |
+| `MazSidebarMenuButton` | Clickable item (link or button), supports icon, label, badge, tooltip |
+| `MazSidebarMenuSub`    | Collapsible sub-menu                                                  |
+| `MazSidebarTrigger`    | Toggle button (must be a descendant of `MazSidebar`)                  |
+
+## Basic usage
+
+```html
+<div class="flex h-screen">
+  <MazSidebar v-model:open="isOpen">
+    <MazSidebarHeader>
+      <div class="p-4 font-bold">My App</div>
+    </MazSidebarHeader>
+    <MazSidebarContent>
+      <MazSidebarMenu>
+        <MazSidebarMenuItem>
+          <MazSidebarMenuButton label="Dashboard" :active="true" />
+        </MazSidebarMenuItem>
+        <MazSidebarMenuItem>
+          <MazSidebarMenuButton label="Settings" />
+        </MazSidebarMenuItem>
+      </MazSidebarMenu>
+    </MazSidebarContent>
+    <MazSidebarFooter>
+      <div class="p-4">Footer</div>
+    </MazSidebarFooter>
+  </MazSidebar>
+  <main class="flex-1 p-4">Main content</main>
+</div>
+
+<script setup>
+const isOpen = ref(true)
+</script>
+```
+
+## Groups & dividers
+
+```html
+<MazSidebar v-model:open="isOpen">
+  <MazSidebarContent>
+    <MazSidebarGroup label="Navigation">
+      <MazSidebarMenu>
+        <MazSidebarMenuItem>
+          <MazSidebarMenuButton label="Dashboard" :active="true" />
+        </MazSidebarMenuItem>
+        <MazSidebarMenuItem>
+          <MazSidebarMenuButton label="Projects" />
+        </MazSidebarMenuItem>
+      </MazSidebarMenu>
+    </MazSidebarGroup>
+    <MazSidebarSeparator />
+    <MazSidebarGroup label="Settings">
+      <MazSidebarMenu>
+        <MazSidebarMenuItem>
+          <MazSidebarMenuButton label="Profile" />
+        </MazSidebarMenuItem>
+      </MazSidebarMenu>
+    </MazSidebarGroup>
+  </MazSidebarContent>
+</MazSidebar>
+```
+
+## Sub-menus
+
+```html
+<MazSidebar v-model:open="isOpen">
+  <MazSidebarContent>
+    <MazSidebarMenu>
+      <MazSidebarMenuItem>
+        <MazSidebarMenuSub label="Products" :default-open="true">
+          <MazSidebarMenuItem>
+            <MazSidebarMenuButton label="All Products" />
+          </MazSidebarMenuItem>
+          <MazSidebarMenuItem>
+            <MazSidebarMenuButton label="Add Product" />
+          </MazSidebarMenuItem>
+        </MazSidebarMenuSub>
+      </MazSidebarMenuItem>
+    </MazSidebarMenu>
+  </MazSidebarContent>
+</MazSidebar>
+```
+
+## Icon mode with tooltips
+
+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 only shown on hover when the sidebar is collapsed by default.
+
+### Controlling when the tooltip appears
+
+Both `MazSidebar` and `MazSidebarMenuButton` accept a `tooltip-mode` prop:
+
+- `closed` (default on the sidebar) - tooltip only shows on hover when the sidebar is collapsed
+- `always` - tooltip shows on hover regardless of the sidebar state
+
+Set it on the sidebar to apply to every descendant button, or override per-button:
+
+```html
+<!-- Every button: tooltip visible only when collapsed -->
+<MazSidebar tooltip-mode="closed">
+  <MazSidebarMenuButton :icon="MazHome" label="Dashboard" tooltip="Go to Dashboard" />
+</MazSidebar>
+
+<!-- This button overrides: tooltip always shown -->
+<MazSidebar tooltip-mode="closed">
+  <MazSidebarMenuButton
+    :icon="MazCog6Tooth"
+    label="Settings"
+    tooltip="Open Settings"
+    tooltip-mode="always"
+  />
+</MazSidebar>
+```
+
+**Tip: Performance**
+
+When no `tooltip` prop is provided on a button, the `v-tooltip` directive is not attached at all - no listeners, no popover instance.
+
+```html
+<script setup>
+import { MazHome } from '@maz-ui/icons/lazy/MazHome'
+import { MazCog6Tooth } from '@maz-ui/icons/lazy/MazCog6Tooth'
+
+const isOpen = ref(true)
+</script>
+
+<template>
+  <MazSidebar v-model:open="isOpen" collapsible="icon">
+    <MazSidebarContent>
+      <MazSidebarMenu>
+        <MazSidebarMenuItem>
+          <MazSidebarMenuButton :icon="MazHome" label="Dashboard" tooltip="Go to Dashboard" />
+        </MazSidebarMenuItem>
+      </MazSidebarMenu>
+    </MazSidebarContent>
+    <MazSidebarFooter>
+      <MazSidebarTrigger />
+    </MazSidebarFooter>
+  </MazSidebar>
+</template>
+```
+
+## Hover mode
+
+`collapsible="hover"` displays the sidebar in icon-only mode and **automatically expands it when the mouse enters the sidebar (or any descendant) and collapses it when the mouse leaves**. Keyboard focus also expands the sidebar, so users navigating with `Tab` see the full labels.
+
+**Tip:**
+
+This is a **purely visual** state. The `v-model:open` value is not updated and the persistence cookie is not written when the sidebar expands or collapses through hover. Use this mode when you want the rail-style sidebar of `collapsible="icon"` without exposing a toggle.
+
+```html
+<MazSidebar collapsible="hover">
+  <MazSidebarContent>
+    <MazSidebarMenu>
+      <MazSidebarMenuItem>
+        <MazSidebarMenuButton :icon="MazHome" label="Dashboard" />
+      </MazSidebarMenuItem>
+      <MazSidebarMenuItem>
+        <MazSidebarMenuButton :icon="MazCog6Tooth" label="Settings" />
+      </MazSidebarMenuItem>
+    </MazSidebarMenu>
+  </MazSidebarContent>
+</MazSidebar>
+```
+
+## Offcanvas mode
+
+```html
+<MazSidebar v-model:open="isOpen" collapsible="offcanvas">
+  <!-- content -->
+</MazSidebar>
+```
+
+## Overlay vs push mode
+
+In `mode="push"` (default), the sidebar is part of the document flow and pushes the main content.
+In `mode="overlay"`, the sidebar floats over the content with a backdrop, escape key support and focus trapping.
+
+```html
+<!-- Overlay mode: sidebar floats over content -->
+<MazSidebar v-model:open="isOpen" mode="overlay">
+  <!-- content -->
+</MazSidebar>
+```
+
+## Side end (right)
+
+```html
+<div class="flex h-screen">
+  <main class="flex-1">Main content</main>
+  <MazSidebar v-model:open="isOpen" side="end">
+    <!-- content -->
+  </MazSidebar>
+</div>
+```
+
+## Badges
+
+`badge` accepts a `string`, a `number`, or a full `MazBadgeProps` object (with an optional `text`) to fine-tune color, size, outlined, etc.
+
+```html
+<!-- Simple: pass a string or number -->
+<MazSidebarMenuButton label="Inbox" :badge="12" />
+
+<!-- Full customisation: pass a MazBadgeProps object -->
+<MazSidebarMenuButton
+  label="Errors"
+  :badge="{ text: 3, color: 'destructive' }"
+/>
+<MazSidebarMenuButton
+  label="Beta"
+  :badge="{ text: 'NEW', color: 'success', outlined: true }"
+/>
+```
+
+## User menu in footer
+
+```html
+<MazSidebar v-model:open="isOpen">
+  <MazSidebarContent><!-- ... --></MazSidebarContent>
+  <MazSidebarFooter>
+    <div class="flex items-center gap-3 p-3">
+      <MazAvatar src="..." size="0.8rem" />
+      <div class="flex-1 min-w-0">
+        <p class="m-0 text-md font-semibold">Jane Doe</p>
+        <p class="m-0 text-xs text-muted">jane@example.com</p>
+      </div>
+    </div>
+  </MazSidebarFooter>
+</MazSidebar>
+```
+
+## Mobile (static rendering)
+
+**Note:**
+
+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.
+
+```html
+<script setup>
+import { useWindowSize } from 'maz-ui'
+
+const { width } = useWindowSize()
+const isMobile = computed(() => width.value < 768)
+const isOpen = ref(!isMobile.value)
+
+watch(isMobile, (mobile) => {
+  isOpen.value = !mobile
+})
+</script>
+
+<template>
+  <div class="flex h-screen">
+    <MazSidebar v-model:open="isOpen" :mode="isMobile ? 'overlay' : 'push'">
+      <!-- content -->
+    </MazSidebar>
+    <main class="flex-1">
+      <MazSidebarTrigger />
+      <!-- page content -->
+    </main>
+  </div>
+</template>
+```
+
+## Programmatic control (v-model + composable)
+
+Use `v-model:open` for two-way binding, or `useSidebar()` inside any descendant component.
+
+```html
+<script setup>
+import { useSidebar } from 'maz-ui'
+
+// Inside a child component that is a descendant of MazSidebar:
+const sidebar = useSidebar()
+
+// sidebar.open.value  → boolean
+// sidebar.state.value → 'expanded' | 'collapsed'
+// sidebar.toggle()    → toggle open state
+// sidebar.setOpen(true/false) → set explicitly
+</script>
+
+<template>
+  <MazSidebar v-model:open="isOpen">
+    <MazSidebarContent>
+      <MazSidebarMenu>
+        <MazSidebarMenuItem>
+          <MazSidebarMenuButton label="Dashboard" />
+        </MazSidebarMenuItem>
+      </MazSidebarMenu>
+    </MazSidebarContent>
+    <!-- MazSidebarTrigger uses useSidebar() internally -->
+    <MazSidebarTrigger />
+  </MazSidebar>
+</template>
+```
+
+## Persistent open state
+
+The sidebar persists its open/collapsed state in a cookie (`maz-sidebar-open`) so it survives page reloads. This is **enabled by default**.
+
+```html
+<!-- Default: persistence enabled, cookie name "maz-sidebar-open" -->
+<MazSidebar v-model:open="isOpen" />
+
+<!-- Disable persistence -->
+<MazSidebar v-model:open="isOpen" :persist="false" />
+
+<!-- Custom cookie key (useful when multiple sidebars coexist) -->
+<MazSidebar v-model:open="isOpen" persist-key="admin-sidebar-open" />
+```
+
+### How it works
+
+- **In setup (server + client)**: the cookie is read and used to initialize the open state. On the server, the value is taken from the request `Cookie` header via Vue's `useSSRContext()`; on the client it comes from `document.cookie`.
+- **On client mount**: `update:open` is emitted if the persisted value differs from the `:open` prop, so your parent `v-model` stays in sync.
+- **On state change**: every transition between expanded/collapsed writes the new value to the cookie (1-year expiry, `SameSite=Lax`).
+
+### SSR considerations
+
+Persistence is **SSR-native** - the server reads the request cookie and renders the sidebar in its persisted state immediately, so there is no expand → collapse flash on hydration. This works out of the box in Nuxt and any Vue 3 SSR runtime that exposes the request headers through `useSSRContext()`.
+
+If you prefer to manage the state yourself (e.g. to share it with other parts of your app), disable persistence and feed the cookie via your own ref:
+
+```html
+<script setup>
+const sidebarOpen = useCookie<boolean>('maz-sidebar-open', { default: () => true })
+</script>
+
+<template>
+  <MazSidebar v-model:open="sidebarOpen" :persist="false">
+    <!-- ... -->
+  </MazSidebar>
+</template>
+```
+
+`:persist="false"` prevents the sidebar from also writing the cookie, leaving full control to your `useCookie` ref.
+
+## With router (vue-router / NuxtLink)
+
+`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.
+
+```html
+<!-- With vue-router -->
+<MazSidebarMenuButton :to="{ name: 'home' }" label="Home" />
+<MazSidebarMenuButton to="/about" label="About" />
+
+<!-- With plain href -->
+<MazSidebarMenuButton href="https://maz-ui.com" label="Docs" />
+
+<!-- Mark as active manually (useful when router is not available) -->
+<MazSidebarMenuButton label="Dashboard" :active="$route.name === 'dashboard'" />
+```
+
+## CSS Variables
+
+Customize the sidebar width using these CSS custom properties (also settable via `width` / `iconWidth` props):
+
+```css
+:root {
+  --maz-sidebar-width: 16rem;      /* expanded width */
+  --maz-sidebar-icon-width: 3rem;  /* icon-mode collapsed width */
+}
+```
+
+## Accessibility
+
+- The sidebar root element renders as `<aside aria-label="Sidebar">`
+- `MazSidebarMenu` renders as `<ul role="menu">`
+- `MazSidebarMenuItem` renders as `<li role="none">`
+- `MazSidebarTrigger` has `aria-expanded` and `aria-controls` referencing the sidebar `id`
+- `MazSidebarMenuButton` applies `aria-current="page"` on active items and exposes the label via `aria-label`
+- `MazSidebarMenuSub` trigger has `aria-expanded` and `aria-controls`
+- In `mode="overlay"`, pressing `Escape` closes the sidebar and focus is restored to the trigger element
+- In `mode="overlay"`, `Tab`/`Shift+Tab` are trapped within the sidebar
+- All transitions respect `prefers-reduced-motion`
+
+## MazSidebar
+
+## MazSidebar API
+
+`import MazSidebar from 'maz-ui/components/MazSidebar'`
+
+### Props
+
+- `id` (`string`): Unique identifier for the sidebar (auto-generated if not provided).
+- `open` (`boolean`, default: `true`, `v-model:open`): Whether the sidebar is open.
+- `side` (`"end" | "start"`, default: `"start"`): Side of the sidebar.
+- `collapsible` (`"icon" | "none" | "hover" | "offcanvas"`, default: `"offcanvas"`): How the sidebar collapses - offcanvas: completely hidden - icon: only icons visible - hover: only icons visible by default, expands on mouse hover or keyboard focus (transient visual state - does not update `v-model:open` nor the persistence cookie) - none: always fully visible.
+- `mode` (`"push" | "overlay"`, default: `"push"`): How the sidebar affects layout - push: sidebar is in document flow - overlay: sidebar floats over content with a backdrop.
+- `width` (`string`, default: `"16rem"`): Width of the expanded sidebar.
+- `icon-width` (`string`, default: `"3rem"`): Width of the collapsed sidebar in icon mode.
+- `tooltip-mode` (`MazSidebarTooltipMode`, default: `"closed"`): When descendant `MazSidebarMenuButton` components should display their tooltip. - `always`: tooltip shows on hover regardless of the sidebar state - `closed`: tooltip only shows on hover when the sidebar is collapsed Individual buttons can override this via their own `tooltipMode` prop.
+- `persist` (`boolean`, default: `true`): Persist the open/collapsed state in a cookie so it survives reloads. Restoration happens on client mount (SSR-safe). For zero-flash SSR, read the cookie server-side and forward it via `v-model:open`.
+- `persist-key` (`string`, default: `"maz-sidebar-open"`): Cookie key used when `persist` is enabled. Set a unique key per sidebar instance if you mount several sidebars on the same site.
+
+### Events
+
+- `@update:open` (payload: `value: boolean`): Emitted when open state changes
+
+### Slots
+
+- `#default`
+
+### Exposed (template ref)
+
+- `toggle`
+- `setOpen`
+
+## MazSidebarMenuButton
+
+## MazSidebarMenuButton API
+
+`import MazSidebarMenuButton from 'maz-ui/components/MazSidebarMenuButton'`
+
+### Props
+
+- `to` (`string | Record<string, unknown>`): Route for router-link navigation.
+- `href` (`string`): URL for anchor navigation.
+- `icon` (`MazIconLike`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control (size, title, fallback, …).
+- `label` (`string`): Label text.
+- `badge` (`MazSidebarMenuButtonBadge`): Badge content. Pass a `string`/`number` for a simple primary badge, or a full `MazBadgeProps` object (with optional `text`) to customise color, size, outlined, ….
+- `tooltip` (`string`): Tooltip text. When provided, shows a tooltip on hover via the `v-tooltip` directive.
+- `tooltip-mode` (`MazSidebarTooltipMode`): Controls when the tooltip should be displayed. - `always`: tooltip shows on hover regardless of the sidebar state - `closed`: tooltip only shows on hover when the sidebar is collapsed Overrides the parent `MazSidebar`'s `tooltipMode`. Falls back to the sidebar value (which defaults to `always`) when not provided.
+- `active` (`boolean`): Whether the item is active (highlights with `aria-current="page"`).
+- `disabled` (`boolean`): Whether the item is disabled.
+- `size` (`"sm" | "md" | "lg"`, default: `"md"`): Size of the button.
+
+### Events
+
+- `@click` (payload: `event: MouseEvent`)
+
+### Slots
+
+- `#icon`
+- `#default`
+
+## MazSidebarMenuSub
+
+## MazSidebarMenuSub API
+
+`import MazSidebarMenuSub from 'maz-ui/components/MazSidebarMenuSub'`
+
+### Props
+
+- `label` (`string`): Label for the sub-menu trigger button.
+- `icon` (`MazIconLike`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control.
+- `default-open` (`boolean`, default: `false`): Whether the sub-menu is open by default.
+
+### Slots
+
+- `#icon`
+- `#label`
+- `#chevron`
+- `#default`
+
+## MazSidebarGroup
+
+## MazSidebarGroup API
+
+`import MazSidebarGroup from 'maz-ui/components/MazSidebarGroup'`
+
+### Props
+
+- `label` (`string`): Optional label for the group.
+
+### Slots
+
+- `#default`