@aceshooting/lyra-ui 2.11.0 → 2.13.0

package/llms-full.txt

@@ -206,7 +206,13 @@ shared `FormAssociated` mixin — see gotchas).
 - `errorText: string = ''` (attribute `error-text` — static error copy shown below the hint;
   overridden by slotted `error` content when provided)
 - `open: boolean = false` (reflected)
-- `withClear: boolean = false` (attribute **`with-clear`** — not `clearable`, see gotchas)
+- `clearable: boolean = false` (reflected) — displays the clear button while a value is selected
+- `withClear: boolean = false` (attribute `with-clear`) — deprecated compatibility alias for
+  `clearable`; either property enables the same clear button
+- `autocomplete: string = 'off'`, `inputMode: string = ''` (attribute `inputmode`),
+  `enterKeyHint: string = ''` (attribute `enterkeyhint`), `spellcheck: boolean = true`,
+  `autocapitalize: string = ''`, and `autoCorrect: string = ''` (attribute `autocorrect`) — native
+  editing-assistance attributes forwarded to the internal filter input
 - `maxOptionsVisible: number = 3` (attribute `max-options-visible` — caps how many selected tags
   show before collapsing to `+N`)
 - `emptyText: string = 'No results'` (attribute `empty-text`)
@@ -229,6 +235,11 @@ shared `FormAssociated` mixin — see gotchas).
 - `selectedRows: ComboboxSourceRow[]` (read-only getter) — structured rows for the current
   selection, including any opaque `data` payload supplied by an async source. Selected async rows
   remain available after the query changes or a later source result no longer contains them
+- `selectionStart`, `selectionEnd`, and `selectionDirection` — selection getters/setters forwarded
+  to the internal input
+
+**Methods:** `focus(options?)`, `blur()`, `select()`, `setSelectionRange()`, and `setRangeText()`
+forward to the internal input. `setRangeText()` synchronizes the filter query and visible options.
 
 `ComboboxSourceRow = { value: string; label: string; sub?: string; icon?: unknown; badge?: string |
 number; accessibleLabel?: string; data?: unknown; dotColor?: string; group?: string; disabled?:
@@ -245,6 +256,7 @@ one bubbling/composed, non-cancelable plain `input` `Event`, immediately followe
 of `change` `Event`. Re-picking the current single value and programmatic/default/reset/restore
 writes are silent. The clear button emits one `lyra-clear` after its `input`/`change` pair.
 `lyra-show` and `lyra-hide` report listbox visibility transitions.
+The internal input's `focus` and `blur` are re-dispatched as bubbling, composed host events.
 
 **Slots:** default (`<lyra-option>` children), `label`, `hint`, `error` (overrides the `errorText`
 attribute when provided)
@@ -315,9 +327,8 @@ collection, while `form.reset()` still returns to the declarative selected defau
 synchronous and fires no `input`/`change` event.
 
 **Known gotchas:**
-- naming drift from Web Awesome parity: the shipped attribute is **`with-clear`**, not
-  `clearable` (which is what `<wa-combobox>` uses) — don't copy-paste WA docs assuming a 1:1
-  attribute name here.
+- `with-clear` remains supported for compatibility, but new code should use the mirrored
+  `clearable` property/attribute.
 - a host-level `aria-label` attribute on `<lyra-combobox>` now takes priority over `label`/
   `placeholder`/`"Combobox"` when resolving the accessible name on `[part="combobox-input"]` —
   previously it was silently ignored. Matches the same fallback on `<lyra-select>`.
@@ -716,7 +727,10 @@ shadow-internal native button doesn't participate in an ancestor form's submissi
 
 **Properties:**
 - `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected)
-- `appearance: 'filled' | 'outlined' | 'plain' = 'filled'` (reflected)
+- `appearance: 'accent' | 'filled' | 'outlined' | 'plain' = 'filled'` (reflected) — `'accent'` is a
+  loud, high-contrast filled tier (equivalent to `wa-button`'s own runtime-default appearance),
+  distinct from `'filled'` for `variant="neutral"` specifically (`'filled'` reads the ambient
+  surface color there; `'accent'` reads a solid neutral fill)
 - `size: 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected)
 - `type: 'button' | 'submit' | 'reset' = 'button'`
 - `loading: boolean = false` (reflected) — shows an internal spinner and disables the button without
@@ -734,12 +748,18 @@ unmodified; disabled while `disabled` or `loading`).
 
 **Themeable custom properties:** `--lyra-button-accent`, `--lyra-button-fill`,
 `--lyra-button-on-fill`, `--lyra-button-border` (each swapped by the active `variant`, default
-`neutral` falls back to plain text/surface/border tokens).
+`neutral` falls back to plain text/surface/border tokens), `--lyra-button-accent-fill`,
+`--lyra-button-accent-on-fill` (the `appearance="accent"` fill/foreground pair; `neutral` falls
+back to `--wa-color-neutral-fill-loud`/`-on-loud`, every other variant reuses that variant's own
+loud fill token), `--lyra-button-hover-brightness` (default `1.08`, the `:hover` filter intensity),
+`--lyra-button-active-scale` (default `0.9875`, the `:active` press-scale, disabled under
+`prefers-reduced-motion`).
 
 **Optional peer deps:** none.
 
 ```html
 <lyra-button variant="brand" appearance="filled">Save</lyra-button>
+<lyra-button variant="neutral" appearance="accent">Save</lyra-button>
 <lyra-button appearance="plain" aria-label="Close dialog"><svg slot="start">...</svg></lyra-button>
 ```
 
@@ -747,6 +767,9 @@ unmodified; disabled while `disabled` or `loading`).
 - A host `aria-label` is forwarded to the internal button as a literal string (for an icon-only
   button); an external `aria-labelledby`/`aria-describedby` idref is not copied across the shadow
   boundary.
+- Is form-associated (`static formAssociated = true` + `attachInternals()`), so it participates in
+  an ancestor `<form>.elements` the same way `wa-button` does — a sibling text field's own
+  Enter-to-submit lookup (which scans `form.elements` for a `type === 'submit'` control) finds it.
 
 ---
 
@@ -767,13 +790,17 @@ form-associated via the same `FormAssociated` mixin as `lyra-textarea`. Ships th
 - `errorText: string = ''` (attribute `error-text`)
 - `accessibleLabel: string | null = null` (attribute `aria-label`)
 - `autocomplete: string = ''`
+- `spellcheck: boolean = true` — forwarded to the native input, including `spellcheck="false"`
+- `autocapitalize: string = ''` / `autoCorrect: string = ''`
+- `inputMode: string = ''` / `enterKeyHint: string = ''`
 - `min?: number` / `max?: number` / `step?: number` (attribute: false — `type="number"` only)
 - `passwordVisible: boolean = false` (attribute `password-visible` — `type="password"` only)
 - `name`/`disabled`/`required` (from `FormAssociated`)
 
-**Events:** `lyra-input` (`detail: { value }`, fired on every user-driven edit), `lyra-change`
-(`detail: { value }`, fired on the native `change` timing), `blur`/`focus` (re-dispatched bubbling +
-composed from the internal native input's own `blur`/`focus`).
+**Events:** native-style composed `input` and `change`, plus `lyra-input` (`detail: { value }`,
+fired on every user-driven edit) and `lyra-change` (`detail: { value }`, fired on the native
+`change` timing), `blur`/`focus` (re-dispatched bubbling + composed from the internal native input's
+own `blur`/`focus`).
 
 **Slots:** `label`, `hint`, `error`.
 
@@ -798,6 +825,18 @@ composed from the internal native input's own `blur`/`focus`).
   `ElementInternals` — not a second hand-rolled regex check.
 - `type="password"` always renders the `password-toggle` button; there is no separate opt-out.
 
+## `lyra-number-input`
+
+A migration-friendly numeric alias of `lyra-input`. It forces `type="number"` while retaining the
+same form association, label/hint/error chrome, native editing passthrough, input/change events,
+and `min`/`max`/`step` validation. It exposes the same properties, slots, events, and CSS parts as
+`lyra-input`.
+
+## `lyra-time-input`
+
+A migration-friendly time alias of `lyra-input`. It forces the native `type="time"` while retaining
+the same form association, chrome, native editing passthrough, events, slots, and CSS parts.
+
 ---
 
 ## `lyra-phone-input`
@@ -851,8 +890,9 @@ interface PhoneNumberAdapter {
 - `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute `error-text`) —
   visible form-field chrome; each has a matching named slot.
 - `placeholder: string = ''` — forwarded to the native telephone input.
-- host `aria-label` — forwarded to the internal telephone input. Name precedence is `phoneLabel`,
-  host `aria-label`, visible `label`, then `placeholder`.
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — forwarded to the internal
+  telephone input. Name precedence is host `aria-label`, `phoneLabel`, visible `label`, then
+  `placeholder`.
 - `phoneLabel: string = ''` (attribute `phone-label`) — explicit accessible-name override for the
   native telephone input.
 - `countryLabel: string = 'Select'` (attribute `country-label`) — country-selector accessible name;
