@reliability-design/web 1.4.6 → 1.4.7

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

@@ -1,102 +1,96 @@
-#rel-breadcrumbs
-
-## Overview
-A breadcrumb navigation component that displays a hierarchical path of pages. Features accessible markup, automatic last-item detection, built-in chevron separators, and proper ARIA attributes. Automatically styles the last item as the current page.
-
-## Usage
-```html
-<!-- Basic breadcrumb -->
-<rel-breadcrumbs id="breadcrumb1"></rel-breadcrumbs>
-<script>
-  const breadcrumb = document.getElementById('breadcrumb1');
-  breadcrumb.items = [
-    { label: 'Home', url: '/' },
-    { label: 'Products', url: '/products' },
-    { label: 'Electronics', url: '/products/electronics' },
-    { label: 'Laptops' } // Last item has no URL
-  ];
-</script>
-
-<!-- Simple path -->
-<rel-breadcrumbs id="breadcrumb2"></rel-breadcrumbs>
-<script>
-  document.getElementById('breadcrumb2').items = [
-    { label: 'Dashboard', url: '/dashboard' },
-    { label: 'Settings' }
-  ];
-</script>
-
-<!-- Deep nested path -->
-<rel-breadcrumbs id="breadcrumb3"></rel-breadcrumbs>
-<script>
-  document.getElementById('breadcrumb3').items = [
-    { label: 'Docs', url: '/docs' },
-    { label: 'Components', url: '/docs/components' },
-    { label: 'Navigation', url: '/docs/components/navigation' },
-    { label: 'Breadcrumbs' }
-  ];
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `items` | `BreadcrumbItem[]` | `[]` | Array of breadcrumb items (see BreadcrumbItem interface below) |
-
-### BreadcrumbItem Interface
-```typescript
-interface BreadcrumbItem {
-  label: string;   // Display text
-  url?: string;    // Optional link URL (omit for current/last page)
-}
-```
-
-## Events
-None.
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-md-regular-font-size` - Font size
-- `--rel-fonts-weight-body-medium` - Font weight for links
-- `--rel-fonts-weight-body-semibold` - Font weight for current page
-
-### Color Tokens
-- `--rel-text-default` - Base text color
-- `--rel-text-label` - Link and current page text color
-- `--rel-bg-info` - Link hover color and focus outline
-
-## Accessibility
-- Uses semantic `<nav>` with `aria-label="Breadcrumb"`
-- Uses `<ol>` ordered list for proper structure
-- Last item has `aria-current="page"` to indicate current page
-- Links have focus visible states with blue outline
-- Chevron separator has `aria-hidden="true"` to hide from screen readers
-
-### Keyboard Interactions
-- `Tab` - Navigate through breadcrumb links
-- `Enter` - Follow focused link
-
-### Focus Behavior
-- Links show 2px blue outline with 2px offset when focused
-- Border radius applied to focus outline for visual consistency
-
-## Notes / Edge Cases
-- The last item in `items` array is automatically treated as the current page
-- Last item renders as a `<span class="current">` instead of `<a>`, even if it has a `url`
-- Chevron separators (SVG chevron-right arrows) appear between all items except after the last one
-- Chevrons are 16px × 16px with 10px horizontal margins
-- Chevron color inherits `currentColor` from parent
-- Links have `text-decoration: none` by default, `underline` on hover
-- The current page label is bold and not clickable (`cursor: default`)
-- The component is `display: block` and takes full width
-- The ordered list uses `flex-wrap: wrap` to handle overflow gracefully
+# rel-breadcrumbs
+
+Breadcrumb trail (element `<rel-breadcrumbs>`, folder `rel-breadcrumb`): a `<nav aria-label="Breadcrumb">` ordered list built from an `items` array, with chevron separators and the last entry rendered as the non-link current page. Use it to show where the current page sits in a hierarchy and to jump back up it; do not use it as primary navigation or for a single-level site.
+
+## Usage
+
+```html
+<!-- Basic trail: every item but the last is a link -->
+<rel-breadcrumbs id="trail"></rel-breadcrumbs>
+<script>
+  document.getElementById('trail').items = [
+    { label: 'Home', url: '/' },
+    { label: 'Products', url: '/products' },
+    { label: 'Electronics', url: '/products/electronics' },
+    { label: 'Laptops' } // current page — no url needed
+  ];
+</script>
+
+<!-- Two levels -->
+<rel-breadcrumbs id="short"></rel-breadcrumbs>
+<script>
+  document.getElementById('short').items = [
+    { label: 'Dashboard', url: '/dashboard' },
+    { label: 'Settings' }
+  ];
+</script>
+
+<!-- Restyle the current-page text through its part -->
+<style>
+  .muted::part(label) {
+    color: gray;
+  }
+</style>
+<rel-breadcrumbs class="muted" id="muted"></rel-breadcrumbs>
+<script>
+  document.getElementById('muted').items = [
+    { label: 'Docs', url: '/docs' },
+    { label: 'Components', url: '/docs/components' },
+    { label: 'Breadcrumbs' }
+  ];
+</script>
+```
+
+The `BreadcrumbItem` shape is `{ label: string; url?: string }`; the type is exported from the package.
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-breadcrumb.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `items` | `BreadcrumbItem[]` | `[]` | Ordered trail, root first: `{ label: string; url?: string }[]`. Items with a `url` render as links except the last one, which is always the current page (and never a link). Set as a property — arrays do not survive attribute serialisation. |
+
+## 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 `<nav>` landmark wrapping the ordered list. |
+| `label` | The non-link current-page text (`aria-current="page"`), also used for any item without a `url`. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- Semantic `<nav aria-label="Breadcrumb">` landmark (the `base` part) containing an `<ol>`, so the trail is announced as an ordered list within a named navigation region.
+- The last item is a `<span aria-current="page">` (the `label` part), never a link, so the current page is identified without being actionable.
+- Chevron separators are inline SVGs with `aria-hidden="true"`.
+- Links show a 2px focus outline with 2px offset on `:focus-visible`.
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move between the breadcrumb links |
+| `Enter` | Follow the focused link (native anchor behaviour) |
+
+## Notes / Edge Cases
+
+- **The last item is always the current page**, even if it has a `url` — it renders as text, not a link. Any earlier item *without* a `url` also renders as text (and reuses the `label` part and `aria-current="page"`, so give every ancestor a `url`).
+- `items` must be assigned as a property (it is an array); setting an `items` attribute in HTML does not work.
+- Separators are 16px chevrons with 10px horizontal margins inheriting `currentColor`; the list wraps onto new lines when it runs out of width.
+- Links are plain anchors: navigation happens natively and no custom event is emitted. Intercept `click` on the host if you route client-side.

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

