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

package/utils/types.d.ts

@@ -0,0 +1,111 @@
+import type { Content } from "@rivetjs/runtime/jsx-runtime";
+import type { RivetKeyboardEvent } from "../interactions/keyboard.jsx";
+import type { ValidationResult } from "../state/form-validation.js";
+export type { PressEvent, PressEvents, PointerType } from "../interactions/press.jsx";
+export type { HoverEvent, HoverEvents } from "../interactions/hover.jsx";
+export type { RivetKeyboardEvent as KeyboardEvent } from "../interactions/keyboard.jsx";
+export type { Key, Selection, SelectionMode, SelectionBehavior, FocusStrategy, DisabledBehavior, Orientation, Direction, LoadingState, SortDescriptor, SortDirection, } from "../collections/types.js";
+export type { Href, RouterOptions, LinkDOMProps } from "./links.jsx";
+export type { ValidationResult, ValidationErrors, ValidationFunction, ValidationBehavior } from "../state/form-validation.js";
+export type { GlobalDOMAttributes, GlobalDOMEvents } from "./dom-props.js";
+export interface KeyboardEvents {
+    /** Handler that is called when a key is pressed. */
+    onKeyDown?: (e: RivetKeyboardEvent) => void;
+    /** Handler that is called when a key is released. */
+    onKeyUp?: (e: RivetKeyboardEvent) => void;
+}
+export interface FocusEvents<Target extends Element = Element> {
+    /** Handler that is called when the element receives focus. */
+    onFocus?: (e: FocusEvent & {
+        currentTarget: Target;
+    }) => void;
+    /** Handler that is called when the element loses focus. */
+    onBlur?: (e: FocusEvent & {
+        currentTarget: Target;
+    }) => void;
+    /** Handler that is called when the element's focus status changes. */
+    onFocusChange?: (isFocused: boolean) => void;
+}
+export interface FocusableProps<Target extends Element = Element> extends FocusEvents<Target>, KeyboardEvents {
+    /** Whether the element should receive focus on render. */
+    autoFocus?: boolean;
+}
+export interface AriaLabelingProps {
+    /** Defines a string value that labels the current element. */
+    "aria-label"?: string;
+    /** Identifies the element (or elements) that labels the current element. */
+    "aria-labelledby"?: string;
+    /** Identifies the element (or elements) that describes the object. */
+    "aria-describedby"?: string;
+    /** Identifies the element (or elements) that provide a detailed, extended description for the object. */
+    "aria-details"?: string;
+}
+export interface AriaValidationProps {
+    /** Identifies the element that provides an error message for the object. */
+    "aria-errormessage"?: string;
+}
+/** Common DOM props allowed on any component. */
+export interface DOMProps {
+    /** The element's unique identifier. */
+    id?: string;
+}
+export interface FocusableDOMProps extends DOMProps {
+    /** Whether to exclude the element from the sequential tab order. */
+    excludeFromTabOrder?: boolean;
+}
+/** Inline style object (`style` prop of every component; render-prop form in `StyleRenderProps`). */
+export type StyleObject = Record<string, string | number | undefined>;
+export type ValidationState = "valid" | "invalid";
+export type ValidationError = string | string[];
+export interface Validation<T = unknown> {
+    /** Whether user input is required on the input before form submission. */
+    isRequired?: boolean;
+    /** Whether the input value is invalid. */
+    isInvalid?: boolean;
+    /** @deprecated upstream: use `isInvalid`. */
+    validationState?: ValidationState;
+    /** `native` blocks form submission and shows native errors; `aria` only marks the field invalid. @default "native" (RAC) */
+    validationBehavior?: "aria" | "native";
+    /** Custom validation: error message(s), or `true` / `null` / `undefined` when valid. */
+    validate?: (value: T) => ValidationError | true | null | undefined;
+}
+export interface InputBase {
+    /** Whether the input is disabled. */
+    isDisabled?: boolean;
+    /** Whether the input can be selected but not changed by the user. */
+    isReadOnly?: boolean;
+}
+/**
+ * Value props. Rivet: `value` is a plain value OR a two-way `Signal` (see `controllable`).
+ */
+export interface ValueBase<T, C = T> {
+    /** The current value (controlled): a plain value or a Signal. */
+    value?: T | import("@rivetjs/reactivity").Signal<T>;
+    /** The default value (uncontrolled). */
+    defaultValue?: T;
+    /** Handler that is called when the value changes. */
+    onChange?: (value: C) => void;
+}
+export interface TextInputBase {
+    /** Temporary text that occupies the text input when it is empty. */
+    placeholder?: string;
+}
+export interface RangeValue<T> {
+    start: T;
+    end: T;
+}
+export interface RangeInputBase<T> {
+    minValue?: T;
+    maxValue?: T;
+    step?: T;
+}
+export interface HelpTextProps {
+    /** A description for the field. */
+    description?: Content;
+    /** An error message for the field. */
+    errorMessage?: Content | ((v: ValidationResult) => Content);
+}
+export interface LabelableProps {
+    /** The content to display as the label. */
+    label?: Content;
+}

