@reliability-design/web 1.4.9 → 1.4.10

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

@@ -1,141 +1,188 @@
-# rel-kbd
-
-`<rel-kbd>` is the single key cap from the Figma "Kbd" component (node 6316:284): a flat, bordered chip that shows a keyboard key or shortcut inline with text, in three heights (20 / 24 / 28px) and two fills (`default`, `muted`), with an `inset` pressed look. `<rel-kbd-group>` (Figma Kbd Items=1–4) renders a multi-key shortcut from an `items` array, one `<rel-kbd>` per key joined by "+" separators. Use them in help text, tooltips, menus and command palettes to display shortcuts. They are display-only — do not use them as buttons, and use `rel-chip` for tags or `rel-badge` for counts.
-
-## Usage
-
-```html
-<!-- Single key -->
-<rel-kbd>K</rel-kbd>
-
-<!-- Sizes -->
-<rel-kbd size="small">Esc</rel-kbd>
-<rel-kbd size="medium">Enter</rel-kbd>
-<rel-kbd size="large">Space</rel-kbd>
-
-<!-- Variants -->
-<rel-kbd variant="default">Shift</rel-kbd>
-<rel-kbd variant="muted">⌘</rel-kbd>
-
-<!-- Pressed look -->
-<p>Hold <rel-kbd inset>Space</rel-kbd> to preview</p>
-
-<!-- Multi-key shortcut from an items array (JSON attribute or property) -->
-<rel-kbd-group items='["Ctrl","Shift","P"]' size="medium"></rel-kbd-group>
-<rel-kbd-group id="palette" variant="muted" size="small"></rel-kbd-group>
-<script>
-  document.getElementById("palette").items = ["⌘", "K"];
-</script>
-
-<!-- Inline with text -->
-<p>Press <rel-kbd-group items='["Ctrl","K"]'></rel-kbd-group> to search</p>
-```
-
-### Deprecated aliases
-
-```html
-<!-- sm / md / lg → small / medium / large (accepted silently; no console notice) -->
-<rel-kbd size="sm">S</rel-kbd>
-<rel-kbd size="md">M</rel-kbd>
-<rel-kbd size="lg">L</rel-kbd>
-<rel-kbd-group items='["Ctrl","C"]' size="md"></rel-kbd-group>
-
-<!-- `pill` is deprecated → use the default 4px radius. Still renders fully rounded corners and logs once:
-     [rel-kbd] "pill" is deprecated and will be removed in 3.0 — use "the default radius (4px at every size)" instead. The Kbd spec has one radius at every size; pill keeps working but is not part of the design. -->
-<rel-kbd pill>R</rel-kbd>
-```
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-kbd.ts — do not edit; run readme-generate.mjs -->
-
-## Elements
-
-| Element | Class | Source |
-| --- | --- | --- |
-| `<rel-kbd>` | `RelKbd` | `rel-kbd.ts` |
-| `<rel-kbd-group>` | `RelKbdGroup` | `rel-kbd.ts` |
-
-## API
-
-### `<rel-kbd>`
-
-#### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `size` | `size` | `"sm" \| "md" \| "lg" \| "small" \| "medium" \| "large"` | `"md"` | Key-cap scale (Figma Size): `small` 20px tall / label-sm, `medium` 24px / label-md, `large` 28px / label-lg; 4px radius at every size. `sm` / `md` / `lg` are the legacy short spellings and stay accepted. Reflected. |
-| `variant` | `variant` | `"default" \| "muted"` | `"default"` | Fill / text contrast: `default` = elevated-1 background with label text; `muted` = elevated-2 background with placeholder-tone text for secondary shortcuts. Both carry a 0.5px stroke and the hard 2px bottom edge Figma draws on the key cap. Reflected. |
-| `inset` | `inset` | `boolean` | `false` | Pressed look: border-strong stroke, 1px downward nudge and (muted variant) a darker fill. Reflected. |
-
-##### Deprecated (still supported — removal targeted for 3.0)
-
-| Property | Attribute | Type | Use instead |
-| --- | --- | --- | --- |
-| `pill` | `pill` | `boolean` | The Kbd spec has a single 4px radius at every size (audit 16); `pill` is kept working as an alias but logs a one-time notice. |
-
-### Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| — | — | — | This element emits no custom events. |
-
-### Slots
-
-| Slot | Description |
-| --- | --- |
-| (default) | The key label (e.g. `Ctrl`, `K`, `⌘`) |
-
-### CSS Parts
-
-| Part | Description |
-| --- | --- |
-| — | None exposed. |
-
-### `<rel-kbd-group>`
-
-#### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `items` | `items` | `string[]` | `[]` | Key labels to render, one `<rel-kbd>` each, joined by `+` separators. Set as a property or as a JSON array attribute (`items='["Ctrl","K"]'`). |
-| `size` | `size` | `"sm" \| "md" \| "lg" \| "small" \| "medium" \| "large"` | `"md"` | Passed through to every generated <rel-kbd>: `small` / `medium` / `large` (legacy `sm` / `md` / `lg` still accepted). Reflected. |
-| `variant` | `variant` | `"default" \| "muted"` | `"default"` | Passed through to every generated <rel-kbd>: `default` or `muted`. Reflected. |
-
-### Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| — | — | — | This element emits no custom events. |
-
-### Slots
-
-| Slot | Description |
-| --- | --- |
-| (default) | Extra content rendered after the generated keys (e.g. hand-written `<rel-kbd>` children) |
-
-### CSS Parts
-
-| Part | Description |
-| --- | --- |
-| `label` | The `+` separator between generated keys |
-| `item` | Each generated `<rel-kbd>` key cap |
-
-<!-- readme-gen:end -->
-
-## Accessibility
-
-- Both elements are purely presentational: no ARIA role, no `tabindex`, no keyboard handling and no events. `<rel-kbd>` renders only its default slot, so the key label is plain text for screen readers.
-- Neither element wraps its content in a native `<kbd>`. If you need that semantics, put the `<kbd>` in light DOM: `<kbd><rel-kbd>Ctrl</rel-kbd></kbd>`.
-- In `<rel-kbd-group>` the "+" separators are `aria-hidden="true"`, so a shortcut reads as the sequence of key labels only.
-- Text is `user-select: none` on the key caps and separators, so shortcuts are not copied along with surrounding prose.
-- Colours come from the neutral elevated backgrounds with `--rel-text-label` (default) and `--rel-text-placeholder` (muted) text; the muted variant is intended for secondary shortcuts and has lower contrast by design.
-
-## Notes / Edge Cases
-
-- Heights are the Figma frame heights (20 / 24 / 28px) with the 0.5px stroke inside them (`box-sizing: border-box`), and the corner radius is 4px at every size. The cap carries a hard 2px bottom edge (a zero-blur drop shadow), so it occupies 2px more vertical space than its nominal height.
-- `small` / `medium` / `large` and `sm` / `md` / `lg` are interchangeable at the CSS level (`:host([size="md"])` and `:host([size="medium"])` share rules); the default value is `md`.
-- `inset` swaps the stroke to `--rel-border-strong` and nudges the cap 1px down; in the `muted` variant it also darkens the fill.
-- A `<span>` slotted into `<rel-kbd>` picks up body-sm-regular type (Figma hint text) instead of the label type.
-- `<rel-kbd-group>` passes its `size` and `variant` to every generated key; `items` set as an attribute must be a JSON array string. Slotted `<rel-kbd>` children render after the generated keys with no automatic "+" separators — either use `items` or hand-write the whole shortcut.
-- The `item` and `label` parts exist only on `<rel-kbd-group>`; a standalone `<rel-kbd>` exposes no parts.
+# rel-kbd
+
+`<rel-kbd>` is the single key cap from the Figma "Kbd" component (node 6316:284): a flat, bordered chip that shows a keyboard key or shortcut inline with text, in three heights (20 / 24 / 28px) and two fills (`default`, `muted`), with an `inset` pressed look. `<rel-kbd-group>` (Figma Kbd Items=1–4) renders a multi-key shortcut from an `items` array, one `<rel-kbd>` per key joined by "+" separators. Use them in help text, tooltips, menus and command palettes to display shortcuts. They are display-only — do not use them as buttons, and use `rel-chip` for tags or `rel-badge` for counts.
+
+## Usage
+
+```html
+<!-- Single key -->
+<rel-kbd>K</rel-kbd>
+
+<!-- Sizes -->
+<rel-kbd size="small">Esc</rel-kbd>
+<rel-kbd size="medium">Enter</rel-kbd>
+<rel-kbd size="large">Space</rel-kbd>
+
+<!-- Variants -->
+<rel-kbd variant="default">Shift</rel-kbd>
+<rel-kbd variant="muted">⌘</rel-kbd>
+
+<!-- Pressed look -->
+<p>Hold <rel-kbd inset>Space</rel-kbd> to preview</p>
+
+<!-- Multi-key shortcut from an items array (JSON attribute or property) -->
+<rel-kbd-group items='["Ctrl","Shift","P"]' size="medium"></rel-kbd-group>
+<rel-kbd-group id="palette" variant="muted" size="small"></rel-kbd-group>
+<script>
+  document.getElementById("palette").items = ["⌘", "K"];
+</script>
+
+<!-- Inline with text -->
+<p>Press <rel-kbd-group items='["mod","K"]'></rel-kbd-group> to search</p>
+```
+
+### Named keys and Mac symbols (new in 1.5.0)
+
+`key-name` on `<rel-kbd>` and every entry of `items` on `<rel-kbd-group>` take a named key. Named keys follow the viewer's platform: Mac shows the symbols (⌘ ⌃ ⌥ ⇧ ↩ ⎋ ⇥ ⌫ ⌦ ⇞ ⇟ ↖ ↘ ⇪), every other platform the short words (Ctrl, Alt, Shift, Enter, Esc, Tab, Backspace, Delete, PgUp, PgDn, Home, End, Caps Lock). `mod` is the primary modifier: ⌘ on Mac, Ctrl elsewhere. Slotted text is never reinterpreted.
+
+```html
+<!-- ⌘ K on a Mac, Ctrl + K elsewhere; read as "Command plus K" / "Control plus K" -->
+<rel-kbd-group items='["mod","K"]'></rel-kbd-group>
+
+<!-- A single named key -->
+<rel-kbd key-name="shift"></rel-kbd>
+
+<!-- Force a convention (default "auto" detects it from the browser) -->
+<rel-kbd-group items='["mod","Shift","P"]' platform="mac"></rel-kbd-group>
+<rel-kbd key-name="option" platform="other"></rel-kbd>  <!-- Alt -->
+
+<!-- Slotted text renders exactly as written -->
+<rel-kbd>Ctrl</rel-kbd>
+```
+
+| `key-name` (any case) | Mac | Elsewhere | Read as |
+| --- | --- | --- | --- |
+| `mod` | ⌘ | Ctrl | Command / Control |
+| `cmd`, `command` | ⌘ | ⌘ | Command |
+| `meta` | ⌘ | Win | Command / Windows |
+| `ctrl`, `control` | ⌃ | Ctrl | Control |
+| `alt`, `option`, `opt` | ⌥ | Alt | Option / Alt |
+| `shift` | ⇧ | Shift | Shift |
+| `enter`, `return` | ↩ | Enter | Return / Enter |
+| `esc`, `escape` | ⎋ | Esc | Escape |
+| `tab` | ⇥ | Tab | Tab |
+| `backspace` | ⌫ | Backspace | Backspace |
+| `delete` | ⌦ | Delete | Delete |
+| `space` | Space | Space | Space |
+| `up`, `down`, `left`, `right` | ↑ ↓ ← → | ↑ ↓ ← → | Up Arrow… |
+| `pageup`, `pagedown` | ⇞ ⇟ | PgUp, PgDn | Page Up / Page Down |
+| `home`, `end` | ↖ ↘ | Home, End | Home / End |
+| `capslock` | ⇪ | Caps Lock | Caps Lock |
+
+Anything else (`K`, `F5`, `⌘`) is shown as typed.
+
+### Deprecated aliases
+
+```html
+<!-- sm / md / lg → small / medium / large (accepted silently; no console notice) -->
+<rel-kbd size="sm">S</rel-kbd>
+<rel-kbd size="md">M</rel-kbd>
+<rel-kbd size="lg">L</rel-kbd>
+<rel-kbd-group items='["Ctrl","C"]' size="md"></rel-kbd-group>
+
+<!-- `pill` is deprecated → use the default 4px radius. Still renders fully rounded corners and logs once:
+     [rel-kbd] "pill" is deprecated and will be removed in 3.0 — use "the default radius (4px at every size)" instead. The Kbd spec has one radius at every size; pill keeps working but is not part of the design. -->
+<rel-kbd pill>R</rel-kbd>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-kbd.ts — do not edit; run readme-generate.mjs -->
+
+## Elements
+
+| Element | Class | Source |
+| --- | --- | --- |
+| `<rel-kbd>` | `RelKbd` | `rel-kbd.ts` |
+| `<rel-kbd-group>` | `RelKbdGroup` | `rel-kbd.ts` |
+
+## API
+
+### `<rel-kbd>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `keyName` | `key-name` | `string` | `undefined` | New in 1.5.0. A named key, drawn in the platform's convention instead of the slotted text: `mod` (⌘ on Mac, Ctrl elsewhere), `cmd` / `command` / `meta`, `ctrl` / `control`, `alt` / `option` / `opt`, `shift`, `enter` / `return`, `esc` / `escape`, `tab`, `backspace`, `delete`, `space`, `up` / `down` / `left` / `right`, `pageup` / `pagedown`, `home` / `end`, `capslock` (case-insensitive). Mac shows symbols (⌘ ⌃ ⌥ ⇧ ↩ ⎋ ⇥ ⌫ ⌦ ⇞ ⇟ ↖ ↘ ⇪); elsewhere the short words (Ctrl, Alt, Esc, PgUp…); arrows are ↑ ↓ ← → on both and Space is the word on both. The symbol is hidden from assistive technology and the key's full name (Command, Option…) is read instead. Any other value is shown as typed. While set, slotted content is not rendered. |
+| `platform` | `platform` | `"auto" \| "mac" \| "other"` | `"auto"` | New in 1.5.0. Keyboard convention for `key-name`: `auto` detects Mac / iPhone / iPad from the browser (no `navigator`, as in SSR, counts as `other`), `mac` and `other` force one. Has no effect on slotted text. |
+| `size` | `size` | `"sm" \| "md" \| "lg" \| "small" \| "medium" \| "large"` | `"md"` | Key-cap scale (Figma Size): `small` 20px tall / label-sm, `medium` 24px / label-md, `large` 28px / label-lg; 4px radius at every size. A single-symbol key (⌘ ⌥ ⇧ ⌃, `mod` when it shows ⌘, arrows…) is a square cap, 20 × 20 / 24 × 24 / 28 × 28px, with the symbol centred (new in 1.5.0). `sm` / `md` / `lg` are the legacy short spellings and stay accepted. Reflected. |
+| `variant` | `variant` | `"default" \| "muted"` | `"default"` | Fill / text contrast: `default` = elevated-1 background with label text; `muted` = elevated-2 background with caption-tone text for secondary shortcuts. Both carry a 0.5px stroke and the hard 2px bottom edge Figma draws on the key cap. Reflected. |
+| `inset` | `inset` | `boolean` | `false` | Pressed look: border-strong stroke and a 1px downward nudge; the fill stays the variant's. Reflected. |
+
+##### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `pill` | `pill` | `boolean` | The Kbd spec has a single 4px radius at every size (audit 16); `pill` is kept working as an alias but logs a one-time notice. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | The key label (e.g. `Ctrl`, `K`, `⌘`), rendered exactly as written. Not rendered while `key-name` is set. |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| — | None exposed. |
+
+### `<rel-kbd-group>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `items` | `string[]` | `[]` | Keys to render, one `<rel-kbd>` each, joined by `+` separators (read as "plus"). Set as a property or as a JSON array attribute (`items='["mod","K"]'`). Since 1.5.0 each entry is a `key-name`: named keys (`mod`, `ctrl`, `shift`, `enter`, arrows…, case-insensitive) follow the platform convention, so `"Ctrl"` shows ⌃ on a Mac; use `"mod"` for the primary modifier (⌘ on Mac, Ctrl elsewhere). Anything else is shown as typed. |
+| `platform` | `platform` | `"auto" \| "mac" \| "other"` | `"auto"` | New in 1.5.0. Passed through to every generated <rel-kbd>: `auto` (default) detects Mac from the browser, `mac` / `other` force a convention for named keys. |
+| `size` | `size` | `"sm" \| "md" \| "lg" \| "small" \| "medium" \| "large"` | `"md"` | Passed through to every generated <rel-kbd>: `small` / `medium` / `large` (legacy `sm` / `md` / `lg` still accepted). Reflected. |
+| `variant` | `variant` | `"default" \| "muted"` | `"default"` | Passed through to every generated <rel-kbd>: `default` or `muted`. Reflected. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Extra content rendered after the generated keys (e.g. hand-written `<rel-kbd>` children) |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `label` | The `+` separator between generated keys |
+| `item` | Each generated `<rel-kbd>` key cap |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- Both elements are purely presentational: no ARIA role, no `tabindex`, no keyboard handling and no events. Slotted key labels are plain text for screen readers.
+- Named keys (`key-name`, and `items` entries): when the cap shows a symbol or abbreviation (⌘, ⌥, Ctrl, Esc, PgUp, ↑), it is `aria-hidden` and the key's full name (Command, Option, Control, Escape, Page Up, Up Arrow) is rendered as visually hidden text instead. The names are English.
+- Neither element wraps its content in a native `<kbd>`. If you need that semantics, put the `<kbd>` in light DOM: `<kbd><rel-kbd>Ctrl</rel-kbd></kbd>`.
+- In `<rel-kbd-group>` the visible "+" separators are `aria-hidden="true"` and a visually hidden "plus" is read in their place (since 1.5.0), so `items='["mod","K"]'` reads "Command plus K" on a Mac and "Control plus K" elsewhere.
+- Text is `user-select: none` on the key caps and separators, so shortcuts are not copied along with surrounding prose.
+- Colours come from the neutral elevated backgrounds with `--rel-text-label` (default) and `--rel-text-caption` (muted) text. The muted variant is for secondary shortcuts: quieter than the default, but its label still meets AA (about 5.7:1 in light mode, 5.8:1 in dark).
+
+## Notes / Edge Cases
+
+- Heights are the Figma frame heights (20 / 24 / 28px) with the 0.5px stroke inside them (`box-sizing: border-box`), and the corner radius is 4px at every size. The cap carries a hard 2px bottom edge (a zero-blur drop shadow), so it occupies 2px more vertical space than its nominal height.
+- `small` / `medium` / `large` and `sm` / `md` / `lg` are interchangeable at the CSS level (`:host([size="md"])` and `:host([size="medium"])` share rules); the default value is `md`.
+- `inset` swaps the stroke to `--rel-border-strong` and nudges the cap 1px down; in the `muted` variant it also darkens the fill.
+- A `<span>` slotted into `<rel-kbd>` picks up body-sm-regular type (Figma hint text) instead of the label type.
+- `<rel-kbd-group>` passes its `size` and `variant` to every generated key; `items` set as an attribute must be a JSON array string. Slotted `<rel-kbd>` children render after the generated keys with no automatic "+" separators — either use `items` or hand-write the whole shortcut.
+- The `item` and `label` parts exist only on `<rel-kbd-group>`; a standalone `<rel-kbd>` exposes no parts.
+- Since 1.5.0 `items` entries are named keys, so on a Mac `items='["Ctrl","Shift","P"]'` shows ⌃ ⇧ P (Control is a real Mac key). Use `"mod"` where you mean "Cmd on Mac, Ctrl elsewhere", or pass `platform="other"` to keep the words everywhere. Elsewhere, `"Escape"` now shows as Esc and `"PageUp"` as PgUp; plain words that are not named keys are unchanged.
+- `platform="auto"` reads `navigator.userAgentData.platform`, then `navigator.platform`. Server-rendered markup has no navigator and resolves to `other`, so a Mac viewer sees Ctrl until the element renders in the browser. Unknown `platform` values behave as `auto`.
+- No Figma guidance exists for Mac symbols (the Kbd component has Size, Variant and Inset only, checked 2026-10-09), so a symbol cap is an ordinary cap: same heights, same side padding as text (a ⌘ cap is about 30 / 33 / 43px wide at small / medium / large), not a narrower square.

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

