@reliability-design/web 1.4.6 → 1.4.8

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

@@ -1,100 +1,88 @@
-# rel-divider
-
-## Overview
-A simple divider component supporting horizontal and vertical orientations. Provides a visual separator line with configurable styling via CSS tokens.
-
-## Usage
-```html
-<!-- Horizontal divider (default) -->
-<p>Section 1</p>
-<rel-divider></rel-divider>
-<p>Section 2</p>
-
-<!-- Vertical divider -->
-<div style="display: flex; align-items: center; height: 50px;">
-  <span>Item 1</span>
-  <rel-divider orientation="vertical"></rel-divider>
-  <span>Item 2</span>
-  <rel-divider orientation="vertical"></rel-divider>
-  <span>Item 3</span>
-</div>
-
-<!-- In a toolbar -->
-<div style="display: flex; gap: 16px; align-items: center;">
-  <button>Action 1</button>
-  <rel-divider orientation="vertical"></rel-divider>
-  <button>Action 2</button>
-  <rel-divider orientation="vertical"></rel-divider>
-  <button>Action 3</button>
-</div>
-
-<!-- Between content sections -->
-<section>
-  <h2>Section A</h2>
-  <p>Content A</p>
-</section>
-<rel-divider></rel-divider>
-<section>
-  <h2>Section B</h2>
-  <p>Content B</p>
-</section>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Divider orientation |
-
-## Events
-None.
-
-## Slots
-None.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-text-default` - Text color (not used visually, but set)
-
-### Color Tokens
-- `--rel-border-default` - Divider line color
-
-### Border Tokens
-- `--rel-stroke-sm` - Line thickness (width/height)
-
-### Spacing Tokens
-- `--rel-spacing-md` - Margin around divider
-
-## Accessibility
-- Uses `role="separator"` for proper ARIA semantics
-- Screen readers will announce the divider as a separator
-
-### Keyboard Interactions
-- None (non-interactive element)
-
-### Focus Behavior
-- Does not receive focus
-
-## Notes / Edge Cases
-- **Horizontal orientation**:
-  - `width: 100%`
-  - `height: var(--rel-stroke-sm)`
-  - `margin: var(--rel-spacing-md) 0` (vertical margin)
-  
-- **Vertical orientation**:
-  - `width: var(--rel-stroke-sm)`
-  - `height: 100%`
-  - `margin: 0 var(--rel-spacing-md)` (horizontal margin)
-  - Uses `align-self: stretch` to fill parent height
-
-- The divider is purely visual and has `background: transparent` on the host element
-- The actual divider line is rendered by an internal `.rel-divider` div
-- For vertical dividers to work properly, the parent must have a defined height
-- Vertical dividers use `align-self: stretch` to match the parent's height
-- The divider is `display: block` on the host element
+# rel-divider
+
+A thin separator rule, horizontal or vertical, drawn with the neutral elevated background token at the small stroke width and padded by the medium spacing token. Use it to visually split sections, list groups or toolbar clusters. Do not use it purely as a spacer — use layout gaps for that.
+
+## Usage
+
+```html
+<!-- Horizontal (default): full width, vertical margin -->
+<section>
+  <h2>Section A</h2>
+  <p>Content A</p>
+</section>
+<rel-divider></rel-divider>
+<section>
+  <h2>Section B</h2>
+  <p>Content B</p>
+</section>
+
+<!-- Vertical: give the parent a height or use a flex row -->
+<div style="display: flex; align-items: center; height: 40px;">
+  <rel-button variant="ghost">Cut</rel-button>
+  <rel-divider orientation="vertical"></rel-divider>
+  <rel-button variant="ghost">Copy</rel-button>
+  <rel-divider orientation="vertical"></rel-divider>
+  <rel-button variant="ghost">Paste</rel-button>
+</div>
+
+<!-- Restyle through the part -->
+<style>
+  .thick::part(base) {
+    height: 2px;
+    margin: 24px 0;
+  }
+</style>
+<rel-divider class="thick"></rel-divider>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-divider.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Axis of the rule: `horizontal` spans the full width with vertical margin; `vertical` is a full-height line with horizontal margin (the parent needs a defined height or a flex row). Mirrored to `aria-orientation` on the host. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The rendered rule — restyle thickness, colour or margin here. |
+
+## Tokens / CSS Variables
+
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-divider-spacing` | `var(--rel-spacing-md)` | Cross-axis margin around the rule; default 16px. Figma specifies none, so set it to `0` for strict parity — the default is kept for back-compat and is planned to become `0` in 3.0. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The host receives `role="separator"` when connected and `aria-orientation` (`horizontal` or `vertical`) on every update, so screen readers announce it as a separator in the right axis. The inner rule also carries `role="separator"`.
+- Not focusable; no keyboard interaction.
+
+## Notes / Edge Cases
+
+- **Vertical dividers need a height.** The vertical rule is `height: 100%` with `align-self: stretch`; inside a flex row it stretches to the row, otherwise the parent must have a definite height or the rule collapses to 0px.
+- The host is `display: block` with a transparent background; the visible line is the inner `base` part. Override thickness, colour or margin via `::part(base)` rather than on the host.

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

