@reliability-design/web 1.4.8 → 1.4.10

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

@@ -1,218 +1,218 @@
-# rel-menubar
-
-`<rel-menubar>` is a horizontal application menubar (`role="menubar"`) in the style of a desktop app's File / Edit / View strip. Each child `<rel-menubar-menu label="…">` becomes a trigger button, and that menu's light-DOM children — `data-item` buttons, `data-separator` rules, `data-submenu` groups, `data-checkbox` labels and `data-radio-group` blocks — are read by the menubar and rendered into a fixed-position dropdown panel with full arrow-key navigation, optional bound keyboard shortcuts and `rel-menubar-select` / `rel-menubar-change` events. Use it for dense, command-style navigation in tools and admin surfaces. For one dropdown hanging off a single button use `rel-menu`; for site navigation with links use the Navbar recipe (`/docs/recipes/navbar`).
-
-## Usage
-
-```html
-<rel-menubar>
-  <rel-menubar-menu label="File">
-    <button data-item data-shortcut="Ctrl+N">New Tab</button>
-    <button data-item data-shortcut="Ctrl+Shift+N">New Window</button>
-    <div data-separator></div>
-    <button data-item disabled>Close</button>
-  </rel-menubar-menu>
-
-  <rel-menubar-menu label="Edit">
-    <button data-item data-shortcut="Ctrl+Z">Undo</button>
-    <button data-item data-shortcut="Ctrl+Y">Redo</button>
-    <div data-separator></div>
-    <button data-item data-shortcut="Ctrl+X">Cut</button>
-    <button data-item data-shortcut="Ctrl+C">Copy</button>
-    <button data-item data-shortcut="Ctrl+V">Paste</button>
-  </rel-menubar-menu>
-</rel-menubar>
-```
-
-### Width mode and disabled menus
-
-```html
-<!-- type="fit" (default) hugs its triggers; type="fixed" spans its container -->
-<rel-menubar type="fixed">
-  <rel-menubar-menu label="File">
-    <button data-item>New Tab</button>
-  </rel-menubar-menu>
-  <rel-menubar-menu label="Edit">
-    <button data-item>Undo</button>
-  </rel-menubar-menu>
-  <!-- a disabled menu keeps its trigger visible and focusable but never opens -->
-  <rel-menubar-menu label="View" disabled>
-    <button data-item>Zoom In</button>
-  </rel-menubar-menu>
-</rel-menubar>
-```
-
-### Submenus, checkbox items and radio groups
-
-```html
-<rel-menubar>
-  <rel-menubar-menu label="File">
-    <button data-item>New Tab</button>
-    <div data-separator></div>
-    <div data-submenu label="Share">
-      <button data-item value="email">Email link</button>
-      <button data-item value="messages">Messages</button>
-      <button data-item value="notes">Notes</button>
-    </div>
-  </rel-menubar-menu>
-
-  <rel-menubar-menu label="View">
-    <label data-checkbox>
-      <input type="checkbox" />
-      Always Show Bookmarks Bar
-    </label>
-    <label data-checkbox>
-      <input type="checkbox" checked />
-      Always Show Full URLs
-    </label>
-    <div data-separator></div>
-    <div data-radio-group name="profile" value="andy">
-      <button data-radio value="andy">Andy</button>
-      <button data-radio value="benoit">Benoit</button>
-      <button data-radio value="luis">Luis</button>
-    </div>
-  </rel-menubar-menu>
-</rel-menubar>
-```
-
-### Bound shortcuts and events
-
-```html
-<rel-menubar id="app-menubar" bind-shortcuts>
-  <rel-menubar-menu label="Edit">
-    <button data-item value="undo" data-shortcut="Mod+Z">Undo</button>
-    <button data-item value="redo" data-shortcut="Mod+Shift+Z">Redo</button>
-  </rel-menubar-menu>
-</rel-menubar>
-
-<script>
-  const bar = document.getElementById('app-menubar');
-  // { label: "Undo", value: "undo", shortcut: "Mod+Z" }
-  bar.addEventListener('rel-menubar-select', (e) => console.log('select', e.detail));
-  // { type: "checkbox", label, checked } | { type: "radio", name, value }
-  bar.addEventListener('rel-menubar-change', (e) => console.log('change', e.detail));
-</script>
-```
-
-### Authoring items
-
-Items are plain HTML placed inside a `<rel-menubar-menu>`; the menubar recognises them by data attribute and renders its own copy in the panel.
-
-| Attribute | Put it on | What it becomes |
-| --- | --- | --- |
-| `data-item` | `<button>` | A `role="menuitem"` row. Its text content is the label; `value` (optional) and `data-shortcut` are echoed in `rel-menubar-select`. A native `disabled` attribute renders the row `aria-disabled` and skips it for clicks and bound shortcuts. |
-| `data-shortcut` | a `data-item` button | Shortcut text shown right-aligned in the row, exactly as written. With `bind-shortcuts` it is also matched against keydowns: `+`-joined tokens, case-insensitive, `Mod` = Cmd on Apple / Ctrl elsewhere, plus `Ctrl`, `Alt`, `Shift`, `Meta`. |
-| `data-separator` | `<div>` | A `role="separator"` rule. |
-| `data-submenu` + `label` | `<div>` wrapping `data-item` buttons | A submenu trigger row (`aria-haspopup="menu"`) that opens a nested panel to the right on hover, click, Enter or ArrowRight. |
-| `data-checkbox` | `<label>` containing `<input type="checkbox">` | A `rel-checkbox` row. The label text is the element's own text nodes (or a `label` attribute); state lives on the wrapped `<input>`. |
-| `data-radio-group` + `name` + `value` | `<div>` wrapping `data-radio` buttons | A `rel-radio` group. `value` on the wrapper is the current selection and is rewritten on change; the chosen `data-radio` also gets `data-checked="true"`. |
-| `data-radio` + `value` | `<button>` inside a `data-radio-group` | One option; text content is its label. |
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-menubar.ts, rel-menubar-menu.ts — do not edit; run readme-generate.mjs -->
-
-## Elements
-
-| Element | Class | Source |
-| --- | --- | --- |
-| `<rel-menubar>` | `RelMenubar` | `rel-menubar.ts` |
-| `<rel-menubar-menu>` | `RelMenubarMenu` | `rel-menubar-menu.ts` |
-
-## API
-
-### `<rel-menubar>`
-
-#### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `bindShortcuts` | `bind-shortcuts` | `boolean` | `false` | Opt-in: actually bind the keys declared via `data-shortcut` on items (e.g. `data-shortcut="Ctrl+Z"`) instead of only displaying them; a "Mod" token means Cmd on Apple platforms and Ctrl elsewhere, and keystrokes that originate in inputs, textareas or contenteditable regions are ignored. |
-| `type` | `type` | `"fixed" \| "fit"` | `"fit"` | Width mode (Figma "Menu Bar" Type, 8699:4): `fit` sizes the bar to its triggers, `fixed` stretches it across its container (override the stretched width with `--rel-menubar-width`). The default stays `fit`, which is how the bar has always rendered. Reflected. |
-
-### Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| `rel-menubar-change` | `detail` | bubbles / composed | Fired when a `data-checkbox` item is toggled or a `data-radio` option is picked. Detail: `{ type: "checkbox", label, checked }` or `{ type: "radio", name, value }`. |
-| `rel-menubar-select` | `{ label: item.textContent?.trim() ?? "", value: item.getAttribute("value") ?? undefined, shortcut: item.getAttribute("data-shortcut") ?? undefined, }` | bubbles / composed | Fired when a regular `data-item` (in a panel or a submenu) is activated by click, Enter/Space or a bound shortcut. Detail: `{ label: string, value?: string, shortcut?: string }` taken from the item's text, `value` and `data-shortcut` attributes. |
-
-### Slots
-
-| Slot | Description |
-| --- | --- |
-| — | This element has no slots. |
-
-### CSS Parts
-
-| Part | Description |
-| --- | --- |
-| — | None exposed. |
-
-### `<rel-menubar-menu>`
-
-#### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `label` | `label` | `string` | `""` | Text of the trigger button the parent menubar renders for this menu. |
-| `disabled` | `disabled` | `boolean` | `false` | Renders this menu's trigger in the Figma State=Disabled style and stops it opening by pointer, keyboard or hover-switch. The trigger stays in the tab order and reachable with the arrow keys (`aria-disabled`, not the native `disabled` attribute), matching how disabled `data-item` rows behave. Reflected. |
-
-### Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| — | — | — | This element emits no custom events. |
-
-### Slots
-
-| Slot | Description |
-| --- | --- |
-| — | This element has no slots. |
-
-### CSS Parts
-
-| Part | Description |
-| --- | --- |
-| — | None exposed. |
-
-<!-- readme-gen:end -->
-
-## Accessibility
-
-- Roles follow the APG menubar pattern: the strip is `role="menubar"`; each trigger is a `<button role="menuitem" aria-haspopup="menu" aria-expanded="true|false">`; each dropdown is a `role="menu"` panel with `tabindex="-1"`; rows are `role="menuitem"` (disabled ones add `aria-disabled="true"`), separators are `role="separator"`, and a submenu trigger row carries `aria-haspopup="menu"` / `aria-expanded` with its own nested `role="menu"` panel.
-- Focus model: the triggers are real buttons in the tab order. When a menu opens from the keyboard, DOM focus moves to the panel itself and the highlighted row is exposed through `aria-activedescendant` (row ids are generated per menubar instance), so arrow keys move a virtual focus rather than DOM focus. `Escape` closes everything and returns DOM focus to the trigger that owned the menu.
-- Checkbox items render as `rel-checkbox` and radio groups as `rel-radio` inside the panel, so those rows carry the native checkbox / radiogroup semantics of those components.
-- There is no type-ahead and no wrap-around: arrow keys stop at the first / last trigger or row.
-- Bound shortcuts (`bind-shortcuts`) listen on `document`, skip events whose `defaultPrevented` is already set, skip keystrokes that start in an input, textarea, select or contenteditable, and call `preventDefault()` on a match.
-
-| Key | Where | Action |
-| --- | --- | --- |
-| `Tab` / `Shift+Tab` | anywhere | Native focus movement between the trigger buttons (and out of the menubar). |
-| `ArrowRight` / `ArrowLeft` | trigger | Move focus to the next / previous trigger (does not open it). |
-| `Enter` / `Space` / `ArrowDown` | trigger | Open that menu, focus the panel and highlight the first item. |
-| `Enter` / `Space` / `ArrowDown` | trigger of a `disabled` menu | Nothing — the trigger is reachable but never opens. |
-| `Escape` | trigger (menu open) | Close all menus and keep focus on the trigger. |
-| `ArrowDown` / `ArrowUp` | open panel | Highlight the next / previous item (clamped, no wrap). |
-| `Home` / `End` | open panel | Highlight the first / last item. |
-| `ArrowRight` | open panel, on a submenu row | Open the submenu and highlight its first item. |
-| `Enter` / `Space` | open panel | Activate the highlighted row: fire `rel-menubar-select` and close, toggle a checkbox, pick a radio option, or open a submenu. |
-| `Escape` | open panel | Close all menus and return focus to the trigger. |
-| `ArrowDown` / `ArrowUp` / `Home` / `End` | open submenu | Move the highlight inside the submenu. |
-| `ArrowLeft` / `Escape` | open submenu | Close only the submenu; the parent panel stays open and focused. |
-| `Enter` / `Space` | open submenu | Activate the highlighted sub-item: fire `rel-menubar-select`, close everything, refocus the trigger. |
-
-## Notes / Edge Cases
-
-- Both elements render into **light DOM** (`createRenderRoot()` returns the host): there are no slots, no `::part` hooks and no style encapsulation. The menubar injects its own `<style>` block; the `.menubar-trigger` / `.menubar-panel` / `.menu-item` class names are implementation details, not a styling contract.
-- `<rel-menubar-menu>` is a hidden data holder (`display: none`) — it never renders its children itself. The menubar discovers menus once, when it connects; menus added or removed later are not picked up until the menubar is re-attached. Item lists inside a menu are re-read on each render, so item changes show up the next time a panel opens.
-- Item content is flattened: a `data-item` row renders the button's `textContent` only, so markup inside the button (icons, `<rel-kbd>` chips) is not reproduced. Use `data-shortcut` for the shortcut hint — it is displayed verbatim, so `Mod+Z` is shown literally as "Mod+Z"; write `Ctrl+Z` if you want that text and only need Ctrl.
-- Panels are `position: fixed` (z-index 1000, submenus 1001), placed flush under the trigger / against the right edge of the submenu row, and repositioned on scroll. They are not moved into the top layer, so a `rel-modal` or other top-layer surface can cover them.
-- Panels are a fixed 300px wide, matching the Figma Menu component the bar is paired with; override with `--rel-menubar-panel-width`. There is no viewport clamping, so a panel opened near the right edge can overflow.
-- The bar follows Figma's Menu Bar geometry: 40px tall triggers (`spacing/xs` × `spacing/md` padding on a `body/lg` label) on a `bg/fill/neutral/default` surface with `border-radius/sm` and no border. The trigger whose menu is open takes the hover overlay plus a medium-weight label, which widens it by a pixel or two — that weight shift is in the Figma spec, not an artefact.
-- A `disabled` `<rel-menubar-menu>` renders its trigger in the disabled tone and refuses to open by click, hover-switch, Enter/Space/ArrowDown or a bound shortcut. It uses `aria-disabled`, not the native `disabled` attribute, so the trigger stays in the tab order — the same model the disabled `data-item` rows use.
-- With a menu already open the bar is in hover-switch mode: moving the pointer onto another trigger opens that menu, so a *click* on it arrives when it is already open and toggles it shut. Switch menus by hovering, or click twice.
-- Hover-switching between menus is armed only after a click has opened one; hovering triggers on a closed menubar does nothing. Clicking outside (checked via `composedPath`, so it works inside shadow roots) closes everything.
-- Disabled `data-item` buttons ignore pointer clicks and bound shortcuts but are still reachable with the arrow keys.
-- `rel-menubar-select` fires only for regular `data-item` rows (panel or submenu); checkbox and radio rows fire `rel-menubar-change` instead. Both events bubble and are composed.
-- Only one submenu can be open at a time, and submenus nest one level deep (a `data-submenu` inside a `data-submenu` is not rendered).
+# rel-menubar
+
+`<rel-menubar>` is a horizontal application menubar (`role="menubar"`) in the style of a desktop app's File / Edit / View strip. Each child `<rel-menubar-menu label="…">` becomes a trigger button, and that menu's light-DOM children — `data-item` buttons, `data-separator` rules, `data-submenu` groups, `data-checkbox` labels and `data-radio-group` blocks — are read by the menubar and rendered into a fixed-position dropdown panel with full arrow-key navigation, optional bound keyboard shortcuts and `rel-menubar-select` / `rel-menubar-change` events. Use it for dense, command-style navigation in tools and admin surfaces. For one dropdown hanging off a single button use `rel-menu`; for site navigation with links use the Navbar recipe (`/docs/recipes/navbar`).
+
+## Usage
+
+```html
+<rel-menubar>
+  <rel-menubar-menu label="File">
+    <button data-item data-shortcut="Ctrl+N">New Tab</button>
+    <button data-item data-shortcut="Ctrl+Shift+N">New Window</button>
+    <div data-separator></div>
+    <button data-item disabled>Close</button>
+  </rel-menubar-menu>
+
+  <rel-menubar-menu label="Edit">
+    <button data-item data-shortcut="Ctrl+Z">Undo</button>
+    <button data-item data-shortcut="Ctrl+Y">Redo</button>
+    <div data-separator></div>
+    <button data-item data-shortcut="Ctrl+X">Cut</button>
+    <button data-item data-shortcut="Ctrl+C">Copy</button>
+    <button data-item data-shortcut="Ctrl+V">Paste</button>
+  </rel-menubar-menu>
+</rel-menubar>
+```
+
+### Width mode and disabled menus
+
+```html
+<!-- type="fit" (default) hugs its triggers; type="fixed" spans its container -->
+<rel-menubar type="fixed">
+  <rel-menubar-menu label="File">
+    <button data-item>New Tab</button>
+  </rel-menubar-menu>
+  <rel-menubar-menu label="Edit">
+    <button data-item>Undo</button>
+  </rel-menubar-menu>
+  <!-- a disabled menu keeps its trigger visible and focusable but never opens -->
+  <rel-menubar-menu label="View" disabled>
+    <button data-item>Zoom In</button>
+  </rel-menubar-menu>
+</rel-menubar>
+```
+
+### Submenus, checkbox items and radio groups
+
+```html
+<rel-menubar>
+  <rel-menubar-menu label="File">
+    <button data-item>New Tab</button>
+    <div data-separator></div>
+    <div data-submenu label="Share">
+      <button data-item value="email">Email link</button>
+      <button data-item value="messages">Messages</button>
+      <button data-item value="notes">Notes</button>
+    </div>
+  </rel-menubar-menu>
+
+  <rel-menubar-menu label="View">
+    <label data-checkbox>
+      <input type="checkbox" />
+      Always Show Bookmarks Bar
+    </label>
+    <label data-checkbox>
+      <input type="checkbox" checked />
+      Always Show Full URLs
+    </label>
+    <div data-separator></div>
+    <div data-radio-group name="profile" value="andy">
+      <button data-radio value="andy">Andy</button>
+      <button data-radio value="benoit">Benoit</button>
+      <button data-radio value="luis">Luis</button>
+    </div>
+  </rel-menubar-menu>
+</rel-menubar>
+```
+
+### Bound shortcuts and events
+
+```html
+<rel-menubar id="app-menubar" bind-shortcuts>
+  <rel-menubar-menu label="Edit">
+    <button data-item value="undo" data-shortcut="Mod+Z">Undo</button>
+    <button data-item value="redo" data-shortcut="Mod+Shift+Z">Redo</button>
+  </rel-menubar-menu>
+</rel-menubar>
+
+<script>
+  const bar = document.getElementById('app-menubar');
+  // { label: "Undo", value: "undo", shortcut: "Mod+Z" }
+  bar.addEventListener('rel-menubar-select', (e) => console.log('select', e.detail));
+  // { type: "checkbox", label, checked } | { type: "radio", name, value }
+  bar.addEventListener('rel-menubar-change', (e) => console.log('change', e.detail));
+</script>
+```
+
+### Authoring items
+
+Items are plain HTML placed inside a `<rel-menubar-menu>`; the menubar recognises them by data attribute and renders its own copy in the panel.
+
+| Attribute | Put it on | What it becomes |
+| --- | --- | --- |
+| `data-item` | `<button>` | A `role="menuitem"` row. Its text content is the label; `value` (optional) and `data-shortcut` are echoed in `rel-menubar-select`. A native `disabled` attribute renders the row `aria-disabled` and skips it for clicks and bound shortcuts. |
+| `data-shortcut` | a `data-item` button | Shortcut text shown right-aligned in the row, exactly as written. With `bind-shortcuts` it is also matched against keydowns: `+`-joined tokens, case-insensitive, `Mod` = Cmd on Apple / Ctrl elsewhere, plus `Ctrl`, `Alt`, `Shift`, `Meta`. |
+| `data-separator` | `<div>` | A `role="separator"` rule. |
+| `data-submenu` + `label` | `<div>` wrapping `data-item` buttons | A submenu trigger row (`aria-haspopup="menu"`) that opens a nested panel to the right on hover, click, Enter or ArrowRight. |
+| `data-checkbox` | `<label>` containing `<input type="checkbox">` | A `rel-checkbox` row. The label text is the element's own text nodes (or a `label` attribute); state lives on the wrapped `<input>`. |
+| `data-radio-group` + `name` + `value` | `<div>` wrapping `data-radio` buttons | A `rel-radio` group. `value` on the wrapper is the current selection and is rewritten on change; the chosen `data-radio` also gets `data-checked="true"`. |
+| `data-radio` + `value` | `<button>` inside a `data-radio-group` | One option; text content is its label. |
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-menubar.ts, rel-menubar-menu.ts — do not edit; run readme-generate.mjs -->
+
+## Elements
+
+| Element | Class | Source |
+| --- | --- | --- |
+| `<rel-menubar>` | `RelMenubar` | `rel-menubar.ts` |
+| `<rel-menubar-menu>` | `RelMenubarMenu` | `rel-menubar-menu.ts` |
+
+## API
+
+### `<rel-menubar>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `bindShortcuts` | `bind-shortcuts` | `boolean` | `false` | Opt-in: actually bind the keys declared via `data-shortcut` on items (e.g. `data-shortcut="Ctrl+Z"`) instead of only displaying them; a "Mod" token means Cmd on Apple platforms and Ctrl elsewhere, and keystrokes that originate in inputs, textareas or contenteditable regions are ignored. |
+| `type` | `type` | `"fixed" \| "fit"` | `"fit"` | Width mode (Figma "Menu Bar" Type, 8699:4): `fit` sizes the bar to its triggers, `fixed` stretches it across its container (override the stretched width with `--rel-menubar-width`). The default stays `fit`, which is how the bar has always rendered. Reflected. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-menubar-change` | `detail` | bubbles / composed | Fired when a `data-checkbox` item is toggled or a `data-radio` option is picked. Detail: `{ type: "checkbox", label, checked }` or `{ type: "radio", name, value }`. |
+| `rel-menubar-select` | `{ label: item.textContent?.trim() ?? "", value: item.getAttribute("value") ?? undefined, shortcut: item.getAttribute("data-shortcut") ?? undefined, }` | bubbles / composed | Fired when a regular `data-item` (in a panel or a submenu) is activated by click, Enter/Space or a bound shortcut. Detail: `{ label: string, value?: string, shortcut?: string }` taken from the item's text, `value` and `data-shortcut` attributes. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| — | None exposed. |
+
+### `<rel-menubar-menu>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `""` | Text of the trigger button the parent menubar renders for this menu. |
+| `disabled` | `disabled` | `boolean` | `false` | Renders this menu's trigger in the Figma State=Disabled style and stops it opening by pointer, keyboard or hover-switch. The trigger stays in the tab order and reachable with the arrow keys (`aria-disabled`, not the native `disabled` attribute), matching how disabled `data-item` rows behave. Reflected. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| — | None exposed. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- Roles follow the APG menubar pattern: the strip is `role="menubar"`; each trigger is a `<button role="menuitem" aria-haspopup="menu" aria-expanded="true|false">`; each dropdown is a `role="menu"` panel with `tabindex="-1"`; rows are `role="menuitem"` (disabled ones add `aria-disabled="true"`), separators are `role="separator"`, and a submenu trigger row carries `aria-haspopup="menu"` / `aria-expanded` with its own nested `role="menu"` panel.
+- Focus model: the triggers are real buttons in the tab order. When a menu opens from the keyboard, DOM focus moves to the panel itself and the highlighted row is exposed through `aria-activedescendant` (row ids are generated per menubar instance), so arrow keys move a virtual focus rather than DOM focus. `Escape` closes everything and returns DOM focus to the trigger that owned the menu.
+- Checkbox items render as `rel-checkbox` and radio groups as `rel-radio` inside the panel, so those rows carry the native checkbox / radiogroup semantics of those components.
+- There is no type-ahead and no wrap-around: arrow keys stop at the first / last trigger or row.
+- Bound shortcuts (`bind-shortcuts`) listen on `document`, skip events whose `defaultPrevented` is already set, skip keystrokes that start in an input, textarea, select or contenteditable, and call `preventDefault()` on a match.
+
+| Key | Where | Action |
+| --- | --- | --- |
+| `Tab` / `Shift+Tab` | anywhere | Native focus movement between the trigger buttons (and out of the menubar). |
+| `ArrowRight` / `ArrowLeft` | trigger | Move focus to the next / previous trigger (does not open it). |
+| `Enter` / `Space` / `ArrowDown` | trigger | Open that menu, focus the panel and highlight the first item. |
+| `Enter` / `Space` / `ArrowDown` | trigger of a `disabled` menu | Nothing — the trigger is reachable but never opens. |
+| `Escape` | trigger (menu open) | Close all menus and keep focus on the trigger. |
+| `ArrowDown` / `ArrowUp` | open panel | Highlight the next / previous item (clamped, no wrap). |
+| `Home` / `End` | open panel | Highlight the first / last item. |
+| `ArrowRight` | open panel, on a submenu row | Open the submenu and highlight its first item. |
+| `Enter` / `Space` | open panel | Activate the highlighted row: fire `rel-menubar-select` and close, toggle a checkbox, pick a radio option, or open a submenu. |
+| `Escape` | open panel | Close all menus and return focus to the trigger. |
+| `ArrowDown` / `ArrowUp` / `Home` / `End` | open submenu | Move the highlight inside the submenu. |
+| `ArrowLeft` / `Escape` | open submenu | Close only the submenu; the parent panel stays open and focused. |
+| `Enter` / `Space` | open submenu | Activate the highlighted sub-item: fire `rel-menubar-select`, close everything, refocus the trigger. |
+
+## Notes / Edge Cases
+
+- Both elements render into **light DOM** (`createRenderRoot()` returns the host): there are no slots, no `::part` hooks and no style encapsulation. The menubar injects its own `<style>` block; the `.menubar-trigger` / `.menubar-panel` / `.menu-item` class names are implementation details, not a styling contract.
+- `<rel-menubar-menu>` is a hidden data holder (`display: none`) — it never renders its children itself. The menubar discovers menus once, when it connects; menus added or removed later are not picked up until the menubar is re-attached. Item lists inside a menu are re-read on each render, so item changes show up the next time a panel opens.
+- Item content is flattened: a `data-item` row renders the button's `textContent` only, so markup inside the button (icons, `<rel-kbd>` chips) is not reproduced. Use `data-shortcut` for the shortcut hint — it is displayed verbatim, so `Mod+Z` is shown literally as "Mod+Z"; write `Ctrl+Z` if you want that text and only need Ctrl.
+- Panels are `position: fixed` (z-index 1000, submenus 1001), placed flush under the trigger / against the right edge of the submenu row, and repositioned on scroll. They are not moved into the top layer, so a `rel-modal` or other top-layer surface can cover them.
+- Panels are a fixed 300px wide, matching the Figma Menu component the bar is paired with; override with `--rel-menubar-panel-width`. There is no viewport clamping, so a panel opened near the right edge can overflow.
+- The bar follows Figma's Menu Bar geometry: 40px tall triggers (`spacing/xs` × `spacing/md` padding on a `body/lg` label) on a `bg/fill/neutral/default` surface with `border-radius/sm` and no border. The trigger whose menu is open takes the hover overlay plus a medium-weight label, which widens it by a pixel or two — that weight shift is in the Figma spec, not an artefact.
+- A `disabled` `<rel-menubar-menu>` renders its trigger in the disabled tone and refuses to open by click, hover-switch, Enter/Space/ArrowDown or a bound shortcut. It uses `aria-disabled`, not the native `disabled` attribute, so the trigger stays in the tab order — the same model the disabled `data-item` rows use.
+- With a menu already open the bar is in hover-switch mode: moving the pointer onto another trigger opens that menu, so a *click* on it arrives when it is already open and toggles it shut. Switch menus by hovering, or click twice.
+- Hover-switching between menus is armed only after a click has opened one; hovering triggers on a closed menubar does nothing. Clicking outside (checked via `composedPath`, so it works inside shadow roots) closes everything.
+- Disabled `data-item` buttons ignore pointer clicks and bound shortcuts but are still reachable with the arrow keys.
+- `rel-menubar-select` fires only for regular `data-item` rows (panel or submenu); checkbox and radio rows fire `rel-menubar-change` instead. Both events bubble and are composed.
+- Only one submenu can be open at a time, and submenus nest one level deep (a `data-submenu` inside a `data-submenu` is not rendered).

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

