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

package/scrolling/state.d.ts

@@ -0,0 +1,92 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { ListRange, VirtualScrollStrategy, VirtualScrollStrategyViewport } from "./virtual-scroll-strategy.js";
+export type { Orientation } from "../collections/types.js";
+import type { Orientation } from "../collections/types.js";
+export interface VirtualScrollOptions<T> {
+    /** The data (Angular `cdkVirtualForOf`): a signal (live) or an array. */
+    items: Signal<readonly T[]> | Signal<T[]> | readonly T[];
+    /** Fixed item size in px (Angular `itemSize`, default 20). Ignored with `autosize`. */
+    itemSize?: number;
+    /** Auto-size strategy (cdk-experimental `autosize`) for items of unknown / varying size. */
+    autosize?: boolean;
+    /** Minimum buffer beyond the viewport in px (default 100). */
+    minBufferPx?: number;
+    /** Buffer to render when rendering more, in px (default 200). */
+    maxBufferPx?: number;
+    orientation?: Orientation;
+    /** Keep rendered items in the DOM after they scroll out of view (default false). */
+    appendOnly?: boolean;
+    /**
+     * Scroll container: `"self"` (default: the viewport scrolls), `"window"` (Angular `scrollWindow`)
+     * or `"element"` (the nearest `CdkVirtualScrollableElement` ancestor; pass this state to it).
+     */
+    scrollable?: "self" | "window" | "element";
+    /** Template cache size (Angular `cdkVirtualForTemplateCacheSize`): accepted for parity; rows are keyed. */
+    templateCacheSize?: number;
+    /** Viewport size in px assumed for the server-rendered range (default 0: just the buffer). */
+    initialViewportSize?: number;
+    id?: string;
+}
+export interface VirtualScrollState<T> {
+    readonly id: string;
+    readonly items: Signal<readonly T[]>;
+    /** Rendered range (rows `[start, end)` are in the DOM). */
+    readonly range: Signal<ListRange>;
+    /** Total content size in px (spacer). */
+    readonly totalSize: Signal<number>;
+    /** Content wrapper transform (`translateY(<offset>px)`). */
+    readonly transform: Signal<string>;
+    /** Offset of the rendered content in px (last `setRenderedContentOffset` "to-start" value). */
+    readonly offset: Signal<number>;
+    readonly itemSize: number;
+    readonly autosize: boolean;
+    readonly minBufferPx: number;
+    readonly maxBufferPx: number;
+    readonly orientation: Orientation;
+    readonly appendOnly: boolean;
+    readonly scrollable: "self" | "window" | "element";
+}
+/**
+ * Viewport callbacks: component props (`<CdkVirtualScrollViewport onScrolledIndexChange>`), not
+ * state options — a `const` initialized with inline functions is re-created on the client from its
+ * symbol (compiler rule for derived consts), which would detach the state's signals.
+ */
+export interface VirtualScrollCallbacks {
+    /** Index of the first visible item (fixed strategy; Angular `scrolledIndexChange`). */
+    onScrolledIndexChange?: (index: number) => void;
+    /** Rendered range (Angular `renderedRangeStream` / CdkVirtualForOf `viewChange`). */
+    onRenderedRangeChange?: (range: ListRange) => void;
+}
+/** The strategy for `state` (Angular: the `itemSize` / `autosize` directive's strategy). */
+export declare function createStrategy(state: Pick<VirtualScrollState<unknown>, "autosize" | "itemSize" | "minBufferPx" | "maxBufferPx">): VirtualScrollStrategy;
+/** Content transform for an offset (Angular `setRenderedContentOffset`). */
+export declare function contentTransform(orientation: Orientation, offset: number, rtl?: boolean, toEnd?: boolean): string;
+/**
+ * Measurement model of a viewport that is not in a browser (server render): scroll offset 0, the
+ * given viewport size, rendered items measured at the estimated size. Runs strategies unchanged.
+ */
+export declare class VirtualScrollModel implements VirtualScrollStrategyViewport {
+    range: ListRange;
+    total: number;
+    offset: number;
+    private dataLength;
+    private viewportSize;
+    private estimate;
+    private appendOnly;
+    private strategy?;
+    constructor(dataLength: number, viewportSize: number, estimate: number, appendOnly?: boolean);
+    run(strategy: VirtualScrollStrategy): this;
+    getDataLength: () => number;
+    getViewportSize: () => number;
+    getRenderedRange: () => ListRange;
+    setRenderedRange(range: ListRange): void;
+    setTotalContentSize(size: number): void;
+    setRenderedContentOffset(offset: number): void;
+    getOffsetToRenderedContentStart: () => number;
+    measureScrollOffset: () => number;
+    measureRenderedContentSize: () => number;
+    measureRangeSize: (range: ListRange) => number;
+    scrollToOffset(): void;
+}
+/** Virtual scroll state with the server-rendered (first) range computed. */
+export declare function createVirtualScroll<T>(options: VirtualScrollOptions<T>): VirtualScrollState<T>;

