@aceshooting/lyra-ui 5.0.0 → 5.1.0

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

@@ -0,0 +1,171 @@
+<!-- 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 slotted non-menu-item content inside the popup; item activation
+  remains scoped to actual menu items
+
+**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)
+
+**CSS parts:** `trigger` (wrapper around the `trigger` slot — the positioning anchor), `popup` (the
+positioned floating panel), `list` (the `role="menu"` container wrapping the default slot)
+
+**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; Tab closes without
+`preventDefault()`, letting the browser's own Tab navigation proceed untouched. All of this list-level
+keydown handling — Escape, Tab, the arrow keys, Home/End, and type-ahead alike — only responds 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. 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 closes the menu without `preventDefault()` or focus trapping — the browser's own default Tab
+  navigation proceeds untouched, only the (now-stale) open state is cleared.
+- 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,171 @@
+<!-- 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 slotted non-menu-item content inside the popup; item activation
+  remains scoped to actual menu items
+
+**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)
+
+**CSS parts:** `trigger` (wrapper around the `trigger` slot — the positioning anchor), `popup` (the
+positioned floating panel), `list` (the `role="menu"` container wrapping the default slot)
+
+**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; Tab closes without
+`preventDefault()`, letting the browser's own Tab navigation proceed untouched. All of this list-level
+keydown handling — Escape, Tab, the arrow keys, Home/End, and type-ahead alike — only responds 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. 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 closes the menu without `preventDefault()` or focus trapping — the browser's own default Tab
+  navigation proceeds untouched, only the (now-stale) open state is cleared.
+- 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,37 @@
+<!-- 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`.

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

@@ -0,0 +1,64 @@
+<!-- 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).
+
+**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.
+
+---

package/llms/components/lr-model-select.md

@@ -0,0 +1,144 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-model-select`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/model-select/model-select.js';` (registers the tag; side-effect import)
+- **Class** `LyraModelSelect`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/model-select/model-select.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-model-select`
+
+A provider/model picker that renders as a closed dropdown when a fixed `catalog` is available, or as a
+filterable free-text combobox when it isn't (or when `allow-custom` explicitly permits typing something
+outside the catalog). Form-associated (hand-rolled internals via `attachInternals()` directly, not the
+shared `FormAssociated` mixin — same reasoning as `lr-combobox`/`lr-select`: see the shared-foundation
+notes). Built on the same trigger-button/`aria-activedescendant` listbox technique `<lr-select>` uses
+and the filter-as-you-type suggestion-popup technique `<lr-combobox>` uses, without composing either
+element. First-party invention (no Web Awesome equivalent).
+Session-history/autofill restoration synchronously restores the model id and form entry without
+emitting `lr-change`.
+
+**Exported types:**
+- `LyraModelCatalogEntry { id: string; label: string }` — one catalog row.
+- `LyraModelCatalog = string[] | LyraModelCatalogEntry[]` — either every entry is a plain string (used
+  as both id and label) or every entry is a full `{ id, label }` row; the two shapes are not meant to be
+  mixed within one array.
+
+**Properties:**
+- `provider: string = ''` — informational only (e.g. `'ollama'`); rendered as a small leading badge.
+- `catalog?: LyraModelCatalog` (attribute: false) — the full model list. Omit (or leave empty) to fall
+  back to plain free-text entry.
+- `allowCustom: boolean = false` (attribute `allow-custom`, reflected) — let the user type/commit a
+  value that isn't in `catalog`, even when `catalog` is non-empty.
+- `label: string = ''` — optional visible title above the control, mirroring `<lr-select>`'s own
+  `label` exactly: rendered via a `[part="form-control-label"]` `<label>` paired with the control's
+  id, and once non-empty it takes over as the accessible-name source (an `aria-label` override is
+  then only consulted as the fallback). Empty (the default) keeps the original
+  `aria-label || placeholder || 'Model'` accessible-name chain untouched.
+- `hint: string = ''` — hint text below the field. Unset (the default): no hint chrome renders.
+- `errorText: string = ''` (attribute `error-text`) — error text below the field (overridden by
+  slotted `error` content). Unset (the default): no error chrome renders.
+- `placeholder: string = ''`
+- `spellcheck: boolean = true` — forwarded to the free-text mode's native `<input>`; no effect in
+  closed-dropdown mode (no native text input there). `spellcheck="false"` is parsed as `false` (a
+  custom converter, not Lit's presence-based `type: Boolean`, so the literal attribute string is
+  honored — matches `<lr-textarea>`/`<lr-date-input>`).
+- `autocapitalize: string = ''` — forwarded to the free-text mode's native `<input>`; empty omits
+  the attribute.
+- `autoCorrect: string = ''` (attribute `autocorrect`) — forwarded to the free-text mode's native
+  `<input>`'s own `autocorrect` (Safari/WebKit-specific); empty omits the attribute. Named
+  `autoCorrect` in JS purely to dodge a `lib.dom.d.ts` typing collision — the wire attribute is
+  still plain `autocorrect`.
+- `autocomplete: string = 'off'`, `inputMode: string = ''` (attribute `inputmode`), and
+  `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the free-text input;
+  they have no effect in closed-dropdown mode
+- `autocomplete: string = 'off'`, `inputMode: string = ''` (`inputmode`), and `enterKeyHint: string = ''`
+  (`enterkeyhint`) — forwarded to the free-text mode's native `<input>`.
+- `name: string = ''` (reflected)
+- `disabled: boolean = false` (reflected)
+- `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
+- `open: boolean = false` (reflected)
+- `value: string` — getter/setter (hand-rolled, not the `FormAssociated` mixin); the current model id,
+  `''` when nothing is selected. Writing it calls `internals.setFormValue()` synchronously. A named,
+  untouched model-select contributes `''` to `FormData` instead of omitting its key.
+
+**Mode switching:** `closedMode` (private) is `true` whenever `normalizedCatalog.length > 0 &&
+!allowCustom` — a non-empty `catalog` with `allowCustom` left `false` renders the closed dropdown
+trigger-button UI (`[part="trigger"]`, `role="combobox"` on a `<button>`, no typing). Any other
+combination (`catalog` empty/unset, or `allowCustom` true) renders the free-text `<input>` UI
+(`[part="combobox"]`/`[part="combobox-input"]`) with live substring filtering against the catalog (id or
+label, case-insensitive). The mode is re-evaluated on every render, so toggling `allowCustom` or clearing
+`catalog` at runtime switches modes live, repositioning the shared `[part="listbox"]` popover against
+whichever element is the active anchor.
+
+A `value` that isn't present in `catalog` (e.g. a model id saved from a provider whose live catalog has
+since changed) is never silently dropped: it's appended to the rendered option list as a synthetic,
+visually-distinct row (dashed border, italic label, "not in catalog" badge) computed fresh from
+`catalog` + `value` on every access, without ever mutating the `catalog` property itself.
+
+**Events:**
+- `lr-change` (`detail: { value: string; inCatalog: boolean }` — fired when a value is selected
+  from the listbox or committed in free-text mode; `inCatalog` reflects whether that value was
+  actually present in `normalizedCatalog`, so a consumer can flag a freshly-typed custom value
+  distinctly from a real catalog pick)
+- `blur` (no detail) — re-dispatched from the free-text mode's internal `<input>`'s own `blur`,
+  bubbling and composed unlike the native event. Closed-dropdown mode's trigger `<button>` has no
+  equivalent re-dispatch, matching `<lr-select>`'s own trigger.
+- `focus` (no detail) — re-dispatched from the free-text mode's internal `<input>`'s own `focus`,
+  for the same reason as `blur`.
+
+**Slots:** `hint` (custom hint content), `error` (custom error content).
+
+**CSS parts:** `form-control-label` (the `<label>` element — only rendered, and only contributes to
+the accessible name, once `label` is non-empty), `trigger` (closed-dropdown mode's
+`<button role="combobox">`, also its positioning anchor), `combobox` (free-text mode's input
+container, also its positioning anchor), `combobox-input` (the free-text `<input>`),
+`provider-badge` (the optional leading `provider` label), `listbox` (the options popover, shared by
+both modes), `option`, `option-label`, `option-badge` (the "not in catalog" badge on a synthetic
+stale-value row), `expand-icon` (the dropdown chevron, present in both modes), `hint` (the hint
+message), `error` (the error message)
+
+**Themeable custom properties:** shared tokens only — `--lr-space-xs/-s`,
+`--lr-color-border/-surface/-brand/-brand-quiet/-text-quiet`, `--lr-radius`, `--lr-shadow`,
+`--lr-focus-ring-width/-color/-offset`, `--lr-icon-button-size`, `--lr-transition-fast`,
+`--lr-opacity-disabled`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-model-select
+  provider="openai"
+  .catalog=${[
+    { id: 'gpt-4o', label: 'GPT-4o' },
+    { id: 'gpt-4o-mini', label: 'GPT-4o mini' },
+  ]}
+  value="gpt-4o"
+  placeholder="Choose a model…"
+  @lr-change=${(e) => setModel(e.detail.value, e.detail.inCatalog)}
+></lr-model-select>
+
+<!-- No fixed catalog yet: falls back to free-text entry -->
+<lr-model-select provider="ollama" placeholder="Type a model id…" allow-custom></lr-model-select>
+```
+
+**Known gotchas:**
+- `catalog` must be homogeneous — an array of plain strings, or an array of `{ id, label }` objects, not
+  a mix; `LyraModelCatalog` is a union of two array *types*, not an array of a union item type.
+- The synthetic "not in catalog" row only ever appears when `catalog` is non-empty and `value` isn't one
+  of its ids — with no `catalog` at all, there's no catalog list to diff `value` against, so no badge.
+- `value`/form-association here is hand-rolled via `attachInternals()` directly, not the shared
+  `FormAssociated` mixin — mirrors `lr-combobox`/`lr-select`'s identical divergence.
+- `aria-invalid`/`data-invalid` only reflect once the control has been blurred (touched) at least once,
+  matching `lr-select`'s identical pattern — validity styling never flashes on first render.
+- In free-text mode, the input's displayed text is `query` only while `open`; while closed it shows the
+  committed value's label — so setting `.value` programmatically doesn't require also touching the live
+  typed text.
+- `hint`/`errorText` mirror `<lr-select>`'s identical chrome, including the `aria-describedby` wiring
+  to the rendered `hint`/`error` ids — set on whichever element (`trigger` or `combobox-input`) owns
+  `role="combobox"` for the active mode.
+
+---