@aceshooting/lyra-ui 5.1.0 → 6.0.0

package/llms/components/lr-heatmap.md

@@ -38,6 +38,16 @@ focus; it continues to emit `lr-cell-click` and leaves selection state consumer-
   measured `clientWidth` on every draw/resize instead of the fixed `cell-size`, so the grid actually
   fills the available width; now applies to calendar mode as well as matrix mode — see gotchas for
   the default, non-`fit-to-width` behavior)
+- `maxCellSize?: number` (attribute `max-cell-size`) — ceiling, in CSS px, on the cell size
+  `fitToWidth` derives from the host width, in **both** modes. Exists because `fitToWidth` divides
+  the *whole* host width across the grid, so a 5-week calendar or a 3-column matrix in a wide pane
+  produces enormous blocks; capping them keeps a cell a cell
+- `minCellSize?: number` (attribute `min-cell-size`) — the mirror floor, in CSS px, so a year-long
+  calendar in a narrow pane keeps legible, hit-testable cells and overflows its host instead of
+  collapsing to hairlines. It can only *raise* the built-in `4`px floor, never lower it: a value
+  below `4` normalizes to `4`. When both clamps are set and `maxCellSize < minCellSize`, the ceiling
+  wins. For both: a non-finite value, or an empty attribute, means unset rather than `0`, and unset
+  (the default) reproduces the unclamped fit-to-width behavior exactly
 - `valueLabel: string = 'value'` (attribute `value-label`)
 - `scale: 'linear' | 'sqrt' = 'linear'` — governs both modes: in matrix mode, `'sqrt'` compresses the
   color ramp via `sqrtStep()` instead of mapping linearly; in calendar mode, the default `'linear'`
@@ -71,7 +81,12 @@ focus; it continues to emit `lr-cell-click` and leaves selection state consumer-
   its low DOM footprint.
 - `cellText?: (pos: MatrixCellPos | CalendarCellPos, value: number) => string` (attribute: false) —
   formats the per-cell hover tooltip and keyboard live-region announcement text; receives the cell
-  position (`{ row, col }` in matrix mode, `{ week, weekday }` in calendar mode) and its value.
+  position (`MatrixCellPos { row, col }` in matrix mode, `CalendarCellPos { week, weekday, date }` in
+  calendar mode) and its value. `CalendarCellPos.date` is a **required** ISO `yyyy-mm-dd` string,
+  present for every grid position — including a sparse gap position with no matching entry in `days`
+  at all, which still sits on a real calendar day (that case simply reports the `-1` "no data" value
+  alongside it). It lets a callback key off the date without re-deriving the grid's own
+  anchor-week arithmetic; `MatrixCellPos` is unchanged, and so is `lr-cell-click`'s detail.
   Unset (the default) falls back to the built-in English "Row X, Col Y: value" (matrix) / "Jan 15:
   value" — short month + day, **not** a weekday abbreviation (calendar) — template. Additive, not
   breaking.
@@ -118,10 +133,14 @@ focus; it continues to emit `lr-cell-click` and leaves selection state consumer-
   interpolate continuously into `colorSteps.length` buckets instead. Unset (the default, or fewer
   than 2 entries) keeps today's 2-endpoint interpolation exactly.
 - `legendStops?: HeatmapLegendStop[]` (attribute: false) — `HeatmapLegendStop { value: number;
-  color: string; label?: string }`: a discrete legend key rendered **instead of** the
+  color?: string; label?: string }`: a discrete legend key rendered **instead of** the
   `--lr-heatmap-scale-lo`/`-hi` gradient bar and its `[part="legend-lo"]`/`[part="legend-hi"]`
   endpoint labels — one `[part="legend-stop"]` per entry, in array order, each a
   `[part="legend-swatch"]` filled with that entry's `color` plus a `[part="legend-stop-label"]`.
+  `color` is optional: omit it (or pass an empty string) for a **caption-only** stop, which renders
+  its `[part="legend-stop-label"]` alone with no `[part="legend-swatch"]` element in the DOM at all —
+  so a leading "0" or trailing "more" caption around a run of colored stops doesn't leave an empty
+  swatch box in the row.
   A stop's label defaults to the component's own locale-aware numeric formatting of `value`, so an
   explicit `label` is only needed when the number isn't the right caption ("none", "≥ 90%"). Exists
   for the consumer who supplies `cellColor`: because that callback overrides a cell's color
@@ -147,7 +166,9 @@ button), `tooltip` (hover tooltip, positioned over the hovered cell),
 `live-region` (visually-hidden `role="status" aria-live="polite"` element announcing the
 keyboard-focused cell), `legend`, `legend-lo`, `legend-hi` (both omitted, along with the gradient
 bar between them, while `legendStops` is supplied), `legend-stop` (one per `legendStops` entry),
-`legend-swatch` (that stop's color chip), `legend-stop-label` (that stop's text),
+`legend-swatch` (that stop's color chip, not rendered at all for a caption-only stop),
+`legend-stop-label` (that stop's text), `legend-value-label` (the trailing `valueLabel` caption that
+closes the legend row, present in both the gradient and the `legendStops` branch),
 `legend-annotation` (one per labeled `annotations` entry)
 
 **Themeable custom properties:** `--lr-heatmap-scale-lo` (default `#cde2fb`),