package/scrolling/state.js

@@ -0,0 +1,94 @@
+// Virtual scroll state: plain signals + options (serializable), shared by CdkVirtualScrollViewport and
+// CdkVirtualForOf (explicit shared state instead of Angular DI). The server computes the first rendered range by running the real strategy against
+// a measurement model (initial viewport size, estimated item sizes); the browser engine takes over on
+// the first scroll / interaction (zero JS before it).
+import { signal, untrack } from "@rivetjs/reactivity";
+import { createId } from "@rivetjs/runtime/id";
+import { AutoSizeVirtualScrollStrategy } from "./auto-size-virtual-scroll.js";
+import { FixedSizeVirtualScrollStrategy } from "./fixed-size-virtual-scroll.js";
+/** The strategy for `state` (Angular: the `itemSize` / `autosize` directive's strategy). */
+export function createStrategy(state) {
+    if (state.maxBufferPx < state.minBufferPx)
+        throw Error("CDK virtual scroll: maxBufferPx must be greater than or equal to minBufferPx");
+    return state.autosize
+        ? new AutoSizeVirtualScrollStrategy(state.minBufferPx, state.maxBufferPx)
+        : new FixedSizeVirtualScrollStrategy(state.itemSize, state.minBufferPx, state.maxBufferPx);
+}
+/** Content transform for an offset (Angular `setRenderedContentOffset`). */
+export function contentTransform(orientation, offset, rtl = false, toEnd = false) {
+    const axis = orientation == "horizontal" ? "X" : "Y";
+    const axisDirection = orientation == "horizontal" && rtl ? -1 : 1;
+    let transform = `translate${axis}(${Number(axisDirection * offset)}px)`;
+    if (toEnd)
+        transform += ` translate${axis}(-100%)`;
+    return transform;
+}
+/**
+ * Measurement model of a viewport that is not in a browser (server render): scroll offset 0, the
+ * given viewport size, rendered items measured at the estimated size. Runs strategies unchanged.
+ */
+export class VirtualScrollModel {
+    range = { start: 0, end: 0 };
+    total = 0;
+    offset = 0;
+    dataLength;
+    viewportSize;
+    estimate;
+    appendOnly;
+    strategy;
+    constructor(dataLength, viewportSize, estimate, appendOnly = false) {
+        this.dataLength = dataLength;
+        this.viewportSize = viewportSize;
+        this.estimate = estimate;
+        this.appendOnly = appendOnly;
+    }
+    run(strategy) {
+        this.strategy = strategy;
+        strategy.attach(this);
+        strategy.onContentRendered();
+        strategy.onRenderedOffsetChanged();
+        strategy.detach();
+        return this;
+    }
+    getDataLength = () => this.dataLength;
+    getViewportSize = () => this.viewportSize;
+    getRenderedRange = () => this.range;
+    setRenderedRange(range) {
+        this.range = this.appendOnly ? { start: 0, end: Math.max(this.range.end, range.end) } : range;
+    }
+    setTotalContentSize(size) {
+        this.total = size;
+    }
+    setRenderedContentOffset(offset) {
+        this.offset = this.appendOnly ? 0 : offset;
+    }
+    getOffsetToRenderedContentStart = () => this.offset;
+    measureScrollOffset = () => 0;
+    measureRenderedContentSize = () => (this.range.end - this.range.start) * this.estimate;
+    measureRangeSize = (range) => Math.max(0, range.end - range.start) * this.estimate;
+    scrollToOffset() { }
+}
+/** Virtual scroll state with the server-rendered (first) range computed. */
+export function createVirtualScroll(options) {
+    const items = (typeof options.items === "function" ? options.items : signal(options.items));
+    const orientation = options.orientation ?? "vertical";
+    const base = {
+        autosize: !!options.autosize,
+        itemSize: options.itemSize ?? 20,
+        minBufferPx: options.minBufferPx ?? 100,
+        maxBufferPx: options.maxBufferPx ?? 200,
+    };
+    const model = new VirtualScrollModel(untrack(items).length, options.initialViewportSize ?? 0, base.autosize ? 50 : base.itemSize, !!options.appendOnly).run(createStrategy(base));
+    return {
+        id: options.id ?? createId(),
+        items,
+        range: signal(model.range),
+        totalSize: signal(model.total),
+        transform: signal(contentTransform(orientation, model.offset)),
+        offset: signal(model.offset),
+        ...base,
+        orientation,
+        appendOnly: !!options.appendOnly,
+        scrollable: options.scrollable ?? "self",
+    };
+}

