@rivetjs/cdk 0.1.0-alpha.0 → 0.1.0-alpha.1

package/tree/index.jsx

@@ -15,6 +15,8 @@
 //   `data-hovered` / `data-focused` / `data-focus-visible` written by the handlers, `data-*` values `"true"`.
 // - `expandedKeys` / `selectedKeys`: a plain value (controlled) or a Signal (two-way).
 // - `class` = RAC `className` (defaults `rv-Tree`, `rv-TreeItem`, `rv-TreeLoader`).
+// - Inside a `<CollectionVirtualizer layout={ListLayout}>` the flattened collection is the virtualizer's source: the
+//   treegrid element is the scroll container (scroll forwarded to the renderer), the focused row is persisted.
 // `render` (RAC DOMRenderProps) on Tree / TreeItem / TreeSection (`<div>`) and TreeHeader (via GridListHeader): given, the attributes object goes to `render(attrs, renderProps)`;
 //   the aria prop objects become one accessor per key (object-literal accessors over `gridAttr` / `row`: only literal arrows resume), the row content is the `children` accessor.
 // Deviations:
@@ -85,7 +87,7 @@ export const TreeContext = resumableContext(createContext(null, { id: "rv-tree"
 export const TreeStateContext = resumableContext(createContext(null, { id: "rv-tree-state" }));
 const TreeInternalContext = resumableContext(createContext(null, { id: "rv-tree-internal" }));
 /** Global DOM events Tree handles itself; the user's run from its own handler. */
-const TREE_OWNED = ["onMouseDown", "style"];
+const TREE_OWNED = ["onMouseDown", "onScroll", "style"];
 /**
  * A tree provides users with a way to navigate nested hierarchical information, with support for
  * keyboard navigation and selection.
@@ -158,6 +160,8 @@ export function Tree(inProps) {
         disallowTypeAhead: props.disallowTypeAhead,
         linkBehavior: props.linkBehavior,
         isVirtualized: renderer.isVirtualized,
+        // RAC: inside a Virtualizer the layout is the keyboard delegate's layout delegate (Page Up / Down).
+        layoutDelegate: renderer.layoutDelegate,
         UNSTABLE_focusOnEntry: props.UNSTABLE_focusOnEntry,
         direction: props.direction,
         locale: props.locale,
@@ -202,6 +206,15 @@ export function Tree(inProps) {
         state: values.state,
     };
     const onMouseDown = props.onMouseDown;
+    const onScroll = props.onScroll;
+    // Virtualized (RAC Virtualizer + ListLayout over the flattened rows): the treegrid element is the scroll container,
+    // its scroll events reach the renderer and its focused row stays rendered.
+    const virtualScroll = renderer.isVirtualized ? customRenderer?.onScroll : undefined;
+    const focusedKey = renderer.isVirtualized ? state.selectionState.focusedKey : undefined;
+    const scrolled = (e) => {
+        virtualScroll?.(e);
+        onScroll?.(e);
+    };
     const slot = props.slot || undefined;
     const dom = globalDOMProps(props, TREE_OWNED);
     const description = () => gridListHighlightDescription(gridOpts, view());
@@ -239,13 +252,18 @@ export function Tree(inProps) {
                 gridListMouseDown(e, gridOpts, view());
                 onMouseDown?.(e);
             },
+            onScroll: (e) => scrolled(e),
             children: () => [
                 <Provider values={[
                         [TreeStateContext, state],
                         [TreeInternalContext, { shared }],
                         [SharedElementContext, sharedElements],
                     ]}>
-          {(customRenderer ?? DefaultCollectionRenderer).CollectionRoot({ collection: flat, scrollRef: el })}
+          {(customRenderer ?? DefaultCollectionRenderer).CollectionRoot({
+                        collection: flat,
+                        scrollRef: el,
+                        focusedKey,
+                    })}
         </Provider>,
                 renderEmptyState ? (<Show when={() => flat().size === 0}>
             {() => (<div role="row" style={{ display: "contents" }} aria-level="1">
@@ -266,14 +284,18 @@ export function Tree(inProps) {
     return (<div {...dom} {...treeProps(gridOpts, view(), hasTabbableChild()).gridProps} ref={rootRef} class={rp.class()} style={rp.style()} slot={slot} data-empty={dataBool(flat().size === 0)} data-selection-mode={values.selectionMode() === "none" ? undefined : values.selectionMode()} onKeyDownCapture={(e) => gridListKeyDownCapture(e, gridOpts, view())} onKeyDown={(e) => gridListKeyDown(e, gridOpts, view())} onFocusIn={(e) => gridListFocus(e, gridOpts, view())} onFocusOut={(e) => gridListBlur(e, gridOpts, view())} onFocus={(e) => focusStateFocus(rootInteraction, e)} onBlur={(e) => focusStateBlur(rootInteraction, e)} onMouseDown={(e) => {
             gridListMouseDown(e, gridOpts, view());
             onMouseDown?.(e);
-        }}>
+        }} onScroll={virtualScroll || onScroll ? scrolled : undefined}>
       <Provider values={[
             [TreeStateContext, state],
             [TreeInternalContext, { shared }],
             // RAC: the rows share one SharedElementTransition scope (a SelectionIndicator animates between them).
             [SharedElementContext, sharedElements],
         ]}>
-        {(customRenderer ?? DefaultCollectionRenderer).CollectionRoot({ collection: flat, scrollRef: el })}
+        {(customRenderer ?? DefaultCollectionRenderer).CollectionRoot({
+            collection: flat,
+            scrollRef: el,
+            focusedKey,
+        })}
       </Provider>
       {renderEmptyState ? (<Show when={() => flat().size === 0}>
           {() => (<div role="row" style={{ display: "contents" }} aria-level="1">

package/utils/data-attrs.d.ts

@@ -61,11 +61,13 @@ export declare function interactionStateProps(o: InteractionStateOptions): Recor
  * - `attrs`: the context's DOM attributes (`aria-*`, `data-*`, `id`, `role`, `title`, …) the props leave
  *   `undefined`, for the element: spread `{...readAttrs(attrs)}` (accessor values allowed);
  * - a disabled element takes none (RA: `isDisabled ? {} : domProps`); the context `ref` is returned for
- *   `mergeRefValues`.
+ *   `mergeRefValues`. An accessor `isDisabled` (live / accessor prop) is never read here: the context handlers do
+ *   nothing and its attributes read `undefined` while it is true (read at event time / in the attribute binding) —
+ *   a render-time read would re-create the component's enclosing region on its first change on a resumed page.
  */
 export declare function mergeFocusableContext<P extends object>(props: P, ctx: {
     ref?: unknown;
     [key: string]: unknown;
-} | null | undefined, isDisabled?: boolean): [P, unknown, Record<string, unknown> | undefined];
+} | null | undefined, isDisabled?: boolean | (() => boolean | undefined)): [P, unknown, Record<string, unknown> | undefined];
 /** `attrs` with accessor values read (call inside the element's spread binding: `{...readAttrs(attrs)}`). */
 export declare function readAttrs(attrs: Record<string, unknown> | undefined): Record<string, unknown> | undefined;

package/utils/data-attrs.jsx

@@ -128,14 +128,17 @@ const FORWARDED_ATTR = /^(?:aria-|data-)|^(?:id|role|title|lang|dir)$/;
  * - `attrs`: the context's DOM attributes (`aria-*`, `data-*`, `id`, `role`, `title`, …) the props leave
  *   `undefined`, for the element: spread `{...readAttrs(attrs)}` (accessor values allowed);
  * - a disabled element takes none (RA: `isDisabled ? {} : domProps`); the context `ref` is returned for
- *   `mergeRefValues`.
+ *   `mergeRefValues`. An accessor `isDisabled` (live / accessor prop) is never read here: the context handlers do
+ *   nothing and its attributes read `undefined` while it is true (read at event time / in the attribute binding) —
+ *   a render-time read would re-create the component's enclosing region on its first change on a resumed page.
  */
 export function mergeFocusableContext(props, ctx, isDisabled) {
     if (!ctx)
         return [props, undefined, undefined];
-    const { ref, ...domProps } = ctx;
-    if (isDisabled)
+    const { ref, ...context } = ctx;
+    if (isDisabled === true)
         return [props, ref, undefined];
+    const domProps = typeof isDisabled === "function" ? gateContext(context, isDisabled) : context;
     if (hasLive(props))
         return liveFocusableMerge(props, ref, domProps);
     const out = { ...props };
@@ -153,6 +156,27 @@ export function mergeFocusableContext(props, ctx, isDisabled) {
     }
     return [out, ref, attrs];
 }
+// Accessor `isDisabled`: context handlers skip and context DOM attributes read `undefined` while it is true (RA
+// re-renders with `{}`). The wrappers are returned arrows (resumable symbols; captures: the context value, the accessor).
+function gateContext(context, isDisabled) {
+    const out = {};
+    for (const key in context) {
+        const value = context[key];
+        if (/^on[A-Z]/.test(key) && typeof value === "function")
+            out[key] = gatedHandler(value, isDisabled);
+        else if (FORWARDED_ATTR.test(key))
+            out[key] = gatedAttr(value, isDisabled);
+        else
+            out[key] = value;
+    }
+    return out;
+}
+function gatedHandler(handler, isDisabled) {
+    return (...args) => (isDisabled() ? undefined : handler(...args));
+}
+function gatedAttr(value, isDisabled) {
+    return () => (isDisabled() ? undefined : typeof value === "function" ? value() : value);
+}
 // Live props (P5): own getters stay unread — runtime `mergeProps(context, props, handlers)`: own defined values win
 // per read (context fills `undefined`), context handlers chain after the own ones at call time.
 function liveFocusableMerge(props, ref, domProps) {

package/utils/index.d.ts

@@ -1,7 +1,6 @@
 import { type Disposer } from "@rivetjs/reactivity";
 export { chain, mergeProps, mergeRefs, type RefLike } from "../interactions/merge-props.jsx";
-/** Focus `element` without scrolling it into view (`focus({ preventScroll: true })`, Baseline). */
-export declare function focusWithoutScrolling(element: HTMLElement | SVGElement): void;
+export { _resetTransitions, focusWithoutScrolling, runAfterTransition, trackTransitions } from "./transitions.js";
 /** Offset of an element edge in client coordinates: left/top, or right/bottom when `reverse`. */
 export declare function getOffset(element: Element, reverse?: boolean, orientation?: "horizontal" | "vertical"): number;
 /** Clamps `value` into [min, max]. */
@@ -12,19 +11,6 @@ export declare function roundToStepPrecision(value: number, step: number): numbe
 export declare function snapValueToStep(value: number, min: number | undefined, max: number | undefined, step: number): number;
 /** Rounds `value` to `digits` digits in `base`. */
 export declare function toFixedNumber(value: number, digits: number, base?: number): number;
-/**
- * Start tracking transitions in `doc` (react-aria does this at import; Rivet modules have no
- * import-time effects, so the first `runAfterTransition` call does it). Transitions already running
- * then are picked up from `document.getAnimations()`.
- */
-export declare function trackTransitions(doc?: Document): void;
-/** Test hook: stop tracking and forget running transitions and queued callbacks. */
-export declare function _resetTransitions(): void;
-/**
- * Run `fn` once every running CSS transition in the document finished (`fn(true)`), or on the next
- * frame when none runs (`fn(false)`; one frame lets a transition on mount start). Returns a cancel function.
- */
-export declare function runAfterTransition(fn: (isTransition: boolean) => void): () => void;
 export interface LabelingProps {
     id?: string;
     "aria-label"?: string;

package/utils/index.js

@@ -4,7 +4,8 @@
 // useFormReset, useUpdateEffect; react-stately utils/number (clamp, snapValueToStep, toFixedNumber).
 //
 // `chain` / `mergeProps` / `mergeRefs` live in `../interactions/merge-props.tsx` (a resume-compiled
-// module, so chained handlers stay resumable) and are re-exported here.
+// module, so chained handlers stay resumable), `focusWithoutScrolling` / `runAfterTransition` in `./transitions.ts`;
+// both are re-exported here.
 // Rivet mapping of the hooks (no hooks, no re-renders):
 // - `useLayoutEffect` / `useEffect` → `clientEffect(fn, { when })` from `@rivetjs/runtime/dom` in a
 //   component (never runs on the server, resumes at its trigger), or `effect` in browser-only code.
@@ -14,10 +15,9 @@
 import { effect, untrack } from "@rivetjs/reactivity";
 import { createId } from "@rivetjs/runtime/id";
 export { chain, mergeProps, mergeRefs } from "../interactions/merge-props.jsx";
-/** Focus `element` without scrolling it into view (`focus({ preventScroll: true })`, Baseline). */
-export function focusWithoutScrolling(element) {
-    element.focus({ preventScroll: true });
-}
+// Leaf module (DOCS-COLD 2026-10-20): `interactions/utils.ts` imports these from there, so focus / overlay helpers
+// never reach this barrel's `merge-props` re-export (chunk owner walks follow every static import).
+export { _resetTransitions, focusWithoutScrolling, runAfterTransition, trackTransitions } from "./transitions.js";
 /** Offset of an element edge in client coordinates: left/top, or right/bottom when `reverse`. */
 export function getOffset(element, reverse, orientation = "horizontal") {
     const rect = element.getBoundingClientRect();
@@ -69,103 +69,6 @@ export function toFixedNumber(value, digits, base = 10) {
     const pow = Math.pow(base, digits);
     return Math.round(value * pow) / pow;
 }
-// --- runAfterTransition ---------------------------------------------------------------------------
-// Elements currently transitioning → their transitioning CSS properties (a set, not a count: Chrome
-// sometimes fires both transitionend and transitioncancel).
-const transitionsByElement = new Map();
-const transitionCallbacks = new Set();
-let tracking = null;
-const isTransitionEvent = (event) => "propertyName" in event;
-const eventTarget = (event) => {
-    try {
-        return event.composedPath?.()[0] ?? event.target;
-    }
-    catch {
-        return event.target;
-    }
-};
-function onTransitionStart(event) {
-    const target = eventTarget(event);
-    if (!isTransitionEvent(event) || !target)
-        return;
-    let transitions = transitionsByElement.get(target);
-    if (!transitions) {
-        transitionsByElement.set(target, (transitions = new Set()));
-        // On the element itself: it must fire even when the node is removed mid-transition.
-        target.addEventListener("transitioncancel", onTransitionEnd, { once: true });
-    }
-    transitions.add(event.propertyName);
-}
-function onTransitionEnd(event) {
-    const target = eventTarget(event);
-    if (!isTransitionEvent(event) || !target)
-        return;
-    const properties = transitionsByElement.get(target);
-    if (!properties)
-        return;
-    properties.delete(event.propertyName);
-    if (properties.size === 0) {
-        target.removeEventListener("transitioncancel", onTransitionEnd);
-        transitionsByElement.delete(target);
-    }
-    if (transitionsByElement.size === 0) {
-        for (const callback of transitionCallbacks) {
-            callback(true);
-            transitionCallbacks.delete(callback);
-        }
-    }
-}
-/**
- * Start tracking transitions in `doc` (react-aria does this at import; Rivet modules have no
- * import-time effects, so the first `runAfterTransition` call does it). Transitions already running
- * then are picked up from `document.getAnimations()`.
- */
-export function trackTransitions(doc = document) {
-    if (tracking === doc)
-        return;
-    tracking = doc;
-    doc.addEventListener("transitionrun", onTransitionStart);
-    doc.addEventListener("transitionend", onTransitionEnd);
-    try {
-        for (const animation of doc.getAnimations?.() ?? []) {
-            const css = animation;
-            const target = css.effect?.target;
-            if (css.transitionProperty && target && animation.playState === "running")
-                onTransitionStart(Object.assign(new Event("transitionrun"), { propertyName: css.transitionProperty, composedPath: () => [target] }));
-        }
-    }
-    catch { }
-}
-/** Test hook: stop tracking and forget running transitions and queued callbacks. */
-export function _resetTransitions() {
-    tracking?.removeEventListener("transitionrun", onTransitionStart);
-    tracking?.removeEventListener("transitionend", onTransitionEnd);
-    tracking = null;
-    transitionsByElement.clear();
-    transitionCallbacks.clear();
-}
-function cleanupDetachedElements() {
-    for (const [target] of transitionsByElement)
-        if ("isConnected" in target && !target.isConnected)
-            transitionsByElement.delete(target);
-}
-/**
- * Run `fn` once every running CSS transition in the document finished (`fn(true)`), or on the next
- * frame when none runs (`fn(false)`; one frame lets a transition on mount start). Returns a cancel function.
- */
-export function runAfterTransition(fn) {
-    trackTransitions();
-    const frame = requestAnimationFrame(() => {
-        cleanupDetachedElements();
-        if (transitionsByElement.size === 0)
-            return fn(false);
-        transitionCallbacks.add(fn);
-    });
-    return () => {
-        cancelAnimationFrame(frame);
-        transitionCallbacks.delete(fn);
-    };
-}
 /**
  * react-aria `useLabels`: with both `aria-label` and `aria-labelledby`, the element labels itself too
  * (its own id joins `aria-labelledby`, so both are read); id lists are normalized; without any label

package/utils/link-state.d.ts

@@ -0,0 +1,6 @@
+/** Set while `openLink` dispatches its event (react-aria's `openLink.isOpening`); read by usePress / focus-visible / collections. */
+export declare const linkState: {
+    isOpening: boolean;
+};
+/** Whether `openLink` is dispatching its synthetic click (item click handlers let it through). */
+export declare const isOpeningLink: () => boolean;

package/utils/link-state.js

@@ -0,0 +1,6 @@
+// The flag `openLink` (`./links.tsx`) sets while it dispatches its synthetic click. A leaf module (DOCS-COLD
+// 2026-10-20): focus-visible / usePress read it through `../interactions/utils.ts` without reaching the router module.
+/** Set while `openLink` dispatches its event (react-aria's `openLink.isOpening`); read by usePress / focus-visible / collections. */
+export const linkState = { isOpening: false };
+/** Whether `openLink` is dispatching its synthetic click (item click handlers let it through). */
+export const isOpeningLink = () => linkState.isOpening;

package/utils/links.d.ts

@@ -34,12 +34,7 @@ export interface LinkDOMProps {
 }
 /** Whether a click on `link` with `modifiers` should navigate in-document (same origin, `_self`, no download, no modifier). */
 export declare function shouldClientNavigate(link: HTMLAnchorElement, modifiers: Modifiers): boolean;
-/** Set while `openLink` dispatches its event (react-aria's `openLink.isOpening`); read by usePress / focus-visible / collections. */
-export declare const linkState: {
-    isOpening: boolean;
-};
-/** Whether `openLink` is dispatching its synthetic click (item click handlers let it through). */
-export declare const isOpeningLink: () => boolean;
+export { isOpeningLink, linkState } from "./link-state.js";
 /**
  * Open `target` as if clicked with `modifiers` (new tab / window / download follow the browser's
  * rules for them). Focuses the link without scrolling, then dispatches a click (WebKit on macOS:

package/utils/links.jsx

@@ -2,6 +2,7 @@ import { createContext, provide, useContext } from "@rivetjs/reactivity";
 import { resumableContext } from "@rivetjs/runtime/resume-format";
 import { isIPad, isMac, isWebKit } from "../platform/index.js";
 import { renderSlot } from "@rivetjs/runtime/slot";
+import { linkState } from "./link-state.js";
 /** Whether a click on `link` with `modifiers` should navigate in-document (same origin, `_self`, no download, no modifier). */
 export function shouldClientNavigate(link, modifiers) {
     // getAttribute: Firefox defaults link.target to "_parent" inside an iframe.
@@ -14,10 +15,7 @@ export function shouldClientNavigate(link, modifiers) {
         !modifiers.altKey && // download
         !modifiers.shiftKey);
 }
-/** Set while `openLink` dispatches its event (react-aria's `openLink.isOpening`); read by usePress / focus-visible / collections. */
-export const linkState = { isOpening: false };
-/** Whether `openLink` is dispatching its synthetic click (item click handlers let it through). */
-export const isOpeningLink = () => linkState.isOpening;
+export { isOpeningLink, linkState } from "./link-state.js";
 /**
  * Open `target` as if clicked with `modifiers` (new tab / window / download follow the browser's
  * rules for them). Focuses the link without scrolling, then dispatches a click (WebKit on macOS:

package/utils/transitions.d.ts

@@ -0,0 +1,15 @@
+/** Focus `element` without scrolling it into view (`focus({ preventScroll: true })`, Baseline). */
+export declare function focusWithoutScrolling(element: HTMLElement | SVGElement): void;
+/**
+ * Start tracking transitions in `doc` (react-aria does this at import; Rivet modules have no
+ * import-time effects, so the first `runAfterTransition` call does it). Transitions already running
+ * then are picked up from `document.getAnimations()`.
+ */
+export declare function trackTransitions(doc?: Document): void;
+/** Test hook: stop tracking and forget running transitions and queued callbacks. */
+export declare function _resetTransitions(): void;
+/**
+ * Run `fn` once every running CSS transition in the document finished (`fn(true)`), or on the next
+ * frame when none runs (`fn(false)`; one frame lets a transition on mount start). Returns a cancel function.
+ */
+export declare function runAfterTransition(fn: (isTransition: boolean) => void): () => void;

package/utils/transitions.js

@@ -0,0 +1,104 @@
+// react-aria `focusWithoutScrolling` + `runAfterTransition` (Apache-2.0, © Adobe; ported in `./index.ts` before
+// DOCS-COLD 2026-10-20). A leaf module: no imports, so the focus / overlay helpers that need these two do not reach
+// `./index.ts` (which re-exports `merge-props`); `./index.ts` re-exports them.
+/** Focus `element` without scrolling it into view (`focus({ preventScroll: true })`, Baseline). */
+export function focusWithoutScrolling(element) {
+    element.focus({ preventScroll: true });
+}
+// --- runAfterTransition ---------------------------------------------------------------------------
+// Elements currently transitioning → their transitioning CSS properties (a set, not a count: Chrome
+// sometimes fires both transitionend and transitioncancel).
+const transitionsByElement = new Map();
+const transitionCallbacks = new Set();
+let tracking = null;
+const isTransitionEvent = (event) => "propertyName" in event;
+const eventTarget = (event) => {
+    try {
+        return event.composedPath?.()[0] ?? event.target;
+    }
+    catch {
+        return event.target;
+    }
+};
+function onTransitionStart(event) {
+    const target = eventTarget(event);
+    if (!isTransitionEvent(event) || !target)
+        return;
+    let transitions = transitionsByElement.get(target);
+    if (!transitions) {
+        transitionsByElement.set(target, (transitions = new Set()));
+        // On the element itself: it must fire even when the node is removed mid-transition.
+        target.addEventListener("transitioncancel", onTransitionEnd, { once: true });
+    }
+    transitions.add(event.propertyName);
+}
+function onTransitionEnd(event) {
+    const target = eventTarget(event);
+    if (!isTransitionEvent(event) || !target)
+        return;
+    const properties = transitionsByElement.get(target);
+    if (!properties)
+        return;
+    properties.delete(event.propertyName);
+    if (properties.size === 0) {
+        target.removeEventListener("transitioncancel", onTransitionEnd);
+        transitionsByElement.delete(target);
+    }
+    if (transitionsByElement.size === 0) {
+        for (const callback of transitionCallbacks) {
+            callback(true);
+            transitionCallbacks.delete(callback);
+        }
+    }
+}
+/**
+ * Start tracking transitions in `doc` (react-aria does this at import; Rivet modules have no
+ * import-time effects, so the first `runAfterTransition` call does it). Transitions already running
+ * then are picked up from `document.getAnimations()`.
+ */
+export function trackTransitions(doc = document) {
+    if (tracking === doc)
+        return;
+    tracking = doc;
+    doc.addEventListener("transitionrun", onTransitionStart);
+    doc.addEventListener("transitionend", onTransitionEnd);
+    try {
+        for (const animation of doc.getAnimations?.() ?? []) {
+            const css = animation;
+            const target = css.effect?.target;
+            if (css.transitionProperty && target && animation.playState === "running")
+                onTransitionStart(Object.assign(new Event("transitionrun"), { propertyName: css.transitionProperty, composedPath: () => [target] }));
+        }
+    }
+    catch { }
+}
+/** Test hook: stop tracking and forget running transitions and queued callbacks. */
+export function _resetTransitions() {
+    tracking?.removeEventListener("transitionrun", onTransitionStart);
+    tracking?.removeEventListener("transitionend", onTransitionEnd);
+    tracking = null;
+    transitionsByElement.clear();
+    transitionCallbacks.clear();
+}
+function cleanupDetachedElements() {
+    for (const [target] of transitionsByElement)
+        if ("isConnected" in target && !target.isConnected)
+            transitionsByElement.delete(target);
+}
+/**
+ * Run `fn` once every running CSS transition in the document finished (`fn(true)`), or on the next
+ * frame when none runs (`fn(false)`; one frame lets a transition on mount start). Returns a cancel function.
+ */
+export function runAfterTransition(fn) {
+    trackTransitions();
+    const frame = requestAnimationFrame(() => {
+        cleanupDetachedElements();
+        if (transitionsByElement.size === 0)
+            return fn(false);
+        transitionCallbacks.add(fn);
+    });
+    return () => {
+        cancelAnimationFrame(frame);
+        transitionCallbacks.delete(fn);
+    };
+}

package/virtualizer/behaviour.d.ts

@@ -1,9 +1,9 @@
 import { type Signal } from "@rivetjs/reactivity";
 import type { StyleObject } from "@rivetjs/runtime/style";
 import type { Key } from "../collections/index.js";
-import { type CollectionOptions, type Node } from "./collection.js";
+import { type Collection, type CollectionOptions, type Node } from "./collection.js";
 import { type ScrollView } from "./dom.js";
-import type { Layout } from "./layout.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";
@@ -34,12 +34,26 @@ export interface VirtualView<T = unknown> {
     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[]>;
-    /** Layout factory (`() => new ListLayout()`), called on the server and once in the browser. */
-    layout: () => Layout<Node<T>, O>;
+    /**
+     * 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: {
@@ -85,8 +99,25 @@ export declare function visibleViews<T, O>(model: VirtualizerModel<T, O>): Virtu
 /** 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. */