@@ -212,6 +233,11 @@ same color as `--lr-heatmap-focus-ring-color`).
   width, so a container-resize redraw is a geometric no-op; the stylesheet's
   `canvas { inline-size: 100% }` is also dead code in that case, since `draw()` unconditionally sets
   an inline `canvas.style.width/height` that wins over it.
+- `maxCellSize`/`minCellSize` are no-ops without `fit-to-width` — an explicit `cellSize` is an exact
+  request and is never clamped. And the canvas is sized *from the clamped* cell size, so a capped
+  grid deliberately leaves the host's remaining width unfilled: the canvas simply ends early rather
+  than stretching to fill. Position it with ordinary CSS on the host if you want it centered or
+  end-aligned.
 - the host is `role="group"` (not `role="img"`) with a dimensions+range summary `aria-label`
   (calendar mode: a day-count + range summary instead) — `[part="canvas"]` inside it is a real
   focusable, keyboard-operable, per-cell-interactive control (roving arrow-key focus,

package/llms/components/lr-histogram.md

@@ -40,7 +40,9 @@ and `label` the generated bucket range string (`"lo–hi"`, both bounds at one d
 
 **Slots:** `data-table`, `center`.
 
-**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`.
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`,
+`error` (`role="alert"` message rendered in place of `canvas` when the optional `chart.js` peer
+dependency fails to load — inherited from `LyraChart`, unaffected by the binning logic).
 
 **Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
 `--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,

package/llms/components/lr-icon-button.md

@@ -29,11 +29,32 @@ With neither `accessibleLabel` nor `label` set, the name falls back to the local
 app-wide with `registerLyraLocale()` (see `llms/shared.md`); don't rely on the fallback for a
 button whose purpose isn't generic.
 
-**Methods:** `focus(options?)`, `blur()` — forward to the native button.
-
-**Slots:** (default) — custom icon content, forwarded into the inner `lr-icon`'s slot; use it
-instead of `icon` for a glyph outside the built-in set.
-
-**CSS parts:** `button`
-
-**Themeable custom properties:** `--lr-icon-button-size` sets both dimensions of the hit target.
+**Methods:** `focus(options?)`, `blur()` — forward to the native button. `click()` also forwards to
+the native button, activating it — including this component's own `type="submit"`/`type="reset"`
+handling, since the click goes through the same `<button>` the pointer/keyboard path does.
+
+**Slots:** (default) — custom icon content. It is rendered **beside** the `icon` glyph, as a
+sibling of it, not piped through `<lr-icon>`: the internal `<lr-icon>` mounts only when `icon` is
+set, so with `icon` left empty your content is the button's only child. That is what lets a
+complete element — an `<svg>`, an `<img>`, an `<lr-flag>` — render at its own natural aspect ratio
+instead of being forced into a 1:1 box. Setting both `icon` and slotted content renders both, side
+by side; that is a valid composition, not a fallback.
+
+**Bare SVG geometry fallback:** slotted bare SVG *geometry* (`path`, `circle`, `rect`, `line`,
+`polygon`, `polyline`, `ellipse`, `g`, `use`) with no `icon` set and no enclosing `<svg>` of its
+own has no real SVG parent as parsed, and is detected and cloned into an internal
+`[part="fallback"]` SVG-namespaced element so it still paints — the same fallback `<lr-icon>`'s own
+custom-content slot uses. This is narrowly scoped to that whitelist: a complete `<svg>`, `<img>`,
+or custom element (e.g. `<lr-flag>`) is never touched by it and keeps rendering as an untouched
+sibling at its own natural aspect ratio.
+
+**CSS parts:** `button`, `fallback` (only present in the DOM while at least one top-level slotted
+element needs the bare-geometry fallback above)
+
+**Themeable custom properties:** `--lr-icon-button-size` (default `2.5rem`) is the **minimum**
+tappable inline and block size of the native button — a floor, not a fixed size. Content larger
+than it grows the button and keeps its own aspect ratio; a small glyph pads out to it. It is a
+library-wide token (declared on `:root` by the token layer, and the shared minimum tappable size
+that several other components size their icon-only controls against), so overriding
+`--lr-theme-icon-button-size` globally resizes all of them together. Keep the resolved value at or
+above 24px — see `llms/shared.md`.

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

@@ -18,7 +18,12 @@ documents) and `<lr-image-comparer>` (before/after slotted surfaces). Adopts `Do
 with `anchorKinds: ['region']` only — no text selection is bound.
 
 **Properties:** `src: string = ''`, `name: string = ''`, `alt?: string`, `fit: 'contain' | 'width' |
-'actual' = 'contain'` (reflected), `zoom: number = 1` (reflected), `rotation: 0 | 90 | 180 | 270 = 0`
+'actual' = 'contain'` (reflected), `zoom: number = 1` (reflected), `minZoom: number = 0.5` (attribute
+`min-zoom`), `maxZoom: number = 4` (attribute `max-zoom`), `zoomStep: number = 0.25` (attribute
+`zoom-step`) — `minZoom`/`maxZoom`/`zoomStep` are pure pass-throughs to the embedded
+`<lr-zoomable-frame>` as its own `.minZoom`/`.maxZoom`/`.zoomStep`, which does the actual
+clamping/normalizing; same names/defaults as `<lr-lightbox>`'s identical trio, both wrapping the
+same pan/zoom surface — `rotation: 0 | 90 | 180 | 270 = 0`
 (reflected), and `annotatable: boolean = false` (reflected).
 
 **Methods:** `rotate()` advances `rotation` by 90°. `zoomIn()`, `zoomOut()`, and `resetZoom()` adjust
@@ -33,3 +38,17 @@ zoom }`), `lr-rotation-change` (`detail: { rotation }`), `lr-fit-change` (`detai
 **CSS parts:** `base`, `toolbar`, `fit-control`, `rotate-button`, `annotate-toggle`, `frame` (the
 embedded `lr-zoomable-frame`), `image-wrapper`, `image`, `highlight-layer`, `highlight` (carries
 `data-tone`/`data-active`), `highlight-label`, `annotation-box`, and `error`.
+
+**Themeable custom properties:** `--lr-image-viewer-annotate-active-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-image-viewer-annotate-active-border` (default
+`var(--lr-color-brand)`) — the background and border of `[part='annotate-toggle']` while annotation
+mode is on. The toggle carries its own glyph in `--lr-color-text`, so keep a 4.5:1 ratio against it
+when overriding the background. `--lr-image-viewer-highlight-active-color` (default
+`var(--lr-color-brand)`) — the outline of the `[part='highlight']` matching `activeHighlightId`,
+independent of the per-tone border colors, so the active box stays distinguishable whatever tone it
+carries. All three are declared as inline `var()` fallbacks at the point of use rather than on
+`:host`, so each can be set on the element *or on any ancestor*: `::part(highlight)[data-active]` is
+invalid CSS — Shadow Parts forbids an attribute selector after `::part()` — which previously left
+overriding the library-wide `--lr-color-brand`/`--lr-color-brand-quiet` tokens as the only lever,
+repainting every other element that read them. Unset, each falls back to the token its rule used
+before.

package/llms/components/lr-ingestion-queue.md

@@ -51,6 +51,14 @@ per-item stage label), `item-progress`,
 `item-error` (only for `stage="failed"` with `error` set), `item-actions`, `retry-button`,
 `cancel-button`, `empty`.
 
+In virtualized mode (at or above `virtualizeThreshold`) the rows live in the internal
+`lr-virtual-list`'s shadow root, and `item`, `item-header`, `item-name`, `item-progress`,
+`item-meta`, `item-error`, `item-actions`, `retry-button` and `cancel-button` are forwarded out
+through `exportparts`, so `lr-ingestion-queue::part(item)` and the rest keep working from a consumer
+stylesheet. `item-stage`, `item-chunk-count`, `item-embedding-status` and `item-attempts` are not
+forwarded, so those four are only reachable through `::part()` while the queue is below the
+threshold.
+
 **Themeable custom properties:** `--lr-ingestion-queue-max-height` (default `none`) — non-virtualized
 mode only: caps how tall the list grows before it scrolls internally. No effect once virtualized —
 retheme the internal list via `lr-virtual-list { --lr-virtual-list-height: … }` instead.

package/llms/components/lr-input.md

@@ -46,7 +46,14 @@ form-associated via the same `FormAssociated` mixin as `lr-textarea`. Ships the
 - `name`/`disabled`/`required` (from `FormAssociated`)
 
 **Getters/methods:** `input: HTMLInputElement | null` (the internal native `<input>`, for direct DOM
-access), `focus(options?: FocusOptions)`, `blur()`, `select()`.
+access), `focus(options?: FocusOptions)`, `blur()`, `select()`. Also forwards the full native
+selection/editing surface, mirroring `lr-textarea`'s identical passthrough: `selectionStart: number
+| null` and `selectionEnd: number | null` (readable/writable; `null` both before the internal input
+has rendered and whenever `type` doesn't support selection — only `text`/`search`/`password` do,
+matching the native `<input>`'s own contract), `setSelectionRange(start, end, direction?)`
+(no-op before render, otherwise throws the same native `InvalidStateError` a native `<input>` would
+for an unsupported `type`), and `setRangeText(replacement, start?, end?, selectMode?)` (no-op
+before render; syncs `value` afterward without emitting a user event).
 
 **Events:** native-style composed `input` and `change`, plus `lr-input` (`detail: { value }`,
 fired on every user-driven edit) and `lr-change` (`detail: { value }`, fired on the native
@@ -65,6 +72,34 @@ input and built-in actions).
 `--lr-input-font-size`, `--lr-input-control-min-height` — all four auto-swapped per `size`
 (`2xs`…`xl`), the same pattern
 `lr-select`'s `--lr-select-trigger-padding`/`--lr-select-font-size` use.
+`--lr-input-control-height` pins an **exact** outer control-row height (both floors and caps it) —
+for example to pixel-match an `<lr-select>` or `<lr-combobox>` in the same toolbar row. It is
+undeclared by default, leaving `--lr-input-control-min-height` as a floor only and the row free to
+grow.
+
+### Exact-height hatches — the one rule that applies to all of them
+
+Several controls expose the same pair: a per-`size` `*-min-height` **floor**, and an exact
+`*-height` **cap**. The family is `--lr-input-control-height`, `--lr-select-trigger-height`,
+`--lr-combobox-trigger-height`, `--lr-date-input-control-height`, `--lr-button-height`,
+`--lr-known-date-field-height`, and `--lr-chip-height`. Every one of them behaves identically:
+
+- **Each is undeclared by default.** The component reads it only through two `var()` fallbacks —
+  `min-block-size: var(--lr-x-height, var(--lr-x-min-height))` and
+  `block-size: var(--lr-x-height, auto)` — so leaving it unset is what makes the per-tier floor
+  and the content-driven height work at all.
+- **Setting one to `auto` is not the same as leaving it unset.** `auto` is a perfectly valid
+  *declared* value, and a declared value wins over the `var()` fallback arm — so `auto` silently
+  turns the per-tier `*-min-height` floor into dead code, and nothing anywhere reports it. To
+  return a control to default behavior, **remove** the declaration; never neutralize it with
+  `auto`.
+- Because the component itself never declares them, each can be set inline on the element, from an
+  ancestor, or from an outer-tree rule (`lr-input { --lr-input-control-height: 44px }`) — no
+  `::part()` rule needed.
+- **A dead declaration is invisible in source.** There is no way to tell a live `--lr-*`
+  declaration from a shadowed or defeated one without rendering: a test asserting on stylesheet
+  text passes either way. Assert the rendered `min-block-size`/`block-size` via
+  `getComputedStyle` on the real element instead of reading the custom property back.
 
 **Optional peer deps:** none.
 

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

@@ -62,9 +62,12 @@ clipboard") or a per-node one (aria-label `Copy ${key/type}`, e.g. "Copy age");
 `copyable`)
 
 **Themeable custom properties:** `--lr-json-viewer-max-height` (default `none` — grows with content
-until `max-height` is set), `--lr-json-viewer-font` (default `ui-monospace, SFMono-Regular, Menlo,
-Consolas, monospace` — component-specific since no shared monospace token exists), plus shared tokens
-`--lr-color-border/-surface/-text/-text-quiet/-brand/-brand-quiet/-success/-warning/-warning-quiet`,
+until `max-height` is set), `--lr-json-viewer-font` (default `var(--lr-font-mono)`),
+`--lr-json-viewer-match-bg` (default `var(--lr-color-warning-quiet)`) — background, and surrounding
+box-shadow, of a key/value that currently matches `search`. Component-scoped indirection over the
+shared `--lr-color-warning-quiet` token, so a consumer can retheme just this search-match highlight
+without repainting every other warning-toned surface that reads the same shared token. Plus shared
+tokens `--lr-color-border/-surface/-text/-text-quiet/-brand/-brand-quiet/-success/-warning/-warning-quiet`,
 `--lr-radius`, `--lr-space-xs/-s/-l`, `--lr-focus-ring-width/-color/-offset`,
 `--lr-transition-fast`.
 

package/llms/components/lr-known-date.md

@@ -58,12 +58,31 @@ block, repeated three times, `data-field="day"|"month"|"year"`), `field-input` (
 small per-field text label), `hint`, `error` (`role="alert"`).
 
 **Themeable custom properties:** `--lr-known-date-field-padding-block`,
-`--lr-known-date-field-padding-inline`, `--lr-known-date-field-font-size` (all three rewritten by
-each `:host([size])` rule; `m` defaults `--lr-space-s`/`--lr-space-s`/`--lr-font-size-md-sm`),
+`--lr-known-date-field-padding-inline`, `--lr-known-date-field-font-size`,
+`--lr-known-date-field-min-height` (all four rewritten by
+each `:host([size])` rule; `m` defaults `--lr-space-s`/`--lr-space-s`/`--lr-font-size-md-sm`/
+`--lr-size-2-5rem`), `--lr-known-date-field-height`,
 `--lr-known-date-field-gap` (default `--lr-space-s` — gap between the three field blocks),
 `--lr-known-date-day-field-width` / `--lr-known-date-month-field-width` (default `--lr-size-3-5em`)
 and `--lr-known-date-year-field-width` (default `--lr-size-5em`) — the per-field input widths, not
-size-scaled.
+size-scaled. `--lr-known-date-invalid-border-color` (default `var(--lr-color-danger)`) — border
+color of each `field-input` while `:host([data-invalid])` is set. Component-scoped indirection over
+the shared `--lr-color-danger` token, so a consumer can retheme just this invalid-field border
+without repainting every other component that reads the same shared danger token.
+
+The two height knobs work as a pair on `[part='field-input']`, the same way
+`lr-input`/`lr-select`/`lr-combobox`/`lr-date-input` expose theirs:
+
+- `--lr-known-date-field-min-height` is a **floor**, re-assigned per `size` tier. Every tier's
+  default sits below the field's own padding/font-driven height, so raising it is what makes it
+  visible; lowering it changes nothing.
+- `--lr-known-date-field-height` pins an **exact** height (both floors and caps), so the three
+  inputs can line up with a neighbouring control of a known height. It is **undeclared by
+  default** — the field grows to fit its content. Never set it to `auto`: `auto` is a valid
+  declared value that wins over the `var()` fallback arm, which would make the per-tier floor
+  dead code. To go back to the default behavior, remove the declaration rather than neutralizing
+  it. Because the component never declares it, it can be set inline, from an ancestor, or from an
+  outer-tree rule.
 
 **Known gotchas:**
 - Field *order* is derived from the locale by formatting a probe date (Jan 2 2026) with

package/llms/components/lr-line-chart.md

@@ -38,7 +38,9 @@ index, label, value }`).
 
 **Slots:** `data-table`, `center`.
 
-**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`.
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`,
+`error` (`role="alert"` message rendered in place of `canvas` when the optional `chart.js` peer
+dependency fails to load — see `llms/components/lr-chart.md`).
 
 **Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
 `--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,

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

@@ -0,0 +1,86 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-locale-picker`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/locale-picker/locale-picker.js';` (registers the tag; side-effect import)
+- **Class** `LyraLocalePicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/locale-picker/locale-picker.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-locale-picker`
+
+A closed-list locale switcher over the library's own locale registry. First-party invention (no
+Web Awesome equivalent). With `locales` unset (the default), the offered rows are exactly
+`getRegisteredLyraLocales()` — every locale with strings registered via `registerLyraLocale()`,
+plus `en` — kept live via `subscribeLyraLocaleRegistry()`. Built directly on `lr-select`'s
+trigger-button/`aria-activedescendant` listbox technique, not composed from it — a plain closed
+list, no filter/free-text mode.
+
+**Properties:**
+- `locales: LyraLocaleCatalog = []` (attribute: false) — `LyraLocaleCatalog = string[] |
+  LyraLocaleEntry[]`, `LyraLocaleEntry { tag: string; label?: string }`. Empty (the default)
+  auto-discovers the registry; a non-empty array (either form) overrides it entirely — a curated
+  subset, custom order, custom labels, or a locale offered before its strings are registered.
+- `showFlags: boolean = true` — each row's leading `<lr-flag language={tag} variant="compact">`;
+  `false` omits the flag element entirely (not just visually).
+- `value: string = ''` — the **committed** selection (form value, drives `lr-change`). While `''`
+  and untouched, the trigger *displays* `effectiveLocale` as a preview label, but
+  `checkValidity()`/`required` are governed by the real `value`, which stays `''` until a real
+  commit — mirrors a native `<select>` showing its first option's text without that being a
+  committed selection.
+- `required: boolean = false`, `disabled: boolean = false`, `name: string = ''` — standard
+  form-associated properties.
+- `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute `error-text`) —
+  same opt-in form-control chrome as `lr-select` (props + matching named slots + parts); unset
+  renders none of it.
+- `open: boolean = false` (reflected).
+- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected — same scale as `lr-select`'s `size`).
+
+**Events:** `lr-change` (`detail: { value, previousValue }`, **cancelable**) — fired on every
+explicit pick; if not `defaultPrevented`, the component applies the pick itself via
+`setLyraLocale(value)`. A listener calling `event.preventDefault()` leaves `value` updated but the
+active locale untouched, so a host can persist the choice first and apply it later. `blur`/`focus`
+re-dispatched from the internal trigger as bubbling, composed events.
+
+**Methods:** `focus(options?)`, `blur()`, and `click()` — all forward to the internal trigger
+button, same convention as `lr-select`'s identical trio.
+
+**Slots:** `label`, `hint`, `error`.
+
+**CSS parts:** `form-control`, `form-control-label`, `trigger`, `listbox`, `option`,
+`option-flag` (present only while `showFlags` is on), `option-label`, `option-tag` (the row's
+secondary line — the raw BCP-47 tag), `expand-icon`, `hint`, `error`.
+
+**Themeable custom properties:** `--lr-locale-picker-trigger-padding`,
+`--lr-locale-picker-trigger-min-height`, `--lr-locale-picker-trigger-height` (unset by default, a
+floor-only escape hatch — set a length to both floor and cap the trigger),
+`--lr-locale-picker-font-size`, `--lr-locale-picker-expand-size` (all scaled by `size`), and
+`--lr-locale-picker-option-active-bg` (default `--lr-color-brand-quiet`, the hovered/keyboard-active
+row background).
+
+**Optional peer deps:** none directly — each row's `<lr-flag>` degrades to an empty render (no
+peer warning duplication; `lr-flag` itself already logs one) when the optional
+`@aceshooting/lyra-flags` package isn't installed and `showFlags` is left on.
+
+```html
+<lr-locale-picker label="Language"></lr-locale-picker>
+<script type="module">
+  import { registerLyraLocale } from '@aceshooting/lyra-ui';
+  registerLyraLocale('fr', { close: 'Fermer' });
+  document
+    .querySelector('lr-locale-picker')
+    .addEventListener('lr-change', (e) => console.log(e.detail.value));
+</script>
+```
+
+**Known gotchas:**
+- selecting a row applies `setLyraLocale()` itself unless the listener calls
+  `event.preventDefault()` on `lr-change` — it does not touch
+  `document.documentElement.lang`/`dir`; apply writing-direction changes to the page yourself.
+- no filter/free-text mode — for a catalog with hundreds+ of rows, roll your own with `lr-select`
+  or `lr-combobox` instead.
+- arrow-key navigation is vertical-only (Home/End/ArrowUp/ArrowDown); there is no
+  ArrowLeft/ArrowRight remap under RTL, since there is no horizontal axis to remap.

package/llms/components/lr-map.md

@@ -66,7 +66,9 @@ exists and was hit)
 
 **Slots:** none.
 
-**CSS parts:** `base`, `container`, `legend`, `legend-swatch`
+**CSS parts:** `base`, `container`, `legend`, `legend-swatch`, `error` (`role="alert"` message
+rendered in place of `container` if the optional `maplibre-gl` peer dependency fails to load, e.g.
+not installed)
 
 **Themeable custom properties:** shared tokens only — `--lr-space-xs/-s`, `--lr-color-surface`,
 `--lr-color-border`, `--lr-shadow`, `--lr-radius`.

package/llms/components/lr-markdown-core.md

@@ -52,6 +52,15 @@ unhighlighted permanently, `headingAnchors: boolean = false` (attribute `heading
 **CSS parts:** `content`, `heading`, `paragraph`, `list`, `code-block`, `inline-code`, `link`,
 `table`, `blockquote`, `img`, `math` — identical to `<lr-markdown>`'s own parts.
 