package/scrolling/viewport-ruler.d.ts

@@ -0,0 +1,47 @@
+import { type Stream } from "./emitter.js";
+/** Time in ms to throttle the resize events by default. */
+export declare const DEFAULT_RESIZE_TIME = 20;
+/** Object that holds the scroll position of the viewport in each direction. */
+export interface ViewportScrollPosition {
+    top: number;
+    left: number;
+}
+/** Simple utility for getting the bounds of the browser viewport. */
+export declare class ViewportRuler {
+    private _listeners;
+    /** Cached viewport dimensions. */
+    private _viewportSize;
+    /** Stream of viewport change events. */
+    private readonly _change;
+    protected _document: Document | undefined;
+    constructor(doc?: Document);
+    private _listen;
+    private _unlisten;
+    /** Remove listeners and complete `change()` (Angular `ngOnDestroy`). */
+    destroy(): void;
+    /** Returns the viewport's width and height. */
+    getViewportSize(): Readonly<{
+        width: number;
+        height: number;
+    }>;
+    /** Gets a DOMRect-like object for the viewport's bounds. */
+    getViewportRect(): {
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+        height: number;
+        width: number;
+    };
+    /** Gets the (top, left) scroll position of the viewport. */
+    getViewportScrollPosition(): ViewportScrollPosition;
+    /**
+     * Stream that emits whenever the size of the viewport changes.
+     * @param throttleTime Time in milliseconds to throttle the stream.
+     */
+    change(throttleTime?: number): Stream<Event>;
+    private _getWindow;
+    private _updateViewportSize;
+}
+/** The shared ViewportRuler of `doc` (Angular root service), created on first use. */
+export declare function viewportRuler(doc?: Document): ViewportRuler;

package/scrolling/viewport-ruler.js

