@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.1

package/virtualizer/rect.js

@@ -0,0 +1,105 @@
+// Ported from React Spectrum (react-stately/src/virtualizer/Rect.ts), Apache-2.0, © Adobe.
+// Rivet: `intersects` has no jsdom test-environment shortcut (Rivet tests run real layout math).
+import { Point } from "./point.js";
+/** Represents a rectangle. */
+export class Rect {
+    /** The x-coordinate of the rectangle. */
+    x;
+    /** The y-coordinate of the rectangle. */
+    y;
+    /** The width of the rectangle. */
+    width;
+    /** The height of the rectangle. */
+    height;
+    constructor(x = 0, y = 0, width = 0, height = 0) {
+        this.x = x;
+        this.y = y;
+        this.width = width;
+        this.height = height;
+    }
+    /** The maximum x-coordinate in the rectangle. */
+    get maxX() {
+        return this.x + this.width;
+    }
+    /** The maximum y-coordinate in the rectangle. */
+    get maxY() {
+        return this.y + this.height;
+    }
+    /** The area of the rectangle. */
+    get area() {
+        return this.width * this.height;
+    }
+    /** The top left corner of the rectangle. */
+    get topLeft() {
+        return new Point(this.x, this.y);
+    }
+    /** The top right corner of the rectangle. */
+    get topRight() {
+        return new Point(this.maxX, this.y);
+    }
+    /** The bottom left corner of the rectangle. */
+    get bottomLeft() {
+        return new Point(this.x, this.maxY);
+    }
+    /** The bottom right corner of the rectangle. */
+    get bottomRight() {
+        return new Point(this.maxX, this.maxY);
+    }
+    /** Returns whether this rectangle intersects another rectangle (both need a non-zero area). */
+    intersects(rect) {
+        return (this.area > 0 &&
+            rect.area > 0 &&
+            this.x <= rect.x + rect.width &&
+            rect.x <= this.x + this.width &&
+            this.y <= rect.y + rect.height &&
+            rect.y <= this.y + this.height);
+    }
+    /** Returns whether this rectangle fully contains another rectangle. */
+    containsRect(rect) {
+        return this.x <= rect.x && this.y <= rect.y && this.maxX >= rect.maxX && this.maxY >= rect.maxY;
+    }
+    /** Returns whether the rectangle contains the given point. */
+    containsPoint(point) {
+        return this.x <= point.x && this.y <= point.y && this.maxX >= point.x && this.maxY >= point.y;
+    }
+    /**
+     * Returns the first corner of this rectangle (from top to bottom, left to right)
+     * that is contained in the given rectangle, or null of the rectangles do not intersect.
+     */
+    getCornerInRect(rect) {
+        for (const key of ["topLeft", "topRight", "bottomLeft", "bottomRight"]) {
+            if (rect.containsPoint(this[key]))
+                return key;
+        }
+        return null;
+    }
+    equals(rect) {
+        return rect.x === this.x && rect.y === this.y && rect.width === this.width && rect.height === this.height;
+    }
+    pointEquals(point) {
+        return this.x === point.x && this.y === point.y;
+    }
+    sizeEquals(size) {
+        return this.width === size.width && this.height === size.height;
+    }
+    /** Returns the union of this Rect and another. */
+    union(other) {
+        const x = Math.min(this.x, other.x);
+        const y = Math.min(this.y, other.y);
+        const width = Math.max(this.maxX, other.maxX) - x;
+        const height = Math.max(this.maxY, other.maxY) - y;
+        return new Rect(x, y, width, height);
+    }
+    /** Returns the intersection of this Rect with another; an all zero Rect if they do not intersect. */
+    intersection(other) {
+        if (!this.intersects(other))
+            return new Rect(0, 0, 0, 0);
+        const x = Math.max(this.x, other.x);
+        const y = Math.max(this.y, other.y);
+        return new Rect(x, y, Math.min(this.maxX, other.maxX) - x, Math.min(this.maxY, other.maxY) - y);
+    }
+    /** Returns a copy of this rectangle. */
+    copy() {
+        return new Rect(this.x, this.y, this.width, this.height);
+    }
+}

package/virtualizer/reusable-view.d.ts

