@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-suggestion-chips.md

@@ -0,0 +1,49 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-suggestion-chips`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/suggestion-chips/suggestion-chips.js';` (registers the tag; side-effect import)
+- **Class** `LyraSuggestionChips`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/suggestion-chips/suggestion-chips.class.js`
+- **Family** `components/conversation/` — 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-suggestion-chips`
+
+Starter prompts (empty thread) and follow-up suggestions (after a response) as a horizontally
+scrollable chip row; activation hands the prompt to the host, which decides whether to compose it
+into an input or send it directly. Never writes into a composer or sends anything itself.
+Streaming-friendly: chips render through a keyed `repeat()` on `id`, so replacing follow-ups
+mid-conversation preserves focus on any chip whose `id` survives.
+
+**Properties:** `suggestions: ChatSuggestion[] = []` (attribute: false) — `ChatSuggestion { id:
+string; label: string; detail?: string }` (exported here); `detail` is an optional secondary line.
+Empty renders nothing at all. `wrap: boolean = false`
+(reflected) — wraps into multiple rows instead of a single horizontally scrollable line. `label:
+string = ''` — accessible name for the group, defaults to the localized `suggestionsLabel`.
+
+**Events:** `lr-suggestion-select` — `detail: { id, label }`.
+
+**CSS parts:** `base` (the labeled group), `chip` (each suggestion button), `chip-label` (the primary
+text), `chip-detail` (the secondary line, only rendered when `detail` is set).
+
+**Themeable custom properties:** `--lr-suggestion-chips-hover-bg` (default
+`var(--lr-color-brand-quiet)`) — a `chip`'s background on hover. `--lr-suggestion-chips-hover-border`
+(default `var(--lr-color-brand)`) — a `chip`'s border color on hover. Both are declared as `var()`
+fallbacks at the point of use, not on `:host`. Plus shared tokens `--lr-space-xs/-m/-2xs`,
+`--lr-color-border/-surface/-text/-text-quiet`, `--lr-radius-pill`, `--lr-font-size-xs`,
+`--lr-focus-ring-width/-color/-offset`.
+
+**Optional peer deps:** none.
+
+Keyboard: roving tabindex across chips; ArrowLeft/ArrowRight (direction-aware) plus Home/End;
+Enter/Space activate. Renders inside an internal `lr-scroller` (`orientation="horizontal"`,
+`hide-scrollbar`) unless `wrap` is set.
+
+```html
+<lr-suggestion-chips .suggestions=${followUps}
+  @lr-suggestion-select=${(e) => (composer.value = e.detail.label)}></lr-suggestion-chips>
+<lr-chat-composer></lr-chat-composer>
+```

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

