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

package/collections/base.d.ts

@@ -0,0 +1,115 @@
+import type { Collection as ICollection, Key, Node, Rendered } from "./types.js";
+export type Mutable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+type FilterFn<T> = (textValue: string, node: Node<T>) => boolean;
+/** An immutable object representing a Node in a Collection. */
+export declare class CollectionNode<T> implements Node<T> {
+    static readonly type: string;
+    readonly type: string;
+    readonly key: Key;
+    readonly value: T | null;
+    readonly level: number;
+    readonly hasChildNodes: boolean;
+    readonly rendered: Rendered;
+    readonly textValue: string;
+    readonly "aria-label"?: string | undefined;
+    readonly index: number;
+    readonly parentKey: Key | null;
+    readonly prevKey: Key | null;
+    readonly nextKey: Key | null;
+    readonly firstChildKey: Key | null;
+    readonly lastChildKey: Key | null;
+    readonly props: any;
+    readonly render?: ((node: Node<any>) => Rendered) | undefined;
+    readonly colSpan: number | null;
+    readonly colIndex: number | null;
+    constructor(key: Key);
+    get childNodes(): Iterable<Node<T>>;
+    clone(): this;
+    filter(collection: BaseCollection<T>, newCollection: BaseCollection<T>, _filterFn: FilterFn<T>): CollectionNode<T> | null;
+}
+export declare class FilterableNode<T> extends CollectionNode<T> {
+    filter(collection: BaseCollection<T>, newCollection: BaseCollection<T>, filterFn: FilterFn<T>): CollectionNode<T> | null;
+}
+export declare class HeaderNode extends CollectionNode<unknown> {
+    static readonly type = "header";
+}
+export declare class LoaderNode extends CollectionNode<unknown> {
+    static readonly type = "loader";
+}
+export declare class ItemNode<T> extends FilterableNode<T> {
+    static readonly type = "item";
+    filter(collection: BaseCollection<T>, newCollection: BaseCollection<T>, filterFn: FilterFn<T>): ItemNode<T> | null;
+}
+export declare class SectionNode<T> extends FilterableNode<T> {
+    static readonly type = "section";
+    filter(collection: BaseCollection<T>, newCollection: BaseCollection<T>, filterFn: FilterFn<T>): SectionNode<T> | null;
+}
+/**
+ * An immutable Collection implementation. Updates are only allowed when it is not marked as frozen.
+ * This can be subclassed to implement custom collection behaviors.
+ */
+export declare class BaseCollection<T> implements ICollection<Node<T>> {
+    protected keyMap: Map<Key, CollectionNode<T>>;
+    protected firstKey: Key | null;
+    protected lastKey: Key | null;
+    protected frozen: boolean;
+    protected itemCount: number;
+    get size(): number;
+    /** Whether the collection is committed (no further mutation). */
+    get isFrozen(): boolean;
+    getKeys(): IterableIterator<Key>;
+    [Symbol.iterator](): IterableIterator<Node<T>>;
+    getChildren(key: Key): Iterable<Node<T>>;
+    getKeyBefore(key: Key): Key | null;
+    getKeyAfter(key: Key): Key | null;
+    getFirstKey(): Key | null;
+    getLastKey(): Key | null;
+    getItem(key: Key): Node<T> | null;
+    at(): Node<T>;
+    clone(): this;
+    addNode(node: CollectionNode<T>): void;
+    /** Deeply add a node and its children from another collection (filtering). */
+    addDescendants(node: CollectionNode<T>, oldCollection: BaseCollection<T>): void;
+    removeNode(key: Key): void;
+    commit(firstKey: Key | null, lastKey: Key | null, isSSR?: boolean): void;
+    filter(filterFn: FilterFn<T>): this;
+}
+export type CollectionNodeClass<T> = {
+    new (key: Key): CollectionNode<T>;
+    readonly type: string;
+    /**
+     * Rivet: props (and `value` fields) the part reads live from the collection by key (e.g. a column's widths):
+     * a rebuild that changes only these keeps the rendered part (`sameRender`).
+     */
+    readonly liveProps?: readonly string[] | undefined;
+};
+/** Node class for a string type (RAC accepts strings in createLeafComponent / createBranchComponent). */
+export declare function collectionNodeClass(type: string | CollectionNodeClass<any>): CollectionNodeClass<any>;
+/** One node of a collection tree (what a RAC leaf / branch component registers). */
+export interface CollectionNodeSpec<T = unknown> {
+    /** Node class or type string (default "item"). */
+    type?: CollectionNodeClass<T> | string | undefined;
+    /** Key (RAC `id`); generated (`rivet-<n>`) when missing. */
+    id?: Key | undefined;
+    value?: T | undefined;
+    textValue?: string | undefined;
+    "aria-label"?: string | undefined;
+    rendered?: Rendered;
+    render?: ((node: Node<any>) => Rendered) | undefined;
+    /** Remaining props (`node.props`): isDisabled, href, colSpan, … */
+    props?: Record<string, any> | undefined;
+    /** `props` is a fresh object owned by the spec (collection parts): used as `node.props` without a copy. */
+    ownProps?: boolean | undefined;
+    /** Hidden nodes stay out of the collection (RAC `display: none` / `<Hidden>`). */
+    hidden?: boolean | undefined;
+    children?: readonly CollectionNodeSpec<T>[] | undefined;
+}
+/**
+ * Build and commit a collection from a node tree, with the bookkeeping of RAC's fake document:
+ * index / level / parent / sibling / first+last visible child keys, colIndex after colSpans, item
+ * count, duplicate-key detection. Returns a frozen collection.
+ */
+export declare function buildCollection<T, C extends BaseCollection<T> = BaseCollection<T>>(nodes: readonly CollectionNodeSpec<T>[], createCollection?: () => C): C;
+export {};