@@ -867,6 +907,8 @@ interface PhoneNumberAdapter {
 - readonly `input: HTMLInputElement | undefined` — the internal native telephone input.
 - readonly `inputValue: string` — editable formatted/partial text, which remains available even when
   canonical `value` is `''`.
+- `selectionStart`, `selectionEnd`, and `selectionDirection` — native selection getters/setters
+  forwarded to the telephone input
 - readonly `phoneStatus: PhoneNumberStatus` — current parse state. The host also reflects it through
   `data-phone-status`.
 - readonly `form`, `labels`, `validity`, `validationMessage`, `willValidate`, and
@@ -878,7 +920,9 @@ text remains in `inputValue`/the native input so validation never makes a number
 but its canonical submitted `value` is blank. Native validation feedback is anchored to the
 telephone input, not the adjacent country selector.
 
-**Methods:** `focus(options?)`, `blur()`, and `select()` forward to the native telephone input.
+**Methods:** `focus(options?)`, `blur()`, `select()`, `setSelectionRange()`, and `setRangeText()`
+forward to the native telephone input. Range-text edits reparse the number and synchronize the
+canonical value, form value, and validity.
 `setFormValue(value)`, `checkValidity()`, and `reportValidity()` come from `FormAssociated`.
 `form.reset()` restores the original declarative `value` and the default country.
 
@@ -1061,6 +1105,8 @@ Zero-dependency inline SVG trend chart (mirrors `<wa-sparkline>`).
 - `type: 'line' | 'bar' | 'area' = 'line'`
 - `min?: number` (defaults to data minimum)
 - `max?: number` (defaults to data maximum)
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the localized
+  generated summary on the internal SVG
 
 **Events:** none.
 
@@ -1081,9 +1127,9 @@ the reviewed family (pure CSS cascade, no JS/`getComputedStyle` bridging needed)
 ```
 
 **Known gotchas:**
-- Auto-sets `role="img"` + a descriptive `aria-label` ("Trend of N values, last X" / "No data" when
-  empty) — good default, but still just a single summary sentence with no tabular fallback; fine for
-  a glance-value sparkline, worth reconsidering if it's ever the *sole* representation of a metric.
+- The semantic `role="img"` and accessible name live on the SVG that owns the graphic. The generated
+  summary is localized, formats the last value with `effectiveLocale`, and can be replaced through
+  `accessibleLabel`/host `aria-label`. It remains a concise summary rather than a tabular fallback.
 - flat data (every value equal, so the auto-computed range spans zero) now renders a centered
   midline/mid-height bars instead of collapsing every point to the bottom edge, and a single-value
   series renders a visible flat line (a zero-length path was previously invisible). **Every** `type`
@@ -1113,6 +1159,8 @@ Country/language flag image. Flag artwork ships in a **separate, optional peer p
   alongside `src` since there's no `country`/`language` to derive a fallback `alt` from.)
 - `label?: string` (accessible name / `alt` text — **defaults to a localized, human-readable region
   name derived from the *resolved country* code via `Intl.DisplayNames` if omitted**, see gotchas)
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — takes precedence over `label`
+  and the derived region name; an explicit empty value marks the image decorative
 - `round: boolean = false` (reflected — circular crop)
 - `variant?: 'compact' | 'standard' | 'detailed'` (attribute `variant`, not reflected — picks a
   fidelity tier for the ~65 codes whose source art embeds a coat of arms/seal/emblem; every other
@@ -1132,9 +1180,8 @@ Country/language flag image. Flag artwork ships in a **separate, optional peer p
 **CSS parts:** `image`
 
 **Themeable custom properties:** `--lyra-flag-radius` (default `calc(var(--lyra-radius) * 0.33)` —
-≈2px at the library's default `--lyra-radius` of `0.375rem`; scales with `--lyra-radius` unless
-overridden directly — non-`round` corner radius); also consumes `--lyra-color-border` (the inset
-ring around the flag image).
+non-`round` corner radius), `--lyra-flag-aspect-ratio` (default `4 / 3`), and
+`--lyra-flag-object-fit` (default `cover`); also consumes `--lyra-color-border` for the inset ring.
 
 **Optional peer deps:** `@aceshooting/lyra-flags` — required for the component to actually render an
 image when `country` or `language` is used. Import `components/flag/flag-peer.js` once to opt into
@@ -1172,8 +1219,8 @@ import '@aceshooting/lyra-ui/components/flag/flag-peer.js';
 - Rendering is async even when the peer *is* installed: `src` resolves after an `import()` +
   resolver call, so there's a brief loading-skeleton window on first paint/attribute change — don't
   assume the `<img>` exists synchronously right after setting `country`/`language`.
-- if `label` is omitted, the accessible name (`alt`) falls back to a localized region name via
-  `Intl.DisplayNames([navigator.language], { type: 'region' })` (e.g. `"United Kingdom"`) instead of
+- if both `aria-label` and `label` are omitted, the accessible name (`alt`) falls back to a localized
+  region name via `Intl.DisplayNames([effectiveLocale], { type: 'region' })` (e.g. `"United Kingdom"`) instead of
   a bare code — for `language="en"` that's derived from `"GB"` (the mapped country), not `"EN"` (the
   language tag itself). Falls back further to the bare uppercase code if `Intl.DisplayNames` throws
   for an unrecognized region or isn't available. You can still pass an explicit `label` (e.g.
@@ -1265,6 +1312,9 @@ Loading placeholder (`text`/`circle`/`rect` shapes, `pulse`/`sheen` effects).
 - `label: string = 'Loading…'` — accessible name for this instance's own `role="status"` (rendered as
   visually-hidden text inside `[part="base"]`); override with a description of what's actually
   loading, e.g. `label="Loading chart"`
+- `announce: boolean = true` (reflected) — set false for decorative members of a skeleton group;
+  removes the status role, live-region state, and visually hidden announcement while preserving
+  the visual placeholder
 
 **Events:** none.
 
@@ -1273,7 +1323,8 @@ Loading placeholder (`text`/`circle`/`rect` shapes, `pulse`/`sheen` effects).
 **CSS parts:** `base`
 
 **Themeable custom properties:** `--lyra-skeleton-w`, `--lyra-skeleton-h` (set/cleared by the
-`width`/`height` properties; default `100%` / `1em`).
+`width`/`height` properties; default `100%` / `1em`) and shared `--lyra-transition-ambient` for
+the pulse/sheen timing.
 
 **Optional peer deps:** none.
 
@@ -1283,14 +1334,8 @@ Loading placeholder (`text`/`circle`/`rect` shapes, `pulse`/`sheen` effects).
 ```
 
 **Known gotchas:**
-- every instance is an independent, simultaneously-firing `role="status"` live region (set via
-  `willUpdate`) with its own visually-hidden `label` text (default `"Loading…"`). A realistic loading
-  state (e.g. a 10×5 skeleton table = 50 instances) mounts 50 separate live regions at nearly the same
-  tick — expect screen readers to announce the label dozens of times, not once, even if every
-  instance shares the same default `label`. A more specific per-instance `label` doesn't fix the
-  fan-out by itself; there's still no grouping primitive to dedupe it — if it matters, wrap your own
-  single `role="status"` region around the set of skeletons and mark the individual ones
-  `aria-hidden`.
+- Each instance announces by default. In a repeated skeleton layout, provide one parent status and
+  set `announce="false"` on the decorative child placeholders to avoid duplicate announcements.
 - no `lines`/`count` shorthand for "N lines of skeleton text" — stamp out N elements
   yourself.
 - Respects `prefers-reduced-motion` (both effects) — safe to leave as-is for that concern.
@@ -1371,25 +1416,27 @@ accent edge and value tint).
 
 ## `lyra-table`
 
-Presentational, sort/select-aware data table. **The host owns actual sorting/filtering/pagination**
-of `rows` — this component only renders and emits intents.
+Sort/select-aware data table. Sorting remains consumer-controlled; optional filtering, pagination,
+and loading chrome are built in while remaining controlled at the public API boundary.
 
 **Properties:**
-- `columns: TableColumn<T>[] = []` (attribute: false) — `{ key, label, sortable?, align?:
-  'start'|'end', priority?: 'medium'|'low', sticky?: boolean, cell: (row) => unknown }` —
+- `columns: TableColumn<T>[] = []` (attribute: false) — `{ key, label, headerCell?, width?,
+  minWidth?, sortable?, align?: 'start'|'end', priority?: 'medium'|'low', sticky?: boolean |
+  'start' | 'end', footer?, cellStyle?, cell: (row) => unknown }` —
   `priority` progressively hides that column via a `@container` query as `[part='base']` narrows
   (`'low'` hides first, under a ~900px container width; `'medium'` next, under ~640px; both
   breakpoints are fixed in `table.styles.ts`, not themeable tokens), reversible via
