@reliability-design/web 1.4.9 → 1.4.11

package/dist/components/rel-time-picker/README.md

@@ -1,170 +1,188 @@
-# rel-time-picker
-
-Time selection field implementing the Figma "Time Picker" component (Reliability DS V1.0, node 8301:3771): an editable text field with a clock icon that opens a panel of Hour / Minute (/ Second / AM-PM) columns and a Now / Cancel / OK footer. Column picks are held as a draft until OK; the field also accepts free-form typed times ("930", "9:30 pm", "n" for now). The committed `value` is always 24-hour `"HH:mm"` (or `"HH:mm:ss"` with `seconds`) regardless of the display `format`. Use it for a single time of day; use `rel-date-picker` for dates and `rel-range-picker` for date ranges.
-
-## Usage
-
-```html
-<!-- Basic (12-hour display, 5-minute steps) -->
-<rel-time-picker></rel-time-picker>
-
-<!-- Value is always 24-hour HH:mm; the field shows it per `format` -->
-<rel-time-picker value="09:30" label="Start time"></rel-time-picker>
-<rel-time-picker value="17:05" format="24h"></rel-time-picker>
-
-<!-- Seconds column; value becomes HH:mm:ss -->
-<rel-time-picker seconds value="17:05:30" format="24h"></rel-time-picker>
-
-<!-- Minute granularity of the column (typed entry still accepts any minute) -->
-<rel-time-picker minute-step="15"></rel-time-picker>
-<rel-time-picker minute-step="1"></rel-time-picker>
-
-<!-- Constrain to business hours (inclusive, HH:mm) -->
-<rel-time-picker min-time="09:00" max-time="17:30" placeholder="Business hours only"></rel-time-picker>
-
-<!-- Clear button, helper / error text, required -->
-<rel-time-picker value="09:30" clearable></rel-time-picker>
-<rel-time-picker label="Start time" helper-text="Local timezone"></rel-time-picker>
-<rel-time-picker label="Start time" error error-message="Select a valid time"></rel-time-picker>
-<rel-time-picker label="Start time" required></rel-time-picker>
-
-<!-- States -->
-<rel-time-picker value="09:30" disabled></rel-time-picker>
-<rel-time-picker value="09:30" readonly></rel-time-picker>
-
-<!-- Sizes (field 32 / 40 / 48px, panel 220 / 250 / 280px) and layout -->
-<rel-time-picker size="small"></rel-time-picker>
-<rel-time-picker size="medium"></rel-time-picker>
-<rel-time-picker size="large"></rel-time-picker>
-<rel-time-picker fullwidth label="Full width"></rel-time-picker>
-
-<!-- Form integration: `name` renders a hidden input carrying the value -->
-<form>
-  <rel-time-picker name="startTime" label="Start time" required></rel-time-picker>
-</form>
-
-<!-- Programmatic control -->
-<rel-time-picker id="tp" clearable></rel-time-picker>
-<script>
-  const picker = document.getElementById('tp');
-  picker.value = '14:30';   // always 24h
-  picker.open = true;       // opens the panel and focuses the selected hour
-
-  picker.addEventListener('rel-change', (e) => {
-    console.log('time:', e.detail.value); // "14:30" | "14:30:00" | null (cleared)
-  });
-  picker.addEventListener('rel-open-change', (e) => {
-    console.log('open:', e.detail.open);
-  });
-</script>
-```
-
-### Typed entry
-
-Typing into the field and pressing `Enter` (or leaving the field) commits the text. Accepted forms are case- and whitespace-insensitive: `9` → 09:00, `930` / `0930` / `9:30` / `9.30` / `9 30` → 09:30, `093015` / `9:30:15` → 09:30:15, `9 pm` / `9:30p` → 21:00 / 21:30, `12am` → 00:00, `12 pm` → 12:00, and `n` / `now` → the current time. Unparseable text shows "Invalid time", a time outside `min-time` / `max-time` shows "Time out of range"; in both cases the text stays in the field for correction and the committed `value` is untouched.
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-time-picker.ts — do not edit; run readme-generate.mjs -->
-
-## API
-
-### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `value` | `value` | `string \| null` | `null` | Committed time, 24-hour "HH:mm" or "HH:mm:ss" (e.g. "09:30", "17:05:30"). Reflected. |
-| `placeholder` | `placeholder` | `string` | `"Select time"` | Placeholder shown in the field while no value is committed and nothing is typed. |
-| `label` | `label` | `string \| null` | `null` | Field label rendered above the trigger; also the input's accessible name (unset → "Select time"). |
-| `disabled` | `disabled` | `boolean` | `false` | Disables the field (0.6 opacity, no pointer events); the panel cannot open. Reflected. |
-| `required` | `required` | `boolean` | `false` | Renders the `*` mark after the label and sets `aria-required`; not enforced by the component. |
-| `readonly` | `readonly` | `boolean` | `false` | Shows the value but blocks typing and opening the panel. Reflected. |
-| `format` | `format` | `"12h" \| "24h"` | `"12h"` | Display format of the trigger text and hour column. Value stays 24-hour. |
-| `seconds` | `seconds` | `boolean` | `false` | Shows the seconds column; committed value becomes "HH:mm:ss". Reflected. |
-| `minuteStep` | `minute-step` | `number` | `5` | Minute granularity of the minutes column (1, 5, 10, 15, 30, …). |
-| `minTime` | `min-time` | `string \| null` | `null` | Earliest selectable time, "HH:mm" (inclusive). |
-| `maxTime` | `max-time` | `string \| null` | `null` | Latest selectable time, "HH:mm" (inclusive). |
-| `open` | `open` | `boolean` | `false` | Whether the panel is open. Settable from outside; opening resets the draft from `value` (programmatic changes do not fire `rel-open-change`). Reflected. |
-| `clearable` | `clearable` | `boolean` | `false` | Shows a clear (×) button inside the field while a value is set; clearing commits `null`. |
-| `error` | `error` | `boolean` | `false` | Error styling (danger border, `aria-invalid`) and shows `errorMessage` below the field. |
-| `invalid` | `invalid` | `boolean` | `false` | Alias for `error` (requested-API compat); either flag applies error styling. |
-| `errorMessage` | `error-message` | `string` | `undefined` | Text shown below the field while `error` / `invalid` is set (falls back to the typed-entry parse error, then `helperText`). |
-| `helperText` | `helper-text` | `string` | `undefined` | Assistive text shown below the field when not in error. |
-| `name` | `name` | `string` | `undefined` | When set, renders a hidden `<input name="…">` carrying `value` for native form submission. |
-| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Trigger height on the shared field scale — small 32 / medium 40 / large 48px border-box; also sets the panel width (220 / 250 / 280px) and option row height (32 / 36 / 40px). Small lowers the trigger min-width from 160 to 128px. |
-| `variant` | `variant` | `"outlined"` | `"outlined"` | Visual style; only `"outlined"` exists today. Reflected. |
-| `fullWidth` | `fullwidth` | `boolean` | `false` | Fills the parent width (the host is inline-block with intrinsic width otherwise). The attribute is lowercase `fullwidth`. Reflected. |
-
-## Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| `rel-blur` | — | bubbles / composed | Fired when the text input loses focus (before any typed text is committed). No detail. |
-| `rel-change` | `{ value: newValue } / { value: null }` | bubbles / composed | Fired when a time is committed (OK, Enter / blur on typed text, the Now shortcut) or cleared. Detail: `{ value: string \| null }` — 24-hour "HH:mm" / "HH:mm:ss", or `null` after a clear. |
-| `rel-focus` | — | bubbles / composed | Fired when the text input receives focus. No detail. |
-| `rel-open-change` | `{ open: this.open } / { open: false }` | bubbles / composed | Fired whenever the panel opens or closes through user interaction. Detail: `{ open: boolean }`. |
-
-## Slots
-
-| Slot | Description |
-| --- | --- |
-| — | This element has no slots. |
-
-## CSS Parts
-
-| Part | Description |
-| --- | --- |
-| `base` | Outer wrapper; carries the size / error / readonly classes |
-| `label` | The field label above the trigger |
-| `trigger` | The field box that anchors the panel (wraps the text input and the icons) |
-| `value` | The editable text input showing the formatted time |
-| `icon` | The trailing clock icon |
-| `panel` | The popover panel (`role="dialog"`) |
-| `shortcuts` | The typed-shortcut chip row at the top of the panel (N → Now) |
-| `option` | Each hour / minute / second / AM-PM entry button |
-| `footer` | The Now / Cancel / OK row |
-| `helper` | The helper / error text live region under the field |
-
-<!-- readme-gen:end -->
-
-
-## CSS Custom Properties
-
-| Custom property | Default | Description |
-| --- | --- | --- |
-| `--rel-overlay-fallback-z` | `1001` | z-index of the panel on the **no-Popover-API fallback path only**. Wherever the browser top layer is available the panel is promoted into it and this value is inert, because top-layer elements are not in the page stacking order at all. Shared with the other overlays (select, autocomplete, the three pickers) so the whole family can be moved from one place. |
-## Accessibility
-
-- The editable field is an `<input type="text" role="combobox">` with `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` pointing at the panel, `aria-required` (from `required`), `aria-invalid` (from `error` / `invalid` / a typed-entry error) and `aria-describedby` pointing at the helper / error text. Its accessible name is the `label` (via `aria-labelledby`), falling back to `aria-label="Select time"`.
-- The clock icon is a button labelled "Open time panel" with its own `aria-expanded`; the optional clear button is labelled "Clear time". The required mark `*` is `aria-hidden`.
-- The panel is `role="dialog"` `aria-label="Choose time"`, promoted to the browser top layer (`popover="manual"`) so a modal / drawer ancestor cannot clip it. Each column is a `role="listbox"` named "Hours", "Minutes", "Seconds" or "AM or PM"; entries are `role="option"` buttons with `aria-selected`, and out-of-range entries are native `disabled`. Each column uses a roving `tabindex` (the selected entry, else the first).
-- The helper / error text (part `helper`) is a persistent `aria-live="polite"` region, so error messages and typed-entry errors are announced as they appear.
-- Focus: opening with the clock icon, `ArrowDown`, `Enter` or by setting `open` moves focus to the selected (or first enabled) hour without scrolling the page; opening by clicking into the field keeps focus in the input so typing continues to work. Cancel, `Escape` and OK return focus to the field; an outside click closes without refocusing.
-- Screen-reader announcement (shared `announce()` utility): "{formatted time} selected" when OK commits the draft.
-
-| Key | Where | Action |
-| --- | --- | --- |
-| Typing | Field | Edits the free-form text (see Typed entry); clears any previous parse error |
-| `Enter` | Field | Commit the typed text; if nothing was typed, open the panel (closed) or apply the draft (open) |
-| `ArrowDown` | Field | Open the panel, or move focus into the columns when already open |
-| `Escape` | Field | Revert uncommitted typed text; also closes the panel discarding the draft |
-| Blur | Field | Commit the typed text when focus leaves the component (moving into the panel does not commit) |
-| `ArrowUp` / `ArrowDown` | Column | Move to and select the previous / next enabled entry |
-| `ArrowLeft` / `ArrowRight` | Column | Jump to the previous / next column (Hour → Minute → Second → AM/PM) |
-| `Home` / `End` | Column | Select the first / last enabled entry |
-| `Enter` | Column | Select the entry and apply (OK) |
-| `N` | Panel | Commit the current time immediately (same as the "N → Now" chip) and close |
-| `Escape` | Anywhere | Discard the draft and close |
-
-## Notes / Edge Cases
-
-- `value` is always 24-hour `"HH:mm"`, or `"HH:mm:ss"` when `seconds` is set; the `format` prop only changes the field text and the hour column (`12h` shows 01–12 plus an AM/PM column, `24h` shows 00–23). An unparseable `value` renders as empty.
-- `min-time` / `max-time` are `"HH:mm"` (inclusive) and are compared at minute precision even with `seconds`. Hours with no in-range step minute and AM/PM periods with no enabled hour are disabled; picking an hour snaps the draft minute to the nearest in-range step.
-- Draft model: column clicks only update the draft; **OK** commits and fires `rel-change`; **Cancel**, `Escape` or an outside click discard it (and fire `rel-open-change` with `open: false`). The OK button is disabled until an hour is chosen; picking an hour with no minute defaults the minute to `00`; picking a minute or second first defaults the hour to the first enabled one.
-- Two "now" behaviours: the footer **Now** link sets the draft to the current time snapped to `minute-step` (and to the nearest enabled hour) — you still press OK; the `N` shortcut / typed `n` / the "N → Now" chip commit the current time immediately, clamped into `min-time` / `max-time`.
-- Typed entry is not limited to `minute-step`: `9:07` commits `09:07` even with `minute-step="15"`. Typing an empty string and committing behaves like the clear button (`rel-change` with `value: null`).
-- `minute-step` outside 1–60 falls back to 1; the seconds column is always step 1.
-- `invalid` is a non-deprecated alias of `error`; either flag applies error styling. The text below the field is `error-message`, else the typed-entry error, else `helper-text`.
-- Panel widths are fixed per `size` (220 / 250 / 280px, border-box) and capped to the viewport; it flips above the field when there is no room below and shrinks (columns scroll) rather than covering the field. Footer buttons are always small per the Figma spec; OK is narrowed to 60px min-width.
-- Setting `open` programmatically opens the panel and resets the draft from `value`; it does not fire `rel-open-change` (only user interaction does).
-- `fullWidth` reflects as the lowercase `fullwidth` attribute; the host is `inline-block` with intrinsic width otherwise.
+# rel-time-picker
+
+Time selection field implementing the Figma "Time Picker" component (Reliability DS V1.0, node 8301:3771): an editable text field with a clock icon that opens a panel of Hour / Minute (/ Second / AM-PM) columns and a Now / Cancel / OK footer. Column picks are held as a draft until OK; the field also accepts free-form typed times ("930", "9:30 pm", "n" for now). The committed `value` is always 24-hour `"HH:mm"` (or `"HH:mm:ss"` with `seconds`) regardless of the display `format`. Use it for a single time of day; use `rel-date-picker` for dates and `rel-range-picker` for date ranges.
+
+## Usage
+
+```html
+<!-- Basic (12-hour display, 5-minute steps) -->
+<rel-time-picker></rel-time-picker>
+
+<!-- Value is always 24-hour HH:mm; the field shows it per `format` -->
+<rel-time-picker value="09:30" label="Start time"></rel-time-picker>
+<rel-time-picker value="17:05" format="24h"></rel-time-picker>
+
+<!-- Seconds column; value becomes HH:mm:ss -->
+<rel-time-picker seconds value="17:05:30" format="24h"></rel-time-picker>
+
+<!-- Minute granularity of the column (typed entry still accepts any minute) -->
+<rel-time-picker minute-step="15"></rel-time-picker>
+<rel-time-picker minute-step="1"></rel-time-picker>
+
+<!-- Constrain to business hours (inclusive, HH:mm) -->
+<rel-time-picker min-time="09:00" max-time="17:30" placeholder="Business hours only"></rel-time-picker>
+
+<!-- Clear button, helper / error text, required -->
+<rel-time-picker value="09:30" clearable></rel-time-picker>
+<rel-time-picker label="Start time" helper-text="Local timezone"></rel-time-picker>
+<rel-time-picker label="Start time" error error-message="Select a valid time"></rel-time-picker>
+<rel-time-picker label="Start time" required></rel-time-picker>
+
+<!-- States -->
+<rel-time-picker value="09:30" disabled></rel-time-picker>
+<rel-time-picker value="09:30" readonly></rel-time-picker>
+
+<!-- Sizes (field 32 / 40 / 48px, panel 220 / 250 / 280px) and layout -->
+<rel-time-picker size="small"></rel-time-picker>
+<rel-time-picker size="medium"></rel-time-picker>
+<rel-time-picker size="large"></rel-time-picker>
+<rel-time-picker full-width label="Full width"></rel-time-picker>
+
+<!-- Form integration: `name` renders a hidden input carrying the value -->
+<form>
+  <rel-time-picker name="startTime" label="Start time" required></rel-time-picker>
+</form>
+
+<!-- Programmatic control -->
+<rel-time-picker id="tp" clearable></rel-time-picker>
+<script>
+  const picker = document.getElementById('tp');
+  picker.value = '14:30';   // always 24h
+  picker.open = true;       // opens the panel and focuses the selected hour
+
+  picker.addEventListener('rel-change', (e) => {
+    console.log('time:', e.detail.value); // "14:30" | "14:30:00" | null (cleared)
+  });
+  picker.addEventListener('rel-open-change', (e) => {
+    console.log('open:', e.detail.open);
+  });
+</script>
+```
+
+### Typed entry
+
+Typing into the field and pressing `Enter` (or leaving the field) commits the text. Accepted forms are case- and whitespace-insensitive: `9` → 09:00, `930` / `0930` / `9:30` / `9.30` / `9 30` → 09:30, `093015` / `9:30:15` → 09:30:15, `9 pm` / `9:30p` → 21:00 / 21:30, `12am` → 00:00, `12 pm` → 12:00, and `n` / `now` → the current time. Unparseable text shows "Invalid time", a time outside `min-time` / `max-time` shows "Time out of range"; in both cases the text stays in the field for correction and the committed `value` is untouched.
+
+### Deprecated aliases
+
+```html
+<!-- fullwidth → full-width (since 1.5.0; still works, logs a one-time console notice, removed in 3.0) -->
+<rel-time-picker fullwidth label="Old spelling"></rel-time-picker>
+<rel-time-picker full-width label="Canonical"></rel-time-picker>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-time-picker.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `value` | `string \| null` | `null` | Committed time, 24-hour "HH:mm" or "HH:mm:ss" (e.g. "09:30", "17:05:30"). Reflected. |
+| `placeholder` | `placeholder` | `string` | `"Select time"` | Placeholder shown in the field while no value is committed and nothing is typed. |
+| `label` | `label` | `string \| null` | `null` | Field label rendered above the trigger; also the input's accessible name (unset → "Select time"). |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the field (no pointer events) and the panel cannot open. The field looks exactly like a disabled `rel-textfield`: the whole field at 0.65 opacity, an elevated-2 box with the accent border, the label in `--rel-text-label` and the value and placeholder in `--rel-text-caption` (changed in 1.5.0: they were `--rel-text-disabled` under the 0.65, which left them barely readable). Reflected. |
+| `required` | `required` | `boolean` | `false` | Renders the `*` mark after the label and sets `aria-required`; not enforced by the component. |
+| `readonly` | `readonly` | `boolean` | `false` | Shows the value but blocks typing and opening the panel. Reflected. |
+| `format` | `format` | `"12h" \| "24h"` | `"12h"` | Display format of the trigger text and hour column. Value stays 24-hour. |
+| `seconds` | `seconds` | `boolean` | `false` | Shows the seconds column; committed value becomes "HH:mm:ss". Reflected. |
+| `minuteStep` | `minute-step` | `number` | `5` | Minute granularity of the minutes column (1, 5, 10, 15, 30, …). |
+| `minTime` | `min-time` | `string \| null` | `null` | Earliest selectable time, "HH:mm" (inclusive). |
+| `maxTime` | `max-time` | `string \| null` | `null` | Latest selectable time, "HH:mm" (inclusive). |
+| `open` | `open` | `boolean` | `false` | Whether the panel is open. Settable from outside; opening resets the draft from `value` (programmatic changes do not fire `rel-open-change`). Reflected. |
+| `clearable` | `clearable` | `boolean` | `false` | Shows a clear (×) button inside the field while a value is set; clearing commits `null`. |
+| `error` | `error` | `boolean` | `false` | Error styling (danger border, `aria-invalid`) and shows `errorMessage` below the field. |
+| `invalid` | `invalid` | `boolean` | `false` | Alias for `error` (requested-API compat); either flag applies error styling. |
+| `errorMessage` | `error-message` | `string` | `undefined` | Text shown below the field while `error` / `invalid` is set (falls back to the typed-entry parse error, then `helperText`). |
+| `helperText` | `helper-text` | `string` | `undefined` | Assistive text shown below the field when not in error. |
+| `name` | `name` | `string` | `undefined` | When set, renders a hidden `<input name="…">` carrying `value` for native form submission. |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Trigger height on the shared field scale — small 32 / medium 40 / large 48px border-box; also sets the panel width (220 / 250 / 280px) and option row height (32 / 36 / 40px). Small lowers the trigger min-width from 160 to 128px. |
+| `variant` | `variant` | `"outlined"` | `"outlined"` | Visual style; only `"outlined"` exists today. Reflected. |
+| `fullWidth` | `full-width` | `boolean` | `false` | Fills the parent width (the host is inline-block with intrinsic width otherwise). The attribute is `full-width`. Reflected (as `fullwidth` in 1.x). The `fullwidth` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-blur` | — | bubbles / composed | Fired when the text input loses focus (before any typed text is committed). No detail. |
+| `rel-change` | `{ value: newValue } / { value: null }` | bubbles / composed | Fired when a time is committed (OK, Enter / blur on typed text, the Now shortcut) or cleared. Detail: `{ value: string \| null }` — 24-hour "HH:mm" / "HH:mm:ss", or `null` after a clear. |
+| `rel-focus` | — | bubbles / composed | Fired when the text input receives focus. No detail. |
+| `rel-open-change` | `{ open: this.open } / { open: false }` | bubbles / composed | Fired whenever the panel opens or closes through user interaction. Detail: `{ open: boolean }`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | Outer wrapper; carries the size / error / readonly classes |
+| `label` | The field label above the trigger |
+| `trigger` | The field box that anchors the panel (wraps the text input and the icons) |
+| `value` | The editable text input showing the formatted time |
+| `icon` | The trailing clock icon |
+| `panel` | The popover panel (`role="dialog"`) |
+| `shortcuts` | The typed-shortcut chip row at the top of the panel (N → Now) |
+| `option` | Each hour / minute / second / AM-PM entry button |
+| `footer` | The Now / Cancel / OK row |
+| `helper` | The helper / error text live region under the field |
+
+## 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-overlay-fallback-z` | `1001` | z-index of the panel on the **no-Popover-API fallback path only**. Wherever the browser top layer is available the panel is promoted into it and this value is inert, because top-layer elements are not in the page stacking order at all. Shared with the other overlays (select, autocomplete, the three pickers) so the whole family can be moved from one place. |
+
+<!-- readme-gen:end -->
+
+
+## CSS Custom Properties
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-overlay-fallback-z` | `1001` | z-index of the panel on the **no-Popover-API fallback path only**. Wherever the browser top layer is available the panel is promoted into it and this value is inert, because top-layer elements are not in the page stacking order at all. Shared with the other overlays (select, autocomplete, the three pickers) so the whole family can be moved from one place. |
+## Accessibility
+
+- The editable field is an `<input type="text" role="combobox">` with `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` pointing at the panel, `aria-required` (from `required`), `aria-invalid` (from `error` / `invalid` / a typed-entry error) and `aria-describedby` pointing at the helper / error text. Its accessible name is the `label` (via `aria-labelledby`), falling back to `aria-label="Select time"`.
+- The clock icon is a button labelled "Open time panel" with its own `aria-expanded`; the optional clear button is labelled "Clear time". The required mark `*` is `aria-hidden`.
+- The panel is `role="dialog"` `aria-label="Choose time"`, promoted to the browser top layer (`popover="manual"`) so a modal / drawer ancestor cannot clip it. Each column is a `role="listbox"` named "Hours", "Minutes", "Seconds" or "AM or PM"; entries are `role="option"` buttons with `aria-selected`, and out-of-range entries are native `disabled`. Each column uses a roving `tabindex` (the selected entry, else the first).
+- The helper / error text (part `helper`) is a persistent `aria-live="polite"` region, so error messages and typed-entry errors are announced as they appear.
+- Focus: opening with the clock icon, `ArrowDown`, `Enter` or by setting `open` moves focus to the selected (or first enabled) hour without scrolling the page; opening by clicking into the field keeps focus in the input so typing continues to work. Cancel, `Escape` and OK return focus to the field; an outside click closes without refocusing.
+- Screen-reader announcement (shared `announce()` utility): "{formatted time} selected" when OK commits the draft.
+
+| Key | Where | Action |
+| --- | --- | --- |
+| Typing | Field | Edits the free-form text (see Typed entry); clears any previous parse error |
+| `Enter` | Field | Commit the typed text; if nothing was typed, open the panel (closed) or apply the draft (open) |
+| `ArrowDown` | Field | Open the panel, or move focus into the columns when already open |
+| `Escape` | Field | Revert uncommitted typed text; also closes the panel discarding the draft |
+| Blur | Field | Commit the typed text when focus leaves the component (moving into the panel does not commit) |
+| `ArrowUp` / `ArrowDown` | Column | Move to and select the previous / next enabled entry |
+| `ArrowLeft` / `ArrowRight` | Column | Jump to the previous / next column (Hour → Minute → Second → AM/PM) |
+| `Home` / `End` | Column | Select the first / last enabled entry |
+| `Enter` | Column | Select the entry and apply (OK) |
+| `N` | Panel | Commit the current time immediately (same as the "N → Now" chip) and close |
+| `Escape` | Anywhere | Discard the draft and close |
+
+## Notes / Edge Cases
+
+- `value` is always 24-hour `"HH:mm"`, or `"HH:mm:ss"` when `seconds` is set; the `format` prop only changes the field text and the hour column (`12h` shows 01–12 plus an AM/PM column, `24h` shows 00–23). An unparseable `value` renders as empty.
+- `min-time` / `max-time` are `"HH:mm"` (inclusive) and are compared at minute precision even with `seconds`. Hours with no in-range step minute and AM/PM periods with no enabled hour are disabled; picking an hour snaps the draft minute to the nearest in-range step.
+- Draft model: column clicks only update the draft; **OK** commits and fires `rel-change`; **Cancel**, `Escape` or an outside click discard it (and fire `rel-open-change` with `open: false`). The OK button is disabled until an hour is chosen; picking an hour with no minute defaults the minute to `00`; picking a minute or second first defaults the hour to the first enabled one.
+- Two "now" behaviours: the footer **Now** link sets the draft to the current time snapped to `minute-step` (and to the nearest enabled hour) — you still press OK; the `N` shortcut / typed `n` / the "N → Now" chip commit the current time immediately, clamped into `min-time` / `max-time`.
+- Typed entry is not limited to `minute-step`: `9:07` commits `09:07` even with `minute-step="15"`. Typing an empty string and committing behaves like the clear button (`rel-change` with `value: null`).
+- `minute-step` outside 1–60 falls back to 1; the seconds column is always step 1.
+- `invalid` is a non-deprecated alias of `error`; either flag applies error styling. The text below the field is `error-message`, else the typed-entry error, else `helper-text`.
+- Panel widths are fixed per `size` (220 / 250 / 280px, border-box) and capped to the viewport; it flips above the field when there is no room below and shrinks (columns scroll) rather than covering the field. On an outside scroll (since 1.5.0) it **stays open and moves with the field while the field is still visible**, and closes once the field scrolls out of the viewport or its scroll container, or under a sticky header — so the top-layer panel never paints over page furniture (the reason 1.4.9 closed it on every scroll). Only the window and the field's own scroll containers count, including ones inside shadow roots such as `rel-modal`'s body; scrolls of unrelated elements and of the panel itself are ignored, and a wheel or swipe over the panel never scrolls the page (`overscroll-behavior: contain`); that includes the hour / minute / period columns. Footer buttons are always small per the Figma spec; OK is narrowed to 60px min-width.
+- Setting `open` programmatically opens the panel and resets the draft from `value`; it does not fire `rel-open-change` (only user interaction does).
+- `fullWidth` (attribute `full-width`) still reflects as the lowercase `fullwidth` attribute in 1.x; the host is `inline-block` with intrinsic width otherwise.

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

@@ -1,6 +1,6 @@
 # rel-toast
 
-`<rel-toast>` is the transient notification of the Reliability Design System: a card anchored to one of six viewport positions (bottom centre by default) that shows a short message, an optional action button ("Undo", "Retry") and a dismiss button, then hides itself after `duration` milliseconds. It has two tones — `default` and `destructive` — and is driven by the `show` property (or `open()` / `close()`). Use it for brief confirmations that need no reply; use `<rel-snackbar>` when you need the status tones, a stacked layout or your own positioning, and `<rel-alert>` for messages that must stay on the page.
+`<rel-toast>` is the transient notification of the Reliability Design System: a card anchored to one of six viewport positions (bottom centre by default) that shows a short message, an optional action button ("Undo", "Retry") and a dismiss button, then hides itself after `duration` milliseconds. It has four tones — `neutral` (default), `info`, `success` and `destructive`; the three filled ones use the same fill and text tokens as `<rel-alert appearance="solid">` — and is driven by the `show` property (or `open()` / `close()`). Use it for brief confirmations that need no reply; use `<rel-snackbar>` when you need a warning tone, a stacked layout or your own positioning, and `<rel-alert>` for messages that must stay on the page.
 
 ## Usage
 
@@ -14,8 +14,12 @@
 <!-- Destructive tone: danger fill, announced assertively -->
 <rel-toast id="failed" tone="destructive" message="Upload failed"></rel-toast>
 
-<!-- Action button (attribute is lower-case: actionlabel) -->
-<rel-toast id="deleted" message="Item deleted" actionlabel="Undo"></rel-toast>
+<!-- Success and info tones: success / info fill (same tokens as a solid rel-alert), announced politely -->
+<rel-toast id="done" tone="success" message="Changes saved"></rel-toast>
+<rel-toast id="note" tone="info" message="A new version is available"></rel-toast>
+
+<!-- Action button -->
+<rel-toast id="deleted" message="Item deleted" action-label="Undo"></rel-toast>
 
 <!-- Longer and persistent toasts -->
 <rel-toast id="slow" message="Download complete" duration="7000"></rel-toast>
@@ -56,6 +60,10 @@ rel-toast { --rel-toast-z: 10000; }
      [rel-toast] "tone="error"" is deprecated and will be removed in 3.0 — use "tone="destructive"" instead. -->
 <rel-toast tone="error" message="Upload failed"></rel-toast>
 <rel-toast tone="danger" message="Upload failed"></rel-toast>
+
+<!-- actionlabel → action-label (since 1.5.0; still works, logs a one-time console notice, removed in 3.0) -->
+<rel-toast message="Item deleted" actionlabel="Undo"></rel-toast>
+<rel-toast message="Item deleted" action-label="Undo"></rel-toast>
 ```
 
 ```css
@@ -74,11 +82,11 @@ rel-toast { --rel-z-toast: 10000; }
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `message` | `message` | `string` | `""` | Text of the toast. It is also announced to screen readers through the shared live-region announcer each time `show` becomes true. |
-| `tone` | `tone` | `"neutral" \| "destructive" \| "default" \| "error" \| "danger" \| "critical"` | `undefined` | Semantic tone (Figma "Tone"): `"neutral"` (default: neutral surface) \| `"destructive"` (danger fill, announced assertively). `"default"` is a deprecated alias of `"neutral"`; `"error"`, `"danger"` and `"critical"` are deprecated aliases of `"destructive"`; each logs a one-time console notice. Takes precedence over the deprecated `type` prop. |
-| `actionLabel` | `actionlabel` | `string` | `undefined` | Label of the optional action button rendered between the message and the dismiss button; the button is omitted when unset. Clicking it fires `action` and then closes the toast. |
+| `tone` | `tone` | `"neutral" \| "info" \| "success" \| "destructive" \| "default" \| "error" \| "danger" \| "critical"` | `undefined` | Semantic tone (Figma "Tone"): `"neutral"` (default: neutral surface) \| `"info"` (info fill) \| `"success"` (success fill) \| `"destructive"` (danger fill, announced assertively). The three filled tones use the same fill and text tokens as rel-alert's solid style, so a toast matches an alert of the same tone; info and success are announced politely. The three filled tones show a 20px leading icon (`error`, `check-circle`, `info`; part `icon`, hidden from assistive technology); the neutral tone has none (new in 1.5.0). Figma's Toast has all four tones. An unknown value renders as `"neutral"`. `"default"` is a deprecated alias of `"neutral"`; `"error"`, `"danger"` and `"critical"` are deprecated aliases of `"destructive"`; each logs a one-time console notice. Takes precedence over the deprecated `type` prop. |
+| `actionLabel` | `action-label` | `string` | `undefined` | Label of the optional action button rendered between the message and the dismiss button; the button is omitted when unset. Clicking it fires `action` and then closes the toast. The `actionlabel` attribute spelling is deprecated (still works; removal targeted for 3.0). |
 | `duration` | `duration` | `number` | `4000` | Auto-dismiss delay in milliseconds, started each time `show` becomes true. `0` (or a negative value) disables auto-dismiss so the toast stays until `close()` or the dismiss button. Changing it while the toast is visible does not restart the running timer. |
 | `show` | `show` | `boolean` | `false` | Whether the toast is visible. Set it to true (or call `open()`) to show the toast and start the auto-dismiss timer; it is set back to false by `close()`, the dismiss button, the action button and the timer. Reflected. |
-| `dismissible` | `dismissible` | `boolean` | `true` | Shows the trailing dismiss button (Figma "Show Close Button"). Defaults to true; because it is a Lit boolean, `dismissible="false"` is still true — set the property to `false` from script to hide the button. |
+| `dismissible` | `dismissible` | `boolean` | `true` | Shows the trailing dismiss button (Figma "Show Close Button"). Defaults to true; `dismissible="false"` (or the property set to `false`) hides the button. |
 | `position` | `position` | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"bottom-center"` | Where the toast is anchored: `bottom-center` (default, unchanged from before this prop existed), `bottom-left`, `bottom-right`, `top-left`, `top-center` or `top-right`. Top anchors also animate in from the top edge rather than upward from the bottom. Figma's Toast has axes Content / Show Button / Show Close Button / Tone and no position, so this axis is ours. Reflected. |
 | `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Toast scale: `small`, `medium` (default, unchanged) or `large`. `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. Scales the padding, the inner gap, the message type role and the close icon. Figma has no Size axis on Toast. Reflected. |
 | `maxVisible` | `max-visible` | `number` | `3` | How many toasts may be on screen at once AT THIS POSITION. Further ones wait their turn rather than being dropped — a notification the user never saw is worse than a late one — and each toast's `duration` only starts once it actually becomes visible, so a queued message cannot expire unseen. Default 3; unbounded stacking just fills the viewport. |
