@aceshooting/lyra-ui 5.1.0 → 6.0.0

package/llms/components/lr-virtual-list.md

@@ -29,10 +29,39 @@ invention (no Web Awesome equivalent).
   which is only a safe identity while `items` never reorders/inserts/removes — provide this whenever
   possible, or scroll position and per-row DOM state (e.g. an `<audio>` element's playback position)
   can attach to the wrong row across a mutation.
-- `groups?: VirtualListGroup[]` (attribute: false) — renders a labeled `role="heading"` marker at each
-  group's `startIndex`, positioned independently of the row window (so it stays in place as its rows
-  scroll past). Groups are sorted by `startIndex`; a `startIndex` that's non-integer, out of range, or
-  a duplicate of an earlier group's is silently dropped rather than rendered wrong.
+- `groups?: VirtualListGroup[]` (attribute: false) — renders a labeled marker at each group's
+  `startIndex`, positioned independently of the row window (so it stays in place as its rows scroll
+  past). Groups are sorted by `startIndex`; a `startIndex` that's non-integer, out of range, or a
+  duplicate of an earlier group's is silently dropped rather than rendered wrong. An entry whose
+  `label` is the **empty string** renders no marker at all — it is a pure position anchor, for a host
+  that renders its own group header as an ordinary row (and would otherwise end up with two stacked
+  headers) but still needs this component to know where each group starts, e.g. to drive
+  `renderStickyGroup` below. Omitting `label` entirely still falls back to rendering `key`.
+- `renderStickyGroup?: (group: VirtualListGroup) => unknown` (attribute: false) — renders a pinned
+  copy of whichever `groups` entry the viewport is currently inside, into a `[part="sticky-group"]`
+  overlay that stays at the top of the scroll viewport and is pushed out by the overlap as the next
+  group's header arrives (rather than swapped abruptly at the boundary). Native `position: sticky` on
+  the rows or markers themselves cannot do this: every row is absolutely positioned and
+  transform-offset by the windowing math, which makes sticky structurally inert. Unset (the default)
+  renders no overlay element whatsoever and changes nothing about the list's output. The overlay is a
+  *visual copy* of content that already exists in the list, which fixes its contract:
+  - it is `aria-hidden`, and ordinary focusable HTML inside it is forced to `tabindex="-1"`, so the
+    real row keeps sole ownership of the heading semantics and of the tab order (a focus-delegating
+    custom element rendered into the copy needs its own `tabindex="-1"`; `inert` is deliberately not
+    used, because it would also block the pointer opt-in below);
+  - it is `pointer-events: none` by default — opt back in with
+    `lr-virtual-list::part(sticky-group) { pointer-events: auto; }` when the copied header content is
+    interactive;
+  - it is never measured as a row, so a group header that is also a real row is not double-counted in
+    `row-height="auto"` mode;
+  - its measured height is applied as `scroll-padding-block-start` on the scroll container and
+    subtracted from top-aligned scroll targets, so `active-id`, `scrollToIndex({ align: 'start' })`
+    and native keyboard scrolling all stop *below* the band instead of parking the row behind it.
+
+  The callback runs on every scroll-driven update, so keep it cheap and side-effect free. While the
+  viewport is above the first group there is nothing to pin: the band shows nothing, but it stays
+  mounted (called with the first group, rendered hidden) so its height is known before the first
+  programmatic jump rather than only after it.
 - `rowHeight: string = 'auto'` (attribute `row-height`) — `'auto'` measures each row's real height via
   `ResizeObserver`; a numeric string (e.g. `"56"`) fixes every row to that many pixels. Anything else
   (non-numeric, zero, negative, non-finite) silently falls back to `'auto'` rather than throwing.
@@ -59,7 +88,8 @@ invention (no Web Awesome equivalent).
 
 **Exported types:** `VirtualListRange { start: number; end: number }` (the `lr-visible-range-changed`
 detail shape); `VirtualListGroup { key: string | number; label?: string; startIndex: number }` — the
-shape consumed by `groups` above.
+shape consumed by `groups` above; `VirtualListScroll { scrollTop: number; viewportHeight: number }` —
+the `lr-scroll` detail shape.
 The package root also exports `groupByRecency(items, options?)`, a DOM-free helper that returns
 non-empty Today/Yesterday/Previous 7 Days/Older buckets, preserves input order within each bucket,
 and accepts a timestamp extractor, reference date, and label overrides.
@@ -69,12 +99,35 @@ automatic scroll-into-view, for a host that needs to scroll to a specific row wi
 row is "active." `options.align` is `'start'`, `'end'`, or `'auto'` (default — no scroll at all when
 already fully visible); `options.behavior` (default `'smooth'`) is forced to `'auto'` under
 `prefers-reduced-motion: reduce`. `index` is clamped to `0…items.length-1`.