@@ -0,0 +1,29 @@
+import type { Key } from "../collections/index.js";
+import type { LayoutInfo } from "./layout-info.js";
+import type { Virtualizer } from "./virtualizer-core.js";
+/** `Virtualizer` creates instances of the `ReusableView` class to represent views currently being displayed. */
+export declare class ReusableView<T extends object, V> {
+    /** The Virtualizer this view is a part of. */
+    virtualizer: Virtualizer<T, V>;
+    /** The LayoutInfo this view is currently representing. */
+    layoutInfo: LayoutInfo | null;
+    /** The content currently being displayed by this view, set by the virtualizer. */
+    content: T | null;
+    rendered: V | null;
+    viewType: string;
+    key: Key;
+    children: Set<ChildView<T, V>>;
+    reusableViews: Map<string, ChildView<T, V>[]>;
+    constructor(virtualizer: Virtualizer<T, V>, viewType: string);
+    /** Prepares the view for reuse. Called just before the view is removed from the DOM. */
+    prepareForReuse(): void;
+    getReusableView(reuseType: string): ChildView<T, V>;
+    reuseChild(child: ChildView<T, V>): void;
+}
+export declare class RootView<T extends object, V> extends ReusableView<T, V> {
+    constructor(virtualizer: Virtualizer<T, V>);
+}
+export declare class ChildView<T extends object, V> extends ReusableView<T, V> {
+    parent: ReusableView<T, V>;
+    constructor(virtualizer: Virtualizer<T, V>, parent: ReusableView<T, V>, viewType: string);
+}

package/virtualizer/reusable-view.js

@@ -0,0 +1,56 @@
+/** `Virtualizer` creates instances of the `ReusableView` class to represent views currently being displayed. */
+export class ReusableView {
+    /** The Virtualizer this view is a part of. */
+    virtualizer;
+    /** The LayoutInfo this view is currently representing. */
+    layoutInfo;
+    /** The content currently being displayed by this view, set by the virtualizer. */
+    content;
+    rendered;
+    viewType;
+    key;
+    children;
+    reusableViews;
+    constructor(virtualizer, viewType) {
+        this.virtualizer = virtualizer;
+        this.key = virtualizer._nextViewKey();
+        this.viewType = viewType;
+        this.children = new Set();
+        this.reusableViews = new Map();
+        this.layoutInfo = null;
+        this.content = null;
+        this.rendered = null;
+    }
+    /** Prepares the view for reuse. Called just before the view is removed from the DOM. */
+    prepareForReuse() {
+        this.content = null;
+        this.rendered = null;
+        this.layoutInfo = null;
+    }
+    getReusableView(reuseType) {
+        // FIFO so that DOM order remains consistent during scrolling (cells of a reused row keep their order).
+        const reusable = this.reusableViews.get(reuseType);
+        return reusable && reusable.length > 0 ? reusable.shift() : new ChildView(this.virtualizer, this, reuseType);
+    }
+    reuseChild(child) {
+        child.prepareForReuse();
+        let reusable = this.reusableViews.get(child.viewType);
+        if (!reusable) {
+            reusable = [];
+            this.reusableViews.set(child.viewType, reusable);
+        }
+        reusable.push(child);
+    }
+}
+export class RootView extends ReusableView {
+    constructor(virtualizer) {
+        super(virtualizer, "root");
+    }
+}
+export class ChildView extends ReusableView {
+    parent;
+    constructor(virtualizer, parent, viewType) {
+        super(virtualizer, viewType);
+        this.parent = parent;
+    }
+}

package/virtualizer/scroll-anchor.d.ts