@@ -87,13 +95,13 @@ rel-toast { --rel-z-toast: 10000; }
 
 | Property | Attribute | Type | Use instead |
 | --- | --- | --- | --- |
-| `type` | `type` | `"neutral" \| "destructive" \| "default" \| "error" \| "danger" \| "critical"` | Deprecated since 1.4.7 — alias of `tone`; use `tone`. Same values as `tone`; `type="error"` maps to `tone="destructive"` and `type="default"` to `tone="neutral"`. Ignored when `tone` is set. Logs a one-time console notice. |
+| `type` | `type` | `"neutral" \| "info" \| "success" \| "destructive" \| "default" \| "error" \| "danger" \| "critical"` | Deprecated since 1.4.7 — alias of `tone`; use `tone`. Same values as `tone`; `type="error"` maps to `tone="destructive"` and `type="default"` to `tone="neutral"`. Ignored when `tone` is set. Logs a one-time console notice. |
 
 ### Public fields / accessors
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `resolvedTone` | `ToastTone` | Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"neutral"` / `"destructive"`. |
+| `resolvedTone` | `ToastTone` | Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"neutral"` / `"destructive"`, and an unknown value to `"neutral"`. |
 
 ### Methods
 
@@ -120,8 +128,9 @@ rel-toast { --rel-z-toast: 10000; }
 | Part | Description |
 | --- | --- |
 | `base` | The `role="status"` toast container that carries the tone class |