+`offsetForIndex(index)` returns the pixel top row `index` renders at, in the same coordinate space as
+the scroll container's `scrollTop`; it is clamped to `0…items.length`, so `offsetForIndex(items.length)`
+is the total content height and an empty list is always `0`. `indexAtOffset(px)` is its inverse — the
+row whose box contains that offset, clamped at both ends, `-1` for an empty list — so
+`indexAtOffset(offsetForIndex(i)) === i` and `indexAtOffset(scrollContainer.scrollTop)` is the row at
+the top of the viewport. In `row-height="auto"` mode both are estimate-based for any row that (or
+above which) has not been measured yet, and converge as those `ResizeObserver` measurements land;
+fixed numeric `row-height` offsets are exact from the first render. Both read the most recent render,
+so `await el.updateComplete` after assigning `items` before querying.
+
+**Getters:** `scrollContainer: HTMLElement | undefined` — the real scroll container (`[part="base"]`),
+`undefined` before the first render; for a host that needs the live scroll position or wants to scroll
+the list itself without reaching into the shadow root. `renderedRows: HTMLElement[]` — the row
+wrappers (`[part="row"]`) that currently exist as real DOM, in item order (the current window, not the
+whole collection; empty before the first render). It exists for hosts that must *reach* a rendered row
+rather than style it — keyboard focus management across a windowed list, where the row to focus may
+not have existed a frame earlier, and which `exportparts` cannot serve since it forwards styling, not
+element references. Treat both as read-only: positioning, keys, and lifetime belong to the windowing
+math, and any row element can be recycled or removed on the next update.
 
 **Events:** `lr-load-more` (no detail — fired once per approach to the bottom of the list while
 `has-more` is true and `loading` is false; does not refire on every scroll tick while still near the
 bottom — scrolling back away from the bottom and returning, or `items` growing enough to move the
 window away from the end, re-arms it), `lr-visible-range-changed` (`detail: VirtualListRange`, the
-current visible, non-overscanned item index range — fired only when it actually changes)
+current visible, non-overscanned item index range — fired only when it actually changes), `lr-scroll`
+(`detail: VirtualListScroll` — the scroll container moved; emitted from the same animation frame that
+already coalesces native `scroll` events, so a fling produces at most one per frame and none at all
+when the position did not change. Unlike `lr-visible-range-changed`, which only fires on index-range
+changes, this reports *sub-row* movement, which is what scroll-linked layout needs)
 
 **Slots:** none — all content comes from `renderItem`.
 
@@ -82,13 +135,20 @@ current visible, non-overscanned item index range — fired only when it actuall
 `item-role="row"` mode — `tabindex="0"`), `spacer` (the full-content-height inner element
 establishing true scroll extent; `role="presentation"` in `item-role="row"` mode), `row` (one
 rendered row's absolutely-positioned wrapper, `role="listitem"` — or `role="row"` with
-`aria-rowindex` in `item-role="row"` mode), `group` (a `groups` entry's positioned `role="heading"`
-marker)
+`aria-rowindex` in `item-role="row"` mode), `group` (a `groups` entry's positioned marker; not
+rendered for an entry whose `label` is the empty string), `sticky-group` (the pinned copy of the
+current group, present only while `renderStickyGroup` is set — `aria-hidden` and
+`pointer-events: none` by default; style it with `pointer-events: auto` to make copied interactive
+content clickable, and it shows nothing while the viewport is above the first group)
 
 **Themeable custom properties:** `--lr-virtual-list-height` (default `24rem` — the host's bounded
 scroll extent; component-specific since a virtualized list is meaningless without a sized viewport),
 plus shared `--lr-focus-ring-width/-color/-offset` (inward-offset ring on `[part="base"]`, negative
-so it isn't clipped by the container's own `overflow: auto`).
+so it isn't clipped by the container's own `overflow: auto`). `[part="base"]` also carries a
+mouse-hover outline — a subtler preview of that same `:focus-visible` ring, shown because the part
+always carries `tabindex="0"` and is a real keyboard-navigable target — tinted via
+`--lr-virtual-list-hover-outline-color` (default `var(--lr-color-border-strong)`); set it to
+`transparent` to opt out of the hover treatment entirely.
 
 **Optional peer deps:** none.
 
