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

package/virtualizer/virtualizer-core.js

@@ -0,0 +1,304 @@
+import { OverscanManager } from "./overscan-manager.js";
+import { Rect } from "./rect.js";
+import { ChildView, RootView } from "./reusable-view.js";
+import { ScrollAnchorTracker } from "./scroll-anchor.js";
+import { Size } from "./size.js";
+import { isSetEqual } from "./utils.js";
+/**
+ * Renders a scrollable collection using customizable layouts: only visible views exist, reused as the user
+ * scrolls. Layouts compute what is visible and where (LayoutInfo); the delegate renders each view.
+ */
+export class Virtualizer {
+    /** The virtualizer delegate, used to create and configure views. */
+    delegate;
+    /** The current content of the virtualizer. */
+    collection;
+    /** The layout object that determines the visible views. */
+    layout;
+    /** The size of the scrollable content. */
+    contentSize;
+    /** The currently visible rectangle. */
+    visibleRect;
+    /** The size of the virtualizer scroll view. */
+    size;
+    /** The set of persisted keys that are always present in the DOM, even if not currently in view. */
+    persistedKeys;
+    _visibleViews;
+    _renderedContent;
+    _rootView;
+    _isScrolling;
+    _invalidationContext;
+    _overscanManager;
+    _scrollAnchor;
+    _viewKey = 0;
+    constructor(options) {
+        this.delegate = options.delegate;
+        this.collection = options.collection;
+        this.layout = options.layout;
+        this.contentSize = new Size();
+        this.visibleRect = new Rect();
+        this.size = new Size();
+        this.persistedKeys = new Set();
+        this._visibleViews = new Map();
+        this._renderedContent = new WeakMap();
+        this._rootView = new RootView(this);
+        this._isScrolling = false;
+        this._invalidationContext = {};
+        this._overscanManager = new OverscanManager();
+        this._scrollAnchor = new ScrollAnchorTracker();
+    }
+    /** @private Next ReusableView key. */
+    _nextViewKey() {
+        return ++this._viewKey;
+    }
+    /** Returns whether the given key, or an ancestor, is persisted. */
+    isPersistedKey(key) {
+        if (this.persistedKeys.has(key))
+            return true;
+        // Check if the key is an ancestor of any of the persisted keys.
+        for (let k of this.persistedKeys) {
+            while (k != null) {
+                const layoutInfo = this.layout.getLayoutInfo(k);
+                if (!layoutInfo || layoutInfo.parentKey == null)
+                    break;
+                k = layoutInfo.parentKey;
+                if (k === key)
+                    return true;
+            }
+        }
+        return false;
+    }
+    getParentView(layoutInfo) {
+        return layoutInfo.parentKey != null ? this._visibleViews.get(layoutInfo.parentKey) : this._rootView;
+    }
+    getReusableView(layoutInfo) {
+        const parentView = this.getParentView(layoutInfo);
+        const view = parentView.getReusableView(layoutInfo.type);
+        view.layoutInfo = layoutInfo;
+        this._renderView(view);
+        return view;
+    }
+    _renderView(reusableView) {
+        if (reusableView.layoutInfo) {
+            const { type, key, content } = reusableView.layoutInfo;
+            reusableView.content = content || this.collection.getItem(key);
+            reusableView.rendered = this._renderContent(type, reusableView.content);
+        }
+    }
+    _renderContent(type, content) {
+        const cached = content != null ? this._renderedContent.get(content) : null;
+        if (cached != null)
+            return cached;
+        const rendered = this.delegate.renderView(type, content);
+        if (content)
+            this._renderedContent.set(content, rendered);
+        return rendered;
+    }
+    /** Returns the key for the item view currently at the given point. */
+    keyAtPoint(point) {
+        const rect = new Rect(point.x, point.y, 1, 1);
+        const layoutInfos = rect.area === 0 ? [] : this.layout.getVisibleLayoutInfos(rect);
+        // Layouts may return persisted keys too: find the first one that actually intersects.
+        for (const layoutInfo of layoutInfos)
+            if (layoutInfo.rect.intersects(rect))
+                return layoutInfo.key;
+        return null;
+    }
+    relayout(context = {}) {
+        const anchorInfo = this.layout.UNSTABLE_getScrollAnchorInfo?.(context.layoutOptions) ?? null;
+        // Capture the scroll anchor from current (pre-layout) view positions; none on first render.
+        let anchor = null;
+        if (anchorInfo) {
+            const preLayoutInfos = [];
+            for (const [key, view] of this._visibleViews) {
+                const layoutInfo = this.layout.getLayoutInfo(key) ?? view.layoutInfo;
+                if (layoutInfo)
+                    preLayoutInfos.push([key, layoutInfo]);
+            }
+            anchor = this._scrollAnchor.captureBeforeLayout(anchorInfo, preLayoutInfos, this.visibleRect);
+        }
+        const previousContentSize = this.contentSize;
+        const previousVisibleRect = this.visibleRect;
+        this.layout.update(context);
+        const rawContentSize = this.layout.getContentSize();
+        this.contentSize = new Size(rawContentSize.width, rawContentSize.height);
+        const target = this._scrollAnchor.resolveAfterLayout({
+            anchorInfo,
+            anchor,
+            postLayoutInfos: anchorInfo ? this.getVisibleLayoutInfos() : new Map(),
+            previousVisibleRect,
+            previousContentSize,
+            contentSize: this.contentSize,
+            itemSizeChanged: context.itemSizeChanged ?? false,
+            isScrolling: this._isScrolling,
+            getLayoutInfo: (key) => this.layout.getLayoutInfo(key),
+        });
+        if (target) {
+            // Queues a new render cycle; skip updateSubviews (it would position views against the old rect).
+            this.delegate.setVisibleRect(target);
+            return;
+        }
+        // Constrain scroll position. If the content changed, scroll to the top.
+        const visibleRect = this.visibleRect;
+        let contentOffsetX = context.contentChanged ? 0 : visibleRect.x;
+        let contentOffsetY = context.contentChanged ? 0 : visibleRect.y;
+        contentOffsetX = Math.max(0, Math.min(this.contentSize.width - visibleRect.width, contentOffsetX));
+        contentOffsetY = Math.max(0, Math.min(this.contentSize.height - visibleRect.height, contentOffsetY));
+        if (contentOffsetX !== visibleRect.x || contentOffsetY !== visibleRect.y) {
+            // If the offset changed, trigger a new re-render.
+            this.delegate.setVisibleRect(new Rect(contentOffsetX, contentOffsetY, visibleRect.width, visibleRect.height));
+        }
+        else {
+            this.updateSubviews();
+        }
+    }
+    getVisibleLayoutInfos() {
+        const rect = this._overscanManager.getOverscannedRect();
+        const map = new Map();
+        for (const layoutInfo of this.layout.getVisibleLayoutInfos(rect))
+            map.set(layoutInfo.key, layoutInfo);
+        return map;
+    }
+    updateSubviews() {
+        const visibleLayoutInfos = this.getVisibleLayoutInfos();
+        const removed = new Set();
+        for (const [key, view] of this._visibleViews) {
+            const layoutInfo = visibleLayoutInfos.get(key);
+            // If a view's parent changed, treat it as a delete and re-create in the new parent.
+            if (!layoutInfo || view.parent !== this.getParentView(layoutInfo)) {
+                this._visibleViews.delete(key);
+                view.parent.reuseChild(view);
+                removed.add(view); // Defer removing in case we reuse this view.
+            }
+        }
+        for (const [key, layoutInfo] of visibleLayoutInfos) {
+            let view = this._visibleViews.get(key);
+            if (!view) {
+                view = this.getReusableView(layoutInfo);
+                view.parent.children.add(view);
+                this._visibleViews.set(key, view);
+                removed.delete(view);
+            }
+            else {
+                view.layoutInfo = layoutInfo;
+                const item = this.collection.getItem(layoutInfo.key);
+                if (view.content !== item) {
+                    if (view.content != null)
+                        this._renderedContent.delete(view.content);
+                    this._renderView(view);
+                }
+            }
+        }
+        // Views left in `removed` were not reused: remove them, and clear the reuse queue (FIFO order would
+        // otherwise hurt later reuse).
+        for (const view of removed) {
+            view.parent.children.delete(view);
+            view.parent.reusableViews.clear();
+        }
+        // Reordering DOM nodes is costly: deferred until scrolling stops (order matters for assistive technology,
+        // not for the absolutely positioned visual order). Layout infos are in topological order.
+        if (!this._isScrolling) {
+            for (const key of visibleLayoutInfos.keys()) {
+                const view = this._visibleViews.get(key);
+                view.parent.children.delete(view);
+                view.parent.children.add(view);
+            }
+        }
+    }
+    /** Performs layout and updates visible views as needed. */
+    render(opts) {
+        const mutableThis = this;
+        let needsLayout = false;
+        let offsetChanged = false;
+        let sizeChanged = false;
+        let widthChanged = false;
+        let heightChanged = false;
+        let itemSizeChanged = false;
+        let layoutOptionsChanged = false;
+        let needsUpdate = false;
+        if (opts.collection !== this.collection) {
+            mutableThis.collection = opts.collection;
+            needsLayout = true;
+        }
+        if (opts.layout !== this.layout || this.layout.virtualizer !== this) {
+            if (this.layout)
+                this.layout.virtualizer = null;
+            opts.layout.virtualizer = this;
+            mutableThis.layout = opts.layout;
+            this._scrollAnchor.reset();
+            needsLayout = true;
+        }
+        if (opts.persistedKeys && !isSetEqual(opts.persistedKeys, this.persistedKeys)) {
+            mutableThis.persistedKeys = opts.persistedKeys;
+            needsUpdate = true;
+        }
+        if (!this.visibleRect.equals(opts.visibleRect) || !this.size.equals(opts.size)) {
+            this._overscanManager.setVisibleRect(opts.visibleRect);
+            // Scroll position + layout size of the scroll view (not the visibleRect, whose size may change during
+            // window scrolling).
+            const oldRect = new Rect(this.visibleRect.x, this.visibleRect.y, this.size.width, this.size.height);
+            const newRect = new Rect(opts.visibleRect.x, opts.visibleRect.y, opts.size.width, opts.size.height);
+            if (this.layout.shouldInvalidate(newRect, oldRect)) {
+                offsetChanged = !opts.visibleRect.pointEquals(this.visibleRect);
+                sizeChanged = !this.size.equals(opts.size);
+                widthChanged = this.size.width !== opts.size.width;
+                heightChanged = this.size.height !== opts.size.height;
+                needsLayout = true;
+            }
+            else {
+                needsUpdate = true;
+            }
+            mutableThis.visibleRect = opts.visibleRect;
+            mutableThis.size = opts.size;
+        }
+        if (opts.invalidationContext !== this._invalidationContext) {
+            if (opts.invalidationContext) {
+                sizeChanged ||= opts.invalidationContext.sizeChanged || false;
+                widthChanged ||= opts.invalidationContext.widthChanged || false;
+                heightChanged ||= opts.invalidationContext.heightChanged || false;
+                offsetChanged ||= opts.invalidationContext.offsetChanged || false;
+                itemSizeChanged ||= opts.invalidationContext.itemSizeChanged || false;
+                layoutOptionsChanged ||=
+                    opts.invalidationContext.layoutOptions != null &&
+                        this._invalidationContext.layoutOptions != null &&
+                        opts.invalidationContext.layoutOptions !== this._invalidationContext.layoutOptions &&
+                        this.layout.shouldInvalidateLayoutOptions(opts.invalidationContext.layoutOptions, this._invalidationContext.layoutOptions);
+                needsLayout ||= itemSizeChanged || sizeChanged || offsetChanged || layoutOptionsChanged;
+            }
+            this._invalidationContext = opts.invalidationContext;
+        }
+        if (opts.isScrolling !== this._isScrolling) {
+            this._isScrolling = opts.isScrolling;
+            // Update to fix the DOM order after scrolling.
+            if (!opts.isScrolling)
+                needsUpdate = true;
+        }
+        if (needsLayout) {
+            this.relayout({
+                offsetChanged,
+                sizeChanged,
+                widthChanged,
+                heightChanged,
+                itemSizeChanged,
+                layoutOptionsChanged,
+                layoutOptions: this._invalidationContext.layoutOptions,
+            });
+        }
+        else if (needsUpdate) {
+            this.updateSubviews();
+        }
+        return Array.from(this._rootView.children);
+    }
+    getVisibleView(key) {
+        return this._visibleViews.get(key);
+    }
+    invalidate(context) {
+        this.delegate.invalidate(context);
+    }
+    updateItemSize(key, size) {
+        if (!this.layout.updateItemSize)
+            return;
+        if (this.layout.updateItemSize(key, size))
+            this.invalidate({ itemSizeChanged: true });
+    }
+}