+| `icon` | The 20px leading icon of a filled tone (`error` on destructive, `check-circle` on success, `info` on info); a neutral toast has none. New in 1.5.0 |
 | `label` | The message text span |
-| `action` | The action button; rendered only when `actionlabel` is set |
+| `action` | The action button; rendered only when `action-label` is set |
 | `close-button` | The dismiss button; rendered while `dismissible` is true |
 
 ## Tokens / CSS Variables
@@ -138,8 +147,8 @@ Set these on the host (or an ancestor) to customise the element without touching
 
 ## Accessibility
 
-- The toast container (part `base`) is always in the shadow DOM with `role="status"`, `aria-live="polite"` and `aria-atomic="true"`; it is hidden with `display: none` while `show` is false. Because toggling `display` is not reliably announced, the component also pushes `message` into the shared off-screen live-region announcer (`utils/announce`) every time `show` becomes true — politely for `default`, assertively for `destructive`. Focus is never moved.
-- Two native `<button>`s: the optional action button (labelled by `actionlabel`) and the dismiss button with `aria-label="Dismiss"`. Both are in the Tab order; the component registers no key handlers (there is no Escape-to-close):
+- The toast container (part `base`) is always in the shadow DOM with `role="status"`, `aria-live="polite"` and `aria-atomic="true"`; it is hidden with `display: none` while `show` is false. Because toggling `display` is not reliably announced, the component also pushes `message` into the shared off-screen live-region announcer (`utils/announce`) every time `show` becomes true — politely for `neutral`, `info` and `success`, assertively for `destructive`. Focus is never moved.
+- Two native `<button>`s: the optional action button (labelled by `action-label`) and the dismiss button with `aria-label="Dismiss"`. Both are in the Tab order; the component registers no key handlers (there is no Escape-to-close):
 
 | Key | Action |
 | --- | --- |

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