@@ -0,0 +1,100 @@
+// Ported from Angular Components (src/cdk/scrolling/viewport-ruler.ts), MIT, © Google LLC.
+// Rivet: no DI / NgZone — `viewportRuler(document?)` returns the lazily created per-document instance;
+// `change()` is a `Stream` (subscribe/unsubscribe) instead of an RxJS Observable. Window listeners are
+// added on first `change()` subscription (Angular: at construction) and removed with the last one.
+import { auditTime, Emitter } from "./emitter.js";
+/** Time in ms to throttle the resize events by default. */
+export const DEFAULT_RESIZE_TIME = 20;
+const isBrowser = () => typeof document === "object" && !!document && typeof window === "object";
+/** Simple utility for getting the bounds of the browser viewport. */
+export class ViewportRuler {
+    _listeners;
+    /** Cached viewport dimensions. */
+    _viewportSize = null;
+    /** Stream of viewport change events. */
+    _change;
+    _document;
+    constructor(doc) {
+        this._document = doc ?? (typeof document === "object" ? document : undefined);
+        this._change = new Emitter((count) => (count ? this._listen() : this._unlisten()));
+    }
+    _listen() {
+        if (this._listeners || !isBrowser())
+            return;
+        const win = this._getWindow();
+        const changeListener = (event) => {
+            // Clear the cached size so that the viewport is re-measured next time it is required.
+            this._viewportSize = null;
+            this._change.next(event);
+        };
+        win.addEventListener("resize", changeListener);
+        win.addEventListener("orientationchange", changeListener);
+        this._listeners = [() => win.removeEventListener("resize", changeListener), () => win.removeEventListener("orientationchange", changeListener)];
+    }
+    _unlisten() {
+        this._listeners?.forEach((cleanup) => cleanup());
+        this._listeners = undefined;
+    }
+    /** Remove listeners and complete `change()` (Angular `ngOnDestroy`). */
+    destroy() {
+        this._unlisten();
+        this._change.complete();
+    }
+    /** Returns the viewport's width and height. */
+    getViewportSize() {
+        // Without change() subscribers nothing invalidates the cache: re-measure every time then.
+        if (!this._viewportSize || !this._listeners)
+            this._updateViewportSize();
+        const output = { width: this._viewportSize.width, height: this._viewportSize.height };
+        // If we're not on a browser, don't cache the size since it'll be mocked out anyway.
+        if (!isBrowser())
+            this._viewportSize = null;
+        return output;
+    }
+    /** Gets a DOMRect-like object for the viewport's bounds. */
+    getViewportRect() {
+        // The document element's bounding rect rather than window scroll properties: they can disagree
+        // under pinch-zoom (https://bugs.chromium.org/p/chromium/issues/detail?id=489206#c4).
+        const scrollPosition = this.getViewportScrollPosition();
+        const { width, height } = this.getViewportSize();
+        return { top: scrollPosition.top, left: scrollPosition.left, bottom: scrollPosition.top + height, right: scrollPosition.left + width, height, width };
+    }
+    /** Gets the (top, left) scroll position of the viewport. */
+    getViewportScrollPosition() {
+        if (!isBrowser() || !this._document)
+            return { top: 0, left: 0 };
+        // Chrome and Firefox disagree on whether body or documentElement scrolls; the documentElement
+        // rect's negative top/left equals the scroll position in both.
+        const doc = this._document;
+        const win = this._getWindow();
+        const documentElement = doc.documentElement;
+        const documentRect = documentElement.getBoundingClientRect();
+        const top = -documentRect.top || doc.body?.scrollTop || win.scrollY || documentElement.scrollTop || 0;
+        const left = -documentRect.left || doc.body?.scrollLeft || win.scrollX || documentElement.scrollLeft || 0;
+        return { top, left };
+    }
+    /**
+     * Stream that emits whenever the size of the viewport changes.
+     * @param throttleTime Time in milliseconds to throttle the stream.
+     */
+    change(throttleTime = DEFAULT_RESIZE_TIME) {
+        return throttleTime > 0 ? auditTime(this._change, throttleTime) : this._change;
+    }
+    _getWindow() {
+        return this._document?.defaultView || window;
+    }
+    _updateViewportSize() {
+        const win = isBrowser() ? this._getWindow() : undefined;
+        this._viewportSize = win ? { width: win.innerWidth, height: win.innerHeight } : { width: 0, height: 0 };
+    }
+}
+const rulers = new WeakMap();
+const serverKey = {};
+/** The shared ViewportRuler of `doc` (Angular root service), created on first use. */
+export function viewportRuler(doc) {
+    const key = doc ?? (typeof document === "object" && document ? document : serverKey);
+    let ruler = rulers.get(key);
+    if (!ruler)
+        rulers.set(key, (ruler = new ViewportRuler(doc)));
+    return ruler;
+}

package/scrolling/viewport.d.ts

