@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-context-meter.md

@@ -0,0 +1,92 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-context-meter`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/context-meter/context-meter.js';` (registers the tag; side-effect import)
+- **Class** `LyraContextMeter`, also available unregistered from `@aceshooting/lyra-ui/components/data/context-meter/context-meter.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-context-meter`
+
+A segmented occupancy meter (bar or ring) for showing how a fixed capacity — a model's context
+window, a token budget, any consumable quota — is divided across labeled categories. First-party
+invention (no Web Awesome equivalent). Pure data visualization: it renders `segments`/`total` exactly
+as given and never computes token counts, costs, or any other domain-specific estimate itself — the
+one exception is the plain arithmetic sum of segment values used to build the accessible "X of Y
+used" summary.
+
+**Properties:**
+- `segments: ContextMeterSegment[] = []` (attribute: false, JS-only) — `{ label: string; value:
+  number; tone?: 'brand' | 'success' | 'warning' | 'danger' | 'neutral'; color?: string }[]`. `value` is an *absolute*
+  quantity measured against `total`, never a pre-computed percentage.
+  `color`, when supplied, is a sanitized arbitrary CSS color that takes precedence over `tone`.
+- `total: number = 0` — the full capacity segments are measured against (e.g. a model's context
+  window size).
+- `variant: 'ring' | 'bar' = 'bar'` (reflected)
+- `label: string = ''` — overall accessible caption, e.g. `"128K context window"`. Also rendered
+  visually (`[part="label"]`) when set.
+
+Accessible summaries, segment tooltips, and ring titles format quantities using `effectiveLocale`.
+A host `aria-label` overrides the generated meter summary and is preserved across reactive updates.
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `base` (a `<div>` for `bar`, an `<svg>` for `ring`), `track` (the unfilled/empty
+capacity), `segment` (one occupied segment — carries `data-tone` and, for custom colors,
+`--lr-context-meter-segment-color`), `label`
+
+**Themeable custom properties:** `--lr-context-meter-segment-color` is set per segment when its
+`color` field is supplied; otherwise the component consumes shared tokens
+`--lr-space-xs`, `--lr-color-text-quiet`, `--lr-font`, `--lr-radius`, `--lr-color-border`,
+`--lr-color-surface` (the bar variant's inter-segment seam), `--lr-color-brand`,
+`--lr-color-success`, `--lr-color-warning`, `--lr-color-danger`, `--lr-transition-base`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-context-meter
+  label="128K context window"
+  total="128000"
+  .segments=${[
+    { label: 'System prompt', value: 2200, tone: 'neutral' },
+    { label: 'Conversation history', value: 61000, tone: 'brand' },
+    { label: 'Retrieved context', value: 30800, tone: 'warning' },
+  ]}
+></lr-context-meter>
+
+<lr-context-meter variant="ring" total="128000" .segments=${segments}></lr-context-meter>
+```
+
+`role="img"` and a computed `aria-label` are set imperatively on the *host* element itself in
+`willUpdate` (mirroring `lr-gauge`'s "meter" role convention) — every internal node (`track`,
+`segment`, the ring's `<svg>`, `label`) is `aria-hidden`, so a screen reader gets one meaningful
+summary string instead of the raw markup. That summary's "used" figure is the sum of
+`segments[].value`, clamped to `total` whenever `total > 0` so the announced text can never claim
+more than 100% used (e.g. `segments` summing to `150000` against `total="128000"` still announces
+`"128,000 of 128,000 used"`) — matching what the *visual* meter shows, since each segment's ratio is
+independently clamped so the running cumulative fill across all segments can never exceed 100% of the
+bar/ring either: an over-`total` `segments` array renders as a fully (not over-) filled meter, with
+later segments truncated or squeezed to zero width/arc-length as the budget runs out. `total <= 0`
+(or non-finite) renders zero segments — an empty track/ring — and the announced summary falls back to
+just `"{used} used"` with no `"of {total}"` clause, regardless of what's in `segments`. Ring geometry
+(a 40-radius circle, 12px stroke, centered at 50,50) intentionally matches `lr-gauge`'s own radial
+numbers, so the two circular-meter components in the library share one visual scale.
+
+**Known gotchas:**
+- The ring variant's per-segment `<title>` and the bar variant's per-segment `title=` attribute are
+  native mouse-hover tooltips only — they sit inside `aria-hidden` markup, so screen readers never
+  read them; only the host's own `role="img"`/`aria-label` carries accessible information.
+- `variant="ring"` fixes the host at `8em × 8em` (`:host([variant='ring'])`) — the bar variant's
+  `inline-size: 100%` does not apply in ring mode; resize it via `font-size` or an explicit
+  width/height override on the host instead.
+- Segment order is significant for the ring's cumulative `stroke-dashoffset` — later entries in
+  `segments` render further around the circle (starting at 12 o'clock, going clockwise); there's no
+  independent sort/z-order control.
+
+---

package/llms/components/lr-control-group.md

@@ -0,0 +1,46 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-control-group`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/control-group/control-group.js';` (registers the tag; side-effect import)
+- **Class** `LyraControlGroup`, also available unregistered from `@aceshooting/lyra-ui/components/layout/control-group/control-group.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-control-group`
+
+Responsive semantic grouping for mixed controls and actions. It keeps slotted children in a
+wrapping inline-flex row, centers children with different intrinsic heights, and switches to a
+full-width allocation in narrow containers. Use it for dashboard toolbars that combine segmented
+controls, selects, buttons, and other interactive elements.
+
+**Properties:**
+- `label: string = ''` — accessible name for the internal `role="group"`; when empty, a host
+  `aria-label` is forwarded as a fallback.
+
+**Events:** none.
+
+**Slots:** default — controls, buttons, or other action content.
+
+**CSS parts:** `base` — the internal `role="group"` wrapper.
+
+**Themeable custom properties:** `--lr-control-group-gap` (default `var(--lr-space-xs)`) — gap
+between grouped controls; shared spacing and layout tokens apply as well.
+
+```html
+<lr-control-group label="Chart controls">
+  <lr-segmented></lr-segmented>
+  <lr-select></lr-select>
+  <lr-button>Export</lr-button>
+</lr-control-group>
+```
+
+**Known gotchas:**
+- This is a layout and semantics primitive; it does not coordinate child values or emit a group
+  change event.
+- Children wrap according to the group's own allocated inline size, not the viewport width.
+
+---

package/llms/components/lr-conversation-item.md

@@ -0,0 +1,118 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-conversation-item`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/conversation-item/conversation-item.js';` (registers the tag; side-effect import)
+- **Class** `LyraConversationItem`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/conversation-item/conversation-item.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-conversation-item`
+
+A selectable row representing one chat session in a history sidebar list. Usable standalone or as the
+`renderItem()` payload of `<lr-virtual-list>`; has no dependency on that (or any) other component.
+First-party invention (no Web Awesome equivalent).
+
+**Properties:**
+- `title: string = ''` — the session's display title. Falls back to "Untitled conversation" when empty
+  (display only — the property itself is never mutated by that fallback).
+- `excerpt: string = ''` — a short preview snippet of the last message. Omit for no excerpt line.
+  Ignored entirely once the `excerpt` slot has assigned content.
+- `timestamp?: Date | string` (attribute: false) — accepts a `Date` or anything `new Date()` can parse
+  (e.g. an ISO 8601 string); invalid input is treated as unset (no `<time>` rendered).
+- `formatTimestamp?: (date: Date) => string` (attribute: false) — overrides the default absolute-time
+  rendering (clock time for same-day timestamps, otherwise a calendar date). Not a fuzzy "2 hours ago"
+  relative string — bucketed relative grouping is a list-level concern, not this row's job.
+- `active: boolean = false` (reflected) — whether this is the currently-selected/open session; drives
+  the brand-quiet background treatment.
+- `editable: boolean = true` (reflected) — whether inline-rename is available at all. When `false`, the
+  rename button never renders and the row can never enter its editing state; flipping it to `false`
+  while a rename is already in progress cancels that edit (discards the draft, like Escape) rather
+  than leaving it stranded and still committable.
+- `spellcheck: boolean = true` — forwarded to the in-place rename `<input>`; `spellcheck="false"` is
+  parsed as false (not Lit's default boolean-attribute behavior)
+- `autocapitalize: string = ''` — forwarded to the in-place rename `<input>`; empty omits the attribute
+- `autoCorrect: string = ''` (attribute `autocorrect`) — forwarded to the in-place rename `<input>`
+  (Safari/WebKit-specific); empty omits the attribute. Named `autoCorrect` to avoid
+  `HTMLElement.autocorrect`'s incompatible DOM typing.
+
+**Events:** `lr-select` (no detail payload — identify the row via the platform `id` attribute on the
+event's `target`/`currentTarget`, the same convention `<lr-attachment-chip>` uses; fires on a click on
+`[part="option"]` outside the rename button/`actions` slot, or Enter/Space while it's focused, only
+while not currently renaming), `lr-rename` (`detail: { title: string }` — an in-place rename was
+committed via Enter or blur-while-editing; does not mutate `title` itself, this is a controlled
+component — not fired when the trimmed draft is empty or unchanged from the original `title`, treated
+as an implicit cancel), `blur` (no detail — re-dispatched from the in-place rename `<input>`'s own
+`blur`, bubbling and composed unlike the native event), `focus` (no detail — re-dispatched from the
+in-place rename `<input>`'s own `focus`, for the same reason as `blur`)
+
+**Slots:**
+- `actions` — overflow/icon-button controls rendered at the trailing edge of the row (e.g. a
+  pin/delete control); only visually shown once it actually has assigned elements. The only slot that
+  may hold focusable content.
+- `leading` — non-interactive leading content (avatar, purpose icon, status dot), rendered inside the
+  selectable region before the title/excerpt content.
+- `content` — replaces the built-in title + excerpt + meta content area with host-supplied
+  non-interactive row content.
+- `excerpt` — full override of the excerpt presentation (e.g. a search-hit snippet with `<mark>`);
+  wins over the `excerpt` property whenever it has assigned content.
+- `meta` — small, non-focusable structured fields below the title/excerpt (a day label, cost, request
+  count); entirely app-supplied, this component computes none of it.
+
+`leading`/`content`/`excerpt`/`meta` must all stay non-focusable — see the `role="button"` note below.
+
+**CSS parts:** `base`, `option`, `content`, `title`, `title-input`, `rename-button`, `excerpt`,
+`timestamp`, `actions`
+
+**Themeable custom properties:** shared tokens only — `--lr-space-xs/-s/-m`, `--lr-radius`,
+`--lr-transition-fast`, `--lr-color-text/-text-quiet/-brand/-brand-quiet/-surface`,
+`--lr-focus-ring-width/-color/-offset`, `--lr-icon-button-size`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-conversation-item
+  id="sess_123"
+  title="Q3 roadmap planning"
+  excerpt="Let's revisit the timeline for the launch…"
+  .timestamp=${session.updatedAt}
+  ?active=${session.id === currentSessionId}
+  @lr-select=${(e) => openSession(e.currentTarget.id)}
+  @lr-rename=${(e) => renameSession(e.currentTarget.id, e.detail.title)}
+>
+  <button slot="actions" aria-label="Delete conversation">✕</button>
+</lr-conversation-item>
+```
+
+`role="button"` (not `"option"`) lives on `[part="option"]` — despite the part name — so the row has
+valid semantics both standalone and inside a larger history-list layout: it activates one current
+session rather than being a listbox option, so it requires no particular owner role. Selection is
+conveyed via `aria-current="true"` while `active`, not `aria-selected`. Because `role="button"`
+forbids focusable descendants (axe-core's `nested-interactive` rule), the rename button and the
+`actions` slot are rendered as DOM *siblings* of `[part="option"]` inside `[part="base"]`, not nested
+inside it — the same constraint the in-place rename `<input>` runs into one level deeper, which is
+why `[part="option"]` sheds its `role`/`tabindex`/`aria-current`/`aria-label` entirely for the
+duration of an edit rather than just visually swapping content (a row mid-edit *is* a text field).
+
+**Known gotchas:**
+- `lr-select` carries no detail payload at all — read the session id off the event's own `target`/
+  `currentTarget`, not a `detail` field.
+- Renaming is a controlled interaction: committing `lr-rename` never updates `title` locally: the
+  consumer must apply the new title once it's actually persisted.
+- An empty or unchanged (post-trim) rename draft is treated as an implicit cancel — no `lr-rename`
+  fires, and the row silently reverts to showing `title`.
+- Rename is triggered only by the dedicated pencil-icon button, never a double-click on the title —
+  double-click has no keyboard/screen-reader equivalent and would also swallow the row's own
+  single-click `lr-select`.
+- While renaming, `[part="option"]` has no `role`/`tabindex`/`aria-current`/`aria-label` at all — a
+  screen reader briefly stops announcing it as a button for the duration of the edit.
+- The part is named `option` for historical reasons but carries `role="button"`; don't write CSS or
+  ARIA assumptions that expect a listbox option.
+- Setting `editable = false` mid-rename silently discards the in-progress draft (no `lr-rename`
+  fires) — a consumer toggling `editable` off (e.g. in response to some other row entering rename
+  mode) should not expect the previous edit to be committed first.
+
+---

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

@@ -0,0 +1,52 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-copy-button`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/copy-button/copy-button.js';` (registers the tag; side-effect import)
+- **Class** `LyraCopyButton`, also available unregistered from `@aceshooting/lyra-ui/components/utility/copy-button/copy-button.class.js`
+- **Family** `components/utility/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-copy-button`
+
+A standalone icon-only copy-to-clipboard button for a plain text `value` — swaps its icon to a
+checkmark for ~1.5s on activation. Takes no positioning opinion of its own; a consumer
+wraps/positions the host element (e.g. absolutely positioned in the corner of a `wa-textarea` or a
+read-only output field). Unlike `lr-code-block`'s or `lr-json-viewer`'s own built-in copy
+buttons, this has no code/JSON content model to adopt just to reuse the copy affordance.
+
+**Properties:**
+- `value: string = ''` — the plain text to copy.
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the localized
+  Copy/Copied accessible name without changing the icon
+- `disabled: boolean = false` (reflected)
+- `feedbackDuration: number = 1500` (attribute `feedback-duration`) — milliseconds before the
+  copied checkmark returns to the copy icon; finite values are clamped at zero
+
+**Methods:** `focus(options?)` and `blur()` forward to the native button.
+
+**Events:** `lr-copy` (`detail: { text: string }`) — fires on activation, always with the current
+`value`, regardless of whether the OS clipboard write actually succeeded (same convention as
+`lr-code-block`'s/`lr-json-viewer`'s own copy buttons).
+
+**Slots:** none.
+
+**CSS parts:** `base` — the button itself.
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-copy-button value="npm install @aceshooting/lyra-ui"></lr-copy-button>
+```
+
+**Known gotchas:**
+- best-effort clipboard write: `navigator.clipboard` is absent in insecure contexts/older browsers,
+  and some engines throw synchronously rather than rejecting — either way `lr-copy` still fires
+  with the intended text so a consumer can always show its own confirmation/fallback UI.
+
+---

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

@@ -0,0 +1,49 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-csv-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/csv-viewer/csv-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraCsvViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/csv-viewer/csv-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `papaparse` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-csv-viewer`
+
+Fetches CSV text, parses quoted fields with the optional `papaparse` peer, and virtualizes body rows.
+
+Adopts `DocumentAnchorTarget`: a `cell-range` anchor addresses the raw file grid, 1-based, with the
+header row included whenever `has-header-row` is set; `scrollToAnchor()` scrolls the addressed
+row/column into view via the virtualized list's `active-id`. `highlights` paint as a focusable
+`part="cell-highlight"`.
+
+**Properties:** `src` and `name` are strings. `hasHeaderRow: boolean = true` (attribute
+`has-header-row`) controls whether the first parsed row is rendered as a sticky header.
+`anchorKinds` is a readonly `['cell-range']` (this viewer's supported `LyraAnchor.kind` values for
+the shared anchor-target contract).
+
+**Methods:** `search(query)` resolves the match count via a case-insensitive substring match over
+the same stringified cell values `cell()` renders, ordered row then column (empty/whitespace query
+behaves like `clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches
+(wrapping, resolving `false` when there are none); `clearSearch()` clears the query, matches, and
+painted marks.
+
+**Events:** `lr-render-error` with `detail.error` when fetching or parsing reports an error.
+`lr-highlight-activate` (`detail: { id }`) — a `highlights` cell was clicked or activated via
+Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
+`scrollToAnchor()` call. `lr-search-change` (`detail: { query, matchCount, activeIndex }`) — from
+`search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
+
+**CSS parts:** `base`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a cell covered by
+a `highlights` entry), `rows`, `spinner`, and `error`.
+
+**Optional peer dependency:** install `papaparse` with `pnpm add papaparse`. The registry matches
+`text/csv` and `.csv` filenames.
+
+Remote resources are capped at 25 MB, and the parsed table at 10,000 rows and 1,000 columns;
+exceeding any of these surfaces the localized `documentPreviewResourceTooLarge` message instead of
+the table.
+
+---

package/llms/components/lr-dashboard-grid.md

@@ -0,0 +1,34 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-dashboard-grid`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.js';` (registers the tag; side-effect import)
+- **Class** `LyraDashboardGrid`, also available unregistered from `@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.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-dashboard-grid`
+
+Responsive, keyboard-accessible controlled widget grid. It positions layout entries and emits
+move, resize, collision, and layout-change requests; the host owns persistence and applies updates.
+
+**Properties:** `layout: DashboardCell[] = []` (attribute: false, never mutated by the component),
+`columns: number = 12`, `rowHeight: number = 80` (px, also the row snap pitch), `gap: number = 8`
+(px, both axes), `collision: 'reject' | 'push' | 'overlap' = 'reject'`, `cellsDraggable: boolean = false`
+(attribute `cells-draggable` — pointer drag plus Ctrl/Cmd+Arrow), `cellsResizable: boolean = false`
+(attribute `cells-resizable` — the resize handle plus Ctrl/Cmd+Shift+Arrow), `locked: boolean =
+false` (reflected — disables every gesture grid-wide), `accessibleLabel: string | null = null`
+(attribute `aria-label`, falls back to a localized grid name).
+
+**Events:** `lr-cell-move` (`detail: { id, position, previous }`), `lr-cell-resize`
+(`detail: { id, size, previous }`), `lr-collision` (`detail: { id, collidedWith, policy, accepted }`),
+`lr-layout-change` (`detail: { layout }`, the full proposed layout after an accepted change).
+**Slots:** `cell-{id}`. **CSS parts:** `base`, `cell`, `empty`, `resize-handle`, `live-region`.
+
+**Themeable custom properties:** `--lr-dashboard-grid-columns`, `--lr-dashboard-grid-row-height`,
+and `--lr-dashboard-grid-gap` back the CSS Grid's `grid-template-columns`/`grid-auto-rows`/`gap`.
+The `columns`/`rowHeight`/`gap` properties write them inline on `[part='base']` on every render, so
+overriding them from a stylesheet has no effect — set the properties instead.

package/llms/components/lr-data-grid.md

@@ -0,0 +1,47 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-data-grid`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/data-grid/data-grid.js';` (registers the tag; side-effect import)
+- **Class** `LyraDataGrid`, also available unregistered from `@aceshooting/lyra-ui/components/data/data-grid/data-grid.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-data-grid`
+
+Keyboard-navigable data grid with typed `columns` and `rows`, sortable headers, roving cell focus,
+loading/empty states, and responsive horizontal overflow.
+
+**Properties:**
+- `columns: DataGridColumn<T>[] = []` (attribute: false) — `{ key, label, width?, sortable?,
+  value? }`; `width` becomes the header cell's `inline-size`, `value(row)` overrides the default
+  `row[key]` lookup
+- `rows: T[] = []` (attribute: false)
+- `rowKey: (row: T, index: number) => string | number = (_row, index) => index` (attribute: false)
+- `selectedKey: string | number | null = null` (attribute: false) — compared against `rowKey(row, i)`
+  to set `[part='row'][data-selected]` and `aria-selected`
+- `sortKey: string = ''`, `sortDirection: 'ascending' | 'descending' = 'ascending'`
+  (attribute: false) — the grid updates both on header activation and emits `lr-sort`, but never
+  reorders `rows`; sorting stays the consumer's job
+- `loading: boolean = false` (reflected) — replaces the body with a localized "loading" row
+- `emptyText: string = ''` (attribute `empty-text`) — empty-state text; falls back to the localized
+  `noData`
+- `accessibleLabel: string = ''` (attribute `aria-label`) — names the `role="grid"` table; falls back
+  to the localized `dataGridLabel`
+
+**Keyboard:** exactly one cell is tabbable. Arrows move the roving focus (Left/Right are swapped
+under RTL), Home/End jump to the first/last column of the current row, Enter/Space activate the row.
+The focus position is re-clamped whenever `rows`/`columns` shrink, so the grid can't lose its tab stop.
+
+**Events:** `lr-row-click` (`detail: { row }`, click or Enter/Space), `lr-selection-change`
+(`detail: { row }`, emitted alongside it after `selectedKey` updates), `lr-cell-focus`
+(`detail: { row, column }`, `column` is the column `key`), `lr-sort` (`detail: { key, direction }`,
+`sortable` columns only; re-activating the active column flips `direction`).
+
+**Slots:** none.
+
+**CSS parts:** `viewport` (the scrolling bordered wrapper), `grid` (the `<table role="grid">`),
+`header` (each sticky `<th>`), `row`, `cell`, `empty` (the loading / no-data cell).

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

@@ -0,0 +1,60 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-dataset-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/dataset-viewer/dataset-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraDatasetViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/dataset-viewer/dataset-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `papaparse` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-dataset-viewer`
+
+Fetches tab-, pipe-, or delimiter-separated text and renders a virtualized, accessible table (a
+`role="table"` container with a sticky `role="row"` header, composed with `<lr-virtual-list
+item-role="row">` for the body) using the optional `papaparse` peer. The document registry matches
+`.tsv`, `.psv`, and `.dat` filenames.
+
+Adopts `DocumentAnchorTarget`: a `cell-range` anchor addresses the raw file grid, 1-based, with the
+header row always occupying row 1 (this component always parses with a header row, so the first row
+is never part of the virtualized body); `scrollToAnchor()` scrolls the addressed row into view via
+the virtualized list's `active-id`. `highlights` paint as a `part="cell-highlight"` cell wrapping a
+focusable `part="cell-highlight-action"` native button, keeping the ARIA table tree intact.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `anchorKinds` is
+a readonly `['cell-range']` (this viewer's supported `LyraAnchor.kind` values for the shared
+anchor-target contract).
+
+**Methods:** `search(query)` resolves the match count via a case-insensitive substring search over
+every body cell's raw string value, ordered row then column (empty/whitespace query behaves like
+`clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches (wrapping,
+resolving `false` when there are none); `clearSearch()` clears the query, matches, and cursor.
+
+**Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
+`lr-highlight-activate` (`detail: { id }`) — a `highlights` cell was clicked or activated via
+Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
+`scrollToAnchor()` call. `lr-search-change` (`detail: { query, matchCount, activeIndex }`) — from
+`search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
+
+**CSS parts:** `base`, `body`, `table`, `header-row`, `header-cell`, `data-row`, `cell`,
+`cell-highlight` (a `role="cell"` covered by a `highlights` entry; wraps the action button),
+`cell-highlight-action` (the native button filling a highlighted cell — focusable, emits
+`lr-highlight-activate` on click or Enter/Space), `spinner`, and `error`.
+
+**Exports:** `DatasetTable` is `{ fields: string[]; rows: Record<string, string>[] }`.
+
+**Themeable custom properties:** `--lr-dataset-viewer-max-height` (default `none`) — maximum block
+size of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
+`--lr-dataset-viewer-highlight-color` (default `var(--lr-color-brand)`) — the outline color of a
+`cell-highlight` cell. The component writes it inline (as
+`var(--lr-color-warning, var(--lr-color-brand))`) on the cell matching `activeHighlightId`, since a
+`[data-active]` selector can't be chained onto the `::part(cell-highlight)` the cell reaches this
+component's stylesheet through; a custom property inherits across that boundary instead.
+
+**Optional peer dependency:** `papaparse`.
+
+Remote resources are capped at 25 MB, and the parsed table at 10,000 rows and 1,000 columns (the
+same shared default as `lr-csv-viewer`/`lr-spreadsheet-viewer`); exceeding either surfaces the
+localized `documentPreviewResourceTooLarge` message instead of the table.