@@ -0,0 +1,62 @@
+import type { Key } from "../collections/index.js";
+import type { LayoutInfo } from "./layout-info.js";
+import { Rect, type RectCorner } from "./rect.js";
+import type { Size } from "./size.js";
+export type ScrollAnchorAxis = "x" | "y";
+export type ScrollAnchorEdge = "start" | "end";
+export interface ScrollAnchor {
+    key: Key;
+    corner: RectCorner;
+    offset: number;
+}
+export interface ScrollAnchorInfo {
+    /** Which edge of the content the viewport should stay anchored to. */
+    edge: "start" | "end";
+    /** Which axis `edge` refers to — 'y' for vertical lists, 'x' for horizontal. */
+    axis: "x" | "y";
+    /** Distance (px) from `edge` within which the viewport is considered "following" it. */
+    threshold: number;
+    /** Excludes structural/ephemeral layout infos (e.g. loaders) from being the anchor. Default: any. */
+    isAnchorable?: (layoutInfo: LayoutInfo) => boolean;
+}
+/** Viewport coordinate (along `axis`) that keeps a previously captured anchor at the same offset from the viewport start. */
+export declare function computeScrollAnchorTarget(anchor: ScrollAnchor, axis: ScrollAnchorAxis, getLayoutInfo: (key: Key) => LayoutInfo | null, visibleRect: Rect, contentSize: Size): number | null;
+/**
+ * Picks the item to anchor scroll to: nearest the top of the viewport when anchoring to 'end', nearest the
+ * bottom when anchoring to 'start'. `isAnchorable` excludes items (like loaders).
+ */
+export declare function captureScrollAnchor(edge: ScrollAnchorEdge, axis: ScrollAnchorAxis, visibleRect: Rect, visibleLayoutInfos: Iterable<[Key, LayoutInfo]>, isAnchorable?: (layoutInfo: LayoutInfo) => boolean): ScrollAnchor | null;
+/** Viewport coordinate (along `axis`) that pins the viewport to `edge` of the content. */
+export declare function getEdgeSnapTarget(edge: ScrollAnchorEdge, axis: ScrollAnchorAxis, contentSize: Size, previousVisibleRect: Rect): number;
+/** Whether the viewport is within `threshold` px of the anchored edge. */
+export declare function isNearEdge(visibleRect: Rect, contentSize: Size, edge: ScrollAnchorEdge, axis: ScrollAnchorAxis, threshold: number): boolean;
+/**
+ * New scroll position after content changes: keep the anchor item where it was; else stick to the edge, but
+ * only if the viewport was near it and the user is not scrolling away.
+ */
+export declare function resolveScrollAdjustment(edge: ScrollAnchorEdge, axis: ScrollAnchorAxis, anchor: ScrollAnchor | null, wasNearAnchorEdge: boolean, isScrolling: boolean, itemSizeChanged: boolean, contentSizeDelta: number, getLayoutInfo: (key: Key) => LayoutInfo | null, previousVisibleRect: Rect, contentSize: Size): Rect | null;
+export interface ResolveAfterLayoutOptions {
+    anchorInfo: ScrollAnchorInfo | null;
+    /** The anchor captured by `captureBeforeLayout` before this pass's `layout.update()` ran. */
+    anchor: ScrollAnchor | null;
+    /** The full post-layout visible layout infos, i.e. `virtualizer.getVisibleLayoutInfos()`. */
+    postLayoutInfos: Map<Key, LayoutInfo>;
+    previousVisibleRect: Rect;
+    previousContentSize: Size;
+    contentSize: Size;
+    itemSizeChanged: boolean;
+    isScrolling: boolean;
+    getLayoutInfo: (key: Key) => LayoutInfo | null;
+}
+/** Cross-pass state needed to keep the viewport anchored to a layout's edge across relayouts. */
+export declare class ScrollAnchorTracker {
+    private hasSnappedToEdge;
+    private hadEstimatedVisibleItems;
+    private wasNearAnchorEdge;
+    /** Resets all tracked state, e.g. when the virtualizer's layout instance changes. */
+    reset(): void;
+    /** Captures the anchor from pre-layout view positions. */
+    captureBeforeLayout(anchorInfo: ScrollAnchorInfo | null, preLayoutInfos: Iterable<[Key, LayoutInfo]>, visibleRect: Rect): ScrollAnchor | null;
+    /** Post-layout decision: updates the tracked state for the next pass and returns the scroll target, or null. */
+    resolveAfterLayout(options: ResolveAfterLayoutOptions): Rect | null;
+}

package/virtualizer/scroll-anchor.js

