@aceshooting/lyra-ui 29.0.2 → 29.1.0

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

@@ -9,22 +9,22 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** `xlsx` — see `llms/peers.md`
-- **Themeable via** 13 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 14 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
 
 ## `lr-spreadsheet-viewer`
 
-Fetches and renders `.xlsx` and `.xls` workbooks with the optional `xlsx` (SheetJS) peer. Multiple
-worksheets render through a `<lr-tab-group>` switcher, and body rows use `<lr-virtual-list>`.
+Fetches `.xlsx` and `.xls` workbooks with the optional `xlsx` (SheetJS) peer, or reads a host-owned
+`dataSource`. Multiple worksheets render through a `<lr-tab-group>` switcher, and body rows use `<lr-virtual-list>`.
 
 Adopts `DocumentAnchorTarget`: a `cell-range` anchor addresses one sheet's raw grid, 1-based, with
 its header row included, resolving the target sheet from the anchor's own `sheet` field (falling
 back to a `Sheet!`-prefixed `range`, then the active sheet); `scrollToAnchor()` switches
 `<lr-tab-group>`'s active tab first when needed, then scrolls the addressed row/column into view.
 `highlights` paint as a focusable `part="cell-highlight"`. A jump whose workbook is replaced by a
-concurrent `src` reassignment mid-flight reports `found: false` rather than a phantom success —
+concurrent `src`, `workbook`, or `dataSource` reassignment mid-flight reports `found: false` rather than a phantom success —
 matching `lr-csv-viewer`/`lr-dataset-viewer` (it wrongly reported `found: true` before 9.0.0).
 
 **Properties:** `src: string = ''` and `name: string = ''`. `maxHeight: string = ''` (attribute
@@ -33,13 +33,103 @@ matching `lr-csv-viewer`/`lr-dataset-viewer` (it wrongly reported `found: true`
 ignored. `anchorKinds: readonly LyraAnchorKind[] = ['cell-range']` (this viewer's supported
 `LyraAnchor.kind` values for the shared anchor-target contract).
 
-**Methods:** `search(query)` resolves the match count across every sheet's stringified cell values,
+Input properties and legacy limits:
+
+- `maxRows: number = 10000` (attribute `max-rows`) — rows per sheet, including its header;
+  effective range 1–100,000. For fetched ZIP workbooks, this also bounds the total row elements
+  encountered across inspected archive parts before SheetJS parsing.
+- `maxColumns: number = 1000` (attribute `max-columns`) — columns per sheet;
+  effective range 1–10,000.
+- `maxBytes: number = 26214400` (attribute `max-bytes`) — source bytes, default 25 MiB;
+  effective range 1–262,144,000 bytes (250 MiB).
+- `workbook: SpreadsheetViewerWorkbook | undefined` (property only, default `undefined`) —
+  `{ sheets: { name: string; rows: unknown[][] }[] }`. Each grid includes its header row and
+  accepts string, number, boolean, `null` or `undefined` cells.
+
+- `dataSource: SpreadsheetViewerSource | undefined` (property only, default `undefined`) — a host-owned
+  logical source, described below; `SpreadsheetViewerSource = LyraWorkbookSource`.
+
+Limits truncate finite fractions and clamp to their effective ranges; non-finite inputs use the
+stated defaults. Set limits before assigning `workbook`. In-memory input bypasses fetching and
+SheetJS, takes precedence over `src` even when empty, and setting it to `undefined` restores the
+configured URL source. Admission reads own data properties and rejects accessors in those fields
+without invoking them. The workbook, sheet records and row arrays are frozen snapshots.
+Reassigning the accepted caller object or getter snapshot is a no-op while effective limits are
+unchanged; replace the outer workbook after caller mutation. Limit changes revalidate the current
+snapshot. Byte admission counts UTF-8 cell text and sheet names, with nullish cells contributing
+empty text. Workbooks remain bounded to 256 sheets and 1,000,000 aggregate cells, counting headers.
+Malformed or over-limit input displays a localized error and emits `lr-render-error`.
+
+**Host-owned source input:** A defined `dataSource` takes precedence over `workbook` and `src`,
+bypassing file fetching and parsing. Invalid defined sources show a localized error and emit
+`lr-render-error`; they do not fall back to legacy input. Setting `dataSource = undefined` cancels
+source work and restores the current `workbook` or URL input. Source pages never overwrite the
+legacy `workbook` getter. The source remains host-owned by identity rather than being cloned. After
+changing its data or revision, reassign it (the same identity is accepted) or call the viewer's
+unnamed `requestUpdate()`. Source replacement, refresh and locale changes invalidate stale reads,
+search results and navigation. Unrelated presentation updates reuse source data.
+
+The source supplies a `revision` and at most 256 sheet descriptors with unique nonempty `key`
+and `name` values and a `data: LyraTabularSource` for each sheet. Sheet keys and names are each
+limited to 65,536 UTF-16 units. Each sheet exposes full logical
+body `rowCount`, `columnCount`, separate `columnAt(index)` labels, and either scalar `cellAt` or
+asynchronous rectangular `readCells`. Only the active sheet's cells are read for viewport
+rendering. Read requests carry revision, locale and an `AbortSignal`; replies must match the
+requested rectangle. Cells are strings, finite numbers, booleans, `null` or `undefined`, with
+nullish values displaying empty text.
+Logical body rows are not truncated by `maxRows` or materialized as a complete array. Each active
+source's `columnCount` must fit `maxColumns` (default 1,000, effective hard maximum 10,000); an
+oversized column count is an error. Reads remain bounded to at most 500 rows, 100 columns and
+10,000 cells per rectangle, with two retained rectangles. Each scalar's display text and each
+column key/label is limited to 65,536 UTF-16 units. Retained cell and column metadata text shares a
+2,000,000-unit ceiling.
+Malformed or oversized replies fail visibly instead of silently clipping source values.
+
+Only source mode uses fixed row boxes and matching virtual-list row geometry, both resolved live
+from `--lr-size-3rem` (3rem, or 48px at a 16px root font). Oversized cell display stays within that
+row box without changing the source scalar. Legacy file and in-memory rows keep their automatic
+heights. Column windows retain absolute `aria-colindex` values; anchors still use one-based display
+coordinates and can reveal unloaded rows and offscreen columns.
+Source column labels always occupy display row 1; hit `row: -1` addresses those labels and body
+row `0` appears at display row 2. Source search hits use stable `sheetKey` values; existing anchors
+continue to use sheet names in `sheet` or a `Sheet!` range prefix. There is no headerless source
+option.
+
+In source mode, `search(query)` delegates to the source's global search capability rather than
+scanning loaded rectangles or an admitted prefix. The viewer requests at most 1,000 hits and keeps
+`matchCount` equal to retained, cursor-addressable hits. A larger known provider total does not
+replace that count; `matchCountExact` is true only for exhaustive, fully retained results. Without
+that capability, a nonempty query returns 0 with `matchCountExact: false` and `part="search-status"`
+shows the localized `sourceSearchUnavailable` message. This adds no local search toolbar or event
+fields. `searchNext()`/`searchPrevious()` report whether the target was actually revealed;
+`clearSearch()` cancels pending search and dependent navigation.
+Global search comes from `LyraWorkbookSource.search`, not a fanout over sheet search callbacks;
+its `LyraWorkbookHit` records include `sheetKey`, zero-based body `row` (or -1 for labels), and
+zero-based `column`.
+
+`SpreadsheetViewerSource` is available from the component entry and package root. The component entry also
+re-exports `LyraSourceCell`, `LyraTabularColumn`, `LyraTabularHit`, `LyraTabularReadRequest`,
+`LyraSourceSearchRequest` and `LyraSourceSearchResult` plus `LyraWorkbookHit`. Shared contracts can be imported with
+`import type` from `@aceshooting/lyra-ui/data-sources.js`.
+
+Body rows and columns are windowed, with the header using the same column window and
+`aria-colindex` preserving full-sheet positions. Search and anchors switch sheets and reveal
+offscreen columns before navigating. Public counts and raw-grid coordinates still describe the
+complete admitted sheet.
+
+**Exports:** `SpreadsheetViewerWorkbook` is the exact workbook type above, available from the
+component entry and as a type export from the package root. Its declared arrays are mutable types;
+the viewer's admitted runtime snapshot is frozen.
+
+**Methods:** With `dataSource` undefined, `search(query)` resolves the match count across every
+sheet's stringified cell values,
 ordered sheet then row then column, switching tabs as navigation crosses sheets (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 fails.
+**Events:** `lr-render-error` with `detail.error` when fetching, parsing, in-memory admission, or
+data-source validation/read/search fails.
 `lr-highlight-activate` (`detail: { highlightId }`) — 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, matchCountExact, activeIndex }`) — from
@@ -51,7 +141,7 @@ grid viewer's event contract; its registry capabilities advertise `textSelect: f
 structural cell covered by a `highlights` entry), `cell-highlight-action` (the native button
 filling a highlighted cell; focusable and emits `lr-highlight-activate`; its complete accessible
 name uses the localized `cellHighlightWithLabel` message with independent `{value}` and `{label}`
-placeholders), `rows`, `spinner`, `error`, and `anchor-live-region` (an aria-hidden, non-live shadow
+placeholders), `rows`, `spinner`, `error`, `search-status` (global source-search unavailable notice), and `anchor-live-region` (an aria-hidden, non-live shadow
 mirror of the latest anchor-jump message; the spoken copy is appended to the shared document-level
 polite sink only while the viewer and its composed ancestors are exposed to the accessibility tree).
 `data-row`, `cell`, `cell-highlight`, and `cell-highlight-action` are rendered inside the internal
@@ -81,13 +171,18 @@ Importing `spreadsheet-viewer.js` (this component's own registration entry) load
 installs the same registration lazily and exports `SPREADSHEET_VIEWER_TAG`
 (`'lr-spreadsheet-viewer'`) as a stable reference to the tag it eventually registers.
 
-Cells render through their workbook number formats: date and time cells localize with the
+Fetched cells render through their workbook number formats: date and time cells localize with the
 effective locale, other formatted numbers (percent, currency, zero-padded codes) show the
 workbook's formatted text, and General numbers use locale digits without grouping.
 
-Remote resources are capped at 25 MB, each sheet's used range at 10,000 rows and 1,000 columns, and
-each workbook at 256 sheets and 1,000,000 aggregate cells in those ranges; the ranges are checked
-before the grid is expanded. Row limits are per sheet, not cumulative across a workbook. Exceeding
-any ceiling surfaces the localized `documentPreviewResourceTooLarge` message instead of the
-workbook. ZIP input must be an Office Open XML workbook: OpenDocument and Numbers packages are
-refused, and binary (`.bin`) parts count against the cell ceiling by size.
+Remote resources use `maxBytes`. By default, each sheet's used range is bounded to 10,000 rows
+and 1,000 columns; `maxRows` and `maxColumns` configure those limits. Every workbook remains
+bounded to 256 sheets and 1,000,000 aggregate cells in those ranges, checked before grid expansion.
+In-memory row limits apply per sheet. Fetched ZIP workbooks additionally enforce `maxRows` across
+row elements encountered by the archive-wide XML admission scan. Archive-entry, expanded-byte,
+aggregate-cell and XML-node budgets also remain in force. Exceeding a ceiling surfaces
+the localized `documentPreviewResourceTooLarge` message instead of the workbook. ZIP input must
+be an Office Open XML workbook: OpenDocument and Numbers packages are refused, and binary
+(`.bin`) parts count against the cell ceiling by size. The fetched-workbook path yields after
+archive admission before SheetJS parsing, and between sheet projections; each parse/projection
+pass remains synchronous.

package/llms/components/lr-streaming-text-core.md

@@ -25,7 +25,7 @@ surface (`tabSize`, `htmlMode`, `withoutGfm`, `linkTarget`, `internalLinkPrefix`
 only which Markdown element Markdown mode composes differs: this variant renders
 `<lr-markdown-core>` (`../markdown/markdown-core.js`) instead of `<lr-markdown>`, so importing this
 entry point instead of `streaming-text.js` never references `<lr-markdown>`'s ~200-language
-dynamic-import table at all. A fenced code block whose language isn't a key in `languages` always
+dynamic-import table at all. A fenced code block whose language is absent from both `languages` and `languageLoaders`
 renders the plain-text fallback — there is no default/full-table highlighter here to fall back to,
 mirroring `<lr-markdown-core>`'s own contract.
 
@@ -39,7 +39,9 @@ Direction behaves exactly as described for `<lr-streaming-text>` (**Direction**
 uses `looksLikeMarkdown`, `plain`/`markdown` force their named paths; `languages?:
 Readonly<Record<string, ShikiLanguageInput>>` (property only) — forwarded verbatim to the composed
 `<lr-markdown-core>`'s own `languages` instead of `<lr-markdown>`'s (defaulting the composed
-element's own `languages` to `{}` when unset, unlike the full variant's `undefined`). The rest of
+element's own `languages` to `{}` when unset, unlike the full variant's `undefined`).
+`languageLoaders?: Readonly<Record<string, ShikiLanguageLoader>>` adds lazy loaders with the same
+concrete-grammar priority and combined-map reuse as `<lr-streaming-text>`. The rest of
 `<lr-markdown-core>`'s configuration surface forwards verbatim too, sharing the same properties,
 attribute names, and defaults described under `<lr-streaming-text>`'s own **Properties** above:
 `tabSize: number = 4` (attribute `tab-size`); `htmlMode: 'sanitize' | 'escape' | 'trusted' =

package/llms/components/lr-streaming-text.md

@@ -41,7 +41,11 @@ streaming.
 - `languages?: Readonly<Record<string, ShikiLanguageInput>>` (property only) — forwarded verbatim to
   the composed `<lr-markdown>`'s own `languages`, the same fine-grained language-grammar scoping
   `<lr-code-block>`/`<lr-markdown>` support. Unset leaves the composed element's own default
-  untouched.
+  untouched when `languageLoaders` is unset.
+- `languageLoaders?: Readonly<Record<string, ShikiLanguageLoader>>` (property only) — lazy grammar
+  loaders forwarded separately from concrete `languages` to the composed Markdown element.
+  Concrete entries win on duplicate keys; only requested loaders execute. The composed element
+  reuses its combined map until either property receives a new map object.
 
 The rest of `<lr-markdown>`'s configuration surface forwards verbatim too, each defaulting to
 exactly `<lr-markdown>`'s own default so leaving it unset renders identically to before these

package/llms/components/lr-table.md

@@ -120,51 +120,35 @@ cell: (row) => unknown }` — `cell` is required for every `editTrigger` except
   _other_ tinted columns' scale shifts around a cell that shows no tint at all. Define both on one
   column only when that override is the intent; to tint _and_ style, return only non-background
   declarations (`color`, `fontWeight`, `textAlign`, …) from `cellStyle`.
-- `columns[].editTrigger: 'double-click' | 'always'` — `'double-click'` opens one transient editor;
-  Enter commits and closes, Escape cancels and closes, and blur-after-change commits. `'always'`
-  renders an editor in
-  every body cell of that column, permanently:
-  - **Keyboard entry (`'double-click'` columns).** The resting (not-currently-editing) cell of a
-    `'double-click'` column is its own roving-focus stop — `tabindex="-1"`, carrying `[data-editable]`
-    — reachable once the row itself has focus: ArrowRight (ArrowLeft under RTL) enters at the first
-    editable cell in the row and steps forward through any further ones; ArrowLeft (ArrowRight under
-    RTL) steps back and, from the first editable cell, returns focus to the row. None of this is a Tab
-    stop — a table with a `'double-click'` column gains no new entry in the page's Tab order, only a
-    new arrow-reachable one — and a table with no `editTrigger` column at all renders no `tabindex`/
-    `[data-editable]` anywhere. `F2` or `Enter` on the focused cell opens its editor; `Enter` on the
-    row itself (no cell focused) still only activates the row. `editCell(rowKey, columnKey)` (see
-    Methods above) is the same open action as a public method. Closing the editor, by commit or by
-    cancel, returns focus to the cell that opened it.
-  - **Focus model (`'always'` columns).** 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/cell 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 `'text'`/`'number'` 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. A persistent `'select'` editor has no equivalent protection —
-    `<select>`/`<option>` carry no native dirty-value flag, so an out-of-band `rows` update to that
-    cell re-applies the selection even after the user has picked a different, uncommitted option.
-    `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 in both modes.
-    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.
-  - **Accessible name.** Each editor's name is `columns[].editLabel(row)` when the column defines
-    it, or otherwise the interpolated `tableEditCell` string (`Edit {column}`) — identical for every
-    row in that column, since the default has no row context. That default is adequate for
-    `'double-click'`, where at most one editor is ever open, but not for `'always'`: every row's
-    editor there is a permanent, individually focusable Tab stop, so leaving `editLabel` unset on an
-    `'always'` column exposes as many identically named controls as there are rows (e.g. fifty "Edit
-    Status" comboboxes), failing WCAG 2.4.6 and 1.3.1. Define `editLabel` for any `'always'` column
-    to give each row's editor its own name.
+- `columns[].editTrigger: 'double-click' | 'always'` — `'double-click'` opens one transient editor:
+  Enter commits/closes, Escape cancels/closes, and native `change` commits (including blur after
+  a text edit). `'always'` renders
+  persistent editors in every body cell of that column.
+  - **Keyboard entry (`'double-click'`).** Resting editable cells carry `tabindex="-1"` and
+    `[data-editable]`. From the focused row, ArrowRight enters the first editable cell and advances;
+    ArrowLeft moves back, returning to the row from the first cell (directions reverse under RTL).
+    These arrow-reachable cells add no page Tab stops. Without an `editTrigger` column, no editable
+    cell `tabindex`/`[data-editable]` is rendered. `F2`/`Enter` on the cell or
+    `editCell(rowKey, columnKey)` opens its editor; Enter on the row still activates the row.
+    Commit/cancel restores focus to the opening cell.
+  - **Focus (`'always'`).** Editors have no explicit `tabindex`: like row-expand toggles, they are
+    ordinary Tab stops outside header/row/cell roving focus. Tab walks down the column; arrows
+    navigate from the row stop but move the caret inside fields. Non-editable columns are unchanged.
+  - **Value binding.** Persistent text/number editors bind the `value` content attribute, not
+    `.value`, preserving native dirty-value semantics: new `rows` values update untouched editors
+    but cannot replace a typed draft. Persistent selects have no equivalent protection;
+    refreshed rows re-apply their selection even over an uncommitted choice. `lr-cell-edit` is
+    the only mutation channel; the table never mutates `row`.
+  - **Keys (`'always'`).** Enter emits `lr-cell-edit` and keeps field focus. `change` commits in
+    both modes. Escape neither changes the persistent editor nor cancels
+    the event, so ancestor dialogs/popovers can handle it.
+  - **Re-sorts/pages.** Keyed rows move the existing input with its draft; focus is restored to the
+    same logical cell after sorting. If filtering/pagination removes that row from the page, focus
+    is lost rather than moved to an unrelated replacement row.
+  - **Accessible names.** `editLabel(row)` overrides the default localized `tableEditCell`
+    (`Edit {column}`), which has no row context. The default is adequate for the single transient
+    editor. Always define `editLabel` for persistent editors: repeated identical names (e.g. fifty
+    “Edit Status” comboboxes) fail WCAG 2.4.6 and 1.3.1; each row needs a distinct editor name.
 - `hasHiddenPriorityColumns: boolean = false` (attribute `has-hidden-priority-columns`, reflected) —
   computed/read-only and true only while a priority column is actually hidden. It becomes false
   when `priorityColumnsVisible` reveals the columns. Measured via a `ResizeObserver` on
@@ -174,10 +158,20 @@ cell: (row) => unknown }` — `cell` is required for every `editTrigger` except
   lasting effect; it is recomputed on the next render or resize. The toggle remains available while
   a narrow table is revealed, even though this property truthfully reports false
 - `rows: readonly T[] = []` (attribute: false; clone-owned frozen collection bounded to the first
-  10,000 rows; reassign a new array to update — rebinding the array `rows`, `columns`,
+  `maxRows` rows, 10,000 by default; reassign a new array to update — rebinding the array `rows`, `columns`,
   `selectedRowKeys` or `expandedRowKeys` last received is a no-op). Records are retained
   here; one canonical `rowKey` projection omits blank and later-duplicate identities first-wins
   before filtering, counts, pagination, focus, actions, and events
+- `maxRows: number = 10000` (attribute `max-rows`) — row and controlled-key admission limit,
+  normalized to 1–100,000; non-finite values use the default. Configure it before assigning `rows`.
+  After changing it, assign a new row collection to deterministically supply rows excluded by the
+  previous cap. A cap change can also reread the original collection while the caller retains it;
+  recovery does not depend on keeping that source alive. Column inspection remains bounded to
+  10,000 source positions. Pagination still renders 100 rows by default and at most 500 per page.
+  Lowering the cap also trims retained selected and expanded key sets without emitting selection
+  or expansion events. Reassign controlled key collections after raising it to restore excluded keys.
+  At the key cap, existing keys retain priority over a newly toggled key; selection and expansion
+  events report the actual retained state.
 - `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
@@ -211,13 +205,14 @@ cell: (row) => unknown }` — `cell` is required for every `editTrigger` except
   (client-mode) sorting, ignoring pagination — the same set `columns[].footer(rows)`/
   `grandTotal(rows)`/the heat-tint domain already compute over. Read this instead of
   re-implementing filtering/sorting in a consumer that needs "what the grid currently shows" (e.g.
-  to export it). A fresh, frozen array on every read: mutating the result cannot reach or corrupt
-  the table's own internal state
+  to export it). The frozen projection retains its identity until row, sort or filter inputs change.
+  Row objects retain their existing identity contract
 - `pageRows: readonly T[]` (readonly; computed, no attribute) — `viewRows` sliced to the page
-  currently rendered in `<tbody>`. Same defensive-copy guarantee as `viewRows`
-- `rowsTruncated: boolean` (readonly) — `true` when the assigned `rows` held more than the 10,000
-  rows the snapshot keeps; the rest are not shown, counted, paged or exported. The localized
-  `row-limit` part makes this visible alongside the table.
+  currently rendered in `<tbody>`. This frozen projection retains its identity until its row,
+  sort, filter or page inputs change
+- `rowsTruncated: boolean` (readonly) — `true` when the assigned rows exceed admission capacity;
+  excluded rows are not shown, counted, paged or exported. The localized `row-limit` part reports
+  the number actually retained, and post-mount truncation changes are announced politely.
 - `rowKey?: (row: T) => K` (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
@@ -228,7 +223,7 @@ cell: (row) => unknown }` — `cell` is required for every `editTrigger` except
 - `selectionMode: 'none'|'single'|'multiple' = 'none'` (attribute `selection-mode`, reflected) —
   opt-in self-managed row selection; the default remains presentational
 - `selectedRowKeys: ReadonlySet<string | number> = new Set()` (attribute: false) — the single selection
-  store in every mode, bounded to 10,000 keys. Single mode enforces at most one key; multiple mode
+  store in every mode, bounded to `maxRows` keys. Single mode enforces at most one key; multiple mode
   toggles membership. Malformed and whitespace-only string keys are omitted, while valid
   unmatched/off-page keys remain controlled state for server pagination. Reads return immutable detached `ReadonlySet`
   facades; reassign a new set to update
@@ -238,7 +233,10 @@ cell: (row) => unknown }` — `cell` is required for every `editTrigger` except
   attribute clears the effective filter safely while retaining native removal readback; a later
   supplied value filters normally.
 - `filter?: (row: T, text: string) => boolean` (attribute: false) — typed predicate used by the
-  filter field; when omitted, rows are matched against their JSON representation
+  filter field; when omitted, rows are matched against their JSON representation. Default search
+  reuses locale-folded text for primitive and frozen scalar records. Mutable rows, nested containers,
+  accessors and custom `toJSON` retain per-query reads; reassign collections after data changes to
+  invalidate sorted and aggregate projections
 - `filterLabel?: string` (attribute `filter-label`) and `filterPlaceholder?: string`
   (attribute `filter-placeholder`) — omission localizes `tableFilterLabel`/
   `tableFilterPlaceholder`; any supplied string, including the built-in English text or `''`, is
@@ -329,7 +327,7 @@ cell: (row) => unknown }` — `cell` is required for every `editTrigger` except
   for the detail to carry and is reported through `expandedRowKeys` alone. An unrecognized attribute
   value falls back to the controlled behaviour rather than self-managing
 - `expandedRowKeys: ReadonlySet<string | number> = new Set()` (attribute: false; `ReadonlySet<K>` on a
-  parameterized element) — expanded state bounded to 10,000 keys. Who writes it depends on
+  parameterized element) — expanded state bounded to `maxRows` keys. Who writes it depends on
   `expansionMode`: under the default `'none'` the table never mutates it and consumers reassign it
   after `lr-row-expand-toggle`; under `'single'`/`'multiple'` the table writes it on each accepted
   activation, and a `preventDefault()` on `lr-row-expand-request` hands that one change back.
@@ -500,7 +498,7 @@ button, while `error` is set. Left unfilled, the built-in `[part='error']` `<lr-
 this slot's fallback content.
 
 **CSS parts:** `base`, `table`, `caption`, `head`, `header-cell`, `row`, `row-limit` (localized
-notice when the assigned row collection exceeds 10,000 entries), `cell`, `more-button`, `sort-icon`
+notice when the assigned row collection exceeds admission capacity), `cell`, `more-button`, `sort-icon`
 (each sort indicator), `sort-icon-active` (the active chevron, rotated per `sortDir`),
 `sort-icon-inactive` (the muted bidirectional indicator under `sort-indicators="all"`), `reveal-columns-button`
 (shown when priority columns are hidden or when a narrow allocation is currently force-visible),
