Added docs

2026-04-13 18:57:47 +05:00
parent b323862e03
commit 5668cf20d9
9 changed files with 1421 additions and 1 deletions
@@ -0,0 +1,139 @@
+# Sidebar
+
+A collapsible, responsive sidebar layout system. Persists expand/collapse state via cookies and adapts between desktop (collapsible rail) and mobile (overlay drawer) modes automatically.
+
+---
+
+## Components
+
+| Component | Description |
+|---|---|
+| `SidebarProvider` | Root wrapper — provides collapse state context |
+| `Sidebar` | The sidebar panel itself |
+| `SidebarHeader` | Top area (logo, app name) — also acts as a collapse trigger |
+| `SidebarContent` | Scrollable middle area for navigation groups |
+| `SidebarFooter` | Bottom area (copyright, user info) |
+| `SidebarGroup` | Groups related menu items |
+| `SidebarGroupLabel` | Section heading within a group |
+| `SidebarGroupContent` | Container for menu items within a group |
+| `SidebarMenuItem` | Navigation link with icon support |
+| `SidebarInset` | Main content area adjacent to the sidebar |
+| `SidebarSeparator` | Horizontal divider line |
+| `SidebarTrigger` | Standalone toggle button (for mobile header bars) |
+
+---
+
+## Basic Layout
+
+```razor
+<SidebarProvider DefaultOpen="true">
+    <Sidebar>
+        <SidebarHeader>
+            <div class="flex items-center gap-2 px-1 py-1.5">
+                <img src="logo.svg" alt="Logo" class="size-8" />
+                <span class="font-semibold text-sm">My App</span>
+            </div>
+        </SidebarHeader>
+
+        <SidebarContent>
+            <SidebarGroup>
+                <SidebarGroupLabel Label="Navigation" />
+                <SidebarGroupContent>
+                    <SidebarMenuItem Href="/" Tooltip="Home" IsActive="true">
+                        <Icon>
+                            <!-- SVG icon -->
+                        </Icon>
+                        <ChildContent>Home</ChildContent>
+                    </SidebarMenuItem>
+                    <SidebarMenuItem Href="/about" Tooltip="About">
+                        <Icon>
+                            <!-- SVG icon -->
+                        </Icon>
+                        <ChildContent>About</ChildContent>
+                    </SidebarMenuItem>
+                </SidebarGroupContent>
+            </SidebarGroup>
+        </SidebarContent>
+
+        <SidebarFooter>
+            <SidebarSeparator />
+            <div class="px-3 py-2 text-xs text-sidebar-foreground/50">
+                &copy; 2026 My Company
+            </div>
+        </SidebarFooter>
+    </Sidebar>
+
+    <SidebarInset>
+        <header class="flex h-14 items-center gap-2 border-b border-border px-4">
+            <SidebarTrigger Class="md:hidden" />
+            <h1 class="text-sm font-medium">My App</h1>
+            <div class="ml-auto">
+                <ThemeToggle />
+            </div>
+        </header>
+
+        <div class="flex-1 p-4 md:p-6">
+            @Body
+        </div>
+    </SidebarInset>
+</SidebarProvider>
+```
+
+---
+
+## Parameters
+
+### SidebarProvider
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `DefaultOpen` | `bool` | `true` | Initial sidebar state on first visit |
+| `ChildContent` | `RenderFragment` | — | Must contain `Sidebar` + `SidebarInset` |
+
+### SidebarMenuItem
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `Href` | `string?` | — | Navigation URL |
+| `Tooltip` | `string?` | — | Tooltip text (shown on hover when collapsed) |
+| `IsActive` | `bool` | `false` | Highlights the item with accent styling |
+| `Icon` | `RenderFragment?` | — | Icon slot (typically an SVG) |
+| `Class` | `string?` | — | Additional CSS classes |
+
+### SidebarGroupLabel
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `Label` | `string?` | — | Label text (alternative to ChildContent) |
+| `ChildContent` | `RenderFragment?` | — | Custom label markup |
+| `Class` | `string?` | — | Additional CSS classes |
+
+### All sidebar components
+
+Every sidebar component accepts:
+- `ChildContent` — slot for nested content
+- `Class` — additional CSS classes to append
+
+---
+
+## Behavior
+
+### Desktop (≥ 768px)
+- Clicking the **SidebarHeader** or **SidebarTrigger** toggles between expanded and collapsed (icon rail) states
+- Collapsed state shrinks to `var(--sidebar-width-icon)` (3rem) showing only icons
+- State persists via a `sidebar:state` cookie (1 year)
+
+### Mobile (< 768px)
+- Sidebar renders as an off-screen drawer
+- Opens with a semi-transparent backdrop overlay
+- Clicking the overlay or trigger closes it
+- Navigation link clicks auto-close the sidebar
+
+### CSS Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `--sidebar-width` | `16rem` | Expanded sidebar width |
+| `--sidebar-width-icon` | `3rem` | Collapsed (icon rail) width |
+
+These can be overridden in your `@theme` block.