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

package/collections/components.jsx

@@ -0,0 +1,537 @@
+// Ported from react-aria (src/collections/CollectionBuilder.tsx, src/collections/Hidden.tsx,
+// src/collections/useCachedChildren.ts) and react-aria-components (src/Collection.tsx), Apache-2.0,
+// © Adobe.
+//
+// The RAC collection API over Rivet: `createLeafComponent` / `createBranchComponent` define collection
+// parts (ListBoxItem, ListBoxSection, MenuItem, TreeItem, Row, …), `Collection` renders static or
+// `items`-driven children, `CollectionBuilder` builds a `BaseCollection` from JSX.
+//
+// Rivet: two render modes instead of React's hidden portal render + real render.
+// - Live (default): parts render their real DOM in place, inside the host's DOM (`data-key` on the
+//   item element); the host's state reads the collection back from the DOM at event time
+//   (`./dom.ts` `domCollection`). Server HTML = final markup, resumed pages need no item model, and a
+//   host that never needs a built collection pays nothing (ListBox).
+// - Build (`buildCollection` / `CollectionBuilder` / `collectionOf`): the content runs once in build
+//   mode — parts register `CollectionNodeSpec`s (with a `render` thunk) and render nothing — and the
+//   specs commit into a frozen `BaseCollection`. Used where upstream needs the collection before /
+//   without the item DOM: closed Select / ComboBox popovers (selected item text, filtered size),
+//   flattened trees (Tree / Table: `CollectionRoot` renders `node.render(node)` per node), virtualizers.
+//   Inside a `computed`, so a signal read by the content (items, filters) rebuilds it — also inside the
+//   (untracked) component bodies of nested parts, which re-enter the build's observer (`tracked`); a resumed
+//   handler capturing the computed rebuilds it in the browser from its recipe. Built rows render through
+//   `renderNodeAt`: a rebuilt node that renders the same keeps its DOM (`sameRender`).
+// Deviation: `CollectionBuilder` children get an accessor `() => C` (reactive), not a value.
+// Deviation: in live mode a part's `node` has key / type / value / textValue / props / level /
+//   parentKey; index / prevKey / nextKey / firstChildKey are unset (no siblings known) — read them from
+//   a built collection. Never capture `node` (class instance) in a resumable handler: capture `node.key`.
+// Deviation: branch nodes carry `content` (Rivet field): the branch's lazy children; the default
+//   `CollectionBranch` renders it in live mode.
+// Deviation: `dependencies` is accepted and ignored (signals re-render; no item cache to invalidate).
+// Deviation: React hook names → Rivet (`useIsHidden` → `isHidden`, `usePersistedKeys` →
+//   `persistedKeys`, `useCachedChildren` → `collectionChildren`).
+import { _observer, _reobserve, _scoped, computed, createContext, provide, runWithOwner, untrack, useContext, } from "@rivetjs/reactivity";
+import { For, Provider } from "@rivetjs/runtime/dom";
+import { _rUnrecorded, resumableContext } from "@rivetjs/runtime/resume-format";
+import { isSlot } from "@rivetjs/runtime/slot";
+import { HiddenContext } from "./hidden.js";
+import { hasLive } from "../utils/live.jsx";
+import { mergeProps as mergeLive, splitProps } from "@rivetjs/runtime/props";
+import { BaseCollection, buildCollection, collectionNodeClass, } from "./base.js";
+const BuildContext = createContext(null);
+/** Provided by collection hosts (`CollectionRoot`) and branches; `null` outside any collection. */
+export const CollectionScopeContext = resumableContext(createContext(null, { id: "rv-collection-scope" }));
+const CollectionItemContext = resumableContext(createContext(null, { id: "rv-collection-item" }));
+/**
+ * RAC `addIdAndValue` clones the ONE element a row renders: only the first part of a row takes the
+ * row's id / value (a fragment's other parts, e.g. a trailing load-more item, keep their own / auto
+ * ids). Tracked outside the (serialized) context value so a re-created region starts fresh.
+ */
+const consumedDefaults = new WeakSet();
+function takeItemDefaults() {
+    const defaults = useContext(CollectionItemContext);
+    if (!defaults || consumedDefaults.has(defaults))
+        return null;
+    consumedDefaults.add(defaults);
+    return defaults;
+}
+/**
+ * Rivet: the `id` an `items` row assigns to a part that is not a collection node (RAC useCachedChildren clones
+ * the rendered element with `id`: TabPanel inside `<TabPanels items>`), or `undefined` outside a row / when a part
+ * of the row already took it. Call once, at the start of the part's body.
+ */
+export function collectionItemId() {
+    return resolveId({}, takeItemDefaults(), useContext(CollectionContext));
+}
+const CollectionContext = resumableContext(createContext(null, { id: "rv-collection" }));
+/**
+ * Run `fn` tracked by the build pass that `build` belongs to. Component bodies run untracked (runtime
+ * component creation untracks), so a part re-enters the build's observer before evaluating user content
+ * (`items` accessors, function children, nested `Collection`s): a signal read there rebuilds the
+ * collection, like React re-rendering RAC's hidden tree. Reads in component *props* expressions stay
+ * snapshots (as in live mode).
+ */
+const tracked = (build, fn) => _reobserve(build.run.o, fn);
+/** RAC `useIsHidden`: whether the caller renders in build mode (render nothing visible, register only). */
+export function isHidden() {
+    return useContext(HiddenContext) || useContext(BuildContext) != null;
+}
+// ---------------------------------------------------------------------------------------------
+// Building
+// ---------------------------------------------------------------------------------------------
+/**
+ * Run `content` in build mode and commit the registered nodes into a collection (RAC
+ * `CollectionBuilder`'s hidden render + `Document.getCollection`). Tracks the signals `content`
+ * reads; call inside a `computed` (`collectionOf`) to rebuild on change.
+ */
+export function buildCollectionFrom(content, createCollection) {
+    const run = { o: _observer() };
+    const scope = { specs: [], parentKey: null, ids: { n: 0 }, run };
+    // The build pass renders nothing: keep the resume recorder out of it (no dead regions/ids).
+    try {
+        _rUnrecorded(() => provide(BuildContext, scope, () => provide(HiddenContext, true, () => tracked(scope, () => evaluate(content)))));
+    }
+    finally {
+        run.o = null;
+    }
+    return buildCollection(scope.specs, createCollection);
+}
+/**
+ * Rivet (server): evaluate `content` in build mode registering nothing, so the collection root in it (ListBox / Menu /
+ * …, `isCollectionProbe`) merges its own `id` into the `SelectableCollectionContext` `MergedId` (`contextProps`) before
+ * the parent's input renders `aria-controls`. RA merges the ids after the first render (mergeIds re-renders the
+ * `useId` holder); a resumed page never re-renders, so its server markup has to carry the merged id. Hideable parts
+ * (SearchField, Input, …) render nothing in build mode.
+ */
+export function probeCollection(content) {
+    const scope = { specs: [], parentKey: null, ids: { n: 0 }, run: { o: null }, probe: true };
+    _rUnrecorded(() => provide(BuildContext, scope, () => provide(HiddenContext, true, () => untrack(() => evaluate(content)))));
+}
+const COMPILED = Symbol.for("rivet.compiled");
+const TEMPLATE = Symbol.for("rivet.template");
+const SCOPED = Symbol.for("rivet.server.scoped");
+/**
+ * @internal Server slot probe walk (`probeSlots`, `./server-on.tsx`): `probeCollection` that also walks the server output
+ * as the server renderer does (lazy slots and 0-arity children called, compiled / template records' slots, scoped
+ * records under their owner), so a Description in a render-function child or nested in another part's lazy children (a
+ * card's ItemContent) is reached. Attribute / spread records and handlers are not called. Cheap because the parts it
+ * reaches return early while `slotProbing` is on (ui wrappers, Label / Input / FieldError, nested field owners).
+ */
+export function _probeTree(content) {
+    const scope = { specs: [], parentKey: null, ids: { n: 0 }, run: { o: null }, probe: true };
+    // No HiddenContext: the hideable parts check `slotProbing` first; `isHidden()` sees the build scope.
+    provide(BuildContext, scope, () => probeWalk(evaluate(content), 0));
+}
+function probeWalk(value, depth) {
+    if (value == null || depth > 200)
+        return;
+    if (typeof value === "function") {
+        if (isSlot(value) || value.length === 0)
+            probeWalk(value(), depth + 1);
+        return;
+    }
+    if (typeof value !== "object")
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            probeWalk(item, depth + 1);
+        return;
+    }
+    const record = value;
+    if (record[COMPILED] || record[TEMPLATE]) {
+        for (const slot of record.slots ?? [])
+            probeWalk(slot, depth + 1);
+    }
+    else if (record[SCOPED]) {
+        const inner = record.value;
+        runWithOwner(record.owner ?? null, () => probeWalk(inner, depth + 1));
+    }
+}
+/** Whether the caller renders inside `probeCollection`: a collection root merges the context id and renders nothing. */
+export function isCollectionProbe() {
+    return useContext(BuildContext)?.probe === true;
+}
+/**
+ * A reactive collection accessor for `content` (lazy JSX / slot / render function): the Rivet
+ * equivalent of reading `CollectionBuilder`'s collection before the item DOM exists (closed
+ * popovers). Server: built on first read. Browser: rebuilt when a signal the content reads changes.
+ */
+export function collectionOf(content, createCollection) {
+    return computed(() => buildCollectionFrom(content, createCollection));
+}
+/**
+ * Builds a `Collection` from the `content` and passes it to `children` (RAC `CollectionBuilder`).
+ * Inside another builder's build pass it only renders the content (registers into that build).
+ */
+export function CollectionBuilder(props) {
+    const { content, children, createCollection } = props;
+    const build = useContext(BuildContext);
+    if (build)
+        return tracked(build, () => evaluate(content));
+    return children(collectionOf(content, createCollection));
+}
+/** Call lazy content / thunks; arrays element-wise. Results are discarded in build mode. */
+function evaluate(content) {
+    if (typeof content === "function" && (isSlot(content) || content.length === 0))
+        return evaluate(content());
+    if (Array.isArray(content))
+        return content.map(evaluate);
+    return content;
+}
+/**
+ * Live (rendered) content of a host / branch / row, placed inside the caller's providers: slots run now; any other
+ * 0-arity function — a `{() => …}` render-function child or a DOM v2 structural accessor (`<For>` / `<Show>` /
+ * dynamic fragment child) — stays a reactive child, each read in a scope under the current owner (`_scoped`: context
+ * lookups see these providers). Calling it here would read it once, untracked: v2 rows / filtered options would never
+ * update. Server: everything now (`evaluate`, see `serverNow`).
+ */
+function place(content) {
+    if (isServer)
+        return evaluate(content);
+    if (isSlot(content))
+        return place(content());
+    if (typeof content === "function" && content.length === 0)
+        return _scoped(() => place(content()));
+    if (Array.isArray(content))
+        return content.map(place);
+    return content;
+}
+/**
+ * `textValue` default (RAC Document): string / number children, else "" (the caller then falls back to
+ * `aria-label`). Lazy JSX children are NEVER evaluated here: that would render the part's content a second
+ * time outside its providers (stray overlays, double Text / Keyboard). Live mode: the DOM collection reads the
+ * item element's text at event time (`./dom.ts` `domTextValue`). Build mode: give `textValue` for non-string
+ * children (RAC's warning).
+ */
+function defaultTextValue(props) {
+    const children = props.children;
+    if (typeof children === "string")
+        return children;
+    if (typeof children === "number")
+        return String(children);
+    return "";
+}
+function resolveId(props, defaults, scope) {
+    if (props.id != null)
+        return props.id;
+    const id = defaults?.id;
+    return id != null && scope?.idScope != null ? `${String(scope.idScope)}:${String(id)}` : id;
+}
+/**
+ * Id of a part without `id` (RAC: generated by the collection document): `$.<n>` per parent in
+ * document order (`<parentKey>.$.<n>` below a branch), the same in build and live mode, so keys read
+ * from the DOM match a built collection's.
+ */
+function generatedId(parentKey, ids) {
+    return (parentKey == null ? "" : String(parentKey) + ".") + "$." + ids.n++;
+}
+/** Live-mode node of a part (see header: no sibling links). */
+function liveNode(NodeClass, props, id, value, scope) {
+    const node = new NodeClass(id);
+    const [textValue, rest] = nodeProps(props);
+    node.props = rest;
+    node.value = (value ?? null);
+    node.textValue = textValue || defaultTextValue(props) || props["aria-label"] || "";
+    if (props["aria-label"])
+        node["aria-label"] = props["aria-label"];
+    node.level = scope?.level ?? 0;
+    node.parentKey = scope?.parentKey ?? null;
+    if (rest.colSpan != null)
+        node.colSpan = rest.colSpan;
+    return node;
+}
+/**
+ * A part's node props (`{ id, value, textValue, ...rest } = props`) and whether a prop is live (P5): with an own getter
+ * the rest forwards unread (`splitProps`), so the build pass does not depend on a live prop and `node.props.isDisabled`
+ * / `class` / … stay live for the selection manager and the part (no node rebuild, no item re-creation). The rest is a
+ * fresh object either way (spec `ownProps`: `buildCollection` uses it without a copy).
+ */
+function nodeProps(props) {
+    if (!hasLive(props)) {
+        const { id: _id, value: _value, textValue, ...rest } = props;
+        return [textValue, rest, false];
+    }
+    return [untrack(() => props.textValue), splitProps(props, ["id", "value", "textValue"])[1], true];
+}
+/**
+ * The props a built part renders with: `node.props` plus its key / value. Live: the part's own props when no `items`
+ * row supplied id / value (they already carry both; no per-render merge), else a merge that keeps the getters.
+ */
+const withNode = (all, direct, props, live, extra) => direct ? all : live ? mergeLive(props, extra) : { ...props, ...extra };
+/**
+ * Defines a collection leaf part (RAC `createLeafComponent`): outside a collection it renders
+ * `render(props, ref)` (a render taking `node` throws there, as upstream); inside a collection host
+ * it renders `render(props, ref, node)` in place (live) or registers a node (build mode).
+ */
+export function createLeafComponent(CollectionNodeClass, render) {
+    const NodeClass = collectionNodeClass(CollectionNodeClass);
+    const name = render.name || "Component";
+    return function CollectionLeaf(props) {
+        const p = props;
+        const build = useContext(BuildContext);
+        const defaults = takeItemDefaults();
+        if (build) {
+            const collectionCtx = useContext(CollectionContext);
+            const all = p;
+            const [textValue, rest, live] = nodeProps(all);
+            const value = all.value ?? defaults?.value;
+            // RAC passes node.props as given: `id` only when the user (or an `items` row) supplied one.
+            const explicitId = resolveId(all, defaults, collectionCtx);
+            build.specs.push({
+                type: NodeClass,
+                id: explicitId ?? generatedId(build.parentKey, build.ids),
+                value: value,
+                textValue: textValue || defaultTextValue(all),
+                "aria-label": all["aria-label"],
+                rendered: all.children,
+                props: rest,
+                ownProps: true,
+                render: (node) => render(withNode(all, live && !defaults, node.props, live, explicitId == null ? { value: node.value } : { id: node.key, value: node.value }), p.ref, node),
+            });
+            return null;
+        }
+        const scope = useContext(CollectionScopeContext);
+        if (!scope) {
+            if (render.length >= 3)
+                throw new Error(name + " cannot be rendered outside a collection.");
+            return render(props, p.ref);
+        }
+        const id = resolveId(p, defaults, useContext(CollectionContext)) ?? generatedId(scope.parentKey, scope.ids);
+        const value = p.value ?? defaults?.value;
+        const node = liveNode(NodeClass, p, id, value, scope);
+        return render(defaults ? { ...props, id, value } : props, p.ref, node);
+    };
+}
+/** RAC useCachedChildren: a branch's `useChildren` sees the explicit / item-default id as `id` (never a generated `$.n` id). */
+const childProps = (props, all, id) => (id == null || all.id === id ? props : { ...props, id });
+/**
+ * Defines a collection branch part (RAC `createBranchComponent`: sections, tree items, rows with
+ * cells). `useChildren(props)` returns the branch's collection children (default: `Collection`
+ * semantics over `props.children` / `props.items`). The render gets `node`; render the children with
+ * the renderer's `CollectionBranch` (`<CollectionBranch collection={…} parent={node} />`).
+ */
+export function createBranchComponent(CollectionNodeClass, render, useChildren = (props) => collectionChildren(props)) {
+    const NodeClass = collectionNodeClass(CollectionNodeClass);
+    return function CollectionBranchPart(props) {
+        const p = props;
+        const all = p;
+        const build = useContext(BuildContext);
+        const defaults = takeItemDefaults();
+        const collectionCtx = useContext(CollectionContext);
+        const id = resolveId(all, defaults, collectionCtx);
+        const value = all.value ?? defaults?.value;
+        if (build) {
+            // Live props (P5): getters forwarded unread (as `nodeProps` for leaves); `children` is the branch's own.
+            const [textValue, rest, live] = nodeProps(all);
+            const key = id ?? generatedId(build.parentKey, build.ids);
+            const spec = {
+                type: NodeClass,
+                id: key,
+                value: value,
+                textValue: textValue || "",
+                "aria-label": all["aria-label"],
+                rendered: null,
+                props: rest,
+                ownProps: true,
+                render: (node) => render(withNode(all, live && !defaults, node.props, live, id == null ? { value: node.value } : { id: node.key, value: node.value }), p.ref, node),
+                children: [],
+            };
+            build.specs.push(spec);
+            provide(BuildContext, { specs: spec.children, parentKey: key, ids: { n: 0 }, run: build.run }, () => provide(CollectionItemContext, null, () => tracked(build, () => evaluate(() => useChildren(childProps(props, all, id))))));
+            return null;
+        }
+        const scope = useContext(CollectionScopeContext);
+        const key = id ?? generatedId(scope?.parentKey, scope?.ids ?? { n: 0 });
+        const node = liveNode(NodeClass, all, key, value, scope);
+        node.hasChildNodes = true;
+        const childScope = {
+            parentKey: key,
+            level: (scope?.level ?? 0) + (NodeClass.type === "item" ? 1 : 0),
+            idScope: scope?.idScope,
+            ids: { n: 0 },
+        };
+        node.content = () => (<Provider token={CollectionScopeContext} value={childScope}>
+        <Provider token={CollectionItemContext} value={null}>
+          {place(useChildren(childProps(props, all, id)))}
+        </Provider>
+      </Provider>);
+        return render(defaults ? { ...props, id: key, value } : props, p.ref, node);
+    };
+}
+const toArray = (items) => {
+    const value = typeof items === "function" ? items() : items;
+    return Array.isArray(value) ? value : [...value];
+};
+/** Default id of an item object (`item.key ?? item.id`). */
+const itemId = (item) => {
+    if (item == null || typeof item !== "object")
+        return undefined;
+    const o = item;
+    return o.key ?? o.id;
+};
+/**
+ * The children of a collection or branch (RAC `useCachedChildren` with `addIdAndValue`): static
+ * content as is; `items` + renderer → one row per item, its part defaulting `id` to `item.key ??
+ * item.id` and `value` to the item.
+ */
+export function collectionChildren(props) {
+    const { items, children } = props;
+    // A per-item renderer (`(item) => …`, arity ≥ 1) without items renders nothing (RAC useCachedChildren). Told
+    // apart from lazy content: compiler slots and 0-arity thunks (`{() => …}` render-function children, kept for
+    // resumability) are content and render as is.
+    if (items == null)
+        return typeof children === "function" && !isSlot(children) && children.length > 0 ? null : children;
+    if (typeof children !== "function" || isSlot(children))
+        return children;
+    const render = children;
+    const build = useContext(BuildContext);
+    if (build) {
+        // Build mode: synchronous loop, tracked by the build (an `items` signal / accessor rebuilds the collection).
+        return tracked(build, () => toArray(items).map((item) => provide(CollectionItemContext, { id: itemId(item), value: item }, () => evaluate(render(item)))));
+    }
+    const each = () => toArray(items);
+    return (<For each={each} by={(item, index) => itemId(item) ?? index}>
+      {(item) => {
+            // Reactive row: a new item object under the same key (or index) re-renders the row's part.
+            const row = () => {
+                const value = item(); // tracked here: component bodies run untracked
+                return (<Provider token={CollectionItemContext} value={{ id: itemId(value), value }}>
+              {place(render(value))}
+            </Provider>);
+            };
+            // A function child is a dynamic region (re-runs when `item()` changes). Server: evaluated in the row
+            // (see `serverNow`).
+            return serverNow(row);
+        }}
+    </For>);
+}
+const isServer = typeof document === "undefined";
+/**
+ * A dynamic row region (`For` row callback returning a function) as the row's content. Server: evaluated right
+ * away — a function value is otherwise rendered after the row's resume scope closed, so the part's bindings would
+ * belong to the page root instead of the row region and outlive a row the resumed list drops ("Missing resumable
+ * element", stale computeds reading a removed key). Runtime gap: function children are not server resume regions.
+ */
+const serverNow = (row) => (isServer ? row() : row);
+/** A Collection renders a list of items, automatically managing ids and values (RAC `Collection`). */
+export function Collection(props) {
+    const ctx = useContext(CollectionContext);
+    const idScope = props.idScope ?? ctx?.idScope;
+    // Build mode: synchronous (a server `Provider` defers its children; the build must register now).
+    const build = useContext(BuildContext);
+    if (build)
+        return provide(CollectionContext, { idScope }, () => tracked(build, () => evaluate(collectionChildren(props))));
+    return (<Provider token={CollectionContext} value={{ idScope }}>
+      {place(collectionChildren(props))}
+    </Provider>);
+}
+/** The collection of a `CollectionInput` (reads the accessor). */
+export const resolveCollection = (collection) => typeof collection === "function" ? collection() : (collection ?? null);
+const isPlain = (v) => {
+    if (v === null || typeof v !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+};
+/**
+ * Two values render the same: identical, or two functions of the same source (lazy children / render
+ * functions re-created by a rebuild: what they capture comes from the node's props / value, compared alongside;
+ * signals they read stay live bindings).
+ */
+const sameField = (a, b) => Object.is(a, b) || (typeof a === "function" && typeof b === "function" && isSlot(a) === isSlot(b) && a.length === b.length && String(a) === String(b));
+/** Shallow equality of plain objects (props, item values), skipping the `live` keys. */
+function sameShallow(a, b, live) {
+    if (Object.is(a, b))
+        return true;
+    if (!isPlain(a) || !isPlain(b))
+        return false;
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length)
+        return false;
+    for (const k of keys)
+        if (!(k in b) || (!live?.includes(k) && !sameField(a[k], b[k])))
+            return false;
+    return true;
+}
+/**
+ * Whether a rebuilt node renders like the previous one (Rivet: RAC keeps the DOM through React's reconciliation;
+ * a Rivet part is re-created): same class / key / text, render inputs (`rendered`, shallow `props` and item `value`)
+ * equal. Sibling links / index / level are not compared: parts read those live from the collection by key.
+ */
+export function sameRender(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b || a.constructor !== b.constructor || a.key !== b.key || a.textValue !== b.textValue || a["aria-label"] !== b["aria-label"])
+        return false;
+    const live = a.constructor.liveProps;
+    return sameField(a.rendered, b.rendered) && sameShallow(a.props, b.props, live) && sameShallow(a.value, b.value, live);
+}
+/**
+ * Renders the node at `key` of a built collection (a keyed row of `CollectionRoot` / `CollectionBranch` and the
+ * hosts' own node loops): a dynamic region that keeps the rendered part (DOM, focus) across rebuilds while the
+ * node renders the same (`sameRender`) and re-renders it when its render inputs changed, or when `depends` (read in the
+ * region) changes: a part whose content renders from its parent's value (TreeItemContent).
+ */
+export function renderNodeAt(collection, key, depends) {
+    // Server: rendered once, untracked. `depends` / the cut-off `node` are the browser region's re-render triggers; read
+    // in a resumable row they would count as the row's own reads, so the resumed For re-created the row on every re-run
+    // of its region (a sort re-created the table header and body: focus lost) instead of keeping it like a client rebuild.
+    if (isServer)
+        return untrack(() => {
+            const n = collection()?.getItem(key()) ?? null;
+            return n?.render ? n.render(n) : null;
+        });
+    const node = computed(() => collection()?.getItem(key()) ?? null, { equals: sameRender });
+    return serverNow(() => {
+        depends?.();
+        node();
+        // The current node (the cut-off computed keeps the first of equal ones; `depends` re-renders with the latest).
+        const n = untrack(() => collection()?.getItem(key()) ?? null);
+        return n?.render ? untrack(() => n.render(n)) : null;
+    });
+}
+function renderNodes(collection, parent) {
+    // Rows are keyed by primitive keys (stable across rebuilds) so an adopted (resumed) row survives a
+    // collection rebuild; a row re-renders only when its node's render inputs changed (`renderNodeAt`) and parts
+    // read live data by key.
+    const each = () => {
+        const c = resolveCollection(collection);
+        const keys = [];
+        for (const n of parent ? c.getChildren(parent.key) : c)
+            if (n.type !== "content")
+                keys.push(n.key);
+        return keys;
+    };
+    return (<For each={each} by={(key) => key}>
+      {(key) => renderNodeAt(() => resolveCollection(collection), key)}
+    </For>);
+}
+/** RAC `DefaultCollectionRenderer`: built collections render node by node; live mode renders content in place. */
+export const DefaultCollectionRenderer = {
+    CollectionRoot(props) {
+        const { collection, content, idScope } = props;
+        if (collection)
+            return renderNodes(collection, null);
+        return (<Provider token={CollectionScopeContext} value={{ parentKey: null, level: 0, idScope, ids: { n: 0 } }}>
+        {place(content)}
+      </Provider>);
+    },
+    CollectionBranch(props) {
+        const { collection, parent } = props;
+        if (collection && untrack(() => resolveCollection(collection)?.getItem(parent.key)))
+            return renderNodes(collection, parent);
+        return (parent.content?.() ?? null);
+    },
+};
+/** RAC `CollectionRendererContext` (Virtualizer provides its own renderer). */
+export const CollectionRendererContext = createContext(DefaultCollectionRenderer);
+/** RAC `usePersistedKeys`: the focused key stays rendered (virtualizers). */
+export function persistedKeys(focusedKey) {
+    return focusedKey != null ? new Set([focusedKey]) : null;
+}
+/** Provided by hosts so a generic `<Section>` renders as their section part (RAC `SectionContext`). */
+export const SectionContext = createContext(null);
+/** @deprecated Use the collection's section part (`ListBoxSection`, `MenuSection`, …). */
+export const Section = /* @__PURE__ */ createBranchComponent("section", function Section(props, ref, section) {
+    const ctx = useContext(SectionContext);
+    return ctx.render(props, ref, section, "rv-Section");
+});