package/utils/types.js

@@ -0,0 +1 @@
+export {};

package/virtualizer/behaviour.d.ts

@@ -0,0 +1,129 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { StyleObject } from "@rivetjs/runtime/style";
+import type { Key } from "../collections/index.js";
+import { type Collection, type CollectionOptions, type Node } from "./collection.js";
+import { type ScrollView } from "./dom.js";
+import { Layout } from "./layout.js";
+import type { LayoutInfo } from "./layout-info.js";
+import type { ReusableView } from "./reusable-view.js";
+import { type VirtualizerState } from "./state.js";
+import type { Direction } from "./types.js";
+/** Key of the loader sentinel node the component appends when `isLoading` / `onLoadMore` are given. */
+export declare const LOADER_KEY = "rv-virtualizer-loader";
+/** One rendered view: JSON-serializable (server window) projection of a ReusableView + its LayoutInfo. */
+export interface VirtualView<T = unknown> {
+    /** Collection key (rows are keyed by it: kept keys keep their DOM). */
+    key: Key;
+    /** View type (`item`, `section`, `header`, `loader`, `row`, `cell`, …). */
+    type: string;
+    /** The data item (node value), or null (loaders, layout-generated views). */
+    item: T | null;
+    /** Index of the node within its parent. */
+    index: number;
+    level: number;
+    parentKey: Key | null;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Size not measured yet (the browser measures it after rendering). */
+    estimated: boolean;
+    /** Position style relative to the parent view. */
+    style: StyleObject;
+    /** Child views (sections: header + items; tables: rows / cells). */
+    children: VirtualView<T>[];
+}
+export type MaybeAccessor<T> = T | (() => T);
+/** A layout class (`ListLayout`, `TableLayout`, …) or a factory (`() => new ListLayout()`): resumable, never an instance. */
+export type LayoutInput<O> = (new () => Layout<Node<any>, O>) | (() => Layout<Node<any>, O>);
+/** A layout instance from a class or a factory (RAC `Virtualizer` takes a class or an instance). */
+export declare function createLayout<O>(layout: LayoutInput<O>): Layout<Node<any>, O>;
+/** Serializable component state. */
+export interface VirtualizerModel<T, O> {
+    id: string;
+    /** Standalone `<Virtualizer items>`: the data (collection mode: unused, `source` holds the host's collection). */
+    items: MaybeAccessor<readonly T[]>;
+    /**
+     * Collection mode (a collection component inside `<Virtualizer layout>`, RAC CollectionRenderer): the host's built
+     * collection (an accessor: a rebuilt collection re-renders the window).
+     */
+    source?: (() => Collection<Node<T>> | null | undefined) | undefined;
+    /** Collection mode: the host's focused key (persisted, RAC `usePersistedKeys`). */
+    focus?: (() => Key | null) | undefined;
+    /** Collection mode: the host's scroll container (a ref accessor; standalone: the element with `id`). */
+    scrollRef?: (() => Element | null | undefined) | undefined;
+    /** Layout factory (`() => new ListLayout()`) or class (`ListLayout`), instantiated on the server and once in the browser. */
+    layout: LayoutInput<O>;
+    layoutOptions?: O;
+    collection: CollectionOptions<T>;
+    initialSize: {
+        width: number;
+        height: number;
+    };
+    dir?: Direction;
+    isLoading?: MaybeAccessor<boolean>;
+    onLoadMore?: () => void;
+    loadMoreOffset: number;
+    shouldObserveItemSize: boolean;
+    /** Caller-persisted keys (plus the focused view). */
+    persistedKeys: readonly Key[];
+    focusedKey: Signal<Key | null>;
+    views: Signal<VirtualView<T>[]>;
+    contentSize: Signal<{
+        width: number;
+        height: number;
+    }>;
+    isScrolling: Signal<boolean>;
+    onScroll?: (event: Event) => void;
+}
+/** Views of the engine as JSON; unchanged views keep their previous object (resumed rows stay adopted). */
+export declare function projectViews<T>(views: Iterable<ReusableView<Node<T>, unknown>>, dir: Direction | undefined, previous: Map<Key, VirtualView<T>>, parent?: LayoutInfo | null): VirtualView<T>[];
+/** First window for the server render (and client-rendered mounts): the engine at `initialSize`, scrolled to 0. */
+export declare function initialWindow<T, O>(model: VirtualizerModel<T, O>): {
+    views: VirtualView<T>[];
+    contentSize: {
+        width: number;
+        height: number;
+    };
+};
+interface Driver {
+    state: VirtualizerState<Node<unknown>, unknown>;
+    scrollView: ScrollView;
+    loadingMore: boolean;
+    lastItems: unknown;
+}
+/** The browser driver of `model` (created on first use: engine, scroll view, measurement). */
+export declare function driverOf<T, O>(model: VirtualizerModel<T, O>, element?: Element | null): Driver | null;
+/** Rows of the model: the server window, or (browser) the driver's projection; reads `items` for reactivity. */
+export declare function visibleViews<T, O>(model: VirtualizerModel<T, O>): VirtualView<T>[];
+/** Keys of `views`: the rows' `For` items. Keys keep their identity across windows, so resumed server rows are
+ * adopted and kept (a `For` re-creates an adopted row whose item changed; view descriptors change on every move). */
+export declare const viewKeys: <T>(views: readonly VirtualView<T>[]) => Key[];
+/** Keys in layout order (top to bottom, then start to end); the engine's reusable views come in recycling order. */
+export declare const orderedViewKeys: <T>(views: readonly VirtualView<T>[]) => Key[];
+/** `rowOrder` parent of the root views. */
+export declare const ROOT_VIEW: {};
+/**
+ * The keyed rows' order: layout order (top to bottom) — except while DOM focus is inside the collection, when kept
+ * keys keep their DOM order and new ones go last. A keyed list moves (detaches) a kept row to reorder it, and a
+ * detached focused option / cell loses focus (keyboard navigation across the window edge inserts rows before the
+ * focused one). Positions are absolute: DOM order is not visual order; options carry `aria-posinset`, rows
+ * `aria-rowindex` (RAC renders in the engine's recycling order).
+ */
+export declare function rowOrder(model: VirtualizerModel<unknown, unknown>, parent: unknown, views: readonly VirtualView<unknown>[]): Key[];
+/** The view with `key` in `views` (a row's descriptor); a row being removed keeps its last descriptor. */
+export declare function viewOf<T, O>(model: VirtualizerModel<T, O>, views: readonly VirtualView<T>[], key: Key): VirtualView<T>;
+/**
+ * Collection mode: the child views of the view with key `parentKey` (a host part's `CollectionBranch`: section items,
+ * table header rows / columns, body rows, cells), from the whole projected tree; `[]` when it is not rendered.
+ */
+export declare function childViews<T, O>(model: VirtualizerModel<T, O>, parentKey: Key): VirtualView<T>[];
+/** Scroll handler of the scroller: drive the engine, load more near the end, then the caller's `onScroll`. */
+export declare function virtualizerScroll<T, O>(model: VirtualizerModel<T, O>, event: Event): void;
+/** focusin: the focused view stays rendered (persisted) while scrolled out of view. */
+export declare function virtualizerFocusIn<T, O>(model: VirtualizerModel<T, O>, event: FocusEvent): void;
+/** Style of the content element (size of the scrollable content; no pointer events while scrolling). */
+export declare function contentStyle<T, O>(model: VirtualizerModel<T, O>): StyleObject;
+/** Style of the scroller: overflow per scroll direction, padding reset (padding is done by the layout). */
+export declare function scrollerStyle(scrollDirection: "horizontal" | "vertical" | "both"): StyleObject;
+export {};

