@reliability-design/web 1.4.6 → 1.4.8

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

@@ -1,121 +1,138 @@
-# rel-chip
-
-## Overview
-A compact chip component for displaying tags, labels, or selected options. Supports multiple color tones, avatar/icon decorations, outline variants, and removable functionality. Automatically hides when removed via the `removed` reflected attribute.
-
-## Usage
-```html
-<!-- Basic chip -->
-<rel-chip label="Active"></rel-chip>
-
-<!-- Colored tones -->
-<rel-chip label="Info" tone="blue"></rel-chip>
-<rel-chip label="Warning" tone="yellow"></rel-chip>
-<rel-chip label="Error" tone="red"></rel-chip>
-<rel-chip label="Success" tone="green"></rel-chip>
-
-<!-- Outline variant -->
-<rel-chip label="Outline Style" tone="blue" outline></rel-chip>
-
-<!-- Small size variant -->
-<rel-chip label="Small" size="sm" tone="blue"></rel-chip>
-
-<!-- With avatar -->
-<rel-chip id="avatarChip" label="John Doe" avatar="./user.jpg"></rel-chip>
-
-<!-- With leading icon (SVG string via JS) -->
-<rel-chip id="iconChip" label="Tagged"></rel-chip>
-<script>
-  const chip = document.getElementById('iconChip');
-  chip.leadingIcon = '<svg viewBox="0 0 16 16"><path d="M8 0l2 6h6l-5 4 2 6-5-4-5 4 2-6-5-4h6z"/></svg>';
-</script>
-
-<!-- Removable chip -->
-<rel-chip id="removableChip" label="Removable" removable></rel-chip>
-<script>
-  const removableChip = document.getElementById('removableChip');
-  removableChip.addEventListener('removed', () => {
-    console.log('Chip was removed');
-  });
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | `"Label"` | Text displayed on the chip |
-| `size` (reflected) | `"sm" \| "md"` | `"md"` | Chip size variant |
-| `tone` | `"default" \| "blue" \| "yellow" \| "red" \| "green"` | `"default"` | Color tone variant |
-| `leadingIcon` | `string` | - | SVG or HTML string for leading icon |
-| `trailingIcon` | `string` | - | SVG or HTML string for trailing icon |
-| `avatar` | `string` | - | Image URL for avatar (circular image before label) |
-| `removable` | `boolean` | `false` | Shows a remove button (✕) |
-| `outline` | `boolean` | `false` | Applies outline styling (transparent background) |
-| `removed` | `boolean` (reflected) | `false` | When true, component hides via `:host([removed])` |
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `removed` | None | Fired when the remove button is clicked (sets `removed` to true) |
-
-## 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
-
-### Spacing Tokens
-- `--rel-spacing-2xs` - Padding and internal gaps
-- `--rel-spacing-sm` - Horizontal padding
-- `--rel-spacing-3xs` - Remove button margin
-
-### Color Tokens (by tone)
-- **default**: `--rel-border-default` (background), `--rel-text-default` (text)
-- **blue**: `--rel-text-info` (background), `--rel-bg-surface` (text)
-- **yellow**: `--rel-bg-warning` (background), `--rel-text-default` (text)
-- **red**: `--rel-text-danger` (background), `--rel-bg-surface` (text)
-- **green**: `--rel-text-success` (background), `--rel-bg-surface` (text)
-
-### Border & Shadow Tokens
-- `--rel-border-radius-full-rounded` - Border radius (pill shape)
-- `--rel-stroke-sm` - Border width (used in outline mode)
-- `--rel-shadows-shadow-100` - Hover shadow
-- `--rel-bg-info` - Focus outline color
-
-## Accessibility
-- Uses `role="button"` and `tabindex="0"` on the main chip element
-- `aria-label` set to the chip's label
-- Remove button has proper `aria-label="Remove {label}"`
-- Focus visible states on chip and remove button with distinct outlines
-- Remove button focus uses white outline for contrast against colored backgrounds
-
-### Keyboard Interactions
-- `Tab` - Focus the chip (or remove button if present)
-- No built-in activation behavior on Enter/Space (purely informational/decorative)
-
-### Focus Behavior
-- Chip focus: 2px blue outline with 2px offset
-- Remove button focus: 2px white outline with 1px offset
-
-## Notes / Edge Cases
-- **Size variants**:
-  - **md** (default): `--rel-body-md-regular-font-size` text, `--rel-spacing-2xs`/`--rel-spacing-xs` padding, 20px × 20px avatar, 16px × 16px icons
-  - **sm**: `--rel-body-sm-regular-font-size` text, `--rel-spacing-3xs`/`--rel-spacing-2xs` padding, 16px × 16px avatar, 12px × 12px icons
-- Icons (`leadingIcon`, `trailingIcon`) must be passed as raw HTML/SVG strings via JavaScript (see examples)
-- Icons are injected using `renderIcon()` which creates a template element and clones the content
-- Avatar images are 20px × 20px circular (`border-radius: 50%`, `object-fit: cover`)
-- When `removed` is set to `true`, the component applies `display: none` via `:host([removed])`
-- `removed` is a reflected attribute, meaning it appears in the HTML when true
-- Clicking the remove button stops propagation to prevent triggering chip-level click handlers
-- **Outline mode** removes the background color but keeps the same text color
-- Hover effect applies `filter: brightness(0.92)` and box-shadow
-- The component is `display: inline-block`, so chips flow inline by default
+# rel-chip
+
+`<rel-chip>` is the compact chip from the Figma "Chip" component: a short label with tone × variant colouring, an optional leading icon or initials avatar, an optional trailing icon, a remove control and opt-in drag-and-drop. Use it for tags, active filters, selected values in a multi-select and small status labels. Do not use it as a general button (use `rel-button`) or for status counts (use `rel-badge`); for long-lived toggles use `rel-switch` or `rel-checkbox`.
+
+## Usage
+
+```html
+<!-- Basic chip (tone="neutral" variant="fill" size="medium" border="default") -->
+<rel-chip label="Active"></rel-chip>
+
+<!-- Tones -->
+<rel-chip label="Info" tone="info"></rel-chip>
+<rel-chip label="Warning" tone="warning"></rel-chip>
+<rel-chip label="Error" tone="destructive"></rel-chip>
+<rel-chip label="Success" tone="success"></rel-chip>
+
+<!-- Subtle variant: tinted background, tone-coloured text -->
+<rel-chip label="Subtle" tone="info" variant="subtle"></rel-chip>
+
+<!-- Sizes -->
+<rel-chip label="Small" size="small"></rel-chip>
+<rel-chip label="Medium" size="medium"></rel-chip>
+<rel-chip label="Large" size="large"></rel-chip>
+
+<!-- Deprecated aliases — these still render, but prefer the canonical spellings above.
+     tone="danger" is an alias of tone="destructive" and logs a one-time console notice.
+     size="sm" / "md" / "lg" are alternative spellings (NOT deprecated, no notice). -->
+<rel-chip label="Error" tone="danger"></rel-chip>
+<rel-chip label="Small" size="sm"></rel-chip>
+
+<!-- Fully rounded corners -->
+<rel-chip label="Rounded" border="rounded"></rel-chip>
+
+<!-- Leading / trailing icons (icon dictionary names, rendered via <rel-icon>) -->
+<rel-chip label="Settings" leading-icon="settings"></rel-chip>
+<rel-chip label="Next" trailing-icon="chevron-right"></rel-chip>
+
+<!-- Initials avatar (takes precedence over leading-icon) -->
+<rel-chip label="John Doe" avatar="JD"></rel-chip>
+
+<!-- Removable chip -->
+<rel-chip id="removableChip" label="Removable" removable></rel-chip>
+<script>
+  document.getElementById("removableChip").addEventListener("removed", () => {
+    console.log("Chip was removed");
+  });
+</script>
+
+<!-- Draggable chip: native drag-and-drop plus Left/Right arrow reordering -->
+<rel-chip id="dragChip" label="Reorder me" draggable-chip></rel-chip>
+<script>
+  document.getElementById("dragChip").addEventListener("chip-move", (e) => {
+    console.log("move", e.detail.direction); // -1 = left, 1 = right
+  });
+</script>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-chip.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `"Label"` | Text shown in the chip; also its accessible name and the drag payload. |
+| `tone` | `tone` | `"neutral" \| "destructive" \| "warning" \| "success" \| "info" \| "danger"` | `"neutral"` | Colour tone (Figma Tone): `neutral`, `destructive`, `warning`, `success` or `info`. Combined with `variant`. `"danger"` is a deprecated alias of `"destructive"`: it keeps working, logs a one-time console notice, and is normalised to `"destructive"` on the property and the reflected attribute. Reflected. |
+| `variant` | `variant` | `"fill" \| "subtle" \| "primary" \| "secondary"` | `"fill"` | Emphasis (Figma Style): `fill` = solid tone background, `subtle` = tinted background with tone-coloured text. Figma's own spellings `primary` and `secondary` are accepted and normalised to `fill` / `subtle`. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Height scale (Figma Size): `small` 24px / body-sm, `medium` 28px / body-md, `large` 32px / body-lg. Icon size follows (12 / 14 / 16px). `sm` / `md` / `lg` are accepted and normalised to the full words. Reflected. |
+| `border` | `border` | `"default" \| "rounded"` | `"default"` | Corner shape (Figma Border): `default` = 4px radius, `rounded` = fully rounded with 12px horizontal padding. Reflected. |
+| `leadingIcon` | `leading-icon` | `string` | `undefined` | Icon name from the generated icon dictionary (e.g. "settings") — rendered via <rel-icon> before the label. Ignored when `avatar` is set. |
+| `trailingIcon` | `trailing-icon` | `string` | `undefined` | Icon name from the generated icon dictionary, rendered after the label. |
+| `avatar` | `avatar` | `string` | `undefined` | Initials text for the avatar (e.g. "JD"), rendered as a `<rel-avatar type="text">` before the label. Mutually exclusive with leadingIcon (avatar wins). |
+| `removable` | `removable` | `boolean` | `false` | Shows a remove (close) button after the label; clicking it sets `removed` and fires `removed`. |
+| `removed` | `removed` | `boolean` | `false` | `true` once the chip has been removed — the host is hidden via `:host([removed])`. Reflected so CSS and Angular can see it; reset to `false` to show the chip again. Reflected. |
+| `draggableChip` | `draggable-chip` | `boolean` | `false` | Opt-in native drag-and-drop: sets `draggable="true"` on the host, shows the Figma "Dragged" state during a real drag gesture, and makes Left/Right arrow keys fire `chip-move`. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `chip-move` | `{ direction: e.key === "ArrowLeft" ? -1 : 1 }` | bubbles / composed | Fired on Left/Right arrow keys when `draggable-chip` is set — the keyboard alternative to drag-and-drop; the container should reorder the chip. Detail: `{ direction: -1 \| 1 }` (-1 = left, 1 = right). |
+| `removed` | — | bubbles / composed | Fired when the chip is removed via its remove button or Delete/Backspace (after `removed` is set to `true`). No detail. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The chip body (`.chip`) that carries size, tone, variant and border styling |
+| `icon` | The leading `<rel-icon>` (rendered only when `leading-icon` is set and no avatar) |
+| `label` | The label text |
+
+## 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-chip-focus-ring` | `var(--rel-border-focus)` | Colour of the keyboard focus outline; default `var(--rel-border-focus)` |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The chip body is a `<span role="button" tabindex="0">` whose `aria-label` is the `label` text. The shadow root uses `delegatesFocus`, so calling `focus()` on the host focuses that inner span.
+- The remove control is a real `<button>` labelled `Remove {label}`; it is a second Tab stop after the chip body.
+- Removing a chip (button or keyboard) calls the shared `announce()` helper with `"{label} removed"`, so screen readers hear the removal even though the chip disappears.
+- Icons and the avatar are decorative; the accessible name comes only from `label`.
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Focus the chip body, then the remove button (when `removable`) |
+| `Enter` / `Space` | Re-dispatches a `click` on the host so consumer `click` handlers run |
+| `Delete` / `Backspace` | Removes the chip when `removable` (sets `removed`, fires `removed`) |
+| `ArrowLeft` / `ArrowRight` | Fires `chip-move` with `direction: -1` / `1` when `draggable-chip` is set |
+
+Focus is shown as a 1.5px outline in `--rel-chip-focus-ring` (defaults to `--rel-border-focus`) around the whole chip, plus an inner `--rel-border-focus-inner` ring, only for keyboard focus (`:focus-visible`). The remove button gets its own `currentColor` outline.
+
+## Notes / Edge Cases
+
+- `avatar` and `leading-icon` are mutually exclusive: when both are set the avatar wins and a console warning is logged. The avatar is a `rel-avatar type="text"` sized to fill the chip's content box — 16 / 20 / 24px for `sm` / `md` / `lg`, driven through `--rel-avatar-size` rather than the avatar's own `size` presets (the small chip needs 16px, below the 20px `xs` floor).
+- The trailing icon has no CSS part; only the leading icon is exposed as `icon`.
+- The remove `✕` is drawn at the same size as the leading/trailing icons (12 / 14 / 16px) and in the same colour as the label — it carries no opacity dulling, so it keeps the label's contrast ratio on the `subtle` tones.
+- `border="rounded"` also widens the horizontal padding to 12px at every size, per the Figma spec.
+- `removed` is reflected: once `true` the host is `display: none` via `:host([removed])`. Set it back to `false` to show the chip again. Clicking the remove button stops propagation, so chip-level `click` handlers do not fire on removal.
+- `draggable-chip` sets the native `draggable="true"` attribute on the host and puts the label in `dataTransfer` as `text/plain`. During a real drag the host carries a `dragging` attribute that maps to the Figma "Dragged" state; the same look is used for `:active`. The component does not reorder anything itself — the container must handle `drop` / `chip-move`.
+- The remove button has no hover state of its own; the hover/pressed colours belong to the whole chip (per-tone action tokens).
+- The host is `display: inline-flex` with `flex: 0 0 auto`, so chips flow inline and never stretch in a flex row.

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

