@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-heatmap.md

@@ -0,0 +1,258 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-heatmap`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/heatmap/heatmap.js';` (registers the tag; side-effect import)
+- **Class** `LyraHeatmap`, also available unregistered from `@aceshooting/lyra-ui/components/data/heatmap/heatmap.class.js`
+- **Family** `components/data/` — 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-heatmap`
+
+A Canvas-rendered heatmap with a DPR-aware, resize-aware redraw loop, in one of two `mode`s:
+`"matrix"` (default — a `rowLabels` × `colLabels` grid of `values`) or `"calendar"` (a
+GitHub-style Sunday–Saturday × week grid built from `days`, colored by quartile bucket rather than
+the matrix mode's continuous ramp). Every cell is independently addressable despite being
+canvas-drawn (no per-cell DOM node by default): a `pointermove` hit-test over the canvas shows `[part="tooltip"]`
+with that cell's label + value; the canvas is `tabindex="0"` with arrow-key roving focus (a stroked
+ring redrawn over the focused cell on every draw, plus `[part="live-region"]` announcing it); and a
+  click, or Enter/Space on the focused cell, fires `lr-cell-click`.
+
+Set `accessibleCells: true` (`accessible-cells`) to opt into a native-button overlay for each
+interactive matrix/calendar cell. The overlay uses localized `aria-label`s, explicit
+`aria-pressed="true"|"false"` from the controlled `selectedCell`, and roving tabindex/arrow-key
+focus; it continues to emit `lr-cell-click` and leaves selection state consumer-controlled.
+
+**Properties:**
+- `rowLabels: string[] = []` (attribute: false — matrix mode only)
+- `colLabels: string[] = []` (attribute: false — matrix mode only)
+- `values: number[][] = []` (attribute: false — matrix mode only) — `-1` or any non-finite value is
+  the "no data" sentinel; ragged/sparse rows are safe (`?? -1`)
+- `cellSize: number = 22` (attribute `cell-size` — default `22` in matrix mode, `11` in calendar
+  mode when left unset; explicitly setting it now governs both modes' per-cell size alike, and it's
+  ignored in either mode when `fitToWidth` is set)
+- `fitToWidth: boolean = false` (attribute `fit-to-width` — derives `cellSize` from the host's
+  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'`
+  still buckets by quartile (`quartileBucket()`, unchanged), while `'sqrt'` instead compresses via the
+  same `sqrtStep()` magnitude compression as matrix mode, so one heavy day doesn't wash out the rest
+- `mode: 'matrix' | 'calendar' = 'matrix'`
+- `days: CalendarDay[] = []` (attribute: false — calendar mode only) — `CalendarDay { date:
+  string /* ISO yyyy-mm-dd */; value: number }`; need not be sorted or contiguous, and an entry whose
+  `date` doesn't parse is dropped rather than poisoning the whole grid
+- `firstDayOfWeek: number = 0` (attribute `first-day-of-week` — calendar mode only, no-op in matrix
+  mode) — anchors the calendar grid at a different weekday instead of always Sunday; `0`-`6`, same
+  numbering as `CalendarCellPos.weekday` (`0` Sunday .. `6` Saturday)
+- `bucketCount: number = 5` (attribute `bucket-count` — calendar mode only; non-finite values fall
+  back to 5, while finite values are floored and clamped to 2–256 before the color-ramp allocation)
+- `annotations: HeatmapAnnotation[] = []` (attribute: false) — `HeatmapAnnotation { row?: number;
+  col?: number; date?: string; label?: string }`: matrix mode matches by `row`/`col`, calendar mode
+  by `date` (whichever pair matches the active `mode`; the other fields are ignored). Draws a
+  stroked ring over the matching cell; an annotation with a `label` also gets its own
+  `[part="legend-annotation"]` entry in the legend.
+- `selectedCell: HeatmapSelectedCell | null = null` (attribute: false) — `HeatmapSelectedCell {
+  row?: number; col?: number; date?: string }`, matched the same way as `annotations`. Draws a
+  persistent ring (independent of keyboard focus) over the matching cell, appends a "Selected: ..."
+  description to the host's own `aria-label`, and appends a "(selected)" suffix to the live-region
+  announcement when the focused cell is the selection. Purely a controlled property — mirrors
+  `<lr-lite-chart>`'s `selectedIndex`, this component never mutates it itself. Unset (the default,
+  `null`) reproduces today's exact output.
+- `accessibleCells: boolean = false` (attribute `accessible-cells`) — renders `[part="cells"]` with
+  one `[part="cell"]` native button per interactive cell. Buttons expose localized `aria-label`s,
+  explicit `aria-pressed` state from `selectedCell`, and a roving tabindex; the canvas becomes
+  `aria-hidden` while this mode is enabled. The property is opt-in so the default canvas mode keeps
+  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 (`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.
+- `cellInteractive?: (pos: MatrixCellPos | CalendarCellPos, value: number) => boolean` (attribute:
+  false) — opts individual cells out of the interaction model; receives the cell position and its
+  value, return `false` to make that cell present-but-non-interactive (no hover tooltip, click, or
+  keyboard roving-focus stop) without losing the layout/color-ramp machinery. Unset (the default)
+  keeps every cell interactive, unchanged.
+- `columnX?: (index: number) => number` (attribute: false, calendar mode only) — overrides the
+  internal week-column x-coordinate formula (`CAL_PAD_LEFT + week * (CAL_CELL + CAL_GAP)`) used
+  consistently across drawing, hit-testing, the focus ring, and month-label positioning, so a
+  consumer can pixel-align this calendar's week columns with a sibling `<lr-lite-chart>`'s bars
+  (see that component's own `barX`) by supplying the same coordinate function to both. Unset (the
+  default) is the original formula, unchanged.
+- `rowY?: (weekday: number) => number` (attribute: false, calendar mode only) — the vertical
+  analogue of `columnX`: overrides the internal weekday-row y-coordinate formula (`CAL_LABEL_H +
+  weekday * (cellSize + CAL_GAP)`), consulted consistently by drawing, hit-testing, and the focus
+  ring (also consulted at `weekday = 7` to size the canvas height, mirroring `columnX` at
+  `week = weekCount`). Unset (the default) is the original formula, unchanged. Ignored in matrix
+  mode.
+- `cellColor?: (pos: MatrixCellPos | CalendarCellPos, value: number) => string | undefined`
+  (attribute: false) — overrides a cell's computed ramp/no-data color entirely for an exact value;
+  return a CSS color string to force that cell to it, or `undefined` to fall back to the normal ramp
+  math unchanged. Lets a consumer designate a value as categorically outside the ramp (e.g. a real
+  zero-count day rendered as a neutral hairline, distinct from both "no data" and the ramp's own
+  lightest step) without a synthetic ramp color, which can't safely reserve an exact value on a
+  skewed dataset. Unset (the default) reproduces the exact ramp/no-data behavior for every cell.
+- `weekdayLabelText?: (jsWeekday: number) => string | undefined` (attribute: false, calendar mode
+  only) — overrides the weekday-axis label text; receives the real JS weekday index (`0` Sunday ..
+  `6` Saturday) for a row that would otherwise render a label and, when it returns a string, uses it
+  instead of the built-in `Intl.DateTimeFormat`-derived short weekday name. Unset (the default)
+  reproduces today's exact locale-derived output.
+- `monthLabelText?: (jsMonth: number, year: number) => string | undefined` (attribute: false,
+  calendar mode only) — the month-axis analogue of `weekdayLabelText`: receives the real JS month
+  index (`0` January .. `11` December) and full year for a month boundary that would otherwise
+  render a label, and, when it returns a string, uses it instead of the built-in
+  `Intl.DateTimeFormat`-derived short month name. Unset (the default) reproduces today's exact
+  locale-derived output. Lets month labels track the same locale signal (e.g. an app's own i18n
+  store) as `weekdayLabelText` and the component's other localizable strings, instead of always
+  following the browser/OS-language default.
+- `colorSteps?: string[]` (attribute: false) — a discrete array (≥2 entries) of CSS colors used as
+  exact ramp steps instead of linearly interpolating between `--lr-heatmap-scale-lo`/`-hi`;
+  governs both `mode`s and both `scale` values, discretizing whichever scale would otherwise
+  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
+  `--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
+  entirely, the built-in two-endpoint bar can end up describing a ramp the grid no longer uses —
+  supplying the same colors here keeps the legend honest instead of hiding `::part(legend)` and
+  re-implementing swatches, labels and annotation entries by hand. Strictly presentation: the stops
+  are never consulted by the color ramp, the bucket math, the tooltip, or the generated accessible
+  name, so adding them changes nothing a cell renders. Labeled `annotations` still render their
+  `[part="legend-annotation"]` entries after the stops. Unset (the default) or an empty array
+  reproduces the exact gradient legend, unchanged.
+
+**Getters/methods:** `refreshTheme()` — redraws canvas content after an upstream design-token or
+color-scheme change; called automatically on theme changes, exposed for a consumer that needs to
+force a redraw manually.
+
+**Events:** `lr-cell-click` (fired on click, or Enter/Space on the keyboard-focused cell —
+`detail: { row, col, value }` in matrix mode, `detail: { date, value }` in calendar mode)
+
+**Slots:** none.
+
+**CSS parts:** `base`, `canvas`, `cells` (opt-in per-cell overlay), `cell` (one opt-in native cell
+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, 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`),
+`--lr-heatmap-scale-hi` (default `#0969da`) — the sequential color-ramp endpoints (matrix mode) or
+quartile-bucket ramp endpoints (calendar mode), resolved via `getComputedStyle` each draw (any valid
+CSS color syntax — hex/rgb/hsl/oklch/named — works, resolved through a scratch canvas).
+`--lr-heatmap-no-data-fill` (default `rgba(128,128,128,0.25)` — the no-data cell fill, same
+resolve-via-`getComputedStyle` pattern), `--lr-heatmap-label-font` (default `10px sans-serif` — the
+canvas-drawn axis/month/weekday label font), `--lr-heatmap-focus-ring-color` (default
+`var(--lr-focus-ring-color)` — the canvas-drawn ring stroked around the keyboard-focused cell;
+also reused by `[part="canvas"]`'s own `:focus-visible` outline so the two stay visually in sync),
+`--lr-heatmap-color-steps-gradient` (default
+`linear-gradient(to right, var(--lr-heatmap-scale-lo), var(--lr-heatmap-scale-hi))` — the gradient
+painted on the continuous legend bar; the component writes it onto the host itself while
+`colorSteps` is supplied and removes it again when it isn't, so it is a read-out rather than a knob
+you set). `--lr-heatmap-annotation-color` (default `var(--lr-color-danger)` — the canvas-drawn ring
+stroked around an annotated cell, deliberately not one of the sequential ramp colors so it stays
+visible regardless of what it's drawn over). `--lr-heatmap-selected-color` (default
+`var(--lr-color-success)` — the canvas-drawn ring stroked around the persistent `selectedCell`, a
+dedicated token distinct from both the focus ring and the annotation ring so a host can retheme it
+independently). `--lr-heatmap-tooltip-bg` (default
+`var(--lr-color-surface)`) and `--lr-heatmap-tooltip-text` (default `var(--lr-color-text)`) —
+unlike the canvas-drawn tokens above, `[part="tooltip"]` is a real DOM element and consumes these
+directly, no `getComputedStyle` bridging needed. Also consumes `--lr-color-text-quiet` (axis label
+color), `--lr-space-xs`, `--lr-radius`/`--lr-shadow` (tooltip box), and `--lr-focus-ring-width`/
+`--lr-focus-ring-offset` (the real `[part="canvas"]:focus-visible` DOM outline, stroked in the
+same color as `--lr-heatmap-focus-ring-color`).
+
+**Optional peer deps:** none.
+
+```html
+<lr-heatmap value-label="requests"></lr-heatmap>
+<script>
+  const hm = document.querySelector('lr-heatmap');
+  hm.rowLabels = ['Mon', 'Tue', 'Wed'];
+  hm.colLabels = ['00h', '06h', '12h', '18h'];
+  hm.values = [[3, 8, 12, 4], [1, 2, 9, 5], [0, 4, 6, 2]];
+</script>
+```
+
+```html
+<!-- Calendar mode: a GitHub-contributions-style day grid -->
+<lr-heatmap mode="calendar" value-label="commits"></lr-heatmap>
+<script>
+  document.querySelector('lr-heatmap').days = [
+    { date: '2026-01-01', value: 3 },
+    { date: '2026-01-02', value: 0 },
+    // ...
+  ];
+</script>
+```
+
+**Known gotchas:**
+- `legendStops` *replaces* the lo/hi gradient bar rather than adding to it: supplying it removes
+  `[part="legend-lo"]`, `[part="legend-hi"]` and the bar from the DOM, so a stylesheet targeting
+  those parts silently stops applying. It is also presentation-only — it never feeds back into the
+  cell colors, so the stops and a `cellColor` callback have to be kept in agreement by the consumer
+  (the point of the property is that they *can* be, from one shared function).
+- the `ResizeObserver` only actually resizes the drawn grid **when `fit-to-width` is set**, in either
+  mode. Without it (the default), `draw()` sizes the canvas as `PAD_LEFT + cols * cellSize` (matrix
+  mode) or `CAL_PAD_LEFT + weekCount * cellSize` (calendar mode), never from the host's measured
+  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,
+  `[part="live-region"]` announcements, `lr-cell-click`), and `role="img"` is documented (ARIA) to
+  flatten its subtree to a single image for some assistive tech, which conflicted with that
+  focusable descendant — fixed, matching `lr-lite-chart`/`lr-word-cloud`'s existing `role="group"`
+  pattern.
+- `NaN`/non-finite cell values in matrix mode are correctly treated as no-data now (alongside `-1`),
+  and repeated DPR crossings (moving the window across displays with different pixel ratios) no
+  longer leak a `MediaQueryList` listener per crossing — both previously-known issues are fixed.
+- calendar mode's date labels (used by the default `cellText` template and the tooltip/live-region
+  text) now format via the runtime locale (`toLocaleString(undefined, ...)`) instead of a hardcoded
+  `'en'` — fixed. The canvas-drawn axis chrome is now locale-aware too: month labels use
+  `toLocaleString(undefined, ...)` (previously hardcoded `'en'`) and weekday labels are derived via
+  `Intl.DateTimeFormat(undefined, { weekday: 'short' })` (previously a literal English `['', 'Mon',
+  '', 'Wed', '', 'Fri', '']` array) — same sparse every-other-day spacing, just locale-correct text.
+
+---

package/llms/components/lr-highlight-layer.md

@@ -0,0 +1,31 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-highlight-layer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/highlight-layer/highlight-layer.js';` (registers the tag; side-effect import)
+- **Class** `LyraHighlightLayer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/highlight-layer/highlight-layer.class.js`
+- **Family** `components/viewers/` — 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-highlight-layer`
+
+A presentational overlay that paints highlight rectangles (percent-of-box coordinates) over
+positioned content and owns their activation, active/flash styling, and keyboard access. `items`
+order is the caller's own reading order; the layer does not re-sort geometrically. Fills its nearest
+positioned ancestor.
+
+**Properties:** `items: HighlightLayerItem[] = []` (attribute: false), `activeId: string | null =
+null` (attribute `active-id`), and `interactive: boolean = true` (reflected) — gates click/keyboard
+activation.
+
+**Methods:** `flash(id)` briefly re-triggers the flash styling for an already-rendered rect (e.g. a
+re-click of the same source citation).
+
+**Events:** `lr-highlight-activate` — a rect was activated (click, or Enter/Space while focused).
+`detail: { id }`.
+
+**CSS parts:** `base` (the absolutely-positioned overlay, inset 0) and `rect` (one highlight
+rectangle; carries `data-tone`/`data-active`/`data-flash` state attributes).

package/llms/components/lr-histogram.md

@@ -0,0 +1,71 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-histogram`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/histogram.js';` (registers the tag; side-effect import)
+- **Class** `LyraHistogram`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/histogram.class.js`
+- **Family** `components/charts/` — see `llms/index.md` for its siblings
+- **Optional peers** `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-histogram`
+
+Bins `values` into `bins` equal-width buckets and renders as a bar chart (extends `LyraChart`,
+`type` fixed to `'bar'`).
+
+**Properties:**
+- `bins: number = 10` — finite values are floored and clamped to 0–1,000 before allocation;
+  non-finite values produce no buckets
+- `values: number[] = []` (attribute: false)
+- `label: string = ''` — dataset label used for the legend/tooltip/accessible summary; empty (the
+  default) falls back to the localized "Frequency" string
+- `labels`/`datasets`/`type` are **derived, read-only** (installed as getter/setter pairs on the
+  prototype; direct writes are silently ignored) — `labels`/`datasets` are computed from
+  `values`/`bins` (memoized per instance, keyed by reference equality on `values` plus the
+  normalized `bins`), and `type` always reads back `'bar'` regardless of any assignment. The `type`
+  lock is the same `lockChartType()` accessor pair the typed `lr-*-chart` subclasses use (e.g.
+  `llms/components/lr-bar-chart.md`) — `el.type = 'line'` is a genuine no-op here too.
+- All other `LyraChart` properties are inherited and usable: `legend`, `legendPosition` (attribute
+  `legend-position`), `valueFormatter`, `area`, `zoom`, `config`, `height`, `xLabel` (`x-label`),
+  `yLabel` (`y-label`), `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `horizontal`,
+  `stacked`, `accessibleLabel` (`accessible-label`), `accessibleDescription`
+  (`accessible-description`), `showDataTable` (`show-data-table`), `chartArea` (readonly).
+
+**Methods:** `resetZoom()`, `refreshTheme()` — both inherited.
+
+**Events:** `lr-zoom`, `lr-point-click` — inherited; `lr-point-click`'s `index` is the bucket index
+and `label` the generated bucket range string (`"lo–hi"`, both bounds at one decimal place).
+
+**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 — 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`,
+`--lr-chart-tooltip-text` — inherited from `LyraChart`, identical in meaning.
+
+**Optional peer deps:** the same `chart.js` (+ `chartjs-plugin-zoom` when `zoom` is set) peers.
+
+All of the above behave exactly as documented in `llms/components/lr-chart.md` — read that file for
+their semantics, defaults, and gotchas.
+
+```html
+<lr-histogram bins="12"></lr-histogram>
+<script>
+  document.querySelector('lr-histogram').values = [1, 2, 2, 3, 5, 5, 5, 8, 13, 13];
+</script>
+```
+
+**Known gotchas:**
+- `bins <= 0` no longer crashes: `binValues()` now returns an empty bucket array for `binCount <= 0`
+  (or empty `values`), so the histogram just renders with no bars instead of throwing.
+- excessively large finite bin counts are capped at 1,000, preventing an attribute or direct
+  property write from requesting an unbounded bucket array.
+- non-finite samples in `values` are dropped before bucketing rather than corrupting bucket-index
+  math; constant data (every sample equal) lands wholly in the **first** bucket, not the last.
+
+---

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

@@ -0,0 +1,30 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-html-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/html-viewer/html-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraHtmlViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/html-viewer/html-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `dompurify` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-html-viewer`
+
+Fetches an HTML document, sanitizes it with the optional `dompurify` peer, and renders the safe markup
+inside a bounded, scrollable body.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings.
+
+**Events:** `lr-render-error` with `detail.error` when fetching or sanitizing fails.
+
+**CSS parts:** `base`, `body`, `html`, `spinner`, and `error`.
+
+**Themeable custom properties:** `--lr-html-viewer-max-height` (default `none`) — maximum block size
+of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
+
+**Optional peer dependency:** `dompurify`.
+
+Remote resources are capped at 25 MB; exceeding it surfaces the localized
+`documentPreviewResourceTooLarge` message instead of the document.

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

@@ -0,0 +1,55 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-icon-button`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/icon-button/icon-button.js';` (registers the tag; side-effect import)
+- **Class** `LyraIconButton`, also available unregistered from `@aceshooting/lyra-ui/components/forms/icon-button/icon-button.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-icon-button`
+
+An accessible icon-only action button — a native `<button>` wrapping an `lr-icon`. Not
+form-associated: it is an action trigger, so `type="submit"`/`"reset"` work through the ancestor
+form the way a native button does, but the element itself contributes no form value.
+
+**Properties:**
+- `icon: string = ''` — an `lr-icon` glyph name (see `llms/components/lr-icon.md`)
+- `accessibleLabel: string = ''` (attribute: `aria-label`) — the typed override for the button's
+  accessible name; wins over `label`
+- `label: string = ''` — accessible name when `accessibleLabel` is unset
+- `disabled: boolean = false` (reflected)
+- `type: 'button' | 'submit' | 'reset' = 'button'`
+
+With neither `accessibleLabel` nor `label` set, the name falls back to the localized
+`iconButtonLabel` string rather than being empty — override it per instance with `.strings` or
+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. `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.
+
+**Migration note:** bare SVG *geometry* (`<path>`, `<circle>`, `<rect>` …) slotted with no `icon`
+set has no SVG parent here and will not paint. Wrap it in an `<lr-icon>`, or in a complete `<svg>`
+of your own.
+
+**CSS parts:** `button`
+
+**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-icon.md

@@ -0,0 +1,36 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-icon`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/icon/icon.js';` (registers the tag; side-effect import)
+- **Class** `LyraIcon`, also available unregistered from `@aceshooting/lyra-ui/components/utility/icon/icon.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-icon`
+
+Dependency-free SVG path icon: no icon font, no sprite sheet, no network fetch. Pairs with
+`lr-icon-button` (see `llms/components/lr-icon-button.md`).
+
+**Properties:**
+- `name: string = ''` — a built-in glyph: `add`, `check`, `close`, `search`, `menu`,
+  `chevron-left`, `chevron-right`, `chevron-down`, `calendar`, `command`, `trash`. An unknown name
+  renders nothing (no error, no fallback glyph).
+- `path: string = ''` — raw SVG path data for a glyph the built-in set doesn't cover. Takes
+  precedence over `name`.
+- `label: string = ''` — accessible name. Left empty (the default) the SVG is `aria-hidden="true"`,
+  which is what you want whenever adjacent text already names the control.
+
+**Slots:** (default) — custom SVG geometry, rendered only when neither `path` nor a known `name`
+resolves. Slotted nodes are cloned into the component-owned `<svg>` (Chromium does not paint SVG
+geometry distributed through a slot that sits inside an SVG), so pass plain `<path>`/`<circle>`/
+`<g>` elements, not a whole `<svg>`.
+
+**CSS parts:** `svg`
+
+**Themeable custom properties:** `--lr-icon-size` (default `--lr-size-1-25rem`) sets both
+dimensions. Stroke color is `currentColor` and the host is `color: inherit`, so color comes from
+the surrounding text with no configuration.

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

@@ -0,0 +1,38 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-image-comparer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/image-comparer/image-comparer.js';` (registers the tag; side-effect import)
+- **Class** `LyraImageComparer`, also available unregistered from `@aceshooting/lyra-ui/components/media/image-comparer/image-comparer.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-image-comparer`
+
+Before/after comparison surface with two named slots and a keyboard-accessible native range handle.
+
+**Properties:**
+- `position: number = 50` (attribute `position`, reflected) — divider position from 0 to 100
+- `orientation: 'horizontal'|'vertical' = 'horizontal'` (attribute `orientation`, reflected)
+- `accessibleLabel: string | null` (attribute `aria-label`) — accessible name for the comparison
+  and its range handle
+- `beforeLabel`/`afterLabel` — fallback text for empty named slots
+
+**Events:** `lr-position-change` (`detail: { position }`), plus composed `focus` and `blur` events
+from the internal range handle.
+
+**Slots:** `before`, `after`.
+
+**CSS parts:** `base`, `before`, `after`, `divider`, and `handle`.
+
+```html
+<lr-image-comparer aria-label="Before and after">
+  <img slot="before" alt="Before" src="before.png">
+  <img slot="after" alt="After" src="after.png">
+</lr-image-comparer>
+```
+
+---

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

@@ -0,0 +1,54 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-image-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/image-viewer/image-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraImageViewer`, also available unregistered from `@aceshooting/lyra-ui/components/media/image-viewer/image-viewer.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-image-viewer`
+
+A full pan/zoom raster-image viewer with labeled region highlights and opt-in region annotation, the
+landing surface for `region`-anchored citations. Distinct from `<lr-svg-viewer>` (rendered SVG
+documents) and `<lr-image-comparer>` (before/after slotted surfaces). Adopts `DocumentAnchorTarget`
+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), `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
+the embedded zoomable-frame's zoom.
+
+**Events:** `lr-load` (`detail: { naturalWidth, naturalHeight }`), `lr-zoom-change` (`detail: {
+zoom }`), `lr-rotation-change` (`detail: { rotation }`), `lr-fit-change` (`detail: { fit }`),
+`lr-highlight-activate` (`detail: { id }`), `lr-annotation-create` (`detail: { anchor }`, kind
+`'region'`), `lr-anchor-result` (`detail: { found }`), and `lr-render-error` (`detail: { error
+}`).
+
+**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-include.md

@@ -0,0 +1,53 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-include`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/include/include.js';` (registers the tag; side-effect import)
+- **Class** `LyraInclude`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/include/include.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `dompurify` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-include`
+
+Fetches an HTML fragment from `src` and transcludes it as sanitized **light-DOM** content, so the
+fragment participates in the surrounding page's CSS cascade like a native server-side include —
+unlike `<lr-html-viewer>`, which renders a foreign document inside an isolated preview card. The
+markup always passes through the shared DOMPurify-backed sanitizer before it reaches `innerHTML`;
+there is deliberately no `allow-scripts`-style escape hatch (the Web Awesome/Shoelace equivalents'
+raw injection option is omitted, not shipped as a no-op).
+
+A bare primitive: no label/hint/error chrome, no implicit role, no computed accessible name, and no
+`aria-live` wrapper (the fragment can carry its own landmarks; wrapping the host would re-announce
+all of it on every load). `aria-busy="true"` is set on the host while a fetch is in flight and
+removed once it settles either way. Build error UI from `lr-include-error`.
+
+**Properties:**
+- `src: string = ''` (reflected) — URL of the fragment, validated through the shared `safeFetchUrl()`
+  allowlist (`http:`, `https:`, `blob:`, `data:`). Empty/falsy is a no-op: no fetch, no events,
+  existing content untouched.
+- `mode: 'cors' | 'no-cors' | 'same-origin' = 'same-origin'` (reflected) — forwarded to
+  `fetch(url, { mode })`. Defaults to `same-origin` (not the upstream components' `cors`) so
+  cross-origin fetching is opt-in; an invalid value is normalized back to `same-origin` rather than
+  letting `fetch()` throw. `no-cors` is accepted for enum completeness but always yields an opaque
+  response (`status` `0`, unreadable body) — a Fetch API limitation, not a bug here.
+
+**Events:**
+- `lr-load` — `detail: { src }` — the fragment was sanitized and written into the light DOM.
+- `lr-include-error` — `detail: { status, reason, error? }`. `reason` is a `LyraIncludeErrorReason`:
+  `'blocked-url'` (`src` failed the allowlist; `fetch()` never ran), `'network'` (`fetch()` rejected),
+  `'http'` (response not `ok`; `status` carries the code), `'missing-sanitizer'` (the optional
+  `dompurify` peer failed to load), or `'resource-too-large'` (the body exceeded the shared 25 MB
+  cap). `status` is `0` for every reason but `'http'`.
+
+**Slots:** default — fallback content shown until (or unless) a fetch succeeds. It is overwritten by
+the sanitized fragment on success, and left untouched on failure (as is any previously successful
+include).
+
+**CSS parts:** `base` — the `display: contents` wrapper around the default slot.
+
+Deviates from the shared degraded-render contract: an absent `dompurify` fires
+`lr-include-error` with `reason: 'missing-sanitizer'` and leaves the existing content in place —
+unsanitized markup is never transcluded.