@@ -0,0 +1,54 @@
+import type { Content, Slot } from "@rivetjs/runtime/jsx-runtime";
+import type { ListRange } from "./virtual-scroll-strategy.js";
+import type { VirtualScrollState } from "./state.js";
+import { type GlobalDOMAttributes } from "@rivetjs/cdk/dom-props";
+/** Global DOM events / attributes go to the viewport element. */
+export interface CdkVirtualScrollViewportProps<T> extends GlobalDOMAttributes<HTMLDivElement> {
+    state: VirtualScrollState<T>;
+    class?: string;
+    label?: string;
+    /** Index of the first visible item (fixed strategy; Angular `scrolledIndexChange`). */
+    onScrolledIndexChange?: (index: number) => void;
+    /** Rendered range changes (Angular `renderedRangeStream`). */
+    onRenderedRangeChange?: (range: ListRange) => void;
+    /** Row identity for a row-template child (Angular `cdkVirtualForTrackBy`), absolute index. */
+    trackBy?: (index: number, item: T) => unknown;
+    /**
+     * A row template (Angular `<div *cdkVirtualFor>` directly in the viewport): rows render straight
+     * into the content wrapper. Or content holding a `<CdkVirtualForOf>` under a native element
+     * (`<ul><CdkVirtualForOf/></ul>`, `<table><tbody>…`): its own update region.
+     */
+    children?: Slot<[item: () => T, context: CdkVirtualForOfContext]> | Content;
+}
+/** A viewport that virtualizes its scrolling with the help of `CdkVirtualForOf`. */
+export declare function CdkVirtualScrollViewport<T>(props: CdkVirtualScrollViewportProps<T>): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** Row context (Angular `CdkVirtualForOfContext`). */
+export interface CdkVirtualForOfContext {
+    /** Absolute index in the data. */
+    index: () => number;
+    count: () => number;
+    first: () => boolean;
+    last: () => boolean;
+    even: () => boolean;
+    odd: () => boolean;
+}
+export interface CdkVirtualForOfProps<T> {
+    state: VirtualScrollState<T>;
+    /** Item identity (Angular `cdkVirtualForTrackBy`), called with the absolute index. Default: the item. */
+    trackBy?: (index: number, item: T) => unknown;
+    /** Row template (Angular `*cdkVirtualFor` template / `cdkVirtualForTemplate`). One root element per row. */
+    children: Slot<[item: () => T, context: CdkVirtualForOfContext]>;
+}
+/**
+ * Renders the rendered range of `state.items` as keyed rows (reused across scrolls by identity). Place it
+ * under a native element (`<ul>`, `<tbody>`, `<div>`) so it gets its own update region; directly in the
+ * viewport, pass the row template as the viewport's child instead.
+ */
+export declare function CdkVirtualForOf<T>(props: CdkVirtualForOfProps<T>): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** An ancestor scroll container for viewports created with `scrollable: "element"` (Angular `cdkVirtualScrollingElement`). */
+export declare function CdkVirtualScrollableElement(props: {
+    states: readonly VirtualScrollState<any>[];
+    class?: string;
+    id?: string;
+    children?: Content;
+} & GlobalDOMAttributes<HTMLDivElement>): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/scrolling/viewport.jsx