+**Themeable custom properties:** `--lr-code-block-tab-size` (default `2` — tab width inside a
+rendered fenced or indented `code-block`), with exactly the mechanics described under
+`<lr-markdown>` above: the same property name and default that `<lr-code-block>`/`<lr-code-editor>`
+read, declared as a `var()` fallback at the point of use rather than on `:host` so a page- or
+container-level value reaches it, and carried here in its own right because this element is a
+**sibling** of `<lr-code-block>` rather than an ancestor of it. Markdown code blocks wrap
+(`white-space: pre-wrap`) while `<lr-code-block>` does not, so the same tab width can render
+differently on a wrapped line.
+
 **Optional peer deps:** `marked`, `dompurify` (both lazy-loaded, same as `<lr-markdown>`), `katex`
 (for `math`). Does *not* depend on the full `shiki` package's default entry point — only
 `shiki/core`/`shiki/engine/oniguruma`/`shiki/langs/*`, the same fine-grained subset

package/llms/components/lr-markdown.md

@@ -114,7 +114,8 @@ carrying `data-display="inline"|"block"`)
 
 **Themeable custom properties:** `--lr-markdown-font-mono` (default `ui-monospace, SFMono-Regular,
 Menlo, Consolas, monospace` — the code/code-block font; component-specific since no shared
-`--lr-*` monospace token exists), plus shared tokens `--lr-space-xs/-s/-m/-l`,
+`--lr-*` monospace token exists), `--lr-code-block-tab-size` (default `2` — tab width inside a
+rendered fenced or indented `code-block`), plus shared tokens `--lr-space-xs/-s/-m/-l`,
 `--lr-color-brand-quiet`, `--lr-color-brand`, `--lr-color-border`, `--lr-color-text-quiet`,
 `--lr-radius`.
 
