@jarenjs/collection 0.83.2

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+/** Public headless collection geometry and vnode projection. */
+export { createCollection } from './collection.js';
+export { createCollectionInteraction } from './interaction.js';

package/dist/types/interaction.d.ts

@@ -0,0 +1,92 @@
+/** Identity-based interaction. Range intent stores endpoint keys in a declared query/snapshot. */
+/** @param {any} options */
+export declare function createCollectionInteraction(options: any): {
+    state: () => {
+        focus: any;
+        pending: any;
+        selection: {
+            mode: string;
+            keys: never[];
+            ranges: never[];
+            exclusions: never[];
+            query: any;
+            snapshot: any;
+        };
+    };
+    selected: (key: any) => boolean;
+    focusIndex: (index: any, column?: number) => {
+        state: string;
+        reason: string;
+        focus?: undefined;
+        index?: undefined;
+        column?: undefined;
+    } | {
+        reason?: undefined;
+        state: string;
+        focus: null;
+        index?: undefined;
+        column?: undefined;
+    } | {
+        reason?: undefined;
+        focus?: undefined;
+        state: string;
+        index: any;
+        column: number;
+    } | {
+        reason?: undefined;
+        focus?: undefined;
+        key: string;
+        index: any;
+        column: number;
+        state: string;
+    };
+    cancelPending(): void;
+    update(next: any): {
+        state: string;
+        reason: string;
+        focus?: undefined;
+        index?: undefined;
+        column?: undefined;
+    } | {
+        reason?: undefined;
+        state: string;
+        focus: null;
+        index?: undefined;
+        column?: undefined;
+    } | {
+        reason?: undefined;
+        focus?: undefined;
+        state: string;
+        index: any;
+        column: number;
+    } | {
+        state: string;
+    };
+    toggle: (key: any) => {
+        state: string;
+        reason: string;
+    } | {
+        reason?: undefined;
+        state: string;
+    };
+    selectAll(): void;
+    clear(): void;
+    restore(intent: any): {
+        state: string;
+        reason: string;
+    } | {
+        reason?: undefined;
+        state: string;
+    };
+    key(event: any): {
+        state: string;
+        reason: string;
+    } | {
+        reason?: undefined;
+        state: string;
+    } | {
+        state: string;
+        key: any;
+        column: any;
+    };
+};

package/docs/COLLECTION.md