@@ -0,0 +1,105 @@
+// Ported from Angular Components (src/cdk/scrolling/{virtual-scroll-viewport.html,virtual-for-of.ts,
+// virtual-scrollable-element.ts,scrollable.ts}), MIT, © Google LLC.
+// Rivet components: <CdkVirtualScrollViewport state> (viewport + content wrapper + spacer),
+// <CdkVirtualForOf state> (keyed rows of the rendered range), <CdkVirtualScrollableElement> (an
+// ancestor scroll container). State from `createVirtualScroll` is shared explicitly (children render
+// before parents: no DI). Server: the first range is rendered; the browser engine
+// (virtual-scroll-viewport.ts) starts on the first scroll / wheel / pointer / focus / key interaction.
+import { untrack } from "@rivetjs/reactivity";
+import { For } from "@rivetjs/runtime/dom";
+import { viewportInteract } from "./behaviour.js";
+import { globalDOMProps } from "@rivetjs/cdk/dom-props";
+import { isSlot, renderSlot } from "@rivetjs/runtime/slot";
+/** Global DOM events the viewport handles itself (engine start); the user's handlers run after its own. */
+const OWNED = ["onScroll", "onWheel", "onPointerDown"];
+const SCROLLABLE_OWNED = ["onScroll"];
+/** A viewport that virtualizes its scrolling with the help of `CdkVirtualForOf`. */
+export function CdkVirtualScrollViewport(props) {
+    const { state, onScrolledIndexChange, onRenderedRangeChange, trackBy, children, onScroll, onWheel, onPointerDown } = props;
+    const callbacks = { onScrolledIndexChange, onRenderedRangeChange };
+    // A row template is a user render function `(item, context) => …`; plain content arrives as a compiler slot.
+    const rowTemplate = typeof children === "function" && !isSlot(children);
+    const horizontal = state.orientation === "horizontal";
+    const cls = "cdk-virtual-scroll-viewport" +
+        (state.scrollable === "self" ? " cdk-virtual-scrollable" : "") +
+        (horizontal ? " cdk-virtual-scroll-orientation-horizontal" : " cdk-virtual-scroll-orientation-vertical") +
+        (props.class ? " " + props.class : "");
+    // 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 label = props.label;
+    return (<div {...dom} id={state.id} class={cls} data-rv-virtual-viewport="" aria-label={label} onScroll={onScroll
+            ? (event) => {
+                viewportInteract(state, event, callbacks);
+                onScroll(event);
+            }
+            : (event) => viewportInteract(state, event, callbacks)} onWheel={onWheel
+            ? (event) => {
+                viewportInteract(state, event, callbacks);
+                onWheel(event);
+            }
+            : (event) => viewportInteract(state, event, callbacks)} onPointerDown={onPointerDown
+            ? (event) => {
+                viewportInteract(state, event, callbacks);
+                onPointerDown(event);
+            }
+            : (event) => viewportInteract(state, event, callbacks)} onFocusIn={(event) => viewportInteract(state, event, callbacks)} onKeyDown={(event) => viewportInteract(state, event, callbacks)}>
+      <div class="cdk-virtual-scroll-content-wrapper" style={{ transform: state.transform() }}>
+        {/* The row-template For sits directly in the wrapper: its own update region (a For inside a
+            conditional gets none — queued compiler work); with content children it renders nothing. */}
+        {rowTemplate ? <template data-rv-vfor={state.id}></template> : null}
+        <For each={() => (rowTemplate ? state.items().slice(state.range().start, state.range().end) : [])} by={(item, i) => (trackBy ? trackBy(i + untrack(state.range).start, item) : item)}>
+          {(item, i) => children(item, rowContext(state, i))}
+        </For>
+        {rowTemplate ? <template data-rv-vfor-end=""></template> : renderSlot(children)}
+      </div>
+      <div class="cdk-virtual-scroll-spacer" style={{ width: horizontal ? `${state.totalSize()}px` : undefined, height: horizontal ? undefined : `${state.totalSize()}px` }}></div>
+      {state.scrollable === "window" ? (
+        // Window scrolling: a document listener (runtime boots at load, the chunk loads on the first page scroll).
+        <span hidden document:onScroll={(event) => viewportInteract(state, event, callbacks)}></span>) : null}
+    </div>);
+}
+/** Row context accessors for absolute row `i` of the rendered range. */
+function rowContext(state, i) {
+    const index = () => state.range().start + i();
+    const count = () => state.items().length;
+    return {
+        index,
+        count,
+        first: () => index() === 0,
+        last: () => index() === count() - 1,
+        even: () => index() % 2 === 0,
+        odd: () => index() % 2 !== 0,
+    };
+}
+/**
+ * Renders the rendered range of `state.items` as keyed rows (reused across scrolls by identity). Place it
+ * under a native element (`<ul>`, `<tbody>`, `<div>`) so it gets its own update region; directly in the
+ * viewport, pass the row template as the viewport's child instead.
+ */
+export function CdkVirtualForOf(props) {
+    const { state, trackBy, children: render } = props;
+    return (<>
+      <template data-rv-vfor={state.id}></template>
+      <For each={() => state.items().slice(state.range().start, state.range().end)} by={(item, i) => (trackBy ? trackBy(i + untrack(state.range).start, item) : item)}>
+        {(item, i) => render(item, rowContext(state, i))}
+      </For>
+      <template data-rv-vfor-end=""></template>
+    </>);
+}
+/** An ancestor scroll container for viewports created with `scrollable: "element"` (Angular `cdkVirtualScrollingElement`). */
+export function CdkVirtualScrollableElement(props) {
+    const { states, onScroll } = props;
+    // 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, SCROLLABLE_OWNED);
+    const id = props.id, className = "cdk-virtual-scrollable" + (props.class ? " " + props.class : "");
+    return (<div {...dom} id={id} class={className} data-rv-virtual-scrollable="" onScroll={onScroll
+            ? (event) => {
+                states.forEach((state) => viewportInteract(state, event));
+                onScroll(event);
+            }
+            : (event) => states.forEach((state) => viewportInteract(state, event))}>
+      {props.children}
+    </div>);
+}