@@ -39,40 +39,40 @@ A responsive CSS Grid layout component with automatic breakpoint handling. Provi
 </rel-layout>
 ```
 
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-layout.ts — do not edit; run readme-generate.mjs -->
-
-## API
-
-### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `gap` | `gap` | `string` | `"1rem"` | — |
-| `columns` | `columns` | `number` | `4` | — |
-| `responsive` | `responsive` | `boolean` | `true` | Reflected. |
-
-## Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| — | — | — | This element emits no custom events. |
-
-## Slots
-
-| Slot | Description |
-| --- | --- |
-| (default) | Main content. |
-
-## CSS Parts
-
-| Part | Description |
-| --- | --- |
-| — | None exposed. |
-
-<!-- readme-gen:end -->
-
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-layout.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `gap` | `gap` | `string` | `"1rem"` | — |
+| `columns` | `columns` | `number` | `4` | — |
+| `responsive` | `responsive` | `boolean` | `true` | Reflected. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Main content. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| — | None exposed. |
+
+<!-- readme-gen:end -->
+
 ## API
 
 ### Attributes/Properties

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

@@ -1,6 +1,6 @@
 # rel-menu
 
-`<rel-menu>` is the vertical action menu of the Reliability Design System (Figma "Menu", 6326:2931). It renders the rows you pass in `items` as a `role="menu"` list with hover, pressed, active, disabled and virtual-focus states, in one of six `type` modes: single-select rows (`default`, plus the `fixed` / `fit` width variants), checkbox rows, radio-style `select-option` rows, or `arrow` rows that open a submenu flyout. It renders into the light DOM (no shadow root). `<rel-menu-item>` is registered alongside it as a declarative placeholder. Use `<rel-menu>` inside a `<rel-popover>` or dropdown for context and overflow actions; for a horizontal application menu bar use `<rel-menubar>`, and for a form field that picks a value use `<rel-select>`.
+`<rel-menu>` is the vertical action menu of the Reliability Design System (Figma "Menu", 6326:2931). It renders the rows you pass in `items` as a `role="menu"` list with hover, pressed, active, disabled and virtual-focus states, in one of four `type` row shapes: plain single-select rows (`list`, the default), checkbox rows, radio-style `select-option` rows, or `arrow` rows that open a submenu flyout; `width` picks the sizing mode (`fixed` or `fit`) independently. It renders into the light DOM (no shadow root). `<rel-menu-item>` is registered alongside it as a declarative placeholder. Use `<rel-menu>` inside a `<rel-popover>` or dropdown for context and overflow actions; for a horizontal application menu bar use `<rel-menubar>`, and for a form field that picks a value use `<rel-select>`.
 
 ## Usage
 
@@ -19,9 +19,10 @@
 <!-- Rows with submenu flyouts -->
 <rel-menu id="file" type="arrow"></rel-menu>
 
-<!-- Width modes: fixed 300px (override with --rel-menu-width) or shrink to content -->
-<rel-menu type="fixed" style="--rel-menu-width: 240px"></rel-menu>
-<rel-menu type="fit"></rel-menu>
+<!-- Sizing modes: both 300px wide (override with --rel-menu-width); fixed caps the height at
+     --rel-menu-height (500px) and scrolls, fit hugs its rows. Combines with any type. -->
+<rel-menu width="fixed" style="--rel-menu-width: 240px"></rel-menu>
+<rel-menu type="checkbox" width="fit"></rel-menu>
 
 <!-- rel-menu-item is a registered placeholder: it renders nothing and rel-menu does not read it yet -->
 <rel-menu-item label="Rename" value="rename" icon="settings"></rel-menu-item>
@@ -84,10 +85,16 @@ actions.items = [...actions.items, { label: "Duplicate" }];
 
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
-| `type` | `type` | `"list" \| "checkbox" \| "select-option" \| "arrow" \| "default" \| "fixed" \| "fit"` | `"list"` | Row shape (Figma ".Menu Item" Type). `list` (default) = plain rows; `checkbox` = toggling rows with a checkbox; `select-option` = single-select rows with a trailing check. `arrow` is a code-only extension with no Figma counterpart: rows whose `submenu` opens a flyout. Because it rides this axis, submenus cannot currently be combined with checkbox or select-option rows — see the README. DEPRECATED values, all still working: `default` is the old spelling of `list`; `fixed` / `fit` were width modes and now set `width` instead, leaving the row shape at `list`. |
+| `type` | `type` | `"list" \| "checkbox" \| "select-option" \| "arrow" \| "default" \| "fixed" \| "fit"` | `"list"` | Row shape (Figma ".Menu Item" Type). `list` (default) = plain rows; `checkbox` = toggling rows with a checkbox; `select-option` = single-select rows with a leading radio (`role="menuitemradio"`). `arrow` is a code-only extension with no Figma counterpart: rows whose `submenu` opens a flyout. Because it rides this axis, submenus cannot currently be combined with checkbox or select-option rows — see the README. DEPRECATED values, all still working: `default` is the old spelling of `list`; `fixed` / `fit` were width modes and now set `width` instead, leaving the row shape at `list`. |
 | `width` | `width` | `"fixed" \| "fit"` | `undefined` | Sizing mode (Figma "Menu" Type). Both modes are `--rel-menu-width` (300px) wide — Figma's Fixed and Fit variants are both 300px — and the axis varies the HEIGHT: `fixed` pins the panel to `--rel-menu-height` (500px) and scrolls, `fit` hugs its rows. `fit` previously varied the width instead, which was the wrong dimension. This was also fused into `type`, where choosing a width silently forced plain rows and choosing a row shape silently forced the default width. Reflected. |
 | `size` | `size` | `"large" \| "medium" \| "small"` | `"large"` | Row size (Figma ".Menu Item" Size, 6326:616): large = 48px rows with body-lg labels (Figma default), medium = 40px / body-md, small = 32px / body-sm. Added in 1.4.7; before that rows were a fixed 36px. Reflected. |
-| `items` | `items` | `MenuItem[]` | `[]` | The rows to render, in order. Each entry is a `MenuItem` (`label`, optional `active`, `checked`, `disabled`, `submenu`, `open`). The array is copied on assignment, so mutate and reassign it to update the menu. |
+| `items` | `items` | `MenuItem[]` | `[]` | The rows to render, in order. Each entry is a `MenuItem` (`label`, optional `active`, `checked`, `disabled`, `submenu`, `open`, and, new in 1.5.0, `icon`). The array is copied on assignment, so mutate and reassign it to update the menu. |
+
+#### Methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `focusItem` | `focusItem(index: number)` | New in 1.5.0. Moves the virtual focus (the row `aria-activedescendant` names) to `index`, clamped to the rows; a negative index counts from the end, so `-1` is the last row. It moves neither DOM focus nor the ring: the row ring still follows the list's own keyboard focus. A menu button uses it to open on the first row (Enter, Space, ArrowDown) or the last (ArrowUp). |
 
 ### Events
 
@@ -143,11 +150,11 @@ actions.items = [...actions.items, { label: "Duplicate" }];
 
 ## Accessibility
 
-- The list (part `list`) is a `role="menu"` named "Menu" with `tabindex="0"`. DOM focus stays on this container; the row that has virtual focus is exposed through `aria-activedescendant` (every row has a stable id) and highlighted with a 2px `--rel-border-focus` outline inset 2px.
+- The list (part `list`) is a `role="menu"` named "Menu" with `tabindex="0"`. DOM focus stays on this container; the row that has virtual focus is exposed through `aria-activedescendant` (every row has a stable id) and, while the list has keyboard focus (`:focus-visible`), highlighted with a 2px `--rel-border-focus` outline inset 2px. There is no ring at rest or after a mouse click: the selected row is shown by its fill only, as in Figma.
 - Row roles follow `type`: `menuitem` for `default` / `arrow` / `fixed` / `fit`, `menuitemcheckbox` with `aria-checked` for `checkbox`, `menuitemradio` with `aria-checked` for `select-option`. Checkbox and select-option rows carry `aria-label` = the row label because their inner `<rel-checkbox>` / `<rel-radio>` control is rendered `inert` and `aria-hidden` (the row itself is the single click target).
 - Disabled rows have `aria-disabled="true"`, render at 40% opacity with a `not-allowed` cursor and ignore clicks and Enter / Space.
 - In `type="arrow"`, a row with a `submenu` has `aria-haspopup="menu"` and `aria-expanded`; the flyout (part `panel`) is a nested `role="menu"` of `menuitem` rows.
-- The container shows a 2px `--rel-border-focus` outline (2px offset) on `:focus-visible`.
+- The container shows a 2px `--rel-border-focus` outline (no offset) on `:focus-visible`.
 - No live-region announcements are made.
 
 | Key (virtual focus in the main list) | Action |
@@ -168,13 +175,13 @@ actions.items = [...actions.items, { label: "Duplicate" }];
 ## Notes / Edge Cases
 
 - **Known limitation — submenus are mutually exclusive with checkbox and select-option rows.** Figma models row shape and width as two independent axes, which is why they are now two props (`type` and `width`). Submenus, however, are a code-only feature with no Figma counterpart, and they ride the `type` axis as `type="arrow"` — so a checkbox menu with submenus cannot currently be expressed. Tracked for 3.0, where `arrow` would become its own boolean the same way the width values just moved off `type`.
-- `MenuItem` shape: `{ label: string; active?: boolean; checked?: boolean; disabled?: boolean; submenu?: MenuItem[]; open?: boolean }`. `active` marks the selected row (`default`, `fixed`, `fit`, `select-option`, submenu entries), `checked` the checkbox state, `submenu` / `open` the flyout rows and their initial visibility (`arrow` only).
+- `MenuItem` shape: `{ label: string; icon?: string; active?: boolean; checked?: boolean; disabled?: boolean; submenu?: MenuItem[]; open?: boolean }`. `active` marks the selected row (`default`, `fixed`, `fit`, `select-option`, submenu entries), `checked` the checkbox state, `submenu` / `open` the flyout rows and their initial visibility (`arrow` only). `icon` (new in 1.5.0) is a `rel-icon` name drawn before the label on `list` and `arrow` rows, at 20 / 18 / 16px for the large / medium / small sizes; checkbox and select-option rows ignore it.
 - The menu keeps an internal copy of `items`; user interaction updates that copy, never your array. Read the current state from the event detail (`item`, `checked`, `parent` / `sub`) — the objects in `e.detail` are the updated copies. Reassign `items` to change the rows.
 - Light DOM: `createRenderRoot()` returns the element, so the menu's CSS is injected as a `<style>` block and page styles can reach it. The parts are plain `part` attributes — target them with `rel-menu [part="list"]` / `rel-menu [part="panel"]`, not `::part()`.
 - `size` is reflected as an attribute and the row rules key off `rel-menu[size="…"]`; submenu rows follow the same size.
 - `type="arrow"`: hovering a row opens its submenu and leaving closes it, unless the row was clicked — a click locks the submenu open (click again to unlock). Keyboard opening also locks. A click outside the menu (detected through `composedPath`, so it works inside shadow roots) closes every submenu. Only one submenu is open at a time. Rows without a `submenu` in this mode behave like `default` rows and fire `rel-select`.
 - `rel-select` in `select-option` mode sets `active` on the chosen row and clears it on the others; the radio control mirrors that state. `rel-check` toggles independently per row.
-- The flyout is positioned `left: 100%` of its row with `z-index: 20` and stays inside the menu's box, so a menu placed at the right edge of a clipping container will have its flyout cut off; the menu itself deliberately does not use `overflow: hidden`.
+- The flyout opens in the browser top layer (Popover API, `popover="manual"`), so no ancestor clips it — not the menu's own scroller in `width="fixed"`, a card, a `rel-modal` or a scrolling sidebar (changed in 1.5.0; it used to be absolutely positioned inside its row and was cut off by all of those). It sits flush beside its row: to the right when it fits, flipped to the left when it would run off the right edge, shifted up when it would run past the bottom, and kept 8px inside the viewport. On an outside scroll it follows its row while the row is visible and closes once the row scrolls out of view. Without the Popover API it falls back to the old `left: 100%` placement.
 - `--rel-menu-width` (default 300px) is read only when `type="fixed"`; other types have `min-width: 220px` (`fit` drops it and uses `max-content`). Submenus have `min-width: 200px`.
 - `<rel-menu-item>` renders nothing and is not read by `<rel-menu>` today; it exists so markup can carry item metadata for future declarative support. Build menus from the `items` property.
 - This module imports `rel-checkbox`, `rel-radio` and `rel-icon`, so those elements are registered whenever `rel-menu` is loaded.