@reliability-design/web 1.0.3 → 1.1.1

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

@@ -0,0 +1,224 @@
+# rel-sheet
+
+## Overview
+A slide-in panel component system with multiple helper components. Features four slide directions (top, right, bottom, left), configurable sizes, modal/non-modal modes, focus trapping, scroll locking, and optional overlay. Built with composition: `rel-sheet` (controller), `rel-sheet-trigger` (opener), `rel-sheet-content` (panel), and layout helpers (`rel-sheet-header`, `rel-sheet-footer`, `rel-sheet-title`, `rel-sheet-description`, `rel-sheet-close`).
+
+## Components
+- **`<rel-sheet>`**: Root wrapper that manages open state
+- **`<rel-sheet-trigger>`**: Button to open the sheet
+- **`<rel-sheet-content>`**: Slide-in panel with all visual elements
+- **`<rel-sheet-header>`**: Header layout helper with bottom border
+- **`<rel-sheet-footer>`**: Footer layout helper with top border
+- **`<rel-sheet-title>`**: Title text (auto-linked to `aria-labelledby`)
+- **`<rel-sheet-description>`**: Description text (auto-linked to `aria-describedby`)
+- **`<rel-sheet-close>`**: Custom close button wrapper
+
+## Usage
+```html
+<!-- Basic right-side sheet -->
+<rel-sheet>
+  <rel-sheet-trigger>
+    <button>Open Settings</button>
+  </rel-sheet-trigger>
+  
+  <rel-sheet-content>
+    <rel-sheet-header>
+      <rel-sheet-title>Settings</rel-sheet-title>
+      <rel-sheet-description>Configure your preferences</rel-sheet-description>
+    </rel-sheet-header>
+    
+    <p>Sheet content goes here...</p>
+    
+    <rel-sheet-footer>
+      <rel-sheet-close>
+        <button>Cancel</button>
+      </rel-sheet-close>
+      <button>Save</button>
+    </rel-sheet-footer>
+  </rel-sheet-content>
+</rel-sheet>
+
+<!-- Left-side sheet, large size -->
+<rel-sheet>
+  <rel-sheet-trigger>
+    <button>Open Menu</button>
+  </rel-sheet-trigger>
+  
+  <rel-sheet-content side="left" size="lg">
+    <nav>
+      <a href="#home">Home</a>
+      <a href="#about">About</a>
+      <a href="#contact">Contact</a>
+    </nav>
+  </rel-sheet-content>
+</rel-sheet>
+
+<!-- Bottom sheet without overlay -->
+<rel-sheet defaultopen>
+  <rel-sheet-trigger>
+    <button>Toggle Bottom Sheet</button>
+  </rel-sheet-trigger>
+  
+  <rel-sheet-content side="bottom" hide-overlay>
+    <p>Bottom sheet content</p>
+  </rel-sheet-content>
+</rel-sheet>
+
+<!-- Controlled state -->
+<rel-sheet id="controlledSheet" open>
+  <rel-sheet-trigger>
+    <button>Open</button>
+  </rel-sheet-trigger>
+  
+  <rel-sheet-content>
+    <p>This sheet is controlled externally</p>
+  </rel-sheet-content>
+</rel-sheet>
+<script>
+  const sheet = document.getElementById('controlledSheet');
+  sheet.addEventListener('rel-open-change', (e) => {
+    console.log('Sheet open:', e.detail.open);
+    console.log('Reason:', e.detail.reason);
+  });
+</script>
+
+<!-- Without built-in close button -->
+<rel-sheet>
+  <rel-sheet-trigger>
+    <button>Open</button>
+  </rel-sheet-trigger>
+  
+  <rel-sheet-content show-close="false">
+    <p>Custom close handling</p>
+    <rel-sheet-close>
+      <button>Close Me</button>
+    </rel-sheet-close>
+  </rel-sheet-content>
+</rel-sheet>
+```
+
+## API
+
+### rel-sheet Properties
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` (reflected) | `boolean?` | `undefined` | Controlled open state |
+| `defaultopen` | `boolean` | `false` | Default open state (uncontrolled) |
+| `disabled` | `boolean` | `false` | Disable trigger |
+| `modal` | `boolean` | `true` | Enable modal behavior (focus trap) |
+
+### rel-sheet-content Properties
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Which side the sheet slides from |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Sheet width/height (320/420/540/640px) |
+| `hide-overlay` | `boolean` | `false` | Hide the backdrop overlay |
+| `close-on-overlay` | `boolean` | `true` | Allow closing by clicking overlay |
+| `show-close` | `boolean` | `true` | Show built-in close button (✕) |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `rel-open-change` | `{ open, reason }` | Fired when sheet opens/closes |
+
+### Close Reasons
+- `"trigger"`: Toggled via trigger button
+- `"close"`: Closed via close button
+- `"overlay"`: Closed by clicking overlay
+- `"escape"`: Closed via Escape key
+- `"api"`: Changed via `setOpen()` method
+
+## Methods
+
+### Sheet Methods
+```typescript
+sheet.setOpen(nextOpen: boolean, reason?: string): void
+```
+
+## Slots
+| Slot | Component | Description |
+|------|-----------|-------------|
+| (default) | `rel-sheet` | Trigger and content elements |
+| (default) | `rel-sheet-trigger` | Trigger button/element |
+| (default) | `rel-sheet-content` | Panel content |
+| (default) | Layout helpers | Content within headers/footers/titles |
+
+## CSS Parts
+| Part | Description |
+|------|-------------|
+| `overlay` | Backdrop overlay element |
+| `panel` | Main panel container |
+
+## Tokens / CSS Variables
+
+### Size Tokens (defined on `<rel-sheet-content>`)
+- `--sheet-size-sm`: `320px`
+- `--sheet-size-md`: `420px`
+- `--sheet-size-lg`: `540px`
+- `--sheet-size-xl`: `640px`
+
+### Transition Tokens
+- `--sheet-transition-duration`: `0.3s`
+- `--sheet-transition-timing`: `cubic-bezier(0.32, 0.72, 0, 1)`
+
+### Color Tokens
+- `--rel-colors-white` - Panel background
+- `--rel-colors-gray-heading` - Title and close button color
+- `--rel-colors-gray-body` - Description color
+- `--rel-colors-gray-surface` - Close button hover background
+- `--rel-colors-gray-border` - Header/footer borders
+- `--rel-overlay-scrim` - Overlay background
+- `--rel-colors-primary-500` - Close button focus outline
+
+### Shadow Tokens
+- `--rel-shadows-shadow-500` - Panel shadow
+
+### Border Tokens
+- `--rel-borders-radius-border-radius-300` - Panel border radius (top corners for bottom, etc.)
+
+### Spacing Tokens
+- `--rel-spacing-space-lg` - Panel content padding
+- `--rel-spacing-space-md` - Header/footer padding, close button positioning
+- `--rel-spacing-space-xs` - Close button padding
+
+## Accessibility
+- Panel uses `role="dialog"` and `aria-modal`
+- Auto-links `aria-labelledby` to `<rel-sheet-title>`
+- Auto-links `aria-describedby` to `<rel-sheet-description>`
+- Focus trap in modal mode
+- Escape key closes sheet
+- Restores focus to trigger on close
+
+### Keyboard Interactions
+| Key | Action |
+|-----|--------|
+| `Escape` | Close sheet |
+| `Tab` | Focus trap within sheet (modal mode only) |
+
+### Focus Behavior
+- On open, focuses first focusable element (or panel if none found)
+- Focus trapped within panel in modal mode
+- On close, restores focus to trigger button
+
+## Notes / Edge Cases
+- **Side positioning and transforms**:
+  - **right**: Slides in from right edge, `translateX(100%)` to `translateX(0)`
+  - **left**: Slides in from left edge, `translateX(-100%)` to `translateX(0)`
+  - **bottom**: Slides in from bottom, `translateY(100%)` to `translateY(0)`
+  - **top**: Slides in from top, `translateY(-100%)` to `translateY(0)`
+
+- **Size constraints**:
+  - Left/right: `max-width: 90vw`
+  - Top/bottom: `max-height: 80vh`
+
+- **Scroll locking**: Body scroll is locked when sheet is open (with scrollbar width compensation)
+- **Close button position**: Top-right by default, but top-left for `side="left"`
+- **Reduced motion**: Transitions disabled, panel hidden via `display: none` instead of transform
+- The sheet root uses `display: contents`
+- Panel is overlaid with `z-index: 1000`, fixed position
+- Overlay detection for `aria-labelledby`/`aria-describedby` happens automatically based on slotted `<rel-sheet-title>` and `<rel-sheet-description>` elements
+- Built-in close button is "✕" character at font-size 20px
+
+### Controlled vs Uncontrolled
+- If `open` prop is set, the sheet is controlled and won't manage its own state
+- Use `rel-open-change` event to sync controlled state