@reliability-design/web 1.4.6 → 1.4.8

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

@@ -1,151 +1,180 @@
-# rel-menu
-
-## Overview
-A rich menu component supporting three modes: default (selectable items), checkbox (multi-select), and arrow (nested submenus). Features keyboard navigation, focus management, disabled items, active states, and automatic submenu positioning.
-
-## Usage
-```html
-<!-- Default menu (single selection) -->
-<rel-menu id="defaultMenu" type="default"></rel-menu>
-<script>
-  const menu = document.getElementById('defaultMenu');
-  menu.items = [
-    { label: 'Edit', active: false },
-    { label: 'Copy', active: true },
-    { label: 'Paste', active: false },
-    { label: 'Delete', disabled: true }
-  ];
-  menu.addEventListener('item-selected', (e) => {
-    console.log('Selected:', e.detail.item.label);
-  });
-</script>
-
-<!-- Checkbox menu (multi-select) -->
-<rel-menu id="checkMenu" type="checkbox"></rel-menu>
-<script>
-  const checkMenu = document.getElementById('checkMenu');
-  checkMenu.items = [
-    { label: 'Show Grid', checked: true },
-    { label: 'Show Rulers', checked: false },
-    { label: 'Show Guides', checked: true }
-  ];
-  checkMenu.addEventListener('item-checked', (e) => {
-    console.log(e.detail.item.label, 'is', e.detail.checked ? 'checked' : 'unchecked');
-  });
-</script>
-
-<!-- Arrow menu (nested submenus) -->
-<rel-menu id="arrowMenu" type="arrow"></rel-menu>
-<script>
-  const arrowMenu = document.getElementById('arrowMenu');
-  arrowMenu.items = [
-    { label: 'File', submenu: [
-      { label: 'New' },
-      { label: 'Open' },
-      { label: 'Save', disabled: false }
-    ]},
-    { label: 'Edit', submenu: [
-      { label: 'Undo' },
-      { label: 'Redo' }
-    ]},
-    { label: 'Help' }
-  ];
-  arrowMenu.addEventListener('submenu-selected', (e) => {
-    console.log('Submenu item:', e.detail.sub.label, 'from', e.detail.parent.label);
-  });
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `type` | `"default" \| "checkbox" \| "arrow"` | `"default"` | Menu behavior mode |
-| `items` | `MenuItem[]` | `[]` | Array of menu items (see MenuItem interface below) |
-
-### MenuItem Interface
-```typescript
-interface MenuItem {
-  label: string;           // Display text
-  active?: boolean;        // Highlighted/selected state (default/arrow modes)
-  checked?: boolean;       // Checkbox state (checkbox mode)
-  disabled?: boolean;      // Disables interaction
-  submenu?: MenuItem[];    // Nested menu items (arrow mode)
-  open?: boolean;          // Submenu visibility state (arrow mode)
-}
-```
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `item-selected` | `{ item: MenuItem }` | Fired when an item is selected (default mode) |
-| `item-checked` | `{ item: MenuItem, checked: boolean }` | Fired when a checkbox item is toggled (checkbox mode) |
-| `submenu-selected` | `{ parent: MenuItem, sub: MenuItem }` | Fired when a submenu item is selected (arrow mode) |
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-sm-regular-font-size` - Font size
-- `--rel-body-xl-regular-font-size` - Chevron font size
-- `--rel-fonts-weight-body-medium` - Active item font weight
-- `--rel-body-sm-regular-line-height` - Line height
-
-### Spacing Tokens
-- `--rel-spacing-3xs` - Menu vertical padding
-- `--rel-spacing-xs` - Item padding, gaps
-- `--rel-spacing-sm` - Item horizontal padding
-- `--rel-spacing-2xs` - Checkbox gap, submenu offset
-
-### Color Tokens
-- `--rel-bg-surface` - Menu and submenu background
-- `--rel-text-default` - Default text color
-- `--rel-text-disabled` - Disabled item text
-- `--rel-bg-surface-elevated` - Hover and active background
-- `--rel-border-default` - Active press background
-- `--rel-bg-info` - Focus outline
-
-### Shadow Tokens
-- `--rel-shadows-shadow-300` - Menu and submenu drop shadow
-
-### Border Tokens
-- `--rel-border-radius-md` - Border radius
-
-## Accessibility
-- Uses `role="menu"` on container and `role="menuitem"` on items
-- Keyboard navigation with Arrow keys, Enter, Space, and Escape
-- Focus visible states with blue outline on menu and items
-- Disabled items have reduced color and are non-interactive
-- Close submenu when clicking outside the menu
-
-### Keyboard Interactions
-- `Arrow Down` - Move focus to next item
-- `Arrow Up` - Move focus to previous item
-- `Arrow Right` - Open focused submenu (arrow mode)
-- `Arrow Left / Escape` - Close all submenus
-- `Enter / Space` - Activate focused item
-- `Tab` - Focus menu container
-
-### Focus Behavior
-- Menu container receives focus on Tab
-- Focused items show blue outline with -2px offset (inside boundary)
-- Focus index tracked programmatically for keyboard navigation
-
-## Notes / Edge Cases
-- **Default mode**: Clicking an item sets `active: true` on that item and `active: false` on all others
-- **Checkbox mode**: Clicking toggles the `checked` state; also clicking the checkbox input itself triggers the same event
-- **Arrow mode**: Submenus open on hover (`mouseenter`) and clicking toggles them; clicking a submenu item closes the submenu
-- Submenus are positioned absolutely at `left: 100%` and `top: -<padding>` relative to parent item
-- Clicking outside the menu (document-level listener) closes all open submenus
-- Disabled items cannot be activated, checked, or expanded
-- In arrow mode, only one submenu can be open at a time (opening one closes others)
-- The menu has a minimum width of `220px`, submenus have `200px`
-- Chevron (▸) appears only on items with `submenu` in arrow mode
-- Native checkbox inputs are used in checkbox mode (16px × 16px)
+# 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>`.
+
+## Usage
+
+```html
+<!-- Single-select rows (default) at the three row heights: 48 / 40 / 32 px -->
+<rel-menu id="actions" size="large"></rel-menu>
+<rel-menu size="medium"></rel-menu>
+<rel-menu size="small"></rel-menu>
+
+<!-- Multi-select rows with a checkbox control -->
+<rel-menu id="view" type="checkbox"></rel-menu>
+
+<!-- Single-select rows with a radio control -->
+<rel-menu id="sort" type="select-option"></rel-menu>
+
+<!-- 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>
+
+<!-- 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>
+<rel-menu-item label="Delete" value="delete" disabled></rel-menu-item>
+```
+
+```js
+const actions = document.getElementById("actions");
+actions.items = [
+  { label: "Edit" },
+  { label: "Copy", active: true },
+  { label: "Paste" },
+  { label: "Delete", disabled: true },
+];
+actions.addEventListener("rel-select", (e) => {
+  e.detail.item.label; // the row that was activated (its copy has active: true)
+});
+
+const view = document.getElementById("view");
+view.items = [
+  { label: "Show grid", checked: true },
+  { label: "Show rulers" },
+];
+view.addEventListener("rel-check", (e) => {
+  e.detail.item.label;
+  e.detail.checked; // new state of that row
+});
+
+const file = document.getElementById("file");
+file.items = [
+  { label: "New", submenu: [{ label: "File" }, { label: "Folder" }] },
+  { label: "Open", submenu: [{ label: "Recent…" }, { label: "Browse…" }] },
+  { label: "Quit" }, // no submenu → fires rel-select
+];
+file.addEventListener("rel-submenu-select", (e) => {
+  e.detail.parent.label; // "New"
+  e.detail.sub.label;    // "Folder"
+});
+
+// The array is copied on assignment — reassign to update
+actions.items = [...actions.items, { label: "Duplicate" }];
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-menu.ts — do not edit; run readme-generate.mjs -->
+
+## Elements
+
+| Element | Class | Source |
+| --- | --- | --- |
+| `<rel-menu>` | `RelMenu` | `rel-menu.ts` |
+| `<rel-menu-item>` | `RelMenuItem` | `rel-menu.ts` |
+
+## API
+
+### `<rel-menu>`
+
+#### Attributes / Properties
+
+| 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`. |
+| `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. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-check` | `{ item: updated, checked: updated.checked }` | bubbles / composed | Fired when a `type="checkbox"` row is toggled. Detail: `{ item: MenuItem, checked: boolean }` — `item` is the updated row. |
+| `rel-select` | `{ item: updated }` | bubbles / composed | Fired when a row is activated in `default`, `select-option`, `fixed` or `fit` mode (and for submenu-less rows in `arrow` mode). Detail: `{ item: MenuItem }` — the row, now `active`. |
+| `rel-submenu-select` | `{ parent: this._items[parentIndex], sub: this._items[parentIndex]?.submenu?.[subIndex], }` | bubbles / composed | Fired when an entry inside a `type="arrow"` submenu is activated (the submenu closes). Detail: `{ parent: MenuItem, sub: MenuItem }`. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `panel` | A submenu flyout (`type="arrow"` only; light-DOM `[part="panel"]` attribute) |
+| `list` | The `role="menu"` root list (a light-DOM `[part="list"]` attribute) |
+
+### `<rel-menu-item>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `""` | Display text of the item. |
+| `value` | `value` | `string` | `""` | Value that identifies the item (not used by `rel-menu` today). |
+| `disabled` | `disabled` | `boolean` | `false` | Marks the item as non-interactive. |
+| `icon` | `icon` | `string` | `""` | `rel-icon` name to render before the label (not used by `rel-menu` today). |
+
+### 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
+
+- 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.
+- 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`.
+- No live-region announcements are made.
+
+| Key (virtual focus in the main list) | Action |
+| --- | --- |
+| ArrowDown / ArrowUp | Move virtual focus to the next / previous row (stops at the ends, no wrap) |
+| Home / End | First / last row |
+| Enter / Space | Activate the row: fires `rel-select` or `rel-check`; on an `arrow` row with a submenu, opens (locks) that submenu and moves virtual focus to its first entry |
+| ArrowRight | `arrow` type: open the focused row's submenu and focus its first entry |
+| ArrowLeft / Escape | Close any open submenu (Escape's propagation is stopped only when a submenu was open, so an enclosing popover does not close in the same keystroke) |
+
+| Key (virtual focus inside an open submenu) | Action |
+| --- | --- |
+| ArrowDown / ArrowUp | Next / previous submenu entry |
+| Home / End | First / last submenu entry |
+| Enter / Space | Activate the entry (fires `rel-submenu-select`, closes the submenu) |
+| ArrowLeft / Escape | Close the submenu and return virtual focus to its parent row |
+
+## 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).
+- 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`.
+- `--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.