@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-segmented.md

@@ -0,0 +1,96 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-segmented`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/segmented/segmented.js';` (registers the tag; side-effect import)
+- **Class** `LyraSegmented`, also available unregistered from `@aceshooting/lyra-ui/components/layout/segmented/segmented.class.js`
+- **Family** `components/layout/` — 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-segmented`
+
+A single-select button row with the WAI-ARIA APG `radiogroup` contract built in:
+`role="radiogroup"`/`role="radio"`, roving tabindex, automatic activation (click or arrow-key move
+both select immediately, like a native radio group), cyclic Arrow/Home/End navigation among
+non-disabled items. First-party invention (no Web Awesome equivalent) — "choose exactly one of N
+labeled options, rendered as a button row" is ubiquitous settings/filter-panel UI.
+
+**Properties:**
+- `items: SegmentedItem[] = []` (attribute: false) — `SegmentedItem { value: string; label: string;
+  icon?: unknown; disabled?: boolean }`; `icon` renders as a decorative leading visual inside
+  `segment-icon` and does not replace the required text label.
+- `value: string = ''` — the currently selected item's `value`.
+- `label: string = ''` — accessible name copied to the internal `role="radiogroup"`; when empty, a
+  host-level `aria-label` is used as a fallback.
+- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected) — visual size, matching
+  `lr-select`/`lr-combobox`'s `xs`-`xl` scale plus `lr-input`'s `2xs` tier. `m` (the default) is
+  unchanged from this component's pre-`size` rendering.
+
+**Events:** `lr-change` (`detail: { value }`) — fired when the selected value changes via click or
+keyboard.
+
+**Slots:** none.
+
+**CSS parts:** `base` (the `role="radiogroup"` root), `segment` (a single `role="radio"` button),
+`segment-icon` (an optional decorative leading icon), `segment-label` (the segment's label text).
+
+**Themeable custom properties:** `--lr-scroll-fade-size` (default `2rem`) — width of the static mask
+fade at each horizontal scroll edge of the track. `--lr-segmented-track-min-height`,
+`--lr-segmented-segment-padding`, and `--lr-segmented-font-size` are the three knobs `size` swaps
+(`m` defaults: `auto`, `var(--lr-size-0-125rem) var(--lr-space-s)`, `var(--lr-font-size-sm)`) —
+override them on the host for a size tier the scale doesn't cover, since a `:host([size])` rule
+wins over the `:host` default.
+
+`--lr-segmented-track-height` pins the `base` track's exact height at every `size` tier (it sets
+both `block-size` and `min-block-size`), for a row that has to sit flush beside a hard-sized toolbar
+control. It is **genuinely undeclared by default** — not `auto` — and that is load-bearing: an
+exact-height hatch only works as an undeclared sentinel, because `auto` is itself a valid value that
+would always win and would silently turn every tier's `--lr-segmented-track-min-height` floor into
+dead code. While it is unset, each tier keeps its own floor and the track grows with its content.
+
+`--lr-segmented-selected-bg` (default `var(--lr-color-surface)`), `--lr-segmented-selected-color`
+(default `var(--lr-color-text)`), `--lr-segmented-selected-font-weight` (default
+`var(--lr-font-weight-semibold)`) and `--lr-segmented-selected-shadow` (default `var(--lr-shadow)`)
+style the checked segment's pill; `--lr-segmented-hover-color` (default `var(--lr-color-text)`)
+styles a hovered segment that is neither checked nor disabled, independently of the four above — so
+recoloring the checked pill never bleeds onto hover. All five are inline `var()` fallbacks at the
+point of use rather than `:host` declarations, so each can be set on the element *or on any
+ancestor*; unset, each falls back to the token its rule used before. They exist because
+`::part(segment)[aria-checked='true']` is invalid CSS — Shadow Parts forbids an attribute selector
+after `::part()` — which previously left hijacking the library-wide
+`--lr-color-surface`/`--lr-color-text` tokens as the only way to restyle a selected segment,
+repainting every other element that read them.
+
+Otherwise shared tokens — `--lr-color-border`/`-surface`/`-text`/
+`-text-quiet`, `--lr-radius`, `--lr-font-weight-semibold`, `--lr-space-s`, `--lr-shadow`,
+`--lr-opacity-disabled`, `--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-segmented></lr-segmented>
+<script type="module">
+  const seg = document.querySelector('lr-segmented');
+  seg.items = [
+    { value: 'day', label: 'Day', icon: '☀' },
+    { value: 'week', label: 'Week', icon: '▦' },
+    { value: 'month', label: 'Month' },
+  ];
+  seg.value = 'week';
+  seg.addEventListener('lr-change', (e) => console.log(e.detail.value));
+</script>
+```
+
+**Known gotchas:**
+- arrow-key navigation cycles (past the last non-disabled item wraps to the first, and vice versa)
+  rather than clamping at the first/last item, unlike `lr-stepper`'s clamped Left/Right.
+- this component self-selects on navigation: clicking or arrow-navigating to an item immediately
+  updates `value` and fires `lr-change` — there's no separate "commit" step the way, e.g.,
+  `lr-select`'s popup has.
+- the semantic `radiogroup` lives inside shadow DOM. Set `label` (preferred for reactive code) or a
+  host `aria-label`; the component deliberately forwards the resulting name to that internal role.
+
+---

package/llms/components/lr-select.md

@@ -0,0 +1,140 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-select`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/select/select.js';` (registers the tag; side-effect import)
+- **Class** `LyraSelect`, also available unregistered from `@aceshooting/lyra-ui/components/forms/select/select.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-select`
+
+A plain closed-list dropdown — a direct `<lr-*>` counterpart to `<wa-select>`/`<wa-option>`.
+**Form-associated** (hand-rolled internals, not the shared `FormAssociated` mixin — same reasoning
+as `lr-combobox`, see the shared-foundation notes above). The trigger is a `<button>`, not a text
+input: click/Enter/Space/ArrowDown opens it, and there's no typing-to-filter. Options are
+`<lr-option value>` children — the same element `<lr-combobox>` uses — reconciled the same way
+combobox does, and the popup reuses `internal/positioner.ts` for placement.
+Session-history/autofill restoration assigns the stored string through the same synchronous
+value/form/validity path as a programmatic value write and does not emit `input` or `change`.
+
+Single-select only, with no `filter`/`source`/`with-clear`/`max-options-visible`/`empty-text`/
+`max-render`/`multiple` surface — reach for `<lr-combobox>` instead whenever any of those apply.
+
+**Single-option auto-commit.** Opt-in via `autoCommitSingleOption` (default `false` — a select always
+renders the normal combobox/listbox/chevron trigger unless enabled, matching pre-1.3.0 behavior).
+When set and exactly one option is enabled (regardless of how many disabled ones exist alongside
+it), the popup never opens at all: a click, Enter, Space, ArrowDown, or ArrowUp on the trigger
+commits that sole option directly, and the trigger renders as a plain `role="button"` with no
+chevron/`aria-haspopup`/`aria-expanded`/`aria-controls`/`aria-activedescendant` rather than a
+combobox with a permanently inert popup state — opening a one-row list to pick the only available
+choice is pure friction with no real decision behind it. It never changes `value`/validity defaults
+on its own: an unselected single-option select stays unselected (and a `required` one stays invalid)
+exactly like the multi-option case, until the trigger is actually activated.
+
+**Properties:**
+- `placeholder: string = ''`
+- `disabled: boolean = false` (reflected)
+- `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
+- `name: string = ''`
+- `label: string = ''`
+- `hint: string = ''`
+- `errorText: string = ''` (attribute `error-text` — static error copy shown below the hint;
+  overridden by slotted `error` content when provided)
+- `open: boolean = false` (reflected)
+- `size: 'xs'|'s'|'m'|'l'|'xl' = 'm'` (reflected — same scale as `lr-toast-item`'s `size`, for
+  compact toolbar placements that don't fit the default trigger height)
+- `autoCommitSingleOption: boolean = false` (attribute `auto-commit-single-option`) — opts in to the
+  single-option auto-commit behavior described above
+- `value: string` — a getter/setter; always a single string (no `multiple` mode)
+
+**Events:** `change` (native-style — selection changed), `input` (fired alongside `change` on every
+selection change — a native `<select>` doesn't meaningfully distinguish the two either),
+`lr-show`, `lr-hide`
+
+**Slots:** default (`<lr-option>` children), `label`, `hint`, `error` (overrides the `errorText`
+attribute when provided)
+
+**`lr-select` deliberately has no `start`/`end` adornment slots**, unlike
+`lr-input`/`lr-combobox`/`lr-date-input`. Two reasons, both structural rather than incidental:
+its `[part='trigger']` is a native `<button>`, and HTML's content model forbids interactive
+descendants inside one — so the slot could only ever accept decorative content, a materially
+different contract from the other three that would read as the same feature; and the trigger lays
+out with `justify-content: space-between`, so injecting a leading element pushes the selected label
+into the middle of the control instead of leaving it at the start. **Instead:** put a glyph in the
+`label` slot, or compose the select into `<lr-control-group>` alongside the adornment.
+
+When hint/error content is present, the trigger's `aria-describedby` references stable shadow-local
+IDs for both messages (error first, then hint), so the visible supporting text is part of the
+control's accessible description.
+
+**CSS parts:** `form-control`, `form-control-label`, `trigger`, `listbox`, `group-label` (a heading
+row emitted inside the listbox whenever an option's `group` differs from the previous one's — a
+presentational `<div>`, not a `role="group"`; options with an empty `group` get no heading),
+`option`, `option-dot` (the leading status dot, when a row's `dotColor` is set), `option-label`,
+`option-sub` (a row's secondary line, when `sub` is set), `expand-icon`, `error`, `hint`
+
+**Themeable custom properties:** `--lr-select-trigger-padding`, `--lr-select-trigger-min-height`,
+`--lr-select-font-size`, `--lr-select-expand-size` — all four auto-swapped per `size` (`xs`…`xl`), the same pattern
+`lr-toast-item`'s `--lr-toast-padding`/`--lr-toast-font-size` use.
+
+`--lr-select-trigger-min-height` is live at **every** tier, the default `m` included, where it is
+`2.5rem` — byte-identical to `lr-input`'s and `lr-combobox`'s own `m` floor, so the three controls
+agree at that tier. It used to be dead code: the component declared `--lr-select-trigger-height:
+auto` on `:host`, and a *declared* value (`auto` is one) wins over the `var()` fallback arm that
+the floor lives in, so the floor never applied and four extra specificity rules existed only to
+patch it back for four of the tiers. Those rules are gone.
+
+`--lr-select-trigger-height` pins an **exact** trigger height — both a floor and a cap — e.g. to
+pixel-match a sibling text field in the same toolbar row. It is **undeclared by default**, which is
+exactly what keeps the per-tier floor alive; see "exact-height hatches" under `lr-input`. Because
+the component never declares it, it can be set inline, from an ancestor, or from an outer-tree
+rule. One consequence worth knowing when testing:
+`getComputedStyle(el).getPropertyValue('--lr-select-trigger-height')` now reads `''` rather than
+`'auto'` — assert the rendered `min-block-size`/`block-size` instead of the property string.
+
+`--lr-select-option-active-bg` (default `var(--lr-color-brand-quiet)`) recolors the background of a
+hovered or keyboard-active `[part='option']` row. Not declared on `:host`, so a value set on any
+ancestor is never shadowed — retheme just this row state without hijacking the shared
+`--lr-color-brand-quiet` token every other component's own hover/active state also reads. Same
+knob `lr-combobox`'s own `--lr-combobox-option-active-bg` provides.
+
+**Optional peer deps:** none.
+
+```html
+<lr-select id="sel" label="Fruit" placeholder="Pick one…">
+  <lr-option value="a">Apple</lr-option>
+  <lr-option value="b" selected>Banana</lr-option>
+</lr-select>
+<script type="module">
+  document.getElementById('sel').addEventListener('change', (e) => console.log(e.target.value));
+</script>
+```
+
+**Known gotchas:**
+- The trigger keeps real DOM focus throughout — the listbox's "active" row is conveyed via
+  `aria-activedescendant`, never actual focus, matching the WAI-ARIA "select-only combobox" pattern
+  (as opposed to `lr-combobox`'s editable-input pattern).
+- No typing-to-filter, but a printable keypress still jumps to (while open) or directly selects
+  (while closed) the next non-disabled option whose label starts with what's been typed, matching a
+  native `<select>`'s own type-ahead; the buffer resets ~500ms after the last keystroke.
+- Declaratively-selected options (`<lr-option value="b" selected>`) seed the initial selection
+  (mirroring native `<select><option selected>`) both the first time options are collected and for
+  any later-slotted batch — only that very first pass' declared selection becomes the
+  `form.reset()` default, the same rule `lr-combobox` follows.
+- `aria-required` on the trigger reflects `required` immediately; `aria-invalid` only reflects once
+  the trigger has been blurred (touched) at least once, mirroring `lr-combobox`'s own input.
+  Blurring the trigger (Tab away) closes an open listbox, the same as a native `<select>`'s popup.
+- The trigger's accessible name now checks a host-level `aria-label` attribute first, before falling
+  back to `label`/`placeholder`/`"Select"` — a plain `aria-label` on `<lr-select>` is no longer
+  silently ignored.
+- With `autoCommitSingleOption` set, a select with exactly one enabled option never exposes
+  `role="combobox"`/opens a listbox at all — see "Single-option auto-commit" above.
+  Testing/automation code that always expects a `role="combobox"` trigger, or that opens the
+  listbox before asserting on a row, either needs at least two enabled options or should leave
+  `autoCommitSingleOption` unset to observe the normal dropdown chrome.
+
+---

package/llms/components/lr-sequence-strip.md

@@ -0,0 +1,107 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-sequence-strip`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/sequence-strip/sequence-strip.js';` (registers the tag; side-effect import)
+- **Class** `LyraSequenceStrip`, also available unregistered from `@aceshooting/lyra-ui/components/data/sequence-strip/sequence-strip.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-sequence-strip`
+
+A compact, one-thin-cell-per-item strip visualizing a sequence of categorical states, with an
+optional secondary per-cell marker. Pure CSS/flex — no chart.js, no SVG, no canvas — sized/named
+consistently with the sparkline/heatmap family, but a glanceable *aggregate* visualization
+(`role="img"`, one summarizing `aria-label`) rather than a `role="list"` of separately-operable
+items: there is no per-cell keyboard focus and no per-cell click event, matching `<lr-sparkline>`'s
+accessibility model rather than `<lr-heatmap>`'s heavier canvas-plus-keyboard-roving one. Hovering a
+cell (pointer only) shows `[part="tooltip"]` with that item's label. Setting `showLegend`
+additionally renders a static `[part="legend"]` key below the strip, so the color-to-category
+mapping is readable without hovering each cell.
+
+**Properties:**
+- `items: SequenceStripItem[] = []` (attribute: false) — `{ id, category, marker?, label? }`;
+  `marker` renders a small bottom marker on that cell independent of the category color (e.g. a
+  subagent-dispatched turn); `label` is per-item hover-tooltip text, falling back to the matching
+  category's own `label` (or its `key`) when unset — not read by the auto-generated `aria-label`,
+  which summarizes by category/count only
+- `categories: SequenceStripCategory[] = []` (attribute: false) — `{ key, color, label? }`; `color`
+  is the cell background for every item whose `category` matches `key` (an item whose `category`
+  matches no entry renders `transparent`); `label` is used in the auto-generated `aria-label` summary
+  and as the hover-tooltip fallback text, falling back to `key` itself when unset
+- `orientation: 'horizontal' = 'horizontal'` (reflected) — only `'horizontal'` is supported today;
+  vertical is plausible future scope, not built speculatively without a motivating case
+- `accessibleLabel?: string` (attribute `accessible-label`) — overrides the auto-generated
+  `aria-label` (a per-category "label: count" summary, e.g. `"Text: 2, Tool: 1"`). Unset computes the
+  summary from `items`/`categories`
+- `showLegend: boolean = false` (attribute `show-legend`, reflected) — renders a static
+  `[part="legend"]` key below the strip, one swatch + label row per `categories` entry, in array
+  order. The key describes the *scheme*, not the current data: a category with no matching item
+  still gets a row, and an item whose `category` matches no entry adds none. Deliberately
+  non-interactive — it toggles nothing and emits nothing (`lr-graph-legend` is the interactive,
+  filtering legend). Because it only repeats the category names `[part="base"]` already announces
+  through its `role="img"` summary, the legend is `aria-hidden` — visible on screen, announced
+  exactly once — and it wraps onto further rows in a narrow allocation rather than overflowing
+- `markerLabel?: string` (attribute `marker-label`) — names what an item's `marker` *means* (e.g.
+  `"Subagent"`). Setting it does two things: with `showLegend` on it adds one trailing
+  `[part="legend-item"]`, whose `[part="legend-marker-swatch"]` reproduces the cell's own marker
+  treatment, and it adds the marker to the auto-generated `aria-label` summary, which is otherwise
+  per-category only. The marker count is reported as its own clause rather than folded into any
+  category's count. Unset (the default) changes nothing: no extra legend row, no extra summary clause
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `base` (the root strip, `role="img"`), `cell` (each item's cell, background-colored
+by its category), `marker` (the small bottom marker on a cell whose item sets `marker: true`),
+`tooltip` (the hover tooltip showing the hovered item's label, hidden until a cell is hovered),
+`legend` (the static category key rendered below the strip when `showLegend` is set — `aria-hidden`,
+as it repeats the strip's own `aria-label`), `legend-item` (one swatch + label pair, one per
+`categories` entry, plus one trailing marker row when `markerLabel` is set), `legend-swatch` (the
+color chip, matching that category's cell color), `legend-marker-swatch` (the marker row's chip
+instead: a neutral chip carrying the same bottom bar a `marker: true` cell paints, in the same
+`--lr-sequence-strip-marker-color`), `legend-label` (the category's `label`, or its `key` when
+unset).
+
+**Themeable custom properties:** `--lr-sequence-strip-height` (default `1.5rem` — the strip's
+block-size), `--lr-sequence-strip-marker-color` (default `var(--lr-color-text)` — the
+`[part="marker"]` fill, and of the marker legend row's bar), `--lr-sequence-strip-legend-swatch-size`
+(default `0.625rem` — a legend swatch's inline- and block-size, category and marker rows alike), and
+`--lr-sequence-strip-legend-marker-bg` (default `var(--lr-color-surface-raised)` — the neutral chip
+background behind the marker legend row's bar; it stands in for "any cell", so it deliberately
+matches no category color); the tooltip also consumes shared tokens
+`--lr-color-surface`, `--lr-color-text`, `--lr-font-size-xs`, `--lr-radius`, and `--lr-shadow`, and
+the legend consumes `--lr-space-2xs`, `--lr-space-xs`, `--lr-space-s`, `--lr-font-size-xs`,
+`--lr-color-text-quiet`, and `--lr-radius-xs`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-sequence-strip></lr-sequence-strip>
+<script>
+  const strip = document.querySelector('lr-sequence-strip');
+  strip.categories = [
+    { key: 'text', color: '#4f46e5', label: 'Text' },
+    { key: 'tool', color: '#16a34a', label: 'Tool' },
+  ];
+  strip.items = [
+    { id: '1', category: 'text', label: 'Turn 1: text' },
+    { id: '2', category: 'tool', marker: true, label: 'Turn 2: tool call' },
+    { id: '3', category: 'text', label: 'Turn 3: text' },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- there is no `lr-cell-click`/keyboard-interaction model at all — unlike `lr-heatmap`'s
+  canvas cells, a strip cell is purely a hover target; build a click handler outside this component
+  (e.g. on a wrapping element) if per-item activation is needed.
+- an `items` entry whose `category` has no matching `categories` entry still renders its own cell
+  (background `transparent`) rather than being dropped, so a strip stays the same length as `items`
+  regardless of `categories` coverage.
+
+---

package/llms/components/lr-skeleton.md

@@ -0,0 +1,53 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-skeleton`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/skeleton/skeleton.js';` (registers the tag; side-effect import)
+- **Class** `LyraSkeleton`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/skeleton/skeleton.class.js`
+- **Family** `components/overlays/` — 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-skeleton`
+
+Loading placeholder (`text`/`circle`/`rect` shapes, `pulse`/`sheen` effects).
+
+**Properties:**
+- `variant: 'text'|'circle'|'rect' = 'text'` (reflected)
+- `effect: 'pulse'|'sheen' = 'pulse'` (reflected)
+- `width?: string`
+- `height?: string`
+- `label: string = 'Loading…'` — accessible name for this instance's own `role="status"` (rendered as
+  visually-hidden text inside `[part="base"]`); override with a description of what's actually
+  loading, e.g. `label="Loading chart"`
+- `announce: boolean = true` (reflected) — set false for decorative members of a skeleton group;
+  removes the status role, live-region state, and visually hidden announcement while preserving
+  the visual placeholder
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `base`
+
+**Themeable custom properties:** `--lr-skeleton-w`, `--lr-skeleton-h` (set/cleared by the
+`width`/`height` properties; default `100%` / `1em`) and shared `--lr-transition-ambient` for
+the pulse/sheen timing.
+
+**Optional peer deps:** none.
+
+```html
+<lr-skeleton variant="circle" width="3rem" height="3rem"></lr-skeleton>
+<lr-skeleton variant="text" label="Loading name"></lr-skeleton>
+```
+
+**Known gotchas:**
+- Each instance announces by default. In a repeated skeleton layout, provide one parent status and
+  set `announce="false"` on the decorative child placeholders to avoid duplicate announcements.
+- no `lines`/`count` shorthand for "N lines of skeleton text" — stamp out N elements
+  yourself.
+- Respects `prefers-reduced-motion` (both effects) — safe to leave as-is for that concern.
+
+---

package/llms/components/lr-slider.md

@@ -0,0 +1,92 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-slider`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/slider/slider.js';` (registers the tag; side-effect import)
+- **Class** `LyraSlider`, also available unregistered from `@aceshooting/lyra-ui/components/forms/slider/slider.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-slider`
+
+A numeric range control (e.g. an LLM "temperature" setting). **Form-associated** via the shared
+`FormAssociated` mixin (`name`, `value`, `disabled`, `required` all inherited). Mirrors native `<input
+type="range">` semantics: `value` is the string form-submitted via the mixin, `valueAsNumber` is the
+ergonomic numeric accessor (matching native `<input type=range>`'s IDL attribute of the same name) kept
+in sync with it in both directions. Clicking anywhere on `[part="base"]` (not just the thumb) jumps the
+thumb to that point and continues the same gesture as a drag, matching native `<input type=range>`
+click-to-seek — the thumb is also `.focus()`ed on that click, so keyboard interaction can continue
+seamlessly right after. First-party invention (no Web Awesome equivalent).
+
+**Properties:**
+- `min: number = 0`
+- `max: number = 100`
+- `step: number = 1`
+- `label: string = ''` — accessible name set as `aria-label` on the `role="slider"` thumb; a plain
+  `aria-label` attribute on the host itself is honored as a fallback when this is left unset (matching
+  `<lr-checkbox>`/`<lr-switch>`).
+- `showValue: boolean = true` (attribute `show-value`) — whether to render the current numeric value as
+  visible text next to the track. Not reflected; toggle it off via the `.showValue=${false}` property
+  binding — a bare `show-value="false"` content attribute is still truthy, since presence is all Lit's
+  default boolean converter checks.
+- Inherited from `FormAssociated`: `name: string = ''`, `value: string` (form-submitted string form),
+  `disabled: boolean = false` (reflected), `required: boolean = false` (reflected).
+
+**Accessor:** `valueAsNumber: number` — get/set. Reading always returns a finite, clamped, step-snapped
+number, even if `value` is momentarily `""` (e.g. right after `form.reset()`, before the mount-time
+default reseeds it), by falling back to the midpoint of `[min, max]`. Writing clamps/snaps the input and
+stringifies the result back into `value`.
+
+**Events:** `lr-input` (`detail: { value: number }` — fired continuously during an active drag or a
+keyboard step, including OS key-repeat while a key is held, mirroring native `<input type=range>`'s
+`input` event), `lr-change` (`detail: { value: number }` — fired once an interaction commits: on
+pointerup for a drag, or on keyup for a keyboard step, so a single Arrow/Home/End/PageUp/PageDown press
+fires both `lr-input` and `lr-change`, mirroring native `<input type=range>`'s own `change`-on-every-
+committed-step behavior)
+
+**Slots:** none.
+
+**CSS parts:** `base` (row wrapping the track and optional value readout), `track`, `fill` (filled
+portion from `min` up to the current value), `thumb` (`role="slider"`), `value` (numeric readout, shown
+when `show-value` is true)
+
+**Themeable custom properties:** shared tokens only — `--lr-space-s`,
+`--lr-color-border/-brand/-surface/-text-quiet`, `--lr-shadow`,
+`--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-slider
+  name="temperature"
+  min="0"
+  max="2"
+  step="0.1"
+  label="Temperature"
+  .valueAsNumber=${0.7}
+  @lr-input=${(e) => setDraftTemperature(e.detail.value)}
+  @lr-change=${(e) => commitTemperature(e.detail.value)}
+></lr-slider>
+```
+
+An unset `value` is eagerly defaulted — on connect, and again after `form.reset()` — to the midpoint of
+`[min, max]` snapped to `step`, the same "range sanitization algorithm" default a native range input
+applies. A slider therefore always represents *some* number, so `required` only has a narrow window to
+block submission before that default lands, matching how `required` isn't a meaningful constraint on a
+native range input either.
+
+**Known gotchas:**
+- `valueAsNumber` always returns a real, clamped number — never `NaN` or `""` — even reading it in the
+  brief window right after a `form.reset()`.
+- Under `direction: rtl`, physical ArrowRight/ArrowLeft swap which one counts as "forward" (increasing
+  value); ArrowUp/ArrowDown are never swapped, since direction only affects the horizontal inline axis.
+- Changing `min`/`max`/`step` after mount automatically re-clamps/re-snaps the current `value` in the
+  next update — narrowing the domain can silently move the slider's value.
+- A pointer drag fires `lr-input` continuously and a single `lr-change` on release; a keyboard step
+  fires exactly one of each per press, but OS key-repeat while a key is held re-fires `lr-input` on
+  every repeat while still only committing `lr-change` once, on the eventual keyup.
+
+---

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

@@ -0,0 +1,144 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-source-card`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/source-card/source-card.js';` (registers the tag; side-effect import)
+- **Class** `LyraSourceCard`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/source-card/source-card.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-source-list` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-source-list` / `lr-source-card`
+
+A collapsible "Sources" panel for one chat message (`lr-source-list`) that groups a set of
+`lr-source-card` entries. First-party invention (no Web Awesome equivalent). Cards are meant to be
+direct light-DOM children of the list (plain composition — no `.items` array prop, the same shape
+`<lr-split>`'s panels take), though `lr-source-card` renders and functions fine standalone.
+
+### `lr-source-list`
+
+**Properties:**
+- `expanded: boolean = false` (reflected) — whether the card list is currently shown. Starts
+  collapsed by default so a message's sources don't eat vertical space until asked for.
+- `label: string = ''` — header text used when `label-plural` isn't set, e.g. `"Sources"`.
+- `labelPlural: string = ''` (attribute `label-plural`) — fully consumer-built, already-pluralized
+  header summary, e.g. `"3 sources"` or `"1 source"`; this component never counts or pluralizes on
+  its own. Takes precedence over `label` when both are set. If neither is set, the header falls back
+  to the literal word `"Sources"`.
+
+**Getters:** `sourceCount: number` — read-only, live-updated count of the currently-slotted children,
+handy for building a `label-plural` string reactively, e.g. `` list.labelPlural = `${list.sourceCount} sources` ``.
+
+**Events:** `lr-toggle` (`detail: { expanded: boolean }`) — the header was activated, expanding or
+collapsing the list.
+
+**Slots:** default — `<lr-source-card>` elements (or any content, though the card pairing is the
+intended usage).
+
+**CSS parts:** `base` (outer container), `header` (the clickable `<button>` toggling `expanded`),
+`toggle` (the chevron indicator inside the header), `list` (wrapper around the default slot, `hidden`
+while collapsed).
+
+**Themeable custom properties:** shared tokens only — `--lr-color-border`, `--lr-color-surface`,
+`--lr-color-text`, `--lr-color-brand` / `-brand-quiet`, `--lr-radius`, `--lr-space-xs`/`-s`/
+`-m`, `--lr-transition-fast`, `--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+### `lr-source-card`
+
+**Properties:**
+- `sourceId: string = ''` (attribute `source-id`) — stable identifier matching a
+  `<lr-citation-badge>` elsewhere on the page.
+- `title: string = ''` — the source's display title, e.g. a filename. Falls back to `"Untitled
+  source"` when empty.
+- `page?: string | number` — optional page reference, e.g. `12` or `"iv"`, rendered as-is (never
+  parsed/validated as a number), appended to the title as `" — p. {page}"`.
+- `href?: string` — optional URL, echoed back (unopened) in `lr-open`'s detail.
+- `compact: boolean = false` (reflected) — tighter root padding and row gap, for the dense citation
+  lists these cards usually render in — the same convention as `lr-empty`'s `compact`. Purely a
+  density knob: the border and background stay. `false` (the default) keeps the full card padding.
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring `lr-card`'s
+  `appearance` vocabulary. `'card'` (the default) keeps the bordered, filled, padded box; `'plain'`
+  removes the border, background, padding and corner radius, so a card inside a `<lr-source-list>`
+  (or any container already drawing its own border/dividers) doesn't double the frame. `plain` wins
+  over `compact` when both are set — nothing left to tighten. The title and toggle keep their brand
+  color and hover underline under `plain`, since neither ever depended on the card chrome.
+
+**Events:**
+- `lr-expand` (`detail: { sourceId: string; expanded: boolean }`) — the per-card "Show
+  more"/"Show less" toggle was activated. Unrelated to the parent `lr-source-list`'s own
+  expand/collapse, which only ever hides/shows the *set* of cards, never a single card's own content.
+- `lr-open` (`detail: { sourceId: string; href?: string }`) — the title was activated. This
+  component never navigates on its own (a controlled component, the same convention
+  `<lr-tool-call-chip>`'s `lr-tool-call-chip-select` follows); a listener decides what "open"
+  means.
+
+**Slots:** `excerpt` (a short preview; when left empty, the `excerpt` part collapses away entirely —
+its wrapper is `hidden`, not just visually empty), `full` (the complete source text/chunk, hidden
+behind the "Show more"/"Show less" toggle — when left empty, no toggle renders at all; removing all
+`full`-slotted content while expanded auto-collapses it back).
+
+**CSS parts:** `base` (outer container), `title` (the clickable title/page heading, a `<button>`),
+`excerpt` (wrapper around the `excerpt` slot, `hidden` when the slot has no assigned content), `full`
+(wrapper around the `full` slot, `hidden` while collapsed), `toggle` (the "Show more"/"Show less"
+button — only rendered when the `full` slot has content).
+
+**Themeable custom properties:** `--lr-source-card-compact-padding` (default `var(--lr-space-xs)`) —
+`[part='base']`'s padding while `compact`; `--lr-source-card-compact-gap` (default
+`var(--lr-space-2xs)`) — the gap between `[part='base']`'s rows while `compact`. Both apply only in
+the `compact` state, so a dense citation list can be tuned without re-pointing shared spacing tokens
+elsewhere. Plus shared tokens — `--lr-color-border`, `--lr-color-surface`,
+`--lr-color-text` / `-text-quiet`, `--lr-color-brand`, `--lr-radius`, `--lr-space-xs`/`-s`,
+`--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-source-list label-plural="2 sources">
+  <lr-source-card source-id="doc-1" title="annual_report.pdf" page="12">
+    <span slot="excerpt">Revenue grew 12% year over year...</span>
+    <span slot="full">Revenue grew 12% year over year, driven primarily by...</span>
+  </lr-source-card>
+  <lr-source-card source-id="doc-2" title="q3_notes.md">
+    <span slot="excerpt">No matching full-text chunk for this source.</span>
+  </lr-source-card>
+</lr-source-list>
+<script type="module">
+  // Elsewhere, a <lr-citation-badge>'s activation handler can scroll to and
+  // highlight the matching card -- neither component needs extra API surface
+  // for that, only source-id to be targeted by:
+  document.addEventListener('lr-citation-activate', (e) => {
+    const card = document.querySelector(`lr-source-card[source-id="${e.detail.sourceId}"]`);
+    card?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+  });
+</script>
+```
+
+`lr-source-list` removes the card list from the accessibility tree (not just visually hides it)
+while collapsed, via the native `hidden` attribute on `[part="list"]` — a screen reader user tabbing
+past the header never lands on off-screen source cards they can't currently see. Both components
+track slot presence in JS state (`slottedCount` on the list, `hasFullSlot` on the card) rather than
+relying on CSS `:empty`, since a `[part]` wrapper always contains a literal `<slot>` child regardless
+of assigned content; both also reconcile that state in `firstUpdated()` as a fallback for slot-
+forwarding scenarios or engines that don't fire `slotchange` for content already present at parse
+time.
+
+**Known gotchas:**
+- This library has no built-in i18n/pluralization (the same stance `<lr-empty>`'s plain
+  `description` prop takes) — `lr-source-list`'s header text is entirely consumer-supplied via
+  `label`/`label-plural`; there's no automatic "N sources" string generation beyond the literal
+  `"Sources"` fallback.
+- `lr-source-card`'s own expand/collapse (`full` slot, `lr-expand` event) is completely
+  independent of the parent list's `expanded`/`lr-toggle` — collapsing the list doesn't reset an
+  individual card's `fullExpanded` state, and there is no cross-talk between the two components at
+  all beyond DOM nesting.
+- `lr-source-card` actively strips a bare host-level `title` attribute right after Lit syncs it into
+  the `title` property — otherwise the whole card would grow an unsolicited native tooltip repeating
+  the title text on hover. Set `title` only as a property/attribute meant to become the rendered
+  heading; don't rely on it surviving as a DOM attribute afterward.
+
+---