@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-menu-item.md

@@ -0,0 +1,223 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-menu-item`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/menu/menu-item.js';` (registers the tag; side-effect import)
+- **Class** `LyraMenuItem`, also available unregistered from `@aceshooting/lyra-ui/components/layout/menu/menu-item.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-menu`, `lr-dropdown-item` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-menu` / `lr-menu-item`
+
+An anchored dropdown built around a consumer-supplied trigger element (typically an icon button)
+assigned to the `trigger` slot. First-party invention (no Web Awesome equivalent) — a close, drop-
+in-shaped replacement for reaching outside this library for a third-party dropdown to build a gear
+menu, an avatar menu, or a history row's overflow menu. Uses the WAI-ARIA "menu button" pattern —
+`role="menu"`/`role="menuitem"` with real roving DOM focus moving between actual focusable
+`<lr-menu-item>` rows — deliberately not a `role="listbox"`/`aria-activedescendant` shape (that's
+`<lr-select>`'s pattern instead).
+
+### `lr-menu`
+
+**Properties:**
+- `open: boolean = false` (reflected)
+- `placement?: Placement` (reflected — resolved through `rtlAwarePlacement()` (`internal/rtl.ts`),
+  then forwarded to `place()`; defaults to whatever `place()` itself defaults to. A `left`/`right`
+  side is mirrored under `dir="rtl"`, so e.g. `placement="left-start"` still anchors to the menu's
+  trailing edge instead of pinning to the physical left)
+- `label: string = 'Menu'` — accessible name for the `role="menu"` popup; override with something
+  specific (e.g. "Row actions") when a page has more than one menu. A host-level `aria-label`
+  attribute takes precedence over both this prop and the localized default (unset by default, so
+  a no-op for existing consumers), matching `lr-select`/`lr-model-select`'s
+  `this.getAttribute('aria-label') || <computed default>` precedence
+
+- `closeOnEscapeAnywhere: boolean = false` (attribute `close-on-escape-anywhere`) — lets Escape
+  close the menu when focus is on non-menu-item content slotted into the **default** slot, i.e.
+  rendered inside `[part="list"]`; item activation remains scoped to actual menu items. It has no
+  bearing on the `header`/`footer` slots, which sit outside the `role="menu"` list and always close
+  on Escape — so a menu that keeps its composed controls there never needs this property
+
+**Methods:** `show(focus: 'first' | 'last' = 'first')` opens the menu and moves roving focus to the
+first (or, with `'last'`, the last) non-disabled item; a no-op when already open.
+`hide(options?: { focusTrigger?: boolean })` closes it; a no-op when already closed. They are the
+imperative pair for the cases the slotted trigger can't express — a "Done"/"Apply" button *inside*
+the menu, a keyboard shortcut, a parent restoring UI state — without hand-reproducing the
+pending-focus bookkeeping. Both are deliberately thin: positioning, the outside-click listener, the
+`lr-show`/`lr-hide` events, and the initial focus move all stay in one place, so **writing `open`
+directly is fully supported and equivalent apart from the focus moves**. In particular the
+roving-tabindex reset is centralized, so a bare `el.open = false` also clears `activeIndex` and
+never leaves a stale `tabindex="0"` tab stop on the last active item. `hide()` never refocuses
+unless you ask: pass `{ focusTrigger: true }` for a dismissal with nowhere else for focus to land,
+and leave it off when the interaction that closed the menu already put focus somewhere the user
+chose (an outside click, a Tab out). Focus restoration lives in `hide()` rather than in the
+close branch precisely so teardown — disconnecting an open menu — can't steal focus.
+
+**Events:** `lr-show` (no detail — fires only when `open` transitions to `true`, not for markup
+that renders `open` true from the start), `lr-hide` (same first-render guard, opposite
+transition), `lr-menu-select` (`detail: { value }` — a consolidated re-fire of the activated
+`<lr-menu-item>`'s own `lr-menu-item-select`; always followed by the menu closing and focus
+returning to the trigger)
+
+**Slots:** `trigger` (the consumer's own trigger element — first assigned element wins if several
+are assigned; enhanced imperatively with `aria-haspopup="menu"`/`aria-expanded`/`aria-controls`
+since those attributes belong on the actual interactive trigger, which lives outside this
+component's shadow root), default (`<lr-menu-item>` elements, plus optionally plain `<hr>`
+dividers between groups — native `<hr>` already carries an implicit `separator` role),
+`header` and `footer` (composed, deliberately non-menu-item content — a filter/search field, a
+section title, an "Apply"/"Done" button, a count — rendered above/below the items inside
+`[part="popup"]` but **outside** the `role="menu"` list. Both collapse to no box at all while
+unfilled, so a menu that uses neither renders exactly as it did before they existed)
+
+Put composed controls in `header`/`footer` rather than the default slot. Non-item content in the
+default slot still works and is not deprecated at runtime (no warning is emitted), but it sits
+inside `role="menu"`, where ARIA permits only
+`menuitem`/`menuitemradio`/`menuitemcheckbox`/`group`/`separator` children — anything else is an
+`aria-required-children` violation. It is also not Tab-reachable from an item, and needs
+`closeOnEscapeAnywhere` before Escape will close the menu. The named regions have none of those
+problems.
+
+**CSS parts:** `trigger` (wrapper around the `trigger` slot — the positioning anchor), `popup` (the
+positioned floating panel), `header` (wrapper around the `header` slot, above the list and outside
+`role="menu"`; `display: none` while that slot is unfilled), `list` (the `role="menu"` container
+wrapping the default slot), `footer` (wrapper around the `footer` slot, below the list and outside
+`role="menu"`; `display: none` while that slot is unfilled)
+
+**Themeable custom properties:** shared tokens only (`--lr-color-surface`, `--lr-color-border`,
+`--lr-radius`, `--lr-shadow`, `--lr-space-xs`, `--lr-transition-fast`).
+
+**Optional peer deps:** none.
+
+### `lr-menu-item`
+
+Not meaningful standalone — it exists purely as `<lr-menu>`'s light-DOM child, the same
+relationship `<lr-option>` has to `<lr-combobox>`/`<lr-select>`. `role="menuitem"` and the
+roving `tabindex` both live on the host element itself (mirroring `<lr-tree-node>`), not an
+internal shadow-DOM button; `<lr-menu>` is the sole owner of this element's `tabIndex`.
+
+**Properties:**
+- `value: string = ''` — an id/value echoed back in the parent `<lr-menu>`'s `lr-menu-select`
+  detail
+- `disabled: boolean = false` (reflected — disables selection and excludes this item from
+  `<lr-menu>`'s roving-tabindex navigation entirely)
+- `destructive: boolean = false` (reflected — tints the row with `--lr-color-danger`, for a
+  dangerous action like "Delete")
+- `type: 'normal' | 'checkbox' = 'normal'` — `'checkbox'` (mirroring `wa-dropdown-item`'s identical
+  `type` option) renders `role="menuitemcheckbox"` in place of `role="menuitem"`, with `aria-checked`
+  reflecting `checked` and a checkmark glyph shown once `checked` is `true`. `'normal'` (the default)
+  renders and behaves exactly as before this option existed.
+- `checked: boolean = false` (reflected) — whether a `type="checkbox"` item is checked; meaningless
+  (ignored) for `type="normal"`
+
+**Methods:** `select(): void` — fires `lr-menu-item-select` (no-op while `disabled`). Called
+internally by this element's own click handler and by `<lr-menu>`'s Enter/Space keydown handling
+of the roving-focused item; also the cleanest way for a consumer/test to trigger selection
+programmatically instead of clicking the shadow-DOM `[part="base"]` element (see the gotcha below).
+For `type="checkbox"`, also toggles `checked` and fires `lr-menu-item-change` first.
+
+**Events:** `lr-menu-item-select` (no detail payload — `this.emit('lr-menu-item-select')` is
+called with no second argument, so `event.detail` is `null`, not `undefined`; fires on click, or
+when the parent `<lr-menu>`'s own Enter/Space keydown handling calls `select()` on the currently
+roving-focused item), `lr-menu-item-change` (`detail: { value, checked }` — fired when a
+`type="checkbox"` item is activated and its `checked` state toggled, in addition to — never instead
+of — `lr-menu-item-select`; never fired for `type="normal"`)
+
+**Slots:** default (the item's label content), `icon` (optional leading icon)
+
+**CSS parts:** `base` (the row — `role` lives on the host, not this part), `icon` (wrapper around
+the `icon` slot; not rendered/hidden entirely while the slot is empty), `label` (wrapper around the
+default slot), `checkmark` (the checkmark glyph shown when a `type="checkbox"` item is `checked`;
+not rendered at all for `type="normal"`)
+
+**Themeable custom properties:** shared tokens only (`--lr-radius`, `--lr-focus-ring-width`,
+`--lr-focus-ring-color`, `--lr-space-xs`, `--lr-space-s`, `--lr-color-brand-quiet`,
+`--lr-opacity-disabled`, `--lr-color-danger`, `--lr-color-danger-quiet`).
+
+**Optional peer deps:** none.
+
+### `lr-dropdown-item`
+
+Compatibility naming alias for `<lr-menu-item>`. It is a subclass of the same implementation,
+so `value`, `disabled`, `destructive`, `type`, `checked`, `select()`, checkbox events, and menu
+roving focus behave identically.
+
+**Slots:** default label content and optional `icon`.
+
+```html
+<lr-menu>
+  <button slot="trigger">Actions</button>
+  <lr-dropdown-item value="archive">Archive</lr-dropdown-item>
+</lr-menu>
+```
+
+```html
+<lr-menu label="Row actions">
+  <button slot="trigger" aria-label="More actions">⋮</button>
+  <lr-menu-item value="edit">Edit</lr-menu-item>
+  <lr-menu-item value="duplicate">Duplicate</lr-menu-item>
+  <hr />
+  <lr-menu-item value="delete" destructive>Delete</lr-menu-item>
+</lr-menu>
+<script type="module">
+  document.querySelector('lr-menu').addEventListener('lr-menu-select', (e) => console.log(e.detail.value));
+</script>
+```
+
+The popup is always rendered in the DOM (never `display:none`) so `.focus()` calls on its content
+work synchronously the instant it opens — closed state is conveyed via `visibility`/`opacity`
+instead. `visibility` is an inherited CSS property that pierces the `<slot>` projection boundary, so
+every closed-state `<lr-menu-item>` is automatically excluded from sequential (Tab-key)
+navigation with no separate JS bookkeeping. ArrowDown/ArrowUp *on the trigger while closed* also
+opens the menu, focusing the first/last non-disabled item respectively (mirrors native `<select>`).
+Once open, ArrowDown/ArrowUp move the roving focus among non-disabled items and wrap past either end
+(unlike `<lr-select>`'s clamped listbox nav); Home/End jump to the first/last non-disabled item;
+Enter/Space activate the focused item; Escape closes and refocuses the trigger. The arrow keys,
+Home/End, Enter/Space and type-ahead only respond when the triggering keydown event's own target is
+an actual `<lr-menu-item>` element; a keydown bubbling up from any other node inside the popup is
+ignored rather than misread as list navigation. Escape and Tab are the two deliberate exceptions.
+Escape from `header`/`footer` content always closes the menu and refocuses the trigger (mirroring
+`lr-popover`'s handling of arbitrary popup content), while Escape from non-item content in the
+*default* slot closes it only with `closeOnEscapeAnywhere` set. Tab never traps focus and never
+calls `preventDefault()` — the browser's own Tab navigation always proceeds untouched — and closes
+the menu only when focus is on its way *out* of `[part="popup"]`: with a focusable in the
+`header`/`footer` region on the far side of the keypress the menu stays open so native Tab can carry
+focus there, and with neither region filled Tab closes exactly as it always has. Tabbing past the
+popup's last focusable in either direction closes the menu, including from slotted non-item content
+— which previously left the menu open while focus walked out of the popup entirely. A printable
+keypress runs type-ahead: roving focus jumps to the next non-disabled item whose text starts with the
+accumulated buffer (cycling from just after the active item, buffer resets ~500ms after the last
+keystroke) — mirrors `<lr-select>`'s identical listbox type-ahead. A click outside both the trigger
+and the open popup also closes it, but deliberately does *not* refocus the trigger — the outside
+click itself already moved focus somewhere the user chose.
+
+**Known gotchas:**
+- `<lr-menu-item>`'s click handler lives on an inner shadow-DOM element (`[part="base"]`), not the
+  host — calling `.click()` directly on the `<lr-menu-item>` host element in a test does **not**
+  trigger selection; either click (or dispatch on) the element returned by
+  `menuItemEl.shadowRoot.querySelector('[part="base"]')`, or just call the item's own `select()`
+  method directly.
+- `lr-show`/`lr-hide` are suppressed on the very first render even if `open` is already `true`
+  in markup — only later `open` transitions fire them.
+- `lr-menu-item-select` carries no detail payload (`event.detail === null`); read
+  `event.target.value` instead. `<lr-menu>`'s own re-fired `lr-menu-select` is the one that
+  carries `detail: { value }`.
+- Tab never calls `preventDefault()` and never traps focus — the browser's own default Tab
+  navigation always proceeds untouched. It closes the menu only when Tab would leave
+  `[part="popup"]` entirely; when the `header`/`footer` region holds a focusable on the far side of
+  the keypress, the menu stays open instead and native Tab moves focus into it. With neither region
+  filled, Tab closes exactly as before.
+- Non-item content in the *default* slot is not Tab-reachable from an item — Tab from an
+  `<lr-menu-item>` still closes the menu when there is no `header`/`footer` focusable to move to,
+  even if a `<button>` is slotted alongside the items. Move such controls to `header`/`footer`.
+- `header`/`footer` emptiness is tracked from each slot's own `slotchange` and reflected on the host
+  as `data-has-header` / `data-has-footer` (plus `data-list-empty`, which suppresses the region
+  divider next to an empty list). They are internal styling hooks, not public API — don't set them
+  by hand — but they are why `[part="header"]`/`[part="footer"]` collapse cleanly: a
+  `[part]:empty` rule can never match a part that contains a slot, since Chromium counts the
+  whitespace-only text nodes Lit leaves there.
+- Only Escape and a committed selection refocus the trigger on close; a click outside does not.
+
+---

package/llms/components/lr-menu.md

@@ -0,0 +1,223 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-menu`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/menu/menu.js';` (registers the tag; side-effect import)
+- **Class** `LyraMenu`, also available unregistered from `@aceshooting/lyra-ui/components/layout/menu/menu.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-menu-item`, `lr-dropdown-item` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-menu` / `lr-menu-item`
+
+An anchored dropdown built around a consumer-supplied trigger element (typically an icon button)
+assigned to the `trigger` slot. First-party invention (no Web Awesome equivalent) — a close, drop-
+in-shaped replacement for reaching outside this library for a third-party dropdown to build a gear
+menu, an avatar menu, or a history row's overflow menu. Uses the WAI-ARIA "menu button" pattern —
+`role="menu"`/`role="menuitem"` with real roving DOM focus moving between actual focusable
+`<lr-menu-item>` rows — deliberately not a `role="listbox"`/`aria-activedescendant` shape (that's
+`<lr-select>`'s pattern instead).
+
+### `lr-menu`
+
+**Properties:**
+- `open: boolean = false` (reflected)
+- `placement?: Placement` (reflected — resolved through `rtlAwarePlacement()` (`internal/rtl.ts`),
+  then forwarded to `place()`; defaults to whatever `place()` itself defaults to. A `left`/`right`
+  side is mirrored under `dir="rtl"`, so e.g. `placement="left-start"` still anchors to the menu's
+  trailing edge instead of pinning to the physical left)
+- `label: string = 'Menu'` — accessible name for the `role="menu"` popup; override with something
+  specific (e.g. "Row actions") when a page has more than one menu. A host-level `aria-label`
+  attribute takes precedence over both this prop and the localized default (unset by default, so
+  a no-op for existing consumers), matching `lr-select`/`lr-model-select`'s
+  `this.getAttribute('aria-label') || <computed default>` precedence
+
+- `closeOnEscapeAnywhere: boolean = false` (attribute `close-on-escape-anywhere`) — lets Escape
+  close the menu when focus is on non-menu-item content slotted into the **default** slot, i.e.
+  rendered inside `[part="list"]`; item activation remains scoped to actual menu items. It has no
+  bearing on the `header`/`footer` slots, which sit outside the `role="menu"` list and always close
+  on Escape — so a menu that keeps its composed controls there never needs this property
+
+**Methods:** `show(focus: 'first' | 'last' = 'first')` opens the menu and moves roving focus to the
+first (or, with `'last'`, the last) non-disabled item; a no-op when already open.
+`hide(options?: { focusTrigger?: boolean })` closes it; a no-op when already closed. They are the
+imperative pair for the cases the slotted trigger can't express — a "Done"/"Apply" button *inside*
+the menu, a keyboard shortcut, a parent restoring UI state — without hand-reproducing the
+pending-focus bookkeeping. Both are deliberately thin: positioning, the outside-click listener, the
+`lr-show`/`lr-hide` events, and the initial focus move all stay in one place, so **writing `open`
+directly is fully supported and equivalent apart from the focus moves**. In particular the
+roving-tabindex reset is centralized, so a bare `el.open = false` also clears `activeIndex` and
+never leaves a stale `tabindex="0"` tab stop on the last active item. `hide()` never refocuses
+unless you ask: pass `{ focusTrigger: true }` for a dismissal with nowhere else for focus to land,
+and leave it off when the interaction that closed the menu already put focus somewhere the user
+chose (an outside click, a Tab out). Focus restoration lives in `hide()` rather than in the
+close branch precisely so teardown — disconnecting an open menu — can't steal focus.
+
+**Events:** `lr-show` (no detail — fires only when `open` transitions to `true`, not for markup
+that renders `open` true from the start), `lr-hide` (same first-render guard, opposite
+transition), `lr-menu-select` (`detail: { value }` — a consolidated re-fire of the activated
+`<lr-menu-item>`'s own `lr-menu-item-select`; always followed by the menu closing and focus
+returning to the trigger)
+
+**Slots:** `trigger` (the consumer's own trigger element — first assigned element wins if several
+are assigned; enhanced imperatively with `aria-haspopup="menu"`/`aria-expanded`/`aria-controls`
+since those attributes belong on the actual interactive trigger, which lives outside this
+component's shadow root), default (`<lr-menu-item>` elements, plus optionally plain `<hr>`
+dividers between groups — native `<hr>` already carries an implicit `separator` role),
+`header` and `footer` (composed, deliberately non-menu-item content — a filter/search field, a
+section title, an "Apply"/"Done" button, a count — rendered above/below the items inside
+`[part="popup"]` but **outside** the `role="menu"` list. Both collapse to no box at all while
+unfilled, so a menu that uses neither renders exactly as it did before they existed)
+
+Put composed controls in `header`/`footer` rather than the default slot. Non-item content in the
+default slot still works and is not deprecated at runtime (no warning is emitted), but it sits
+inside `role="menu"`, where ARIA permits only
+`menuitem`/`menuitemradio`/`menuitemcheckbox`/`group`/`separator` children — anything else is an
+`aria-required-children` violation. It is also not Tab-reachable from an item, and needs
+`closeOnEscapeAnywhere` before Escape will close the menu. The named regions have none of those
+problems.
+
+**CSS parts:** `trigger` (wrapper around the `trigger` slot — the positioning anchor), `popup` (the
+positioned floating panel), `header` (wrapper around the `header` slot, above the list and outside
+`role="menu"`; `display: none` while that slot is unfilled), `list` (the `role="menu"` container
+wrapping the default slot), `footer` (wrapper around the `footer` slot, below the list and outside
+`role="menu"`; `display: none` while that slot is unfilled)
+
+**Themeable custom properties:** shared tokens only (`--lr-color-surface`, `--lr-color-border`,
+`--lr-radius`, `--lr-shadow`, `--lr-space-xs`, `--lr-transition-fast`).
+
+**Optional peer deps:** none.
+
+### `lr-menu-item`
+
+Not meaningful standalone — it exists purely as `<lr-menu>`'s light-DOM child, the same
+relationship `<lr-option>` has to `<lr-combobox>`/`<lr-select>`. `role="menuitem"` and the
+roving `tabindex` both live on the host element itself (mirroring `<lr-tree-node>`), not an
+internal shadow-DOM button; `<lr-menu>` is the sole owner of this element's `tabIndex`.
+
+**Properties:**
+- `value: string = ''` — an id/value echoed back in the parent `<lr-menu>`'s `lr-menu-select`
+  detail
+- `disabled: boolean = false` (reflected — disables selection and excludes this item from
+  `<lr-menu>`'s roving-tabindex navigation entirely)
+- `destructive: boolean = false` (reflected — tints the row with `--lr-color-danger`, for a
+  dangerous action like "Delete")
+- `type: 'normal' | 'checkbox' = 'normal'` — `'checkbox'` (mirroring `wa-dropdown-item`'s identical
+  `type` option) renders `role="menuitemcheckbox"` in place of `role="menuitem"`, with `aria-checked`
+  reflecting `checked` and a checkmark glyph shown once `checked` is `true`. `'normal'` (the default)
+  renders and behaves exactly as before this option existed.
+- `checked: boolean = false` (reflected) — whether a `type="checkbox"` item is checked; meaningless
+  (ignored) for `type="normal"`
+
+**Methods:** `select(): void` — fires `lr-menu-item-select` (no-op while `disabled`). Called
+internally by this element's own click handler and by `<lr-menu>`'s Enter/Space keydown handling
+of the roving-focused item; also the cleanest way for a consumer/test to trigger selection
+programmatically instead of clicking the shadow-DOM `[part="base"]` element (see the gotcha below).
+For `type="checkbox"`, also toggles `checked` and fires `lr-menu-item-change` first.
+
+**Events:** `lr-menu-item-select` (no detail payload — `this.emit('lr-menu-item-select')` is
+called with no second argument, so `event.detail` is `null`, not `undefined`; fires on click, or
+when the parent `<lr-menu>`'s own Enter/Space keydown handling calls `select()` on the currently
+roving-focused item), `lr-menu-item-change` (`detail: { value, checked }` — fired when a
+`type="checkbox"` item is activated and its `checked` state toggled, in addition to — never instead
+of — `lr-menu-item-select`; never fired for `type="normal"`)
+
+**Slots:** default (the item's label content), `icon` (optional leading icon)
+
+**CSS parts:** `base` (the row — `role` lives on the host, not this part), `icon` (wrapper around
+the `icon` slot; not rendered/hidden entirely while the slot is empty), `label` (wrapper around the
+default slot), `checkmark` (the checkmark glyph shown when a `type="checkbox"` item is `checked`;
+not rendered at all for `type="normal"`)
+
+**Themeable custom properties:** shared tokens only (`--lr-radius`, `--lr-focus-ring-width`,
+`--lr-focus-ring-color`, `--lr-space-xs`, `--lr-space-s`, `--lr-color-brand-quiet`,
+`--lr-opacity-disabled`, `--lr-color-danger`, `--lr-color-danger-quiet`).
+
+**Optional peer deps:** none.
+
+### `lr-dropdown-item`
+
+Compatibility naming alias for `<lr-menu-item>`. It is a subclass of the same implementation,
+so `value`, `disabled`, `destructive`, `type`, `checked`, `select()`, checkbox events, and menu
+roving focus behave identically.
+
+**Slots:** default label content and optional `icon`.
+
+```html
+<lr-menu>
+  <button slot="trigger">Actions</button>
+  <lr-dropdown-item value="archive">Archive</lr-dropdown-item>
+</lr-menu>
+```
+
+```html
+<lr-menu label="Row actions">
+  <button slot="trigger" aria-label="More actions">⋮</button>
+  <lr-menu-item value="edit">Edit</lr-menu-item>
+  <lr-menu-item value="duplicate">Duplicate</lr-menu-item>
+  <hr />
+  <lr-menu-item value="delete" destructive>Delete</lr-menu-item>
+</lr-menu>
+<script type="module">
+  document.querySelector('lr-menu').addEventListener('lr-menu-select', (e) => console.log(e.detail.value));
+</script>
+```
+
+The popup is always rendered in the DOM (never `display:none`) so `.focus()` calls on its content
+work synchronously the instant it opens — closed state is conveyed via `visibility`/`opacity`
+instead. `visibility` is an inherited CSS property that pierces the `<slot>` projection boundary, so
+every closed-state `<lr-menu-item>` is automatically excluded from sequential (Tab-key)
+navigation with no separate JS bookkeeping. ArrowDown/ArrowUp *on the trigger while closed* also
+opens the menu, focusing the first/last non-disabled item respectively (mirrors native `<select>`).
+Once open, ArrowDown/ArrowUp move the roving focus among non-disabled items and wrap past either end
+(unlike `<lr-select>`'s clamped listbox nav); Home/End jump to the first/last non-disabled item;
+Enter/Space activate the focused item; Escape closes and refocuses the trigger. The arrow keys,
+Home/End, Enter/Space and type-ahead only respond when the triggering keydown event's own target is
+an actual `<lr-menu-item>` element; a keydown bubbling up from any other node inside the popup is
+ignored rather than misread as list navigation. Escape and Tab are the two deliberate exceptions.
+Escape from `header`/`footer` content always closes the menu and refocuses the trigger (mirroring
+`lr-popover`'s handling of arbitrary popup content), while Escape from non-item content in the
+*default* slot closes it only with `closeOnEscapeAnywhere` set. Tab never traps focus and never
+calls `preventDefault()` — the browser's own Tab navigation always proceeds untouched — and closes
+the menu only when focus is on its way *out* of `[part="popup"]`: with a focusable in the
+`header`/`footer` region on the far side of the keypress the menu stays open so native Tab can carry
+focus there, and with neither region filled Tab closes exactly as it always has. Tabbing past the
+popup's last focusable in either direction closes the menu, including from slotted non-item content
+— which previously left the menu open while focus walked out of the popup entirely. A printable
+keypress runs type-ahead: roving focus jumps to the next non-disabled item whose text starts with the
+accumulated buffer (cycling from just after the active item, buffer resets ~500ms after the last
+keystroke) — mirrors `<lr-select>`'s identical listbox type-ahead. A click outside both the trigger
+and the open popup also closes it, but deliberately does *not* refocus the trigger — the outside
+click itself already moved focus somewhere the user chose.
+
+**Known gotchas:**
+- `<lr-menu-item>`'s click handler lives on an inner shadow-DOM element (`[part="base"]`), not the
+  host — calling `.click()` directly on the `<lr-menu-item>` host element in a test does **not**
+  trigger selection; either click (or dispatch on) the element returned by
+  `menuItemEl.shadowRoot.querySelector('[part="base"]')`, or just call the item's own `select()`
+  method directly.
+- `lr-show`/`lr-hide` are suppressed on the very first render even if `open` is already `true`
+  in markup — only later `open` transitions fire them.
+- `lr-menu-item-select` carries no detail payload (`event.detail === null`); read
+  `event.target.value` instead. `<lr-menu>`'s own re-fired `lr-menu-select` is the one that
+  carries `detail: { value }`.
+- Tab never calls `preventDefault()` and never traps focus — the browser's own default Tab
+  navigation always proceeds untouched. It closes the menu only when Tab would leave
+  `[part="popup"]` entirely; when the `header`/`footer` region holds a focusable on the far side of
+  the keypress, the menu stays open instead and native Tab moves focus into it. With neither region
+  filled, Tab closes exactly as before.
+- Non-item content in the *default* slot is not Tab-reachable from an item — Tab from an
+  `<lr-menu-item>` still closes the menu when there is no `header`/`footer` focusable to move to,
+  even if a `<button>` is slotted alongside the items. Move such controls to `header`/`footer`.
+- `header`/`footer` emptiness is tracked from each slot's own `slotchange` and reflected on the host
+  as `data-has-header` / `data-has-footer` (plus `data-list-empty`, which suppresses the region
+  divider next to an empty list). They are internal styling hooks, not public API — don't set them
+  by hand — but they are why `[part="header"]`/`[part="footer"]` collapse cleanly: a
+  `[part]:empty` rule can never match a part that contains a slot, since Chromium counts the
+  whitespace-only text nodes Lit leaves there.
+- Only Escape and a committed selection refocus the trigger on close; a click outside does not.
+
+---

package/llms/components/lr-message-actions.md

@@ -0,0 +1,48 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-message-actions`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/message-actions/message-actions.js';` (registers the tag; side-effect import)
+- **Class** `LyraMessageActions`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/message-actions/message-actions.class.js`
+- **Family** `components/conversation/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-message-actions`
+
+The per-message action toolbar for `lr-chat-message`'s `actions` slot: opt-in built-ins (copy /
+regenerate / edit / feedback) that emit intent events, plus a default slot for custom controls (e.g.
+a slotted `lr-branch-picker`). `role="toolbar"` with WAI-ARIA APG roving-tabindex; ArrowLeft/
+ArrowRight (RTL-aware) plus Home/End move focus across every stop — built-ins and slotted controls
+alike — via `.focus()`. Only the plain-button built-ins (`regenerate`/`edit`) get their `tabindex`
+toggled by this component itself; a composite child (`lr-copy-button`, the `feedback` built-in, any
+slotted custom element) remains independently reachable via the page's native Tab order alongside the
+toolbar's single roving stop, since a shadow-root-internal focusable element can't be suppressed from
+outside its own component.
+
+**Properties:** `controls: MessageActionControl[] = []` (attribute: false) —
+`MessageActionControl = 'copy' | 'regenerate' | 'edit' | 'feedback'` (exported here); which built-ins
+render, in that order. `copyText: string = ''`
+(attribute `copy-text`) — required for the `copy` built-in to render at all. `feedbackValue: 'up' |
+'down' | null = null` (attribute `feedback-value`) — forwarded to the embedded, thumbs-only
+`lr-message-feedback` (its `reasons`/`commentable`/`detailFor` are never forwarded, so its detail
+panel never opens). `revealOnHover: boolean = false` (reflected, attribute `reveal-on-hover`) — hides
+the bar until the closest `lr-chat-message` ancestor is hovered or a control inside has focus.
+`label: string = ''` — accessible name override for the toolbar. `accessibleLabel: string | null =
+null` (attribute `aria-label`) — overrides the toolbar's computed accessible name, winning over
+`label` and the localized default; attribute-reflects from a host-level `aria-label`.
+
+**Events:** `lr-regenerate`/`lr-edit` — a built-in was activated, no detail. `lr-copy` —
+`detail: { text }`, surfaced by the embedded `lr-copy-button` (bubbles/composed already, not
+re-emitted). `lr-change`/`lr-submit` — bubble unchanged from the embedded, thumbs-only
+`lr-message-feedback`.
+
+**Slots:** default — additional controls (e.g. `lr-copy-button`, `lr-icon-button`,
+`lr-branch-picker`) appended after the built-ins; they participate in the toolbar's arrow-key
+navigation.
+
+**CSS parts:** `base` (the toolbar, `role="toolbar"`), `copy-button` (the embedded
+`lr-copy-button`), `regenerate-button`, `edit-button`, and `feedback` (the embedded
+`lr-message-feedback`).

package/llms/components/lr-message-feedback.md

@@ -0,0 +1,52 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-message-feedback`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/message-feedback/message-feedback.js';` (registers the tag; side-effect import)
+- **Class** `LyraMessageFeedback`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/message-feedback/message-feedback.class.js`
+- **Family** `components/conversation/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-message-feedback`
+
+Thumbs up/down for one assistant message, with an optional inline detail step (categorical reason
+chips + a free-text comment) that opens as a disclosure directly below the thumbs. Emits; never
+persists — a host reflects a previously-recorded rating back via `value` (+ `disabled` for a
+read-only display). Activating the pressed thumb again toggles it off to `null` unless its own detail
+panel is currently open, in which case that click re-opens the panel instead.
+
+**Properties:** `value: 'up' | 'down' | null = null` (reflected), `reasons: MessageFeedbackReason[] =
+[]` (attribute: false, each `{ id, label }`), `commentable: boolean = false` (reflected) adds a
+free-text comment field, `detailFor: 'down' | 'both' = 'down'` (attribute `detail-for`) — which
+rating opens the detail panel, and `disabled: boolean = false` (reflected) for a read-only display.
+
+**Methods:** `focus()` focuses the thumb matching the current `value` (the up thumb when `null`);
+`blur()` blurs both thumbs.
+
+**Events:** `lr-change` — `detail: { value: 'up' | 'down' | null }`, fired when a thumb's rating
+changes or clears. `lr-submit` — `detail: { value: 'up' | 'down'; reasonIds: string[]; comment:
+string }`, fired by the panel's submit button (`value` is never `null` here — the panel only exists
+for a set rating).
+
+**CSS parts:** `base` (the root), `thumbs` (wrapper around both thumb buttons), `up-button`,
+`down-button`, `panel` (the inline detail disclosure, only rendered when `reasons` is non-empty or
+`commentable` is set), `reasons` (the reason-chip group), `comment` (the comment `<textarea>`), and
+`submit-button`.
+
+**Themeable custom properties:** six pressed-state hooks, three per thumb —
+`--lr-message-feedback-up-active-color` (default `var(--lr-color-success)`),
+`--lr-message-feedback-up-active-bg` (default `var(--lr-color-success-quiet)`),
+`--lr-message-feedback-up-active-border` (default `var(--lr-color-success)`), and the thumbs-down
+trio `--lr-message-feedback-down-active-color`, `--lr-message-feedback-down-active-bg`,
+`--lr-message-feedback-down-active-border` (defaulting to `var(--lr-color-danger)`,
+`var(--lr-color-danger-quiet)`, `var(--lr-color-danger)`). Each styles the glyph, background, and
+border of its thumb only while that thumb is pressed. All six are declared as inline `var()`
+fallbacks at the point of use and never on `:host`, so each can be set on the element *or on any
+ancestor* — a whole transcript's feedback controls retint from one declaration. That shape is
+required because `::part(up-button)[aria-pressed='true']` is invalid CSS (Shadow Parts forbids an
+attribute selector after `::part()`), which previously left overriding the library-wide
+`--lr-color-success`/`--lr-color-danger` tokens as the only lever, repainting every other element
+reading them. Unset, each falls back to exactly the token its rule used before.

package/llms/components/lr-mind-map.md

@@ -0,0 +1,66 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-mind-map`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/mind-map/mind-map.js';` (registers the tag; side-effect import)
+- **Class** `LyraMindMap`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/mind-map/mind-map.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-mind-map`
+
+A radial expandable topic tree (NotebookLM Mind Maps): a spatial overview of a topic hierarchy where
+activating a topic drills in or hands the topic to the chat. Hierarchy, not network — no cross-links,
+no force simulation, no communities, no edge labels (that's `lr-graph`). Zero-dependency SVG; the
+radial layout is closed-form arithmetic, in its own `mind-map-layout.ts` module, mirroring
+`lr-word-cloud`'s dependency-free precedent.
+
+**Properties:**
+- `topics: LyraTopic[] = []` (attribute: false) — `LyraTopic { id: string; label: string; children?:
+  LyraTopic[] }`; a single root sits at the center, multiple roots hang off an implicit center hub
+- `label: string = ''` — accessible name for the SVG group and the implicit hub's text
+- `expandDepth: number = 1` (attribute `expand-depth`) — initial expansion depth (root + first
+  ring); expansion state afterward is component-managed per topic id and survives `topics`
+  reassignment
+
+**Events:** `lr-topic-select` (`detail: { id }`, a *leaf* topic was activated),
+`lr-topic-toggle` (`detail: { id, expanded }`, a parent topic was activated, or auto-expanded by
+keyboard descent).
+
+**Slots:** none.
+
+**CSS parts:** `base`, `svg` (the single-tab-stop focus target), `node`, `node-label`, `link`
+(parent-child connector), `focus-ring` (keyboard focus ring), `live-region` (visually hidden
+announcement region), `empty` (shown when `topics` is empty).
+
+**Themeable custom properties:** `--lr-mind-map-ring-gap` (default `6rem`, radius step per depth
+ring). `--lr-mind-map-node-hover-halo` (default `var(--lr-color-brand-quiet)`) — stroke color of
+the halo drawn around a topic node's dot on `:hover`, giving mouse users the same "this is
+clickable" feedback keyboard users already get from the drawn `focus-ring` part.
+
+**Optional peer deps:** none.
+
+```html
+<lr-mind-map style="height:480px" expand-depth="2"></lr-mind-map>
+<script>
+  document.querySelector('lr-mind-map').topics = [
+    { id: 'root', label: 'Computing history', children: [
+      { id: 'people', label: 'People', children: [{ id: 'ada', label: 'Ada Lovelace' }] },
+      { id: 'machines', label: 'Machines' },
+    ] },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- A user's explicit expand/collapse only ever overrides the `depth < expandDepth` default in the
+  direction chosen — reassigning `topics` (even with the same ids) never silently discards that
+  override.
+- Node-position transitions use `--lr-transition-base`, which already collapses to near-zero under
+  `prefers-reduced-motion: reduce` globally, so expansion snaps rather than tweening for a
+  reduced-motion user with no extra branching in this component.
+
+---