@@ -0,0 +1,110 @@
+# Collection contract
+
+## Engine and rendering
+
+`createCollection(options)` from `@jarenjs/collection` needs `count`, `keyAt(index)`,
+`getItem(index)` and `renderCell(row,column,index)`. Keys are unique stable strings;
+`null` denotes an unloaded placeholder. Duplicate loaded keys throw `TypeError`.
+Accessors visit only the credited viewport and pins. The engine imports core/view
+only and has no DOM, app, database or worker import.
+
+Geometry options include `rowSize` (44), `columnSize` (160), `columnCount` (1),
+`overscan` (2), `columnOverscan` (1), `maxRows` (128), `maxColumns` (32) and
+`maxCells` (840). Row and column windows are independent. `rowPins`, `columnPins`,
+`rowPinBudget` (2) and `columnPinBudget` (2) include focus pins in the same limits.
+Pinned rows/columns remain at the leading viewport edge. With base windows R/C,
+row/column mounts are at most R+rowPins and C+columnPins; all cells must also fit
+`maxCells`. Credit exhaustion returns an empty explicit refusal, never a partially
+rendered success. Hidden viewports have no rows, cells or focus pins.
+
+The row and column axes independently accept `maxMeasurements`, `measurementBytes`,
+`maxColumnMeasurements` and `columnMeasurementBytes`. Eviction reverts a size to
+its estimate. `measure(index,key,size,axis='row')` preserves the stored keyed row
+anchor, including compensation for evicted measurements. `update(next)` reindexes
+retained measurements via `indexOf(key)`; it must run after the host changes source
+order. Changing `rowSize` or `columnSize` invalidates corresponding measurements.
+
+`viewport({top,left,width,height})`, `layout()`, `view(interaction,id)`, `stats()`,
+`position()`, `options()`, `pin(rows,columns)`, `snapshot()`, `restore(anchor)` and
+idempotent `dispose()` form the controller API. `scrollToOffset`, `scrollToIndex`
+and `scrollToKey` return outcomes; missing key lookup returns `unsupported-seek`.
+The optional column argument of `scrollToIndex` scrolls both axes. Indices locate
+rows in the current query and are never persisted as entity identity. A missing
+anchor key falls back to its clamped previous position; a changed query starts at
+zero. A new snapshot re-resolves the stable key in the same query.
+
+## DOM ownership and accessibility
+
+Import `mountCollection`, `createCollectionWidget` and `mountProviderCollection`
+from `@jarenjs/collection/component`, and link `@jarenjs/collection/styles/collection.css`.
+`mountCollection(host, options)` owns its element, scroll listener, keyboard/click/
+focus/composition handlers, resize observers and frames. `requestFrame`,
+`cancelFrame` and `observe(element, callback) => unsubscribe` can be injected by the
+host. `dispose` is adapted to the existing widget `unmount` hook, preserving the
+renderer lifecycle. Failed mounts clean acquired resources too.
+
+```js
+import { createCollectionWidget } from '@jarenjs/collection/component';
+const widgets = { collection: createCollectionWidget({
+  count: rows.length, keyAt: (i) => rows[i].id, indexOf: (key) => index.get(key) ?? -1,
+  getItem: (i) => rows[i], renderCell: (row, column) => columns[column].render(row),
+  columnCount: columns.length, label: 'Catalog'
+}) };
+const vnode = ['jaren-widget', { name: 'collection', props: { height: 440 } }];
+```
+
+The DOM adapter's conservative `maxExtent` defaults to 8,000,000 CSS pixels per
+axis; larger extents return `error / scroll-extent` before reaching CSS layout.
+The pure engine can compute larger ranges; this is an explicit browser refusal.
+`direction: 'rtl'` normalizes negative browser scroll offsets and aligns columns
+with logical inline positions. `height` controls the viewport; its host controls
+width. `measured:true` observes content; `measureRow(element,index)` can supply
+host-specific height measurement. The default measures the tallest cell content
+plus cell padding. `maxMeasurementWork` (64) bounds measured rows per pass; resize
+notifications coalesce into one frame. The same keyed renderer handles controlled
+inputs, so scroll and measurement patches preserve node identity and selection.
+
+`role` is `grid` by default or `listbox`. Grid cells carry logical row/column
+indices; list options carry logical position/set size. `totalKnown:false` exposes
+unknown total as -1 rather than loaded count. `label` names the collection.
+`createCollectionInteraction(options)` is the headless counterpart: arrows,
+Home/End (Ctrl for the whole grid), PageUp/Down, Space selection, Enter activation
+and Escape return focus. Arrow direction follows RTL. Editing targets and
+composition bypass collection shortcuts. Browser-native editing keys retain their
+normal caret behavior.
+
+`focusIndex` realizes a loaded key or records a pending transient index while
+retaining existing focus. The DOM exposes `aria-activedescendant` only after the
+referenced element exists. Loading exposes `aria-busy`; source refusal clears
+pending realization. `removedKeys` tells interaction to resolve a removal fallback.
+`onRealize`, `onActivate`, `returnFocus`, `onIntent` and `onChange` are host hooks;
+only bounded observations and JSON intent need enter app state.
+
+Selection contains stable `keys`, or query/snapshot-scoped `mode:'all'` with
+`exclusions`, or one range with stable `fromKey`/`toKey` endpoints. Shift ranges
+survive asynchronous endpoint realization. `maxSelectedKeys` (4096) bounds explicit
+keys/exclusions. `state`, `selected`, `toggle`, `selectAll`, `clear`, `restore`,
+`cancelPending` and `update` expose the model. Range membership for rendered rows
+uses the host's current key lookup; exports resolve endpoints over the full ordered
+snapshot. Key selection survives eviction and query changes; scoped all/range
+selection cannot be exported against another identity. Authoritative writes must
+still recheck membership/revision.
+
+## Data and complete output
+
+`mountProviderCollection(host,coordinator,options)` uses exactly the same controller
+and interaction. The host injects `createCollectionCoordinator(provider)` from
+`@jarenjs/app`. The component requests missing visible ranges, publishes loading/
+refusal state, and preserves edit pages within the coordinator's existing credits.
+Eviction cannot destroy an active editor; if its pinned page prevents admission,
+the coordinator returns `pinned-page-credits` until the host releases the pin.
+
+The mounted provider handle exposes `mounted`, `coordinator`, `next`, `snapshot`,
+`output`, `print` and async idempotent `dispose`. `next` is the continuation
+operation for unknown-total sequential sources. Printing and exporting use the same
+complete snapshot stream, with the host supplying a transactional sink; neither
+reads mounted DOM. The source must advertise `completeExport`. See the normative
+[app provider contract](../../../packages/app/docs/COLLECTION-PROVIDER.md).
+
+Actual assistive technology, physical touch and native OS IME qualification remain
+separate from automated browser evidence; see [measurements](MEASUREMENTS.md).