-  `[part='reveal-columns-button']`; `sticky` pins that column's header cell/cells to the inline-start
-  edge (`position: sticky`) while the table scrolls horizontally — multiple `sticky` columns stack
-  left-to-right (each measures every earlier sticky column's rendered width via
+  `[part='reveal-columns-button']`; `sticky` pins that column's header/cells to the logical start
+  (`true`/`'start'`) or end edge while the table scrolls horizontally — multiple sticky columns stack
+  in logical order (each measures every earlier sticky column's rendered width via
   `--lyra-table-sticky-offset`) instead of overlapping at the same edge; `footer` renders a
   sticky-bottom footer cell for that column, computed from every currently-rendered row (post-sort,
   pre-pagination) — e.g. a column total — omit it for a column with no footer value, and a
   `[part='foot']` (`<tfoot>`) only renders at all when at least one column defines `footer`;
   `cellStyle` is applied directly to the generated `<td>` via `styleMap` — e.g. a computed heat-tint
   background a `cell()`-returned inner element can't paint into the cell's own padding — omit it for
-  no per-cell style override (the default, unchanged output)
+  no per-cell style override (the default, unchanged output); `editable` enables double-click
+  editing, `editValue` supplies the editor value, and `editType` selects `text` or `number`
 - `columnsHidden: boolean = false` (attribute `columns-hidden`, reflected) — computed/read-only: true
   when a `priority` column is *actually* hidden right now by the `@container` breakpoints above, or
   `showAllColumns` force-visible mode is currently active. Measured via a `ResizeObserver` on
@@ -1407,6 +1454,36 @@ of `rows` — this component only renders and emits intents.
   when omitted, which is only safe while `rows` never reorders — set it whenever `rows` can be
   sorted/filtered/re-ordered across renders, or selection/click can silently attach to the wrong row
 - `selectedKey: string | number | null = null` (attribute: false) — **single**-selection only
+- `selectionMode: 'none'|'single'|'multiple' = 'none'` (attribute `selection-mode`, reflected) —
+  opt-in self-managed row selection; the default remains presentational
+- `selectedKeys: Set<string | number> = new Set()` (attribute: false) — the selected raw row keys
+  used by multiple selection
+- `filterable: boolean = false` (attribute `filterable`, reflected) — renders a localized search
+  field above the grid
+- `filterText: string = ''` (attribute `filter-text`) — controlled filter text
+- `filter?: (row: T, text: string) => boolean` (attribute: false) — typed predicate used by the
+  filter field; when omitted, rows are matched against their JSON representation
+- `filterLabel: string = ''` (attribute `filter-label`) and `filterPlaceholder: string = ''`
+  (attribute `filter-placeholder`) — optional localized-label overrides
+- `loading: boolean = false` (attribute `loading`, reflected) and `loadingLabel: string = ''`
+  (attribute `loading-label`) — renders a busy spinner and suppresses the grid while loading
+- `pageSize: number = 0` (attribute `page-size`) — positive values enable controlled pagination;
+  zero disables the pagination footer
+- `page: number = 1` (attribute `page`, reflected) — controlled current page
+- `totalItems: number = -1` (attribute `total-items`) — server-side total item count; `-1` derives
+  the total from filtered rows
+- `paginationMode: 'client'|'server' = 'client'` (attribute `pagination-mode`, reflected) — client
+  mode slices rows; server mode renders the supplied page unchanged
+- Editable columns emit `lyra-cell-edit` on commit and never mutate the supplied row object.
+- `groupBy?: (row: T) => string | number` (attribute: false) — inserts a non-focusable full-width
+  group row before each group
+- `groupLabel?: (key: string | number, rows: T[]) => unknown` (attribute: false) — custom group
+  header content; without it, the group key is rendered as text
+- `expandedContent?: (row: T) => unknown` (attribute: false) — enables a leading expand toggle and
+  renders a full-width detail row beneath expanded records
+- `canExpand?: (row: T) => boolean` (attribute: false) — optional per-row gate for expansion
+- `expandedKeys: Set<string | number> = new Set()` (attribute: false) — consumer-controlled expanded
+  state; update it in response to `lyra-row-expand-toggle`
 - `hasMore: boolean = false` (attribute `has-more`, reflected)
 - `moreLabel: string = 'Load more'` (attribute `more-label`)
 - `emptyHeading: string = 'No data'` (attribute `empty-heading`)
@@ -1417,17 +1494,27 @@ of `rows` — this component only renders and emits intents.
   reveal-button's label while `priority`-hidden columns are hidden)
 - `hideColumnsLabel: string = 'Show fewer columns'` (attribute `hide-columns-label` — the same
   button's label once they've been revealed)
+- `showAllColumns: boolean = false` (attribute `show-all-columns`, reflected) — forces responsive
+  priority columns visible and is updated by the built-in reveal button
 
 **Events:** `lyra-sort` (`detail: { key }`, fired on sortable-header activation), `lyra-row-click`
 (`detail: { row }`), `lyra-load-more` (fired on the "load more" button), `lyra-columns-hidden-change`
-(`detail: { hidden: boolean }`, fired only on a real `columnsHidden` transition)
+(`detail: { hidden: boolean }`, fired only on a real `columnsHidden` transition),
+`lyra-columns-revealed` (`detail: { revealed: boolean }`), and `lyra-row-expand-toggle`
+(`detail: { row, key }`; the table does not mutate `expandedKeys`), and
+`lyra-selection-change` (`detail: { keys }`) when selection is enabled, `lyra-filter-change`
+(`detail: { text }`), and `lyra-page-change` (`detail: { page }`) from the controlled
+filter/pagination surfaces, and `lyra-cell-edit` (`detail: { row, key, value }`) for editable
+columns
 
 **Slots:** none — content comes entirely from `columns`/`rows`.
 
 **CSS parts:** `base`, `table`, `head`, `header-cell`, `row`, `cell`, `more-button`, `sort-icon` (a
 chevron indicator shown on the active sortable header, rotated per `sortDir`), `reveal-columns-button`
 (shown only when `columnsHidden` is true), `foot` (the `<tfoot>`, only rendered when at least one
-column defines `footer`), `footer-row` (the single footer row), `footer-cell` (a single footer cell)
+column defines `footer`), `footer-row`, `footer-cell`, `expand-toggle-cell`, `row-expand-toggle`,
+`row-expand-icon`, `expanded-row`, `expanded-cell`, `filter-label`, `filter`, `loading`, and
+`pagination`, `cell-editor`, `group-row`, and `group-cell`
 
 **Themeable custom properties:** `--lyra-table-max-height` (default `none`; controls the scrollable
 body's `max-block-size`).
@@ -1510,6 +1597,9 @@ from its built-in default is treated as an explicit per-instance wording overrid
 **Events:** `lyra-page-change` (`detail: { page: number }`, bubbles and composes, non-cancelable) —
 emitted for a valid, different requested page. The host applies `event.detail.page` back to `page`
 after routing, fetching, or any other policy decision.
+The internal page input's `focus` and `blur` are also bridged as bubbling, composed host events.
+
+**Methods:** `focus(options?)` and `blur()` forward to the numeric page input.
 
 **Slots:** none.
 
@@ -1625,8 +1715,12 @@ immediately) or multi-format (click opens a small menu).
   not toggle it automatically
 - `label: string = 'Export'` — trigger button text; also feeds the format-choice menu's `aria-label`
   as `` `${label} format` `` so assistive tech gets an accessible name for the menu
+- `accessibleLabel: string = ''` (attribute `aria-label`) — overrides the trigger's accessible
+  name and feeds the localized format-menu name without changing the visible label
 - `open: boolean = false` (reflected)
 
+**Methods:** `focus(options?)` and `blur()` forward to the native trigger button.
+
 **Events:** `lyra-export` (`detail: { format: string }`, **cancelable** — call `preventDefault()` to
 substitute your own server-generated download instead of the built-in client-side one),
 `lyra-export-complete` (`detail: { format: 'csv' | 'json' }`, fires only after a non-cancelled
@@ -1684,6 +1778,9 @@ downloadBlob(content: string, filename: string, mime: string): void      // trig
   jump to the first/last item once open, Escape closes it and returns focus to the trigger button,
   and a completed export also returns focus to the trigger — not just Escape/click-outside as
   before.
+- the positioned menu is constrained to the inline/block space reported by the positioner, wraps
+  long localized format labels/descriptions, scrolls when necessary, and disables its transition
+  under reduced motion.
 
 ---
 
@@ -1697,6 +1794,13 @@ buttons, this has no code/JSON content model to adopt just to reuse the copy aff
 
 **Properties:**
 - `value: string = ''` — the plain text to copy.
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the localized
+  Copy/Copied accessible name without changing the icon
+- `disabled: boolean = false` (reflected)
+- `feedbackDuration: number = 1500` (attribute `feedback-duration`) — milliseconds before the
+  copied checkmark returns to the copy icon; finite values are clamped at zero
+
+**Methods:** `focus(options?)` and `blur()` forward to the native button.
 
 **Events:** `lyra-copy` (`detail: { text: string }`) — fires on activation, always with the current
 `value`, regardless of whether the OS clipboard write actually succeeded (same convention as
@@ -2112,10 +2216,11 @@ Steps an index through `[0, length)` on a fixed interval — play/pause for time
   change-tracking sees it and auto-pauses on `hidden = true`)
 
 **Methods:** `play()`, `pause()`, `toggle()`, `next()`, `previous()`, `goTo(index: number)` — all
-idempotent/clamped; `length <= 1` is a no-op degenerate case.
+idempotent/clamped; `length <= 1` is a no-op degenerate case. `focus(options?)` and `blur()` forward
+to the play button.
 
 **Events:** `lyra-play`, `lyra-pause` (no detail), `lyra-step` (`detail: { index }`, fired on every
-tick and manual step)
+tick and manual step); internal `focus`/`blur` are bridged as bubbling, composed host events.
 
 **Slots:** none.
 