@@ -150,6 +151,17 @@ cleared in `updated()` based on whether the deps have loaded) and shows the same
 rendering — there's no separate loading skeleton, since the un-rendered Markdown source is already
 legible text in the meantime.
 
+**One tab width for every code surface.** `--lr-code-block-tab-size` is deliberately the same
+property name and default (`2`) that `<lr-code-block>` and `<lr-code-editor>` use, so a consumer sets
+tab width once for every code surface in the app. It is declared as a `var()` fallback **at the point
+of use, never on `:host`** — a `:host` declaration is re-stamped on every instance and shadows any
+inherited value, so a page- or container-level declaration could never reach it. This element carries
+its own copy of that fallback rather than inheriting `<lr-code-block>`'s because the two are
+**sibling** custom elements, not ancestor and descendant: no single declaration inside one of them
+can cover the other. The same value can still *look* different between the two — a markdown code
+block inherits `white-space: pre-wrap` while `<lr-code-block>` is `white-space: pre`, and tab stops
+restart at the beginning of each visual line, so a wrapped line's tabs land differently.
+
 **Known gotchas:**
 - a malformed percent-escape or lone UTF-16 surrogate in a link's raw `href` makes the internal
   `encodeURI`-based validity guard throw, silently dropping just that anchor (the link text still

package/llms/components/lr-media-card.md

@@ -34,6 +34,11 @@ final.
   overrides the `--lr-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
   shadow root) — same contract as `<lr-document-preview>`'s identically-named prop.
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring
+  `<lr-source-card>`'s `appearance` vocabulary. `'card'` (the default) keeps the bordered, filled
+  box. `'plain'` removes `[part="base"]`'s border, background, padding, and corner radius, so a
+  card inside a dense chat transcript (or any container already drawing its own separation between
+  attachments) doesn't double the frame.
 
 **Events:** `lr-open` (`detail: { src: string; filename: string }`, cancelable) — fired when the
 card (or, for `kind="video"`, its separate `open-button`) is activated. `detail.src` is whichever

package/llms/components/lr-memory-panel.md

@@ -54,7 +54,12 @@ somewhere to land after a confirmation resolves), `item-row`, `item-text`, `conf
 `provenance` is unset; `item-body` is `hidden` while collapsed), `item-actions`, `add-button`,
 `remove-button`, `forget-all-button`.
 