package/docs/MEASUREMENTS.md

@@ -0,0 +1,62 @@
+# Collection evidence
+
+The retained reference fixtures and budgets remain unchanged. The installed
+Node/Bun consumer runs both fixed and measured profiles using only public package
+exports, without a retained virtualizer dependency. The reference remains in the
+benchmark workspace for differential checks and future downstream qualification.
+
+<!--fact:collection.measurements-->
+
+Measured on v24.19.0, linux/x64, AMD Ryzen 9 5900HX with Radeon Graphics.
+
+| Consumer | Rows | Reference range ms | Native range/view/interaction p95 ms | Cells | Cached rows / bytes | Measurements / accounted bytes | Heap MiB | Teardown ms |
+|---|---:|---:|---:|---:|---|---|---:|---:|
+| catalog | 10000 | 0.020 | 1.450 | 170 | 256 / 9732 | 256 / 8192 | 19.49 | 0.177 |
+| archive-stock | 75000 | 8.080 | 0.307 | 160 | 256 / 10244 | 256 / 8448 | 92.43 | 0.047 |
+
+The component and coordinator browser bundle is 16815 gzip bytes. Reference range calls do less work than native vnode and interaction calls; the comparison deliberately publishes that cost rather than claiming equal workloads.
+
+<!--/fact-->
+
+The Node measurements include range calculation, vnode projection and headless
+interaction. The reference timing is range-only and is therefore cheaper work.
+The historical adoption report also includes other engines; its heap and RSS
+cannot be treated as isolated virtualizer memory. Measurement bytes account for
+UTF-8 keys and numeric payloads; runtime heap separately includes Map/array overhead.
+
+The browser matrix covers keyed anchor preservation, both axes, RTL, pinned rows,
+resize, CSS zoom, synthetic touch events, keyboard selection, pending realization,
+editing/composition events, extent limits, source examples and disposal. The
+near-ceiling fixture uses lazy row access. It never allocates the entire logical
+source in the browser. Browser script timings cover synchronous DOM reconciliation;
+paint scheduling is separate. Physical touch devices, actual assistive technology,
+native OS IME sessions and real downstream cutover remain unqualified.
+
+<!--fact:collection.browser-->
+
+Linux container, Node v24.20.0, 4 browser workers. Each sample set contains 40 synchronous viewport changes after the near-ceiling check.
+
+| Engine / version | DOM interaction p95 ms | Earlier full-matrix p95 ms | Peak cells | CSS extent / final offset | Remaining resources |
+|---|---:|---:|---:|---|---:|
+| chromium 149.0.7827.55 | 10.30 | 8.60 | 170 | 7920000 / 7919560 | 0 |
+| firefox 151.0 | 11.00 | 12.00 | 170 | 7920000 / 7919560 | 0 |
+| webkit 26.5 | 15.00 | 17.00 | 170 | 7920000 / 7919560 | 0 |
+
+The earlier loaded WebKit sample exceeded the fixed-profile 16 ms target. Browser latency varies with concurrent load; these measurements do not establish a universal frame-time guarantee.
+
+<!--/fact-->
+
+Reproduce the portable and Node measurements with `npm run test:packed` and
+`npm run benchmark:collection`. After `npm run website:build`, run
+`COLLECTION_MEASURE=1 npx playwright test -c packages/website/playwright.config.js packages/website/e2e/collection.spec.js packages/website/e2e/lifecycle.spec.js --workers=4`
+on the qualified browser host, then `npm run docs:derive`. Ordinary gates omit the
+measurement environment variable and leave committed timings unchanged. The earlier
+full-matrix sample is retained separately so rerunning does not erase a measured loss.
+True peak heap remains unmeasured; sampled heap and process peak RSS are reported.
+
+The browser's conservative CSS extent ceiling refuses larger extents before they
+reach layout. The pure range engine supports larger logical counts. Source-backed
+sequential providers retain unknown totals and refuse index/key jumps and complete
+export. Complete export is qualified for immutable resident array sources and
+bounded complete SQLite resident snapshots. The browser download example uses a
+finite output spool and refuses an oversized export before making a download.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@jarenjs/collection",
+  "private": false,
+  "version": "0.83.2",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./component": {
+      "types": "./dist/types/component/index.d.ts",
+      "default": "./src/component/index.js"
+    },
+    "./package.json": "./package.json",
+    "./styles/collection.css": "./styles/collection.css"
+  },
+  "files": [
+    "src/",
+    "dist/types/",
+    "styles/",
+    "docs/",
+    "ARCHITECTURE.md"
+  ],
+  "description": "Bounded virtual lists and grids with keyed interaction and injected data providers",
+  "author": "joham",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/jarenjs.git",
+    "directory": "components/collection"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "jaren",
+    "collection",
+    "virtual",
+    "grid"
+  ],
+  "scripts": {
+    "build": "npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
+    "prepack": "npm run build:types"
+  },
+  "dependencies": {
+    "@jarenjs/core": "^0.83.2",
+    "@jarenjs/view": "^0.83.2",
+    "@jarenjs/app": "^0.83.2"
+  }
+}