@@ -0,0 +1,55 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-svg-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/svg-viewer/svg-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraSvgViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/svg-viewer/svg-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-svg-viewer`
+
+Fetches an SVG document, sanitizes it with the optional `dompurify` peer, and renders it inline.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `maxHeight` caps
+the scrollable body. `zoomable: boolean = false` (reflected) — wraps the rendered content in an
+internal `<lr-zoomable-frame>`. `false` (the default) preserves the exact pre-`zoomable` DOM — an
+inline thumbnail (e.g. in a chat stream) must not unexpectedly grow a focusable zoom-chrome viewport;
+an inspection surface opts in. `highlights: LyraHighlight[] = []` (attribute: false) — display-only
+`region` highlights painted over the rendered SVG. `activeHighlightId: string | null = null`
+(attribute `active-highlight-id`) — the `highlights` entry, if any, currently treated as active
+(`data-active` on its `region-highlight`). `anchorKinds` is a readonly `['region']` (this viewer's
+supported `LyraAnchor.kind` values for the shared anchor-target contract).
+
+**Methods:** `scrollToAnchor(target)` — scrolls a `region` highlight (by id, or a `LyraAnchor` matched
+back to its owning `LyraHighlight` by reference) into view; resolves `false` when nothing matches, the
+anchor isn't `region`, or the document isn't loaded yet (no retry loop — a caller invoking this before
+`src` resolves simply gets `false`).
+
+**Events:** `lr-render-error` with `detail.error` when fetching or sanitizing fails.
+`lr-highlight-activate` (`detail: { id }`) — a region highlight was clicked or activated via
+Enter/Space.
+
+**CSS parts:** `base`, `body`, `svg`, `spinner`, `error`, `highlight-layer` (wrapper around every
+rendered region highlight), `region-highlight` (one region highlight, `data-tone`, `data-active`),
+`frame-viewport`/`frame-content`/`frame-controls`/`frame-zoom-in`/`frame-zoom-out`/`frame-reset`
+(forwarded from the internal `<lr-zoomable-frame>` while `zoomable`).
+
+**Themeable custom properties:** `--lr-svg-viewer-max-height` (default `none`) — maximum block size
+of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
+`--lr-svg-viewer-active-border` (default `var(--lr-color-warning, var(--lr-color-brand))`) — the
+border color of the `[part='region-highlight']` matching `activeHighlightId`, distinct from the
+resting highlight border so the active region can be recolored without touching the rest. It is an
+inline `var()` fallback at the point of use rather than a `:host` declaration, so it can be set on
+the element *or on any ancestor*: `::part(region-highlight)[data-active]` is invalid CSS — Shadow
+Parts forbids an attribute selector after `::part()` — so re-pointing a shared `--lr-color-*` token,
+and repainting everything else reading it, was previously the only way. Unset, it falls back to
+exactly the tokens the rule used before.
+
+**Optional peer dependency:** `dompurify`.
+
+Remote resources are capped at 25 MB; exceeding it surfaces the localized
+`documentPreviewResourceTooLarge` message instead of the graphic.

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,312 @@
+<!-- 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 inline editing —
+  `true` opens a native editor on that cell's double-click (one cell at a time), `'always'` instead
+  renders a persistent editor in every body cell of the column from first paint, for a
+  settings/rate-style column meant to be typed straight into — while `editValue` supplies the editor
+  value and `editType` selects `text` or `number`
+  `cellTitle(row) => string | undefined` is the `title` analogue of `cellStyle`, applied directly to
+  the generated `<td>` — e.g. the untruncated text behind an ellipsized cell, or a formatted
+  timestamp behind a relative one;
+  `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.
+- `columns[].editable: boolean | 'always'` — a widening of the original `boolean`, non-breaking.
+  `true` is unchanged: double-click a cell to open its editor, one at a time, Enter commits and
+  closes, Escape cancels and closes, blur-after-change commits. `'always'` renders an editor in
+  every body cell of that column, permanently:
+  - **Focus model.** Each editor is a plain tab stop — no `tabindex` of its own — exactly like the
+    existing row-expand toggle, and stays *outside* the header/row roving-tabindex model. Tab walks
+    down the column; arrow keys still navigate the grid from a row's own roving stop, and act as
+    ordinary caret movement once focus is inside a field. Non-editable columns are unaffected.
+  - **Value binding.** A persistent editor binds its `value` as a **content attribute**, not as the
+    `.value` property, so native dirty-value-flag semantics apply. Trade-off: once the user has
+    typed into a cell, an out-of-band `rows` update to that same cell will **not** visibly replace
+    their draft. An editor the user has not touched still picks up a new `rows` value normally.
+    `lr-cell-edit` remains the only mutation channel — the table never mutates `row`.
+  - **Keys.** Enter commits (emits `lr-cell-edit`) and *keeps focus* in the field, since there is no
+    closed state to fall back to. `change` (blur after a modification) commits, as with `true`.
+    Escape is **not** cancelled and does nothing to the editor — there is nothing to cancel back to
+    — so an ancestor dialog/popover still acts on it.
+  - **Focus across re-sorts and pagination.** Rows are keyed, so a re-sort *moves* the editor's
+    `<input>` (the typed value rides along) and the table restores focus to the same logical cell
+    afterwards. If the focused row leaves the rendered page entirely (pagination, filtering), focus
+    is simply lost rather than yanked to whichever unrelated row now sits in that position.
+  - Each editor keeps its own interpolated `tableEditCell` accessible name (`Edit {column}`), so a
+    column of otherwise-identical inputs is still individually named to a screen reader.
+- `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)
+- `layout: 'auto'|'fixed' = 'auto'` (reflected) — a **floor** on the `<table>`'s `table-layout`, not
+  an override. `'fixed'` forces the fixed algorithm even when no column declares a `width`, so every
+  column shares the available width evenly and long cell content is clipped/wrapped instead of
+  stretching its column. The default `'auto'` still *resolves* to `fixed` whenever a column declares
+  a `width`, a column has been drag-resized, or a resize gesture is in flight — column resizing does
+  not work under `table-layout: auto`, so `'auto'` can never mean "never fixed". See the gotchas for
+  the two consequences of the fixed algorithm worth knowing before opting in
+- `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 busy chrome and suppresses the real rows while loading
+- `loadingAppearance: 'spinner'|'skeleton' = 'spinner'` (attribute `loading-appearance`, reflected) —
+  how `loading` renders. `'spinner'` replaces the whole grid with an indeterminate spinner.
+  `'skeleton'` instead renders the real table — the same `<colgroup>` (declared *and* drag-resized
+  widths included), the same `<thead>`, the filter field and the pagination footer — and fills
+  `<tbody>` with placeholder rows, so a cold load sketches the grid's shape rather than collapsing to
+  a spinner and reflowing when the rows land. Kept as a separate property rather than widening
+  `loading` to a string union, so `?loading=${…}` bindings and `el.loading === true` checks keep
+  working
+- `skeletonRows: number = 0` (attribute `skeleton-rows`) — placeholder row count under
+  `loadingAppearance="skeleton"`. `0` derives the count instead: the normalized `pageSize` when
+  pagination is on (capped at 20, so a large page size can't emit thousands of placeholder cells),
+  otherwise 3. Any positive value is used verbatim and is *not* capped. Ignored entirely under the
+  default spinner appearance
+- `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`)
+- `emptyCompact?: boolean` (attribute `empty-compact`) — overrides the built-in `[part='empty']`
+  state's `compact` rendering. Tri-state: leave it `undefined` (the default) to keep each empty
+  branch's own built-in default — the two shadow-root-level branches (no columns, no rows) render
+  spacious, while the filtered-to-zero branch, which sits inside `[part='base']` alongside the filter
+  field, renders compact. `empty-compact="false"` forces the spacious rendering everywhere, and is
+  parsed as `false` rather than as mere attribute presence. Has no effect once the `empty` slot is
+  filled
+- `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:** `empty` — replaces the built-in empty state on the two *data*-empty branches (no rows at
+all, and filtered/paginated down to zero). Left unfilled, the built-in `[part='empty']` `<lr-empty>`
+renders as this slot's fallback content. The no-columns branch is deliberately **not**
+slot-replaceable: it reports a configuration problem (`noColumnsHeading`), not "this query returned
+nothing", and one slot covering all three would collapse that distinction. Everything else comes
+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` (under
+`loadingAppearance="spinner"` the visible block holding the spinner; under `"skeleton"` the
+visually-hidden `role="status"` node, since the placeholder rows are the visible affordance),
+`skeleton` (each `<lr-skeleton>` placeholder inside a skeleton-mode body cell — the placeholder rows
+and cells reuse the ordinary `row`/`cell`/`row-total-cell` parts, which is exactly what keeps them
+geometrically identical to real rows, so `skeleton` is the part to target for the placeholder's own
+look: `::part(skeleton) { --lr-skeleton-h: 2em; }`), and
+`pagination`, `cell-editor`, `group-row`, `group-cell`, and `resize-handle` (the focusable column
+separator). The built-in empty state is addressable rather than fixed: `empty` is the `<lr-empty>`
+host in all three empty states, and it re-exports that element's own inner parts as `empty-base`,
+`empty-icon`, `empty-heading`, `empty-description` and `empty-actions`. Note that the no-columns and
+no-rows states return the empty element as the shadow root's own root, with no `[part='base']`
+wrapper around it — `::part(base)` does not apply in those two states, only in the filtered-to-zero
+one — and that `empty` disappears entirely once the `empty` slot is filled.
+
+**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.
+`--lr-table-row-selected-bg` (default `var(--lr-color-brand-quiet)`) — the background of a row whose
+`aria-selected` is `true`. Like every state-scoped custom property in this library it is an inline
+`var()` fallback at its point of use and is **not** declared on `:host`, so it can be set on the
+element *or on any ancestor* and still reach the rule that reads it. It exists because Shadow Parts
+forbids an attribute selector after `::part()` — `::part(row)[aria-selected='true']` is invalid CSS —
+so the only prior lever for restyling the selected row was overriding the library-wide
+`--lr-color-brand-quiet` token, which repaints everything else reading it.
+`--lr-table-sticky-offset` (default `0`) is measured and written inline per column by the component
+so multiple `sticky` columns stack instead of overlapping; it is a read-out, not a knob you set.
+`--lr-table-heat-t` is likewise component-written (each `[data-heat]` cell's position on the ramp).
+
+**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`.
+- `layout="fixed"` (and any `'auto'` that resolves to fixed) carries two consequences of the CSS
+  fixed algorithm. With no declared widths the **first** row — the header row included — determines
+  every column's width, so revealing a `priority`-hidden column via
+  `[part='reveal-columns-button']` re-measures and changes *all* of them, not just the revealed one.
+  And `columns[].minWidth`/`maxWidth` are silently ignored by `table-layout: fixed`; declare `width`
+  instead when a specific column needs a specific size.
+- skeleton mode keeps geometry stable only when the browser isn't sizing columns from cell content.
+  Under the default `table-layout: auto`, placeholder cells have no intrinsic width, so the columns
+  re-measure when real content arrives — exactly as they do between any two different data sets. For
+  pixel-identical widths across the load, declare `columns[].width` or set `layout="fixed"`. Either
+  loading appearance keeps exactly one `role="status"` live region announcing the state: every
+  placeholder opts out of `<lr-skeleton>`'s own announcement, so a skeleton table never announces
+  once per placeholder row.
+- `columns[].cellTitle` returning an empty string **or** `undefined` omits the `title` attribute
+  entirely rather than rendering `title=""` — an empty `title` would suppress an ancestor element's
+  own tooltip. The attribute is also suppressed while that cell is in inline-edit mode, so the
+  tooltip can't shadow the editor. Accessibility caveat: some screen readers announce a `<td title>`
+  as the cell's accessible *name*, replacing the cell's content rather than supplementing it (the
+  same caveat `lr-stat`'s `exactValue` carries). Use it for a longer form of what the cell already
+  shows, never for information that exists nowhere else.
+- `editable: 'always'` deliberately does not re-assert a cell's source value once the user has typed
+  into it. That is the native dirty-value-flag behavior the attribute binding buys, and it is the
+  point: a background `rows` refresh cannot silently overwrite an in-progress edit. If you need the
+  opposite — an authoritative external value that always wins — do not use `'always'`; re-key the
+  row (`rowKey`) so the editor is recreated rather than updated, or keep `editable: true` and let
+  the short-lived double-click editor's property binding re-assert. Also note the two things
+  `'always'` intentionally does *not* do: it never sets the roving `tabindex` (its editors are
+  ordinary tab stops, so Tab order in that column interleaves with the grid's two roving stops,
+  the same way the row-expand toggle's already does), and it never cancels Escape.
+
+---