-**Themeable custom properties:** shared tokens only.
+**Themeable custom properties:** `--lr-memory-panel-confidence-success-color` (default
+`var(--lr-color-success)`), `--lr-memory-panel-confidence-warning-color` (default
+`var(--lr-color-warning)`), `--lr-memory-panel-confidence-danger-color` (default
+`var(--lr-color-danger)`) — text color of an item's `confidence` indicator, one per confidence
+tier (`high`/`medium`/`low` against `thresholds`, the same tiering `lr-chunk-inspector` uses for
+its score bar). Plus shared tokens otherwise.
 
 **Optional peer deps:** none.
 

package/llms/components/lr-mention-popover.md

@@ -66,12 +66,19 @@ renders `open="false"` on first paint)
 **CSS parts:** `listbox`, `option`, `option-icon` (when `icon` is set), `option-label`,
 `option-description` (when `description` is set), `empty`
 
-**Themeable custom properties:** shared tokens only — `--lr-space-xs`/`-s`/`-m` (popup padding,
+**Themeable custom properties:** `--lr-mention-popover-option-active-bg` (default
+`var(--lr-color-brand-quiet)`) — background of the hovered or `[data-active]`
+(keyboard-highlighted) suggestion row. Component-scoped indirection over the shared
+`--lr-color-brand-quiet` token, so a consumer can retheme just this highlighted/active row without
+repainting every other component that reuses the same shared token. Plus shared tokens —
+`--lr-space-xs`/`-s`/`-m` (popup padding,
 row padding/gap), `--lr-color-surface`/`-border` (popup background/border), `--lr-radius`
 (popup and row corners), `--lr-shadow` (popup elevation), `--lr-transition-fast` (open/close
-transition), `--lr-color-brand-quiet` (active-row background), `--lr-color-brand` (selected-row
+transition), `--lr-color-brand` (selected-row
 text), `--lr-color-text-quiet`/`--lr-color-text` (description text, full-contrast on the active
-row).
+row), and `--lr-popover-viewport-clamp` (default `92vw`) — the shared narrow-viewport ceiling the
+popup's max-inline-size is `min()`ed against, alongside its own `24rem` cap and the positioner's
+available space. See `lr-tour` for the shared-clamp note.
 
 **Optional peer deps:** none.
 

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