@@ -1,130 +1,160 @@
-# rel-button
-
-## Overview
-A versatile button component with six variants (default, primary, secondary, text, link, icon), three tone options, three sizes, and configurable border radius. Features hover, active, and focus states with smooth transitions. Slots support custom content including text, icons, or combinations.
-
-## Usage
-```html
-<!-- Basic variants -->
-<rel-button variant="default">Default Button</rel-button>
-<rel-button variant="primary">Primary Button</rel-button>
-<rel-button variant="secondary">Secondary Button</rel-button>
-<rel-button variant="text">Text Button</rel-button>
-<rel-button variant="link">Link Style</rel-button>
-
-<!-- Icon button -->
-<rel-button variant="icon">⚙️</rel-button>
-
-<!-- Tones (affect color scheme) -->
-<rel-button variant="primary" tone="default">Default Tone</rel-button>
-<rel-button variant="primary" tone="critical">Critical Action</rel-button>
-<rel-button variant="primary" tone="success">Success Action</rel-button>
-
-<!-- Sizes -->
-<rel-button size="small">Small</rel-button>
-<rel-button size="medium">Medium</rel-button>
-<rel-button size="large">Large</rel-button>
-
-<!-- Border radius options -->
-<rel-button border="corner-radius">Rounded</rel-button>
-<rel-button border="small-corner-radius">Small Rounded</rel-button>
-<rel-button border="no-corner-radius">Sharp</rel-button>
-
-<!-- Disabled -->
-<rel-button disabled>Disabled Button</rel-button>
-
-<!-- With icon and text (using slot) -->
-<rel-button variant="primary">
-  <svg width="16" height="16" viewBox="0 0 16 16"><path d="M8 0l3 6h6l-5 4 2 6-6-4-6 4 2-6-5-4h6z"/></svg>
-  Save
-</rel-button>
-
-<!-- Listen for click -->
-<rel-button id="actionBtn" variant="primary">Click Me</rel-button>
-<script>
-  document.getElementById('actionBtn').addEventListener('click', () => {
-    console.log('Button clicked');
-  });
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `"default" \| "primary" \| "secondary" \| "text" \| "link" \| "icon"` | `"default"` | Visual style variant |
-| `tone` | `"default" \| "critical" \| "success"` | `"default"` | Color tone (affects default/primary variants) |
-| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Button size |
-| `border` | `"corner-radius" \| "small-corner-radius" \| "no-corner-radius"` | `"corner-radius"` | Border radius style |
-| `disabled` | `boolean` (reflected) | `false` | Disables interaction and applies disabled styling |
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `click` | `MouseEvent` | Re-dispatched from the internal button (for framework compatibility) |
-
-## Slots
-| Slot | Description |
-|------|-------------|
-| (default) | Button content (text, icons, or combination) |
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-fonts-weight-body-semibold` - Font weight
-- `--rel-body-sm-regular-font-size`, `--rel-body-md-regular-font-size`, `--rel-body-xl-regular-font-size` - Font sizes for sizes
-
-### Spacing Tokens
-- `--rel-spacing-2xs` - Internal gap between elements
-- `--rel-spacing-md`, `--rel-spacing-lg`, `--rel-spacing-xl` - Horizontal padding by size
-
-### Color Tokens (by variant/tone)
-- **default + default tone**: `--rel-text-default` (bg), `--rel-bg-surface` (text)
-- **default + critical tone**: `--rel-bg-danger` (bg), `--rel-bg-surface` (text)
-- **default + success tone**: `--rel-text-success` (bg), `--rel-bg-surface` (text)
-- **primary + default tone**: `--rel-bg-brand` (bg), `--rel-text-default` (text)
-- **primary + critical tone**: `--rel-bg-danger` (bg), `--rel-bg-surface` (text)
-- **primary + success tone**: `--rel-text-success` (bg), `--rel-bg-surface` (text)
-- **secondary**: `--rel-bg-surface` (bg), `--rel-text-default` (text + border)
-- **text**: transparent (bg), `--rel-text-default` (text)
-- **link**: transparent (bg), `--rel-bg-info` (text), underlined
-- **icon**: `--rel-bg-surface-elevated` (bg), `--rel-text-default` (text), circular (40px × 40px)
-- **disabled**: `--rel-border-default` (bg), `--rel-text-disabled` (text)
-
-### Border Tokens
-- `--rel-border-radius-full-rounded` - Large corner radius
-- `--rel-border-radius-sm` - Small corner radius
-- `--rel-border-radius-square` - No corner radius
-
-## Accessibility
-- Uses native `<button>` element for proper semantics
-- `aria-disabled` attribute set on disabled buttons
-- Focus visible state with blue outline
-- Keyboard accessible (Space/Enter activation)
-
-### Keyboard Interactions
-- `Tab` - Focus the button
-- `Space/Enter` - Activate the button
-
-### Focus Behavior
-- Blue 2px outline with 2px offset on focus-visible
-- Focus outline works across all variants
-
-## Notes / Edge Cases
-- **Icon variant** is always circular (40px × 40px), ignores size property, and has no padding
-- **Link variant** has `text-decoration: underline`
-- **Secondary variant** includes a 1px border matching the text color
-- Hover effect applies `filter: brightness(0.92)` to darken
-- Active (pressed) effect applies `transform: scale(0.97)` for tactile feedback
-- Disabled buttons have `pointer-events: none` and use `!important` to override theming
-- The component re-dispatches click events to ensure framework compatibility (e.g., Angular)
-- Clicking a disabled button prevents default and stops propagation
-- Size variants affect height (32px/40px/48px) and horizontal padding
-- The button has `display: inline-flex` with `align-items: center` and `justify-content: center`
-- Internal gap of `var(--rel-spacing-2xs)` allows icons + text combinations
-- Transitions are `0.15s ease` for all visual changes
+# rel-button
+
+Action button implementing the Figma "Button" component: a native `<button>` with the Figma **Style** (`variant`), **Tone** (`tone`) and **Size** axes, an independent **Icon Only** mode, a **Loading** state and an optional corner badge. Use it for every clickable action (submit, confirm, open, delete). Do not use it for navigation to another page — use a link instead.
+
+## Usage
+
+```html
+<!-- Styles (Figma "Style") -->
+<rel-button variant="primary">Primary</rel-button>
+<rel-button variant="secondary">Secondary</rel-button>
+<rel-button variant="ghost">Ghost</rel-button>
+<rel-button variant="link">Link style</rel-button>
+<rel-button variant="default">Neutral fill</rel-button>
+<div style="background: #1f2937; padding: 8px;">
+  <rel-button variant="static">Static (on dark surfaces)</rel-button>
+</div>
+
+<!-- Tones (Figma "Tone") -->
+<rel-button variant="primary" tone="brand">Save</rel-button>
+<rel-button variant="primary" tone="neutral">Cancel</rel-button>
+<rel-button variant="primary" tone="destructive">Delete</rel-button>
+<rel-button variant="secondary" tone="destructive">Remove</rel-button>
+<rel-button variant="ghost" tone="destructive">Discard</rel-button>
+
+<!-- Sizes: 32 / 40 / 48px -->
+<rel-button size="small">Small</rel-button>
+<rel-button size="medium">Medium</rel-button>
+<rel-button size="large">Large</rel-button>
+
+<!-- Corner radius -->
+<rel-button border="corner-radius">Pill</rel-button>
+<rel-button border="small-corner-radius">Small radius</rel-button>
+<rel-button border="no-corner-radius">Square</rel-button>
+
+<!-- Icon + label, and icon-only (needs an accessible name) -->
+<rel-button variant="primary">
+  <rel-icon name="plus"></rel-icon>
+  Add item
+</rel-button>
+<rel-button variant="secondary" icon-only aria-label="Settings">
+  <rel-icon name="settings"></rel-icon>
+</rel-button>
+<rel-button variant="ghost" icon-only size="small" aria-label="Close">
+  <rel-icon name="x"></rel-icon>
+</rel-button>
+
+<!-- States -->
+<rel-button variant="primary" loading>Saving</rel-button>
+<rel-button variant="primary" disabled>Unavailable</rel-button>
+
+<!-- Corner badges -->
+<rel-button variant="secondary" badge="3">Inbox</rel-button>
+<rel-button variant="ghost" icon-only badge-dot aria-label="Notifications">
+  <rel-icon name="bell"></rel-icon>
+</rel-button>
+
+<!-- Listen for clicks (native click bubbles through the shadow root) -->
+<rel-button id="save" variant="primary">Save</rel-button>
+<script>
+  document.getElementById('save').addEventListener('click', () => {
+    console.log('saved');
+  });
+</script>
+
+<!-- Per-instance minimum width -->
+<rel-button variant="primary" style="--rel-button-min-width: 160px;">Wide</rel-button>
+```
+
+### Deprecated aliases
+
+```html
+<!-- Legacy Style spellings — still rendered identically, prefer the canonical names -->
+<rel-button variant="outline">Outline</rel-button>   <!-- → variant="secondary" -->
+<rel-button variant="text">Text</rel-button>         <!-- → variant="ghost" -->
+<rel-button variant="icon" aria-label="Settings">    <!-- → icon-only + a variant -->
+  <rel-icon name="settings"></rel-icon>
+</rel-button>
+
+<!-- Legacy Tone spellings — each logs once per page:
+     [rel-button] "tone="critical"" is deprecated and will be removed in 3.0 — use "tone="destructive"" instead. -->
+<rel-button variant="primary" tone="critical">Delete</rel-button> <!-- → tone="destructive" -->
+<rel-button variant="primary" tone="danger">Delete</rel-button>   <!-- → tone="destructive" -->
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-button.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `variant` | `"default" \| "primary" \| "secondary" \| "text" \| "link" \| "icon" \| "static" \| "outline" \| "ghost"` | `"default"` | Style axis (Figma "Style"). Canonical: `default` (legacy neutral fill), `primary`, `secondary` (outlined), `ghost` (text-only), `link` (underlined inline text), `static` (transparent, static-light label for dark/colored surfaces). Deprecated aliases still accepted: `outline` = secondary, `text` = ghost, and `icon` (pre-2.0 40px circular icon button — use `icon-only` with a style instead). |
+| `tone` | `tone` | `"default" \| "primary" \| "secondary" \| "critical" \| "success" \| "neutral" \| "brand" \| "danger" \| "destructive"` | `"default"` | Tone axis (Figma "Tone"). Canonical: `neutral` (= `default`), `brand` (= `primary`), `destructive`. Deprecated aliases `critical` and `danger` map to destructive and log a one-time console notice. `secondary` and `success` are legacy extras with no Figma counterpart (secondary only affects the legacy `icon` variant). |
+| `iconOnly` | `icon-only` | `boolean` | `false` | Figma "Type=Icon Only": renders a square button (32/40/48px per `size`) of the current style and tone with no padding or min-width. Composes with every `variant`; slot a single `rel-icon` and set `aria-label`. Reflected. |
+| `loading` | `loading` | `boolean` | `false` | Figma "State=Loading": replaces the label with a spinner (`indicator` part), sets `aria-busy`, and blocks pointer and programmatic clicks. The button keeps its width. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Figma "Size": `small` = 32px, `medium` = 40px, `large` = 48px height, with matching padding, typography and minimum width. |
+| `border` | `border` | `"corner-radius" \| "small-corner-radius" \| "no-corner-radius"` | `"corner-radius"` | Corner treatment: `corner-radius` = fully rounded pill, `small-corner-radius` = small radius token, `no-corner-radius` = square corners. |
+| `disabled` | `disabled` | `boolean` | `false` | Figma "State=Disabled": dims the button to 50% opacity, flattens filled styles to the disabled fill, shows a `not-allowed` cursor and swallows every click (including programmatic `.click()`). Reflected. |
+| `ariaLabel` | `aria-label` | `string \| null` | `null` | Accessible name forwarded to the inner native `<button>`. Required for `icon-only` buttons, whose slotted icon has no visible text. |
+| `badge` | `badge` | `string` | `""` | Text for a small `rel-badge` anchored to the top-right corner (e.g. "3", "999+"). Empty string renders no badge. Ignored when `badge-dot` is set. |
+| `badgeDot` | `badge-dot` | `boolean` | `false` | Renders a small dot badge in the top-right corner instead of a numbered badge; takes precedence over `badge`. The dot is inset 2px from the corner so it lands on a circular icon button's edge. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Button content: label text, a `rel-icon`, or icon + text (kept on one line with the size's gap). |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The inner native `<button>` element (padding, min-width, fill, border, focus ring). |
+| `indicator` | The loading spinner, rendered only while `loading` is set. |
+
+## 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-button-min-width` | `80px` | Overrides the per-size minimum width (Figma small/medium/large = 80/100/120px, ghost small = 56px). Ignored by `icon-only` and `link`. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- Renders a native `<button>` (the `base` part), so it is focusable, announced as a button and activated with the keyboard without extra work.
+- `aria-disabled` mirrors `disabled`; `aria-busy` mirrors `loading`. The spinner is `aria-hidden`, and the label stays in the DOM (visually hidden) while loading, so the accessible name does not change.
+- `aria-label` is forwarded to the inner button. Always set it on `icon-only` buttons and on the legacy `icon` variant — a slotted icon has no text.
+- Disabled and loading buttons swallow clicks in the capture phase on the host, so `el.click()` and delegated listeners never fire.
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move focus to / from the button |
+| `Enter` / `Space` | Activate (native button behaviour) |
+
+Focus: `:focus-visible` shows the shared 2px focus outline plus inner/outer halo on every style except `link`, which shows a 2px focus-coloured underline bar and the hover label colour instead (still a visible indicator per WCAG 2.4.7). Pressing scales the button to 97%; the spinner slows to 2s under `prefers-reduced-motion: reduce`.
+
+## Notes / Edge Cases
+
+- **Events.** The element dispatches no custom events. The native `click` is `composed`, so a listener on `<rel-button>` (or an ancestor) receives exactly one event per activation — do not re-dispatch it.
+- **Minimum widths** come from the Figma master: small/medium/large = 80/100/120px, ghost small = 56px. `link` has no minimum, `icon-only` is a fixed square (32/40/48px) and the legacy `icon` variant is always a 40px circle regardless of `size`. Override per instance with `--rel-button-min-width`.
+- **Legacy `icon` variant vs `icon-only`.** `variant="icon"` keeps its pre-2.0 look (40px circle, tone-driven fill, `tone="secondary"` gives it an outline) and ignores `size` and `border`. `icon-only` is an axis that composes with any style and size — prefer it.
+- **`tone` on `secondary` / `ghost` / `link`** changes the label, border or text colour only; the fill stays on the surface. The destructive outline border is deliberately subtle at rest and only goes solid on hover/pressed, matching Figma.
+- **`static`** is a neutral-only style meant for coloured or dark backgrounds; other tones have no static treatment.
+- **`success`** is a legacy tone without a Figma counterpart; it renders a green fill/outline/ghost tint but is not part of the current spec.
+- **Badges** render a small `rel-badge` positioned outside the button's box (numbered) or 2px inside the corner (dot); give the button room in tight layouts. `badge-dot` wins when both are set.
+- **Disabled styling**: only filled styles (`default`, `primary`, `icon`) flatten to the neutral disabled fill; `secondary`, `ghost`, `link` and `static` keep their shape at 50% opacity so they still read as their own style.