package/virtualizer/virtualizer.d.ts

@@ -0,0 +1,64 @@
+import type { Slot } from "@rivetjs/runtime/jsx-runtime";
+import type { Key } from "../collections/index.js";
+import { type LayoutInput, type MaybeAccessor, type VirtualView } from "./behaviour.js";
+import type { CollectionOptions } from "./collection.js";
+import type { Direction } from "./types.js";
+import type { StyleObject } from "@rivetjs/runtime/style";
+import { type GlobalDOMAttributes } from "@rivetjs/cdk/dom-props";
+/** Global DOM events / attributes go to the scroller element. */
+export interface VirtualizerProps<T, O> extends Omit<GlobalDOMAttributes<HTMLDivElement>, "dir" | "onScroll"> {
+    /** The data: an array, or an accessor (`() => list()`) whose changes re-render the window. */
+    items: MaybeAccessor<readonly T[]>;
+    /** Layout class (`ListLayout`) or factory (`() => new ListLayout()`): resumable, instantiated on the server and on first scroll. */
+    layout: LayoutInput<O>;
+    /** Options for the layout (JSON: `{ rowHeight: 32 }`, `{ minItemSize: { width: 120, height: 120 } }`). */
+    layoutOptions?: O;
+    /** View content: `(item, view) => …`; `view().type` tells items from sections / headers / loaders. */
+    children: Slot<[item: () => T, view: () => VirtualView<T>]>;
+    /** Viewport size used for the server-rendered window (match the scroller's CSS size). Default 800 x 600. */
+    initialSize?: {
+        width: number;
+        height: number;
+    };
+    /** Scrollable axes. Default `vertical` (`both` for grids wider than the viewport). */
+    scrollDirection?: "horizontal" | "vertical" | "both";
+    /** Keys always rendered even when out of view (the focused view is persisted automatically). */
+    persistedKeys?: Iterable<Key>;
+    /** Whether more data is loading (reserves the loader view's size). */
+    isLoading?: MaybeAccessor<boolean>;
+    /** Called when scrolled within `loadMoreOffset` viewports of the end. */
+    onLoadMore?: () => void;
+    /** Distance from the end that triggers `onLoadMore`, in viewport heights. Default 1. */
+    loadMoreOffset?: number;
+    /** Re-measure views when their content resizes (ResizeObserver on each view's children). */
+    shouldObserveItemSize?: boolean;
+    /** Text direction for view positions (`left` / `right`); default: logical `inset-inline-start`. */
+    dir?: Direction;
+    /** Collection adapter options: keys, node types, section children. */
+    getKey?: CollectionOptions<T>["getKey"];
+    getType?: CollectionOptions<T>["getType"];
+    getChildren?: CollectionOptions<T>["getChildren"];
+    getTextValue?: CollectionOptions<T>["getTextValue"];
+    /** Caller scroll handler (runs after the virtualizer's). */
+    onScroll?: (event: Event) => void;
+    id?: string;
+    /** Scroller role (e.g. `listbox`, `grid`); default `presentation`-free plain div. */
+    role?: string;
+    label?: string;
+    labelledBy?: string;
+    tabIndex?: number;
+    /** Scroller class (default `rv-Virtualizer`). */
+    class?: string;
+    /** Scroller inline style (sizing), merged over the overflow style. */
+    style?: StyleObject;
+    /** View wrapper class (default `rv-Virtualizer-item`). */
+    itemClass?: string;
+}
+/**
+ * Renders a scrollable collection with a layout (ListLayout, GridLayout, TableLayout, WaterfallLayout): only
+ * views inside the visible rect (plus overscan and persisted keys) are in the DOM. Renders its own views
+ * (`children(item, view)`) from `items`; a cdk collection component (`ListBox`, `Table`) is virtualized by
+ * `CollectionVirtualizer` (`./collection-renderer.tsx`), kept apart so this component and its users (Masonry)
+ * carry none of the collection renderer.
+ */
+export declare function Virtualizer<T, O = unknown>(props: VirtualizerProps<T, O>): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/virtualizer/virtualizer.jsx