@@ -112,6 +172,20 @@ so it isn't clipped by the container's own `overflow: auto`).
 ></lr-virtual-list>
 ```
 
+```html
+<!-- Sticky group headers: the header is a real row, so the `groups` entries are position anchors
+     only (`label: ''`), and the pinned copy opts back into pointer events for its own toggle. -->
+<lr-virtual-list
+  .items=${rows}
+  .groups=${groupStarts /* [{ key: 'Today', label: '', startIndex: 0 }, …] */}
+  .renderItem=${(item, index) => (item.isHeader ? headerTemplate(item) : rowTemplate(item))}
+  .renderStickyGroup=${(group) => headerTemplate(group)}
+></lr-virtual-list>
+<style>
+  lr-virtual-list::part(sticky-group) { pointer-events: auto; }
+</style>
+```
+
 Every row — in both `row-height` modes — is positioned by a `transform: translateY(offset)` computed
 from a single cumulative offsets array, rather than by page flow; this is what lets a small DOM window
 exist while the scrollbar still reflects the true total content height. That array is rebuilt only
@@ -139,7 +213,26 @@ history sidebar); it is not the right approach for a hundred-thousand-row list w
 - `aria-setsize`/`aria-posinset` are computed from a row's real index in the full `items` array, not its
   position among the currently-rendered DOM window, so assistive tech still announces e.g. "item 12 of
   340" correctly even though only a handful of rows exist in the DOM at a time.
-- `groups` is accepted today purely for forward API compatibility; setting it has no visible effect
-  yet.
+- `groups`, `renderStickyGroup`, `offsetForIndex()`/`indexAtOffset()` and the `lr-scroll` event are
+  all expressed against the *same* windowing math, so they agree with each other — but that math is
+  estimate-based in `row-height="auto"` mode until the rows involved have been measured. Read a
+  position after `await el.updateComplete`, and expect the value to converge rather than be final on
+  the first frame.
+- A sticky band only appears when `renderStickyGroup` *and* at least one valid `groups` entry are
+  both present; `groups` alone renders positioned markers with nothing pinned, and
+  `renderStickyGroup` alone renders no overlay element at all.
+- **A row that renders a popup needs the focused-row lift, and this is why `[part='row']` has one.**
+  Each row carries `will-change: transform` (a compositor hint for the per-frame translate), which
+  makes every row its own stacking context. Rows otherwise carry no `z-index`, so they paint in DOM
+  order and each one paints over the previous. Anything a row renders that overflows its own box —
+  an `<lr-menu>` popup in a row-action menu, a tooltip, an outward focus ring — is therefore painted
+  *underneath* every following row, no matter how high its own `z-index` is: that `z-index` only
+  orders siblings inside the row's own context. The last row always looks correct, which is exactly
+  why a short fixture never catches it. `[part='row']:focus-within` lifts the row to
+  `--lr-layer-content` for precisely as long as something inside it holds focus — the lifetime of an
+  open popup — and costs nothing otherwise. The value deliberately *matches* `[part='group']`'s
+  rather than exceeding it, so the two land on the same layer and DOM order decides: groups render
+  before the rows, so a focused row wins while (and only while) it holds focus, which is right — a
+  group header is a non-interactive `pointer-events: none` label.
 
 ---

package/llms/components/lr-voice-picker.md

@@ -43,6 +43,14 @@ identically-named properties.
 getter/setter (the current voice id, `''` when nothing is selected), `name` (reflected), `disabled`
 (reflected), `required` (reflected — enforced via `internals.setValidity()`).
 
+**Methods:** `click()` (override) — same forwarding contract as `lr-model-select`'s own `click()`
+override (see that section for the full rationale): closed-dropdown mode forwards a real `.click()`
+to the trigger `<button>`, whose own `@click` handler opens it; free-text mode instead calls
+`.focus()` on the combobox `<input>`, since a synthetic `.click()` on a text input never dispatches
+`focus` the way a real click's `mousedown` default action does, and this mode's open behavior is
+wired to the input's native `focus` event, not a `click` handler on the input itself. Mirrors
+`<lr-button>`'s identical host `click()` forwarding.
+
 **Events:** `lr-change` — `detail: { value, inCatalog }`. `lr-preview-request` — `detail: {
 voiceId, previewUrl? }`, cancelable. `lr-preview-change` — `detail: { voiceId }`, internal playback
 started (`voiceId`) or stopped (`null`). Plus mirrored native `input`/`change` and re-dispatched

package/llms/components/lr-widget.md

@@ -72,6 +72,17 @@ the fullscreen backdrop scrim color), `--lr-widget-fullscreen-inset` (default pe
 tokens (`--lr-space-*`, `--lr-color-border/-surface/-text-quiet`,
 `--lr-radius`, `--lr-shadow`, `--lr-icon-button-size`, `--lr-focus-ring-*`).
 
+Two further properties style the pressed view toggle: `--lr-widget-view-toggle-active-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-widget-view-toggle-active-color` (default
+`var(--lr-color-brand)`) — the background and text color of the `aria-pressed="true"` toggle. Both
+are **state hooks**: declared as inline `var()` fallbacks at the point of use and never on `:host`,
+so setting either on the element *or on any ancestor* reaches the toggle. That shape exists because
+`::part(view-toggle)[aria-pressed='true']` is not valid CSS — Shadow Parts forbids an attribute
+selector after `::part()` — so before these hooks the only way to recolor an active toggle was to
+override the library-wide `--lr-color-brand-quiet`/`--lr-color-brand` tokens, repainting every other
+element that reads them. Left unset, each falls back to exactly the token the rule used before, so
+rendering is unchanged.
+
 **Optional peer deps:** none.
 
 ```html

package/llms/components/lr-xml-viewer.md