package/src/collection.js

@@ -0,0 +1,134 @@
+//@ts-check
+import { createVirtualAxis, virtualIndices } from '@jarenjs/core/virtual';
+
+/** Stable DOM identity; JSON escaping also supports lone surrogate code units in JSON keys.
+ * @param {string} id @param {string} key @param {number} [column] */
+export function collectionItemId(id, key, column) {
+  return `${id}-r-${encodeURIComponent(JSON.stringify(key))}${column === undefined ? '' : `-c-${column}`}`;
+}
+
+/**
+ * Create a source-independent collection. Accessors run only for credited mounted rows.
+ * Measurements and pins have their own finite credits. Oversized DOM extents refuse explicitly.
+ * @param {any} options
+ */
+export function createCollection(options) {
+  let config = { rowSize: 44, overscan: 2, columnCount: 1, columnSize: 160, columnOverscan: 1,
+    maxRows: 128, maxColumns: 32, maxCells: 840, rowPinBudget: 2, columnPinBudget: 2,
+    maxExtent: Number.MAX_SAFE_INTEGER, query: '', snapshot: '', ...options };
+  for (const name of ['maxRows', 'maxColumns', 'maxCells', 'rowPinBudget', 'columnPinBudget'])
+    if (!Number.isSafeInteger(config[name]) || config[name] < 0) throw new RangeError(`Invalid ${name}`);
+  const rowAxis = createVirtualAxis({ count: config.count, estimateSize: config.rowSize,
+    maxMeasurements: config.maxMeasurements, maxBytes: config.measurementBytes });
+  const columnAxis = createVirtualAxis({ count: config.columnCount, estimateSize: config.columnSize,
+    maxMeasurements: config.maxColumnMeasurements, maxBytes: config.columnMeasurementBytes });
+  let viewport = { top: 0, left: 0, width: 0, height: 0 };
+  let anchor = null, disposed = false;
+  let focusPins = { rows: [], columns: [] };
+  const keyAt = (index) => config.keyAt(index);
+  const refusal = (state, reason) => ({ state, reason, rows: [], columns: [] });
+  function layout() {
+    if (disposed) return refusal('error', 'disposed');
+    const visible = viewport.height > 0 && viewport.width > 0;
+    const rows = rowAxis.range({ viewport: visible ? viewport.height : 0, offset: viewport.top, overscan: config.overscan });
+    const columns = columnAxis.range({ viewport: visible ? viewport.width : 0, offset: viewport.left, overscan: config.columnOverscan });
+    if (rows.extent > config.maxExtent || columns.extent > config.maxExtent) return refusal('error', 'scroll-extent');
+    if (rows.end - rows.start > config.maxRows || columns.end - columns.start > config.maxColumns)
+      return refusal('budget-exhausted', 'dom-credits');
+    const rowIndices = virtualIndices(rows, visible ? [...(config.rowPins ?? []), ...focusPins.rows] : [], config.count, config.rowPinBudget);
+    const columnIndices = virtualIndices(columns, visible ? [...(config.columnPins ?? []), ...focusPins.columns] : [], config.columnCount, config.columnPinBudget);
+    if (rowIndices.state !== 'ready' || columnIndices.state !== 'ready') return refusal('budget-exhausted', 'pin-credits');
+    if (rowIndices.indices.length * columnIndices.indices.length > config.maxCells) return refusal('budget-exhausted', 'dom-credits');
+    const seen = new Set();
+    const mounted = rowIndices.indices.map((index) => {
+      const key = keyAt(index);
+      if (key != null && (typeof key !== 'string' || seen.has(key))) throw new TypeError('Collection keys must be unique strings');
+      if (key != null) seen.add(key);
+      return { index, key, start: rowAxis.position(index), size: rowAxis.size(index), pinned: (config.rowPins ?? []).includes(index) };
+    });
+    return { state: 'ready', rowRange: rows, columnRange: columns, rows: mounted,
+      columns: columnIndices.indices.map((index) => ({ index, start: columnAxis.position(index), size: columnAxis.size(index),
+        pinned: (config.columnPins ?? []).includes(index) })) };
+  }
+  function saveAnchor() { anchor = rowAxis.anchor(viewport.top, keyAt, config.query); }
+  function restoreAnchor() {
+    const restored = rowAxis.restore(anchor, config.indexOf, config.query);
+    viewport.top = Math.min(restored.offset, Math.max(0, rowAxis.extent() - viewport.height));
+    return viewport.top;
+  }
+  function scrollToOffset(offset) {
+    if (disposed) return { state: 'error', reason: 'disposed' };
+    viewport.top = offset;
+    const result = layout();
+    if (result.state !== 'ready') return result;
+    viewport.top = result.rowRange.offset; saveAnchor();
+    return { state: 'ready', offset: viewport.top, left: viewport.left };
+  }
+  return {
+    rowAxis, columnAxis, layout,
+    options() { return config; },
+    position() { return { ...viewport }; },
+    viewport(next) { viewport = { ...viewport, ...next }; const result = layout();
+      if (result.state === 'ready') { viewport.top = result.rowRange.offset; viewport.left = result.columnRange.offset; saveAnchor(); }
+      return result; },
+    update(next) {
+      config = { ...config, ...next };
+      rowAxis.update({ count: config.count, estimateSize: config.rowSize, indexOf: config.indexOf });
+      columnAxis.update({ count: config.columnCount, estimateSize: config.columnSize });
+      restoreAnchor(); saveAnchor(); return layout();
+    },
+    measure(index, key, size, axis = 'row') {
+      const engine = axis === 'column' ? columnAxis : rowAxis;
+      const result = engine.measure(index, key, size);
+      if (result.state === 'ready') { restoreAnchor(); saveAnchor(); }
+      return { ...result, offset: viewport.top };
+    },
+    pin(rows = [], columns = []) { focusPins = { rows, columns }; return layout(); },
+    restore(value) { anchor = value; const offset = restoreAnchor(); saveAnchor(); return scrollToOffset(offset); },
+    snapshot() { return anchor ? { ...anchor, snapshot: config.snapshot } : null; },
+    scrollToOffset,
+    /** @param {number} index @param {number} [column] */
+    scrollToIndex(index, column) {
+      if (!Number.isSafeInteger(index) || index < 0 || index >= config.count) return { state: 'error', reason: 'invalid-index' };
+      if (column !== undefined) viewport.left = columnAxis.position(Math.max(0, Math.min(config.columnCount - 1, column)));
+      return scrollToOffset(rowAxis.position(index));
+    },
+    scrollToKey(key) {
+      if (!config.indexOf) return { state: 'error', reason: 'unsupported-seek' };
+      return this.scrollToIndex(config.indexOf(key));
+    },
+    view(interaction = null, id = 'collection') {
+      const result = layout();
+      const grid = config.role !== 'listbox';
+      const selection = (key) => interaction?.selected(key) ?? false;
+      const active = interaction?.state().focus;
+      const rows = result.rows.map((row) => {
+        const rowKey = JSON.stringify(row.key == null ? [0, row.index] : [1, row.key]);
+        const rowId = row.key == null ? `${id}-p-${row.index}` : collectionItemId(id, row.key);
+        const rowTop = row.pinned ? Math.max(row.start, viewport.top) : row.start;
+        return ['div', { key: rowKey, 'data-row': row.index, 'data-key': row.key,
+          role: grid ? 'row' : 'option', id: grid ? undefined : rowId,
+          'aria-rowindex': grid ? row.index + 1 : undefined,
+          'aria-posinset': grid ? undefined : row.index + 1,
+          'aria-setsize': grid ? undefined : config.totalKnown === false ? -1 : config.count,
+          'aria-selected': grid ? undefined : selection(row.key), class: row.pinned ? 'jc-row jc-pin' : 'jc-row', style: {
+            position: 'absolute', top: `${rowTop}px`, height: `${row.size}px`, width: '100%', zIndex: row.pinned ? 2 : 0 } },
+        ...result.columns.map((column) => ['div', { key: column.index, class: column.pinned ? 'jc-cell jc-pin' : 'jc-cell',
+          role: grid ? 'gridcell' : undefined,
+          id: grid ? `${rowId}-c-${column.index}` : undefined,
+          'data-column': column.index, 'aria-colindex': grid ? column.index + 1 : undefined,
+          'aria-selected': grid ? selection(row.key) : undefined,
+          'data-active': active?.key === row.key && active?.column === column.index,
+          style: { position: 'absolute', [config.direction === 'rtl' ? 'right' : 'left']:
+            `${column.pinned ? Math.max(column.start, viewport.left) : column.start}px`,
+          width: `${column.size}px`, height: '100%', zIndex: column.pinned ? 1 : 0 } },
+        ['div', { class: 'jc-content' }, row.key == null ? (config.loadingLabel ?? 'Loading…') : config.renderCell(config.getItem(row.index), column.index, row.index)]])];
+      });
+      return ['div', { class: 'jc-surface', style: { position: 'relative', height: `${result.rowRange?.extent ?? 0}px`,
+        width: `${result.columnRange?.extent ?? 0}px` } }, ...rows];
+    },
+    stats() { const result = layout(); return { rows: result.rows.length, columns: result.columns.length,
+      cells: result.rows.length * result.columns.length, rowMeasurements: rowAxis.stats(), columnMeasurements: columnAxis.stats() }; },
+    dispose() { disposed = true; rowAxis.dispose(); columnAxis.dispose(); anchor = null; focusPins = { rows: [], columns: [] }; },
+  };
+}