@aceshooting/lyra-ui 5.0.0 → 5.1.0

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

@@ -0,0 +1,91 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-swatch-picker`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/swatch-picker/swatch-picker.js';` (registers the tag; side-effect import)
+- **Class** `LyraSwatchPicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/swatch-picker/swatch-picker.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-swatch-picker`
+
+A single-select picker over a small, fixed set of color swatches 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. First-party invention (no Web Awesome equivalent). Distinct from
+`lr-color-picker`'s freeform native color input — this picks exactly one of N designer-chosen
+named colors, the shape apps otherwise hand-roll as a row of round accent-color buttons.
+
+**Properties:**
+- `options: SwatchOption[] = []` (attribute: false) — `SwatchOption { value: string; color: string;
+  label: string; icon?: unknown }`; `color` is any CSS color string used as the swatch fill, `label`
+  is each swatch's accessible name and `title`. `icon` is an optional custom shape (e.g. a gem
+  glyph) rendered *instead of* the plain filled circle; the swatch sets `color: <option color>` so a
+  `currentColor`-based SVG picks the option's color up automatically, matching
+  `<lr-segmented>`'s `SegmentedItem.icon`.
+- `value: string | null = null` — the currently selected option's `value` (controlled); `null`
+  leaves nothing selected while keeping the first swatch tabbable.
+- `label: string = ''` — accessible name copied to the internal `role="radiogroup"`; when empty, a
+  host-level `aria-label` is used as a fallback.
+
+**Events:** `lr-change` (`detail: { value }`) — fired only when the selected value actually
+changes via click or keyboard (re-selecting the current swatch is a no-op).
+
+**Slots:** none.
+
+**CSS parts:** `base` (the `role="radiogroup"` root), `swatch` (a single `role="radio"` color
+swatch's interactive hit target, floored at the shared `--lr-icon-button-size` tap size; the
+selected one is `[part='swatch'][aria-checked='true']`), `swatch-fill` (the compact
+`--lr-size-1-5rem` filled circle inside it, rendered when the option has no `icon`), `swatch-icon`
+(the option's `icon` shape, rendered in its place when it has one). Exactly one of
+`swatch-fill`/`swatch-icon` is mounted per swatch, so the two never coexist.
+
+**Themeable custom properties:** `--lr-swatch-picker-selected-color` (ring color around the
+selected swatch, defaults to `--lr-color-brand`, themeable independently of the focus ring),
+`--lr-swatch-picker-selected-blur` (default `0` — a crisp ring; set a real length such as `0.4rem`
+for a soft glow. It is the blur radius of `swatch-fill`'s `box-shadow` ring, and of the equivalent
+`drop-shadow()` used for `swatch-icon`, since `box-shadow` can't follow a slotted icon's real
+shape), `--lr-swatch-picker-shine-duration` (default `0s`, a no-op; set a duration such as `1.6s`
+for a looping brighten-and-settle pulse on the selected swatch. It drives a separate
+`filter: brightness()` keyframe rather than `box-shadow`, so it composes with the blur token and
+works identically for a fill and an icon; disabled outright under `prefers-reduced-motion: reduce`,
+which also drops the hover/selection scale transition); plus
+shared tokens — `--lr-color-border`/`-brand`, `--lr-icon-button-size`, `--lr-space-xs`,
+`--lr-size-1-5rem`, `--lr-border-width-thin`/`-thick`, `--lr-radius`, `--lr-transition-fast`,
+`--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-swatch-picker label="Accent color"></lr-swatch-picker>
+<script type="module">
+  const picker = document.querySelector('lr-swatch-picker');
+  picker.options = [
+    { value: 'blue', color: '#0969da', label: 'Blue' },
+    { value: 'green', color: '#1a7f37', label: 'Green' },
+    { value: 'purple', color: '#8250df', label: 'Purple' },
+  ];
+  picker.value = 'green';
+  picker.addEventListener('lr-change', (e) => console.log(e.detail.value));
+</script>
+```
+
+**Known gotchas:**
+- arrow-key navigation cycles (past the last swatch wraps to the first, and vice versa) rather than
+  clamping, and self-selects on move — arrow-navigating to a swatch immediately updates `value` and
+  fires `lr-change`, there's no separate commit step.
+- under RTL (nearest `dir="rtl"` ancestor) `ArrowLeft`/`ArrowRight` swap which direction they move.
+- each swatch's fill comes from its option's `color`, applied through a per-swatch custom property
+  set inline on `[part='swatch']` and read by `[part='swatch-fill']`, so a consumer's
+  `::part(swatch-fill)` `background-color` rule can still override it.
+- style the selected state through `--lr-swatch-picker-selected-color`/`-selected-blur`/
+  `-shine-duration`, not through `::part(swatch)[aria-checked='true']` from outside: the CSS Shadow
+  Parts spec only allows a fixed set of pseudo-classes after `::part()`, not arbitrary attribute
+  selectors, so that combinator can silently fail to match depending on the engine.
+- 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-switch.md

@@ -0,0 +1,82 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-switch`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/switch/switch.js';` (registers the tag; side-effect import)
+- **Class** `LyraSwitch`, also available unregistered from `@aceshooting/lyra-ui/components/forms/switch/switch.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-switch`
+
+A boolean toggle-switch form control. `role="switch"` with `aria-checked` read as an on/off state
+rather than checked/unchecked, and no indeterminate state. Structurally the same idea as
+`<lr-checkbox>` (form-associated via `ElementInternals`, click and Space/Enter both toggle).
+Ships an opt-in `hint`/`errorText` form-control chrome (props + matching named slots + `hint`/`error`
+CSS parts), mirroring `<lr-select>`'s pattern for those two pieces — left unset, neither renders.
+Deliberately no separate top-of-field `label` prop/slot/part: the default slot already is this
+control's visible, clickable label (same as `<lr-checkbox>`).
+
+**Properties:**
+- `checked: boolean = false` (reflected)
+- `disabled: boolean = false` (reflected)
+- `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
+- `name: string = ''`
+- `value: string = 'on'` — only contributed to form submission while `checked`
+- `hint: string = ''` — hint text below the switch. Unset: no hint chrome renders.
+- `errorText: string = ''` (attribute `error-text`) — error text below the switch (overridden by
+  slotted `error` content). Unset: no error chrome renders.
+
+**Events:** `lr-change` (`detail: { checked: boolean }`) — fired on a user toggle (click or
+Space/Enter); not fired for a programmatic `.checked` assignment.
+
+**Methods:** `focus(options?)` and `blur()` forward to the internal switch control.
+
+**Slots:**
+- default — label text, rendered next to the track. Clicking it toggles the switch, the same as
+  clicking a checkbox's associated `<label>`. If left empty, set `aria-label` on the host so the
+  control still has an accessible name.
+- `hint` — custom hint content.
+- `error` — custom error content.
+
+**CSS parts:** `form-control` (the outer wrapper around the switch, error and hint), `base` (the
+whole interactive control, `role="switch"`), `track` (the pill-shaped background), `thumb` (the
+circular knob that slides across the track), `label` (wrapper around the default slot), `hint` (the
+hint message), `error` (the error message)
+
+**Themeable custom properties:** `--lr-switch-track-inline-size` (default `2.25rem`),
+`--lr-switch-track-block-size` (default `1.25rem`), `--lr-switch-thumb-offset` (default
+`2px`) — component-local geometry knobs, set on `:host`, since a fully-rounded pill/thumb needs
+a radius well past the shared `--lr-radius` default — plus shared tokens
+`--lr-space-s`, `--lr-color-border/-brand/-surface/-text`,
+`--lr-transition-fast`, `--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-switch name="notifications" checked>Enable notifications</lr-switch>
+<script type="module">
+  document
+    .querySelector('lr-switch')
+    .addEventListener('lr-change', (e) => console.log(e.detail.checked));
+</script>
+```
+
+Form-associated the same way as `<lr-checkbox>`: a directly-attached `ElementInternals` with a
+hand-rolled `updateValidity()`, not the shared `FormAssociated` mixin. The thumb animates the
+logical `inset-inline-start` property (not a physical `transform: translateX()`), so the slide
+direction mirrors correctly under `dir="rtl"`.
+Session-history/autofill restoration uses the same explicit `checked`/`unchecked` state tokens as
+checkbox and does not emit `lr-change`.
+
+**Known gotchas:**
+- `formResetCallback()` restores `checked` to the value captured from the declarative `checked`
+  attribute at first connect (same one-shot-flag capture as `<lr-checkbox>`) — a later `.checked =
+  true` property assignment never redefines what `form.reset()` restores to.
+- The rendered `aria-label` is copied from the host's own `aria-label` attribute at render time; with
+  neither that nor slotted label text, the control has no accessible name.
+
+---

package/llms/components/lr-table.md

@@ -0,0 +1,201 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-table`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/table/table.js';` (registers the tag; side-effect import)
+- **Class** `LyraTable`, also available unregistered from `@aceshooting/lyra-ui/components/data/table/table.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-table`
+
+Sort/select-aware data table. Sorting remains consumer-controlled; optional filtering, pagination,
+and loading chrome are built in while remaining controlled at the public API boundary. A
+`columns[].heatValue`-opted-in heat-tint mode paints a shared, normalized color-mix background across
+every tinted cell (auto-derived domain, or overridden via `heatTintScale`); `rowTotal`/`grandTotal`
+add a trailing totals column mirroring `expandedContent`'s leading one — `rowTotal(row)` renders
+per-row, `grandTotal(rows)` renders at its intersection with the footer row — both sharing `footer`'s
+own "consumer computes/renders" contract rather than assuming addition.
+
+**Properties:**
+- `columns: TableColumn<T>[] = []` (attribute: false) — `{ key, label, headerCell?, width?,
+  minWidth?, maxWidth?, resizable?, sortable?, align?: 'start'|'end', priority?: 'medium'|'low', sticky?: boolean |
+  'start' | 'end', footer?, cellStyle?, heatValue?, cell: (row) => unknown }` —
+  `priority` progressively hides that column via a `@container` query as `[part='base']` narrows
+  (`'low'` hides first, under a ~900px container width; `'medium'` next, under ~640px; both
+  breakpoints are fixed in `table.styles.ts`, not themeable tokens), reversible via
+  `[part='reveal-columns-button']`; `sticky` pins that column's header/cells to the logical start
+  (`true`/`'start'`) or end edge while the table scrolls horizontally — multiple sticky columns stack
+  in logical order (each measures every earlier sticky column's rendered width via
+  `--lr-table-sticky-offset`) instead of overlapping at the same edge; `footer` renders a
+  sticky-bottom footer cell for that column, computed from every currently-rendered row (post-sort,
+  pre-pagination) — e.g. a column total — omit it for a column with no footer value, and a
+  `[part='foot']` (`<tfoot>`) only renders at all when at least one column defines `footer`;
+  `heatValue(row) => number | null | undefined` opts a column into heat-tint mode: its presence on
+  any column is the opt-in signal (no separate boolean), a `null`/`undefined` return excludes that
+  cell from both the domain and the tint ("no data", not "zero"), and every `heatValue`-defining
+  column shares one normalized `color-mix()` background scale (see `heatTintScale` below) painted
+  via the retheme-able `--lr-table-heat-tint-lo`/`-hi` custom properties, matching `lr-heatmap`'s
+  own ramp-token convention; `cellStyle` is applied directly to the generated `<td>` via `styleMap` — e.g. a computed heat-tint
+  background a `cell()`-returned inner element can't paint into the cell's own padding — omit it for
+  no per-cell style override (the default, unchanged output); `editable` enables double-click
+  editing, `editValue` supplies the editor value, and `editType` selects `text` or `number`
+  `resizable` adds a focusable separator `[part='resize-handle']` and emits `lr-column-resize` with
+  the live width in CSS pixels. Drag it, or use logical ArrowLeft/ArrowRight for 10px steps (mirrored
+  under RTL), Shift+Arrow for 50px steps, Home for the minimum, and End for an explicit pixel
+  `maxWidth`; explicit pixel `minWidth`/`maxWidth` values bound both input paths. The separator
+  exposes its current/minimum/bounded-maximum pixel width through ARIA value attributes.
+- `columnsHidden: boolean = false` (attribute `columns-hidden`, reflected) — computed/read-only: true
+  when a `priority` column is *actually* hidden right now by the `@container` breakpoints above, or
+  `showAllColumns` force-visible mode is currently active. Measured via a `ResizeObserver` on
+  `[part='base']` plus a post-render DOM check, so it settles one render cycle after a `columns`/
+  `rows`/width change lands — poll for the settled value (e.g. `await el.updateComplete;` twice, or
+  `waitUntil()`) rather than assuming a single `updateComplete` covers it. Setting it directly has no
+  lasting effect; it's recomputed on the next render or resize. `[part='reveal-columns-button']` now
+  renders exactly when `columnsHidden` is true — no longer whenever any column merely *declares* a
+  `priority` regardless of whether anything is actually hidden
+- `rows: T[] = []` (attribute: false)
+- `sortKey: string = ''` (attribute `sort-key`)
+- `sortDir: 'asc'|'desc' = 'asc'` (attribute `sort-dir`)
+- `rowKey?: (row: T) => string | number` (attribute: false) — derives each row's stable identity for
+  DOM-reconciliation and the delegated row click/keydown lookup; falls back to the row's array index
+  when omitted, which is only safe while `rows` never reorders — set it whenever `rows` can be
+  sorted/filtered/re-ordered across renders, or selection/click can silently attach to the wrong row
+- `selectedKey: string | number | null = null` (attribute: false) — **single**-selection only
+- `selectionMode: 'none'|'single'|'multiple' = 'none'` (attribute `selection-mode`, reflected) —
+  opt-in self-managed row selection; the default remains presentational
+- `selectedKeys: Set<string | number> = new Set()` (attribute: false) — the selected raw row keys
+  used by multiple selection
+- `filterable: boolean = false` (attribute `filterable`, reflected) — renders a localized search
+  field above the grid
+- `filterText: string = ''` (attribute `filter-text`) — controlled filter text
+- `filter?: (row: T, text: string) => boolean` (attribute: false) — typed predicate used by the
+  filter field; when omitted, rows are matched against their JSON representation
+- `filterLabel: string = ''` (attribute `filter-label`) and `filterPlaceholder: string = ''`
+  (attribute `filter-placeholder`) — optional localized-label overrides
+- `spellcheck: boolean = true`, `autocapitalize: string = ''`, `autoCorrect: string = ''`
+  (attribute `autocorrect`) — forwarded to the filter input and, for a `'text'` (the default)
+  `editType`, the inline cell editor; no effect on a `'number'` cell editor. `spellcheck="false"`
+  is parsed as `false` via a string-aware converter (Lit's default presence-based boolean
+  converter would otherwise treat any attribute value, including the literal string `"false"`, as
+  `true`).
+- `loading: boolean = false` (attribute `loading`, reflected) and `loadingLabel: string = ''`
+  (attribute `loading-label`) — renders a busy spinner and suppresses the grid while loading
+- `pageSize: number = 0` (attribute `page-size`) — positive values enable controlled pagination;
+  zero disables the pagination footer
+- `page: number = 1` (attribute `page`, reflected) — controlled current page
+- `totalItems: number = -1` (attribute `total-items`) — server-side total item count; `-1` derives
+  the total from filtered rows
+- `paginationMode: 'client'|'server' = 'client'` (attribute `pagination-mode`, reflected) — client
+  mode slices rows; server mode renders the supplied page unchanged
+- Editable columns emit `lr-cell-edit` on commit and never mutate the supplied row object.
+- `groupBy?: (row: T) => string | number` (attribute: false) — inserts a non-focusable full-width
+  group row before each group
+- `groupLabel?: (key: string | number, rows: T[]) => unknown` (attribute: false) — custom group
+  header content; without it, the group key is rendered as text
+- `expandedContent?: (row: T) => unknown` (attribute: false) — enables a leading expand toggle and
+  renders a full-width detail row beneath expanded records
+- `canExpand?: (row: T) => boolean` (attribute: false) — optional per-row gate for expansion
+- `expandedKeys: Set<string | number> = new Set()` (attribute: false) — consumer-controlled expanded
+  state; update it in response to `lr-row-expand-toggle`
+- `hasMore: boolean = false` (attribute `has-more`, reflected)
+- `moreLabel: string = 'Load more'` (attribute `more-label`)
+- `emptyHeading: string = 'No data'` (attribute `empty-heading`)
+- `emptyDescription: string = ''` (attribute `empty-description`)
+- `noColumnsHeading: string = 'No columns configured'` (attribute `no-columns-heading`)
+- `noColumnsDescription: string = ''` (attribute `no-columns-description`)
+- `revealColumnsLabel: string = 'Show all columns'` (attribute `reveal-columns-label` — the
+  reveal-button's label while `priority`-hidden columns are hidden)
+- `hideColumnsLabel: string = 'Show fewer columns'` (attribute `hide-columns-label` — the same
+  button's label once they've been revealed)
+- `showAllColumns: boolean = false` (attribute `show-all-columns`, reflected) — forces responsive
+  priority columns visible and is updated by the built-in reveal button
+- `heatTintScale?: { min?: number; max?: number }` (attribute: false) — overrides the auto-derived
+  heat-tint domain (min/max of every `heatValue` result across every currently-rendered row —
+  post-sort, pre-pagination, the same rows `footer(rows)` already sees). Unset (the default) computes
+  the domain automatically from the data, spanning every `heatValue`-defining column together — a
+  single shared scale across the whole grid, not one scale per column
+- `rowTotal?: (row: T) => unknown` (attribute: false) — renders a trailing `<td>`
+  (`[part='row-total-cell']`) on every body row holding this row's total. Same "consumer
+  computes/renders, table only positions" contract as the existing per-column `footer(rows)` — does
+  not assume addition, so a non-sum aggregate works identically. Omit for no trailing column at all
+  (unchanged output)
+- `grandTotal?: (rows: T[]) => unknown` (attribute: false) — renders the bottom-right cell (row-total
+  column × footer row). Only rendered when both `rowTotal` is set **and** at least one column defines
+  `footer` — otherwise there is no footer row for it to occupy, and this renders nothing
+
+**Events:** `lr-sort` (`detail: { key }`, fired on sortable-header activation), `lr-row-click`
+(`detail: { row }`), `lr-load-more` (fired on the "load more" button), `lr-columns-hidden-change`
+(`detail: { hidden: boolean }`, fired only on a real `columnsHidden` transition),
+`lr-columns-revealed` (`detail: { revealed: boolean }`), and `lr-row-expand-toggle`
+(`detail: { row, key }`; the table does not mutate `expandedKeys`), and
+`lr-selection-change` (`detail: { keys }`) when selection is enabled, `lr-filter-change`
+(`detail: { text }`), and `lr-page-change` (`detail: { page }`) from the controlled
+filter/pagination surfaces, and `lr-cell-edit` (`detail: { row, key, value }`) for editable
+columns, and `lr-column-resize` (`detail: { key, width }`) on every pointer or keyboard resize step.
+The internal filter/cell-editor native inputs' `focus` and `blur` are also re-dispatched from the
+host as bubbling, composed events (the native ones are neither).
+
+**Slots:** none — content comes entirely from `columns`/`rows`.
+
+**CSS parts:** `base`, `table`, `head`, `header-cell`, `row`, `cell`, `more-button`, `sort-icon` (a
+chevron indicator shown on the active sortable header, rotated per `sortDir`), `reveal-columns-button`
+(shown only when `columnsHidden` is true), `foot` (the `<tfoot>`, only rendered when at least one
+column defines `footer`), `footer-row`, `footer-cell`, `row-total-cell` (each body row's trailing
+`<td>` holding `rowTotal(row)`, rendered only when `rowTotal` is set — the corresponding footer-row
+cell, holding `grandTotal`, is a `footer-cell` instead, matching every other footer cell),
+`expand-toggle-cell`, `row-expand-toggle`,
+`row-expand-icon`, `expanded-row`, `expanded-cell`, `filter-label`, `filter`, `loading`, and
+`pagination`, `cell-editor`, `group-row`, `group-cell`, and `resize-handle` (the focusable column
+separator)
+
+**Themeable custom properties:** `--lr-table-max-height` (default `none`; controls the scrollable
+body's `max-block-size`). `--lr-table-heat-tint-lo` (default `var(--lr-color-brand-quiet)`) and
+`--lr-table-heat-tint-hi` (default `var(--lr-color-brand)`) — the `color-mix()` ramp endpoints
+for heat-tint mode's per-cell background, consulted only on columns/rows that define `heatValue`;
+`--lr-table-resize-min-width` (default `var(--lr-size-3rem)`) and
+`--lr-table-resize-handle-opacity` (default `0.12`) control resizable-column behavior.
+
+**Optional peer deps:** none.
+
+```html
+<lr-table id="t" sort-key="name" sort-dir="asc"></lr-table>
+<script type="module">
+  const t = document.getElementById('t');
+  t.columns = [
+    { key: 'name', label: 'Name', sortable: true, cell: (r) => r.name },
+    { key: 'value', label: 'Value', align: 'end', cell: (r) => r.value },
+  ];
+  t.rows = [{ name: 'Alpha', value: 1 }, { name: 'Beta', value: 2 }];
+  t.rowKey = (r) => r.name;
+  t.addEventListener('lr-sort', (e) => console.log('sort by', e.detail.key));
+  t.addEventListener('lr-row-click', (e) => console.log('clicked', e.detail.row));
+</script>
+```
+
+**Known gotchas:**
+- only single-row selection is modeled (`selectedKey: string | number | null`);
+  there's no bulk-select/checkbox-column API — you must hand-roll a checkbox column entirely inside
+  a `cell()` callback if you need multi-select.
+- no `caption`/`aria-label` *property* exists, but a plain `aria-label` HTML attribute set on the
+  host **is** forwarded into the shadow-DOM `<table role="grid">` (read via
+  `this.getAttribute('aria-label')` at render time — a plain global-attribute read, not a reactive
+  Lit `@property`): `<lr-table aria-label="Scores">` gives the grid an accessible name; omit it and
+  the shadow table simply has none.
+- Full roving-tabindex grid keyboard pattern (one `tabindex="0"` stop among header cells, one among
+  body rows) — Left/Right/Home/End move within the header row, Up/Down/Home/End move within the
+  body, Down from the header enters the body's roving stop and Up from the body's first row returns
+  to the header, Enter/Space still only sort/activate — a genuine strength versus most siblings in
+  this family. A `priority`-hidden header/cell is skipped when computing the visible header stops,
+  so arrow-key navigation never strands the roving stop on a hidden column.
+- a `cell()` template can render its own interactive content without it being swallowed by
+  row/column activation: clicks and Enter/Space landing on (or bubbling through) anything matching
+  `button, a[href], input, select, textarea, [role="button"], [role="combobox"], [role="listbox"],
+  [role="slider"]`, **or any custom element** (any tag name containing a hyphen — e.g. a
+  `<lr-select>`/`<lr-combobox>` rendered inside a `cell()`), are left alone by the table's own
+  delegated `click`/`keydown` handlers instead of triggering `lr-sort`/`lr-row-click`.
+
+---

package/llms/components/lr-tabs.md

@@ -0,0 +1,80 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-tabs`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/tabs/tabs.js';` (registers the tag; side-effect import)
+- **Class** `LyraTabs`, also available unregistered from `@aceshooting/lyra-ui/components/layout/tabs/tabs.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-tabs`
+
+A tab strip whose panels are direct light-DOM children, each carrying `slot="<id>"` (the panel's
+stable id) and `label="<text>"` (the tab button's text). One named `<slot>` is rendered per distinct
+`slot` name found among the current children — a child with no `label`, or a name with no matching
+child, simply never produces a tab. Implements the WAI-ARIA APG tabs pattern with automatic
+activation: Left/Right (swapped under RTL) move focus *and* selection together, Home/End jump to the
+first/last enabled tab, and a roving `tabindex` follows whichever tab is currently selected.
+
+A tab button's *visible* content can carry a leading icon without ever changing its *accessible
+name* (always exactly `label`'s text): give a tab an extra direct-child sibling of `<lr-tabs>`
+carrying `slot="<id>-icon"` (that sibling's own content — inline SVG, emoji span, a custom icon
+element, anything — is entirely up to the consumer). It renders ahead of the label inside that tab's
+button, wrapped in an `aria-hidden="true"` `[part="tab-icon"]` so it's excluded from accessible-name
+computation regardless of content. A tab with no matching `<id>-icon` sibling renders no icon
+wrapper at all, so existing text-only tabs are unaffected.
+
+**Properties:**
+- `active: string = ''` (reflected) — the active tab's `slot`/id; falls back to the first enabled
+  tab whenever the current value doesn't resolve to one (including on every children/attribute
+  change, tracked via a `MutationObserver`)
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name applied to the
+  `role="tablist"` strip; attribute-reflects from a host-level `aria-label`. Unset, the tablist
+  renders without an `aria-label` (there is no localized default name).
+
+**Events:** `lr-tabs-change` (`detail: { tabId: string }`) — fired when the active tab changes via
+click or keyboard. Not fired when `active` self-corrects to a valid tab (initial default, or a tab
+disappearing/becoming disabled underneath the current selection).
+
+**Slots:** default — direct children with `slot="<id>" label="<text>"` (and optionally `disabled`);
+one becomes each tab's panel. `<id>-icon` — optional sibling direct child supplying a tab's leading
+icon content; excluded from the tab button's accessible name.
+
+**CSS parts:** `base` (root wrapper around the tablist and panels), `tablist` (the `role="tablist"`
+row of tab buttons), `tab` (a single tab button), `tab-icon` (the optional leading-icon wrapper
+inside a tab button; only rendered when that tab has a matching `<id>-icon` sibling), `panel` (a
+single `role="tabpanel"` wrapper, one per tab, hidden unless active)
+
+**Themeable custom properties:** `--lr-scroll-fade-size` (default `2rem`) — width of the static
+mask fade at each horizontal scroll edge of the tablist. Otherwise shared tokens —
+`--lr-space-xs/-s/-m`, `--lr-color-border/-text-quiet/-text/-brand`, `--lr-transition-fast`,
+`--lr-radius`, `--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-tabs active="general">
+  <div slot="general" label="General">General settings…</div>
+  <div slot="advanced" label="Advanced" disabled>Advanced settings…</div>
+</lr-tabs>
+<script type="module">
+  document.querySelector('lr-tabs').addEventListener('lr-tabs-change', (e) => console.log(e.detail.tabId));
+</script>
+```
+
+**Known gotchas:**
+- Tabs are rebuilt from direct children via a `MutationObserver` watching `childList` plus
+  `attributeFilter: ['slot', 'label', 'disabled']` — not `slotchange` — because a brand-new tab's
+  `slot` name has no matching `<slot>` to fire `slotchange` on until this component has already
+  rendered one for it, and neither `slotchange` nor any Lit lifecycle hook observes a plain
+  attribute edit on a light-DOM child at all.
+- If two children share the same `slot` name, the *first* one wins for the tab button's label
+  (matches native slot assignment: both would render into the one panel, but only one label can back
+  the button).
+- Left/Right are swapped under RTL (read via `internal/rtl.ts`'s `isRtl()`); Up/Down are not used —
+  this is a horizontal strip only.
+
+---

package/llms/components/lr-tag.md

@@ -0,0 +1,25 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-tag`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/badge/tag.js';` (registers the tag; side-effect import)
+- **Class** `LyraTag`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/badge/tag.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-badge` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-badge` and `lr-tag`
+
+Compact status labels. Both expose `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger'`.
+The two tags share the same visual contract; `lr-tag` is a semantic alias for migration-friendly
+markup.
+
+**Slots:** default content. **CSS parts:** `base`.
+
+**Themeable custom properties:** `--lr-badge-background`, `--lr-badge-color`, `--lr-badge-border`
+— the trio each `:host([variant])` rule rewrites (`neutral` defaults to
+`--lr-color-surface`/`-text`/`-border`; the other four to the matching `*-quiet` fill with the loud
+color for text and border). Set one directly on the element for a tint outside the five variants.

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

@@ -0,0 +1,42 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-task-list`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/task-list/task-list.js';` (registers the tag; side-effect import)
+- **Class** `LyraTaskList`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/task-list/task-list.class.js`
+- **Family** `components/agent-tools/` — 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-task-list`
+
+A live, collapsible tracker for an agent's plan: ordered steps with per-step lifecycle status and one
+level of nested sub-steps, embedded in the transcript. `items` is controlled and never mutated by this
+component. Unlike `<lr-stepper>`'s single-`current` navigation, task-list is a read-only status
+report: several steps may be `running` at once, there is no selection, and status changes are
+announced through an internal `<lr-live-region>`.
+
+**Properties:** `items: TaskItem[] = []` (attribute: false) — `TaskItem { id: string; label: string;
+status: TaskStatus; detail?: string; children?: TaskItem[] }` with `TaskStatus = 'pending' |
+'running' | 'success' | 'error'` (both exported here). `detail` is an optional secondary plain-text
+line; `children` is exactly **one** level of sub-steps — a child's own `children` is ignored with a
+`console.warn`. `label: string = 'Tasks'`, `expanded: boolean = true` (reflected), and
+`collapsible: boolean = true`.
+
+**Slots:** `detail-<id>` — dynamic, one per item id (e.g. `slot="detail-step-3"`); rich detail under
+that item's label, typically a `<lr-tool-call-chip>` or file `<lr-chip>`.
+
+**Events:** `lr-toggle` — the header was activated, expanding or collapsing the panel. `detail: {
+expanded }`.
+
+**CSS parts:** `base`, `header` (a `<button>` when `collapsible`, a plain heading otherwise), `label`,
+`summary` (the visible "N of M completed" summary, top-level items only), `toggle` (the chevron
+indicator, only rendered when `collapsible`), `body` (the list of items, `hidden` while collapsed),
+`item` (`role="listitem"`; carries `data-status`/`data-id`/`data-depth`), `status-icon`, `item-label`,
+`item-detail`, and `item-children` (the nested `role="list"` wrapper around a top-level item's
+children).
+
+**Themeable custom properties:** `--lr-task-list-spin` (default `1s linear`) — running-status icon
+spin animation duration/timing.

package/llms/components/lr-terminal.md

@@ -0,0 +1,44 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-terminal`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/terminal/terminal.js';` (registers the tag; side-effect import)
+- **Class** `LyraTerminal`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/terminal/terminal.class.js`
+- **Family** `components/agent-tools/` — 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-terminal`
+
+A read-only ANSI console for streamed agent/tool output. Not a PTY: no stdin/keystroke handling, no
+cursor-addressed full-screen apps.
+
+**Properties:** `content: string = ''` — initial/replaceable buffer content, parsed for ANSI/SGR
+codes. `maxScrollback: number = 5000` (attribute `max-scrollback`), `follow: boolean = true`
+(reflected) — stick-to-bottom, `wrap: boolean = true` (reflected), `copyable: boolean = true`
+(reflected) and `downloadable: boolean = false` (reflected) toggle the toolbar buttons, `filename:
+string = 'terminal.log'`, `announceOutput: boolean = false` (attribute `announce-output`),
+`accessibleLabel: string = ''` (attribute `aria-label`), `highlights: LyraHighlight[] = []` (attribute:
+false), and `activeHighlightId: string | null = null` (attribute: false). `anchorKinds` is a readonly
+`['page', 'text-quote', 'region']` for the shared anchor-target contract.
+
+**Methods:** `write(text)` appends ANSI-parsed text to the buffer. `clear()` empties the buffer.
+`scrollToBottom()` and `scrollToAnchor(anchor)` control scroll position. `search(query)`,
+`searchNext()`, `searchPrevious()`, and `clearSearch()` drive in-buffer text search. `getPlainText()`
+returns the SGR-stripped plain text of the whole buffer.
+
+**Events:** `lr-copy` (`detail: { text }`), `lr-download` (`detail: { filename }`),
+`lr-follow-change` (`detail: { following }`), `lr-search-change` (`detail: { query, matchCount,
+activeIndex }`), `lr-highlight-activate` (`detail: { id }`), and `lr-text-select` (`detail: {
+text, anchor, rects }`).
+
+**CSS parts:** `base`, `toolbar` (only rendered when copy/download are enabled), `copy-button`,
+`download-button`, `viewport` (the `role="log"` scrollable region), `line` (one rendered line; carries
+`data-line-number`/`data-match`/`data-highlight-tone`), `jump-to-latest` (shown while `follow` is
+disengaged and new output has arrived), and `announcer` (the visually-hidden `role="status"` region
+used when `announce-output` is set).
+
+**Themeable custom properties:** `--lr-terminal-height` (default `var(--lr-size-20rem)`) — the
+viewport's block size.

package/llms/components/lr-test-results.md

@@ -0,0 +1,38 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-test-results`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/test-results/test-results.js';` (registers the tag; side-effect import)
+- **Class** `LyraTestResults`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/test-results/test-results.class.js`
+- **Family** `components/agent-tools/` — 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-test-results`
+
+A pass/fail suite summary with per-status counts, status filter toggles, and per-test rows whose
+failures auto-expand by default and can host rich slotted detail (e.g. a diff or code block)
+alongside the plain failure message.
+
+**Properties:** `suites: TestSuiteResult[] = []` (attribute: false) — `TestSuiteResult { id: string;
+name: string; tests: TestCaseResult[] }` and `TestCaseResult { id: string; name: string; status:
+TestStatus; durationMs?: number; message?: string }`, with `TestStatus = 'passed' | 'failed' |
+'skipped' | 'running'` (all three exported here). `statusFilter: TestStatus[] =
+[]` (attribute: false) — empty shows every status; and `autoExpandFailures: boolean = true`
+(attribute `auto-expand-failures`).
+
+**Slots:** `detail-{testId}` — rich failure detail for that test, rendered after its plain `message`
+text once the row is expanded.
+
+**Events:** `lr-test-select` (`detail: { suiteId: string; testId: string }`, a test row's name was
+activated), `lr-filter-change` (`detail: { statuses: TestStatus[] }` — the complete next filter set; the
+component updates its own `statusFilter` first, then emits),
+and `lr-toggle` (`detail: { id: string; expanded: boolean }`, a row's failure detail was
+expanded/collapsed).
+
+**CSS parts:** `base`, `summary` (the status-count strip), `count` (carries `data-status`), `filter`,
+`filter-toggle` (carries `data-status`/`aria-pressed`), `suite`, `suite-header`, `test` (carries
+`data-status`), `test-status`, `test-name`, `test-duration`, `test-expand-toggle`, `failure`
+(hidden while collapsed), and `failure-message`.