@@ -46,7 +46,30 @@ the resolved anchor target, `data-match`, `data-active-match`), `tag` (`data-mat
 `toggle` (an element's expand/collapse button, hidden but present for row alignment on leaf/empty
 elements), `error`, `spinner`.
 
-**Themeable custom properties:** `--lr-xml-viewer-max-height` (default `none`).
+**Themeable custom properties:** `--lr-xml-viewer-max-height` (default `none`) — maximum block size
+of the scrollable body; also settable via the `max-height` property.
+`--lr-xml-viewer-active-match-color` (default `var(--lr-color-warning)`) — the solid outline on the
+`[part='node']` holding the *current* search match, leaving every other match on its dashed
+`--lr-xml-viewer-match-color` outline. It is an inline `var()` fallback at the point of use rather
+than a `:host` declaration, so it can be set on the element *or on any ancestor*:
+`::part(node)[data-active-match]` is invalid CSS — Shadow Parts forbids an attribute selector after
+`::part()` — so distinguishing the active match previously meant re-pointing the shared
+`--lr-color-warning` token, which recolored every other match (and every other warning surface)
+along with it. Unset, it falls back to that token, so rendering is unchanged.
+
+`--lr-xml-viewer-match-color` (default `var(--lr-color-warning)`) — outline color of a non-active
+`[part='node']` search match, and (via `color-mix`) the tint source for a matching `[part='text']`'s
+background — kept distinct from `--lr-xml-viewer-active-match-color` so the non-active matches can
+be recolored without touching the active one. `--lr-xml-viewer-match-bg` (default
+`var(--lr-color-warning-quiet)`) — background of a matching `[part='tag']`/`[part='attribute-value']`.
+Both are inline `var()` fallbacks at the point of use, so either can be set on the element or any
+ancestor; unset, they fall back to the same shared tokens the rules used before.
+
+`[part='toggle']`'s glyph box stays compact (`1.25rem`) while its *interactive* box takes the shared
+minimum target size as a floor via `--lr-icon-button-size`. That token is a floor, not a fixed size,
+so lowering it never squashes the chevron below its own box — the visible glyph keeps its size while
+the hit target follows the token, and it can never fall under the accessible minimum from this
+component's own rules.
 
 ```html
 <lr-xml-viewer .xml=${payload} collapsed-depth="2" copyable

package/llms/index.md

@@ -2,7 +2,7 @@
 
 # Component index
 
-249 custom elements, grouped by the source family they live in.
+251 custom elements, grouped by the source family they live in.
 
 **Reading one component.** Its reference file path is derived from the tag — no search needed:
 `llms/components/<tag>.md` (e.g. `llms/components/lr-table.md`). Each is self-contained: import
@@ -18,7 +18,7 @@ get the class without registering the tag.
 `strings`, TypeScript, frameworks, SSR): `llms/shared.md`. Design tokens: `llms/tokens.md`.
 Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 
-## Form controls & inputs — `components/forms/` (25)
+## Form controls & inputs — `components/forms/` (26)
 
 - `lr-combobox` · forms/combobox/combobox.js — a filterable single/multi select that combines a text input with a listbox.
 - `lr-option` · forms/combobox/option.js — a selectable option for `<lr-combobox>`.