package/scrolling/virtual-scroll-strategy.d.ts

@@ -0,0 +1,41 @@
+import type { Stream } from "./emitter.js";
+/** A range of indices: `start` inclusive, `end` exclusive (Angular `ListRange`). */
+export interface ListRange {
+    start: number;
+    end: number;
+}
+/** The viewport API a strategy drives. */
+export interface VirtualScrollStrategyViewport {
+    getDataLength(): number;
+    getViewportSize(): number;
+    getRenderedRange(): ListRange;
+    setRenderedRange(range: ListRange): void;
+    setTotalContentSize(size: number): void;
+    setRenderedContentOffset(offset: number, to?: "to-start" | "to-end"): void;
+    getOffsetToRenderedContentStart(): number | null;
+    measureScrollOffset(from?: "top" | "left" | "right" | "bottom" | "start" | "end"): number;
+    measureRenderedContentSize(): number;
+    measureRangeSize(range: ListRange): number;
+    scrollToOffset(offset: number, behavior?: ScrollBehavior): void;
+}
+/** A strategy that dictates which items should be rendered in the viewport. */
+export interface VirtualScrollStrategy {
+    /** Emits when the index of the first element visible in the viewport changes. */
+    scrolledIndexChange: Stream<number>;
+    /** Attaches this scroll strategy to a viewport. */
+    attach(viewport: VirtualScrollStrategyViewport): void;
+    /** Detaches this scroll strategy from the currently attached viewport. */
+    detach(): void;
+    /** Called when the viewport is scrolled (debounced using requestAnimationFrame). */
+    onContentScrolled(): void;
+    /** Called when the length of the data changes. */
+    onDataLengthChanged(): void;
+    /** Called when the range of items rendered in the DOM has changed. */
+    onContentRendered(): void;
+    /** Called when the offset of the rendered items changed. */
+    onRenderedOffsetChanged(): void;
+    /** Scroll to the offset for the given index. */
+    scrollToIndex(index: number, behavior: ScrollBehavior): void;
+}
+/** Checks if the given ranges are equal. */
+export declare const rangesEqual: (r1: ListRange, r2: ListRange) => boolean;

package/scrolling/virtual-scroll-strategy.js

@@ -0,0 +1,2 @@
+/** Checks if the given ranges are equal. */
+export const rangesEqual = (r1, r2) => r1.start == r2.start && r1.end == r2.end;

package/scrolling/virtual-scroll-viewport.d.ts