@@ -0,0 +1,130 @@
+import { Rect } from "./rect.js";
+/** Minimum overlap (along the scroll axis) an item needs with the viewport to be eligible as a scroll anchor. */
+const MIN_ANCHOR_OVERLAP = 4;
+const dimensionForAxis = (axis) => (axis === "x" ? "width" : "height");
+/** Viewport coordinate (along `axis`) that keeps a previously captured anchor at the same offset from the viewport start. */
+export function computeScrollAnchorTarget(anchor, axis, getLayoutInfo, visibleRect, contentSize) {
+    const finalInfo = getLayoutInfo(anchor.key);
+    if (!finalInfo)
+        return null;
+    const adjustment = finalInfo.rect[anchor.corner][axis] - visibleRect[axis] - anchor.offset;
+    if (adjustment === 0)
+        return null;
+    const target = visibleRect[axis] + adjustment;
+    const dimension = dimensionForAxis(axis);
+    const max = Math.max(0, contentSize[dimension] - visibleRect[dimension]);
+    const clamped = Math.max(0, Math.min(max, target));
+    return clamped !== visibleRect[axis] ? clamped : null;
+}
+/**
+ * Picks the item to anchor scroll to: nearest the top of the viewport when anchoring to 'end', nearest the
+ * bottom when anchoring to 'start'. `isAnchorable` excludes items (like loaders).
+ */
+export function captureScrollAnchor(edge, axis, visibleRect, visibleLayoutInfos, isAnchorable = () => true) {
+    const dimension = dimensionForAxis(axis);
+    let best = null;
+    for (const [key, layoutInfo] of visibleLayoutInfos) {
+        if (!layoutInfo || !isAnchorable(layoutInfo))
+            continue;
+        const overlap = layoutInfo.rect.intersection(visibleRect)[dimension];
+        if (layoutInfo.rect.area > 0 && overlap >= MIN_ANCHOR_OVERLAP) {
+            const corner = layoutInfo.rect.getCornerInRect(visibleRect) ?? "topLeft";
+            const offset = layoutInfo.rect[corner][axis] - visibleRect[axis];
+            const isBetter = !best || (edge === "end" ? offset < best.offset : offset > best.offset);
+            if (isBetter)
+                best = { key, corner, offset };
+        }
+    }
+    return best;
+}
+/** Viewport coordinate (along `axis`) that pins the viewport to `edge` of the content. */
+export function getEdgeSnapTarget(edge, axis, contentSize, previousVisibleRect) {
+    if (edge === "start")
+        return 0;
+    const dimension = dimensionForAxis(axis);
+    return Math.max(0, contentSize[dimension] - previousVisibleRect[dimension]);
+}
+/** Whether the viewport is within `threshold` px of the anchored edge. */
+export function isNearEdge(visibleRect, contentSize, edge, axis, threshold) {
+    if (edge === "start")
+        return visibleRect[axis] <= threshold;
+    const dimension = dimensionForAxis(axis);
+    const distanceFromEnd = contentSize[dimension] - (visibleRect[axis] + visibleRect[dimension]);
+    return distanceFromEnd <= threshold;
+}
+/**
+ * New scroll position after content changes: keep the anchor item where it was; else stick to the edge, but
+ * only if the viewport was near it and the user is not scrolling away.
+ */
+export function resolveScrollAdjustment(edge, axis, anchor, wasNearAnchorEdge, isScrolling, itemSizeChanged, contentSizeDelta, getLayoutInfo, previousVisibleRect, contentSize) {
+    const withTarget = (target) => axis === "x"
+        ? new Rect(target, previousVisibleRect.y, previousVisibleRect.width, previousVisibleRect.height)
+        : new Rect(previousVisibleRect.x, target, previousVisibleRect.width, previousVisibleRect.height);
+    if (anchor) {
+        const target = computeScrollAnchorTarget(anchor, axis, getLayoutInfo, previousVisibleRect, contentSize);
+        if (target != null)
+            return withTarget(target);
+    }
+    if (wasNearAnchorEdge && !isScrolling && (!itemSizeChanged || contentSizeDelta > 0)) {
+        const target = withTarget(getEdgeSnapTarget(edge, axis, contentSize, previousVisibleRect));
+        return target.equals(previousVisibleRect) ? null : target;
+    }
+    return null;
+}
+/** Cross-pass state needed to keep the viewport anchored to a layout's edge across relayouts. */
+export class ScrollAnchorTracker {
+    hasSnappedToEdge = false;
+    hadEstimatedVisibleItems = false;
+    wasNearAnchorEdge = false;
+    /** Resets all tracked state, e.g. when the virtualizer's layout instance changes. */
+    reset() {
+        this.hasSnappedToEdge = false;
+        this.hadEstimatedVisibleItems = false;
+        this.wasNearAnchorEdge = false;
+    }
+    /** Captures the anchor from pre-layout view positions. */
+    captureBeforeLayout(anchorInfo, preLayoutInfos, visibleRect) {
+        if (!anchorInfo)
+            return null;
+        return captureScrollAnchor(anchorInfo.edge, anchorInfo.axis, visibleRect, preLayoutInfos, anchorInfo.isAnchorable);
+    }
+    /** Post-layout decision: updates the tracked state for the next pass and returns the scroll target, or null. */
+    resolveAfterLayout(options) {
+        const { anchorInfo, anchor, postLayoutInfos, previousVisibleRect, previousContentSize, contentSize, itemSizeChanged, isScrolling, getLayoutInfo } = options;
+        if (!anchorInfo)
+            return null;
+        // Read the previous pass's state into locals before any writes below overwrite it.
+        const wasSettlingLastPass = this.hadEstimatedVisibleItems;
+        const wasNearAnchorEdgeLastPass = this.wasNearAnchorEdge;
+        let hasEstimated = false;
+        for (const layoutInfo of postLayoutInfos.values()) {
+            if (layoutInfo.estimatedSize) {
+                hasEstimated = true;
+                break;
+            }
+        }
+        this.hadEstimatedVisibleItems = hasEstimated;
+        // Don't recheck "near edge?" mid-resize (it could look like a scroll that never happened).
+        if (!wasSettlingLastPass) {
+            this.wasNearAnchorEdge = isNearEdge(previousVisibleRect, previousContentSize, anchorInfo.edge, anchorInfo.axis, anchorInfo.threshold);
+        }
+        if (previousVisibleRect.area === 0)
+            return null;
+        const dimension = anchorInfo.axis === "x" ? "width" : "height";
+        const contentSizeDelta = contentSize[dimension] - previousContentSize[dimension];
+        const isFirstAnchoredLayout = !this.hasSnappedToEdge;
+        this.hasSnappedToEdge = true;
+        // Only modify scroll when content actually changed (or this is the first layout, which always snaps).
+        if (!(isFirstAnchoredLayout || contentSizeDelta !== 0 || itemSizeChanged))
+            return null;
+        const wasNearAnchorEdge = isFirstAnchoredLayout ||
+            (wasSettlingLastPass && wasNearAnchorEdgeLastPass) ||
+            isNearEdge(previousVisibleRect, previousContentSize, anchorInfo.edge, anchorInfo.axis, anchorInfo.threshold);
+        // A first-ever layout always snaps: save that decision so later passes of this cascade reuse it.
+        if (!wasSettlingLastPass)
+            this.wasNearAnchorEdge = wasNearAnchorEdge;
+        // While still resizing, items above the anchor are also growing: following it would fall short of the edge.
+        const effectiveAnchor = isFirstAnchoredLayout || (wasSettlingLastPass && wasNearAnchorEdgeLastPass) ? null : anchor;
+        return resolveScrollAdjustment(anchorInfo.edge, anchorInfo.axis, effectiveAnchor, wasNearAnchorEdge, isScrolling, itemSizeChanged, contentSizeDelta, getLayoutInfo, previousVisibleRect, contentSize);
+    }
+}

