@reliability-design/web 1.0.3 → 1.1.1

package/dist/components/rel-sidebar/README.md

@@ -0,0 +1,209 @@
+# rel-sidebar
+
+## Overview
+A sophisticated sidebar navigation system with multiple components: `rel-sidebar-provider` (state manager), `rel-sidebar` (visual container), `rel-sidebar-trigger` (toggle button), and layout helpers (`rel-sidebar-header`, `rel-sidebar-footer`, `rel-sidebar-content`, `rel-sidebar-rail`). Supports three variants (sidebar, floating, inset), two collapsible modes (offcanvas, icon), mobile detection, localStorage persistence, keyboard shortcuts, and focus trapping.
+
+## Components
+This sidebar system consists of multiple components that work together:
+- **`<rel-sidebar-provider>`**: Root wrapper that manages state
+- **`<rel-sidebar>`**: Visual sidebar container
+- **`<rel-sidebar-trigger>`**: Toggle button
+- **`<rel-sidebar-header>`**: Header layout helper
+- **`<rel-sidebar-footer>`**: Footer layout helper
+- **`<rel-sidebar-content>`**: Main content wrapper
+- **`<rel-sidebar-rail>`**: Collapsed (icon-only) state content
+
+## Usage
+```html
+<!-- Basic sidebar with provider -->
+<rel-sidebar-provider>
+  <rel-sidebar>
+    <rel-sidebar-header>
+      <h2>App Name</h2>
+      <rel-sidebar-trigger>
+        <button>☰</button>
+      </rel-sidebar-trigger>
+    </rel-sidebar-header>
+    
+    <rel-sidebar-content>
+      <nav>
+        <a href="#home">Home</a>
+        <a href="#about">About</a>
+        <a href="#contact">Contact</a>
+      </nav>
+    </rel-sidebar-content>
+    
+    <rel-sidebar-footer>
+      <p>© 2024 Company</p>
+    </rel-sidebar-footer>
+  </rel-sidebar>
+  
+  <main>
+    <h1>Main Content</h1>
+    <p>Page content goes here</p>
+  </main>
+</rel-sidebar-provider>
+
+<!-- Controlled open state -->
+<rel-sidebar-provider open="true">
+  <rel-sidebar>
+    <nav>Navigation items</nav>
+  </rel-sidebar>
+  <main>Content</main>
+</rel-sidebar-provider>
+
+<!-- Right-side floating variant -->
+<rel-sidebar-provider side="right" variant="floating" width="lg">
+  <rel-sidebar>
+    <h3>Right Sidebar</h3>
+  </rel-sidebar>
+  <main>Content</main>
+</rel-sidebar-provider>
+
+<!-- Offcanvas mode (overlay on all screen sizes) -->
+<rel-sidebar-provider collapsible="offcanvas">
+  <rel-sidebar>
+    <nav>Menu</nav>
+  </rel-sidebar>
+  <main>Content</main>
+</rel-sidebar-provider>
+
+<!-- Listen for state changes -->
+<rel-sidebar-provider id="sidebarProvider">
+  <rel-sidebar>Nav</rel-sidebar>
+  <main>Content</main>
+</rel-sidebar-provider>
+<script>
+  const provider = document.getElementById('sidebarProvider');
+  provider.addEventListener('rel-sidebar-change', (e) => {
+    console.log('Open:', e.detail.open);
+    console.log('Collapsed:', e.detail.collapsed);
+    console.log('Reason:', e.detail.reason);
+  });
+</script>
+```
+
+## API
+
+### rel-sidebar-provider Properties
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` (reflected) | `boolean?` | `undefined` | Controlled open state (undefined = uncontrolled) |
+| `defaultopen` | `boolean` | `true` | Default open state (uncontrolled mode) |
+| `collapsed` (reflected) | `boolean?` | `undefined` | Controlled collapsed state |
+| `defaultcollapsed` | `boolean` | `false` | Default collapsed state (uncontrolled mode) |
+| `variant` | `"sidebar" \| "floating" \| "inset"` | `"sidebar"` | Visual variant |
+| `side` | `"left" \| "right"` | `"left"` | Which side the sidebar appears on |
+| `collapsible` | `"offcanvas" \| "icon" \| "none"` | `"icon"` | Collapsible behavior mode |
+| `width` | `"sm" \| "md" \| "lg"` | `"md"` | Sidebar width (240/280/320px) |
+| `persist-key` | `string` | `"rel-sidebar"` | localStorage key for persistence |
+| `keyboard-shortcut` | `boolean` | `true` | Enable Ctrl/Cmd+B shortcut |
+| `disable-persist` | `boolean` | `false` | Disable localStorage persistence |
+| `disable-overlay-close` | `boolean` | `false` | Prevent closing on overlay click |
+
+### rel-sidebar Properties
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `inset` | `boolean` | `false` | Use inset variant styling (overrides provider variant) |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `rel-sidebar-change` | `{ open, collapsed, reason }` | Fired when sidebar state changes |
+| `rel-sidebar-state` | `{ isOpen, isCollapsed, isMobile, side, variant, collapsible, width }` | Internal state sync event |
+
+### Change Reasons
+- `"trigger"`: Toggled via trigger button
+- `"rail"`: Toggled collapsed state
+- `"overlay"`: Closed by clicking overlay
+- `"escape"`: Closed via Escape key
+- `"shortcut"`: Toggled via keyboard shortcut (Ctrl/Cmd+B)
+- `"api"`: Changed programmatically via `setOpen()` or `setCollapsed()`
+
+## Methods
+
+### Provider Methods
+```typescript
+provider.setOpen(nextOpen: boolean, reason?: string): void
+provider.setCollapsed(nextCollapsed: boolean, reason?: string): void
+```
+
+##Slots
+| Slot | Component | Description |
+|------|-----------|-------------|
+| (default) | All | Main content area |
+
+## CSS Parts
+None exposed.
+
+## Tokens / CSS Variables
+
+### Width Tokens (defined on `<rel-sidebar>`)
+- `--sidebar-width-sm`: `240px` (small width)
+- `--sidebar-width-md`: `280px` (medium width)
+- `--sidebar-width-lg`: `320px` (large width)
+- `--sidebar-width-collapsed`: `56px` (collapsed/icon-only width)
+
+### Transition Tokens
+- `--sidebar-transition-duration`: `0.2s`
+- `--sidebar-transition-timing`: `cubic-bezier(0.4, 0, 0.2, 1)`
+
+### Color Tokens
+- `--rel-surface-secondary` - Sidebar background (`#fafafa`)
+- `--rel-text-primary` - Text color
+- `--rel-border-default` - Border color
+- `--rel-overlay-scrim` - Overlay background (`rgba(0, 0, 0, 0.5)`)
+
+### Shadow Tokens (floating variant)
+- `--rel-shadows-shadow-400` - Floating variant shadow
+
+### Other Tokens
+- `--rel-borders-radius-border-radius-300` - Floating variant border radius
+- `--rel-spacing-space-md` - Floating variant inset, header/footer padding
+- `--rel-spacing-space-2xs` - Used in various layouts
+
+## Accessibility
+- Sidebar uses `role="navigation"`
+- Focus trap active in offcanvas mode
+- Escape key closes offcanvas
+- Keyboard shortcut (Ctrl/Cmd+B) for toggling
+- Restores focus to trigger when closing
+
+### Keyboard Interactions
+| Key | Action |
+|-----|--------|
+| `Ctrl/Cmd + B` | Toggle sidebar (open/collapsed depending on mode) |
+| `Escape` | Close sidebar (offcanvas mode only) |
+| `Tab` | Focus trap within sidebar when open in offcanvas mode |
+
+### Focus Behavior
+- In offcanvas mode, focus moves to first focusable element when opened
+- Focus is trapped within sidebar in offcanvas mode
+- Focus restores to trigger button when closed
+
+## Notes / Edge Cases
+- **Mobile detection**: Automatically detects `max-width: 768px` breakpoint and switches to offcanvas mode
+- **Collapsible modes**:
+  - **offcanvas**: Sidebar slides in/out with overlay (like a drawer)
+  - **icon**: Sidebar collapses to icon-only width (56px)
+  - **none**: Sidebar cannot be collapsed (always full width)
+
+- **Variants**:
+  - **sidebar**: Fixed position, full height
+  - **floating**: Inset with margins, rounded corners, shadow
+  - **inset**: Relative position, no shadow
+
+- **State persistence**: By default, sidebar state is saved to localStorage and restored on reload (disable with `disable-persist`)
+- **Controlled vs uncontrolled**: If `open` or `collapsed` props are set, the component is controlled and won't manage its own state
+- **Mobile behavior**: On mobile, sidebar starts closed and ignores persisted state
+- **Scroll locking**: In offcanvas mode, body scroll is locked when sidebar is open
+- **Transitions disabled**: When `prefers-reduced-motion: reduce`
+- The provider uses `display: contents` to avoid affecting layout
+- Sidebar is overlaid with `z-index: 1000` in offcanvas mode
+- Overlay is `z-index: 999`
+
+### Width Values
+- **sm**: 240px
+- **md**: 280px
+- **lg**: 320px
+- **collapsed**: 56px