@ixfx/components 0.7.3 → 0.7.5

package/docs-user/data-grid.md

@@ -65,6 +65,30 @@ grid.getRowKey = (row, i) => row.key ?? row.id ?? String(i);
 
 Reassign `rows` to update. Sorting is derived from `sortState`.
 
+When the row set changes without a wholesale replace — rows spliced in, rows
+filtered out — the new rows fade in and, for ~0.3s afterwards, every row slides
+to its new position instead of snapping (so an inserted row's neighbours make
+room and a removed row's gap closes). Skipped under `prefers-reduced-motion:
+reduce`; timing is `--data-grid-row-move-duration` (default `200ms`).
+
+### Streaming appends — `appendRows()`
+
+Reassigning `rows` re-runs `_applySort([...rows])` + `_rebuildFlat()` every
+time — O(n log n) per batch, quadratic over a full load. When feeding the grid
+from a stream (paged fetch, incremental scan), use `appendRows()` instead:
+
+```ts
+for await (const batch of stream) {
+  grid.appendRows(batch);
+}
+```
+
+It still sets `rows` to a new array reference (reactivity preserved) but
+**bypasses the `rows` setter's full rebuild** — the derived arrays are extended
+over the appended slice only. When a sort is active the new rows show unsorted
+for one frame, then a single coalesced re-sort runs. Scroll position, selection
+and cursor are preserved across the append.
+
 ---
 
 ## Selection & interaction
@@ -76,7 +100,19 @@ Reassign `rows` to update. Sorting is derived from `sortState`.
 
 See `ixfx-vertical-list` README for mode table. Data-grid adds checkbox column in `checked` mode.
 
-Programmatic: selection is `Set<string>` of row keys (`_selectedKeys` private, read via events).
+### Programmatic selection & cursor
+
+```ts
+grid.selectedKeys;                 // ReadonlySet<string> of selected row keys
+grid.selectedKeys = ['r3', 'r7'];  // replace (clamped to known rows, single-mode keeps the last)
+grid.selectKeys(['r3', 'r7']);     // alias of the setter
+
+grid.tickleRow('r7');              // move the row cursor + scroll it into view
+grid.tickledKey;                   // row key under the cursor, or undefined
+```
+
+The setter fires `datagrid-select` `{ selectedKeys, previous }` only when the
+selection actually changes.
 
 ---
 
@@ -194,6 +230,10 @@ Demo: `Score` is random float `0–100` with 0–3 decimals, `align:'right'`, `f
 
 Gear menu (`ixfx-menu-trigger` placement `bottom-end`, `inset-area: block-end span-inline-end`) lists `Columns` (check-items) and `Group by` (radio). Toggle visibility via `col.visible=false` or menu. Event: `datagrid-column-visibility` `{key, visible}`.
 
+`column-menu` attribute: `auto` (default) renders the gear menu; `none`
+suppresses it entirely. `col.visible` + `datagrid-column-visibility` still give
+full external control, so `none` lets a host own the column-visibility UI.
+
 Other events: `datagrid-column-reorder` `{from,to,columns}`, `datagrid-column-resize` `{key,width}`, `datagrid-cell-click` `{rowKey,colKey,rowIndex,colIndex}`, `datagrid-cell-edit` `{rowKey,colKey,oldValue,newValue}`.
 
 ---
@@ -213,11 +253,31 @@ Grid is focusable (`tabindex=0`). When not editing:
 
 ---
 
+## Incremental search
+
+A built-in type-ahead popover with **navigate** (cursor + scroll to best match),
+**select** (matching rows become the selection), and **filter** (non-matching
+rows dropped from the flat list) modes. No default shortcut:
+
+```typescript
+grid.registry.invoke('list.search.filter');   // or .navigate / .select
+```
+
+A row is matched against `rowSearchText(row)` — by default its visible cells'
+values joined by a space; override with the `rowSearchText` property. `select`
+mode needs `selection-mode="multiple"` to hold more than one row. Character
+highlights are not drawn (a match position spans multiple cells). `filterPredicate`
+(a `(row) => boolean` property) filters rows directly. `search-modes` limits the
+offered modes. Full model: [`docs/infra-incremental.md`](../../docs/infra-incremental.md).
+
+---
+
 ## CSS variables & parts
 
 | Variable | Default | Description |
 |---|---|---|
 | `--data-grid-row-height` | `28px` | Row height |
+| `--data-grid-row-move-duration` | `200ms` | Insertion / removal animation duration |
 | `--data-grid-header-height` | `32px` | Header height |
 | `--data-grid-bg` | `var(--surface-3)` | Grid background |
 | `--data-grid-header-bg` | `var(--surface-2)` | Header background |
@@ -239,10 +299,18 @@ No `::part` exports yet (header/row/cell are shadow-internal).
 | `startRowEdit` | `(rowKey)` | Open row editors |
 | `stopEdit` | `()` | Cancel editors |
 | `getVisibleRange` | `()=>{startRow,endRow,startCol,endCol}` | Virtual window |
+| `appendRows` | `(rows)` | Add rows without a full re-sort/rebuild — for streaming |
+| `selectKeys` / `set selectedKeys` | `(keys)` | Replace the selection by row key |
+| `tickleRow` | `(key)` | Move the row cursor and scroll it into view |
+
+| Getter | Type | |
+|---|---|---|
+| `selectedKeys` | `ReadonlySet<string>` | Selected row keys |
+| `tickledKey` | `string \| undefined` | Row key under the cursor |
 
 ---
 
 ## Demo
 
-`demo/data-grid.html` + `demo/data-grid.ts`: 200 rows, `Department` random, `Score` float, `Name`/`Department` editable (`user` mode, slow double-click; `Tab`/`Up`/`Down` navigation; `Enter` from tickled row). Controls: Selection/Interaction/Group by/Editability + `Edit first row` (manual).
+`demo/data-grid.html` + `demo/data-grid.ts`: 200 rows, `Department` random, `Score` float, `Name`/`Department` editable (`user` mode, slow double-click; `Tab`/`Up`/`Down` navigation; `Enter` from tickled row). Controls: Selection/Interaction/Group by/Editability/`column-menu` + `Edit first row` (manual), a `Stream +5,000 rows` button (`appendRows`), and `selectKeys` / `tickleRow` buttons.
 

package/docs-user/detail-list.md

@@ -87,8 +87,17 @@ list.addItem('Image 01.png');
 const li = document.createElement('li');
 li.textContent = 'Custom item';
 list.addItem(li);
+
+// removeItem / removeItems return a Promise that resolves once the row is gone
+list.removeItems(list.selectedItems);
 ```
 
+Rows added mid-list collapse + fade in; `removeItem` / `removeItems` collapse +
+fade them out before detaching, so the rows around them slide to make or close
+the gap. A bulk populate isn't animated, and it's all skipped under
+`prefers-reduced-motion: reduce` (`--ixfx-list-item-move-duration`, default
+`200ms`).
+
 ---
 
 ## Item types
@@ -191,6 +200,35 @@ list.clearSelection();     // Clear all selections
 list.selectAll();          // Select all visible items (if permitted)
 ```
 
+### Key-based selection
+
+`Element` references die when the item set is rebuilt (re-fetch, re-sort,
+filter). Drive selection by a stable **`data-key`** (or `data-value`) instead —
+the Element API is unchanged, the key API is additive. Object items built from
+`items` / a provider get their key stamped automatically from `keyProperty`.
+
+```typescript
+list.selectKeys(['row-3', 'row-7']);   // replace selection; unknown keys ignored
+list.addSelectedKeys(['row-9']);       // multi-select modes only
+list.removeSelectedKeys(['row-3']);
+list.selectedKeys;                     // ReadonlySet<string>
+
+list.focusKey('row-7');                // move cursor to an item + scroll into view
+list.tickledKey;                       // key under the cursor, or undefined
+
+list.addEventListener('list-select', ({ detail }) => {
+  console.log([...detail.selectedKeys]);   // carried alongside detail.selected
+});
+```
+
+Restore a selection across a data reload:
+
+```typescript
+const keep = [...list.selectedKeys];
+list.items = await fetchRows();         // Element refs are stale...
+list.selectKeys(keep);                  // ...keys still resolve
+```
+
 ---
 
 ## Interaction modes
@@ -275,7 +313,7 @@ With wrapping:
 
 ## Incremental search
 
-Press Ctrl+F (or Cmd+F on Mac) to open the search overlay. Type to filter items in real-time using fuzzy matching.
+A built-in type-ahead popover with **navigate** / **select** / **filter** modes — see [`docs/infra-incremental.md`](../../docs/infra-incremental.md). No default shortcut; open it with `list.registry.invoke('list.search.filter')` (or `.navigate` / `.select`). A filter change re-runs the column geometry automatically.
 
 Search matches against `data-search-label` (or `textContent` as fallback). Use `data-search-label` to match against a different string than what's displayed:
 

package/docs-user/grid-list.md

@@ -0,0 +1,298 @@
+# `ixfx-grid-list`
+
+A virtualised grid of items — thumbnails, cards, or arbitrary slotted markup —
+with selection, keyboard navigation, and captions. Windowed rendering keeps the
+DOM small regardless of item count; the same component does a wrapping grid, a
+single vertical column, or a horizontally-scrolling strip.
+
+---
+
+## Contents
+
+1. [Quick start](#quick-start)
+2. [Items & keys](#items--keys)
+3. [Sizing & layout](#sizing--layout)
+4. [Captions](#captions)
+5. [Orientation](#orientation)
+6. [Selection](#selection)
+7. [Cursor](#cursor)
+8. [Events](#events)
+9. [Keyboard](#keyboard)
+10. [Virtualisation](#virtualisation)
+11. [CSS parts](#css-parts)
+12. [Choosing a list component](#choosing-a-list-component)
+
+---
+
+## Quick start
+
+```html
+<ixfx-grid-list id="grid" selection-mode="single" item-size="120" gap="8">
+  <div class="tile" data-key="a" data-label="Apple">🍎</div>
+  <div class="tile" data-key="b" data-label="Banana">🍌</div>
+  <div class="tile" data-key="c" data-label="Cherry">🍒</div>
+</ixfx-grid-list>
+
+<script type="module">
+  import '@ixfx/components/grid-list';
+
+  const grid = document.querySelector('#grid');
+  grid.addEventListener('list-select', ({ detail }) => {
+    console.log([...detail.selectedKeys]);
+  });
+</script>
+```
+
+Items are **light-DOM children**. Each is projected into its own virtualised
+cell via a named `<slot>`. Add or remove children at any time — a
+`MutationObserver` picks the change up and re-renders.
+
+```typescript
+import type { GridListElement } from '@ixfx/components/grid-list';
+
+const grid = document.querySelector<GridListElement>('#grid')!;
+for (const item of data) {
+  const el = document.createElement('div');
+  el.className = 'tile';
+  el.dataset.key = item.id;
+  el.dataset.label = item.name;
+  el.textContent = item.glyph;
+  grid.appendChild(el);
+}
+```
+
+---
+
+## Items & keys
+
+| Item attribute | Purpose |
+|---|---|
+| `data-key` (or `data-value`) | Stable identity — for key-based selection, `focusKey`, and `visibleKeys()`. Recommended on every item. |
+| `data-label` | Caption text (see [Captions](#captions)). Alternatively put the text in a `[data-grid-list-caption]` descendant. |
+| `not-checked` | Item can't be tickled / checked (skipped by the cursor). |
+| `hidden` | Item is excluded from layout and navigation. |
+
+---
+
+## Sizing & layout
+
+| Property / attribute | Default | Description |
+|---|---|---|
+| `itemSize` / `item-size` | `160` | Cell width in px. Also the square's height for `separate` / `under` / `overlaid` / `hidden`. |
+| `gap` | `8` | Gap between cells, px. |
+| `captionHeight` / `caption-height` | `24` | Height reserved for the caption band in `separate` / `under`. |
+
+Values are clamped and rounded. Changing `item-size` / `gap` re-anchors the
+scroll on the item nearest the viewport centre (zoom stays put rather than
+jumping to the top-left corner).
+
+---
+
+## Captions
+
+`caption-style` — how the caption relates to the content:
+
+| value | layout |
+|---|---|
+| `hidden` | No caption. Cell height = `item-size`. |
+| `separate` | Content in a square; caption a **detached** label below it. Square and caption highlight independently (macOS Finder icon view). |
+| `under` (default) | One box: content on top, caption strip **inside** it below. One selection outline. |
+| `overlaid` | Caption floats over the content. |
+
+`caption-align` — `left` \| `middle` (default) \| `right`. Text alignment; also
+positions the pill in `separate`.
+
+`overlaid` only:
+
+- `caption-position` — `top` \| `middle` \| `bottom` (default).
+- `caption-backdrop` — `scrim` (default, flat translucent panel) \| `gradient`
+  (fades away from the caption edge) \| `blur` (frosted) \| `none` (text +
+  shadow, no panel).
+
+```html
+<ixfx-grid-list caption-style="separate" caption-align="left"></ixfx-grid-list>
+<ixfx-grid-list caption-style="overlaid" caption-position="top" caption-backdrop="gradient"></ixfx-grid-list>
+```
+
+---
+
+## Orientation
+
+`orientation`:
+
+| value | layout | scrolls |
+|---|---|---|
+| `grid` (default) | wraps across as many columns as fit | vertically |
+| `row` | a single row of items | **horizontally** |
+| `column` | a single column of items | vertically |
+
+`row` is the virtualised horizontal strip; `column` is the recommended
+large-list replacement for `ixfx-vertical-list`.
+
+---
+
+## Selection
+
+`selection-mode` (`none` \| `single` \| `multiple`) and `interaction-mode`
+(`standard` \| `implicit` \| `manual` \| `checked` \| `sticky` \| `vscode`) match
+the other list components — see the `ixfx-vertical-list` README for the mode
+table.
+
+### Element API
+
+```typescript
+grid.select(el);              // replace with one item
+grid.selectMany([a, b]);      // selection-mode="multiple" only
+grid.deselect(el);
+grid.clearSelection();
+grid.selectAll();
+grid.selectedItems;           // ReadonlySet<Element>
+```
+
+### Key-based selection
+
+`Element` references die when the item set is rebuilt. With a `data-key` on each
+item, drive selection by key instead — additive, the Element API is unchanged.
+
+```typescript
+grid.selectKeys(['a', 'c']);        // replace; unknown keys ignored
+grid.addSelectedKeys(['b']);        // multi-select modes only
+grid.removeSelectedKeys(['a']);
+grid.selectedKeys;                  // ReadonlySet<string>
+
+grid.addEventListener('list-select', ({ detail }) => {
+  console.log([...detail.selectedKeys]);   // alongside detail.selected
+});
+```
+
+Restore across a reload:
+
+```typescript
+const keep = [...grid.selectedKeys];
+grid.replaceChildren(...(await fetchTiles()));
+grid.selectKeys(keep);
+```
+
+---
+
+## Cursor
+
+The "tickled" cursor follows hover (mouse) or arrow keys (keyboard).
+
+```typescript
+grid.focusKey('b');      // move the cursor to an item and scroll it into view
+grid.tickledKey;         // key under the cursor, or undefined
+```
+
+---
+
+## Events
+
+All bubble and are `composed`.
+
+| Event | Detail | When |
+|---|---|---|
+| `list-select` | `{ selected, previous, selectedKeys }` | Selection changes by any means |
+| `list-activate` | `{ item }` | Double-click or `Enter` on an item |
+| `list-item-click` | `{ item }` | Single click / `Enter` |
+| `list-tickle` | `{ item }` | Cursor moves onto an item |
+| `grid-list-viewport-change` | `{ visibleKeys }` | Scroll, resize, or content change — the rendered window moved |
+
+---
+
+## Keyboard
+
+| Key | `grid` | `row` / `column` |
+|---|---|---|
+| `ArrowLeft` / `ArrowRight` | ∓1 item | ∓1 item |
+| `ArrowUp` / `ArrowDown` | ∓/± one row | ∓1 item |
+| `Home` / `End` | first / last | first / last |
+| `PageUp` / `PageDown` | ± one screen of rows | ± one screen of items |
+| `Enter` | activate | activate |
+| `Space` | toggle selection | toggle selection |
+| `Escape` | clear selection | clear selection |
+| `Ctrl` / `Cmd` + `A` | select all (multi modes) | select all (multi modes) |
+
+---
+
+## Incremental search
+
+A built-in type-ahead popover with **navigate** / **select** / **filter** modes.
+No default shortcut — open it via a command on `grid.registry`:
+
+```typescript
+grid.registry.invoke('list.search.filter');   // or .navigate / .select
+```
+
+Search matches `data-label` (or `[data-grid-list-caption]` text, then
+`data-search-label`, then `textContent`). Filter mode genuinely removes items
+from the virtualised layout. Add a page-level highlight rule to see matched
+characters:
+
+```css
+::highlight(grid-list-search) { background: var(--accent); color: var(--accent-text); }
+```
+
+`filterPredicate` (an `(el: Element) => boolean` property) filters items directly,
+independent of search. Limit modes with `search-modes="navigate filter"`. Full
+model: [`docs/infra-incremental.md`](../../docs/infra-incremental.md).
+
+---
+
+## Virtualisation
+
+Only the cells in (or near) the viewport are in the DOM.
+
+```typescript
+grid.count;             // total items
+grid.renderedCount;     // cells currently in the shadow DOM
+grid.visibleKeys();     // data-key of items in the current window
+```
+
+`grid-list` handles tens of thousands of children in every orientation.
+
+---
+
+## Scroll fade & insertion animation
+
+The scrollable edge is fade-masked whenever there's more content that way — a
+zero-JS `scroll-timeline` mask (`scroll-fade-y` for `grid` / `column`,
+`scroll-fade-x` for `row`). See `docs/infra-theming.md` → *Scroll Fade*; tune the
+reach with `--scroll-fade-width` (default `30px`).
+
+When the child list changes **mid-list** (not a first populate or a wholesale
+`replaceChildren`), the cells slide to their new position rather than snapping —
+so an inserted item's neighbours make room and a removed item's gap closes — and
+a freshly inserted cell also fades in. The transition is confined to a short
+window after the mutation, so it never fires during scroll virtualisation, and
+it's suppressed under `prefers-reduced-motion: reduce`. Duration:
+`--grid-list-item-move-duration` (default `200ms`).
+
+---
+
+## CSS parts
+
+| Part | Element |
+|---|---|
+| `viewport` | The scroll container |
+| `item` | A cell |
+| `thumb` | The square holding the slotted content |
+| `caption` | The caption element (absent for `caption-style="hidden"`) |
+
+Host CSS custom properties: `--grid-list-item-bg`, `--grid-list-radius`,
+`--grid-list-gap`, `--grid-list-item-move-duration` (insertion animation,
+default `200ms`), `--scroll-fade-width` (edge fade reach, default `30px`), plus
+the shared `--item-bg-*` / `--accent` theme tokens.
+
+---
+
+## Choosing a list component
+
+- **Large lists** — prefer `ixfx-grid-list` with `orientation="column"` over
+  `ixfx-vertical-list`. `vertical-list` renders every child; `grid-list` is
+  windowed.
+- **Small, declarative, richly-slotted lists** — `ixfx-vertical-list` stays the
+  simpler choice.
+- **Horizontal virtualised strip** — `ixfx-grid-list` with `orientation="row"`.
+- **Tabular data with columns / sort / grouping / inline edit** —
+  `ixfx-data-grid`.

package/docs-user/incr-search.md

@@ -1,8 +1,18 @@
 # Incremental Search
 
 Utilities for incremental (type-ahead) search over data collections or DOM-backed lists.
-You can use the low-level `createIncrSearch` for data, `createElementIncrSearch` for
-DOM elements, or `IncrSearchTreeController` for tree and Miller list components.
+
+- **`ListSearchController`** — the shared brain behind the built-in search
+  popover in `ixfx-grid-list` / `ixfx-vertical-list` / `ixfx-detail-list` /
+  `ixfx-data-grid` / `ixfx-tree-list` / `ixfx-miller-list`. Three modes
+  (navigate / select / filter), driven by `list.search.*` commands. See
+  [`docs/infra-incremental.md`](../../docs/infra-incremental.md) — start there
+  for anything component-facing.
+- **`createIncrSearch`** — the low-level fuzzy engine (fzf) both the controller
+  and the helpers below are built on.
+- **`createElementIncrSearch`** / **`IncrSearchTreeController`** — *deprecated*
+  filter-only controllers driven by an external `<input>`. Kept for standalone
+  use; components now use `ListSearchController`.
 
 ## Plain UL list
 

package/docs-user/index.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
-  "version": "0.7.3",
-  "generated": "2026-09-06T18:27:10.873Z",
+  "version": "0.7.5",
+  "generated": "2026-09-08T18:17:07.322Z",
   "components": [
     {
       "name": "ac-text",
@@ -63,6 +63,11 @@
       "summary": "Primitives for typical form layout with responsive label positioning and data binding.",
       "path": "docs-user/form.md"
     },
+    {
+      "name": "grid-list",
+      "summary": "A virtualised grid of items — thumbnails, cards, or arbitrary slotted markup —",
+      "path": "docs-user/grid-list.md"
+    },
     {
       "name": "grouped-item-lister",
       "summary": "A meta-component that renders a typed item list using any sub-component you supply. Items can be displayed in a single sub-component (_ungrouped_ mode) or split into labelled groups, each with its own",

package/docs-user/llms.txt

@@ -23,6 +23,7 @@ import '@ixfx/components/data-grid';
 - [dock](docs-user/dock.md): Dockable, movable panels like VS Code / Photoshop. Drag a panel by its
 - [editable-label](docs-user/editable-label.md): Inline editable text components. `ixfx-editable-number` extends `ixfx-editable-label` with drag-to-adjust and fill-bar visualization.
 - [form](docs-user/form.md): Primitives for typical form layout with responsive label positioning and data binding.
+- [grid-list](docs-user/grid-list.md): A virtualised grid of items — thumbnails, cards, or arbitrary slotted markup —
 - [grouped-item-lister](docs-user/grouped-item-lister.md): A meta-component that renders a typed item list using any sub-component you supply. Items can be displayed in a single sub-component (_ungrouped_ mode) or split into labelled groups, each with its own
 - [icons](docs-user/icons.md): A centralized SVG icon system for `@ixfx/components`. Icons are stored by name, can be overridden globally, and all components that use a given icon re-render automatically when it changes.
 - [incr-search](docs-user/incr-search.md): Utilities for incremental (type-ahead) search over data collections or DOM-backed lists.

package/docs-user/tree.md

@@ -367,7 +367,28 @@ Keyboard navigation follows the crumb path. Arrow keys move between breadcrumb s
 
 ## Incremental search
 
-Wire up a text input to filter and highlight matching nodes using `IncrSearchTreeController`:
+`ixfx-tree-list` and `ixfx-miller-list` have a **built-in type-ahead popover**
+with three modes:
+
+- **navigate** — expands the match's ancestors and moves the cursor to it; ↑/↓
+  cycle between matches; Enter activates and closes.
+- **select** — the selection becomes the set of matching nodes.
+- **filter** — non-matching nodes (and branches with no matching descendant) are
+  hidden; branches with a match auto-expand so the match is visible.
+
+No default shortcut — open it via a command on `el.registry`:
+
+```typescript
+el.registry.invoke('list.search.navigate'); // or .select / .filter
+```
+
+Limit the offered modes with the `search-modes` attribute
+(`search-modes="navigate filter"`). Full model: [`docs/infra-incremental.md`](../../docs/infra-incremental.md).
+
+### Deprecated: `IncrSearchTreeController`
+
+The external-`<input>` filter-only controller still works but is superseded by
+the built-in popover.
 
 ```typescript
 import { IncrSearchTreeController } from '@ixfx/components';
@@ -463,6 +484,18 @@ Each column is a separate `role="listbox"` with `aria-label` showing the parent
 
 ---
 
+## Row animation
+
+Rows that appear — a branch expanded, a node added to `root` / the model —
+collapse + fade in, and the rows below slide down to make room. Rows that
+disappear — a branch collapsed, a node removed — are kept as fading "ghost" rows
+until they've collapsed out, so the gap closes smoothly. Above ~50 rows changing
+at once the animation is skipped, as it is entirely under
+`prefers-reduced-motion: reduce`. Duration: `--ixfx-list-item-move-duration`
+(default `200ms`).
+
+---
+
 ## CSS variables
 
 ### Shared / themed
@@ -493,6 +526,7 @@ These are set by the global theme and inherited by all tree components.
 | `--tree-indent` | `20px` | Indentation per depth level |
 | `--tree-item-height` | `28px` | Height of each row |
 | `--tree-caret-size` | `10px` | Expand/collapse caret size |
+| `--ixfx-list-item-move-duration` | `200ms` | Row enter / leave animation duration |
 
 ### `ixfx-miller-list` specific
 

package/docs-user/vertical-list.md

@@ -313,13 +313,21 @@ list.addItem(myElement);
 // In checked mode, add a row that shows no checkbox and can't be checked
 list.addItem('Header', { notChecked: true });
 
-// Remove a specific element
+// Remove a specific element (returns a Promise that resolves once it's gone)
 list.removeItem(element);
+list.removeItems(list.selectedItems);
 
 // Remove all items and clear selection
 list.clearItems();
 ```
 
+Items added mid-list — via `addItem`, a direct `appendChild`, or a framework
+binding — collapse + fade in, and the rows below slide down to make room.
+`removeItem` / `removeItems` play the reverse (collapse + fade out) and then
+detach, so the gap closes smoothly. A bulk populate isn't animated, and
+everything is skipped under `prefers-reduced-motion: reduce`. Tune the timing
+with the `--ixfx-list-item-move-duration` custom property (default `200ms`).
+
 ### Reading the selection
 
 ```typescript
@@ -341,6 +349,48 @@ list.addEventListener('list-select', ({ detail }) => {
 });
 ```
 
+### Key-based selection
+
+`Element` references die the moment you rebuild the item set (re-fetch, external
+re-sort, filter). Give each item a **`data-key`** (or `data-value`) and drive
+selection by that stable string instead. The Element API keeps working
+unchanged — the key API is additive.
+
+```html
+<ixfx-vertical-list selection-mode="multiple">
+  <li data-key="a">Apple</li>
+  <li data-key="b">Banana</li>
+  <li data-key="c">Cherry</li>
+</ixfx-vertical-list>
+```
+
+```typescript
+list.selectKeys(['a', 'c']);          // replace selection; unknown keys ignored
+list.addSelectedKeys(['b']);          // multi-select modes only
+list.removeSelectedKeys(['a']);
+list.selectedKeys;                    // ReadonlySet<string>, e.g. Set { 'b', 'c' }
+
+list.focusKey('b');                   // move the cursor to an item + scroll it into view
+list.tickledKey;                      // key under the cursor, or undefined
+
+// list-select carries keys too
+list.addEventListener('list-select', ({ detail }) => {
+  console.log([...detail.selectedKeys]);
+});
+```
+
+Restore a selection across a data reload:
+
+```typescript
+const keep = [...list.selectedKeys];
+list.setItems(await fetchRows());     // Element refs are now stale
+list.selectKeys(keep);               // ...but the keys still resolve
+```
+
+The `data-key` requirement is documented, not enforced: items without a key
+simply never appear in `selectedKeys` and can't be targeted by `selectKeys` /
+`focusKey`.
+
 ### Filtering by state
 
 Use `selectedFilter()` to iterate over items based on their selection or checked state. Pass `'selected'`, `'checked'`, or `'either'` to filter accordingly:
@@ -454,7 +504,13 @@ The element must be focused (click it or tab to it) before keyboard navigation w
 
 ## Incremental search
 
-Press **Ctrl+F** (or **Cmd+F**) to open the search overlay. Typing filters items in real time using fuzzy matching. Matched text in plain `<li>` items is highlighted via the [CSS Highlight API](https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API).
+A built-in type-ahead popover with three modes — **navigate** (cursor jumps to the best match, ↑/↓ cycle), **select** (matches become the selection), **filter** (non-matches hidden). See [`docs/infra-incremental.md`](../../docs/infra-incremental.md) for the full model, conversions between modes, and the `search-modes` attribute.
+
+There is **no default shortcut**. Open it by invoking one of the commands on `list.registry`:
+
+```typescript
+list.registry.invoke('list.search.filter');   // or .navigate / .select
+```
 
 ### Adding the page-level highlight rule
 

package/llms.txt

@@ -23,6 +23,7 @@ import '@ixfx/components/data-grid';
 - [dock](docs-user/dock.md): Dockable, movable panels like VS Code / Photoshop. Drag a panel by its
 - [editable-label](docs-user/editable-label.md): Inline editable text components. `ixfx-editable-number` extends `ixfx-editable-label` with drag-to-adjust and fill-bar visualization.
 - [form](docs-user/form.md): Primitives for typical form layout with responsive label positioning and data binding.
+- [grid-list](docs-user/grid-list.md): A virtualised grid of items — thumbnails, cards, or arbitrary slotted markup —
 - [grouped-item-lister](docs-user/grouped-item-lister.md): A meta-component that renders a typed item list using any sub-component you supply. Items can be displayed in a single sub-component (_ungrouped_ mode) or split into labelled groups, each with its own
 - [icons](docs-user/icons.md): A centralized SVG icon system for `@ixfx/components`. Icons are stored by name, can be overridden globally, and all components that use a given icon re-render automatically when it changes.
 - [incr-search](docs-user/incr-search.md): Utilities for incremental (type-ahead) search over data collections or DOM-backed lists.