@reliability-design/web 1.4.6 → 1.4.7

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

@@ -1,209 +0,0 @@
-# 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-bg-surface-elevated` - Sidebar background (`#fafafa`)
-- `--rel-text-default` - 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-border-radius-md` - Floating variant border radius
-- `--rel-spacing-md` - Floating variant inset, header/footer padding
-- `--rel-spacing-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