package/collections/base.js

@@ -0,0 +1,346 @@
+/** An immutable object representing a Node in a Collection. */
+export class CollectionNode {
+    static type;
+    type;
+    key;
+    value = null;
+    level = 0;
+    hasChildNodes = false;
+    rendered = null;
+    textValue = "";
+    "aria-label" = undefined;
+    index = 0;
+    parentKey = null;
+    prevKey = null;
+    nextKey = null;
+    firstChildKey = null;
+    lastChildKey = null;
+    props = {};
+    render;
+    colSpan = null;
+    colIndex = null;
+    constructor(key) {
+        this.type = this.constructor.type;
+        this.key = key;
+    }
+    get childNodes() {
+        throw new Error("childNodes is not supported");
+    }
+    clone() {
+        const node = new this.constructor(this.key);
+        node.value = this.value;
+        node.level = this.level;
+        node.hasChildNodes = this.hasChildNodes;
+        node.rendered = this.rendered;
+        node.textValue = this.textValue;
+        node["aria-label"] = this["aria-label"];
+        node.index = this.index;
+        node.parentKey = this.parentKey;
+        node.prevKey = this.prevKey;
+        node.nextKey = this.nextKey;
+        node.firstChildKey = this.firstChildKey;
+        node.lastChildKey = this.lastChildKey;
+        node.props = this.props;
+        node.render = this.render;
+        node.colSpan = this.colSpan;
+        node.colIndex = this.colIndex;
+        return node;
+    }
+    filter(collection, newCollection, _filterFn) {
+        const clone = this.clone();
+        newCollection.addDescendants(clone, collection);
+        return clone;
+    }
+}
+export class FilterableNode extends CollectionNode {
+    filter(collection, newCollection, filterFn) {
+        const [firstKey, lastKey] = filterChildren(collection, newCollection, this.firstChildKey, filterFn);
+        const newNode = this.clone();
+        newNode.firstChildKey = firstKey;
+        newNode.lastChildKey = lastKey;
+        return newNode;
+    }
+}
+export class HeaderNode extends CollectionNode {
+    static type = "header";
+}
+export class LoaderNode extends CollectionNode {
+    static type = "loader";
+}
+export class ItemNode extends FilterableNode {
+    static type = "item";
+    filter(collection, newCollection, filterFn) {
+        if (filterFn(this.textValue, this)) {
+            const clone = this.clone();
+            newCollection.addDescendants(clone, collection);
+            return clone;
+        }
+        return null;
+    }
+}
+export class SectionNode extends FilterableNode {
+    static type = "section";
+    filter(collection, newCollection, filterFn) {
+        const filteredSection = super.filter(collection, newCollection, filterFn);
+        if (filteredSection && filteredSection.lastChildKey !== null) {
+            const lastChild = collection.getItem(filteredSection.lastChildKey);
+            if (lastChild && lastChild.type !== "header")
+                return filteredSection;
+        }
+        return null;
+    }
+}
+/**
+ * An immutable Collection implementation. Updates are only allowed when it is not marked as frozen.
+ * This can be subclassed to implement custom collection behaviors.
+ */
+export class BaseCollection {
+    keyMap = new Map();
+    firstKey = null;
+    lastKey = null;
+    frozen = false;
+    itemCount = 0;
+    get size() {
+        return this.itemCount;
+    }
+    /** Whether the collection is committed (no further mutation). */
+    get isFrozen() {
+        return this.frozen;
+    }
+    getKeys() {
+        return this.keyMap.keys();
+    }
+    *[Symbol.iterator]() {
+        let node = this.firstKey != null ? this.keyMap.get(this.firstKey) : undefined;
+        while (node) {
+            yield node;
+            node = node.nextKey != null ? this.keyMap.get(node.nextKey) : undefined;
+        }
+    }
+    getChildren(key) {
+        const keyMap = this.keyMap;
+        return {
+            *[Symbol.iterator]() {
+                const parent = keyMap.get(key);
+                let node = parent?.firstChildKey != null ? keyMap.get(parent.firstChildKey) : null;
+                while (node) {
+                    yield node;
+                    node = node.nextKey != null ? keyMap.get(node.nextKey) : undefined;
+                }
+            },
+        };
+    }
+    getKeyBefore(key) {
+        let node = this.keyMap.get(key);
+        if (!node)
+            return null;
+        if (node.prevKey != null) {
+            node = this.keyMap.get(node.prevKey);
+            while (node && node.type !== "item" && node.lastChildKey != null)
+                node = this.keyMap.get(node.lastChildKey);
+            return node?.key ?? null;
+        }
+        return node.parentKey;
+    }
+    getKeyAfter(key) {
+        let node = this.keyMap.get(key);
+        if (!node)
+            return null;
+        if (node.type !== "item" && node.firstChildKey != null)
+            return node.firstChildKey;
+        while (node) {
+            if (node.nextKey != null)
+                return node.nextKey;
+            if (node.parentKey != null)
+                node = this.keyMap.get(node.parentKey);
+            else
+                return null;
+        }
+        return null;
+    }
+    getFirstKey() {
+        return this.firstKey;
+    }
+    getLastKey() {
+        let node = this.lastKey != null ? this.keyMap.get(this.lastKey) : null;
+        while (node?.lastChildKey != null)
+            node = this.keyMap.get(node.lastChildKey);
+        return node?.key ?? null;
+    }
+    getItem(key) {
+        return this.keyMap.get(key) ?? null;
+    }
+    at() {
+        throw new Error("Not implemented");
+    }
+    clone() {
+        const Constructor = this.constructor;
+        const collection = new Constructor();
+        collection.keyMap = new Map(this.keyMap);
+        collection.firstKey = this.firstKey;
+        collection.lastKey = this.lastKey;
+        collection.itemCount = this.itemCount;
+        return collection;
+    }
+    addNode(node) {
+        if (this.frozen)
+            throw new Error("Cannot add a node to a frozen collection");
+        if (node.type === "item" && this.keyMap.get(node.key) == null)
+            this.itemCount++;
+        this.keyMap.set(node.key, node);
+    }
+    /** Deeply add a node and its children from another collection (filtering). */
+    addDescendants(node, oldCollection) {
+        this.addNode(node);
+        for (const child of oldCollection.getChildren(node.key))
+            this.addDescendants(child, oldCollection);
+    }
+    removeNode(key) {
+        if (this.frozen)
+            throw new Error("Cannot remove a node to a frozen collection");
+        const node = this.keyMap.get(key);
+        if (node != null && node.type === "item")
+            this.itemCount--;
+        this.keyMap.delete(key);
+    }
+    commit(firstKey, lastKey, isSSR = false) {
+        if (this.frozen)
+            throw new Error("Cannot commit a frozen collection");
+        this.firstKey = firstKey;
+        this.lastKey = lastKey;
+        this.frozen = !isSSR;
+    }
+    filter(filterFn) {
+        const newCollection = new this.constructor();
+        const [firstKey, lastKey] = filterChildren(this, newCollection, this.firstKey, filterFn);
+        newCollection?.commit(firstKey, lastKey);
+        return newCollection;
+    }
+}
+function filterChildren(collection, newCollection, firstChildKey, filterFn) {
+    // Loop over the siblings of firstChildKey, create new nodes with node.filter, update prev/next keys.
+    if (firstChildKey == null)
+        return [null, null];
+    let firstNode = null;
+    let lastNode = null;
+    let currentNode = collection.getItem(firstChildKey);
+    while (currentNode != null) {
+        const newNode = currentNode.filter(collection, newCollection, filterFn);
+        if (newNode != null) {
+            newNode.nextKey = null;
+            if (lastNode) {
+                newNode.prevKey = lastNode.key;
+                lastNode.nextKey = newNode.key;
+            }
+            if (firstNode == null)
+                firstNode = newNode;
+            newCollection.addNode(newNode);
+            lastNode = newNode;
+        }
+        currentNode = currentNode.nextKey != null ? collection.getItem(currentNode.nextKey) : null;
+    }
+    // A trailing separator is dropped once the rest of the contents are filtered.
+    if (lastNode && lastNode.type === "separator") {
+        const prevKey = lastNode.prevKey;
+        newCollection.removeNode(lastNode.key);
+        if (prevKey != null) {
+            lastNode = newCollection.getItem(prevKey);
+            lastNode.nextKey = null;
+        }
+        else
+            lastNode = null;
+    }
+    return [firstNode?.key ?? null, lastNode?.key ?? null];
+}
+const nodeClasses = new Map();
+/** Node class for a string type (RAC accepts strings in createLeafComponent / createBranchComponent). */
+export function collectionNodeClass(type) {
+    if (typeof type !== "string")
+        return type;
+    if (type === "item")
+        return ItemNode;
+    if (type === "section")
+        return SectionNode;
+    if (type === "header")
+        return HeaderNode;
+    if (type === "loader")
+        return LoaderNode;
+    let NodeClass = nodeClasses.get(type);
+    if (!NodeClass) {
+        NodeClass = class extends CollectionNode {
+            static type = type;
+        };
+        nodeClasses.set(type, NodeClass);
+    }
+    return NodeClass;
+}
+/**
+ * Build and commit a collection from a node tree, with the bookkeeping of RAC's fake document:
+ * index / level / parent / sibling / first+last visible child keys, colIndex after colSpans, item
+ * count, duplicate-key detection. Returns a frozen collection.
+ */
+export function buildCollection(nodes, createCollection) {
+    const collection = createCollection ? createCollection() : new BaseCollection();
+    const owners = new Set();
+    let nodeId = 0;
+    const create = (spec) => {
+        const NodeClass = collectionNodeClass(spec.type ?? "item");
+        const node = new NodeClass(spec.id ?? `rivet-${++nodeId}`);
+        // `ownProps`: a fresh object of the part (live props: getters stay unread; a spread would read every live prop in
+        // the tracked build pass and re-render the rows).
+        const props = spec.ownProps ? (spec.props ?? {}) : { ...(spec.props ?? {}) };
+        node.props = props;
+        node.rendered = spec.rendered;
+        node.render = spec.render;
+        node.value = spec.value ?? null;
+        if (spec["aria-label"])
+            node["aria-label"] = spec["aria-label"];
+        node.textValue = spec.textValue || (typeof spec.rendered === "string" ? spec.rendered : "") || spec["aria-label"] || "";
+        if (props.colSpan != null)
+            node.colSpan = props.colSpan;
+        return node;
+    };
+    // Post-order: children get their ids before their parent (RAC registers leaves first, so the
+    // auto ids of a section's items precede the section's).
+    const childrenOf = new Map();
+    const build = (specs) => {
+        const out = [];
+        for (const spec of specs) {
+            if (spec.hidden)
+                continue;
+            const children = build(spec.children ?? []);
+            const node = create(spec);
+            node.hasChildNodes = (spec.children ?? []).length > 0;
+            node.firstChildKey = children[0]?.key ?? null;
+            node.lastChildKey = children[children.length - 1]?.key ?? null;
+            childrenOf.set(node.key, children);
+            out.push(node);
+        }
+        return out;
+    };
+    const link = (siblings, parent) => {
+        const level = parent ? parent.level + (parent.type === "item" ? 1 : 0) : 0;
+        let colIndex = null;
+        siblings.forEach((node, index) => {
+            node.index = index;
+            node.level = level;
+            node.parentKey = parent ? parent.key : null;
+            node.prevKey = siblings[index - 1]?.key ?? null;
+            node.nextKey = siblings[index + 1]?.key ?? null;
+            // Update the colIndex of sibling nodes after a colSpan.
+            if (colIndex != null)
+                node.colIndex = colIndex;
+            if (node.colSpan != null || node.colIndex != null)
+                colIndex = (node.colIndex ?? node.index) + (node.colSpan ?? 1);
+            if (owners.has(node.key))
+                throw new Error(`Duplicate key "${String(node.key)}" found in collection. Every item in a collection must have a unique key.`);
+            owners.add(node.key);
+            collection.addNode(node);
+            link(childrenOf.get(node.key) ?? [], node);
+        });
+    };
+    const top = build(nodes);
+    link(top, null);
+    collection.commit(top[0]?.key ?? null, top[top.length - 1]?.key ?? null);
+    return collection;
+}