@@ -0,0 +1,95 @@
+import { type Stream } from "./emitter.js";
+import { CdkVirtualScrollable, type ScrollEdge } from "./scrollable.js";
+import { type VirtualScrollCallbacks, type VirtualScrollState } from "./state.js";
+import { type ListRange, type VirtualScrollStrategy, type VirtualScrollStrategyViewport } from "./virtual-scroll-strategy.js";
+/** The engine of a virtual scroll viewport element (Angular `CdkVirtualScrollViewport` instance). */
+export declare class VirtualScrollViewport<T = unknown> extends CdkVirtualScrollable implements VirtualScrollStrategyViewport {
+    readonly state: VirtualScrollState<T>;
+    /** Updated by every viewport interaction (the engine may have been created by an API call first). */
+    callbacks: VirtualScrollCallbacks;
+    scrollable: CdkVirtualScrollable;
+    private _scrollStrategy;
+    private readonly _renderedRangeSubject;
+    /** Emits when the rendered range changes. */
+    readonly renderedRangeStream: Stream<ListRange>;
+    private readonly _renderedContentOffsetSubject;
+    /** Emits the offset from the start of the viewport to the start of the rendered data (px). */
+    readonly renderedContentOffset: Stream<number | null>;
+    private _totalContentSize;
+    private _renderedContentTransform;
+    private _renderedRange;
+    private _dataLength;
+    private _viewportSize;
+    private _renderedContentOffset;
+    private _renderedContentOffsetNeedsRewrite;
+    private _changeDetectionNeeded;
+    private _runAfterChangeDetection;
+    private _subscriptions;
+    private _disposeData;
+    private _isDestroyed;
+    private _attached;
+    /** Rivet: the strategy's latest scrolled index, and the last one `callbacks` got (see `deliverScrolledIndex`). */
+    private _scrolledIndex;
+    private _deliveredIndex;
+    constructor(state: VirtualScrollState<T>, element: HTMLElement, callbacks?: VirtualScrollCallbacks);
+    get orientation(): "horizontal" | "vertical";
+    get appendOnly(): boolean;
+    /** The strategy (Angular: the `itemSize` / `autosize` directive's `_scrollStrategy`). */
+    get scrollStrategy(): VirtualScrollStrategy;
+    /**
+     * Rivet: hand `onScrolledIndexChange` the latest scrolled index it has not seen. Angular binds the output with the
+     * component; here the callbacks arrive with the first viewport event, and an API call (`scrollToIndex` from a
+     * button) may create the engine before that: its scroll's index would otherwise be lost (scrolledIndexChange is
+     * distinct, so it never fires again for that index).
+     */
+    deliverScrolledIndex(): void;
+    /** Emits when the index of the first element visible in the viewport changes. */
+    get scrolledIndexChange(): Stream<number>;
+    /** Measure, attach the strategy, follow scroll and data changes (Angular ngOnInit + attach(forOf)). */
+    init(): this;
+    destroy(): void;
+    getDataLength(): number;
+    getViewportSize(): number;
+    getRenderedRange(): ListRange;
+    measureBoundingClientRectWithScrollOffset(from: "left" | "top" | "right" | "bottom"): number;
+    /** Sets the total size of all content (px), including content that is not rendered. */
+    setTotalContentSize(size: number): void;
+    /** Sets the currently rendered range of indices. */
+    setRenderedRange(range: ListRange): void;
+    /** Offset from the start of the viewport to the start of the rendered data (px). */
+    getOffsetToRenderedContentStart(): number | null;
+    /** Sets the offset from the start of the viewport to the start or end of the rendered data (px). */
+    setRenderedContentOffset(offset: number, to?: "to-start" | "to-end"): void;
+    /** Scrolls to `offset` from the start (a fictional `scrollRight` in horizontal RTL). */
+    scrollToOffset(offset: number, behavior?: ScrollBehavior): void;
+    /** Scrolls to the offset of the given index. */
+    scrollToIndex(index: number, behavior?: ScrollBehavior): void;
+    /** Scroll offset from the start of the scrollable (default `top` / `start`), minus the viewport offset. */
+    measureScrollOffset(from?: ScrollEdge): number;
+    /** Offset of the viewport from the scrolling container. */
+    measureViewportOffset(from?: ScrollEdge): number;
+    /** The content wrapper element. */
+    get contentWrapper(): HTMLElement;
+    /** Measure the combined size of all rendered items. */
+    measureRenderedContentSize(): number;
+    /** Root nodes of rendered rows, grouped per row (CdkVirtualForOf views). */
+    private _rowNodes;
+    /** Combined size of the given (rendered) range. Throws if part of it is not rendered. */
+    measureRangeSize(range: ListRange): number;
+    /** Update the viewport dimensions and re-render. */
+    checkViewportSize(): void;
+    private _measureViewportSize;
+    /** Queue up a render pass (Angular change detection). */
+    private _markChangeDetectionNeeded;
+    /** Apply the transform, then run the after-render callbacks. */
+    private _doChangeDetection;
+}
+/**
+ * The engine for `state` (created and attached on first call, in the browser). `element` defaults to
+ * the viewport element (`id = state.id`).
+ */
+export declare function virtualScrollViewport<T>(state: VirtualScrollState<T>, element?: HTMLElement | null, callbacks?: VirtualScrollCallbacks): VirtualScrollViewport<T> | undefined;
+/** Scroll `state`'s viewport to `index` (Angular `viewport.scrollToIndex`). */
+export declare function scrollToIndex<T>(state: VirtualScrollState<T>, index: number, behavior?: ScrollBehavior): void;
+/** Scroll `state`'s viewport to `offset` px from the start (Angular `viewport.scrollToOffset`). */
+export declare function scrollToOffset<T>(state: VirtualScrollState<T>, offset: number, behavior?: ScrollBehavior): void;