package/collections/data-source.d.ts

@@ -0,0 +1,26 @@
+/** A range of numbers: `start` inclusive, `end` exclusive. */
+export type ListRange = {
+    start: number;
+    end: number;
+};
+/** A component that provides a view of some data collection (CDK `CollectionViewer`). */
+export interface CollectionViewer {
+    /** The portion of the data the viewer currently looks at. */
+    viewChange: () => ListRange;
+}
+/** Source of data for a collection viewer (table, tree, virtual list). */
+export declare abstract class DataSource<T> {
+    /** Connects a collection viewer; returns an accessor of the current data. */
+    abstract connect(collectionViewer: CollectionViewer): () => readonly T[];
+    /** Disconnects a collection viewer (clean-up / tear-down). */
+    abstract disconnect(collectionViewer: CollectionViewer): void;
+}
+/** Checks whether an object is a data source (has a `connect` function). */
+export declare function isDataSource(value: any): value is DataSource<any>;
+/** DataSource wrapper for a native array or an accessor of one. */
+export declare class ArrayDataSource<T> extends DataSource<T> {
+    private _data;
+    constructor(_data: readonly T[] | (() => readonly T[]));
+    connect(): () => readonly T[];
+    disconnect(): void;
+}

package/collections/data-source.js

@@ -0,0 +1,27 @@
+// Ported from @angular/cdk/collections (data-source.ts, array-data-source.ts, collection-viewer.ts),
+// MIT, © Google LLC.
+//
+// rxjs Observables → Rivet accessors: `connect` returns `() => readonly T[]` (a signal or computed:
+// read it in a binding / `For each` to track changes). `viewChange` is an accessor of the rendered
+// range (virtual lists write it).
+/** Source of data for a collection viewer (table, tree, virtual list). */
+export class DataSource {
+}
+/** Checks whether an object is a data source (has a `connect` function). */
+export function isDataSource(value) {
+    // Cannot be checked as `instanceof DataSource`: sources may match the interface without extending it.
+    return !!value && typeof value.connect === "function";
+}
+/** DataSource wrapper for a native array or an accessor of one. */
+export class ArrayDataSource extends DataSource {
+    _data;
+    constructor(_data) {
+        super();
+        this._data = _data;
+    }
+    connect() {
+        const data = this._data;
+        return typeof data === "function" ? data : () => data;
+    }
+    disconnect() { }
+}

package/collections/dom.d.ts

@@ -0,0 +1,34 @@
+import { BaseCollection } from "./base.js";
+import type { Key, Node } from "./types.js";
+/** Attributes that encode `key` for `domKey` (numeric keys keep their type). */
+export declare function keyAttrs(key: Key): {
+    "data-key": string;
+    "data-key-type"?: "number";
+};
+/** The key an element encodes (`keyAttrs`), or null. */
+export declare function domKey(element: Element): Key | null;
+/** Node type of a collection element. */
+export declare function domNodeType(element: Element): string;
+/** Typeahead text of a collection element. */
+export declare function domTextValue(element: Element): string;
+export interface DomCollectionOptions {
+    /** Selector of collection nodes (default `[data-key]`). */
+    selector?: string;
+    /**
+     * Only nodes owned by this collection: elements whose closest `[data-collection]` is `root`'s
+     * (nested collections, e.g. a tag group inside a table cell, are skipped). Default true when
+     * `root` has `data-collection`.
+     */
+    scoped?: boolean;
+}
+/**
+ * Build a frozen `BaseCollection` from the DOM under `root`. Cheap enough to run per handler call
+ * (one `querySelectorAll` + one pass); cache per event if a handler needs it repeatedly.
+ */
+export declare function domCollection<T = unknown>(root: Element, options?: DomCollectionOptions): BaseCollection<T>;
+/** Element of `key` inside the collection element (react-aria `getItemElement`). */
+export declare function getItemElement(collection: Element | null | undefined, key: Key): HTMLElement | null;
+/** Node of `element` in `collection`, if any. */
+export declare function nodeOf<T>(collection: {
+    getItem(key: Key): Node<T> | null;
+}, element: Element): Node<T> | null;