@@ -0,0 +1,91 @@
+// Virtualizer component: the react-aria / react-aria-components `Virtualizer` (React Spectrum, Apache-2.0,
+// © Adobe) for Rivet. The server renders the first window (engine at `initialSize`, absolutely positioned
+// views); the browser runs the engine from the first scroll (or focus) on: measured sizes, keyed rows.
+// Resumed pages: no library code runs before the visitor scrolls (`preload="interaction"` on the scroller).
+import { computed, signal } from "@rivetjs/reactivity";
+import { For } from "@rivetjs/runtime/dom";
+import { createId } from "../utils/id.js";
+import { contentStyle, initialWindow, scrollerStyle, virtualizerFocusIn, virtualizerScroll, viewKeys, viewOf, visibleViews, } from "./behaviour.js";
+import { globalDOMProps } from "@rivetjs/cdk/dom-props";
+/** Global DOM props the scroller sets itself (`onScroll` runs after the virtualizer's, `dir` positions views). */
+const OWNED = ["onScroll", "dir"];
+/**
+ * Renders a scrollable collection with a layout (ListLayout, GridLayout, TableLayout, WaterfallLayout): only
+ * views inside the visible rect (plus overscan and persisted keys) are in the DOM. Renders its own views
+ * (`children(item, view)`) from `items`; a cdk collection component (`ListBox`, `Table`) is virtualized by
+ * `CollectionVirtualizer` (`./collection-renderer.tsx`), kept apart so this component and its users (Masonry)
+ * carry none of the collection renderer.
+ */
+export function Virtualizer(props) {
+    const collection = {};
+    if (props.getKey)
+        collection.getKey = props.getKey;
+    if (props.getType)
+        collection.getType = props.getType;
+    if (props.getChildren)
+        collection.getChildren = props.getChildren;
+    if (props.getTextValue)
+        collection.getTextValue = props.getTextValue;
+    const model = {
+        id: props.id ?? createId(),
+        items: props.items,
+        layout: props.layout,
+        layoutOptions: props.layoutOptions,
+        collection,
+        initialSize: props.initialSize ?? { width: 800, height: 600 },
+        dir: props.dir,
+        isLoading: props.isLoading,
+        onLoadMore: props.onLoadMore,
+        loadMoreOffset: props.loadMoreOffset ?? 1,
+        shouldObserveItemSize: props.shouldObserveItemSize ?? false,
+        persistedKeys: [...(props.persistedKeys ?? [])],
+        focusedKey: signal(null),
+        views: signal([]),
+        contentSize: signal({ width: 0, height: 0 }),
+        isScrolling: signal(false),
+        onScroll: props.onScroll,
+    };
+    const first = initialWindow(model);
+    model.views.set(first.views);
+    model.contentSize.set(first.contentSize);
+    const render = props.children;
+    const itemClass = props.itemClass ?? "rv-Virtualizer-item";
+    // Read every prop up front: an element with a spread resumes as one binding over all its
+    // attributes, and reading `props` there would capture the whole props object (children included).
+    const dom = globalDOMProps(props, OWNED);
+    const className = props.class ?? "rv-Virtualizer", role = props.role, label = props.label, labelledBy = props.labelledBy, tabIndex = props.tabIndex, dir = props.dir, style = { ...scrollerStyle(props.scrollDirection ?? "vertical"), ...props.style };
+    return (<div {...dom} id={model.id} class={className} role={role} aria-label={label} aria-labelledby={labelledBy} tabIndex={tabIndex} dir={dir} style={style} preload="interaction" onScroll={(event) => virtualizerScroll(model, event)} onFocusIn={(event) => virtualizerFocusIn(model, event)}>
+      <div role="presentation" class="rv-Virtualizer-content" style={contentStyle(model)}>
+        <For each={() => viewKeys(visibleViews(model))} by={(key) => key}>
+          {(key) => {
+            // Local functions, not call arguments: the row accessors handed to `children` must be resumable (R2).
+            const view = () => viewOf(model, model.views(), key());
+            const item = () => view().item;
+            // A computed: the branch re-runs only when a view gains / loses children, not on every layout pass
+            // (a resumed page would re-create the nested rows and leave their server bindings on removed elements).
+            const nested = computed(() => view().children.length > 0);
+            return (<div role="presentation" class={itemClass} data-rv-view={String(key())} data-rv-type={view().type} style={view().style}>
+                {render(item, view)}
+                {nested() ? <VirtualizerChildren model={model} views={() => view().children} render={render} itemClass={itemClass}/> : null}
+              </div>);
+        }}
+        </For>
+      </div>
+    </div>);
+}
+/** Nested views (section items, table rows / cells), positioned relative to their parent view. */
+function VirtualizerChildren(props) {
+    const { model, views, render, itemClass } = props;
+    return (<For each={() => viewKeys(views())} by={(key) => key}>
+      {(key) => {
+            // Local functions, not call arguments: the row accessors handed to `children` must be resumable (R2).
+            const view = () => viewOf(model, views(), key());
+            const item = () => view().item;
+            const nested = computed(() => view().children.length > 0);
+            return (<div role="presentation" class={itemClass} data-rv-view={String(key())} data-rv-type={view().type} style={view().style}>
+            {render(item, view)}
+            {nested() ? <VirtualizerChildren model={model} views={() => view().children} render={render} itemClass={itemClass}/> : null}
+          </div>);
+        }}
+    </For>);
+}