@@ -2242,6 +2347,14 @@ click, or Enter/Space on the focused cell, fires `lyra-cell-click`.
   `6` Saturday) for a row that would otherwise render a label and, when it returns a string, uses it
   instead of the built-in `Intl.DateTimeFormat`-derived short weekday name. Unset (the default)
   reproduces today's exact locale-derived output.
+- `monthLabelText?: (jsMonth: number, year: number) => string | undefined` (attribute: false,
+  calendar mode only) — the month-axis analogue of `weekdayLabelText`: receives the real JS month
+  index (`0` January .. `11` December) and full year for a month boundary that would otherwise
+  render a label, and, when it returns a string, uses it instead of the built-in
+  `Intl.DateTimeFormat`-derived short month name. Unset (the default) reproduces today's exact
+  locale-derived output. Lets month labels track the same locale signal (e.g. an app's own i18n
+  store) as `weekdayLabelText` and the component's other localizable strings, instead of always
+  following the browser/OS-language default.
 - `colorSteps?: string[]` (attribute: false) — a discrete array (≥2 entries) of CSS colors used as
   exact ramp steps instead of linearly interpolating between `--lyra-heatmap-scale-lo`/`-hi`;
   governs both `mode`s and both `scale` values, discretizing whichever scale would otherwise
@@ -2599,6 +2712,12 @@ Chart.js wrapper every other `lyra-*-chart` tag subclasses; supports both a simp
 - `config?: Partial<ChartConfiguration>` (attribute: false) — deep-merged over the generated
   config; any nested key wins without clobbering sibling generated keys. This is the raw Chart.js
   escape hatch, so a caller-supplied `config.type` is passed through rather than normalized.
