@ixfx/components 0.17.0 → 0.17.1

package/docs-user/grid-list.md

@@ -412,6 +412,8 @@ Parts: `part="icon"` and `part="badge"` on the wrappers this adds.
 | `setItems(items)` | Replace the collection. Selection / cursor keep any key still present; vanished keys are deselected silently and held pending (see [View state](#view-state)). |
 | `appendItems(items)` | Add to the end. Scroll, selection and cursor untouched; no reflow animation. |
 | `updateItem(key, item)` | Replace one item. A visible cell re-renders in place; an offscreen one updates when scrolled in. |
+| `updateItems(entries)` | Replace many items at once — the batched form of `updateItem`. See [Batched updates](#batched-updates). |
+| `refreshItem(key)` | Re-render one cell **without** changing `items`. See [Refreshing a cell](#refreshing-a-cell). |
 | `removeItems(keys)` | Remove items. Removed keys drop out of selection / cursor silently and are held pending. |
 | `clearItems()` | Drop everything. Resets selection / cursor and emits one empty `list-select`; the keys are held pending, so re-adding them restores the selection. |
 
@@ -424,6 +426,49 @@ key-based. Data-mode events carry the data value as `detail.item` and
 Duplicate keys are warned about once; the first occurrence wins for key-based
 operations.
 
+#### Batched updates
+
+`updateItems(entries)` applies many replacements with **one** array copy and
+**one** source rebuild:
+
+```typescript
+grid.updateItems([
+  { key: 'a', item: { ...fileA, name: 'Renamed' } },
+  { key: 'b', item: { ...fileB, thumb: newThumb } },
+]);
+
+// A Map works too:
+grid.updateItems(new Map([['a', newA], ['b', newB]]));
+```
+
+It has the same semantics as the equivalent run of `updateItem` calls: unknown
+keys are ignored, selection / cursor / scroll are untouched, and an entry whose
+`item` is the identical object already at that key is skipped. If nothing
+changes, `items` keeps its identity and nothing is emitted.
+
+**Use `updateItems` rather than a loop of `updateItem`s** when you have more
+than one row to change. A loop pays one array copy per call, so changing n rows
+costs n copies; the batched form pays one. On a 20k-item collection, replacing
+500 rows measured ~22 ms as a loop versus ~0.7 ms as one batch (happy-dom).
+
+#### Refreshing a cell
+
+`updateItem(key, item)` with the **same object** that is already at `key` is a
+no-op — the array is not copied and nothing is emitted. That is the right
+behaviour when you only want to push the *data* through.
+
+If instead you want to redraw a cell whose data is unchanged — because the
+adapter renders something that lives outside the item, such as a thumbnail that
+just finished loading — use `refreshItem(key)`:
+
+```typescript
+grid.refreshItem('a');   // re-renders the cell for 'a'; `items` is untouched
+```
+
+The adapter's `render` is called again for that cell, so it picks up the new
+state. The `items` array keeps its identity, so nothing is copied and the
+collection is not rebuilt.
+
 ---
 
 ## Grouping
@@ -608,6 +653,26 @@ Inserting is O(items): one `appendItems` costs ~5 ms at 5k items and ~21 ms at
 50k (the source and search index are rebuilt, and `items` is copied); the
 element-mode equivalents are ~8 ms at 2k and ~16 ms at 10k.
 
+### Mutation API
+
+`src/grid-list/grid-list.perf.test.ts` guards the data-mode mutation API with
+**work counters** — how many times the adapter's `key` is called per mutation.
+That number must not scale with the item count. Run it with:
+
+```sh
+pnpm test:perf            # all perf suites, verbose
+PERF_REPORT=1 pnpm vitest run src/grid-list/grid-list.perf.test.ts
+```
+
+The mutation paths keep a key → raw index map, so a lookup is O(1) rather than
+an O(n) scan of the array:
+
+- `updateItem(key, item)` — one lookup and one array copy. Passing the
+  identical object is a no-op (no copy, no emit).
+- `updateItems(entries)` — many replacements, one copy, one rebuild.
+- `appendItems(items)` — the appended items are added to the map; the existing
+  ones are not re-scanned.
+
 Things that keep the per-frame paths flat, and that the benchmark guards:
 
 - **Cell recycling.** Cells are keyed by a stable cell id, not the item key, so

package/docs-user/index.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
-  "version": "0.17.0",
-  "generated": "2026-11-09T22:52:59.151Z",
+  "version": "0.17.1",
+  "generated": "2026-11-10T11:14:57.413Z",
   "components": [
     {
       "name": "ac-text",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",