package/virtualizer/size.d.ts

@@ -0,0 +1,11 @@
+export declare class Size {
+    width: number;
+    height: number;
+    constructor(width?: number, height?: number);
+    /** Returns a copy of this size. */
+    copy(): Size;
+    /** Returns whether this size is equal to another one. */
+    equals(other: Size): boolean;
+    /** The total area of the Size. */
+    get area(): number;
+}

package/virtualizer/size.js

@@ -0,0 +1,21 @@
+// Ported from React Spectrum (react-stately/src/virtualizer/Size.ts), Apache-2.0, © Adobe.
+export class Size {
+    width;
+    height;
+    constructor(width = 0, height = 0) {
+        this.width = Math.max(width, 0);
+        this.height = Math.max(height, 0);
+    }
+    /** Returns a copy of this size. */
+    copy() {
+        return new Size(this.width, this.height);
+    }
+    /** Returns whether this size is equal to another one. */
+    equals(other) {
+        return this.width === other.width && this.height === other.height;
+    }
+    /** The total area of the Size. */
+    get area() {
+        return this.width * this.height;
+    }
+}

package/virtualizer/state.d.ts

@@ -0,0 +1,35 @@
+import type { Key } from "../collections/index.js";
+import type { Collection } from "./collection.js";
+import type { Layout } from "./layout.js";
+import { Rect } from "./rect.js";
+import type { ReusableView } from "./reusable-view.js";
+import { Size } from "./size.js";
+import { Virtualizer } from "./virtualizer-core.js";
+/** A value or an accessor (read inside the render effect, so signals in it re-render). */
+export type MaybeAccessor<T> = T | (() => T);
+export interface VirtualizerStateOptions<T extends object, V, O> {
+    renderView(type: string, content: T | null): V;
+    layout: MaybeAccessor<Layout<T>>;
+    collection: MaybeAccessor<Collection<T>>;
+    onVisibleRectChange(rect: Rect): void;
+    persistedKeys?: MaybeAccessor<Set<Key> | null | undefined>;
+    layoutOptions?: MaybeAccessor<O | undefined>;
+    allowsWindowScrolling?: boolean;
+    /** Rivet: start from a measured rect (default empty, like the original) so the first render keeps its views. */
+    initialVisibleRect?: Rect;
+}
+export interface VirtualizerState<T extends object, V> {
+    /** Root views (each with `children`), re-read after every render. */
+    visibleViews(): ReusableView<T, V>[];
+    setVisibleRect(rect: Rect): void;
+    size(): Size;
+    setSize(size: Size): void;
+    contentSize(): Size;
+    virtualizer: Virtualizer<T, V>;
+    isScrolling(): boolean;
+    startScrolling(): void;
+    endScrolling(): void;
+    /** Stop the render effect. */
+    dispose(): void;
+}
+export declare function createVirtualizerState<T extends object, V, O = any>(opts: VirtualizerStateOptions<T, V, O>): VirtualizerState<T, V>;