@@ -36,8 +36,25 @@ menu, an avatar menu, or a history row's overflow menu. Uses the WAI-ARIA "menu
   `this.getAttribute('aria-label') || <computed default>` precedence
 
 - `closeOnEscapeAnywhere: boolean = false` (attribute `close-on-escape-anywhere`) — lets Escape
-  close the menu when focus is on slotted non-menu-item content inside the popup; item activation
-  remains scoped to actual menu items
+  close the menu when focus is on non-menu-item content slotted into the **default** slot, i.e.
+  rendered inside `[part="list"]`; item activation remains scoped to actual menu items. It has no
+  bearing on the `header`/`footer` slots, which sit outside the `role="menu"` list and always close
+  on Escape — so a menu that keeps its composed controls there never needs this property
+
+**Methods:** `show(focus: 'first' | 'last' = 'first')` opens the menu and moves roving focus to the
+first (or, with `'last'`, the last) non-disabled item; a no-op when already open.
+`hide(options?: { focusTrigger?: boolean })` closes it; a no-op when already closed. They are the
+imperative pair for the cases the slotted trigger can't express — a "Done"/"Apply" button *inside*
+the menu, a keyboard shortcut, a parent restoring UI state — without hand-reproducing the
+pending-focus bookkeeping. Both are deliberately thin: positioning, the outside-click listener, the
+`lr-show`/`lr-hide` events, and the initial focus move all stay in one place, so **writing `open`
+directly is fully supported and equivalent apart from the focus moves**. In particular the
+roving-tabindex reset is centralized, so a bare `el.open = false` also clears `activeIndex` and
+never leaves a stale `tabindex="0"` tab stop on the last active item. `hide()` never refocuses
+unless you ask: pass `{ focusTrigger: true }` for a dismissal with nowhere else for focus to land,
+and leave it off when the interaction that closed the menu already put focus somewhere the user
+chose (an outside click, a Tab out). Focus restoration lives in `hide()` rather than in the
+close branch precisely so teardown — disconnecting an open menu — can't steal focus.
 
 **Events:** `lr-show` (no detail — fires only when `open` transitions to `true`, not for markup
 that renders `open` true from the start), `lr-hide` (same first-render guard, opposite
@@ -49,10 +66,25 @@ returning to the trigger)
 are assigned; enhanced imperatively with `aria-haspopup="menu"`/`aria-expanded`/`aria-controls`
 since those attributes belong on the actual interactive trigger, which lives outside this
 component's shadow root), default (`<lr-menu-item>` elements, plus optionally plain `<hr>`
