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

package/virtualizer/dom.js

@@ -0,0 +1,233 @@
+import { Point } from "./point.js";
+import { Rect } from "./rect.js";
+import { Size } from "./size.js";
+let cachedRTLResult = null;
+/**
+ * How the browser reports `scrollLeft` of RTL elements (spec: negative; old Chrome: positive from the left;
+ * old WebKit/IE: positive from the right). Detected once by scrolling a probe element.
+ */
+export function getRTLOffsetType(recalculate = false) {
+    if (cachedRTLResult === null || recalculate) {
+        const outerDiv = document.createElement("div");
+        const outerStyle = outerDiv.style;
+        outerStyle.width = "50px";
+        outerStyle.height = "50px";
+        outerStyle.overflow = "scroll";
+        outerStyle.direction = "rtl";
+        const innerDiv = document.createElement("div");
+        innerDiv.style.width = "100px";
+        innerDiv.style.height = "100px";
+        outerDiv.appendChild(innerDiv);
+        document.body.appendChild(outerDiv);
+        if (outerDiv.scrollLeft > 0) {
+            cachedRTLResult = "positive-descending";
+        }
+        else {
+            outerDiv.scrollLeft = 1;
+            cachedRTLResult = outerDiv.scrollLeft === 0 ? "negative" : "positive-ascending";
+        }
+        document.body.removeChild(outerDiv);
+    }
+    return cachedRTLResult;
+}
+/** `scrollLeft` normalized to a distance from the inline start (RTL-safe). */
+export function getScrollLeft(node, direction) {
+    let { scrollLeft } = node;
+    if (direction === "rtl") {
+        const { scrollWidth, clientWidth } = node;
+        switch (getRTLOffsetType()) {
+            case "negative":
+                scrollLeft = -scrollLeft;
+                break;
+            case "positive-descending":
+                scrollLeft = scrollWidth - clientWidth - scrollLeft;
+                break;
+        }
+    }
+    return scrollLeft;
+}
+/** Set `scrollLeft` from a distance from the inline start (RTL-safe). */
+export function setScrollLeft(node, direction, scrollLeft) {
+    if (direction === "rtl") {
+        switch (getRTLOffsetType()) {
+            case "negative":
+                scrollLeft = -scrollLeft;
+                break;
+            case "positive-ascending":
+                break;
+            default: {
+                const { clientWidth, scrollWidth } = node;
+                scrollLeft = scrollWidth - clientWidth - scrollLeft;
+                break;
+            }
+        }
+    }
+    node.scrollLeft = scrollLeft;
+}
+const px = (value) => (Number.isFinite(value) ? value + "px" : undefined);
+/**
+ * Absolute (or sticky) position style of a view, relative to its parent view. `dir` picks `left` / `right`;
+ * without `dir` the inline-start offset is the logical `inset-inline-start` (RTL without JS).
+ */
+export function layoutInfoToStyle(layoutInfo, dir, parent) {
+    const xProperty = dir === "rtl" ? "right" : dir === "ltr" ? "left" : "inset-inline-start";
+    // Sticky children of an overflowing parent are positioned against the scroll container, not the parent.
+    const relative = parent && !(parent.allowOverflow && layoutInfo.isSticky);
+    const style = {
+        position: layoutInfo.isSticky ? "sticky" : "absolute",
+        // Sticky elements are in normal flow: inline-block so sticky columns don't push each other onto new rows.
+        display: layoutInfo.isSticky ? "inline-block" : undefined,
+        overflow: layoutInfo.allowOverflow ? "visible" : "hidden",
+        opacity: layoutInfo.opacity === 1 ? undefined : String(layoutInfo.opacity),
+        "z-index": layoutInfo.zIndex ? String(layoutInfo.zIndex) : undefined,
+        transform: layoutInfo.transform ?? undefined,
+        contain: "size layout style",
+        top: px(layoutInfo.rect.y - (relative ? parent.rect.y : 0)),
+        [xProperty]: px(layoutInfo.rect.x - (relative ? parent.rect.x : 0)),
+        width: px(layoutInfo.rect.width),
+        height: px(layoutInfo.rect.height),
+    };
+    // Non-finite / unset values are dropped (no `undefined` in serialized state).
+    for (const key in style)
+        if (style[key] === undefined)
+            delete style[key];
+    return style;
+}
+/** Intrinsic size of a view element (its fixed height reset while measuring). */
+export function getSize(node) {
+    const height = node.style.height;
+    node.style.height = "";
+    const size = new Size(node.scrollWidth, node.scrollHeight);
+    node.style.height = height;
+    return size;
+}
+/** Whether `element` is rendered and visible (hidden virtualizers must not report 0 sizes). */
+export function isElementVisible(element) {
+    const el = element;
+    if (typeof el.checkVisibility === "function")
+        return el.checkVisibility({ visibilityProperty: true });
+    const style = getComputedStyle(element);
+    return style.display !== "none" && style.visibility !== "hidden" && !element.closest("[hidden]");
+}
+/** useVirtualizerItem's measurement: report the view's measured size (only while visible). */
+export function measureItem(virtualizer, key, element) {
+    if (!isElementVisible(element))
+        return;
+    virtualizer.updateItemSize(key, getSize(element));
+}
+/** useScrollView as a controller for `element`: visible rect from scroll position + size, scroll start / end (300 ms). */
+export function createScrollView(element, options) {
+    const state = {
+        // Internal scroll position of the scroll view.
+        scrollPosition: new Point(),
+        // Size of the scroll view.
+        size: new Size(),
+        // Offset of the scroll view relative to the window viewport.
+        viewportOffset: new Point(),
+        // Size of the window viewport.
+        viewportSize: new Size(window.innerWidth, window.innerHeight),
+        scrollEndTime: 0,
+        scrollTimeout: null,
+        isScrolling: false,
+        lastVisibleRect: new Rect(),
+    };
+    const updateVisibleRect = () => {
+        // Window scrolling: intersect the window viewport with the scroll view (unbounded height, page scroll).
+        const visibleRect = options.allowsWindowScrolling
+            ? new Rect(state.viewportOffset.x + state.scrollPosition.x, state.viewportOffset.y + state.scrollPosition.y, Math.max(0, Math.min(state.size.width - state.viewportOffset.x, state.viewportSize.width)), Math.max(0, Math.min(state.size.height - state.viewportOffset.y, state.viewportSize.height)))
+            : new Rect(state.scrollPosition.x, state.scrollPosition.y, state.size.width, state.size.height);
+        // Don't emit updates if the visible area is zero and the last emitted area was also zero.
+        if (visibleRect.area > 0 || state.lastVisibleRect.area > 0) {
+            options.onVisibleRectChange(visibleRect);
+            state.lastVisibleRect = visibleRect;
+        }
+    };
+    const onScroll = (event) => {
+        const target = event.target;
+        if (target !== element && !target.contains?.(element) && target !== document)
+            return;
+        if (target !== element) {
+            // An ancestor element or the window was scrolled: update the position relative to the viewport.
+            const boundingRect = element.getBoundingClientRect();
+            const x = boundingRect.x < 0 ? -boundingRect.x : 0;
+            const y = boundingRect.y < 0 ? -boundingRect.y : 0;
+            if (x === state.viewportOffset.x && y === state.viewportOffset.y)
+                return;
+            state.viewportOffset = new Point(x, y);
+        }
+        else {
+            // The scroll view itself was scrolled; clamp (no rubber band shaking out of bounds).
+            const contentSize = options.contentSize();
+            const scrollTop = element.scrollTop;
+            const scrollLeft = getScrollLeft(element, options.direction());
+            state.scrollPosition = new Point(Math.max(0, Math.min(scrollLeft, contentSize.width - state.size.width)), Math.max(0, Math.min(scrollTop, contentSize.height - state.size.height)));
+        }
+        updateVisibleRect();
+        if (!state.isScrolling) {
+            state.isScrolling = true;
+            options.onScrollStart?.();
+        }
+        // Reschedule the end timer only when it gets close.
+        const now = Date.now();
+        if (state.scrollEndTime <= now + 50) {
+            state.scrollEndTime = now + 300;
+            if (state.scrollTimeout != null)
+                clearTimeout(state.scrollTimeout);
+            state.scrollTimeout = setTimeout(() => {
+                state.isScrolling = false;
+                state.scrollTimeout = null;
+                options.onScrollEnd?.();
+            }, 300);
+        }
+    };
+    let isUpdatingSize = false;
+    const updateSize = () => {
+        // No reentrancy: a resize observer firing from the relayout this causes would loop.
+        if (isUpdatingSize)
+            return;
+        isUpdatingSize = true;
+        const clientWidth = element.clientWidth;
+        const clientHeight = element.clientHeight;
+        const viewportWidth = window.innerWidth;
+        const viewportHeight = window.innerHeight;
+        const viewportSizeChanged = state.viewportSize.width !== viewportWidth || state.viewportSize.height !== viewportHeight;
+        if (viewportSizeChanged)
+            state.viewportSize = new Size(viewportWidth, viewportHeight);
+        if (state.size.width !== clientWidth || state.size.height !== clientHeight || viewportSizeChanged) {
+            state.size = new Size(clientWidth, clientHeight);
+            state.scrollPosition = new Point(getScrollLeft(element, options.direction()), element.scrollTop);
+            updateVisibleRect();
+            options.onSizeChange?.(state.size);
+            // Scrollbars appeared or disappeared from the relayout: lay out once more (at most two passes).
+            if (clientWidth !== element.clientWidth || clientHeight !== element.clientHeight) {
+                state.size = new Size(element.clientWidth, element.clientHeight);
+                updateVisibleRect();
+                options.onSizeChange?.(state.size);
+            }
+        }
+        isUpdatingSize = false;
+    };
+    // Border-box observation: content-box would loop when scrollbars appear or disappear.
+    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => updateSize());
+    observer?.observe(element, { box: "border-box" });
+    const onWindowResize = () => updateSize();
+    window.addEventListener("resize", onWindowResize);
+    // Ancestor / window scrolling (capture: scroll does not bubble).
+    if (options.allowsWindowScrolling)
+        document.addEventListener("scroll", onScroll, { capture: true, passive: true });
+    return {
+        onScroll,
+        updateSize,
+        get isScrolling() {
+            return state.isScrolling;
+        },
+        dispose() {
+            observer?.disconnect();
+            window.removeEventListener("resize", onWindowResize);
+            if (options.allowsWindowScrolling)
+                document.removeEventListener("scroll", onScroll, { capture: true });
+            if (state.scrollTimeout != null)
+                clearTimeout(state.scrollTimeout);
+        },
+    };
+}