@@ -52,12 +52,8 @@ A one-time-password input implementing the Figma "OTP Input" cell: one single-ch
   });
 </script>
 
-<!-- No separators: show-separator is a boolean attribute (presence = true),
-     so hide the dashes by setting the property -->
-<rel-otp id="otp-plain" length="6"></rel-otp>
-<script>
-  document.getElementById('otp-plain').showSeparator = false;
-</script>
+<!-- No separators ("false" switches a default-true boolean off, since 1.5.0) -->
+<rel-otp length="6" show-separator="false"></rel-otp>
 
 <!-- States -->
 <rel-otp value="123456" readonly></rel-otp>
@@ -102,7 +98,7 @@ A one-time-password input implementing the Figma "OTP Input" cell: one single-ch
 | `pattern` | `pattern` | `string \| null` | `null` | Native `pattern` attribute forwarded to every cell (per-character regex for form validation). |
 | `ariaLabel` | `aria-label` | `string \| null` | `null` | Accessible name of the whole group; defaults to "One-time password input". Each cell is additionally labelled "Digit/Character N of M". |
 | `invalid` | `invalid` | `boolean` | `false` | Error styling (danger border on every cell) and `aria-invalid="true"`. Reflected. |
-| `showSeparator` | `show-separator` | `boolean` | `true` | Renders the dash separator between groups. Boolean attribute: its presence means true — set the property to `false` to hide separators. Even when on, separators appear only if `length` divides evenly by `group-size`; see `groupSize`. |
+| `showSeparator` | `show-separator` | `boolean` | `true` | Renders the dash separator between groups. Presence or `""` means true; `show-separator="false"` (or the property set to `false`) hides them. Even when on, separators appear only if `length` divides evenly by `group-size`; see `groupSize`. |
 | `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Cell size on the shared field scale (square, border-box): `small` 32px, `medium` 40px, `large` 48px (the Figma OTP Input cell). `sm` / `md` / `lg` are deprecated aliases of the full words. Reflected. |
 
 #### Deprecated (still supported — removal targeted for 3.0)
@@ -163,7 +159,7 @@ A one-time-password input implementing the Figma "OTP Input" cell: one single-ch
 - `rel-change` fires on every edit; `rel-complete` fires right after it when all cells hold a valid character for the current mode — validate the code server-side, the component only checks the character set.
 - `input-mode` unset (`""`) falls back to the deprecated `type` prop (default `"numeric"`); set `input-mode` explicitly and it always wins.
 - The lowercase `inputmode` prop is the raw native keyboard hint, not the accepted character set — normally leave it unset.
-- `show-separator` is a boolean attribute: `show-separator="false"` still enables separators. Hide them with `el.showSeparator = false` or `group-size="0"`.
+- `show-separator="false"` hides the separators (since 1.5.0; before that any value enabled them), as do `el.showSeparator = false` and `group-size="0"`.
 - **Separators require an even split.** Grouping applies only when `length` divides evenly by `group-size`; otherwise the cells render as one ungrouped row. A separator marks a boundary between two equal groups, so a length that does not divide would put one before a lone trailing cell — `length="4"` with the default `group-size="3"` used to draw `3 – 1`. Affected lengths at the default group size are 4, 5, 7 and 8; each now renders ungrouped. To group a length of 4, set `group-size="2"` for `2 – 2`.
 - `required` is applied to the first cell only, so native form validation blocks submission when the code is empty but not when it is partial — check `e.detail.complete` yourself.
 - The `autocomplete` prop currently has no effect: every cell always renders `autocomplete="one-time-code"`.