@@ -45,8 +45,9 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-color-picker` · forms/color-picker/color-picker.js — a form-associated native color picker with label, hint and error chrome.
 - `lr-emoji-picker` · forms/emoji-picker/emoji-picker.js — a searchable, keyboard-navigable, form-associated emoji picker.
 - `lr-rubric-form` · forms/rubric-form/rubric-form.js — a configurable annotation rubric (LangSmith annotation-queue style): score, category, and freeform-comment keys with a submit-and-next fl...
+- `lr-locale-picker` · forms/locale-picker/locale-picker.js — a closed-list locale switcher over the library's own locale registry.
 
-## Data display, dashboards & flow canvas — `components/data/` (25)
+## Data display, dashboards & flow canvas — `components/data/` (24)
 
 - `lr-sparkline` · data/sparkline/sparkline.js — a zero-dependency inline SVG trend chart.
 - `lr-stat` · data/stat/stat.js — a KPI/stat card.
@@ -64,7 +65,6 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-flow-controls` · data/flow-controls/flow-controls.js — the canvas's button cluster: zoom in/out, fit, and interaction lock, so every flow surface ships the same affordances without hosts rebui...
 - `lr-flow-run-overlay` · data/flow-run-overlay/flow-run-overlay.js — execution-state presentation for a `lr-flow-canvas`: pushes a `FlowRunDecorations` map into the resolved canvas (the canvas itself render...
 - `lr-context-meter` · data/context-meter/context-meter.js — a segmented occupancy meter (bar or ring) for showing how a fixed capacity (a model's context window, a token budget, any consumable quot...
-- `lr-data-grid` · data/data-grid/data-grid.js — keyboard-navigable, responsive data grid with sortable columns.
 - `lr-calendar` · data/calendar/calendar.js — responsive month calendar with event markers and agenda mode.
 - `lr-timeline` · data/timeline/timeline.js — an ordered, connected sequence of past-event rows (an audit trail, an agent action history, a changelog) composed from `<lr-timeline-item...
 - `lr-timeline-item` · data/timeline/timeline-item.js — one marker + title + optional timestamp + optional description row inside `<lr-timeline>`'s default slot.
@@ -74,7 +74,7 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-graph-query-builder` · data/graph-query-builder/graph-query-builder.js — an editor for a single typed relationship/path filter (`GraphQuery`) over a knowledge graph: start/end entity anchors, relationship-type...
 - `lr-query-builder` · data/query-builder/query-builder.js — a composable structured-query builder for tabular/dashboard data: a flat list of field/operator/value condition rows combined with one AN...
 
-## Layout, navigation & structure — `components/layout/` (28)
+## Layout, navigation & structure — `components/layout/` (30)
 
 - `lr-split` · layout/split/split.js — resizable panels for dashboard layouts.
 - `lr-widget` · layout/widget/widget.js — a titled panel shell with an optional collapse toggle and an optional fullscreen-expand toggle.
@@ -85,6 +85,8 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-tabs` · layout/tabs/tabs.js — a tab strip whose panels are direct light-DOM children, each carrying `slot="<id>"` (the panel's stable id) and `label="<text>"` (the tab...
 - `lr-stepper` · layout/stepper/stepper.js — ordered multi-step wizard/form navigation: label + index per step, current/completed/locked/error state, click-to-jump.
 - `lr-control-group` · layout/control-group/control-group.js — a responsive layout primitive for a row of mixed form controls and action buttons (e.g.
+- `lr-reorder-list` · layout/reorder-list/reorder-list.js — a generic vertical list of `<lr-reorder-item>` rows, reorderable via per-row move-up/move-down buttons (always available) or Ctrl/Cmd+Arr...
+- `lr-reorder-item` · layout/reorder-list/reorder-item.js — one row inside `<lr-reorder-list>`.
 - `lr-segmented` · layout/segmented/segmented.js — a single-select button row with the WAI-ARIA APG `radiogroup` contract built in: `role="radiogroup"`/`role="radio"`, roving tabindex, aut...
 - `lr-virtual-list` · layout/virtual-list/virtual-list.js — a generic windowed/virtualized list host.
 - `lr-app-rail` · layout/app-rail/app-rail.js — a responsive navigation rail that adapts across three presentations as the *viewport* narrows (not this element's own inline size — see t...

package/llms/peers.md

@@ -14,7 +14,7 @@ If the peer is genuinely absent, the component falls back to an empty/degraded r
 
 | Peer | Range | Needed by |
 |---|---|---|
-| `@aceshooting/lyra-flags` | `workspace:^2.0.0` | `lr-flag` |
+| `@aceshooting/lyra-flags` | `workspace:^2.0.0` | `lr-flag`, `lr-phone-input` |
 | `@aiden0z/pptx-renderer` | `^1.2.4` | `lr-pptx-viewer` |
 | `@sgratzl/chartjs-chart-boxplot` | `^4.4.0` | `lr-box-plot` |
 | `chart.js` | `^4.5.0` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |

package/llms/shared.md

@@ -8,7 +8,7 @@ import '@aceshooting/lyra-ui/components/forms/combobox/combobox.js'; // register
 import '@aceshooting/lyra-ui/components/data/table/table.js';        // registers <lr-table>
 ```
 
-`llms/index.md` lists the exact path for all 249 tags. A wrong or missing family segment is a hard
+`llms/index.md` lists the exact path for all 251 tags. A wrong or missing family segment is a hard
 module-resolution failure, not a silent no-op — `exports` maps `./components/*` straight onto
 `./dist/components/*`.
 
@@ -21,7 +21,7 @@ module-resolution failure, not a silent no-op — `exports` maps `./components/*
   `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`,
   `lr-bubble-chart`, `lr-scatter-chart`), `lr-box-plot`, `lr-histogram`, `lr-map`, `lr-graph`,
   `lr-knowledge-graph-explorer`, and `lr-geojson-view`. Those always need their own subpath import.
-  The barrel also re-exports every class and type (127 `Lyra*EventMap` types included), so it is the
+  The barrel also re-exports every class and type (every `Lyra*EventMap` type included), so it is the
   one import that defeats tree-shaking — prefer per-component entries in application code.
 - **`lr-flag`** registers from the barrel, but resolving a flag by `country`/`language` (rather than
   a pre-resolved `src`) additionally needs
@@ -104,17 +104,78 @@ Readonly getters, on every form-associated control: `form`, `labels`, `validity`
 
 ## Theming and design tokens
 
-Two layers, both inherited from `LyraElement` (`internal/tokens.styles.ts`):
+Three layers, and **which one you set decides how far the override reaches**:
 
-1. **`--lr-theme-*`** — the application input layer. Set these to retheme; this is the only supported
-   theming mechanism.
+1. **`--lr-theme-*`** — the application input layer. Declared exactly once, at `:root` in
+   `theme.css`, and never inside any component's shadow styles. Set these to retheme.
 2. **`--lr-*`** — internal tokens. Each reads one `--lr-theme-*` input with a hardcoded fallback
    (`--lr-color-brand: var(--lr-theme-color-brand-fill-loud, #0969da)`), so every component renders
    correctly with no theme configured.
+3. **`--lr-<component>-*`** — per-component properties, for one element at a time. Listed in each
+   component's own section.
+
+### Where an override actually reaches
+
+**A `--lr-*` token is declared on every `lr-*` element's `:host`.** So a `--lr-*` value you set on
+an ancestor is re-declared — and lost — at the first `lr-*` element between that ancestor and the
+component you meant to style. It never reaches anything nested inside another component.
+
+**`--lr-theme-*` inputs are declared only once**, at `:root`, and never inside a component's shadow
+styles — so they inherit normally through every nested shadow root. **Setting a `--lr-theme-*` input
+on a wrapper element is the supported way to retheme one subtree.** Setting a `--lr-*` token there
+only works for that wrapper's direct children.
+
+```css
+/* Reaches everything in the subtree, however deeply nested. */
+.invoice-panel { --lr-theme-color-brand-fill-loud: #7c3aed; }
+
+/* Reaches direct lr-* children only — shadowed at the first nested lr-* host. */
+.invoice-panel { --lr-color-brand: #7c3aed; }
+```
+
+Layer 3 is the exception that proves the rule: a handful of `--lr-<component>-*` escape hatches are
+deliberately left **undeclared** by their component and read only through a `var()` fallback at the
+point of use, precisely so a value set on an ancestor is not shadowed. Each one says so in its own
+section; assume shadowing for anything that doesn't.
+
+**Diagnostic:** if a token override has no effect on a nested component, check which layer you set
+before assuming the component is at fault. A `--lr-*` override that works on a standalone control
+and stops working once you nest that control inside another component is this rule, not a bug.
+
+**There is no way to tell a live `--lr-*` declaration from a dead one without rendering.** A dead
+declaration is byte-identical to a working one in the stylesheet, and nothing in a build reports
+it — a test asserting on stylesheet source text (`expect(source).toContain('--lr-token: …')`)
+passes just as happily when the token is being shadowed at a nested host. Verify with
+`getComputedStyle` on the real element in the real state, and perturb the value deliberately to
+confirm the assertion actually bites.
+
+The same trap has a second form inside a component's own styles: a *declared* value always wins
+over a `var()` fallback arm, and `auto` is a declared value. That is why the exact-height escape
+hatches (`--lr-input-control-height`, `--lr-select-trigger-height`, `--lr-chip-height`, …) are
+undeclared by default rather than set to `auto`. Setting one *to* `auto` is therefore not the same
+as leaving it alone: it wins over the fallback arm and makes the per-size minimum-height floor dead
+code. See each control's own reference page for its exact pair.
+
+### Tokens with a contract attached
+
+- **`--lr-theme-icon-button-size`** (default `2.5rem`) backs `--lr-icon-button-size`, the tappable
+  box of **every** icon-only control in the library — `lr-icon-button` itself, and the
+  expand/clear/toggle affordances inside `lr-date-input`, `lr-combobox`, `lr-input`, and
+  `lr-select`. It is a *floor*, not a fixed size. Keep the resolved value **at or above 24px**
+  (WCAG 2.2 SC 2.5.8 target size); the default leaves headroom. Lowering it below that shrinks
+  every affordance in the library at once.
+- **Aligning your own content next to a checkbox or radio.** `--lr-checkbox-label-indent` /
+  `--lr-radio-label-indent` publish the label offset, but custom properties inherit *down*, not
+  sideways, so a sibling node in your tree cannot read them off the control. Compute the same
+  formula from the `--lr-theme-*` inputs you control:
+  ```css
+  padding-inline-start: calc(
+    min(var(--lr-theme-icon-button-size, 2.5rem), 1.75rem) + var(--lr-theme-space-s, 0.5rem)
+  );
+  ```
 
 **`llms/tokens.md` is the full generated catalog** of every token, its `--lr-theme-*` input, and its
-fallback — consult it rather than guessing a token name. Components additionally expose scoped
-`--lr-<component>-*` properties for one-off overrides, listed in each component's own section.
+fallback — consult it rather than guessing a token name.
 
 ```css
 @import '@aceshooting/lyra-ui/theme.css'; /* optional ready-made light + dark base */
@@ -155,12 +216,21 @@ setLyraLocale('fr'); // …or just set <html lang="fr"> and let components inher
 ```
 
 Exported from the package root: `registerLyraLocale`, `setLyraLocale`, `getLyraLocale`,
-`resolveLyraLocale`, `resolveLyraDirection`, `resolveLyraString`, `LYRA_DEFAULT_STRINGS`, and the
-types `LyraLocaleStrings` / `LyraMessageKey`. **`LYRA_DEFAULT_STRINGS` is the authoritative key list**
-(996 keys, matching the `LyraMessageKey` union) — read it to find the key to override rather than
+`getRegisteredLyraLocales`, `subscribeLyraLocaleRegistry`, `resolveLyraLocale`,
+`resolveLyraDirection`, `resolveLyraString`, `LYRA_DEFAULT_STRINGS`, and the types
+`LyraLocaleStrings` / `LyraMessageKey`. **`LYRA_DEFAULT_STRINGS` is the authoritative key list**
+(1005 keys, matching the `LyraMessageKey` union) — read it to find the key to override rather than
 guessing one. Lookup falls back exact locale → base language → English. Date, number, byte,
 relative-time and calendar output goes through `Intl`.
 
+`getRegisteredLyraLocales(): string[]` lists every locale with strings registered via
+`registerLyraLocale()`, plus `'en'` (always available through the built-in English fallback),
+sorted and deduped. `subscribeLyraLocaleRegistry(listener: () => void): () => void` fires whenever
+`registerLyraLocale()` registers *any* locale — including one that isn't the currently active
+locale — unlike the page-level locale-change subscription every component already uses
+internally, which only fires for the active locale's own string changes. `<lr-locale-picker>` is
+the built-in consumer of both; see `llms/components/lr-locale-picker.md`.
+
 Gotcha: `localize()`'s optional second argument is a fallback string. Passing a defined literal there
 silently defeats a registered catalog — omit it, or pass `undefined`.
 
@@ -286,7 +356,7 @@ Not custom elements — infrastructure the components compose. Importable via
   Returns a cleanup function that stops the `autoUpdate` loop — call it in `disconnectedCallback()`.
   Used by `lr-combobox`, `lr-select`, `lr-date-input`, `lr-export-button`, `lr-model-select`,
   `lr-mention-popover`, `lr-tool-call-chip`, `lr-citation-badge`, and `lr-menu`.
-- **`prefix.ts`** — `LYRA_PREFIX = 'lyra'`; `tag(name)` → `` `lr-${name}` ``; `defineElement(name, ctor)`,
+- **`prefix.ts`** — `LYRA_PREFIX = 'lr'`; `tag(name)` → `` `lr-${name}` ``; `defineElement(name, ctor)`,
   an idempotent `customElements.define` that is safe if a module is evaluated twice.
 - **`a11y.ts`** — `nextId(scope)`, a monotonic id generator (`nextId('combobox-list')` →
   `"lr-combobox-list-3"`); `srOnly`, a visually-hidden-but-AT-visible class.
@@ -319,3 +389,64 @@ Not custom elements — infrastructure the components compose. Importable via
 `custom-elements.json`, the editor metadata, and every file under `llms/` are regenerated by
 `prepack` and included in `package.json`'s `files` allowlist, so a published tarball always carries
 an up-to-date copy matching its `dist/`.
+
+## When no component fits, file it
+
+First rule out a naming mismatch: check `llms/index.md` for a component covering the same job
+under a different name. Most apparent gaps are discovery failures, not missing components.
+
+Then check the live catalog — one read-only request, no side effects, nothing filed:
+
+```bash
+curl -sS 'https://www.lyra-ui.com/api/v1/components/search?q=kanban+board+swimlane'
+```
+
+It returns the closest components with doc links. Search as many phrasings as you like; this
+endpoint is meant to be used freely, and it is the cheapest way to discover that a "missing"
+component already exists under a name you did not guess.
+
+If nothing fits, report the gap so it can be built — but **ask the user and get their explicit
+agreement first.** Filing sends the user's description to an external service; show them what you
+intend to submit, and never file as a silent side effect of noticing a gap. If the user has not
+said yes, do not send it.
+
+```bash
+curl -sS -X POST https://www.lyra-ui.com/api/v1/feature-requests \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "title": "Kanban board",
+    "description": "Needed a drag-and-drop board with swimlanes for a task view; nothing in the catalog covers it.",
+    "searched_for": ["kanban", "board", "swimlane", "drag drop"],
+    "settled_for": "a hand-rolled div grid with HTML5 drag events",
+    "agent": "claude-code"
+  }'
+```
+
+Accepted fields: `title` (required, ≤120 chars), `description` (required, ≤4000 chars), `use_case`,
+`searched_for` (array of terms tried — the most valuable field, since it records which name was
+expected and that's exactly what makes a component undiscoverable), `settled_for` (what was used
+instead), `agent`, and the optional contact fields `name` (≤120) and `email` (≤200). Anonymous
+submission is the default and is fine — `name`/`email` only add value if the maintainer might
+follow up. Ask the user whether they want to be reachable before adding either one; never invent,
+guess, or reuse an address from context you happen to have (git config, an earlier message, the
+environment). All submissions, including any name/email, are stored privately and shown only to
+the maintainer — never published.
+
+The response includes `matches` (the closest existing components, with doc links — read it, since
+it often answers the gap outright) and an `id`; status is readable later at
+`https://www.lyra-ui.com/api/v1/feature-requests/{id}`. The full schema is at
+`https://www.lyra-ui.com/api/v1/openapi.json`.
+
+**Never include private material.** Submissions leave the user's machine. Describe the component
+generically — no source code, no client or product names, no file paths, no credentials. If the
+need cannot be described without such details, do not file it.
+
+Use the API even when you are working inside the lyra-ui repo itself. It is the only intake path —
+do not write the request into a local file instead, where nothing will pick it up.
+
+Keep the report short and concrete:
+
+- **Name the component you wanted**, in library style (`lr-kanban-board`), so the gap is searchable.
+- **Say what it had to do** in a sentence or two — the behaviour, not your implementation.
+- **List the `lr-*` components you actually checked** and why each fell short. This is what separates
+  a real gap from a naming mismatch, and it is the part only you can supply.

package/llms/tokens.md

@@ -16,7 +16,7 @@ For a ready-made light/dark base, import `@aceshooting/lyra-ui/theme.css` once a
 Per-component `--lr-<component>-*` custom properties (listed in each component's own section)
 override a single element without touching the shared layer.
 
-## Themeable inputs (228)
+## Themeable inputs (234)
 
 | Internal token | `--lr-theme-*` input | Fallback |
 |---|---|---|
@@ -41,7 +41,7 @@ override a single element without touching the shared layer.
 | `--lr-color-on-danger` | `--lr-theme-color-danger-on-loud` | `#fff` |
 | `--lr-color-on-neutral` | `--lr-theme-color-neutral-on-loud` | `#fff` |
 | `--lr-color-overlay` | `--lr-theme-color-overlay` | `rgb(0 0 0 / 0.5)` |
-| `--lr-color-overlay-strong` | `--lr-theme-color-overlay` | `rgb(0 0 0 / 0.92)` |
+| `--lr-color-overlay-strong` | `--lr-theme-color-overlay-strong` | `var(--lr-theme-color-overlay, rgb(0 0 0 / 0.92))` |
 | `--lr-color-no-data` | `--lr-theme-color-no-data` | `rgb(128 128 128 / 25%)` |
 | `--lr-font-mono` | `--lr-theme-font-family-mono` | `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` |
 | `--lr-space-xs` | `--lr-theme-space-xs` | `0.25rem` |
@@ -50,6 +50,7 @@ override a single element without touching the shared layer.
 | `--lr-space-l` | `--lr-theme-space-l` | `1rem` |
 | `--lr-space-2xs` | `--lr-theme-space-2xs` | `0.125rem` |
 | `--lr-space-2xl` | `--lr-theme-space-2xl` | `2rem` |
+| `--lr-font-size-3xs` | `--lr-theme-font-size-3xs` | `0.5rem` |
 | `--lr-font-size-2xs` | `--lr-theme-font-size-2xs` | `0.625rem` |
 | `--lr-font-size-xs` | `--lr-theme-font-size-xs` | `0.75rem` |
 | `--lr-font-size-sm` | `--lr-theme-font-size-sm` | `0.8125rem` |
@@ -211,7 +212,12 @@ override a single element without touching the shared layer.
 | `--lr-transition-base` | `--lr-theme-transition-normal` | `180ms ease-out` |
 | `--lr-transition-ambient` | `--lr-theme-transition-slow` | `1.8s ease-in-out` |
 | `--lr-opacity-disabled` | `--lr-theme-opacity-disabled` | `0.5` |
+| `--lr-hover-brightness` | `--lr-theme-hover-brightness` | `1.08` |
+| `--lr-popover-viewport-clamp` | `--lr-theme-popover-viewport-clamp` | `92vw` |
+| `--lr-focus-ring-width` | `--lr-theme-focus-ring-width` | `2px` |
 | `--lr-focus-ring-color` | `--lr-theme-color-focus` | `var(--lr-color-brand)` |
+| `--lr-focus-ring-offset` | `--lr-theme-focus-ring-offset` | `2px` |
+| `--lr-icon-button-size` | `--lr-theme-icon-button-size` | `2.5rem` |
 | `--lr-color-surface` | `--lr-theme-color-surface-default` | `#1a1a1a` |
 | `--lr-color-surface-raised` | `--lr-theme-color-surface-raised` | `#22272e` |
 | `--lr-color-text` | `--lr-theme-color-text-normal` | `#f2f2f2` |
@@ -249,7 +255,7 @@ override a single element without touching the shared layer.
 | `--lr-graph-cat-7` | `--lr-theme-graph-cat-7` | `#79e2ef` |
 | `--lr-graph-cat-8` | `--lr-theme-graph-cat-8` | `#e4e7eb` |
 
-## Derived tokens (276)
+## Derived tokens (279)
 
 Computed from the layer above; not directly themeable.
 
@@ -276,7 +282,7 @@ Computed from the layer above; not directly themeable.
 | `--lr-color-on-danger` | `var(--lr-theme-color-danger-on-loud, #fff)` |
 | `--lr-color-on-neutral` | `var(--lr-theme-color-neutral-on-loud, #fff)` |
 | `--lr-color-overlay` | `var(--lr-theme-color-overlay, rgb(0 0 0 / 0.5))` |
-| `--lr-color-overlay-strong` | `var(--lr-theme-color-overlay, rgb(0 0 0 / 0.92))` |
+| `--lr-color-overlay-strong` | `var(--lr-theme-color-overlay-strong, var(--lr-theme-color-overlay, rgb(0 0 0 / 0.92)))` |
 | `--lr-color-no-data` | `var(--lr-theme-color-no-data, rgb(128 128 128 / 25%))` |
 | `--lr-font-mono` | `var(--lr-theme-font-family-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace)` |
 | `--lr-space-xs` | `var(--lr-theme-space-xs, 0.25rem)` |
@@ -285,6 +291,7 @@ Computed from the layer above; not directly themeable.
 | `--lr-space-l` | `var(--lr-theme-space-l, 1rem)` |
 | `--lr-space-2xs` | `var(--lr-theme-space-2xs, 0.125rem)` |
 | `--lr-space-2xl` | `var(--lr-theme-space-2xl, 2rem)` |
+| `--lr-font-size-3xs` | `var(--lr-theme-font-size-3xs, 0.5rem)` |
 | `--lr-font-size-2xs` | `var(--lr-theme-font-size-2xs, 0.625rem)` |
 | `--lr-font-size-xs` | `var(--lr-theme-font-size-xs, 0.75rem)` |
 | `--lr-font-size-sm` | `var(--lr-theme-font-size-sm, 0.8125rem)` |
@@ -450,10 +457,12 @@ Computed from the layer above; not directly themeable.
 | `--lr-transition-base` | `var(--lr-theme-transition-normal, 180ms ease-out)` |
 | `--lr-transition-ambient` | `var(--lr-theme-transition-slow, 1.8s ease-in-out)` |
 | `--lr-opacity-disabled` | `var(--lr-theme-opacity-disabled, 0.5)` |
-| `--lr-focus-ring-width` | `2px` |
+| `--lr-hover-brightness` | `var(--lr-theme-hover-brightness, 1.08)` |
+| `--lr-popover-viewport-clamp` | `var(--lr-theme-popover-viewport-clamp, 92vw)` |
+| `--lr-focus-ring-width` | `var(--lr-theme-focus-ring-width, 2px)` |
 | `--lr-focus-ring-color` | `var(--lr-theme-color-focus, var(--lr-color-brand))` |
-| `--lr-focus-ring-offset` | `2px` |
-| `--lr-icon-button-size` | `2.5rem` |
+| `--lr-focus-ring-offset` | `var(--lr-theme-focus-ring-offset, 2px)` |
+| `--lr-icon-button-size` | `var(--lr-theme-icon-button-size, 2.5rem)` |
 | `--lr-safe-area-inline-start` | `env(safe-area-inset-right, 0px)` |
 | `--lr-safe-area-inline-end` | `env(safe-area-inset-left, 0px)` |
 | `--lr-color-surface` | `var(--lr-theme-color-surface-default, #1a1a1a)` |