package/virtualizer/engine.d.ts

@@ -0,0 +1,21 @@
+export { LOADER_KEY, initialWindow, projectViews, type VirtualView, type VirtualizerModel } from "./behaviour.js";
+export { Virtualizer as VirtualizerEngine, type VirtualizerOptions } from "./virtualizer-core.js";
+export { createVirtualizerState, type VirtualizerState, type VirtualizerStateOptions } from "./state.js";
+export { Point } from "./point.js";
+export { Size } from "./size.js";
+export { Rect, type RectCorner } from "./rect.js";
+export { LayoutInfo } from "./layout-info.js";
+export { Layout } from "./layout.js";
+export { ReusableView, RootView, ChildView } from "./reusable-view.js";
+export { OverscanManager } from "./overscan-manager.js";
+export { ScrollAnchorTracker, captureScrollAnchor, computeScrollAnchorTarget, getEdgeSnapTarget, isNearEdge, resolveScrollAdjustment, type ScrollAnchor, type ScrollAnchorInfo, } from "./scroll-anchor.js";
+export { isSetEqual } from "./utils.js";
+export { ListLayout, type ListLayoutOptions, type LayoutNode } from "./list-layout.js";
+export { GridLayout, type GridLayoutOptions } from "./grid-layout.js";
+export { WaterfallLayout, type WaterfallLayoutOptions } from "./waterfall-layout.js";
+export { TableLayout, type TableLayoutProps } from "./table-layout.js";
+export { TableColumnLayout, calculateColumnSizes, type ColumnSize, type TableColumnLayoutOptions } from "./table-column-layout.js";
+export { createTableCollection, type GridNode, type TableCollection, type TableColumn } from "./table-collection.js";
+export { ListCollection, createCollection, buildNodes, loaderNode, getChildNodes, type Collection, type CollectionOptions, type Node, } from "./collection.js";
+export { createScrollView, getRTLOffsetType, getScrollLeft, setScrollLeft, layoutInfoToStyle, getSize, isElementVisible, measureItem, type ScrollView, type ScrollViewOptions, type RTLOffsetType, } from "./dom.js";
+export type { InvalidationContext, VirtualizerDelegate, VirtualizerRenderOptions, DropTarget, DropPosition, ItemDropTarget, RootDropTarget, DropTargetDelegate, LayoutDelegate, Orientation, Direction, } from "./types.js";