package/virtualizer/state.js

@@ -0,0 +1,89 @@
+// Ported from React Spectrum (react-stately/src/virtualizer/useVirtualizerState.ts), Apache-2.0, © Adobe.
+// Rivet: signals instead of hooks — `createVirtualizerState` owns one effect that renders the engine whenever
+// the visible rect, size, scrolling flag, invalidation context or a reactive option changes. Browser-side
+// (or test) only: the state holds class instances, never serialize it.
+import { createRoot, effect, signal, untrack } from "@rivetjs/reactivity";
+import { Rect } from "./rect.js";
+import { Size } from "./size.js";
+import { Virtualizer } from "./virtualizer-core.js";
+const read = (value) => (typeof value === "function" ? value() : value);
+export function createVirtualizerState(opts) {
+    const sameRect = { equals: (a, b) => a.equals(b) };
+    const visibleRect = signal(opts.initialVisibleRect ?? new Rect(0, 0, 0, 0), sameRect);
+    const size = signal(opts.initialVisibleRect ? new Size(opts.initialVisibleRect.width, opts.initialVisibleRect.height) : new Size(), {
+        equals: (a, b) => a.equals(b),
+    });
+    const isScrolling = signal(false);
+    const invalidationContext = signal({});
+    const visibleViews = signal([], { equals: false });
+    const contentSize = signal(new Size(), { equals: (a, b) => a.equals(b) });
+    let visibleRectChanged = false;
+    const virtualizer = new Virtualizer({
+        collection: untrack(() => read(opts.collection)),
+        layout: untrack(() => read(opts.layout)),
+        delegate: {
+            setVisibleRect(rect) {
+                visibleRect.set(rect);
+                visibleRectChanged = true;
+            },
+            renderView: opts.renderView,
+            invalidate: (ctx) => invalidationContext.set(ctx),
+        },
+    });
+    // Merged invalidation context: a new object only when the context or the layout options change.
+    let lastContext = null;
+    let lastOptions;
+    let merged = {};
+    const { dispose } = createRoot((dispose) => {
+        effect(() => {
+            const layoutOptions = read(opts.layoutOptions);
+            const context = invalidationContext();
+            if (context !== lastContext || layoutOptions !== lastOptions) {
+                lastContext = context;
+                lastOptions = layoutOptions;
+                merged = layoutOptions != null ? { ...context, layoutOptions } : context;
+            }
+            let rect = visibleRect();
+            const render = () => virtualizer.render({
+                layout: read(opts.layout),
+                collection: read(opts.collection),
+                persistedKeys: read(opts.persistedKeys) ?? null,
+                layoutOptions,
+                visibleRect: rect,
+                size: opts.allowsWindowScrolling ? size() : rect,
+                invalidationContext: merged,
+                isScrolling: isScrolling(),
+            });
+            let views = render();
+            // A render that moved the visible rect (the layout clamped the scroll offset, or a scroll anchor) laid out no
+            // subviews: render again at the new rect before publishing, as the original's `setVisibleRect` (a state update
+            // during render) re-renders before commit. Publishing the empty pass emptied the rows' `For` once — on a resumed
+            // page that dropped every adopted server row (a first click that scrolled the scroller 4px past its clamped
+            // offset re-created all rows and lost focus; resume fuzz `/list-data`, 2026-10-20).
+            for (let pass = 0; pass < 3 && visibleRectChanged && !untrack(visibleRect).equals(rect); pass++) {
+                rect = untrack(visibleRect);
+                views = render();
+            }
+            visibleViews.set(views);
+            contentSize.set(virtualizer.contentSize);
+            // onVisibleRectChange runs after the render (a layout effect in the original).
+            if (visibleRectChanged) {
+                visibleRectChanged = false;
+                untrack(() => opts.onVisibleRectChange(visibleRect()));
+            }
+        });
+        return dispose;
+    });
+    return {
+        virtualizer,
+        visibleViews,
+        setVisibleRect: (rect) => visibleRect.set(rect),
+        size,
+        setSize: (value) => size.set(value),
+        contentSize,
+        isScrolling,
+        startScrolling: () => isScrolling.set(true),
+        endScrolling: () => isScrolling.set(false),
+        dispose,
+    };
+}

