@aceshooting/lyra-ui 5.0.0 → 5.2.0

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

@@ -0,0 +1,103 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-known-date`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/known-date/known-date.js';` (registers the tag; side-effect import)
+- **Class** `LyraKnownDate`, also available unregistered from `@aceshooting/lyra-ui/components/utility/known-date/known-date.class.js`
+- **Family** `components/utility/` — 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-known-date`
+
+A form-associated control for a date the user already knows (a birthdate, a passport expiry),
+collected as three plain day/month/year number fields in the locale's natural order rather than a
+calendar popup. Uses the shared `FormAssociated` mixin; the submitted value is always canonical ISO
+8601 (`YYYY-MM-DD`), or `''` while any field is blank or the combination isn't a real calendar date.
+
+**Properties:**
+- `value: string` — canonical `YYYY-MM-DD` or `''`. Assignment goes through a strict-ISO gate:
+  a non-zero-padded (`"2007-3-27"`) or calendar-invalid (`"2007-02-30"`) literal sanitizes to `''`
+  and clears all three fields. Programmatic assignment never emits `input`/`change`
+- `valueAsDate: Date | null` — the same value as a local-midnight `Date`; settable (assigning
+  `null` clears)
+- `min: string = ''`, `max: string = ''` — inclusive `YYYY-MM-DD` bounds, surfaced as
+  `rangeUnderflow`/`rangeOverflow`
+- `readonly: boolean = false` (reflected) — also suspends all validity flags
+- `size: 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected)
+- `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute `error-text`)
+- `locale: string = ''` — BCP-47 override for field order and per-field label sampling only
+  (redeclared non-reflecting over the base `locale`, like `lr-date-input`)
+- `autocomplete: string = ''` — the special value `'bday'` expands to
+  `bday-day`/`bday-month`/`bday-year` across the three fields; any other non-empty value is
+  forwarded verbatim to all three
+- `dayLabel: string = 'Day'` (`day-label`), `monthLabel: string = 'Month'` (`month-label`),
+  `yearLabel: string = 'Year'` (`year-label`) — visible **and** accessible per-field labels; each
+  routes through `localize()` only while left at its literal default
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — applied to `[part="fieldset"]`,
+  which owns the group role, overriding the `<legend>`-derived name
+
+**Methods:** `focus(options?)` focuses the first field in locale order; `blur()` blurs whichever
+field currently has focus.
+
+**Events:** `input` (every keystroke), `change` (a field blur where the composite value newly
+transitioned), plus re-dispatched bubbling/composed `focus` and `blur` (`blur` fires once when focus
+leaves all three fields, not per field-to-field Tab). `input`/`change` detail is
+`{ value, day, month, year, field }` — `value` is the canonical ISO date or `''`, `day`/`month`/`year`
+are the live raw typed text, and `field` is `'day' | 'month' | 'year'`, whichever was last edited.
+
+**Slots:** `label`, `hint`, `error` (each rendered alongside its matching property).
+
+**CSS parts:** `form-control` (outer wrapper), `fieldset` (the `<fieldset>` grouping the fields —
+carries `aria-label` when `accessibleLabel` is set), `legend` (the `<legend>`; hidden when there is
+no label, and grows a `*` suffix while `required`), `fields` (the flex row), `field` (one field
+block, repeated three times, `data-field="day"|"month"|"year"`), `field-input` (the native
+`<input type="text" inputmode="numeric">` inside it, same `data-field` marker), `field-label` (the
+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`,
+`--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. `--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
+  `Intl.DateTimeFormat` and reading back the part order — not from `Date.parse()`'s mm/dd/yyyy bias.
+  It falls back to `month, day, year` only when that sampling fails.
+- Auto-advance (typing a field's last digit moves to the next) and backspace-into-the-previous-field
+  are this library's own additions, not Web Awesome parity. Auto-advance is purely digit-count
+  based, never value based.
+- Each `<input>` shows exactly what was typed and is never reformatted or reverted; only the
+  composite `value` is zero-padded.
+- Non-digit keystrokes are rejected before reaching field state — locale-specific numerals
+  (e.g. Arabic-Indic digits) are not accepted as input.
+- ArrowLeft/ArrowRight cross fields at a field's text boundary, and the *physical* key meaning
+  "next field" flips under an inherited `dir="rtl"`; the locale-derived field order itself does not.
+- A blank composite is `valueMissing` only when **all three** fields are blank; a partially typed
+  required date reports `badInput` instead.
+- The host carries a `:state(blank)` custom state whenever `value === ''`, and `data-invalid` only
+  once touched (first blur out of the whole control) and actually invalid.

package/llms/components/lr-lightbox.md

@@ -0,0 +1,79 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-lightbox`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/lightbox/lightbox.js';` (registers the tag; side-effect import)
+- **Class** `LyraLightbox`, also available unregistered from `@aceshooting/lyra-ui/components/media/lightbox/lightbox.class.js`
+- **Family** `components/media/` — 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-lightbox`
+
+A modal, full-screen image viewer with prev/next navigation, captions, and pan/zoom delegated to one
+stable embedded `<lr-zoomable-frame>`. It renders its own dialog panel (not a nested `<lr-dialog>`)
+but shares the same overlay infrastructure as `<lr-dialog>`/`<lr-command-palette>` — stacking, focus
+trap, Escape/backdrop dismissal, scroll lock, and focus return.
+
+**Properties:**
+- `open: boolean = false` (reflected) — set this or call `close()`; there is no `show()`/`hide()`.
+- `images: LyraLightboxImage[] = []` (attribute: false) — `LyraLightboxImage { src: string; alt?:
+  string; caption?: string }`. `src` is passed to the embedded frame, which runs it through
+  `safeMediaSrc()`. `alt`/`caption` are caller data, never localized.
+- `index: number = 0` (reflected) — clamped defensively for rendering and silently re-synced (no
+  event) when `images` shrinks.
+- `loop: boolean = false` (reflected) — wraps prev/next past the ends.
+- `noLightDismiss: boolean = false` (attribute `no-light-dismiss`) — opts out of backdrop dismissal.
+- `showCounter: boolean = true` (attribute `show-counter`) — shows `[part="counter"]` and its
+  live-region announcement.
+- `minZoom: number = 0.5`, `maxZoom: number = 4`, `zoomStep: number = 0.25` (attributes `min-zoom`/
+  `max-zoom`/`zoom-step`) — pure pass-throughs to the embedded `<lr-zoomable-frame>`, which does the
+  normalizing.
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — the panel's accessible name,
+  overriding the localized `lightboxLabel`.
+
+**Methods:** `next()`, `previous()`, `goTo(index)`, `close(reason?)` — `reason` defaults to `'api'`
+and is forwarded as the close event's detail.
+
+**Events:** `lr-lightbox-close` (`detail: LyraLightboxCloseReason = 'escape' | 'backdrop' |
+'close-button' | 'api' | 'unmount' | (string & {})`; **cancelable** — `preventDefault()` blocks
+closing on every path, including a consumer's own `close()` call. Also fires with `'unmount'` when
+the element is removed from the DOM while still open); `lr-index-change` (`detail: { index }`, fired
+only for internally-driven navigation — a button, a keyboard shortcut, or `next()`/`previous()`/
+`goTo()`; **not** when a consumer sets `index`/`images` directly); `lr-zoom-change` (`detail: {
+zoom }`) is not emitted by the lightbox itself — it bubbles up composed from the embedded frame.
+
+**Slots:** `actions` — extra toolbar buttons (download/share/delete), rendered in `[part="toolbar"]`
+between the counter and the close button.
+
+**CSS parts:** `backdrop`, `panel` (`role="dialog"` + `aria-modal="true"` while open; fills the
+padded safe area rather than shrink-wrapping), `toolbar`, `counter` (visible localized "Image N of
+Total"), `live-region` (visually-hidden `role="status"` that announces position on *every* `index`
+change, including consumer-driven ones), `actions` (wrapper, `hidden` when nothing is slotted),
+`close-button` (always rendered — unlike `<lr-dialog>`'s opt-in `closable`), `stage`, `frame` (the
+embedded `<lr-zoomable-frame>`; its internal parts are not re-exported), `previous-button`,
+`previous-glyph`, `next-button`, `next-glyph`, `caption` (only when the current image has one; its
+`id` is the panel's `aria-describedby` target).
+
+**Themeable custom properties:** `--lr-lightbox-overlay-color` (default
+`var(--lr-color-overlay-strong)` — the backdrop scrim), `--lr-lightbox-control-bg` (default
+`var(--lr-color-neutral)`) and `--lr-lightbox-control-color` (default `var(--lr-color-on-neutral)`)
+— background/foreground for the counter, caption, and every floating/toolbar icon button; these use
+the solid neutral token rather than `--lr-color-surface` because the controls float over arbitrary
+photo content.
+
+**Optional peer deps:** none.
+
+**Known gotchas:**
+- keyboard navigation is RTL-aware and bound on `[part="panel"]`, so it also sees keydowns bubbling
+  out of the embedded frame's shadow tree: Arrow forward/back (mirrored under `rtl`), `Home`, `End`.
+  It never collides with the frame's own `+`/`-`/`0` zoom shortcuts.
+- initial focus deliberately goes to `close-button`, not the first tabbable element — a slotted
+  `actions` button placed before it does not steal focus.
+- zoom/pan reset on navigation is imperative (`resetView()` from `updated()`), not a binding; the
+  frame element is reused across navigations rather than recreated, so a keyboard user who tabbed
+  into the viewport keeps focus.
+- scope for v1: no per-image slotted content (data-driven via `images` only), no dot indicators, no
+  open/close transition, no click-image-to-navigate, no touch-swipe.

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

@@ -0,0 +1,72 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-line-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/line-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraLineChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/line-chart.class.js`
+- **Family** `components/charts/` — see `llms/index.md` for its siblings
+- **Optional peers** `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Documented with** `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## Typed subclasses: `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart`
+
+Each is `LyraChart` with `type` locked to a fixed value — respectively `line`, `bar`, `pie`,
+`doughnut`, `radar`, `polarArea`, `bubble`, `scatter` — via a real `get`/`set` accessor pair the
+shared `lockChartType()` helper installs on the subclass's own prototype (`declare type: '…'`
+narrows the TS type at compile time; the runtime lock is the `Object.defineProperty` pair alongside
+it — the same helper `lr-histogram` uses), not merely a class-field default a later assignment
+could still override.
+
+Everything else is inherited verbatim from `lr-chart`; each name below has the same type, default,
+and behavior there. **See `llms/components/lr-chart.md` for the details, code example, and gotchas
+of every entry in these lists.**
+
+**Properties:** `labels`, `datasets`, `legend`, `legendPosition` (attribute `legend-position`),
+`valueFormatter`, `area`, `zoom`, `height`, `xLabel` (`x-label`), `yLabel` (`y-label`), `y2Label`
+(`y2-label`), `beginAtZero` (`begin-at-zero`), `horizontal`, `stacked`, `config`, `accessibleLabel`
+(`accessible-label`), `accessibleDescription` (`accessible-description`), `showDataTable`
+(`show-data-table`), `chartArea` (readonly). `type` is the only member that differs: read-only,
+locked to this tag's value.
+
+**Methods:** `resetZoom()`, `refreshTheme()`.
+
+**Events:** `lr-zoom` (`detail: { zoomed: boolean }`), `lr-point-click` (`detail: { datasetIndex,
+index, label, value }`).
+
+**Slots:** `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`,
+`--lr-chart-tooltip-text`.
+
+**Optional peer deps:** same as `lr-chart` — `chart.js`, plus `chartjs-plugin-zoom` only once
+`zoom` is set.
+
+```html
+<lr-bar-chart legend></lr-bar-chart>
+<lr-pie-chart></lr-pie-chart>
+<script>
+  document.querySelector('lr-bar-chart').labels = ['A', 'B'];
+  document.querySelector('lr-bar-chart').datasets = [{ label: 'Count', data: [4, 9] }];
+
+  document.querySelector('lr-pie-chart').labels = ['A', 'B', 'C'];
+  document.querySelector('lr-pie-chart').datasets = [{ label: 'Share', data: [30, 45, 25], color: ['#2563eb', '#16a34a', '#dc2626'] }];
+</script>
+```
+
+**Known gotchas (in addition to the core `lr-chart` list in `llms/components/lr-chart.md`):**
+- `type` truly is locked per subclass: `<lr-pie-chart type="bar">` or `el.type = 'bar'` at runtime
+  is a genuine no-op (the accessor's setter silently ignores the write), not a footgun like a plain
+  overridden class-field default would be.
+- `lr-bubble-chart` needs `Series.points` entries with an `x`/`y`/`r` triple, but `Series.points`
+  is typed as `{x, y, label?}[]` with no `r` field — cast the array through `as unknown as
+  Series['points']` (or a local `BubblePoint` type) when constructing bubble data.
+
+---

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

@@ -0,0 +1,143 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-lite-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/lite-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraLiteChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/lite-chart.class.js`
+- **Family** `components/charts/` — 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-lite-chart`
+
+A dependency-free bar/line chart — plain SVG/DOM rendering, zero peer dependencies (unlike
+`lr-chart`, which wraps `chart.js`). For a project whose architecture forbids a charting
+dependency outright: covers grouped/stacked bars, multi-series lines, per-point click, and hover
+tooltips (native SVG `<title>`, no positioning JS) — not a full `lr-chart` replacement (no
+zoom/pan, no pie/doughnut/radar/scatter/bubble types, no horizontal/dual-y-axis, no raw-config
+passthrough). Not a subclass of `LyraChart`.
+
+**Properties:**
+- `type: LyraLiteChartType = 'bar'` — `'bar' | 'line'`
+- `labels: string[] = []` (attribute: false)
+- `datasets: LiteSeries[] = []` (attribute: false) — `LiteSeries { label: string; data:
+  (number|null)[]; color?: string }`
+- `legend: boolean = false`
+- `height: string = '280px'`
+- `xLabel: string = ''` (attribute `x-label`)
+- `yLabel: string = ''` (attribute `y-label`)
+- `beginAtZero: boolean = true` (attribute `begin-at-zero`)
+- `stacked: boolean = false` — sums each category's bars into one segmented bar instead of grouping
+  them side by side; ignored for `type="line"`
+- `tickFormat?: (value: number) => string` (attribute: false) — formats a y-axis tick value for
+  display (e.g. `(v) => \`$${v.toFixed(2)}\`` for currency, or a duration formatter for `"42s"`).
+  Falls back to the built-in "nice numbers" formatter when unset.
+- `layout: 'fit' | 'scroll' = 'fit'` (reflected) — `'fit'` (default) is the original squeeze-the-
+  whole-plot-to-host-width behavior, unchanged. `'scroll'` gives bars a fixed `barWidth` instead: plot
+  content width becomes `categoryCount * barWidth` (can exceed the host's measured width), and
+  `[part='base']` becomes horizontally `overflow-x: auto` so the user scrolls to see every bar at a
+  legible fixed width instead of them compressing as category count grows. Bar type only.
+- `barWidth: number = 32` (attribute `bar-width`, px) — each bar's fixed width in `layout="scroll"`
+  mode; ignored in the default `'fit'` mode.
+- `maxLabels?: number` (attribute `max-labels`, type Number) — decimates which category axis labels
+  actually render *text* when `labels.length > maxLabels` (bars themselves are never decimated, only
+  their axis `<text>` labels): always shows the first and last label, and roughly evenly distributes
+  the rest between them. Works in either `layout` mode. Unset (the default) renders every label,
+  unchanged.
+- `barX?: (index: number) => number` (attribute: false, bar type only) — overrides the internal
+  per-category x-origin formula (`plotX + i * slot`) used by both bars and their axis labels, so a
+  consumer can pixel-align this chart's bars with a sibling `<lr-heatmap>` calendar's week columns
+  (see that component's own `columnX`) by supplying the same coordinate function to both. Unset (the
+  default) is the original formula, unchanged.
+- `pointText?: (label: string, value: number, datasetIndex: number) => string` (attribute: false) —
+  overrides the per-bar/per-point `<title>`/`aria-label` tooltip text (mirrors `lr-heatmap`'s
+  `cellText`). Falls back to the built-in raw-value template when unset.
+- `legendText?: (label: string, datasetIndex: number) => string` (attribute: false) — appends
+  formatter-supplied text (e.g. a value or percentage share) after each series' label in the
+  built-in legend row, mirroring `pointText`/`tickFormat`'s opt-in-hook convention. Falls back to
+  the label alone when unset; no-op while `legend` is `false`.
+- `roundedBars: boolean = false` (attribute `rounded-bars`, bar type only) — draws each bar as a
+  rounded-top-corner shape instead of a square-cornered `<rect>`.
+- `skipZero: boolean = false` (attribute `skip-zero`, bar type only) — omits a bar entirely (no
+  mark/tabindex/tooltip) for a value that is exactly `0`; `null`/non-finite values are always
+  skipped regardless.
+- `padLeft?: number` (attribute `pad-left`) — overrides the internal 36px `PAD_LEFT` plot-left-
+  padding constant. Unset keeps the fixed 36px.
+- `barGapRatio?: number` (attribute `bar-gap-ratio`) — overrides the internal 0.2 `BAR_GROUP_GAP`
+  fraction of a category slot left as a gap between categories. Unset keeps the fixed 0.2.
+- `scale: 'linear' | 'sqrt' = 'linear'` (bar type only) — `'sqrt'` maps a bar's value to height via
+  `Math.sqrt(value / domainMax)` instead of the standard linear `niceDomain` fraction (mirroring
+  `lr-heatmap`'s matrix-mode `sqrt` scale), so a skewed dataset's smaller bars aren't washed out
+  by one dominant value; gridlines/tick labels stay on the linear domain either way, and `type="line"`
+  ignores it entirely.
+- `hideAxis: boolean = false` (attribute `hide-axis`) — suppresses gridlines/y-axis tick labels
+  altogether; x-axis category labels (rendered separately) are unaffected.
+- `selectedIndex: number[] = []` (attribute: false) — category indexes to mark `data-selected` on
+  every bar/segment at that index, across every dataset — e.g. to highlight a whole selected week's
+  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:** `lr-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 `lr-chart`'s `lr-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:** `render()` recomputes the grid/marks on every update rather than memoizing against a
+content signature — `datasets`/`labels` can hold callbacks (`tickFormat`, `barX`) or arbitrary,
+possibly circular or BigInt-bearing application data that a fingerprint can't serialize safely, so a
+fresh, small SVG render is cheaper and more correct than a lossy cache.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `grid-line`, `axis-label`, `axis-title`, `bar` (each bar rect; carries
+`data-selected` when its category index is in `selectedIndex`), `line`, `point`, `legend`,
+`legend-item`, `legend-swatch`, `legend-text` (extra per-item text after the series label,
+rendered only when `legendText` is set), `live-region` (the current mark announcement for keyboard
+users), `data-list` (a visually hidden list of all plotted data points).
+
+**Themeable custom properties:** `--lr-chart-height` (same host-level property as `lr-chart`);
+`--lr-chart-grid-color`, `--lr-chart-tick-color`, `--lr-chart-legend-color` — same token
+*names* as `lr-chart`, so a host already theming `lr-chart` themes this for free;
+`--lr-lite-chart-selected-outline-color` (default `var(--lr-color-brand)`) — the stroke drawn on
+`[part='bar'][data-selected]`, i.e. bars whose category index is in `selectedIndex` (bars only;
+`[part='point']` is never marked `data-selected`, and the stroke width is a fixed 2px). Unlike
+`lr-chart` (canvas-rendered, needs `getComputedStyle`-based re-theming on every draw), this is
+plain SVG/DOM and reads these via native CSS `var()` — no JS-side resolution step, and no
+`refreshTheme()` method needed (there's nothing to go stale).
+
+**Optional peer deps:** none. This is the point of the component.
+
+```html
+<lr-lite-chart type="bar" stacked legend x-label="Week" y-label="Commits"></lr-lite-chart>
+<script>
+  const c = document.querySelector('lr-lite-chart');
+  c.labels = ['W1', 'W2', 'W3', 'W4'];
+  c.datasets = [
+    { label: 'Docs', data: [4, 6, 3, 8] },
+    { label: 'Bugs', data: [3, 2, 5, 4] },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- No `horizontal` mode (unlike `lr-chart`) — deliberately cut from scope, not a stub: bars are
+  always vertical.
+- No dual y-axis (`Series.axis: 'y2'`) — every series shares one y-axis/domain.
+- Series colors default to a fixed built-in 8-color categorical palette (round-robin by dataset
+  index) when `color` is unset — not configurable beyond passing `color` per series.
+- Bar/point elements are real focusable DOM nodes (`tabindex="0" role="button"`, each with its own
+  `aria-label`), so the `<svg>` itself uses `role="group"`, not `role="img"` — an "img" role would
+  conflict with genuinely interactive descendants (axe's `nested-interactive` rule).
+- Tick values use a standard "nice numbers" (1/2/5 × 10ⁿ) rounding step, not exact data min/max —
+  intentional (readable axis labels), matches how most charting libraries pick tick steps.
+
+---

package/llms/components/lr-live-region.md

@@ -0,0 +1,105 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-live-region`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/live-region/live-region.js';` (registers the tag; side-effect import)
+- **Class** `LyraLiveRegion`, also available unregistered from `@aceshooting/lyra-ui/components/utility/live-region/live-region.class.js`
+- **Family** `components/utility/` — 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-live-region` (+ internal `Announcer`)
+
+A throttled screen-reader announcement helper, split into a DOM-free coalescing engine
+(`internal/announcer.ts`'s `Announcer` class) and a real custom element that wraps it.
+
+### Internal: `Announcer` (`internal/announcer.ts`)
+
+Not a custom element — pure timing/coalescing logic with no DOM dependency, composed by
+`<lr-live-region>` (below) and intended for reuse by any other component that needs throttled
+announcements (a stream-status indicator, a tool-call chip's status transitions, a chat message's
+streaming state).
+
+Streaming UIs (token-by-token chat responses, progress ticks, etc.) naturally produce far more
+candidate announcements than a screen-reader user can usefully absorb — reading every incremental
+chunk aloud is spam, not information. `Announcer` collapses a burst of `announce()` calls arriving
+within `throttleMs` of the *first* call in that burst down to a single trailing-edge flush of the
+latest text: superseded intermediate text is dropped outright, never queued or concatenated.
+
+- `new Announcer(options: AnnouncerOptions)` where
+  `AnnouncerOptions = { throttleMs?: number /* = 500 */; onFlush: (text: string) => void }`.
+- `announce(text: string, options?: AnnounceOptions)` where `AnnounceOptions = { force?: boolean }` —
+  queues `text`, overwriting whatever an earlier call in the same burst queued. Only the *first*
+  call of a burst schedules the flush timer, so the deadline stays anchored to that first call
+  rather than being pushed back by every subsequent call. `{ force: true }` bypasses any
+  in-progress window and flushes immediately, so a terminal message (e.g. "response complete") is
+  never swallowed mid-burst.
+- `cancel()` — drops any pending (not yet flushed) text without invoking `onFlush`.
+- `pendingText: string | undefined` — the latest text awaiting flush, if a burst is in progress.
+- `isPending: boolean` — whether a flush is currently scheduled.
+- `throttleMs` — a plain public field, safe to change between bursts; a flush already scheduled
+  keeps the deadline it was scheduled with.
+
+### `lr-live-region`
+
+A visually-hidden ARIA live region that throttles and coalesces announcements instead of relaying
+every call verbatim, by composing an internal `Announcer`. A consumer typically mounts one
+`<lr-live-region>` per page/surface (much like `<lr-toast>` is one region per placement) and
+keeps a reference to call `announce()` from application code or a parent component.
+
+**Properties:**
+- `mode: 'polite' | 'assertive' = 'polite'` (reflected) — `'polite'` renders `role="status"` +
+  `aria-live="polite"` (waits for the user to be idle); `'assertive'` renders `role="alert"` +
+  `aria-live="assertive"` (interrupts)
+- `throttleMs: number = 500` (attribute `throttle-ms`) — the coalescing window; see `Announcer`
+  above
+
+**Methods:** `announce(text: string, options?: AnnounceOptions): void` — queues `text` for
+announcement through the internal `Announcer`; `{ force: true }` bypasses the current throttle
+window and flushes immediately.
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `region` — the visually-hidden element carrying `role`/`aria-live`/`aria-atomic="true"`.
+
+**Themeable custom properties:** none component-specific — the region is hidden via the shared
+`.sr-only` helper class (`internal/a11y.ts`), not tokenized CSS.
+
+**Optional peer deps:** none.
+
+```html
+<!-- once, near the root of a page/surface -->
+<lr-live-region id="live" mode="polite"></lr-live-region>
+<script type="module">
+  const live = document.getElementById('live');
+  // streaming tokens: fine to call on every chunk, only the trailing state lands
+  live.announce(`${partialText} …`);
+  // stream finished: always announced, even mid-throttle-window
+  live.announce('Response complete', { force: true });
+</script>
+```
+
+A parent Lit component would instead hold the reference via `@query('lr-live-region')`.
+
+**Known gotchas:**
+- Re-announcing text identical to what was last written is special-cased: screen readers announce a
+  live region only on text-content *change*, so the component clears `textContent` first and
+  re-sets it on the next animation frame (not the same tick, which can coalesce into nothing ever
+  appearing to change) to give assistive tech a real empty-to-populated transition to observe. The
+  frame is scheduled and canceled through the region's own document window, including after the
+  element is adopted into an iframe.
+- The region's DOM is tracked outside Lit's own template bindings (`write()` mutates
+  `regionEl.textContent` directly) — an `announce()`/flush landing before `firstUpdated()` has run
+  (e.g. a consumer creates, appends, and calls `announce()` synchronously) is buffered and applied
+  on the next `firstUpdated()` rather than dropped.
+- `disconnectedCallback()` cancels any pending (unflushed) announcement, any before-first-render
+  buffered write, and any in-flight re-announce animation-frame callback — an element removed before
+  a deferred write lands silently drops it, including across a later reconnect.
+- Changing `throttle-ms` updates the live `Announcer`'s window immediately, but a flush already
+  scheduled under the old window keeps the deadline it was scheduled with.
+
+---

package/llms/components/lr-map.md

@@ -0,0 +1,129 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-map`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/map/map.js';` (registers the tag; side-effect import)
+- **Class** `LyraMap`, also available unregistered from `@aceshooting/lyra-ui/components/media/map/map.class.js`
+- **Family** `components/media/` — see `llms/index.md` for its siblings
+- **Optional peers** `maplibre-gl` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-map`
+
+A `maplibre-gl` wrapper with a declarative legend, a single choropleth GeoJSON fill layer, markers,
+and additive plain-GeoJSON `dataLayers`, plus a raw `map` escape hatch for anything unexposed.
+
+**Properties:**
+- `center: [number, number] = [0, 0]`
+- `zoom: number = 2`
+- `mapStyle: StyleSpecification | string = DEFAULT_STYLE` (attribute: false) — the default is a
+  basic OSM raster tile style pointing at **OpenStreetMap's shared demo tile server**. Fine for
+  local development, but its usage policy forbids bulk/production traffic, requires an identifying
+  User-Agent, and rate-limits or IP-blocks non-compliant clients
+  (https://operations.osmfoundation.org/policies/tiles/). **Production apps must pass their own
+  `mapStyle`** — a hosted vector/raster style from a tile provider you have a plan with.
+- `legend: LegendEntry[] = []` (attribute: false) — `LegendEntry { color: string; label: string }`
+  (discrete swatch rows only, no continuous gradient bar)
+- `choropleth?: ChoroplethLayer` (attribute: false) — `ChoroplethLayer { sourceId: string; geojson:
+  GeoJSON.FeatureCollection; field: string; stops: [number, string][] }` (interpolated
+  fill-color expression from `field`'s value against `stops`; `stops` must contain at least one
+  `[value, color]` pair — an empty array is ignored, leaving whatever fill layer already exists, if
+  any, untouched, rather than being applied)
+- `markers: MapMarker[] = []` (attribute: false) — `MapMarker { id?: string; lngLat: [number,
+  number]; color?: string; label?: string; unsafeHtml?: string }`; reconciled by `id` (falling back
+  to a `lng,lat` key, disambiguated by occurrence order for duplicate-coordinate id-less markers,
+  when `id` is omitted) so an unchanged marker isn't torn down and recreated on every `markers`
+  reassignment — its `lngLat` **and** its popup content (`unsafeHtml`/`label`, in that precedence)
+  are both updated in place, and the popup is removed if a later update sets neither. `unsafeHtml` is
+  rendered via `Popup.setHTML()` — **raw markup, inline event handlers included** — only pass trusted
+  content, sanitize anything derived from user input first; prefer `label` (`Popup.setText()`,
+  escaped) when the content is plain text. A marker whose `color` changes for a persisting `id`
+  can't be recolored in place (no `Marker.setColor()`) and is torn down/reconstructed instead — see
+  gotchas.
+- `dataLayers: GeoJsonDataLayer[] = []` (attribute: false) — `GeoJsonDataLayer { sourceId: string;
+  geojson: GeoJSON.Feature | GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
+  'danger' | 'neutral' }`. Each entry adds one GeoJSON source plus three layers
+  (`${sourceId}-fill`/`${sourceId}-line`/`${sourceId}-circle`, filtered by geometry type so a mixed
+  `FeatureCollection` renders correctly across all three), colored from the matching `--lr-color-*`
+  token (`tone` defaults to `'accent'` → `--lr-color-brand`). Independent of `choropleth` — no
+  `field`/`stops` color-interpolation, just the geometry rendered in a flat tone; use `choropleth`
+  instead when you need a data-driven color ramp. Reconciled by `sourceId` the same way `choropleth`
+  is: an entry whose `sourceId` persists across a `dataLayers` reassignment gets its GeoJSON updated
+  in place (`setData()`), one that's dropped has its source/layers removed, and a genuinely new
+  `sourceId` gets a new source/layers — nothing leaks on removal, style change, or disconnect.
+- `label: string = ''` — accessible name for the map region, applied as `[part="base"]`'s
+  `aria-label`. A plain `aria-label` attribute on the host itself is honored as a fallback when
+  `label` is left unset, matching `lr-slider`/`lr-checkbox`/`lr-switch`; with neither set, it
+  falls back to the localized `'map'` message.
+
+**Getters:** `map` → the raw `maplibregl.Map` instance.
+
+**Events:** `lr-map-load` (fired once, after the underlying map's own `'load'`), `lr-map-click`
+(`detail: { lngLat: [lng, lat], feature? }` — feature only populated if a choropleth fill layer
+exists and was hit)
+
+**Slots:** none.
+
+**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`.
+
+**Optional peer deps:** `maplibre-gl` (lazy-loaded; consumer must **separately** `import
+'maplibre-gl/dist/maplibre-gl.css'` once — the component does not do this for you).
+
+```html
+<lr-map center="[2.35, 48.85]" zoom="10"></lr-map>
+<script>
+  import 'maplibre-gl/dist/maplibre-gl.css';
+  const m = document.querySelector('lr-map');
+  m.choropleth = {
+    sourceId: 'regions',
+    geojson: myGeoJson,
+    field: 'value',
+    stops: [[0, '#cde2fb'], [100, '#0969da']],
+  };
+  m.legend = [{ color: '#cde2fb', label: 'Low' }, { color: '#0969da', label: 'High' }];
+  m.markers = [{ lngLat: [2.29, 48.86], label: 'Eiffel Tower' }];
+  m.addEventListener('lr-map-click', (e) => console.log(e.detail.feature?.properties));
+</script>
+```
+
+**Known gotchas:**
+- clearing or swapping the choropleth no longer leaks the old layer: setting `choropleth =
+  undefined`, or changing `choropleth.sourceId` to a different value, now calls `removeLayer`/
+  `removeSource` on whatever was previously applied before adding the new one (or nothing, if
+  cleared).
+- `mapStyle` changes after construction now call `setStyle()` (in addition to `center`/`zoom`
+  already calling `setCenter`/`setZoom`) — the choropleth and `dataLayers` are both automatically
+  re-applied once the new style's own `'style.load'` fires, since a style change wipes every
+  layer/source maplibre-gl knows about.
+- Point markers now have a declarative API (`markers`, above) with popup support — the `.map` escape
+  hatch and manual `new maplibregl.Marker()` are no longer the only way to place pins.
+- a marker whose `color` changes for a persisting `id` is torn down and reconstructed (maplibre-gl's
+  `Marker` has no `setColor()`) rather than mutated in place — this also closes any popup the user
+  currently has open on that marker (a fresh, closed `Popup` is built for the new instance); an
+  accepted side effect of the reconstruction fallback, not a bug.
+- No click-select visual highlight on choropleth features (no `setFeatureState` call) — clicking
+  only fires the event, no built-in visual feedback. Popups are still only reachable declaratively
+  through `markers`' `unsafeHtml`/`label` — a choropleth-feature click still has no built-in popup,
+  only the raw `lr-map-click` event.
+- `LegendEntry.color` is validated against a strict CSS-color-syntax allowlist before being applied
+  to the legend swatch's `background`, rejecting anything that isn't recognizable color syntax
+  (notably `url(...)`, which `background` also accepts and would otherwise fetch as soon as the
+  swatch renders).
+- while the `maplibre-gl` peer is resolving, the host shows a `<lr-skeleton variant="rect">` with
+  `aria-busy="true"` in place of the map container.
+- construction of the real `maplibregl.Map` (and its WebGL context) is additionally gated on this
+  element being observed intersecting the viewport (`IntersectionObserver`), independent of whether
+  the `maplibre-gl` peer has already loaded — an off-screen `<lr-map>` swaps its skeleton for the
+  empty `[part="container"]` div as soon as the peer resolves, but `map` stays `undefined` and
+  `lr-map-load` never fires until the element is actually scrolled into view. Deliberate: caps
+  concurrent WebGL contexts when many `<lr-map>`s sit in one dashboard/grid. Skipped entirely
+  (constructs immediately once the peer loads) when `IntersectionObserver` itself is unavailable.
+
+---