package/virtualizer/engine.js

@@ -0,0 +1,21 @@
+// Engine, layouts and DOM helpers of @rivetjs/cdk/virtualizer (no component: importable from plain .ts / node).
+export { LOADER_KEY, initialWindow, projectViews } from "./behaviour.js";
+export { Virtualizer as VirtualizerEngine } from "./virtualizer-core.js";
+export { createVirtualizerState } from "./state.js";
+export { Point } from "./point.js";
+export { Size } from "./size.js";
+export { Rect } from "./rect.js";
+export { LayoutInfo } from "./layout-info.js";
+export { Layout } from "./layout.js";
+export { ReusableView, RootView, ChildView } from "./reusable-view.js";
+export { OverscanManager } from "./overscan-manager.js";
+export { ScrollAnchorTracker, captureScrollAnchor, computeScrollAnchorTarget, getEdgeSnapTarget, isNearEdge, resolveScrollAdjustment, } from "./scroll-anchor.js";
+export { isSetEqual } from "./utils.js";
+export { ListLayout } from "./list-layout.js";
+export { GridLayout } from "./grid-layout.js";
+export { WaterfallLayout } from "./waterfall-layout.js";
+export { TableLayout } from "./table-layout.js";
+export { TableColumnLayout, calculateColumnSizes } from "./table-column-layout.js";
+export { createTableCollection } from "./table-collection.js";
+export { ListCollection, createCollection, buildNodes, loaderNode, getChildNodes, } from "./collection.js";
+export { createScrollView, getRTLOffsetType, getScrollLeft, setScrollLeft, layoutInfoToStyle, getSize, isElementVisible, measureItem, } from "./dom.js";