package/virtualizer/behaviour.js

@@ -0,0 +1,437 @@
+// Virtualizer component behaviour: serializable model, server first window, and the browser driver that
+// runs the engine (createVirtualizerState + createScrollView) once the visitor scrolls. Semantics follow
+// react-aria/src/virtualizer/Virtualizer.tsx and react-aria-components/src/Virtualizer.tsx (React Spectrum,
+// Apache-2.0, © Adobe): layout + layoutOptions, persisted keys, item measurement, load more.
+// Resume: the model is plain signals + JSON + resumable functions; engine instances live only in the browser
+// (one driver per scroller element, in a lazily created WeakMap).
+import { computed, createRoot, effect, runWithOwner, untrack } from "@rivetjs/reactivity";
+import { direction as directionOf } from "../bidi/index.js";
+import { createCollection, loaderNode } from "./collection.js";
+import { createScrollView, getScrollLeft, layoutInfoToStyle, measureItem, setScrollLeft } from "./dom.js";
+import { Layout } from "./layout.js";
+import { Rect } from "./rect.js";
+import { Size } from "./size.js";
+import { createVirtualizerState } from "./state.js";
+import { Virtualizer } from "./virtualizer-core.js";
+/** Key of the loader sentinel node the component appends when `isLoading` / `onLoadMore` are given. */
+export const LOADER_KEY = "rv-virtualizer-loader";
+/** A layout instance from a class or a factory (RAC `Virtualizer` takes a class or an instance). */
+export function createLayout(layout) {
+    const fn = layout;
+    return fn.prototype instanceof Layout ? new layout() : layout();
+}
+const read = (value) => (typeof value === "function" ? value() : value);
+function collectionOf(model) {
+    if (model.source)
+        return (model.source() ?? createCollection([], {}));
+    const loading = model.isLoading === undefined && !model.onLoadMore ? null : !!read(model.isLoading ?? false);
+    return createCollection(read(model.items), model.collection, loading === null ? [] : [loaderNode(LOADER_KEY, loading)]);
+}
+const persistedOf = (model) => {
+    const keys = new Set(model.persistedKeys);
+    const focused = model.focusedKey();
+    if (focused != null)
+        keys.add(focused);
+    const hostFocused = model.focus?.();
+    if (hostFocused != null)
+        keys.add(hostFocused);
+    // Collection mode: the view holding DOM focus stays until focus moves on — the focused key changes before its
+    // item renders (and before the engine sees the scroll that brings it in), and removing the focused element
+    // would blur the collection (fast keyboard navigation across the window edge).
+    if (model.focus) {
+        const active = activeViewKey(model);
+        if (active != null)
+            keys.add(active);
+    }
+    return keys;
+};
+function activeViewKey(model) {
+    if (typeof document === "undefined")
+        return null;
+    const scroller = scrollerOf(model);
+    const active = document.activeElement;
+    const view = active && scroller?.contains(active) ? active.closest("[data-rv-view]") : null;
+    return view && scroller.contains(view) ? keyOfView(untrack(model.views), view.dataset.rvView) : null;
+}
+/** The view key whose `String(key)` is `text` (keys render as `data-rv-view` text), at any depth. */
+function keyOfView(views, text) {
+    for (const view of views) {
+        if (String(view.key) === text)
+            return view.key;
+        const nested = view.children.length ? keyOfView(view.children, text) : null;
+        if (nested != null)
+            return nested;
+    }
+    return null;
+}
+const sameStyle = (a, b) => {
+    const ka = Object.keys(a).filter((k) => a[k] != null), kb = Object.keys(b).filter((k) => b[k] != null);
+    return ka.length === kb.length && ka.every((k) => a[k] === b[k]);
+};
+/** Views of the engine as JSON; unchanged views keep their previous object (resumed rows stay adopted). */
+export function projectViews(views, dir, previous, parent = null) {
+    const out = [];
+    for (const view of views) {
+        const li = view.layoutInfo;
+        if (!li)
+            continue;
+        const node = view.content;
+        const children = projectViews(view.children, dir, previous, li);
+        const next = {
+            key: li.key,
+            type: li.type,
+            item: (node?.value ?? null),
+            index: node?.index ?? 0,
+            level: node?.level ?? 0,
+            parentKey: li.parentKey,
+            x: li.rect.x,
+            y: li.rect.y,
+            width: li.rect.width,
+            height: li.rect.height,
+            estimated: li.estimatedSize,
+            style: layoutInfoToStyle(li, dir, parent),
+            children,
+        };
+        const old = previous.get(li.key);
+        const same = old &&
+            old.type === next.type &&
+            old.item === next.item &&
+            old.index === next.index &&
+            old.level === next.level &&
+            old.parentKey === next.parentKey &&
+            old.x === next.x &&
+            old.y === next.y &&
+            old.width === next.width &&
+            old.height === next.height &&
+            old.estimated === next.estimated &&
+            sameStyle(old.style, next.style) &&
+            old.children.length === children.length &&
+            old.children.every((c, i) => c === children[i]);
+        out.push(same ? old : next);
+    }
+    return out;
+}
+const flatten = (views, into = new Map()) => {
+    for (const view of views) {
+        into.set(view.key, view);
+        flatten(view.children, into);
+    }
+    return into;
+};
+const sizeOfContent = (size) => ({ width: size.width, height: size.height });
+/** First window for the server render (and client-rendered mounts): the engine at `initialSize`, scrolled to 0. */
+export function initialWindow(model) {
+    return untrack(() => {
+        const collection = collectionOf(model);
+        const layout = createLayout(model.layout);
+        const virtualizer = new Virtualizer({
+            collection,
+            layout,
+            delegate: { setVisibleRect() { }, renderView: (_type, content) => content, invalidate() { } },
+        });
+        const { width, height } = model.initialSize;
+        const views = virtualizer.render({
+            layout,
+            collection,
+            persistedKeys: persistedOf(model),
+            visibleRect: new Rect(0, 0, width, height),
+            size: new Size(width, height),
+            invalidationContext: model.layoutOptions != null ? { layoutOptions: model.layoutOptions } : {},
+            isScrolling: false,
+            layoutOptions: model.layoutOptions,
+        });
+        return { views: projectViews(views, model.dir, new Map()), contentSize: sizeOfContent(virtualizer.contentSize) };
+    });
+}
+let drivers;
+/** The scroll container of `model`: the host's `scrollRef` (collection mode), else the element with `model.id`. */
+function scrollerOf(model) {
+    if (typeof document === "undefined")
+        return null;
+    return (model.scrollRef ? model.scrollRef() : document.getElementById(model.id)) ?? null;
+}
+const viewElement = (root, key) => {
+    for (const el of root.querySelectorAll("[data-rv-view]"))
+        if (el.dataset.rvView === String(key))
+            return el;
+    return null;
+};
+/** The browser driver of `model` (created on first use: engine, scroll view, measurement). */
+export function driverOf(model, element) {
+    const el = (element ?? scrollerOf(model));
+    // Not in the document yet (a client render's first pass): no size to start from.
+    if (!el || !el.isConnected)
+        return null;
+    drivers ??= new WeakMap();
+    const existing = drivers.get(el);
+    if (existing)
+        return existing;
+    // Detached from the caller's owner: `createRoot` attaches to the current owner, and the first caller may be the
+    // rows' `For` binding (`visibleViews` on a resumed page's first projection), which disposes its children on its
+    // next run — the cached driver then kept dead effects and an items change no longer reached the engine
+    // (cdk-docs `virtualizer-items`, cold scroll then filter, 2026-10-19). The driver lives with its element.
+    return runWithOwner(null, () => createDriver(model, el));
+}
+function createDriver(model, el) {
+    const dir = () => model.dir ?? directionOf(el);
+    const collection = computed(() => collectionOf(model));
+    const layout = untrack(() => createLayout(model.layout));
+    let state;
+    const scrollView = createScrollView(el, {
+        contentSize: () => untrack(() => state?.contentSize() ?? new Size(model.contentSize().width, model.contentSize().height)),
+        onVisibleRectChange: (rect) => state?.setVisibleRect(rect),
+        onScrollStart: () => {
+            state?.startScrolling();
+            model.isScrolling.set(true);
+        },
+        onScrollEnd: () => {
+            state?.endScrolling();
+            model.isScrolling.set(false);
+        },
+        direction: dir,
+    });
+    state = createVirtualizerState({
+        layout,
+        collection,
+        renderView: (_type, content) => content,
+        onVisibleRectChange(rect) {
+            setScrollLeft(el, dir(), rect.x);
+            el.scrollTop = rect.y;
+        },
+        persistedKeys: () => persistedOf(model),
+        layoutOptions: model.layoutOptions,
+        initialVisibleRect: new Rect(getScrollLeft(el, dir()), el.scrollTop, el.clientWidth, el.clientHeight),
+    });
+    const driver = { state, scrollView, loadingMore: false, lastItems: undefined };
+    drivers.set(el, driver);
+    scrollView.updateSize();
+    // Project engine views into the model (the rows' For), then measure estimated views once rendered.
+    let observer = null;
+    const observed = new WeakSet();
+    const measureQueue = new Set();
+    let scheduled = false;
+    const measure = () => {
+        scheduled = false;
+        for (const key of measureQueue) {
+            const element = viewElement(el, key);
+            if (element)
+                measureItem(state.virtualizer, key, element);
+        }
+        measureQueue.clear();
+    };
+    const schedule = (key) => {
+        measureQueue.add(key);
+        if (!scheduled) {
+            scheduled = true;
+            queueMicrotask(measure);
+        }
+    };
+    if (model.shouldObserveItemSize && typeof ResizeObserver !== "undefined") {
+        observer = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                const key = entry.target.parentElement?.closest("[data-rv-view]")?.dataset.rvView;
+                const view = key == null ? undefined : [...flatten(untrack(model.views)).values()].find((v) => String(v.key) === key);
+                if (view)
+                    schedule(view.key);
+            }
+        });
+    }
+    computedEffect(() => {
+        const views = state.visibleViews();
+        const contentSize = state.contentSize();
+        untrack(() => {
+            const previous = flatten(model.views());
+            // Rows leaving the window read their last descriptor (viewOf); on a resumed page no row accessor ran
+            // before this first projection, so the replaced (server) views seed that cache.
+            remember(model, previous);
+            const next = projectViews(views, model.dir, previous);
+            model.views.set(next);
+            const size = model.contentSize();
+            if (size.width !== contentSize.width || size.height !== contentSize.height)
+                model.contentSize.set(sizeOfContent(contentSize));
+            const visit = (list) => {
+                for (const view of list) {
+                    if (view.estimated)
+                        schedule(view.key);
+                    visit(view.children);
+                }
+            };
+            visit(next);
+            if (observer)
+                queueMicrotask(() => {
+                    for (const element of el.querySelectorAll("[data-rv-view]"))
+                        for (const child of element.children)
+                            if (!observed.has(child))
+                                (observed.add(child), observer.observe(child));
+                });
+        });
+    });
+    return driver;
+}
+// The driver's projection effect: its own root (created under the detached driver, so it outlives region re-creation).
+function computedEffect(fn) {
+    createRoot(() => effect(fn));
+}
+/** Rows of the model: the server window, or (browser) the driver's projection; reads `items` for reactivity. */
+export function visibleViews(model) {
+    if (model.source) {
+        // Collection mode: a rebuilt collection or a focus move (persisted key) starts the driver on a resumed page.
+        model.source();
+        model.focus?.();
+    }
+    else if (typeof model.items === "function")
+        model.items();
+    if (typeof model.isLoading === "function")
+        model.isLoading();
+    if (typeof document !== "undefined")
+        untrack(() => driverOf(model) ?? (model.source && startWhenMounted(model)));
+    return model.views();
+}
+let mounting;
+/**
+ * Collection mode, client render: the host element exists but is not in the document during its first pass. Start
+ * the engine once it is (RAC measures the scroll view on mount); the server window stays until then.
+ */
+function startWhenMounted(model) {
+    if ((mounting ??= new WeakSet()).has(model) || !scrollerOf(model))
+        return null;
+    mounting.add(model);
+    queueMicrotask(() => {
+        mounting.delete(model);
+        untrack(() => driverOf(model));
+    });
+    return null;
+}
+/** Keys of `views`: the rows' `For` items. Keys keep their identity across windows, so resumed server rows are
+ * adopted and kept (a `For` re-creates an adopted row whose item changed; view descriptors change on every move). */
+export const viewKeys = (views) => views.map((view) => view.key);
+const byLayoutOrder = (a, b) => a.y - b.y || a.x - b.x;
+/** Keys in layout order (top to bottom, then start to end); the engine's reusable views come in recycling order. */
+export const orderedViewKeys = (views) => views
+    .slice()
+    .sort(byLayoutOrder)
+    .map((view) => view.key);
+/** `rowOrder` parent of the root views. */
+export const ROOT_VIEW = {};
+let orders;
+/**
+ * The keyed rows' order: layout order (top to bottom) — except while DOM focus is inside the collection, when kept
+ * keys keep their DOM order and new ones go last. A keyed list moves (detaches) a kept row to reorder it, and a
+ * detached focused option / cell loses focus (keyboard navigation across the window edge inserts rows before the
+ * focused one). Positions are absolute: DOM order is not visual order; options carry `aria-posinset`, rows
+ * `aria-rowindex` (RAC renders in the engine's recycling order).
+ */
+export function rowOrder(model, parent, views) {
+    const next = orderedViewKeys(views);
+    if (typeof document === "undefined")
+        return next;
+    const byParent = (orders ??= new WeakMap()).get(model) ?? new Map();
+    orders.set(model, byParent);
+    const prev = byParent.get(parent);
+    const scroller = model.scrollRef?.();
+    if (prev && scroller?.contains(document.activeElement)) {
+        const present = new Set(next);
+        const kept = prev.filter((key) => present.has(key));
+        const known = new Set(kept);
+        for (const key of next)
+            if (!known.has(key))
+                kept.push(key);
+        byParent.set(parent, kept);
+        return kept;
+    }
+    byParent.set(parent, next);
+    return next;
+}
+let indexes;
+let last;
+const seenOf = (model) => {
+    let seen = (last ??= new WeakMap()).get(model);
+    if (!seen)
+        last.set(model, (seen = new Map()));
+    return seen;
+};
+// The views a projection replaces: rows removed by it still find their descriptor.
+function remember(model, views) {
+    const seen = seenOf(model);
+    for (const [key, view] of views)
+        seen.set(key, view);
+}
+/** The view with `key` in `views` (a row's descriptor); a row being removed keeps its last descriptor. */
+export function viewOf(model, views, key) {
+    let index = (indexes ??= new WeakMap()).get(views);
+    if (!index)
+        indexes.set(views, (index = new Map(views.map((view) => [view.key, view]))));
+    const seen = seenOf(model);
+    const view = index.get(key);
+    if (!view)
+        return seen.get(key);
+    seen.set(key, view);
+    return view;
+}
+let trees;
+/**
+ * Collection mode: the child views of the view with key `parentKey` (a host part's `CollectionBranch`: section items,
+ * table header rows / columns, body rows, cells), from the whole projected tree; `[]` when it is not rendered.
+ */
+export function childViews(model, parentKey) {
+    const views = model.views();
+    let tree = (trees ??= new WeakMap()).get(views);
+    if (!tree)
+        trees.set(views, (tree = flatten(views)));
+    return (tree.get(parentKey)?.children ?? EMPTY);
+}
+const EMPTY = [];
+/** Scroll handler of the scroller: drive the engine, load more near the end, then the caller's `onScroll`. */
+export function virtualizerScroll(model, event) {
+    const el = event.currentTarget;
+    const driver = driverOf(model, el);
+    if (!driver)
+        return;
+    driver.scrollView.onScroll(event);
+    loadMore(model, driver, el);
+    model.onScroll?.(event);
+}
+function loadMore(model, driver, el) {
+    if (!model.onLoadMore)
+        return;
+    const items = untrack(() => read(model.items));
+    const loading = untrack(() => !!read(model.isLoading ?? false));
+    // A finished load (new items or loading flag reset) re-arms the trigger.
+    if (items !== driver.lastItems || loading)
+        driver.loadingMore = loading;
+    driver.lastItems = items;
+    if (driver.loadingMore)
+        return;
+    if (el.scrollHeight - el.scrollTop - el.clientHeight < el.clientHeight * model.loadMoreOffset) {
+        driver.loadingMore = true;
+        model.onLoadMore();
+    }
+}
+/** focusin: the focused view stays rendered (persisted) while scrolled out of view. */
+export function virtualizerFocusIn(model, event) {
+    const key = event.target?.closest?.("[data-rv-view]")?.dataset.rvView;
+    if (key == null)
+        return;
+    const view = [...flatten(untrack(model.views)).values()].find((v) => String(v.key) === key);
+    if (view && untrack(model.focusedKey) !== view.key)
+        model.focusedKey.set(view.key);
+    driverOf(model, event.currentTarget);
+}
+/** Style of the content element (size of the scrollable content; no pointer events while scrolling). */
+export function contentStyle(model) {
+    const { width, height } = model.contentSize();
+    return {
+        position: "relative",
+        width: Number.isFinite(width) && width > 0 ? width + "px" : undefined,
+        height: Number.isFinite(height) ? height + "px" : undefined,
+        "pointer-events": model.isScrolling() ? "none" : undefined,
+    };
+}
+/** Style of the scroller: overflow per scroll direction, padding reset (padding is done by the layout). */
+export function scrollerStyle(scrollDirection) {
+    return scrollDirection === "horizontal"
+        ? { padding: "0", "overflow-x": "auto", "overflow-y": "hidden" }
+        : scrollDirection === "vertical"
+            ? { padding: "0", "overflow-y": "auto", "overflow-x": "hidden" }
+            : { padding: "0", overflow: "auto" };
+}