@@ -1,99 +1,107 @@
-# rel-container
-
-## Overview
-A versatile container component providing configurable padding, background colors, and optional shadow. Ideal for wrapping content sections with consistent spacing and theming.
-
-## Usage
-```html
-<!-- Default container (white background, medium padding) -->
-<rel-container>
-  <h2>Section Title</h2>
-  <p>Content goes here</p>
-</rel-container>
-
-<!-- Light background with small padding -->
-<rel-container background="light" padding="sm">
-  <p>Compact section with light background</p>
-</rel-container>
-
-<!-- Large padding with shadow -->
-<rel-container padding="lg" shadow>
-  <h1>Hero Section</h1>
-  <p>With shadow elevation</p>
-</rel-container>
-
-<!-- Transparent background -->
-<rel-container background="none">
-  <div>Content with transparent background</div>
-</rel-container>
-
-<!-- All options combined -->
-<rel-container background="white" padding="md" shadow>
-  <h3>Card-like Container</h3>
-  <p>White background, medium padding, with shadow</p>
-</rel-container>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `padding` | `"sm" \| "md" \| "lg"` | `"md"` | Padding size variant |
-| `shadow` | `boolean` | `false` | Enable box shadow |
-| `background` | `"light" \| "white" \| "none"` | `"white"` | Background color variant |
-
-## Events
-None.
-
-## Slots
-| Slot | Description |
-|------|-------------|
-| (default) | Container content (any HTML elements) |
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Color Tokens
-- `--rel-bg-surface` - White background color
-- `--rel-bg-surface-elevated` - Light background color
-
-### Shadow Tokens
-- `--rel-shadows-shadow-300` - Shadow when `shadow` is true
-
-### Border Tokens
-- `--rel-border-radius-sm` - Container border radius
-
-### Spacing Tokens
-- `--rel-spacing-xs` - Small padding
-- `--rel-spacing-md` - Medium padding
-- `--rel-spacing-2xl` - Large padding
-
-## Accessibility
-- Purely presentational container, no specific accessibility features
-- Ensure slotted content includes proper semantic HTML
-
-### Keyboard Interactions
-- None (purely presentational container)
-
-### Focus Behavior
-- No specific focus handling
-
-## Notes / Edge Cases
-- **Padding variants**:
-  - **sm**: Uses `--rel-spacing-xs`
-  - **md**: Uses `--rel-spacing-md`
-  - **lg**: Uses `--rel-spacing-2xl`
-  
-- **Background variants**:
-  - **white**: White background (`--rel-bg-surface`)
-  - **light**: Light gray background (`--rel-bg-surface-elevated`)
-  - **none**: Transparent background
-
-- The component is `display: block` and `width: 100%` with `box-sizing: border-box`
-- All styles are applied to an internal `.reliability-container` div
-- The border-radius is always applied regardless of background variant
-- The shadow is applied via the `--rel-shadows-shadow-300` token when `shadow` is true
-- Slotted content inherits the padding and background from the container
+# rel-container
+
+`<rel-container>` is the Figma "Container" surface block: a full-width, rounded wrapper with a `surface` fill (`default` page surface, `elevated` raised surface or `transparent`), a `padding` step and an optional `shadow`, plus default heading and paragraph typography for what you slot into it. Use it to group a section of a page or a settings panel on a consistent surface. It is a static layout primitive — for a bordered content card use `rel-card`, and for anything transient use `rel-modal` or `rel-drawer`.
+
+## Usage
+
+```html
+<!-- Default: page surface, medium padding -->
+<rel-container>
+  <h2>Section title</h2>
+  <p>Content goes here.</p>
+</rel-container>
+
+<!-- Elevated surface with small padding -->
+<rel-container surface="elevated" padding="small">
+  <p>Compact section on the raised surface.</p>
+</rel-container>
+
+<!-- Large padding with shadow -->
+<rel-container padding="large" shadow>
+  <h1>Hero section</h1>
+  <p>With shadow elevation.</p>
+</rel-container>
+
+<!-- Transparent surface: spacing only, no fill -->
+<rel-container surface="transparent" padding="extra-large">
+  <div>Content with no background.</div>
+</rel-container>
+
+<!-- Everything combined -->
+<rel-container surface="default" padding="medium" shadow>
+  <h3>Card-like container</h3>
+  <p>Page surface, medium padding, shadow.</p>
+</rel-container>
+```
+
+### Deprecated aliases
+
+```html
+<!-- background="white|light|none" is the deprecated 1.4.6 spelling of surface="default|elevated|transparent".
+     Still supported; logs once per page:
+     [rel-container] "background" is deprecated and will be removed in 3.0 — use "surface" instead. Map: white → "default", light → "elevated", none → "transparent". -->
+<rel-container background="light" padding="small">
+  <p>Same as surface="elevated".</p>
+</rel-container>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-container.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `padding` | `padding` | `"small" \| "medium" \| "large" \| "extra-large" \| "sm" \| "md" \| "lg" \| "xl"` | `"medium"` | Inner padding step: `small` = spacing-xs, `medium` = spacing-md, `large` = spacing-lg. `extra-large` = spacing-2xl is a code-only extension — Figma publishes only the three steps above — and is supported, not deprecated. `sm` / `md` / `lg` / `xl` are alternative spellings and stay supported, normalised to the full words. Reflected. |
+| `shadow` | `shadow` | `boolean` | `false` | Adds the shadow-300 elevation box-shadow to the surface. |
+| `surface` | `surface` | `"default" \| "elevated" \| "transparent"` | `undefined` | Surface fill: default (page surface) \| elevated (raised surface) \| transparent. Takes precedence over the deprecated `background` prop. Reflected. |
+
+#### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `background` | `background` | `"light" \| "white" \| "none"` | Deprecated since 1.4.7 — use `surface` (white→default, light→elevated, none→transparent). |
+
+### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `resolvedSurface` | `ContainerSurface` | Resolved surface: explicit `surface` wins, else mapped `background`, else "default". |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Section content; slotted `h1`–`h4` get the headings-sm role and `p` the body-md role |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The padded surface `<div>` (same element as `container`) |
+| `container` | Alias of `base`, kept for existing `::part(container)` selectors |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The container sets no ARIA role and is not focusable; it is a generic `display: block` region with no keyboard handling. The accessible structure comes entirely from the slotted content, so use real headings and paragraphs (they also pick up the container typography) and wrap the whole thing in a `<section>` / `<article>` with a heading when it forms a landmark.
+- `surface` and `shadow` are purely visual; nothing about the fill or elevation is conveyed to assistive technology.
+
+## Notes / Edge Cases
+
+- Padding steps map to spacing tokens: `small` = `--rel-spacing-xs`, `medium` = `--rel-spacing-md`, `large` = `--rel-spacing-lg`. `extra-large` = `--rel-spacing-2xl` is a code-only extension: Figma's Container publishes only three padding steps, and it is supported rather than deprecated. The short spellings `sm` / `md` / `lg` / `xl` keep working and normalise to the full words.
+- Surface fills: `default` = `--rel-bg-surface`, `elevated` = `--rel-bg-surface-elevated`, `transparent` = no fill. The corner radius (`--rel-border-radius-sm`) is applied regardless of surface, and `shadow` adds `--rel-shadows-md`.
+- `resolvedSurface` tells you which fill is in effect: an explicit `surface` wins, otherwise the deprecated `background` value is mapped (white → default, light → elevated, none → transparent), otherwise `default`.
+- The inner `<div>` keeps the legacy class names `bg-white` / `bg-light` / `bg-none` for the three surfaces so existing test selectors keep matching; `::part(base)` and `::part(container)` both target that same element.
+- Slotted `h1`–`h4` receive the headings-sm role with a bottom margin of `--rel-spacing-lg`; slotted `p` receives the body-md role with zero margin. Wrap other content in your own elements to style it.
+- The host is `display: block; width: 100%` with `box-sizing: border-box`, so it fills its parent; constrain the parent, not the container.