package/virtualizer/grid-layout.d.ts

@@ -0,0 +1,50 @@
+import type { Key } from "../collections/index.js";
+import type { Node } from "./collection.js";
+import { Layout } from "./layout.js";
+import { LayoutInfo } from "./layout-info.js";
+import { Rect } from "./rect.js";
+import { Size } from "./size.js";
+import type { Direction, DropTarget, DropTargetDelegate, InvalidationContext, ItemDropTarget } from "./types.js";
+export interface GridLayoutOptions {
+    /** The minimum item size. Default 200 x 200. */
+    minItemSize?: Size;
+    /** The maximum item size. Default Infinity. */
+    maxItemSize?: Size;
+    /** Preserve the aspect ratio of `minItemSize` (all rows equal height). Default false (variable rows). */
+    preserveAspectRatio?: boolean;
+    /** The minimum space required between items. Default 18 x 18. */
+    minSpace?: Size;
+    /** The maximum allowed horizontal space between items. Default Infinity. */
+    maxHorizontalSpace?: number;
+    /** The maximum number of columns. Default Infinity. */
+    maxColumns?: number;
+    /** The thickness of the drop indicator. Default 2. */
+    dropIndicatorThickness?: number;
+    /** The fixed height of a "load more" loader element in px. Default 48. */
+    loaderHeight?: number;
+    /** Layout direction: `rtl` flips drop target `before` / `after` in multi-column grids. Default `ltr`. */
+    direction?: Direction;
+}
+/** Arranges items in a grid; items are sized between a minimum and maximum size depending on the container width. */
+export declare class GridLayout<T, O extends GridLayoutOptions = GridLayoutOptions> extends Layout<Node<T>, O> implements DropTargetDelegate {
+    protected gap: Size;
+    protected dropIndicatorThickness: number;
+    protected numColumns: number;
+    protected direction: Direction;
+    private contentSize;
+    private layoutInfos;
+    private margin;
+    shouldInvalidateLayoutOptions(newOptions: O, oldOptions: O): boolean;
+    update(invalidationContext: InvalidationContext<O>): void;
+    getLayoutInfo(key: Key): LayoutInfo | null;
+    getContentSize(): Size;
+    getVisibleLayoutInfos(rect: Rect): LayoutInfo[];
+    updateItemSize(key: Key, size: Size): boolean;
+    getDropTargetFromPoint(x: number, y: number, isValidDropTarget: (target: DropTarget) => boolean): DropTarget;
+    getDropTargetLayoutInfo(target: ItemDropTarget): LayoutInfo;
+}
+/** Layout options may arrive as plain `{ width, height }` objects (serialized props): normalize to `Size`. */
+export declare function sizeOf(value: {
+    width: number;
+    height: number;
+} | null | undefined, fallback: Size): Size;

