@joewinke/jatui 0.26.0 → 0.27.1

package/dist/virtual/rowWindowCore.js

@@ -0,0 +1,510 @@
+/**
+ * rowWindowCore — the framework-free engine behind `createRowWindow`
+ * (jatui-u6d4e.1, spec: jat docs/design/datatable-virtualisation-group-rows.md §3.1).
+ *
+ * Variable-height windowing for SPACER-ROW layouts: the consumer renders
+ * `paddingTop` px of spacer, the rendered slice in document flow, then
+ * `paddingBottom` px of spacer. Nothing is absolutely positioned, so a
+ * `<table>` keeps `table-layout: fixed` widths and native sticky `<thead>`s.
+ *
+ * Layering:
+ *   - Pure helpers (`normalizeStickyLevels`, `activeStickyIndices`,
+ *     `extractWindowIndices`, `layoutWindow`, `findScrollRoot`) hold the
+ *     window policy — threshold, pinned keys, sticky group headers, spacer
+ *     maths. DOM-free, so `npm run test:unit` covers them under node:test.
+ *   - `RowWindowEngine` drives `@tanstack/virtual-core` (an OPTIONAL peer,
+ *     which is why this module only ships behind `@joewinke/jatui/virtual`)
+ *     for measured sizes, scroll-offset tracking and scroll-anchor correction
+ *     when a row above the viewport changes height.
+ *   - `createRowWindow.svelte.ts` is the thin runes wrapper.
+ */
+import { Virtualizer, defaultRangeExtractor, elementScroll, observeElementOffset, observeElementRect, observeWindowOffset, observeWindowRect, windowScroll } from '@tanstack/virtual-core';
+export const EMPTY_SNAPSHOT = Object.freeze({
+    items: Object.freeze([]),
+    paddingTop: 0,
+    paddingBottom: 0,
+    totalSize: 0,
+    windowed: false,
+    count: 0
+});
+// ─── Pure helpers ───────────────────────────────────────────────────────────
+/**
+ * `stickyIndices` accepts one flat list (one header level) or one list per
+ * level, outermost first (`[projectHeaderIdx[], epicHeaderIdx[]]`). Returns the
+ * per-level form, each level sorted ascending with out-of-range entries dropped.
+ */
+export function normalizeStickyLevels(input, count) {
+    if (!input || input.length === 0)
+        return [];
+    const levels = Array.isArray(input[0])
+        ? input
+        : [input];
+    return levels.map((level) => level
+        .filter((i) => Number.isInteger(i) && i >= 0 && i < count)
+        .slice()
+        .sort((a, b) => a - b));
+}
+/** Last element of sorted `arr` that is `<= max` and `> floor`, else -1. */
+function lastAtOrBelow(arr, max, floor) {
+    let lo = 0;
+    let hi = arr.length - 1;
+    let found = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (arr[mid] <= max) {
+            found = arr[mid];
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return found > floor ? found : -1;
+}
+/**
+ * The sticky header that is "active" at `startIndex` (the first visible item),
+ * per level. For level n it is the last level-n header at or above
+ * `startIndex` that comes AFTER level n-1's active header, so an epic header
+ * from the previous project never sticks under the current project's header.
+ */
+export function activeStickyIndices(levels, startIndex) {
+    const out = [];
+    let floor = -1;
+    for (const level of levels) {
+        const idx = lastAtOrBelow(level, startIndex, floor);
+        if (idx >= 0) {
+            out.push(idx);
+            floor = idx;
+        }
+    }
+    return out;
+}
+/**
+ * The rangeExtractor: which indices to render for a visible `range`. The
+ * visible slice plus overscan, every pinned index, and the active sticky
+ * header of each level, sorted and de-duplicated. Below `threshold`, all.
+ */
+export function extractWindowIndices(range, policy) {
+    const { count } = range;
+    if (count <= 0)
+        return [];
+    if (policy.threshold > 0 && count < policy.threshold) {
+        return Array.from({ length: count }, (_, i) => i);
+    }
+    const base = defaultRangeExtractor(range);
+    const extra = [];
+    for (const i of activeStickyIndices(policy.stickyLevels, range.startIndex))
+        extra.push(i);
+    for (const i of policy.pinnedIndices)
+        if (i >= 0 && i < count)
+            extra.push(i);
+    if (extra.length === 0)
+        return base;
+    const lo = base.length ? base[0] : Infinity;
+    const hi = base.length ? base[base.length - 1] : -Infinity;
+    const outside = extra.filter((i) => i < lo || i > hi);
+    if (outside.length === 0)
+        return base;
+    return Array.from(new Set([...base, ...outside])).sort((a, b) => a - b);
+}
+/**
+ * Turn virtual-core's measured items (absolute offsets that include
+ * `scrollMargin`) into the spacer-row snapshot the consumer renders.
+ */
+export function layoutWindow(virtualItems, opts) {
+    const items = [];
+    let prevEnd = 0;
+    for (let k = 0; k < virtualItems.length; k++) {
+        const v = virtualItems[k];
+        const start = v.start - opts.scrollMargin;
+        const end = start + v.size;
+        items.push({
+            index: v.index,
+            key: v.key,
+            start,
+            size: v.size,
+            end,
+            gapBefore: k === 0 ? 0 : Math.max(0, start - prevEnd),
+            sticky: opts.stickySet.has(v.index),
+            pinned: opts.pinnedSet.has(v.index)
+        });
+        prevEnd = end;
+    }
+    const totalSize = Math.max(opts.totalSize, prevEnd);
+    return {
+        items,
+        paddingTop: items.length ? Math.max(0, items[0].start) : 0,
+        paddingBottom: items.length ? Math.max(0, totalSize - prevEnd) : totalSize,
+        totalSize,
+        windowed: opts.windowed,
+        count: opts.count
+    };
+}
+/** Cheap structural equality so unchanged layouts don't churn reactive state. */
+export function sameSnapshot(a, b) {
+    if (a.paddingTop !== b.paddingTop ||
+        a.paddingBottom !== b.paddingBottom ||
+        a.totalSize !== b.totalSize ||
+        a.windowed !== b.windowed ||
+        a.count !== b.count ||
+        a.items.length !== b.items.length) {
+        return false;
+    }
+    for (let i = 0; i < a.items.length; i++) {
+        const x = a.items[i];
+        const y = b.items[i];
+        if (x.index !== y.index ||
+            x.key !== y.key ||
+            x.start !== y.start ||
+            x.size !== y.size ||
+            x.gapBefore !== y.gapBefore ||
+            x.sticky !== y.sticky ||
+            x.pinned !== y.pinned) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * `scrollRoot: 'auto'` — the nearest ancestor that actually scrolls
+ * vertically: `overflow-y` is auto/scroll/overlay AND its content overflows it.
+ * An `overflow-auto` wrapper that grows with its content never scrolls (the
+ * dash TaskTable case), so it is skipped in favour of the real scroller.
+ * Returns `null` for "the window".
+ */
+export function findScrollRoot(node, overflowY) {
+    let el = node.parentElement;
+    while (el) {
+        const tag = el.tagName.toUpperCase();
+        if (tag === 'BODY' || tag === 'HTML')
+            return null;
+        const o = overflowY(el);
+        if ((o === 'auto' || o === 'scroll' || o === 'overlay') && el.scrollHeight > el.clientHeight) {
+            return el;
+        }
+        el = el.parentElement;
+    }
+    return null;
+}
+function isWindowLike(x) {
+    return !!x && typeof x === 'object' && 'document' in x && 'scrollY' in x;
+}
+/** The ResizeObserver constructor of a document's window, if it has one. */
+function resizeObserverOf(view) {
+    return view?.ResizeObserver;
+}
+/**
+ * Imperative windowing engine. One per list. Feed it the render list with
+ * `setItems`, mount it with `attach(anchor)`, register each rendered element
+ * with `measure`, and read `snapshot` (or listen via `onChange`).
+ */
+export class RowWindowEngine {
+    opts;
+    v;
+    keys = [];
+    estimates = [];
+    keyIndex = new Map();
+    getItemKey = (i) => i;
+    estimateSize = () => 0;
+    pinnedKeys = [];
+    pinnedIndices = [];
+    pinnedSet = new Set();
+    stickyInput = [];
+    stickyLevels = [];
+    stickySet = new Set();
+    rangeExtractor = defaultRangeExtractor;
+    scrollMargin = 0;
+    anchorEl = null;
+    root = null;
+    rootUnsub = null;
+    anchorRO = null;
+    prevOverflowAnchor = '';
+    unmountVirtualizer = null;
+    nodes = new Map();
+    pendingScroll = null;
+    sweepQueued = false;
+    destroyed = false;
+    snapshot = EMPTY_SNAPSHOT;
+    constructor(opts) {
+        this.opts = { ...opts };
+        this.v = new Virtualizer(this.buildOptions(null));
+    }
+    // ── inputs ──
+    /** Replace the render list. `keys[i]` must be unique. */
+    setItems(keys, estimates) {
+        this.keys = keys;
+        this.estimates = estimates;
+        const map = new Map();
+        for (let i = 0; i < keys.length; i++)
+            map.set(keys[i], i);
+        this.keyIndex = map;
+        // New closures on purpose: virtual-core memoises its measurements on the
+        // getItemKey identity, so a reorder with an unchanged count still relayouts.
+        this.getItemKey = (i) => keys[i];
+        this.estimateSize = (i) => estimates[i] ?? 0;
+        // Mounted elements keep their key but may have a new index.
+        for (const [key, node] of this.nodes) {
+            const idx = map.get(key);
+            node.setAttribute('data-index', idx === undefined ? '-1' : String(idx));
+        }
+        this.resolvePinned();
+        this.stickyLevels = normalizeStickyLevels(this.stickyInput, keys.length);
+        this.stickySet = new Set(this.stickyLevels.flat());
+        this.rebuildRangeExtractor();
+        this.sync();
+    }
+    setPinned(keys) {
+        this.pinnedKeys = Array.from(keys);
+        this.resolvePinned();
+        this.rebuildRangeExtractor();
+        this.sync();
+    }
+    /** Change the render-everything threshold. */
+    setThreshold(threshold) {
+        if (threshold === this.opts.threshold)
+            return;
+        this.opts.threshold = threshold;
+        this.rebuildRangeExtractor();
+        this.sync();
+    }
+    setSticky(input) {
+        this.stickyInput = input;
+        this.stickyLevels = normalizeStickyLevels(input, this.keys.length);
+        this.stickySet = new Set(this.stickyLevels.flat());
+        this.rebuildRangeExtractor();
+        this.sync();
+    }
+    resolvePinned() {
+        const idx = [];
+        for (const k of this.pinnedKeys) {
+            const i = this.keyIndex.get(k);
+            if (i !== undefined)
+                idx.push(i);
+        }
+        this.pinnedIndices = idx;
+        this.pinnedSet = new Set(idx);
+    }
+    rebuildRangeExtractor() {
+        const policy = {
+            threshold: this.opts.threshold,
+            pinnedIndices: this.pinnedIndices,
+            stickyLevels: this.stickyLevels
+        };
+        this.rangeExtractor = (range) => extractWindowIndices(range, policy);
+    }
+    // ── virtual-core wiring ──
+    buildOptions(root) {
+        const win = isWindowLike(root);
+        return {
+            count: this.keys.length,
+            getScrollElement: () => root,
+            estimateSize: this.estimateSize,
+            getItemKey: this.getItemKey,
+            rangeExtractor: this.rangeExtractor,
+            overscan: this.opts.overscan,
+            scrollMargin: this.scrollMargin,
+            scrollPaddingStart: this.opts.scrollPaddingStart,
+            scrollPaddingEnd: this.opts.scrollPaddingEnd,
+            initialRect: { width: 0, height: this.opts.initialViewportSize },
+            observeElementRect: (win ? observeWindowRect : observeElementRect),
+            observeElementOffset: (win ? observeWindowOffset : observeElementOffset),
+            scrollToFn: (win ? windowScroll : elementScroll),
+            onChange: () => this.emit()
+        };
+    }
+    /** Push current inputs into virtual-core and recompute the snapshot. */
+    sync() {
+        if (this.destroyed)
+            return;
+        this.v.setOptions(this.buildOptions(this.root));
+        if (this.anchorEl)
+            this.v._willUpdate();
+        this.emit();
+    }
+    emit() {
+        if (this.destroyed)
+            return;
+        const count = this.keys.length;
+        const next = layoutWindow(this.v.getVirtualItems(), {
+            scrollMargin: this.scrollMargin,
+            totalSize: this.v.getTotalSize(),
+            count,
+            windowed: !(this.opts.threshold > 0 && count < this.opts.threshold),
+            stickySet: this.stickySet,
+            pinnedSet: this.pinnedSet
+        });
+        if (sameSnapshot(next, this.snapshot))
+            return;
+        this.snapshot = next;
+        this.opts.onChange?.(next);
+    }
+    // ── DOM lifecycle ──
+    /** Mount on the element whose top is item 0's top (a `<tbody>` or list container). */
+    attach(anchor) {
+        if (this.destroyed)
+            return;
+        this.anchorEl = anchor;
+        // The engine does its own scroll-anchor correction when a row above the
+        // viewport is measured; native CSS scroll anchoring would correct the same
+        // shift a second time and jump.
+        this.prevOverflowAnchor = anchor.style.overflowAnchor;
+        anchor.style.overflowAnchor = 'none';
+        this.bindRoot(this.resolveRoot(anchor));
+        this.unmountVirtualizer = this.v._didMount();
+        this.v._willUpdate();
+        for (const node of this.nodes.values()) {
+            if (node.isConnected)
+                this.v.measureElement(node);
+        }
+        const RO = resizeObserverOf(anchor.ownerDocument?.defaultView);
+        if (RO) {
+            this.anchorRO = new RO(() => this.onLayoutShift());
+            this.anchorRO.observe(anchor);
+        }
+        this.emit();
+        if (this.pendingScroll) {
+            const { index, align } = this.pendingScroll;
+            this.pendingScroll = null;
+            this.scrollToIndex(index, { align });
+        }
+    }
+    detach() {
+        this.rootUnsub?.();
+        this.rootUnsub = null;
+        this.anchorRO?.disconnect();
+        this.anchorRO = null;
+        this.unmountVirtualizer?.();
+        this.unmountVirtualizer = null;
+        if (this.anchorEl)
+            this.anchorEl.style.overflowAnchor = this.prevOverflowAnchor;
+        this.anchorEl = null;
+        this.root = null;
+    }
+    destroy() {
+        this.detach();
+        this.nodes.clear();
+        this.destroyed = true;
+    }
+    resolveRoot(anchor) {
+        const view = anchor.ownerDocument?.defaultView;
+        const configured = this.opts.scrollRoot;
+        if (configured !== 'auto')
+            return configured;
+        const found = findScrollRoot(anchor, (el) => view.getComputedStyle(el).overflowY);
+        return found ?? view;
+    }
+    bindRoot(root) {
+        this.rootUnsub?.();
+        this.root = root;
+        // Registered BEFORE virtual-core's own scroll listener (`_willUpdate` adds
+        // it), so the margin is fresh when virtual-core recomputes the range.
+        const onScroll = () => this.updateScrollMargin();
+        root.addEventListener('scroll', onScroll, { passive: true });
+        let rootRO = null;
+        const RO = isWindowLike(root) ? undefined : resizeObserverOf(root.ownerDocument?.defaultView);
+        if (RO && !isWindowLike(root)) {
+            const ro = new RO(() => this.onLayoutShift());
+            ro.observe(root);
+            rootRO = ro;
+        }
+        this.rootUnsub = () => {
+            root.removeEventListener('scroll', onScroll);
+            rootRO?.disconnect();
+        };
+        this.updateScrollMargin(false);
+        this.v.setOptions(this.buildOptions(root));
+    }
+    /** The anchor or root resized: re-resolve an 'auto' root, refresh the margin. */
+    onLayoutShift() {
+        if (!this.anchorEl || this.destroyed)
+            return;
+        if (this.opts.scrollRoot === 'auto') {
+            const next = this.resolveRoot(this.anchorEl);
+            if (next !== this.root) {
+                this.bindRoot(next);
+                this.v._willUpdate();
+                this.emit();
+                return;
+            }
+        }
+        this.updateScrollMargin();
+    }
+    /** Distance from the scroller's content top to the anchor's top. */
+    updateScrollMargin(apply = true) {
+        const anchor = this.anchorEl;
+        const root = this.root;
+        if (!anchor || !root)
+            return;
+        const anchorTop = anchor.getBoundingClientRect().top;
+        let margin;
+        if (isWindowLike(root)) {
+            margin = anchorTop + root.scrollY;
+        }
+        else {
+            const el = root;
+            margin = anchorTop - el.getBoundingClientRect().top - el.clientTop + el.scrollTop;
+        }
+        margin = Math.round(margin);
+        if (margin === this.scrollMargin)
+            return;
+        this.scrollMargin = margin;
+        if (apply)
+            this.sync();
+    }
+    // ── per-item measurement ──
+    /** Register a rendered item element. Re-measured on every resize. */
+    measure(node, key) {
+        const idx = this.keyIndex.get(key);
+        node.setAttribute('data-index', idx === undefined ? '-1' : String(idx));
+        const prev = this.nodes.get(key);
+        if (prev && prev !== node && !prev.isConnected)
+            this.queueSweep();
+        this.nodes.set(key, node);
+        if (idx !== undefined)
+            this.v.measureElement(node);
+    }
+    /** Forget an item element (it unmounted, or its key changed). */
+    unmeasure(node, key) {
+        if (this.nodes.get(key) === node)
+            this.nodes.delete(key);
+        this.queueSweep();
+    }
+    queueSweep() {
+        if (this.sweepQueued)
+            return;
+        this.sweepQueued = true;
+        queueMicrotask(() => {
+            this.sweepQueued = false;
+            if (!this.destroyed)
+                this.v.measureElement(null);
+        });
+    }
+    // ── scrolling ──
+    scrollToIndex(index, opts = {}) {
+        const align = opts.align ?? 'auto';
+        if (index < 0 || index >= this.keys.length)
+            return;
+        if (!this.anchorEl) {
+            this.pendingScroll = { index, align };
+            return;
+        }
+        this.v.scrollToIndex(index, { align });
+    }
+    scrollToKey(key, opts = {}) {
+        const idx = this.keyIndex.get(key);
+        if (idx !== undefined)
+            this.scrollToIndex(idx, opts);
+    }
+    /** Index of `key` in the render list, or -1. */
+    indexOf(key) {
+        return this.keyIndex.get(key) ?? -1;
+    }
+    /** Drop every cached measurement (e.g. after a column-width change). */
+    remeasure() {
+        this.v.measure();
+        for (const node of this.nodes.values())
+            if (node.isConnected)
+                this.v.measureElement(node);
+        this.emit();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
@@ -34,6 +34,11 @@
       "svelte": "./dist/components/table/index.js",
       "default": "./dist/components/table/index.js"
     },
+    "./virtual": {
+      "types": "./dist/virtual/index.d.ts",
+      "svelte": "./dist/virtual/index.js",
+      "default": "./dist/virtual/index.js"
+    },
     "./graph": {
       "types": "./dist/components/graph/index.d.ts",
       "svelte": "./dist/components/graph/index.js",
@@ -76,7 +81,7 @@
     "build": "vite build",
     "build:site": "npm run package && vite build",
     "preview": "vite preview",
-    "package": "svelte-package --input src/lib --output dist && node scripts/compile-rune-modules.mjs",
+    "package": "svelte-package --input src/lib --output dist && node scripts/compile-rune-modules.mjs && node scripts/verify-dist.mjs",
     "check:demos": "node scripts/check-demo-coverage.mjs",
     "guard": "node scripts/check-demo-coverage.mjs",
     "test:dist": "svelte-kit sync && vitest run --config vitest.dist.config.ts",
@@ -91,6 +96,7 @@
     "@atlaskit/pragmatic-drag-and-drop-live-region": "~2.0.0",
     "@paper-design/shaders": ">=0.0.50",
     "@tanstack/table-core": "^8.0.0",
+    "@tanstack/virtual-core": "^3.17.0",
     "@xyflow/svelte": "^1.0.0",
     "cobe": "^2.0.0",
     "d3": "^7.0.0",
@@ -127,6 +133,9 @@
     "@tanstack/table-core": {
       "optional": true
     },
+    "@tanstack/virtual-core": {
+      "optional": true
+    },
     "@xyflow/svelte": {
       "optional": true
     },
@@ -163,6 +172,7 @@
     "@sveltejs/vite-plugin-svelte": "^5.0.0",
     "@tailwindcss/vite": "^4.0.0",
     "@tanstack/table-core": "^8.21.3",
+    "@tanstack/virtual-core": "^3.17.11",
     "@types/d3": "^7.4.3",
     "@vitest/browser": "^3.2.7",
     "@xyflow/svelte": "^1.6.2",