@@ -648,65 +646,48 @@ declaration to retheme every internal scroll container in the library, including
 
 **Known gotchas:**
 
-- The built-in sort transaction toggles between `asc` and `desc`; a tri-state header with an
-  unsorted state remains consumer-owned. Veto `lr-sort-request` to suppress state change and commit.
-- `sortValue`/`cell` are read off the column object by identity. Mutating a column **in place**
-  (`t.columns[0].sortValue = …`) neither re-renders nor re-sorts; assign a new `columns` array.
-- both single and multiple row selection use `selectedRowKeys`; the component does not synthesize a
-  checkbox column, so a bulk-select UI still belongs in `headerCell()`/`cell()` callbacks.
-- A host `aria-label` (or native `ariaLabel` property) names the internal `<table role="grid">`.
-  Presence wins, including an explicitly empty string. Caller text in the host `aria-label` bypasses localization.
-- `caption: string = ''` — an optional visible `<caption>` (exposed as the `caption` CSS part). When
-  no host `aria-label` is present the caption also names the grid via
+- Sorting toggles `asc`/`desc`; consumers own any third, unsorted state. Veto `lr-sort-request`
+  to prevent state change and commit.
+- `sortValue`/`cell` use column identity. In-place mutation (`t.columns[0].sortValue = …`)
+  neither renders nor re-sorts; assign a new `columns` array.
+- Single/multiple selection both use `selectedRowKeys`. No checkbox column is synthesized;
+  implement bulk selection through `headerCell()`/`cell()`.
+- Host `aria-label` (or native `ariaLabel`) names the internal `<table role="grid">` verbatim,
+  bypassing localization; its presence wins even when empty. `caption: string = ''` supplies an
+  optional visible `<caption>` (`caption` part); without a host label it also names the grid through
   `aria-labelledby`.