-dividers between groups — native `<hr>` already carries an implicit `separator` role)
+dividers between groups — native `<hr>` already carries an implicit `separator` role),
+`header` and `footer` (composed, deliberately non-menu-item content — a filter/search field, a
+section title, an "Apply"/"Done" button, a count — rendered above/below the items inside
+`[part="popup"]` but **outside** the `role="menu"` list. Both collapse to no box at all while
+unfilled, so a menu that uses neither renders exactly as it did before they existed)
+
+Put composed controls in `header`/`footer` rather than the default slot. Non-item content in the
+default slot still works and is not deprecated at runtime (no warning is emitted), but it sits
+inside `role="menu"`, where ARIA permits only
+`menuitem`/`menuitemradio`/`menuitemcheckbox`/`group`/`separator` children — anything else is an
+`aria-required-children` violation. It is also not Tab-reachable from an item, and needs
+`closeOnEscapeAnywhere` before Escape will close the menu. The named regions have none of those
+problems.
 
 **CSS parts:** `trigger` (wrapper around the `trigger` slot — the positioning anchor), `popup` (the
-positioned floating panel), `list` (the `role="menu"` container wrapping the default slot)
+positioned floating panel), `header` (wrapper around the `header` slot, above the list and outside
+`role="menu"`; `display: none` while that slot is unfilled), `list` (the `role="menu"` container
+wrapping the default slot), `footer` (wrapper around the `footer` slot, below the list and outside
+`role="menu"`; `display: none` while that slot is unfilled)
 
 **Themeable custom properties:** shared tokens only (`--lr-color-surface`, `--lr-color-border`,
 `--lr-radius`, `--lr-shadow`, `--lr-space-xs`, `--lr-transition-fast`).