package/virtualizer/table-collection.d.ts

@@ -0,0 +1,45 @@
+import type { Key } from "../collections/index.js";
+import { type Collection, type Node } from "./collection.js";
+export interface GridNode<T> extends Node<T> {
+    column?: GridNode<T>;
+    /** The number of columns spanned by this cell. */
+    colSpan?: number | null;
+    /** The column index of this cell, accounting for any colSpans. */
+    colIndex?: number | null;
+    /** The index of this node within its parent, ignoring sibling nodes that aren't of the same type. */
+    indexOfType?: number;
+}
+export interface TableCollection<T> extends Collection<GridNode<T>> {
+    /** The header row nodes (one per tier of nested columns). */
+    headerRows: GridNode<T>[];
+    /** The column nodes. */
+    columns: GridNode<T>[];
+    /** Column keys that serve as row headers. */
+    rowHeaderColumnKeys: Set<Key>;
+    /** The node that makes up the header of the table. */
+    head?: GridNode<T>;
+    /** The node that makes up the body of the table. */
+    body: GridNode<T>;
+}
+export interface TableColumn {
+    key: Key;
+    /** Header text. */
+    label?: string;
+    width?: number | string;
+    defaultWidth?: number | string;
+    minWidth?: number | string;
+    maxWidth?: number | string;
+    isRowHeader?: boolean;
+}
+export interface TableCollectionOptions<R> {
+    /** Row key (default: `row.key ?? row.id`). */
+    getKey?: (row: R, index: number) => Key;
+    /** Cell value of `row` in `column` (default `row[column.key]`). */
+    getCell?: (row: R, column: TableColumn) => unknown;
+    /** Footer rows (`tablefooter` row group). */
+    footer?: readonly R[];
+    /** Append a "load more" loader row to the body; `true` reserves its height. */
+    loader?: boolean;
+}
+/** A table collection: `tableheader` (one `headerrow` of `column`s), `tablebody` rows of `cell`s, optional footer. */
+export declare function createTableCollection<R>(columns: readonly TableColumn[], rows: readonly R[], options?: TableCollectionOptions<R>): TableCollection<R>;