package/virtualizer/grid-layout.js

@@ -0,0 +1,247 @@
+import { Layout } from "./layout.js";
+import { LayoutInfo } from "./layout-info.js";
+import { Rect } from "./rect.js";
+import { Size } from "./size.js";
+const DEFAULT_OPTIONS = {
+    minItemSize: new Size(200, 200),
+    maxItemSize: new Size(Infinity, Infinity),
+    preserveAspectRatio: false,
+    minSpace: new Size(18, 18),
+    maxSpace: Infinity,
+    maxColumns: Infinity,
+    dropIndicatorThickness: 2,
+    loaderHeight: 48,
+};
+/** Arranges items in a grid; items are sized between a minimum and maximum size depending on the container width. */
+export class GridLayout extends Layout {
+    gap = DEFAULT_OPTIONS.minSpace;
+    dropIndicatorThickness = 2;
+    numColumns = 0;
+    direction = "ltr";
+    contentSize = new Size();
+    layoutInfos = new Map();
+    margin = 0;
+    shouldInvalidateLayoutOptions(newOptions, oldOptions) {
+        return (newOptions.maxColumns !== oldOptions.maxColumns ||
+            newOptions.dropIndicatorThickness !== oldOptions.dropIndicatorThickness ||
+            newOptions.preserveAspectRatio !== oldOptions.preserveAspectRatio ||
+            !sizeOf(newOptions.minItemSize, DEFAULT_OPTIONS.minItemSize).equals(sizeOf(oldOptions.minItemSize, DEFAULT_OPTIONS.minItemSize)) ||
+            !sizeOf(newOptions.maxItemSize, DEFAULT_OPTIONS.maxItemSize).equals(sizeOf(oldOptions.maxItemSize, DEFAULT_OPTIONS.maxItemSize)) ||
+            !sizeOf(newOptions.minSpace, DEFAULT_OPTIONS.minSpace).equals(sizeOf(oldOptions.minSpace, DEFAULT_OPTIONS.minSpace)) ||
+            newOptions.maxHorizontalSpace !== oldOptions.maxHorizontalSpace ||
+            newOptions.loaderHeight !== oldOptions.loaderHeight ||
+            newOptions.direction !== oldOptions.direction);
+    }
+    update(invalidationContext) {
+        const options = (invalidationContext.layoutOptions || {});
+        const minItemSize = sizeOf(options.minItemSize, DEFAULT_OPTIONS.minItemSize);
+        const maxItemSize = sizeOf(options.maxItemSize, DEFAULT_OPTIONS.maxItemSize);
+        const minSpace = sizeOf(options.minSpace, DEFAULT_OPTIONS.minSpace);
+        const { preserveAspectRatio = DEFAULT_OPTIONS.preserveAspectRatio, maxHorizontalSpace = DEFAULT_OPTIONS.maxSpace, maxColumns = DEFAULT_OPTIONS.maxColumns, } = options;
+        const { dropIndicatorThickness = DEFAULT_OPTIONS.dropIndicatorThickness, direction = "ltr" } = options;
+        let loaderHeight = options.loaderHeight ?? DEFAULT_OPTIONS.loaderHeight;
+        this.dropIndicatorThickness = dropIndicatorThickness;
+        this.direction = direction;
+        const virtualizerWidth = this.virtualizer.size.width;
+        // The max item width is always the entire viewport; an infinite max height scales with the max width.
+        const maxItemWidth = Math.min(maxItemSize.width, virtualizerWidth);
+        const maxItemHeight = Number.isFinite(maxItemSize.height) ? maxItemSize.height : Math.floor((minItemSize.height / minItemSize.width) * maxItemWidth);
+        // Compute the number of rows and columns needed to display the content.
+        const columns = Math.floor(virtualizerWidth / (minItemSize.width + minSpace.width));
+        const numColumns = Math.max(1, Math.min(maxColumns, columns));
+        this.numColumns = numColumns;
+        // Compute the available width (minus the space between items).
+        const width = virtualizerWidth - minSpace.width * Math.max(0, numColumns);
+        // Compute the item width based on the space available.
+        let itemWidth = Math.floor(width / numColumns);
+        itemWidth = Math.max(minItemSize.width, Math.min(maxItemWidth, itemWidth));
+        // Compute the item height, which is proportional to the item width.
+        const t = (itemWidth - minItemSize.width) / Math.max(1, maxItemWidth - minItemSize.width);
+        let itemHeight = minItemSize.height + Math.floor((maxItemHeight - minItemSize.height) * t);
+        itemHeight = Math.max(minItemSize.height, Math.min(maxItemHeight, itemHeight));
+        // Compute the horizontal spacing, content height and horizontal margin.
+        const horizontalSpacing = Math.min(Math.max(maxHorizontalSpace, minSpace.width), Math.floor((virtualizerWidth - numColumns * itemWidth) / (numColumns + 1)));
+        this.gap = new Size(horizontalSpacing, minSpace.height);
+        this.margin = Math.floor((virtualizerWidth - numColumns * itemWidth - horizontalSpacing * (numColumns + 1)) / 2);
+        // A skeleton loader within the last 2 items adds a row for the skeletons.
+        const collection = this.virtualizer.collection;
+        let collectionSize = collection.size;
+        let lastKey = collection.getLastKey();
+        for (let i = 0; i < 2 && lastKey != null; i++) {
+            const item = collection.getItem(lastKey);
+            if (item?.type === "skeleton") {
+                collectionSize++;
+                break;
+            }
+            lastKey = collection.getKeyBefore(lastKey);
+        }
+        let rows = Math.ceil(collectionSize / numColumns);
+        const iterator = collection[Symbol.iterator]();
+        let y = rows > 0 ? minSpace.height : 0;
+        const newLayoutInfos = new Map();
+        let skeleton = null;
+        let skeletonCount = 0;
+        for (let row = 0; row < rows; row++) {
+            let maxHeight = 0;
+            const rowLayoutInfos = [];
+            for (let col = 0; col < numColumns; col++) {
+                // Repeat skeleton until the end of the current row.
+                const node = skeleton || iterator.next().value;
+                if (!node)
+                    break;
+                // The loader is added after the skeletons.
+                if (node.type === "loader")
+                    continue;
+                if (node.type === "skeleton")
+                    skeleton = node;
+                const key = skeleton ? `${skeleton.key}-${skeletonCount++}` : node.key;
+                const oldLayoutInfo = this.layoutInfos.get(key);
+                let content = node;
+                if (skeleton)
+                    content = oldLayoutInfo && oldLayoutInfo.content.key === key ? oldLayoutInfo.content : { ...skeleton, key };
+                const x = horizontalSpacing + col * (itemWidth + horizontalSpacing) + this.margin;
+                let height = itemHeight;
+                let estimatedSize = !preserveAspectRatio;
+                if (oldLayoutInfo && estimatedSize) {
+                    height = oldLayoutInfo.rect.height;
+                    estimatedSize =
+                        !!invalidationContext.layoutOptionsChanged || !!invalidationContext.sizeChanged || oldLayoutInfo.estimatedSize || oldLayoutInfo.content !== content;
+                }
+                const layoutInfo = new LayoutInfo(node.type, key, new Rect(x, y, itemWidth, height));
+                layoutInfo.estimatedSize = estimatedSize;
+                layoutInfo.allowOverflow = true;
+                layoutInfo.content = content;
+                newLayoutInfos.set(key, layoutInfo);
+                rowLayoutInfos.push(layoutInfo);
+                maxHeight = Math.max(maxHeight, layoutInfo.rect.height);
+            }
+            for (const layoutInfo of rowLayoutInfos)
+                layoutInfo.rect.height = maxHeight;
+            y += maxHeight + minSpace.height;
+            // Keep adding skeleton rows until we fill the viewport.
+            if (skeleton && row === rows - 1 && y < this.virtualizer.size.height)
+                rows++;
+        }
+        // Always add the loader sentinel if present, so it is never virtualized out.
+        const lastNode = collection.getItem(collection.getLastKey());
+        if (lastNode?.type === "loader") {
+            if (skeletonCount > 0 || !lastNode.props.isLoading)
+                loaderHeight = 0;
+            const loaderWidth = virtualizerWidth - horizontalSpacing * 2;
+            // An `isLoading` sentinel reserves room for the loader (also alongside an empty state).
+            const layoutInfo = new LayoutInfo("loader", lastNode.key, new Rect(horizontalSpacing, y, loaderWidth, loaderHeight));
+            newLayoutInfos.set(lastNode.key, layoutInfo);
+            y = layoutInfo.rect.maxY;
+        }
+        this.layoutInfos = newLayoutInfos;
+        this.contentSize = new Size(this.virtualizer.size.width, y);
+    }
+    getLayoutInfo(key) {
+        return this.layoutInfos.get(key) || null;
+    }
+    getContentSize() {
+        return this.contentSize;
+    }
+    getVisibleLayoutInfos(rect) {
+        const layoutInfos = [];
+        for (const layoutInfo of this.layoutInfos.values()) {
+            if (layoutInfo.rect.intersects(rect) || this.virtualizer.isPersistedKey(layoutInfo.key) || layoutInfo.type === "loader") {
+                layoutInfos.push(layoutInfo);
+            }
+        }
+        return layoutInfos;
+    }
+    updateItemSize(key, size) {
+        const layoutInfo = this.layoutInfos.get(key);
+        if (!size || !layoutInfo)
+            return false;
+        if (size.height !== layoutInfo.rect.height) {
+            const newLayoutInfo = layoutInfo.copy();
+            newLayoutInfo.rect.height = size.height;
+            newLayoutInfo.estimatedSize = false;
+            this.layoutInfos.set(key, newLayoutInfo);
+            return true;
+        }
+        return false;
+    }
+    getDropTargetFromPoint(x, y, isValidDropTarget) {
+        if (this.layoutInfos.size === 0)
+            return { type: "root" };
+        x += this.virtualizer.visibleRect.x;
+        y += this.virtualizer.visibleRect.y;
+        // RTL: items are positioned with `right` = rect.x, pointer coordinates are left-origin; flip x.
+        if (this.direction === "rtl" && this.numColumns > 1)
+            x = this.contentSize.width - x;
+        // Find the closest item within on either side of the point using the gap width.
+        let key = null;
+        if (this.numColumns === 1) {
+            const searchRect = new Rect(x, Math.max(0, y - this.gap.height), 1, Math.max(1, this.gap.height * 2));
+            let minDistance = Infinity;
+            for (const candidate of this.getVisibleLayoutInfos(searchRect)) {
+                // Ignore items outside the search rect, e.g. persisted keys.
+                if (!candidate.rect.intersects(searchRect))
+                    continue;
+                const dist = Math.min(Math.abs(candidate.rect.y - y), Math.abs(candidate.rect.maxY - y));
+                if (dist < minDistance) {
+                    minDistance = dist;
+                    key = candidate.key;
+                }
+            }
+        }
+        else {
+            const searchRect = new Rect(Math.max(0, x - this.gap.width), y, this.gap.width * 2, 1);
+            let minDistance = Infinity;
+            for (const candidate of this.getVisibleLayoutInfos(searchRect)) {
+                if (!candidate.rect.intersects(searchRect))
+                    continue;
+                const dist = Math.min(Math.abs(candidate.rect.x - x), Math.abs(candidate.rect.maxX - x));
+                if (dist < minDistance) {
+                    minDistance = dist;
+                    key = candidate.key;
+                }
+            }
+        }
+        const layoutInfo = key != null ? this.getLayoutInfo(key) : null;
+        if (!layoutInfo)
+            return { type: "root" };
+        const target = { type: "item", key: layoutInfo.key, dropPosition: "on" };
+        const pos = this.numColumns === 1 ? y : x;
+        const layoutInfoPos = this.numColumns === 1 ? layoutInfo.rect.y : layoutInfo.rect.x;
+        const size = this.numColumns === 1 ? layoutInfo.rect.height : layoutInfo.rect.width;
+        if (isValidDropTarget(target)) {
+            // Accepted: still before / after within 5px of the start or end of the item.
+            if (pos < layoutInfoPos + 5)
+                target.dropPosition = "before";
+            else if (pos > layoutInfoPos + size - 5)
+                target.dropPosition = "after";
+        }
+        else {
+            // Not accepted: before / after depending on the position.
+            const mid = layoutInfoPos + size / 2;
+            if (pos <= mid && isValidDropTarget({ ...target, dropPosition: "before" }))
+                target.dropPosition = "before";
+            else if (pos >= mid && isValidDropTarget({ ...target, dropPosition: "after" }))
+                target.dropPosition = "after";
+        }
+        return target;
+    }
+    getDropTargetLayoutInfo(target) {
+        const layoutInfo = this.getLayoutInfo(target.key);
+        const t = this.dropIndicatorThickness;
+        let rect;
+        if (this.numColumns === 1) {
+            // Flip from vertical to horizontal if only one column is visible.
+            rect = new Rect(layoutInfo.rect.x, target.dropPosition === "before" ? layoutInfo.rect.y - this.gap.height / 2 - t / 2 : layoutInfo.rect.maxY + this.gap.height / 2 - t / 2, layoutInfo.rect.width, t);
+        }
+        else {
+            rect = new Rect(target.dropPosition === "before" ? layoutInfo.rect.x - this.gap.width / 2 - t / 2 : layoutInfo.rect.maxX + this.gap.width / 2 - t / 2, layoutInfo.rect.y, t, layoutInfo.rect.height);
+        }
+        return new LayoutInfo("dropIndicator", target.key + ":" + target.dropPosition, rect);
+    }
+}
+/** Layout options may arrive as plain `{ width, height }` objects (serialized props): normalize to `Size`. */
+export function sizeOf(value, fallback) {
+    if (!value)
+        return fallback;
+    return value instanceof Size ? value : new Size(value.width, value.height);
+}