@@ -142,11 +174,19 @@ navigation with no separate JS bookkeeping. ArrowDown/ArrowUp *on the trigger wh
 opens the menu, focusing the first/last non-disabled item respectively (mirrors native `<select>`).
 Once open, ArrowDown/ArrowUp move the roving focus among non-disabled items and wrap past either end
 (unlike `<lr-select>`'s clamped listbox nav); Home/End jump to the first/last non-disabled item;
-Enter/Space activate the focused item; Escape closes and refocuses the trigger; Tab closes without
-`preventDefault()`, letting the browser's own Tab navigation proceed untouched. All of this list-level
-keydown handling — Escape, Tab, the arrow keys, Home/End, and type-ahead alike — only responds when
-the triggering keydown event's own target is an actual `<lr-menu-item>` element; a keydown bubbling
-up from any other node inside the popup is ignored rather than misread as list navigation. A printable
+Enter/Space activate the focused item; Escape closes and refocuses the trigger. The arrow keys,
+Home/End, Enter/Space and type-ahead only respond when the triggering keydown event's own target is
+an actual `<lr-menu-item>` element; a keydown bubbling up from any other node inside the popup is
+ignored rather than misread as list navigation. Escape and Tab are the two deliberate exceptions.
+Escape from `header`/`footer` content always closes the menu and refocuses the trigger (mirroring
+`lr-popover`'s handling of arbitrary popup content), while Escape from non-item content in the
+*default* slot closes it only with `closeOnEscapeAnywhere` set. Tab never traps focus and never
+calls `preventDefault()` — the browser's own Tab navigation always proceeds untouched — and closes
+the menu only when focus is on its way *out* of `[part="popup"]`: with a focusable in the
+`header`/`footer` region on the far side of the keypress the menu stays open so native Tab can carry
+focus there, and with neither region filled Tab closes exactly as it always has. Tabbing past the
+popup's last focusable in either direction closes the menu, including from slotted non-item content
+— which previously left the menu open while focus walked out of the popup entirely. A printable
 keypress runs type-ahead: roving focus jumps to the next non-disabled item whose text starts with the
 accumulated buffer (cycling from just after the active item, buffer resets ~500ms after the last
 keystroke) — mirrors `<lr-select>`'s identical listbox type-ahead. A click outside both the trigger
@@ -164,8 +204,20 @@ click itself already moved focus somewhere the user chose.
 - `lr-menu-item-select` carries no detail payload (`event.detail === null`); read
   `event.target.value` instead. `<lr-menu>`'s own re-fired `lr-menu-select` is the one that
   carries `detail: { value }`.
-- Tab closes the menu without `preventDefault()` or focus trapping — the browser's own default Tab
-  navigation proceeds untouched, only the (now-stale) open state is cleared.
+- Tab never calls `preventDefault()` and never traps focus — the browser's own default Tab
+  navigation always proceeds untouched. It closes the menu only when Tab would leave
+  `[part="popup"]` entirely; when the `header`/`footer` region holds a focusable on the far side of
+  the keypress, the menu stays open instead and native Tab moves focus into it. With neither region
+  filled, Tab closes exactly as before.
+- Non-item content in the *default* slot is not Tab-reachable from an item — Tab from an
+  `<lr-menu-item>` still closes the menu when there is no `header`/`footer` focusable to move to,
+  even if a `<button>` is slotted alongside the items. Move such controls to `header`/`footer`.
+- `header`/`footer` emptiness is tracked from each slot's own `slotchange` and reflected on the host
+  as `data-has-header` / `data-has-footer` (plus `data-list-empty`, which suppresses the region
+  divider next to an empty list). They are internal styling hooks, not public API — don't set them
+  by hand — but they are why `[part="header"]`/`[part="footer"]` collapse cleanly: a
+  `[part]:empty` rule can never match a part that contains a slot, since Chromium counts the
+  whitespace-only text nodes Lit leaves there.
 - Only Escape and a committed selection refocus the trigger on close; a click outside does not.
 
 ---