package/virtualizer/waterfall-layout.d.ts

@@ -0,0 +1,41 @@
+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 { DropTarget, DropTargetDelegate, InvalidationContext, LayoutDelegate } from "./types.js";
+export interface WaterfallLayoutOptions {
+    /** The minimum item size. Default 200 x 200. */
+    minItemSize?: Size;
+    /** The maximum item size. Default Infinity. */
+    maxItemSize?: Size;
+    /** 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;
+}
+/** Masonry: items of a column stack with their measured heights; each item goes to the shortest column. */
+export declare class WaterfallLayout<T extends object, O extends WaterfallLayoutOptions = WaterfallLayoutOptions> extends Layout<Node<T>, O> implements LayoutDelegate, DropTargetDelegate {
+    private contentSize;
+    private layoutInfos;
+    protected numColumns: number;
+    protected dropIndicatorThickness: number;
+    private margin;
+    shouldInvalidateLayoutOptions(newOptions: O, oldOptions: O): boolean;
+    update(invalidationContext: InvalidationContext<O>): void;
+    getLayoutInfo(key: Key): LayoutInfo;
+    getContentSize(): Size;
+    getVisibleLayoutInfos(rect: Rect): LayoutInfo[];
+    updateItemSize(key: Key, size: Size): boolean;
+    getKeyRightOf(key: Key): Key | null;
+    getKeyLeftOf(key: Key): Key | null;
+    getKeyRange(from: Key, to: Key): Key[];
+    getDropTargetFromPoint(x: number, y: number): DropTarget;
+}