-- A grid with **none** of host `aria-label` or `caption` logs a one-time
-  `console.warn` on first render in development builds only — an unnamed grid is an accessibility
-  defect that otherwise renders silently. Production and unknown/unbundled runtimes do not log it.
-- `revealColumnsLabel`/`columnsHideLabel` only ever reach the DOM on
-  `[part='reveal-columns-button']`, which itself only renders while at least one column declares
-  `priority`. Setting either label with no `priority` column is therefore always inert — it logs
-  the same shape of one-time, development-only, production-silent `console.warn` as the missing
-  accessible-name check above, rather than failing silently.
-- The grid has one roving `tabindex="0"` stop among header cells and one among body rows.
-  Left/Right/Home/End navigate headers; Up/Down/Home/End navigate rows. Down from a header enters
-  the body, Up from its first row returns to the header, and Enter/Space sort or activate.
-  A `priority`-hidden header/cell is skipped when computing 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. Delegated clicks and Enter/Space inspect the event's composed path for
-  native buttons, links, inputs, selects, textareas, summaries, and media with controls;
-  editable content; a non-negative `tabindex`; or role semantics (`button`, `checkbox`, `combobox`,
-  `listbox`, `menu`, `menuitem`, `option`, `radio`, `separator`, `slider`, `spinbutton`, `switch`,
-  `tab`, or `textbox`). Open-shadow custom controls expose those semantics through the composed path
-  and therefore keep their own action. A passive custom element — including a formatter or
-  display-only badge — remains part of the row activation surface instead of creating a dead zone
-  merely because its tag contains a hyphen. An opaque closed-shadow control can explicitly opt out
-  of row activation by adding `data-table-interactive` to its visible host.
-- `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"`.
-  Initial declarative loading stays silent; every later transition into either loading appearance
-  appends the localized loading text to the document's shared light-DOM polite sink, including
-  repeated cycles. `[part="base"]` exposes `aria-busy`, `[part="loading"]` is an `aria-hidden`
-  mirror rather than a live region, and 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.
-- For an externally authoritative value, re-key the row (`rowKey`) to recreate an `'always'`
-  editor, or use the transient `editTrigger: 'double-click'` editor. Persistent text/number editors
-  otherwise retain dirty drafts; persistent select editors re-apply refreshed selections, as
-  described under `columns[].editTrigger` above.
+  Without either name, first render issues one development-only `console.warn`; production and
+  unknown/unbundled runtimes stay silent.
+- `revealColumnsLabel`/`columnsHideLabel` only label `[part='reveal-columns-button']`, which
+  requires a `priority` column. Setting either without one is inert and issues the same one-time,
+  development-only warning; production and unknown/unbundled runtimes stay silent.
+- Headers and body rows each have one roving `tabindex="0"`. Left/Right/Home/End navigate headers;
+  Up/Down/Home/End navigate rows. Down enters the body from a header; Up from the first row
+  returns to the header. Enter/Space sort or activate. Priority-hidden columns are skipped.
+- `cell()` controls retain their actions. Delegated clicks/Enter/Space inspect the composed path
+  for buttons, links, inputs, selects, textareas, summaries, media with controls, editable content,
+  non-negative `tabindex`, or roles `button`, `checkbox`, `combobox`, `listbox`, `menu`, `menuitem`,
+  `option`, `radio`, `separator`, `slider`, `spinbutton`, `switch`, `tab`, `textbox`.
+  Open-shadow controls expose these semantics. Passive custom elements (formatters/badges) remain
+  row activation surfaces; a hyphenated tag alone is not an exemption. Closed-shadow controls can
+  opt out with `data-table-interactive` on their visible host.
+- Fixed layout (explicit or resolved from `'auto'`) uses the first row, including headers, to
+  determine widths when none are declared. Revealing priority columns through
+  `[part='reveal-columns-button']` can therefore resize every column. Fixed layout ignores
+  `columns[].minWidth`/`maxWidth`; declare `width` for a specific size.
+- Skeletons cannot stabilize content-sized columns: default `table-layout: auto` placeholders
+  lack intrinsic width, so arriving data re-measures columns as any data change can. Declare
+  `columns[].width` or `layout="fixed"` for identical loading/loaded widths. Initial declarative
+  loading is silent; each later transition into either loading appearance, including repeated
+  cycles, appends localized loading text to the shared light-DOM polite sink. `base` exposes
+  `aria-busy`; `loading` is an `aria-hidden` mirror, not a live region. Placeholders disable their
+  own `<lr-skeleton>` announcements to avoid one announcement per row.
+- `cellTitle` returning `''`/`undefined` omits `title`, preserving ancestor tooltips; inline editing
+  also suppresses it. Some screen readers replace the cell's accessible name with `<td title>`
+  rather than supplementing its content (also a caveat of `lr-stat`'s `exactValue`). Use it only
+  to expand visible information, never as the sole source of information.
+- To replace a persistent editor with an externally authoritative value, re-key its row (`rowKey`)
+  or use transient `editTrigger: 'double-click'`. Otherwise text/number editors retain dirty
+  drafts, while persistent selects re-apply refreshed selections (see `editTrigger`).
 
 ---