package/virtualizer/index.d.ts

@@ -0,0 +1,2 @@
+export { Virtualizer, type VirtualizerProps } from "./virtualizer.jsx";
+export * from "./engine.js";

package/virtualizer/index.jsx

@@ -0,0 +1,4 @@
+// @rivetjs/cdk/virtualizer — React Spectrum's virtualizer (react-stately engine + layouts, react-aria
+// Virtualizer / ScrollView / VirtualizerItem) for Rivet. Apache-2.0 portions © Adobe; see NOTICE.
+export { Virtualizer } from "./virtualizer.jsx";
+export * from "./engine.js";

package/virtualizer/layout-info.d.ts

@@ -0,0 +1,33 @@
+import type { Key } from "../collections/index.js";
+import type { Rect } from "./rect.js";
+/**
+ * Instances of this lightweight class are created by `Layout` subclasses to represent each item in the
+ * `Virtualizer`: position, size and style information the virtualizer uses when rendering views.
+ */
+export declare class LayoutInfo {
+    /** The type of element represented by this LayoutInfo; matches the `type` of the collection node. */
+    type: string;
+    /** A unique key for this LayoutInfo; matches the `key` of the collection node. */
+    key: Key;
+    /** The key for a parent LayoutInfo, if any. */
+    parentKey: Key | null;
+    /** Content for this item if it was generated by the layout rather than coming from the Collection. */
+    content: any | null;
+    /** The rectangle describing the size and position of this element. */
+    rect: Rect;
+    /** Whether the size is estimated (measured the first time the item is added to the DOM). Default false. */
+    estimatedSize: boolean;
+    /** Whether the layout info sticks to the viewport when scrolling. Default false. */
+    isSticky: boolean;
+    /** The element's opacity. Default 1. */
+    opacity: number;
+    /** A CSS transform string to apply to the element. `null` by default. */
+    transform: string | null;
+    /** The z-index of the element. 0 by default. */
+    zIndex: number;
+    /** Whether the element allows its contents to overflow its container. Default false. */
+    allowOverflow: boolean;
+    constructor(type: string, key: Key, rect: Rect);
+    /** Returns a copy of the LayoutInfo. */
+    copy(): LayoutInfo;
+}