+- `accessibleLabel: string = ''` (attribute `accessible-label`) — canvas name override; a host
+  `aria-label` has highest precedence
+- `accessibleDescription: string = ''` (attribute `accessible-description`) — overrides the
+  localized data/trend summary
+- `showDataTable: boolean = false` (attribute `show-data-table`) — makes the always-available
+  accessible data table visible rather than screen-reader-only
 
 **Methods:** `resetZoom()` (reset any active zoom/pan to the original view), `refreshTheme()`
 (forces a redraw so the `--lyra-chart-*` tokens below are re-read from the current computed style —
@@ -2642,9 +2761,8 @@ subset actually used.
 ```
 
 **Known gotchas:**
-- `type` at the `lyra-chart` (core) level is completely unchecked — `buildConfig()` passes it
-  straight to Chart.js as-is, so `<lyra-chart type="pie">` already works today with no subclass
-  needed. Each typed subclass below locks its *own* `type` via a real prototype accessor (see the
+- supported `type` values are normalized before reaching Chart.js; unknown runtime attribute or
+  property values fall back to `line`. Each typed subclass below locks its *own* `type` via a real prototype accessor (see the
   typed-subclasses section) — a genuine runtime lock, not just a compile-time default.
 - no global theme-broadcast event exists to auto-retheme an already-drawn chart on a theme switch —
   a consumer flipping something upstream (e.g. a `data-theme` attribute) that doesn't otherwise
@@ -2678,6 +2796,9 @@ subset actually used.
   changed since the last draw (e.g. an unrelated property/state update, or a bare `requestUpdate()`).
   `refreshTheme()` calls `draw()` directly and is unaffected by either gate — it always redraws, since
   a theme change isn't reflected in any tracked property.
+- Chart.js receives `effectiveLocale`; generated summary values use the same locale. Cartesian y/y2
+  axes swap logical sides under RTL, and host `aria-label` is forwarded to the canvas and data-table
+  caption.
 
 ---
 
@@ -2746,11 +2867,18 @@ passthrough). Not a subclass of `LyraChart`.
   column in a stacked chart. Empty (the default) reproduces the exact existing output: no bar
   carries `data-selected`. This component takes no opinion on what the highlight looks like, only
   which bars it applies to — style it via `::part(bar)[data-selected]`.
+- `minBarHeight?: number` (attribute `min-bar-height`) — optional minimum visible bar height for
+  small non-zero values
+- `accessibleLabel?: string` (attribute `accessible-label`) — SVG accessible-name override; a host
+  `aria-label` wins
 
 **Events:** `lyra-point-click` — fired when a bar/point is activated (click, or Enter/Space while
 focused). `detail: { datasetIndex: number, index: number, label: string | undefined, value: number
 | null }` — same shape as `lyra-chart`'s `lyra-point-click`.
 
+The axis gutter/title and y-axis labels mirror to logical start under RTL. Built-in mark summaries
+are complete localized templates and format values with `effectiveLocale`.
+
 **Performance:** rendering is `IntersectionObserver`-gated and content-signature-memoized — `render()`
 skips recomputing the grid/marks (and reuses the previous `TemplateResult`) while the host is scrolled
 off-screen, or when none of the content-affecting properties (`type`, `labels`, `datasets`, `legend`,
@@ -2880,6 +3008,13 @@ browser). Does **not** extend `LyraChart` — a deliberately bespoke API.
 - `height: string = '280px'`
 - `yLabel: string = ''` (attribute `y-label`)
 - `beginAtZero: boolean = true` (attribute `begin-at-zero`)
+- `accessibleLabel: string = ''` (attribute `accessible-label`) — canvas name override; host
+  `aria-label` wins
+- `accessibleDescription: string = ''` (attribute `accessible-description`) — overrides the
+  localized five-number summary
+- `showDataTable: boolean = false` (attribute `show-data-table`) — reveals the accessible data table
+
+**Methods:** `refreshTheme()` re-reads canvas theme custom properties after an ancestor theme change.
 
 **Events:** none.
 
@@ -2903,9 +3038,11 @@ independently of the base `chart-loader.ts`).
 ```
 
 **Known gotchas:**
-- no raw `config` passthrough (unlike every other chart tag) — limited to
-  `labels`/`boxes`/`legend`/`height`/`yLabel`/`beginAtZero`; can't reach the underlying
+- no raw `config` passthrough — limited to the properties above; can't reach the underlying
   controller's own options (`itemRadius`, `outlierRadius`, `coef`).
+- Chart.js receives `effectiveLocale`; generated numeric summaries use it, the y axis moves to
+  logical start in RTL, canvas tooltip/axis colors are token-driven, and animation is disabled
+  under reduced motion.
 - The peer-dependency-missing failure path (`.catch()` → warn + resolve `null`) is untested —
   verify it manually if shipping without the peer installed.
 
@@ -3030,8 +3167,11 @@ parsing (that's left entirely to the host).
   **before** (and takes precedence over) `allowedMimeTypes`
 - `maxFileSize: number = 0` (attribute `max-file-size` — bytes; `0` disables the check)
 - `label: string = 'Drop files here or click to browse'`
+- `accessibleLabel: string = ''` (attribute `aria-label`) — overrides `label` as the internal
+  dropzone/button accessible name without changing visible copy
 
-**Methods:** `openPicker()` — programmatically opens the native file dialog.
+**Methods:** `openPicker()` programmatically opens the native file dialog; `focus(options?)`
+forwards to the interactive dropzone.
 
 **Events:** `lyra-files` (`detail: { files: File[], rejected: RejectedFile[] }`, fired on both drop
 and manual file-picker selection) — `RejectedFile = { file: File; reason: 'type' | 'count' | 'size'
@@ -3088,6 +3228,219 @@ an extension-only `accept` list.
 
 ---
 
+## `lyra-drawer`
+
+A modal panel anchored to one edge of the viewport. It inherits the dialog overlay contract:
+focus trapping, Escape and optional backdrop dismissal, document scroll locking, overlay stacking,
+accessible naming, and the cancelable `lyra-dialog-close` event.
+
+**Properties:**
+- `open: boolean = false` (attribute `open`, reflected) — controls visibility
+- `placement: 'start'|'end'|'top'|'bottom' = 'start'` (attribute `placement`, reflected)
+- `heading?: string`, `label: string`, `closable: boolean`, and `noLightDismiss: boolean` — inherited
+  dialog naming and dismissal options
+
+**CSS parts:** `backdrop`, `panel`, `header`, `heading`, `close-button`, `label`, `body`, `footer`.
+
+**Themeable custom properties:** `--lyra-drawer-width`, `--lyra-drawer-height`, and inherited
+dialog surface/overlay tokens.
+
+```html
+<lyra-drawer open placement="end" heading="Filters" closable>
+  <lyra-checkbox label="Only active"></lyra-checkbox>
+</lyra-drawer>
+```
+
+---
+
+## `lyra-carousel`
+
+Accessible carousel for arbitrary slotted slide elements. It shows one assigned element at a time,
+adds slide semantics and localized position labels, and provides keyboard, button, and indicator
+navigation.
+
+**Properties:**
+- `index: number = 0` (attribute `index`, reflected) — active slide index
+- `loop: boolean = false` (attribute `loop`, reflected) — wraps navigation at either end
+- `autoplay: boolean = false` (attribute `autoplay`, reflected) and `autoplayInterval: number = 5000`
+  (attribute `autoplay-interval`) — optional timed advance; autoplay is disabled under reduced motion
+- `showIndicators: boolean = true` (attribute `show-indicators`) — renders slide indicator buttons
+- `accessibleLabel: string = ''` (attribute `accessible-label`) — fallback landmark name; a host
+  `aria-label` takes precedence
+
+**Methods:** `next()`, `previous()`, and `goTo(index)` update the active index and emit
+`lyra-slide-change` (`detail: { index }`).
+
+**CSS parts:** `base`, `viewport`, `track`, `controls`, `previous-button`, `next-button`,
+`indicators`, and `indicator`.
+
+```html
+<lyra-carousel aria-label="Screenshots">
+  <img alt="Dashboard overview" src="overview.png">
+  <img alt="Dashboard details" src="details.png">
+</lyra-carousel>
+```
+
+---
+
+## `lyra-carousel-item`
+
+Optional semantic wrapper for one slide in `<lyra-carousel>`. The carousel also accepts arbitrary
+slotted elements, so this element is useful when a migration needs the explicit item tag.
+
+**Slots:** default slide content.
+
+**CSS parts:** `base`.
+
+```html
+<lyra-carousel>
+  <lyra-carousel-item>Dashboard overview</lyra-carousel-item>
+  <lyra-carousel-item>Dashboard details</lyra-carousel-item>
+</lyra-carousel>
+```
+
+---
+
+## `lyra-button-group`
+
+Responsive semantic grouping primitive for related action controls. It preserves the slotted
+controls and exposes `role="group"` on its internal wrapper.
+
+**Properties:**
+- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected)
+- `label: string = ''` — accessible group name; a host `aria-label` is used when `label` is empty
+
+**Slots:** default action controls.
+
+**CSS parts:** `base`.
+
+---
+
+## `lyra-image-comparer`
+
+Before/after comparison surface with two named slots and a keyboard-accessible native range handle.
+
+**Properties:**
+- `position: number = 50` (attribute `position`, reflected) — divider position from 0 to 100
+- `orientation: 'horizontal'|'vertical' = 'horizontal'` (attribute `orientation`, reflected)
+- `accessibleLabel: string | null` (attribute `aria-label`) — accessible name for the comparison
+  and its range handle
+- `beforeLabel`/`afterLabel` — fallback text for empty named slots
+
+**Events:** `lyra-position-change` (`detail: { position }`), plus composed `focus` and `blur` events
+from the internal range handle.
+
+**Slots:** `before`, `after`.
+
+**CSS parts:** `base`, `before`, `after`, `divider`, and `handle`.
+
+```html
+<lyra-image-comparer aria-label="Before and after">
+  <img slot="before" alt="Before" src="before.png">
+  <img slot="after" alt="After" src="after.png">
+</lyra-image-comparer>
+```
+
+---
+
+## `lyra-zoomable-frame`
+
+Scrollable inspection frame with bounded zoom controls and keyboard shortcuts. Scrolling provides
+panning when zoomed content exceeds the viewport.
+
+**Properties:**
+- `zoom: number = 1` (attribute `zoom`, reflected), `minZoom: number = 0.5`, `maxZoom: number = 4`,
+  and `zoomStep: number = 0.25` — bounded zoom configuration
+- `src: string = ''` and `alt: string = ''` — optional image source; otherwise the default slot is
+  rendered
+- `accessibleLabel: string | null` (attribute `aria-label`) — host-level accessible name
+
+**Methods:** `zoomIn()`, `zoomOut()`, and `resetZoom()` update the zoom and emit
+`lyra-zoom-change` (`detail: { zoom }`). The viewport also accepts `+`, `-`, and `0` keyboard
+shortcuts.
+
+**CSS parts:** `base`, `viewport`, `content`, `controls`, `zoom-out`, `zoom-in`, and `reset`.
+
+```html
+<lyra-zoomable-frame src="map-preview.png" alt="Map preview" aria-label="Map preview"></lyra-zoomable-frame>
+```
+
+---
+
+## `lyra-scroller`
+
+Responsive overflow surface with optional previous/next controls. The default slot remains the
+consumer's content, and the viewport is a native scroll container that works in narrow panels as
+well as full-width layouts.
+
+**Properties:**
+- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected)
+- `controls: boolean = false` (reflected) — show previous/next controls
+- `hideScrollbar: boolean = false` (attribute `hide-scrollbar`, reflected)
+- `scrollStep: number = 0` (attribute `scroll-step`) — custom step; zero uses 80% of the viewport
+- `label: string = ''` — accessible region name; a host `aria-label` is used when set
+
+**Events:** `lyra-scroll` with `scrollStart`, `scrollEnd`, `scrollLeft`, and `scrollTop` in the
+detail object.
+
+**Slots:** default scrollable content.
+
+**CSS parts:** `base`, `viewport`, `content`, `previous`, and `next`.
+
+```html
+<lyra-scroller controls label="Project cards">
+  <lyra-card>Solar</lyra-card>
+  <lyra-card>Wind</lyra-card>
+  <lyra-card>Battery</lyra-card>
+</lyra-scroller>
+```
+
+---
+
+## `lyra-resize-observer`
+
+Lifecycle-managed wrapper around the native `ResizeObserver`. It observes all element children in
+the default slot and emits a composed event, while adding no layout of its own.
+
+**Properties:** `disabled: boolean = false` (reflected) and `box: 'content-box' | 'border-box' |
+'device-pixel-content-box' = 'content-box'` (reflected).
+
+**Events:** `lyra-resize` with `{ entries: ResizeObserverEntry[] }` in `detail`.
+
+**Slots:** default observed elements. **CSS parts:** `base`.
+
+---
+
+## `lyra-intersection-observer`
+
+Lifecycle-managed wrapper around the native `IntersectionObserver`. It observes all element children
+in the default slot and emits a composed event, while adding no layout of its own.
+
+**Properties:** `disabled: boolean = false` (reflected), `rootMargin: string = '0px'` (attribute
+`root-margin`), `threshold: number | number[] = 0`, and `root: Element | null = null`.
+
+**Events:** `lyra-intersection` with `{ entries: IntersectionObserverEntry[] }` in `detail`.
+
+**Slots:** default observed elements. **CSS parts:** `base`.
+
+---
+
+## `lyra-mutation-observer`
+
+Lifecycle-managed wrapper around the native `MutationObserver`. All element children in the default
+slot are observed and their mutation records are emitted as a composed event; the wrapper itself
+adds no layout.
+
+**Properties:** `disabled: boolean = false` (reflected), `childList: boolean = true` (attribute
+`child-list`), `observeAttributes: boolean = false` (attribute `attributes`), `characterData: boolean = false` (attribute
+`character-data`), `subtree: boolean = true`, and `attributeFilter: string[] = []`.
+
+**Events:** `lyra-mutation` with `{ records: MutationRecord[] }` in `detail`.
+
+**Slots:** default observed elements. **CSS parts:** `base`.
+
+---
+
 ## `lyra-dialog` / `confirm()`
 
 General-purpose modal/overlay plus a promise-based confirmation helper built on top of it.
@@ -3445,7 +3798,7 @@ keyboard.
 
 A boolean form control. `role="checkbox"` with an `aria-checked` that can also be `"mixed"`, and a
 visual box/checkmark. Structurally the same idea as `<lyra-switch>` (form-associated via
-`ElementInternals`, click and Space/Enter both toggle) but with checkbox semantics.
+`ElementInternals`, click and Space toggle) but with checkbox semantics.
 
 **Properties:**
 - `checked: boolean = false` (reflected)
@@ -3458,8 +3811,11 @@ visual box/checkmark. Structurally the same idea as `<lyra-switch>` (form-associ
 - `value: string = 'on'` — only contributed to form submission while `checked` (a native checkbox
   submits nothing at all, not even an empty string, while unchecked)
 
-**Events:** `lyra-change` (`detail: { checked: boolean }`) — fired on a user toggle (click or
-Space/Enter); not fired for a programmatic `.checked` assignment.
+**Events:** user toggles emit bubbling/composed `input`, then `change`, then the compatibility
+`lyra-change` alias (`detail: { checked: boolean }`). Programmatic `.checked` assignments are
+silent. Internal `focus`/`blur` are re-dispatched as bubbling, composed host events.
+
+**Methods:** `focus(options?)` and `blur()` forward to the internal checkbox control.
 
 **Slots:** default — label text, rendered next to the box. Clicking it toggles the checkbox, the
 same as clicking a native checkbox's associated `<label>`. If left empty, set `aria-label` on the
@@ -3785,8 +4141,9 @@ produced HTML in a single pass (no second DOM walk after insertion).
   the page already finished loading); falls back to the normal async path (with its brief
   plain-text-fallback first paint) when the cache isn't warm yet. `false` (the default) is
   byte-identical to always taking the async path
-- `streaming: boolean = false` (reflected) — reserved hint for a host-provided streaming renderer;
-  setting it has no rendering effect, but lets a consumer target `lyra-markdown[streaming]` in CSS
+- `streaming: boolean = false` (reflected) — marks the host `aria-busy="true"` while partial Markdown
+  is still arriving and lets consumers target `lyra-markdown[streaming]`; busy state also remains
+  true while parser dependencies are loading
 
 **Events:** `lyra-link-click` (`detail: { href: string, internal: true }`, fired — with the click
 prevented — when a rendered link's `href` starts with `internal-link-prefix`; ordinary external
@@ -4030,7 +4387,7 @@ decorative; `label` is the entire accessible content, nothing narrates individua
 A compact inline pill representing one tool/function call an agent made mid-conversation, e.g.
 `web_search: Searching web…` with a `running` spinner. First-party invention (no Web Awesome
 equivalent). It owns no detail surface of its own — activating it (click or Enter/Space while
-focused) only fires `lyra-tool-chip-select`; a consumer wires that to opening a
+focused) fires `lyra-tool-call-chip-select`; a consumer wires that to opening a
 `<lyra-tool-result-dialog>` (or anything else) at the call site, keeping the chip reusable wherever
 a compact call summary is useful, with or without a detail surface behind it.
 
@@ -4047,10 +4404,11 @@ a compact call summary is useful, with or without a detail surface behind it.
 - `icon: string = ''` — literal icon hint (e.g. an emoji) rendered when the `icon` slot is empty;
   ignored once anything is assigned to `slot="icon"`
 - `callId: string = ''` (attribute `call-id`) — unique identifier for this invocation, echoed back
-  in `lyra-tool-chip-select`'s detail so a listener can correlate the click with the call it fired for
+  in `lyra-tool-call-chip-select`'s detail so a listener can correlate the click with the call it fired for
 
-**Events:** `lyra-tool-chip-select` (`detail: { name: string; callId: string }`) — fired on click or
-Enter/Space activation of the pill.
+**Events:** `lyra-tool-call-chip-select` (`detail: { name: string; callId: string }`) — fired on
+click or Enter/Space activation of the pill. The deprecated `lyra-tool-chip-select` alias is fired
+alongside it for one minor compatibility cycle.
 
 **Slots:** default (rich tooltip/detail content — e.g. the tool's raw arguments or a short preview —
 shown in a floating tooltip on hover/focus; nothing renders at all, no hover affordance, when this
@@ -4080,7 +4438,7 @@ rules, not part of the public theming API); shared tokens referenced: `--lyra-co
   summary="Searching web…"
   duration-ms="820"
   call-id="call_123"
-  @lyra-tool-chip-select=${(e) => openDetail(e.detail.callId)}
+  @lyra-tool-call-chip-select=${(e) => openDetail(e.detail.callId)}
 >
   <pre slot="icon" style="display:none"></pre>
   <code>{"query": "lyra ui components"}</code>
@@ -4271,6 +4629,8 @@ overlay stack.
 **Properties:**
 - `open: boolean = false` (reflected) — whether the dialog is open; set this (or call `close()`) —
   there is no separate `show()`/`hide()` pair
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — directly names the internal
+  dialog panel; otherwise the tool-name title supplies `aria-labelledby`
 - `toolName: string = ''` (attribute `tool-name`) — the tool's name, rendered prominently in the
   header
 - `status: 'pending'|'running'|'success'|'error'|'denied' = 'pending'` (reflected) — drives the
@@ -4280,12 +4640,12 @@ overlay stack.
 - `maximized: boolean = false` (reflected) — near-fullscreen presentation of the same open dialog
 
 **Methods:** `close(reason: ToolResultDialogCloseReason = 'api'): void` — closes the dialog (no-op if
-already closed), emits `lyra-dialog-close` with `reason`, and returns focus to whatever had it before
+already closed), emits `lyra-close` with `reason`, and returns focus to whatever had it before
 the dialog opened. Built-in triggers call this with `'escape'`/`'backdrop'`/`'close-button'`; a
 consumer's own close affordance (e.g. a footer action button) should call it directly with its own
 reason string so every dismissal path funnels through the same event.
 
-**Events:** `lyra-dialog-close` (`detail: ToolResultDialogCloseReason` — `'escape'|'backdrop'|
+**Events:** `lyra-close` (`detail: ToolResultDialogCloseReason` — `'escape'|'backdrop'|
 'close-button'|'api'|string`) fired exactly once per dismissal; `lyra-maximize-change` (`detail:
 boolean`, the new `maximized` state) fired when the header's maximize/restore toggle is clicked.
 
@@ -4300,7 +4660,8 @@ tool name/status/duration), `tool-name`, `status`, `duration`, `header-actions`,
 **Themeable custom properties:** `--lyra-tool-result-dialog-overlay-color` (default `rgb(0 0 0 /
 0.5)` — the backdrop scrim color; component-specific since no shared overlay token exists),
 `--lyra-tool-result-dialog-maximized-inset` (default `var(--lyra-space-l)` — inset applied to the
-panel while `[maximized]`, overridable e.g. to leave a persistent app rail visible), plus shared
+panel while `[maximized]`, overridable e.g. to leave a persistent app rail visible), and
+`--lyra-tool-result-dialog-spin` (default `1s linear`, stopped under reduced motion), plus shared
 tokens `--lyra-color-surface/-border/-text-quiet/-brand/-brand-quiet/-success/-success-quiet/
 -danger/-danger-quiet/-warning/-warning-quiet`, `--lyra-space-*`, `--lyra-radius`, `--lyra-shadow`,
 `--lyra-icon-button-size`, `--lyra-focus-ring-*`, `--lyra-transition-base`.
@@ -4313,7 +4674,7 @@ tokens `--lyra-color-surface/-border/-text-quiet/-brand/-brand-quiet/-success/-s
   status="success"
   duration-ms="1240"
   ?open=${dialogOpen}
-  @lyra-dialog-close=${(e) => (dialogOpen = false)}
+  @lyra-close=${(e) => (dialogOpen = false)}
   @lyra-maximize-change=${(e) => console.log('maximized:', e.detail)}
 >
   <lyra-tabs slot="body">
@@ -4344,7 +4705,7 @@ state, so no additional scroll-lock/focus-trap bookkeeping is needed for that tr
   panel template so a slotted `<lyra-tabs>` (or any other light-DOM-scanning child) sees real
   projected content rather than a forwarding `<slot>`, while still sharing the overlay stack
 - `close()` is a no-op when `open` is already `false` — calling it twice in a row only fires
-  `lyra-dialog-close` once
+  `lyra-close` once
 - the `maximize`/`close` buttons are always the first elements in the Tab order while open,
   regardless of visual position, followed by `body` then `footer` content
 
@@ -4374,14 +4735,24 @@ reveals the invalid state, and `form.reset()` clears the touched presentation.
   built-in button's icon/label (send vs. stop) and whether Enter still submits
 - `submitOnEnter: boolean = true` (reflected, attribute `submit-on-enter`) — when `false`, Enter
   always inserts a newline instead of submitting
+- `stoppable: boolean = true` (reflected) — when false, busy states keep a disabled Send button
+  instead of exposing a Stop action
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — names the internal textarea;
+  wins over placeholder and the localized composer label
 - `spellcheck: boolean = true` — forwarded to the internal `<textarea>`
 - `autocapitalize: string = ''` — forwarded to the internal `<textarea>`; empty omits the attribute
 - `autoCorrect: string = ''` (attribute `autocorrect`) — forwarded to the internal `<textarea>`
   (Safari/WebKit-specific); empty omits the attribute. Named `autoCorrect`, not `autocorrect`, only
   to dodge a `lib.dom.d.ts` collision with `HTMLElement`'s own `boolean`-typed `autocorrect` IDL
   member; the host attribute is explicitly mapped to plain `autocorrect`.
+- `wrap: 'hard' | 'soft' | 'off' = 'soft'`, `autocomplete: string = ''`, `inputMode: string = ''`
+  (attribute `inputmode`), and `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to
+  the native textarea
+- `selectionStart`, `selectionEnd`, and `selectionDirection` — native selection getters/setters
 
-**Methods (own):** none beyond the inherited `checkValidity()`/`reportValidity()`.
+**Methods (own):** `focus(options?)`, `blur()`, `select()`, `setSelectionRange()`, and
+`setRangeText()` forward to the textarea; `setRangeText()` synchronizes reactive/form value and
+auto-sizing. `checkValidity()`/`reportValidity()` remain inherited.
 
 **Events:**
 - `lyra-input` (`detail: { value }`) — fired on every user-driven edit of the textarea, not a
@@ -4496,12 +4867,12 @@ wins when both are present.
   attachment, leaving only the thumbnail. Has no effect for a non-image chip, or when `compact` is
   unset. `false` (the default) reproduces the chip's exact existing output.
 - `removeLabel: string = 'Remove'` (attribute `remove-label`) — verb used in the remove button's
-  `aria-label`, interpolated as `` `${removeLabel} ${displayName}` ``; override for i18n/locale
+  accessible name; the default routes through the complete localized `removeWithContext` template
 - `retryLabel: string = 'Retry'` (attribute `retry-label`) — verb used in the retry button's
-  `aria-label`, interpolated as `` `${retryLabel} ${displayName}` ``; override for i18n/locale
+  accessible name; the default routes through the complete localized attachment template
 - `uploadingLabel: string = 'Uploading'` (attribute `uploading-label`) — verb used in the visible
-  uploading status text, rendered as `` `${uploadingLabel} ${percent}%` `` once progress is a
-  meaningful number, else `` `${uploadingLabel}…` ``; override for i18n/locale
+  uploading status; the untouched default uses complete localized messages for progress,
+  indeterminate state, and filename context so translators can reorder every value
 - `uploadFailedLabel: string = 'Upload failed'` (attribute `upload-failed-label`) — visible status
   text shown for `status="error"`; override for i18n/locale
 
@@ -4526,7 +4897,8 @@ generated internal id is used as a last resort.
 `done` → success/success-quiet/transparent); `--lyra-attachment-chip-compact-thumbnail-size` (default
 `1.75rem`), `--lyra-attachment-chip-compact-font-size` (default `var(--lyra-font-size-xs)`),
 `--lyra-attachment-chip-compact-gap` (default `0.25rem`) — govern the chip's thumbnail size, text
-size, and internal gap while `compact` is set; plus shared tokens `--lyra-space-xs`, `--lyra-space-s`,
+size, and internal gap while `compact` is set; `--lyra-attachment-chip-spinner-duration` (default
+`0.8s`) controls the indeterminate rotation and stops under reduced motion; plus shared tokens `--lyra-space-xs`, `--lyra-space-s`,
 `--lyra-radius`, `--lyra-color-text`, `--lyra-color-danger`, `--lyra-icon-button-size`,
 `--lyra-transition-fast`, `--lyra-transition-base`, `--lyra-focus-ring-width`,
 `--lyra-focus-ring-color`, `--lyra-focus-ring-offset`.
@@ -5287,7 +5659,8 @@ anything about `<lyra-source-card>`, it only carries the id through its event de
   echoed back verbatim in both events; never read or validated by this component.
 - `href: string = ''` — optional direct link target for the citation's source, carried into
   `lyra-citation-open`'s detail as-is; this component never navigates.
-- `label: string = ''` — overrides the computed accessible name (`"Citation {index}[, {status}]"`).
+- `label: string = ''` — overrides the computed accessible name. The built-in citation/status
+  summary is a complete localized template; a host `aria-label` has highest precedence.
 
 **Events:**
 - `lyra-citation-activate` (`detail: { sourceId: string; index: number }`) — fires on click, or on
@@ -5301,6 +5674,8 @@ anything about `<lyra-source-card>`, it only carries the id through its event de
 **Slots:** default — rich preview/tooltip content (e.g. a filename + excerpt), shown in a floating
 popover on hover/focus. This is *not* the badge's visible content (the badge always renders
 `[index]`); nothing renders at all (no hover affordance) when this slot is empty.
+When populated, the button carries `aria-describedby` referencing the same-shadow-tree popover,
+which owns `role="tooltip"` whether currently shown or hidden.
 
 **CSS parts:** `base` (the clickable `<button>`), `bracket` (each of the two literal `[`/`]` glyphs),
 `index` (the citation number), `popover` (the floating preview panel, only meaningful while open).
@@ -5412,7 +5787,8 @@ while collapsed).
   expand/collapse, which only ever hides/shows the *set* of cards, never a single card's own content.
 - `lyra-open` (`detail: { sourceId: string; href?: string }`) — the title was activated. This
   component never navigates on its own (a controlled component, the same convention
-  `<lyra-tool-call-chip>`'s `lyra-tool-chip-select` follows); a listener decides what "open" means.
+  `<lyra-tool-call-chip>`'s `lyra-tool-call-chip-select` follows); a listener decides what "open"
+  means.
 
 **Slots:** `excerpt` (a short preview; when left empty, the `excerpt` part collapses away entirely —
 its wrapper is `hidden`, not just visually empty), `full` (the complete source text/chunk, hidden
@@ -6192,6 +6568,8 @@ and it's what every instance renders at zero extra bytes until shiki resolves.
   `"json"`); when unset, or when shiki doesn't recognize it, the code renders as plain unhighlighted
   text regardless of whether shiki itself is available
 - `filename: string = ''` — shown in the header, when set
+- `accessibleLabel: string = ''` (attribute `aria-label`) — names the internal focusable code-body
+  region; otherwise a localized filename/language description is generated
 - `collapsible: boolean = false` (reflected) — shows the collapse/expand chevron button
 - `collapsed: boolean = false` (reflected) — only has a visible effect while `collapsible` is also
   true
@@ -6302,6 +6680,8 @@ toggle, the loading-skeleton behavior while the fine-grained highlighter resolve
   key in `languages`, the code renders as plain unhighlighted text — this component has no
   default/full-table highlighter to fall back to.
 - `filename: string = ''` — shown in the header, when set.
+- `accessibleLabel: string = ''` (attribute `aria-label`) — names the internal focusable code-body
+  region; otherwise a localized filename/language description is generated.
 - `collapsible: boolean = false` (reflected) — shows the collapse/expand chevron button.
 - `collapsed: boolean = false` (reflected) — only has a visible effect while `collapsible` is also
   true.
@@ -6749,6 +7129,21 @@ not rendered at all for `type="normal"`)
 
 **Optional peer deps:** none.
 
+### `lyra-dropdown-item`
+
+Compatibility naming alias for `<lyra-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
+<lyra-menu>
+  <button slot="trigger">Actions</button>
+  <lyra-dropdown-item value="archive">Archive</lyra-dropdown-item>
+</lyra-menu>
+```
+
 ```html
 <lyra-menu label="Row actions">
   <button slot="trigger" aria-label="More actions">⋮</button>
@@ -6871,9 +7266,9 @@ children are the chips (the same shape `<lyra-split>`'s panels / `<lyra-source-l
 no `.items` array prop).
 
 **Properties:**
-- `maxVisible?: number` (attribute `max-visible`) — maximum number of direct children shown before
-  the rest collapse behind a "+N" indicator; unset (the default) means no limit, every child is
-  always shown
+- `maxVisible?: number` (attribute `max-visible`) — maximum number of assigned children shown before
+  the rest collapse behind a "+N" indicator; flattened slot-forwarded children count the same as
+  direct children. Unset means no limit
 
 **Events:** `lyra-overflow-toggle` (`detail: { expanded }` — the overflow indicator was activated,
 revealing or re-collapsing the excess children; fires only from that click, i.e. only when
@@ -7032,6 +7427,9 @@ used" summary.
 - `label: string = ''` — overall accessible caption, e.g. `"128K context window"`. Also rendered
   visually (`[part="label"]`) when set.
 
+Accessible summaries, segment tooltips, and ring titles format quantities using `effectiveLocale`.
+A host `aria-label` overrides the generated meter summary and is preserved across reactive updates.
+
 **Events:** none.
 
 **Slots:** none.
@@ -7228,6 +7626,8 @@ fallback simply omits `[part="download-link"]` entirely.
   `<img>`/the anchor.
 - `mimeType: string = ''` (attribute `mime-type`) — drives format dispatch (see above).
 - `filename: string = ''` — shown in the header and used as the download link's suggested filename.
+- `alt?: string` — image description. When omitted, the filename/localized image-preview fallback
+  is used; an explicit empty string keeps a decorative preview's `alt=""` intact.
 - `status: 'idle' | 'converting' | 'ready' | 'error' = 'idle'` (reflected) — host-owned lifecycle
   state. `"converting"` shows the spinner regardless of `mimeType`/`src`; `"error"` shows
   `errorMessage` regardless of either. `"idle"`/`"ready"` both resume normal format dispatch — a host
@@ -7262,8 +7662,8 @@ above; excludes `data:` even though the other two sinks allow it)
 **Themeable custom properties:** `--lyra-document-preview-max-height` (default `none`) — the
 consumer-tunable scroll cap on `[part="body"]`, set from `max-height`; `none` means the preview grows
 with its content until a caller opts in. `--lyra-document-preview-font` (default `ui-monospace,
-SFMono-Regular, Menlo, Consolas, monospace`) — no shared `--wa-*`/`--lyra-*` monospace token exists yet
-(the same gap `lyra-json-viewer`'s own `--lyra-json-viewer-font` documents). Plus shared tokens
+SFMono-Regular, Menlo, Consolas, monospace`) and `--lyra-document-preview-spin-duration` (default
+`0.8s`, stopped under reduced motion). Plus shared tokens
 `--lyra-color-border`, `--lyra-radius`, `--lyra-color-surface`, `--lyra-space-s/-m/-l/-xs`,
 `--lyra-color-text`, `--lyra-color-text-quiet`, `--lyra-color-danger`, `--lyra-color-brand`,
 `--lyra-color-on-brand`, `--lyra-focus-ring-width/-color/-offset`, `--lyra-transition-fast`.
@@ -7304,6 +7704,8 @@ available, the region becomes a standard `role="progressbar"` instead, self-desc
 - The component's own text/JSON `fetch(src)` is a *different* async operation from the host-driven
   `status="converting"` conversion. A failed fetch fires `lyra-render-error` and renders
   `[part="error"]` on its own; it never sets `status="error"` itself.
+- changing `src` aborts the superseded text fetch as well as ignoring any stale completion; removing
+  the component aborts its active request.
 - `progress` is only ever consulted for the host-driven `"converting"` state — this component's own
   in-flight text fetch always renders the indeterminate spinner, with no numeric-progress path.
 - The `unsupported` slot's initial presence is detected once, before the first render, by scanning
@@ -7340,6 +7742,8 @@ final.
   filename, and folded into the accessible name.
 - `alt: string = ''` — alt text for the image case (and reused as a video label fallback). Falls
   back to `filename`, then a generic per-kind description.
+- `accessibleLabel: string = ''` (attribute `aria-label`) — overrides the localized action name on
+  the actual button/link without replacing image alt text or the video control's own label
 - `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"16rem"`); once set,
   overrides the `--lyra-media-card-max-height` custom property for this instance only (applied
   inline on `[part="base"]`, so it reliably wins over a `:host{}`-declared default from outside the
@@ -7638,6 +8042,8 @@ user-menu affordance.
 - `src?: string` — image URL; takes priority over `initials` when set and loads successfully, falling
   back to `initials` on a load error.
 - `alt: string = ''` — image alt text; set alongside `src` for accessibility.
+- host `aria-label` — overrides `alt` as the image/fallback accessible name without changing the
+  visible initials or image
 - `size: 'sm' | 'md' | 'lg' = 'md'` (reflected).
 - `shape: 'circle' | 'square' = 'circle'` (reflected).
 - `tone: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected) — recolors
@@ -7666,13 +8072,10 @@ var(--lyra-color-border))`, swapped per `tone`), `--lyra-avatar-color` (default
 ```
 
 **Known gotchas:**
-- an image load failure falls back to `initials` automatically (an `error` listener flips internal
-  state) — there's no manual reset/retry method; reassigning `src` (even to the same value)
-  re-attempts the load.
-- the initials fallback is `aria-hidden="true"` whenever `alt` is set, regardless of whether an image
-  is actually showing — so if `src`/`alt` are both set but the image fails to load, the rendered
-  initials text is still hidden from assistive tech, leaving the avatar with no accessible name of
-  its own unless the surrounding context supplies one.
+- an image load failure falls back to `initials` automatically. Changing `src` clears the failure
+  state so the replacement URL gets its own load attempt.
+- when `alt` or host `aria-label` supplies a name, the base preserves that name through the
+  initials fallback while hiding duplicate initials text from assistive technology.
 
 ---
 
@@ -7732,6 +8135,164 @@ the `footer` slot, hidden entirely when empty).
 
 ---
 