package/collections/builder.d.ts

@@ -0,0 +1,44 @@
+import type { Collection, CollectionBase, CollectionChildren, CollectionComponent, CollectionElement, CollectionStateBase, ItemProps, Key, Node, PartialNode, SectionProps } from "./types.js";
+/** Whether `value` is a collection element (`Item(…)`, `Section(…)`, custom builder components). */
+export declare function isCollectionElement(value: unknown): value is CollectionElement;
+/**
+ * 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 declare function defineCollectionComponent<P extends {
+    key?: Key | undefined;
+}, T = unknown>(getCollectionNode: (props: P, context: any) => Generator<PartialNode<T>, void, Node<T>[]>): CollectionComponent<T, P>;
+/** React.Children.forEach equivalent: flattens arrays, skips null / undefined / booleans. */
+export declare function forEachChild(children: unknown, fn: (child: any) => void): void;
+/** React.Children.count equivalent. */
+export declare function countChildren(children: unknown): number;
+/**
+ * Item / Section are generic in React (`<Item<T>>`); elements they return are assignable to any
+ * collection's children, like untyped JSX elements.
+ */
+export interface GenericCollectionComponent<P> extends CollectionComponent<any, P> {
+    (props: P): CollectionElement<any, P>;
+}
+/** An item in a collection (static: `Item({ key, children })`; dynamic: from a renderer). */
+export declare const Item: GenericCollectionComponent<ItemProps<any>>;
+/** A section (group) of items. */
+export declare const Section: GenericCollectionComponent<SectionProps<any>>;
+/** Builds collection nodes from collection elements / items + renderer (react-stately `CollectionBuilder`). */
+export declare class CollectionBuilder<T extends object> {
+    private context?;
+    private cache;
+    build(props: Partial<CollectionBase<T>>, context?: unknown): Iterable<Node<T>>;
+    private iterateCollection;
+    private getKey;
+    private getChildState;
+    private getFullNode;
+}
+export interface CollectionOptions<T, C extends Collection<Node<T>>> extends Omit<CollectionStateBase<T, C>, "children"> {
+    children?: CollectionChildren<T> | undefined;
+}
+export type CollectionFactory<T, C extends Collection<Node<T>>> = (nodes: Iterable<Node<T>>) => C;
+/**
+ * Build a collection from props (react-stately `useCollection`): `collection` if given, else
+ * `factory(builder.build({ children, items }, context))`.
+ */
+export declare function createCollection<T, C extends Collection<Node<T>> = Collection<Node<T>>>(props: CollectionOptions<T, C>, factory: CollectionFactory<T, C>, context?: unknown, builder?: CollectionBuilder<any>): C;