@reliability-design/web 1.4.6 → 1.4.7

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

@@ -1,329 +1,218 @@
-# rel-menubar
-
-A horizontal menubar component with dropdown menus, submenus, checkbox items, and radio groups. Provides full keyboard navigation and accessibility features.
-
-## What It Is
-
-The menubar component consists of two custom elements:
-- `<rel-menubar>` - The root container that manages state and interactions
-- `<rel-menubar-menu>` - Individual menu definitions with their content
-
-Content is authored using semantic HTML with data attributes, allowing the component to enhance it with proper menubar behavior.
-
-## Basic Usage
-
-```html
-<rel-menubar>
-  <rel-menubar-menu label="File">
-    <button data-item>New Tab</button>
-    <button data-item>New Window</button>
-    <button data-item>Close</button>
-  </rel-menubar-menu>
-
-  <rel-menubar-menu label="Edit">
-    <button data-item>Undo</button>
-    <button data-item>Redo</button>
-    <div data-separator></div>
-    <button data-item>Cut</button>
-    <button data-item>Copy</button>
-    <button data-item>Paste</button>
-  </rel-menubar-menu>
-
-  <rel-menubar-menu label="View">
-    <button data-item>Zoom In</button>
-    <button data-item>Zoom Out</button>
-  </rel-menubar-menu>
-</rel-menubar>
-```
-
-## Submenu Example
-
-Use `data-submenu` attribute with a `label` attribute to create nested menus:
-
-```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>Email link</button>
-      <button data-item>Messages</button>
-      <button data-item>Notes</button>
-    </div>
-    <div data-separator></div>
-    <button data-item>Close</button>
-  </rel-menubar-menu>
-</rel-menubar>
-```
-
-## Checkbox Example
-
-Wrap a checkbox input in a label with `data-checkbox` attribute:
-
-```html
-<rel-menubar>
-  <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>
-  </rel-menubar-menu>
-</rel-menubar>
-```
-
-## Radio Group Example
-
-Use `data-radio-group` container with `data-radio` items:
-
-```html
-<rel-menubar>
-  <rel-menubar-menu label="Profile">
-    <div data-radio-group name="user-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>
-```
-
-## Shortcuts
-
-Add keyboard shortcuts as text using the `data-shortcut` attribute:
-
-```html
-<rel-menubar>
-  <rel-menubar-menu label="Edit">
-    <button data-item data-shortcut="Ctrl+Z">Undo</button>
-    <button data-item data-shortcut="Ctrl+Y">Redo</button>
-  </rel-menubar-menu>
-</rel-menubar>
-```
-
-Or use `<rel-kbd>` components in the button content for better styling:
-
-```html
-<rel-menubar>
-  <rel-menubar-menu label="Edit">
-    <button data-item>
-      Undo
-      <span style="margin-left: auto; display: flex; gap: 4px;">
-        <rel-kbd size="sm">Ctrl</rel-kbd>
-        <rel-kbd size="sm">Z</rel-kbd>
-      </span>
-    </button>
-  </rel-menubar-menu>
-</rel-menubar>
-```
-
-## Data Attributes
-
-### Menu Items
-
-| Attribute | Element | Description |
-|-----------|---------|-------------|
-| `data-item` | `<button>` | Standard clickable menu item |
-| `data-separator` | `<div>` | Visual separator line |
-| `data-submenu` | `<div>` | Container for submenu items (requires `label` attribute) |
-| `data-checkbox` | `<label>` | Checkbox item (must contain `<input type="checkbox">`) |
-| `data-radio-group` | `<div>` | Radio group container (requires `name` and `value` attributes) |
-| `data-radio` | `<button>` | Radio button item (requires `value` attribute) |
-| `data-shortcut` | `<button>` | Optional keyboard shortcut text |
-
-### Properties
-
-**rel-menubar-menu**
-- `label` (string) - The text displayed on the menubar trigger button
-
-## Events
-
-### rel-menubar-change
-
-Emitted when a checkbox is toggled or a radio button is selected.
-
-**Checkbox Event Detail:**
-```typescript
-{
-  type: "checkbox",
-  label: string,    // Label text of the checkbox
-  checked: boolean  // New checked state
-}
-```
-
-**Radio Event Detail:**
-```typescript
-{
-  type: "radio",
-  name: string,     // Name of the radio group
-  value: string     // Selected value
-}
-```
-
-**Usage Example:**
-```javascript
-const menubar = document.querySelector('rel-menubar');
-menubar.addEventListener('rel-menubar-change', (event) => {
-  const { type, label, checked, name, value } = event.detail;
-
-  if (type === 'checkbox') {
-    console.log(`Checkbox "${label}" is now ${checked ? 'checked' : 'unchecked'}`);
-  } else if (type === 'radio') {
-    console.log(`Radio group "${name}" selected: ${value}`);
-  }
-});
-```
-
-## Keyboard Navigation
-
-The menubar provides comprehensive keyboard support:
-
-| Key | Context | Action |
-|-----|---------|--------|
-| `Tab` / `Shift+Tab` | Menubar | Focus menubar triggers |
-| `ArrowLeft` / `ArrowRight` | Menubar triggers | Navigate between menu triggers |
-| `Enter` / `Space` | Focused trigger | Open the menu |
-| `ArrowDown` | Open menu | Move to first item or next item |
-| `ArrowUp` | Open menu | Move to previous item |
-| `ArrowRight` | Submenu item | Open submenu |
-| `ArrowLeft` | Open submenu | Close submenu and return to parent |
-| `Escape` | Open menu | Close menu and return focus to trigger |
-| `Enter` / `Space` | Menu item | Activate item (click, toggle checkbox, select radio) |
-
-## Interaction Behavior
-
-### Opening/Closing
-- Click a trigger to open its menu
-- Click outside to close all menus
-- When a menu is open, clicking another trigger switches to it
-- When a menu is open, hovering another trigger switches to it
-
-### Submenus
-- Click or hover a submenu item to open its submenu
-- Submenu appears to the right of the parent menu
-- ArrowRight/ArrowLeft navigate in/out of submenus
-
-### State Management
-- Checkbox state is maintained in the DOM
-- Radio group value is stored on the `data-radio-group` element
-- Selected radio items receive `data-checked` attribute
-
-## Accessibility
-
-- Proper ARIA roles and keyboard navigation
-- Focus management with visual focus indicators
-- Screen reader friendly with semantic HTML
-- Disabled items are properly marked and non-interactive
-- All interactive elements are keyboard accessible
-
-## Styling Tokens
-
-The component uses design tokens from the Reliability Design System:
-
-### Colors
-- `--rel-bg-surface-elevated` - Menubar background
-- `--rel-bg-neutral-elevated-1` - Trigger and item hover state
-- `--rel-border-default` - Borders
-- `--rel-border-default` - Separators
-- `--rel-text-label` - Text color
-- `--rel-bg-surface` - Panel background
-- `--rel-bg-info` - Focus outline and radio selected state
-
-### Typography
-- `--rel-fonts-font-family` - Font family (Poppins)
-- `--rel-body-sm-regular-font-size` - Default text size
-- `--rel-body-xs-regular-font-size` - Shortcut text size
-- `--rel-body-sm-regular-line-height` - Line height
-
-### Spacing
-- `--rel-spacing-3xs` (2px) - Menubar gap and panel padding
-- `--rel-spacing-2xs` (4px) - Trigger padding vertical
-- `--rel-spacing-xs` (8px) - Item padding vertical
-- `--rel-spacing-sm` (12px) - Trigger and item horizontal padding
-- `--rel-spacing-md` (16px) - Item padding and radio offset
-
-### Borders
-- `--rel-stroke-sm` (1px) - Border width
-- `--rel-stroke-md` (1.5px) - Radio border
-- `--rel-border-radius-xs` (2px) - Trigger border radius
-- `--rel-border-radius-sm` (8px) - Panel border radius
-
-### Shadows
-- `--rel-shadows-shadow-300` - Panel drop shadow
-
-### Z-Index
-- Menu panels: `z-index: 1000`
-- Submenu panels: `z-index: 1001`
-
-## Browser Support
-
-Compatible with all modern browsers that support:
-- Web Components (Custom Elements v1)
-- Shadow DOM
-- ES2020+ features
-
-## Framework Integration
-
-Works seamlessly with:
-- Vanilla JavaScript
-- Angular
-- React (via wrapper)
-- Vue
-- Any framework that supports Web Components
-
-## Complete Example
-
-```html
-<rel-menubar id="app-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>
-    <div data-submenu label="Share">
-      <button data-item>Email link</button>
-      <button data-item>Messages</button>
-      <button data-item>Notes</button>
-    </div>
-    <div data-separator></div>
-    <button data-item>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-menu label="View">
-    <button data-item>Zoom In</button>
-    <button data-item>Zoom Out</button>
-    <div data-separator></div>
-    <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>
-
-<script>
-  document.getElementById('app-menubar').addEventListener('rel-menubar-change', (e) => {
-    console.log('Menubar change:', e.detail);
-  });
-</script>
-```
+# 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`). Added in 1.4.8; 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).