+## `lyra-radio`
+
+A form-associated single-choice control. Use it alone or inside `lyra-radio-group`.
+
+**Properties:** `checked`, `disabled`, `required`, `name`, and `value` (all reflected where
+applicable). A selected radio submits its value through `ElementInternals`.
+
+**Events:** native-style composed `input` and `change`, plus `lyra-change` with
+`{ checked, value }`.
+
+**Slots:** default label content.
+
+**CSS parts:** `base`, `circle`, `dot`, `label`.
+
+```html
+<lyra-radio name="format" value="json">JSON</lyra-radio>
+```
+
+## `lyra-popover`
+
+A click-triggered, light-dismiss floating surface positioned with the shared Floating UI positioner.
+
+**Properties:** `open`, `placement`, `distance`, `accessibleLabel` (`aria-label`), and `popupRole` (`popup-role`).
+**Events:** `lyra-show`, `lyra-hide`. **Slots:** `trigger`, default content. **CSS parts:** `trigger`,
+`popup`, `content`.
+
+## `lyra-tooltip`
+
+A hover/focus tooltip positioned with the shared Floating UI positioner.
+
+**Properties:** `open`, `manual`, `delay`, `placement`, `distance`, `content`, and
+`accessibleLabel` (`aria-label`). **Slots:** `trigger`, default content. **CSS parts:**
+`trigger`, `popup`.
+
+## `lyra-dropdown`
+
+A menu-role popover for consumer-supplied action content. Compose `lyra-menu` when full roving
+menu-item behavior is needed.
+
+**Properties:** `open`, `placement`, `distance`, `accessibleLabel` (`aria-label`), and `popupRole` (`popup-role`).
+**Slots:** `trigger`, default menu content. **CSS parts:** `trigger`, `popup`, `content`.
+
+## `lyra-radio-group`
+
+A labeled, keyboard-navigable group of `lyra-radio` controls. Arrow keys, Home, and End move
+focus; arrow navigation selects the next enabled radio.
+
+**Properties:** `label`, `hint`, `errorText` (`error-text`), `name`, `required`, `disabled`, and
+`aria-label` (through `accessibleLabel`).
+
+**Events:** `lyra-change` with `{ value, radio }`.
+
+**Slots:** default radios, `label`, `hint`, `error`.
+
+**CSS parts:** `base`, `label`, `hint`, `error`.
+
+## `lyra-spinner`
+
+An indeterminate busy indicator with a localized `role="status"` name.
+
+**Properties:** `labelPlacement` (`label-placement`): `'none' | 'after'` and `accessibleLabel`
+(`accessible-label`).
+
+**Slots:** default optional visible label. **CSS parts:** `base`, `spinner`, `label`.
+
+## `lyra-progress-bar`
+
+A determinate or indeterminate progress bar.
+
+**Properties:** `value`, `max`, `indeterminate`, `variant`, `showValue` (`show-value`), and
+`accessibleLabel` (`accessible-label`).
+The rendered progressbar exposes `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` when
+determinate.
+
+**Slots:** `label`. **CSS parts:** `base`, `track`, `indicator`, `label`.
+
+## `lyra-progress-ring`
+
+A circular progress indicator with the same value contract as `lyra-progress-bar`.
+
+**Properties:** `value`, `max`, `indeterminate`, and `accessibleLabel` (`accessible-label`).
+**Slots:** default center label. **CSS parts:** `base`, `track`, `indicator`, `label`.
+
+## `lyra-badge` and `lyra-tag`
+
+Compact status labels. Both expose `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger'`.
+The two tags share the same visual contract; `lyra-tag` is a semantic alias for migration-friendly
+markup.
+
+**Slots:** default content. **CSS parts:** `base`.
+
+## `lyra-callout`
+
+An inline status, warning, or error surface.
+
+**Properties:** `variant`, `heading`, `closable`, `open`, and `accessibleLabel` (`accessible-label`).
+
+**Events:** cancelable `lyra-close`; the callout hides after the event unless a listener calls
+`preventDefault()`.
+
+**Slots:** default message, `heading`, `icon`. **CSS parts:** `base`, `icon`, `content`, `heading`,
+`close-button`.
+
+## `lyra-details`, `lyra-accordion`, and `lyra-accordion-item`
+
+`lyra-details` is a native-semantics disclosure panel. `lyra-accordion` coordinates slotted
+details panels and closes siblings unless `multiple` is true. `lyra-accordion-item` is an
+accordion-compatible alias.
+
+**Properties:** `open`, `disabled`, and `summary` on details/items; `multiple` on accordion.
+**Events:** `lyra-toggle` with `{ open }` from details/items. **Slots:** `summary` and default
+content on details/items; default panels on accordion. **CSS parts:** `base`, `summary`, `content`
+on details/items; `base` on accordion.
+
+## `lyra-divider`
+
+A semantic separator with `orientation: 'horizontal' | 'vertical'`. **CSS part:** `base`.
+
+## `lyra-breadcrumb` and `lyra-breadcrumb-item`
+
+Responsive navigation trail primitives. Breadcrumb has `accessibleLabel` (`accessible-label`);
+items have `href` and `current`. Breadcrumb slots default items; item slots default label content.
+Breadcrumb exposes `base`; item exposes `base`.
+
+## `lyra-format-number`
+
+Locale-aware `Intl.NumberFormat` output. **Properties:** `value`, `locale`, `currency`, `notation`,
+`minimumFractionDigits`, and `maximumFractionDigits`. Default slot is fallback content for a
+non-finite value.
+
+## `lyra-format-date`
+
+Locale-aware `Intl.DateTimeFormat` output. **Properties:** `date`, `locale`, `year`, `month`, `day`,
+`dateStyle`, and `timeStyle`. Default slot is fallback content for an invalid date.
+
+## `lyra-format-bytes`
+
+Locale-aware byte-size output. **Properties:** `value`, `locale`, `unitStep` (`unit-step`), and
+`decimals`.
+
+## `lyra-relative-time`
+
+Locale-aware relative time output. **Properties:** `date`, `locale`, `unit`, `numeric`, and `sync`.
+When `sync` is true the displayed value refreshes periodically.
+
+## `lyra-rating`
+
+A keyboard-accessible star rating control with slider semantics. **Properties:** `value`, `max`,
+`precision`, `readonly`, `disabled`, and `accessibleLabel` (`aria-label`). **Events:**
+`lyra-change` with `{ value }`. **CSS parts:** `base`, `star`.
+
+## `lyra-color-picker`
+
+A form-associated native color picker with label and hint chrome. **Properties:** the shared form
+properties `name`, `value`, `disabled`, and `required`, plus `label`, `hint`, and `accessibleLabel`
+(`aria-label`). **Slots:** `label`, `hint`. **Events:** composed `input` and `change`, plus
+`lyra-change` with `{ value }`. **CSS parts:** `form-control`, `label`, `input`, `hint`.
+
 ## Cross-cutting notes
 
 These apply across the whole library rather than to any one component: