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

package/collections/builder.js

@@ -0,0 +1,283 @@
+import { isSlot } from "@rivetjs/runtime/slot";
+/** Whether `value` is a collection element (`Item(…)`, `Section(…)`, custom builder components). */
+export function isCollectionElement(value) {
+    return typeof value === "object" && value !== null && value.$$collection === true;
+}
+/**
+ * Define a builder component from a `getCollectionNode` generator (react-stately's static method).
+ * Calling the component returns a collection element; `props.key` becomes the element key.
+ */
+export function defineCollectionComponent(getCollectionNode) {
+    const component = ((props) => {
+        const { key = null, ...rest } = props;
+        return { $$collection: true, type: component, key, props: rest };
+    });
+    component.getCollectionNode = getCollectionNode;
+    return component;
+}
+/** React.Children.forEach equivalent: flattens arrays, skips null / undefined / booleans. */
+export function forEachChild(children, fn) {
+    // Plain JSX children arrive as a compiler slot (lazy thunk): resolve it here, once.
+    if (isSlot(children))
+        forEachChild(children(), fn);
+    else if (Array.isArray(children))
+        for (const child of children)
+            forEachChild(child, fn);
+    else if (children != null && typeof children !== "boolean")
+        fn(children);
+}
+/** React.Children.count equivalent. */
+export function countChildren(children) {
+    let n = 0;
+    forEachChild(children, () => n++);
+    return n;
+}
+function hasChildItems(props) {
+    if (props.hasChildItems != null)
+        return props.hasChildItems;
+    if (props.childItems)
+        return true;
+    if (props.title && countChildren(props.children) > 0)
+        return true;
+    return false;
+}
+/** An item in a collection (static: `Item({ key, children })`; dynamic: from a renderer). */
+export const Item = /* @__PURE__ */ defineCollectionComponent(function* getCollectionNode(props, context) {
+    const { childItems, title, children } = props;
+    const rendered = props.title || props.children;
+    const textValue = props.textValue || (typeof rendered === "string" ? rendered : "") || props["aria-label"] || "";
+    // suppressTextValueWarning is used in components like Tabs, which don't have type to select support.
+    if (!textValue && !context?.suppressTextValueWarning && isDev()) {
+        console.warn("<Item> with non-plain text contents is unsupported by type to select for accessibility. Please add a `textValue` prop.");
+    }
+    yield {
+        type: "item",
+        props,
+        rendered,
+        textValue,
+        "aria-label": props["aria-label"],
+        hasChildNodes: hasChildItems(props),
+        *childNodes() {
+            if (childItems) {
+                for (const child of childItems)
+                    yield { type: "item", value: child };
+            }
+            else if (title) {
+                const items = [];
+                forEachChild(children, (child) => items.push({ type: "item", element: child }));
+                yield* items;
+            }
+        },
+    };
+});
+/** A section (group) of items. */
+export const Section = /* @__PURE__ */ defineCollectionComponent(function* getCollectionNode(props) {
+    const { children, title, items } = props;
+    yield {
+        type: "section",
+        props,
+        hasChildNodes: true,
+        rendered: title,
+        "aria-label": props["aria-label"],
+        *childNodes() {
+            if (typeof children === "function" && !isSlot(children)) {
+                if (!items)
+                    throw new Error("props.children was a function but props.items is missing");
+                for (const item of items)
+                    yield { type: "item", value: item, renderer: children };
+            }
+            else {
+                const list = [];
+                forEachChild(children, (child) => list.push({ type: "item", element: child }));
+                yield* list;
+            }
+        },
+    };
+});
+const isDev = () => globalThis.process?.env?.NODE_ENV === "development";
+/** Builds collection nodes from collection elements / items + renderer (react-stately `CollectionBuilder`). */
+export class CollectionBuilder {
+    context;
+    cache = new WeakMap();
+    build(props, context) {
+        this.context = context;
+        return iterable(() => this.iterateCollection(props));
+    }
+    *iterateCollection(props) {
+        const { children, items } = props;
+        if (typeof children === "function" && !isSlot(children)) {
+            if (!items)
+                throw new Error("props.children was a function but props.items is missing");
+            let index = 0;
+            for (const item of items) {
+                yield* this.getFullNode({ value: item, index }, { renderer: children });
+                index++;
+            }
+        }
+        else {
+            const elements = [];
+            forEachChild(children, (child) => {
+                if (child)
+                    elements.push(child);
+            });
+            let index = 0;
+            for (const item of elements) {
+                const nodes = this.getFullNode({ element: item, index }, {});
+                for (const node of nodes) {
+                    index++;
+                    yield node;
+                }
+            }
+        }
+    }
+    getKey(item, partialNode, _state, parentKey) {
+        if (item.key != null)
+            return item.key;
+        if (partialNode.type === "cell" && partialNode.key != null)
+            return `${parentKey}${partialNode.key}`;
+        const v = partialNode.value;
+        if (v != null) {
+            const key = v.key ?? v.id;
+            if (key == null)
+                throw new Error("No key found for item");
+            return key;
+        }
+        return parentKey ? `${parentKey}.${partialNode.index}` : `$.${partialNode.index}`;
+    }
+    getChildState(state, partialNode) {
+        return { renderer: partialNode.renderer || state.renderer };
+    }
+    *getFullNode(partialNode, state, parentKey, parentNode) {
+        // Fragments: arrays of elements.
+        if (Array.isArray(partialNode.element)) {
+            const children = [];
+            forEachChild(partialNode.element, (child) => children.push(child));
+            let index = partialNode.index ?? 0;
+            for (const child of children)
+                yield* this.getFullNode({ element: child, index: index++ }, state, parentKey, parentNode);
+            return;
+        }
+        // If there's a value instead of an element on the node, and a parent renderer function is
+        // available, use it to render an element for the value.
+        let element = partialNode.element;
+        if (!element && partialNode.value && state && state.renderer) {
+            const cached = this.cache.get(partialNode.value);
+            if (cached && (!cached.shouldInvalidate || !cached.shouldInvalidate(this.context))) {
+                cached.index = partialNode.index;
+                cached.parentKey = parentNode ? parentNode.key : null;
+                yield cached;
+                return;
+            }
+            element = state.renderer(partialNode.value);
+        }
+        // An element with a getCollectionNode function on its type is a supported component. Call it to
+        // get a partial node, and recursively build a full node from there.
+        if (isCollectionElement(element)) {
+            const type = element.type;
+            if (typeof type !== "function" || typeof type.getCollectionNode !== "function") {
+                throw new Error(`Unknown element <${String(type.name)}> in collection.`);
+            }
+            const childNodes = type.getCollectionNode(element.props, this.context);
+            let index = partialNode.index ?? 0;
+            let result = childNodes.next();
+            while (!result.done && result.value) {
+                const childNode = result.value;
+                partialNode.index = index;
+                let nodeKey = childNode.key ?? null;
+                if (nodeKey == null)
+                    nodeKey = childNode.element ? null : this.getKey(element, partialNode, state, parentKey);
+                const nodes = this.getFullNode({ ...childNode, key: nodeKey, index, wrapper: compose(partialNode.wrapper, childNode.wrapper) }, this.getChildState(state, childNode), parentKey ? `${parentKey}${element.key}` : element.key, parentNode);
+                const children = [...nodes];
+                for (const node of children) {
+                    // Cache the node based on its value.
+                    node.value = childNode.value ?? partialNode.value ?? null;
+                    if (node.value)
+                        this.cache.set(node.value, node);
+                    // The partial node may have specified a type for the child in order to specify a
+                    // constraint. Verify that the full node that was built recursively matches this type.
+                    if (partialNode.type && node.type !== partialNode.type) {
+                        throw new Error(`Unsupported type <${capitalize(node.type)}> in <${capitalize(parentNode?.type ?? "unknown parent type")}>. Only <${capitalize(partialNode.type)}> is supported.`);
+                    }
+                    index++;
+                    yield node;
+                }
+                result = childNodes.next(children);
+            }
+            return;
+        }
+        // Ignore invalid elements.
+        if (partialNode.key == null || partialNode.type == null)
+            return;
+        // Create full node.
+        const builder = this;
+        const node = {
+            type: partialNode.type,
+            props: partialNode.props,
+            key: partialNode.key,
+            parentKey: parentNode ? parentNode.key : null,
+            value: partialNode.value ?? null,
+            level: (parentNode?.level ?? 0) + (parentNode?.type === "item" ? 1 : 0),
+            index: partialNode.index,
+            rendered: partialNode.rendered,
+            textValue: partialNode.textValue ?? "",
+            "aria-label": partialNode["aria-label"],
+            wrapper: partialNode.wrapper,
+            shouldInvalidate: partialNode.shouldInvalidate,
+            hasChildNodes: partialNode.hasChildNodes || false,
+            childNodes: iterable(function* () {
+                if (!partialNode.hasChildNodes || !partialNode.childNodes)
+                    return;
+                let index = 0;
+                for (const child of partialNode.childNodes()) {
+                    // Ensure child keys are globally unique by prepending the parent node's key.
+                    if (child.key != null)
+                        child.key = `${node.key}${child.key}`;
+                    const nodes = builder.getFullNode({ ...child, index }, builder.getChildState(state, child), node.key, node);
+                    for (const n of nodes) {
+                        index++;
+                        yield n;
+                    }
+                }
+            }),
+        };
+        yield node;
+    }
+}
+/** Wraps an iterator function as an iterable object, and caches the results. */
+function iterable(iterator) {
+    const cache = [];
+    let it = null;
+    return {
+        *[Symbol.iterator]() {
+            for (const item of cache)
+                yield item;
+            if (!it)
+                it = iterator();
+            for (const item of it) {
+                cache.push(item);
+                yield item;
+            }
+        },
+    };
+}
+function compose(outer, inner) {
+    if (outer && inner)
+        return (element) => outer(inner(element));
+    if (outer)
+        return outer;
+    if (inner)
+        return inner;
+    return undefined;
+}
+function capitalize(str) {
+    return str[0].toUpperCase() + str.slice(1);
+}
+/**
+ * Build a collection from props (react-stately `useCollection`): `collection` if given, else
+ * `factory(builder.build({ children, items }, context))`.
+ */
+export function createCollection(props, factory, context, builder = new CollectionBuilder()) {
+    if (props.collection)
+        return props.collection;
+    return factory(builder.build({ children: props.children ?? null, items: props.items }, context));
+}

package/collections/components.d.ts

@@ -0,0 +1,217 @@
+import { type Context } from "@rivetjs/reactivity";
+import type { RefProp } from "@rivetjs/runtime/jsx-runtime";
+import { BaseCollection, type CollectionNodeClass } from "./base.js";
+import type { Collection as ICollection, Key, LayoutDelegate, Node, SelectionBehavior, SelectionMode } from "./types.js";
+export type { CollectionNodeClass, CollectionNodeSpec } from "./base.js";
+/** Live scope: parent / level / id scope of the parts rendered below (plain data, resumable). */
+export interface CollectionScope {
+    readonly parentKey: Key | null;
+    readonly level: number;
+    readonly idScope?: Key | undefined;
+    /** Ordinal of the next id-less part under this parent (`generatedId`). */
+    readonly ids: {
+        n: number;
+    };
+}
+/** Provided by collection hosts (`CollectionRoot`) and branches; `null` outside any collection. */
+export declare const CollectionScopeContext: Context<CollectionScope | null>;
+/**
+ * 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 declare function collectionItemId(): Key | undefined;
+/** RAC `useIsHidden`: whether the caller renders in build mode (render nothing visible, register only). */
+export declare function isHidden(): boolean;
+/**
+ * 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 declare function buildCollectionFrom<C extends BaseCollection<any> = BaseCollection<any>>(content: unknown, createCollection?: () => C): C;
+/**
+ * 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 declare function probeCollection(content: unknown): void;
+/**
+ * @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 declare function _probeTree(content: unknown): void;
+/** Whether the caller renders inside `probeCollection`: a collection root merges the context id and renders nothing. */
+export declare function isCollectionProbe(): boolean;
+/**
+ * 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 declare function collectionOf<C extends BaseCollection<any> = BaseCollection<any>>(content: unknown, createCollection?: () => C): () => C;
+export interface CollectionBuilderProps<C extends BaseCollection<any>> {
+    /** The collection content (plain JSX children are lazy). */
+    content: unknown;
+    /** Renders with the built collection (Rivet: an accessor). */
+    children: (collection: () => C) => unknown;
+    createCollection?: () => C;
+}
+/**
+ * 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 declare function CollectionBuilder<C extends BaseCollection<any>>(props: CollectionBuilderProps<C>): unknown;
+/** Props every collection part may carry (RAC: `id`, `value`, `textValue` are read by the collection). */
+export interface CollectionPartProps {
+    id?: Key | undefined;
+    value?: unknown;
+    textValue?: string | undefined;
+    "aria-label"?: string | undefined;
+    ref?: RefProp<any> | undefined;
+    children?: unknown;
+}
+type LeafRender<P, E extends Element, T> = (props: P, ref: RefProp<E> | undefined, node: Node<T>) => unknown;
+/**
+ * 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 declare function createLeafComponent<P extends object, E extends Element = HTMLElement, T = unknown>(CollectionNodeClass: CollectionNodeClass<any> | string, render: LeafRender<P, E, T> | ((props: P, ref: RefProp<E> | undefined) => unknown)): (props: P) => unknown;
+type BranchRender<P, E extends Element, T> = (props: P, ref: RefProp<E> | undefined, node: Node<T>) => unknown;
+/**
+ * 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 declare function createBranchComponent<P extends {
+    children?: unknown;
+}, E extends Element = HTMLElement, T = unknown>(CollectionNodeClass: CollectionNodeClass<any> | string, render: BranchRender<P, E, T>, useChildren?: (props: P) => unknown): (props: P) => unknown;
+export interface CollectionProps<T> {
+    /** Item objects in the collection (array or accessor). */
+    items?: Iterable<T> | (() => Iterable<T>) | undefined;
+    /** Static parts (lazy JSX), or a renderer for `items` returning one part per item. */
+    children?: unknown | ((item: T) => unknown);
+    /** RAC parity; ignored (Rivet re-renders through signals). */
+    dependencies?: readonly unknown[] | undefined;
+    /** A scope prepended to the ids of child items (`<idScope>:<id>`) to keep them unique. */
+    idScope?: Key | undefined;
+}
+/**
+ * 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 declare function collectionChildren<T>(props: CollectionProps<T>): unknown;
+/** A Collection renders a list of items, automatically managing ids and values (RAC `Collection`). */
+export declare function Collection<T>(props: CollectionProps<T>): unknown;
+/** RAC `ItemRenderProps` (Rivet: values are read inside bindings — the render-prop object is reactive). */
+export interface ItemRenderProps {
+    /** @selector [data-hovered] */
+    isHovered: boolean;
+    /** @selector [data-pressed] */
+    isPressed: boolean;
+    /** @selector [data-selected] */
+    isSelected: boolean;
+    /** @selector [data-focused] */
+    isFocused: boolean;
+    /** @selector [data-focus-visible] */
+    isFocusVisible: boolean;
+    /** @selector [data-disabled] */
+    isDisabled: boolean;
+    /** @selector [data-selection-mode="single | multiple"] */
+    selectionMode: SelectionMode;
+    selectionBehavior: SelectionBehavior;
+    /** @selector [data-allows-dragging] */
+    allowsDragging?: boolean;
+    /** @selector [data-dragging] */
+    isDragging?: boolean;
+    /** @selector [data-drop-target] */
+    isDropTarget?: boolean;
+}
+export interface CollectionBranchProps {
+    /** The collection of items to render (a built collection or an accessor of one; null in live mode). */
+    collection: CollectionInput;
+    /** The parent node of the items to render. */
+    parent: Node<unknown>;
+    /** A function that renders a drop indicator between items (DnD, C8). */
+    renderDropIndicator?: ((target: {
+        type: "item";
+        key: Key;
+        dropPosition: "before" | "after" | "on";
+    }) => unknown) | undefined;
+}
+export interface CollectionRootProps {
+    /**
+     * The built collection to render from (`node.render(node)` per node) or an accessor of one (a
+     * changing collection updates the keyed rows in place), or null: live mode, render `content` in place.
+     */
+    collection: CollectionInput;
+    /** Rivet: the host's collection content (live mode), lazy: a slot / thunk evaluated inside the root scope. */
+    content?: unknown;
+    /** Rivet: id scope of the root (live mode). */
+    idScope?: Key | undefined;
+    /** A set of keys for items that should always be persisted in the DOM (virtualizers). */
+    persistedKeys?: Set<Key> | null | undefined;
+    /** The scroll container (virtualizers). */
+    scrollRef?: unknown;
+    renderDropIndicator?: CollectionBranchProps["renderDropIndicator"];
+}
+export interface CollectionRenderer {
+    /** Whether this is a virtualized collection (hosts then build the collection and pass it). */
+    isVirtualized?: boolean | undefined;
+    /** A delegate object that provides layout information for items in the collection. */
+    layoutDelegate?: LayoutDelegate | undefined;
+    /** A delegate that provides drop targets for pointer coordinates (DnD, C8). */
+    dropTargetDelegate?: unknown;
+    /** Renders the root collection items. */
+    CollectionRoot: (props: CollectionRootProps) => unknown;
+    /** Renders the child items of a branch. */
+    CollectionBranch: (props: CollectionBranchProps) => unknown;
+}
+/** A built collection, an accessor of one, or null (live mode). */
+export type CollectionInput = ICollection<Node<unknown>> | (() => ICollection<Node<unknown>>) | null | undefined;
+/** The collection of a `CollectionInput` (reads the accessor). */
+export declare const resolveCollection: (collection: CollectionInput) => ICollection<Node<unknown>> | null;
+/**
+ * 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 declare function sameRender(a: Node<unknown> | null | undefined, b: Node<unknown> | null | undefined): boolean;
+/**
+ * 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 declare function renderNodeAt(collection: () => ICollection<Node<unknown>> | null | undefined, key: () => Key, depends?: () => unknown): unknown;
+/** RAC `DefaultCollectionRenderer`: built collections render node by node; live mode renders content in place. */
+export declare const DefaultCollectionRenderer: CollectionRenderer;
+/** RAC `CollectionRendererContext` (Virtualizer provides its own renderer). */
+export declare const CollectionRendererContext: Context<CollectionRenderer>;
+/** RAC `usePersistedKeys`: the focused key stays rendered (virtualizers). */
+export declare function persistedKeys(focusedKey: Key | null): Set<Key> | null;
+export interface SectionProps<T> extends CollectionProps<T> {
+    /** The unique id of the section. */
+    id?: Key | undefined;
+    /** The object value that this section represents (set automatically in dynamic collections). */
+    value?: T | undefined;
+    "aria-label"?: string | undefined;
+    class?: string | undefined;
+    style?: unknown;
+    [attr: `data-${string}`]: unknown;
+}
+interface SectionContextValue {
+    /** Name of the collection-specific section part (deprecation message). */
+    name: string;
+    render: (props: SectionProps<any>, ref: RefProp<HTMLElement> | undefined, section: Node<any>, className?: string) => unknown;
+}
+/** Provided by hosts so a generic `<Section>` renders as their section part (RAC `SectionContext`). */
+export declare const SectionContext: Context<SectionContextValue | null>;
+/** @deprecated Use the collection's section part (`ListBoxSection`, `MenuSection`, …). */
+export declare const Section: <T>(props: SectionProps<T>) => unknown;