@@ -7,7 +7,7 @@ Hover/focus tooltip implementing the Figma "Tooltip" component: wraps a trigger
 ```html
 <!-- Default: above the trigger -->
 <rel-tooltip text="Save your changes">
-  <rel-button variant="primary">Save</rel-button>
+  <rel-button variant="primary" tone="brand">Save</rel-button>
 </rel-tooltip>
 
 <!-- Positions -->
@@ -24,7 +24,7 @@ Hover/focus tooltip implementing the Figma "Tooltip" component: wraps a trigger
 <!-- With the pointing tail -->
 <rel-tooltip text="Edit" show-tail>
   <rel-button variant="ghost" icon-only aria-label="Edit">
-    <rel-icon name="edit"></rel-icon>
+    <rel-icon name="pencil"></rel-icon>
   </rel-button>
 </rel-tooltip>
 
@@ -75,7 +75,7 @@ Hover/focus tooltip implementing the Figma "Tooltip" component: wraps a trigger
 
 | Slot | Description |
 | --- | --- |
-| (default) | The trigger element (one focusable element such as a button or icon button). It receives `aria-describedby` pointing at the bubble. |
+| (default) | The trigger element (one focusable element such as a button or icon button). The control that takes focus — the slotted element itself, or the focusable control inside a rel-* trigger such as rel-button — receives `text` as its `aria-description`, so screen readers announce it. |
 
 ## CSS Parts
 
@@ -98,7 +98,8 @@ Set these on the host (or an ancestor) to customise the element without touching
 
 ## Accessibility
 
-- The bubble is a `role="tooltip"` element with a stable generated `id`; the first slotted element is given `aria-describedby` pointing at it (re-linked on `slotchange`), so screen readers read the hint as the trigger's description.
+- Screen readers read `text` as the trigger's **description**: it is set as `aria-description` on the control that takes focus — the first slotted element, or, when that is a rel-* component such as `<rel-button>`, the focusable control inside its shadow root. It is re-linked on `slotchange` and updated when `text` changes, and a swapped-out trigger loses the description it was given. (Up to 1.4.9 the trigger got `aria-describedby` pointing at the bubble's id inside this component's shadow root, a reference that cannot cross the shadow boundary, so nothing was announced.)
+- The bubble keeps `role="tooltip"` but is `aria-hidden`: it stays in the DOM while hidden (opacity), so it would otherwise be read a second time as stray text.
 - The bubble is shown while the host is hovered **or** has focus within (`:focus-within`), so keyboard users see it when the slotted trigger is focused. The trigger therefore must be focusable — wrap a button or link, not plain text.
 - The bubble never takes focus and has `pointer-events: none`.