@@ -1,200 +1,187 @@
-# RelDrawer Component
-
-A flexible, accessible drawer/sheet component for the Reliability Design System.
-
-## Features
-
-- Slides from bottom (default), left, right, or top
-- Overlay/backdrop with configurable dismiss behavior
-- Drag-to-close for bottom drawers (touch & mouse)
-- Focus trapping for modal mode
-- Keyboard navigation (Escape to close, Tab trap)
-- Token-driven styling (no hardcoded colors)
-- Respects `prefers-reduced-motion`
-- Slot-based content API
-
-## Basic Usage
-
-```html
-<rel-drawer open>
-  <h3 slot="title">Drawer Title</h3>
-  <p slot="description">Optional description text</p>
-
-  <p>Your drawer content goes here.</p>
-
-  <div slot="footer">
-    <button>Cancel</button>
-    <button>Save</button>
-  </div>
-</rel-drawer>
-```
-
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `open` | `boolean` | `false` | Controls drawer visibility (reflects) |
-| `side` | `"bottom" \| "left" \| "right" \| "top"` | `"bottom"` | Edge from which drawer slides |
-| `dismissible` | `boolean` | `true` | Allows backdrop/Escape close |
-| `modal` | `boolean` | `true` | Enables focus trap and `aria-modal` |
-| `close-on-backdrop` | `boolean` | `true` | Close when clicking backdrop |
-| `close-on-escape` | `boolean` | `true` | Close when pressing Escape |
-| `show-handle` | `boolean` | `true` | Show handle bar (bottom drawer only) |
-| `draggable` | `boolean` | `true` | Enable drag-to-close (bottom only) |
-| `snap-threshold` | `number` | `0.25` | Drag distance % to trigger close |
-| `max-height` | `string` | `"80vh"` | Max height for bottom/top drawers |
-| `width` | `string` | `"420px"` | Width for left/right drawers |
-| `disabled` | `boolean` | `false` | Disables all interaction |
-
-## Events
-
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `rel-open-change` | `{ open: boolean }` | Fires when open state changes |
-| `rel-close` | `{ reason: "backdrop" \| "escape" \| "drag" \| "programmatic" }` | Fires when drawer closes |
-
-## Slots
-
-| Slot | Description |
-|------|-------------|
-| (default) | Drawer content body |
-| `title` | Header title text |
-| `description` | Header description text |
-| `footer` | Footer content (buttons, actions) |
-
-## CSS Parts
-
-| Part | Description |
-|------|-------------|
-| `overlay` | Backdrop element |
-| `panel` | Drawer panel container |
-| `handle` | Drag handle bar |
-| `header` | Header container |
-| `content` | Content container |
-| `footer` | Footer container |
-| `close-button` | Close button (X) |
-
-## Examples
-
-### Bottom Sheet (Mobile-style)
-
-```html
-<rel-drawer open side="bottom" max-height="60vh">
-  <h3 slot="title">Select an option</h3>
-  <ul>
-    <li>Option 1</li>
-    <li>Option 2</li>
-    <li>Option 3</li>
-  </ul>
-</rel-drawer>
-```
-
-### Side Panel (Desktop Navigation)
-
-```html
-<rel-drawer open side="right" width="300px">
-  <h3 slot="title">Navigation</h3>
-  <nav>
-    <a href="/home">Home</a>
-    <a href="/about">About</a>
-    <a href="/contact">Contact</a>
-  </nav>
-</rel-drawer>
-```
-
-### Programmatic Control
-
-```javascript
-const drawer = document.querySelector('rel-drawer');
-
-// Open drawer
-drawer.open = true;
-
-// Close drawer
-drawer.open = false;
-
-// Listen for close event
-drawer.addEventListener('rel-close', (e) => {
-  console.log('Closed via:', e.detail.reason);
-});
-```
-
-### Non-Modal Drawer
-
-```html
-<rel-drawer open modal="false" dismissible="false">
-  <!-- Doesn't trap focus, can't be dismissed -->
-  <p>Persistent sidebar content</p>
-</rel-drawer>
-```
-
-## Accessibility
-
-- When `modal="true"`:
-  - Sets `role="dialog"` and `aria-modal="true"`
-  - Traps focus within drawer
-  - Returns focus to trigger element on close
-  - Locks body scroll to prevent background scrolling
-- Keyboard support:
-  - `Escape`: Close drawer (if `close-on-escape`)
-  - `Tab`: Cycle focus within drawer (if `modal`)
-- Screen reader: Announced as dialog when opened
-
-## Styling
-
-The drawer uses design system tokens for all colors, spacing, shadows, and borders. You can customize appearance using CSS parts:
-
-```css
-rel-drawer::part(overlay) {
-  background: rgba(0, 0, 0, 0.7);
-}
-
-rel-drawer::part(panel) {
-  box-shadow: 0 0 30px rgba(0, 0, 0, 0.3);
-}
-
-rel-drawer::part(handle) {
-  background: var(--rel-bg-info);
-}
-```
-
-## Framework Integration
-
-### React
-
-```jsx
-<RelDrawer
-  open={isOpen}
-  onRelClose={(e) => setIsOpen(false)}
-  side="right"
->
-  <span slot="title">Settings</span>
-  <SettingsForm />
-</RelDrawer>
-```
-
-### Angular
-
-```html
-<rel-drawer
-  [open]="isOpen"
-  (rel-close)="isOpen = false"
-  side="left"
->
-  <span slot="title">Menu</span>
-  <app-menu></app-menu>
-</rel-drawer>
-```
-
-### Vue
-
-```vue
-<rel-drawer
-  :open="isOpen"
-  @rel-close="isOpen = false"
-  side="bottom"
->
-  <template #title>Options</template>
-  <OptionsPanel />
-</rel-drawer>
-```
+# rel-drawer
+
+`<rel-drawer>` implements the Figma **Drawer** component (5699:6844): a panel that slides in from the bottom, left or right edge over a scrim, with an optional drag-to-close handle on bottom drawers, a title/description header, a scrollable body and a footer. The folder also registers `<rel-drawer-footer>`, the right-aligned actions row the drawer uses for its `footer` slot, which can be reused standalone. Use a drawer for side navigation, filter panels and secondary editing flows that should stay attached to a viewport edge; use `<rel-modal>` for confirmations and short dialogs, and `<rel-popover>` for small contextual content anchored to a trigger.
+
+## Usage
+
+```html
+<!-- Bottom drawer (default) with header, body and footer actions -->
+<rel-button id="open-filters">Filters</rel-button>
+
+<rel-drawer id="filters" title="Filters" description="Narrow down the results.">
+  <p>Filter controls go here.</p>
+  <rel-button slot="footer" variant="secondary" id="reset">Reset</rel-button>
+  <rel-button slot="footer" variant="primary" id="apply">Apply</rel-button>
+</rel-drawer>
+
+<script>
+  const drawer = document.getElementById('filters');
+  document.getElementById('open-filters').addEventListener('click', () => { drawer.open = true; });
+  document.getElementById('apply').addEventListener('click', () => { drawer.open = false; });
+  drawer.addEventListener('rel-open-change', (e) => {
+    console.log('open =', e.detail.open);
+  });
+</script>
+
+<!-- Right side panel with an explicit width -->
+<rel-drawer side="right" width="360px" title="Settings">
+  <p>Account settings.</p>
+</rel-drawer>
+
+<!-- Left navigation drawer -->
+<rel-drawer side="left" title="Menu">
+  <nav>
+    <a href="/home">Home</a>
+    <a href="/reports">Reports</a>
+  </nav>
+</rel-drawer>
+
+<!-- Bottom drawer that closes after a longer drag -->
+<rel-drawer snap-threshold="0.5" title="Share">
+  <p>Drag the handle down past half the panel to close.</p>
+</rel-drawer>
+
+<!-- Non-modal, persistent side panel (no scrim, no focus trap, not dismissible) -->
+<rel-drawer id="sidebar" side="left" open>
+  <p>Always-on sidebar content.</p>
+</rel-drawer>
+<script>
+  // Boolean props that default to true can only be switched off from JS —
+  // an absent attribute leaves the default in place.
+  const sidebar = document.getElementById('sidebar');
+  sidebar.modal = false;
+  sidebar.dismissible = false;
+</script>
+
+<!-- Standalone actions row using the same layout as the drawer footer -->
+<rel-drawer-footer>
+  <rel-button variant="secondary">Cancel</rel-button>
+  <rel-button variant="primary">Save</rel-button>
+</rel-drawer-footer>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-drawer.ts, rel-drawer-footer.ts — do not edit; run readme-generate.mjs -->
+
+## Elements
+
+| Element | Class | Source |
+| --- | --- | --- |
+| `<rel-drawer>` | `RelDrawer` | `rel-drawer.ts` |
+| `<rel-drawer-footer>` | `RelDrawerFooter` | `rel-drawer-footer.ts` |
+
+## API
+
+### `<rel-drawer>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `open` | `boolean` | `false` | Whether the drawer is shown. Toggle it to open/close; every change fires `rel-open-change`. Reflected. |
+| `side` | `side` | `"bottom" \| "left" \| "right"` | `"bottom"` | Edge the panel slides in from. `bottom` is centred horizontally and supports the drag handle; `left`/`right` are full-height side panels. |
+| `dismissible` | `dismissible` | `boolean` | `true` | When false the close button is hidden and backdrop clicks / Escape are ignored (drag-to-close still works). |
+| `modal` | `modal` | `boolean` | `true` | Modal mode: renders the scrim, sets `role="dialog"` + `aria-modal`, traps Tab inside the panel and moves focus in on open. When false the panel is a `region` with no scrim and no focus trap. |
+| `closeOnBackdrop` | `close-on-backdrop` | `boolean` | `true` | Close when the scrim is clicked. Only effective while `dismissible` is true. |
+| `closeOnEscape` | `close-on-escape` | `boolean` | `true` | Close on the Escape key. Only effective while `dismissible` is true. |
+| `showHandle` | `show-handle` | `boolean` | `true` | Show the grab bar above the header. Only rendered when `side="bottom"` and `draggable` is true. |
+| `draggable` | `draggable` | `boolean` | `true` | Enable drag-to-close on the handle (pointer or touch). Bottom drawers only. |
+| `snapThreshold` | `snap-threshold` | `number` | `0.25` | Fraction (0–1) of the panel height the user must drag down before release closes the drawer; shorter drags snap back. |
+| `maxHeight` | `max-height` | `string` | `"80vh"` | Written to the panel as the `--drawer-max-height` custom property (any CSS length). No built-in rule reads it yet; use `--rel-drawer-height` to size a bottom drawer. |
+| `width` | `width` | `string` | `""` | Explicit panel width (any CSS length). Empty by default, which uses the per-side `--rel-drawer-width` default. |
+| `title` | `title` | `string` | `""` | Heading text (rendered as an `<h2>`, linked via `aria-labelledby`). |
+| `description` | `description` | `string` | `""` | Supporting text under the title (linked via `aria-describedby`). |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-open-change` | `{ open: true } / { open: false }` | bubbles / composed | Fired whenever `open` changes, from any cause (prop set, close button, backdrop, Escape, drag). Detail: `{ open: boolean }`. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Body content of the drawer |
+| `footer` | Actions row; rendered inside a `<rel-drawer-footer>` (right-aligned, 8px gap) |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `overlay` | The full-viewport scrim behind the panel |
+| `panel` | The sliding panel (role="dialog") |
+| `handle` | The drag-to-close grab bar (bottom drawers only) |
+| `header` | Header block holding title, description and close button |
+| `close-button` | The "X" close button |
+| `content` | Scrollable body wrapper around the default slot |
+| `footer` | Footer wrapper around the `footer` slot |
+
+### Tokens / CSS Variables
+
+#### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-drawer-height` | `var(--drawer-height, clamp(360px, 49vh, 600px))` | Panel height for `side="bottom"`; default `clamp(360px, 49vh, 600px)`. Left/right drawers are always full height |
+| `--rel-drawer-scrim-opacity` | `1` | Opacity of the scrim while open; default `1` |
+| `--rel-drawer-transition-duration` | `var(--drawer-transition-duration)` | Slide/scrim animation duration; default `0.3s` |
+| `--rel-drawer-transition-timing` | `var(--drawer-transition-timing)` | Slide/scrim animation easing; default `cubic-bezier(0.32, 0.72, 0, 1)` |
+| `--rel-drawer-width` | `var(--drawer-width, clamp(640px, 66vw, 952px))` | Panel width. Default `clamp(640px, 66vw, 952px)` for `side="bottom"`, `clamp(280px, 24vw, 420px)` for left/right. The `width` prop sets this on the panel and wins over a host value |
+
+### `<rel-drawer-footer>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| — | — | — | — | No public properties. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Footer actions (typically `<rel-button>`s) |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| — | None exposed. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The panel is `role="dialog"` with `aria-modal="true"` while `modal` is on; with `modal` off it becomes a `role="region"` without scrim or focus trap.
+- `aria-labelledby` points at the rendered `<h2>` when `title` is set, otherwise the panel carries `aria-label="Drawer"`; `aria-describedby` points at the description paragraph when `description` is set.
+- The close button is a real `<button>` with `aria-label="Close"`. It is rendered whenever `dismissible` is on.
+- Focus: on open in modal mode focus moves to the first focusable element inside the panel, or to the panel itself (`tabindex="-1"`). On close focus always returns to the element that was active before opening — resolved through shadow roots, so a `<rel-button>` opener gets focus back.
+- Body scroll is locked while open; the scrollbar width is added as body padding so the page does not shift.
+- The drag handle is pointer-only (`touch-action: none`); keyboard users close with `Escape` or the close button.
+- `prefers-reduced-motion: reduce` removes the slide/fade transitions and hides the closed panel outright.
+
+| Key | Action |
+| --- | --- |
+| `Escape` | Closes the drawer when `dismissible` and `close-on-escape` are on. |
+| `Tab` / `Shift+Tab` | Cycles focus inside the panel while `modal` is on (focus trap); wraps at either end. |
+
+## Notes / Edge Cases
+
+- Drag-to-close only exists for `side="bottom"` and only when `draggable` is on; the handle is additionally hidden when `show-handle` is off. Dragging is one-directional (down); release past `snap-threshold` × panel height closes, shorter drags snap back. The scrim fades in proportion to the drag. Drag still closes the drawer when `dismissible` is off.
+- `rel-open-change` is the only event; it fires for every `open` change including programmatic ones. The exported `DrawerCloseReason` type is used internally only — the event detail does not carry a reason.
+- Boolean props default to `true` (`dismissible`, `modal`, `close-on-backdrop`, `close-on-escape`, `show-handle`, `draggable`); an absent attribute keeps the default, so switch them off from JavaScript (`drawer.modal = false`).
+- `width` is written to the panel as an inline `--rel-drawer-width`, so it wins over a `--rel-drawer-width` set on the host. Leave it empty to use the per-side defaults.
+- `max-height` is written to the panel as `--drawer-max-height` but no rule reads it yet; size bottom drawers with `--rel-drawer-height` instead.
+- After a left/right drawer finishes sliding in, its `transform` is dropped so `position: fixed` descendants (select menus, popovers, tooltips, date pickers) are no longer clipped to the panel. Bottom drawers keep their transform because it centres them.
+- The footer wrapper (padding + top border) is always rendered, even when the `footer` slot is empty.
+- Legacy hook aliases still honoured: `--drawer-width`, `--drawer-height`, `--drawer-transition-duration` and `--drawer-transition-timing` are read as fallbacks of the `--rel-drawer-*` hooks. `--rel-drawer-scrim-opacity` has no legacy alias.