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

package/collections/selection-model.js

@@ -0,0 +1,192 @@
+// Ported from @angular/cdk/collections (selection-model.ts), MIT, © Google LLC.
+//
+// Imperative selection of values (not keys): for client-side code and stores. rxjs `Subject` →
+// a minimal `changed` emitter (`subscribe(fn)` returns an unsubscribe). Not serializable: for
+// resumable component state use `@rivetjs/cdk/selection/state` (signals) instead.
+/** Minimal Subject: `next` notifies subscribers in order. */
+export class Emitter {
+    listeners = [];
+    subscribe(fn) {
+        this.listeners.push(fn);
+        return {
+            unsubscribe: () => {
+                this.listeners = this.listeners.filter((l) => l !== fn);
+            },
+        };
+    }
+    next(value) {
+        for (const fn of [...this.listeners])
+            fn(value);
+    }
+    get observed() {
+        return this.listeners.length > 0;
+    }
+}
+/** Class to be used to power selecting one or more options from a list. */
+export class SelectionModel {
+    /** Currently-selected values. */
+    _selection = new Set();
+    /** Keeps track of the deselected options that haven't been emitted by the change event. */
+    _deselectedToEmit = [];
+    /** Keeps track of the selected options that haven't been emitted by the change event. */
+    _selectedToEmit = [];
+    /** Cache for the array value of the selected items. */
+    _selected = null;
+    /** Selected values. */
+    get selected() {
+        if (!this._selected)
+            this._selected = Array.from(this._selection.values());
+        return this._selected;
+    }
+    /** Event emitted when the value has changed. */
+    changed = new Emitter();
+    /** Selection methods taking arrays (no spread: large collections). */
+    bulk = {
+        select: (values) => this._select(values),
+        deselect: (values) => this._deselect(values),
+        setSelection: (values) => this._setSelection(values),
+    };
+    _multiple;
+    _emitChanges;
+    compareWith;
+    constructor(_multiple = false, initiallySelectedValues, _emitChanges = true, compareWith) {
+        this._multiple = _multiple;
+        this._emitChanges = _emitChanges;
+        this.compareWith = compareWith;
+        if (initiallySelectedValues && initiallySelectedValues.length) {
+            if (_multiple)
+                initiallySelectedValues.forEach((value) => this._markSelected(value));
+            else
+                this._markSelected(initiallySelectedValues[0]);
+            // Clear the array in order to avoid firing the change event for preselected values.
+            this._selectedToEmit.length = 0;
+        }
+    }
+    /** Selects a value or an array of values. Returns whether the selection changed. */
+    select(...values) {
+        return this._select(values);
+    }
+    /** Deselects a value or an array of values. Returns whether the selection changed. */
+    deselect(...values) {
+        return this._deselect(values);
+    }
+    /** Sets the selected values. Returns whether the selection changed. */
+    setSelection(...values) {
+        return this._setSelection(values);
+    }
+    /** Toggles a value between selected and deselected. */
+    toggle(value) {
+        return this.isSelected(value) ? this.deselect(value) : this.select(value);
+    }
+    /**
+     * Clears all of the selected values. `flushEvent` false defers the change event to the next one.
+     * Returns whether the selection changed.
+     */
+    clear(flushEvent = true) {
+        this._unmarkAll();
+        const changed = this._hasQueuedChanges();
+        if (flushEvent)
+            this._emitChangeEvent();
+        return changed;
+    }
+    /** Determines whether a value is selected. */
+    isSelected(value) {
+        return this._selection.has(this._getConcreteValue(value));
+    }
+    /** Determines whether the model does not have a value. */
+    isEmpty() {
+        return this._selection.size === 0;
+    }
+    /** Determines whether the model has a value. */
+    hasValue() {
+        return !this.isEmpty();
+    }
+    /** Sorts the selected values based on a predicate function. */
+    sort(predicate) {
+        if (this._multiple && this.selected)
+            this._selected.sort(predicate);
+    }
+    /** Gets whether multiple values can be selected. */
+    isMultipleSelection() {
+        return this._multiple;
+    }
+    _select(values) {
+        this._verifyValueAssignment(values);
+        values.forEach((value) => this._markSelected(value));
+        const changed = this._hasQueuedChanges();
+        this._emitChangeEvent();
+        return changed;
+    }
+    _deselect(values) {
+        this._verifyValueAssignment(values);
+        values.forEach((value) => this._unmarkSelected(value));
+        const changed = this._hasQueuedChanges();
+        this._emitChangeEvent();
+        return changed;
+    }
+    _setSelection(values) {
+        this._verifyValueAssignment(values);
+        const oldValues = this.selected;
+        const newSelectedSet = new Set(values.map((value) => this._getConcreteValue(value)));
+        values.forEach((value) => this._markSelected(value));
+        oldValues.filter((value) => !newSelectedSet.has(this._getConcreteValue(value, newSelectedSet))).forEach((value) => this._unmarkSelected(value));
+        const changed = this._hasQueuedChanges();
+        this._emitChangeEvent();
+        return changed;
+    }
+    /** Emits a change event and clears the records of selected and deselected values. */
+    _emitChangeEvent() {
+        // Clear the selected values so they can be re-cached.
+        this._selected = null;
+        if (this._selectedToEmit.length || this._deselectedToEmit.length) {
+            this.changed.next({ source: this, added: this._selectedToEmit, removed: this._deselectedToEmit });
+            this._deselectedToEmit = [];
+            this._selectedToEmit = [];
+        }
+    }
+    _markSelected(value) {
+        value = this._getConcreteValue(value);
+        if (!this.isSelected(value)) {
+            if (!this._multiple)
+                this._unmarkAll();
+            if (!this.isSelected(value))
+                this._selection.add(value);
+            if (this._emitChanges)
+                this._selectedToEmit.push(value);
+        }
+    }
+    _unmarkSelected(value) {
+        value = this._getConcreteValue(value);
+        if (this.isSelected(value)) {
+            this._selection.delete(value);
+            if (this._emitChanges)
+                this._deselectedToEmit.push(value);
+        }
+    }
+    _unmarkAll() {
+        if (!this.isEmpty())
+            this._selection.forEach((value) => this._unmarkSelected(value));
+    }
+    /** Throws when several values are assigned to a single-selection model. */
+    _verifyValueAssignment(values) {
+        if (values.length > 1 && !this._multiple)
+            throw getMultipleValuesInSingleSelectionError();
+    }
+    _hasQueuedChanges() {
+        return !!(this._deselectedToEmit.length || this._selectedToEmit.length);
+    }
+    /** A value comparable to inputValue by compareWith, or inputValue itself. */
+    _getConcreteValue(inputValue, selection) {
+        if (!this.compareWith)
+            return inputValue;
+        selection = selection ?? this._selection;
+        for (const selectedValue of selection)
+            if (this.compareWith(inputValue, selectedValue))
+                return selectedValue;
+        return inputValue;
+    }
+}
+/** Error: multiple values passed into a single-value SelectionModel. */
+export function getMultipleValuesInSingleSelectionError() {
+    return Error("Cannot pass multiple values into SelectionModel with single-value mode.");
+}

package/collections/server-dev.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from "@rivetjs/reactivity";
+export declare const slotProbing = false;
+export declare function probeSlots(_values: readonly (readonly [Context<any>, unknown])[], _content: unknown): void;
+export declare const idScoping = false;
+export declare function scopedIdUpdaters(): Map<string, unknown> | undefined;
+export declare function domRowItem(_item: unknown): void;

package/collections/server-dev.js

@@ -0,0 +1,18 @@
+export const slotProbing = false;
+let warned = false;
+export function probeSlots(_values, _content) {
+    if (warned || typeof document !== "undefined")
+        return;
+    warned = true;
+    // eslint-disable-next-line no-console
+    console.warn("[rivet cdk] cdk slot probe is disabled: your server bundle resolves the `browser` export condition for @rivetjs/cdk " +
+        "(`#server` / `@rivetjs/cdk/slot-probe` → the browser no-op), so server-rendered aria-describedby / aria-labelledby " +
+        "ids keep slots by expectation and can point at elements that never render. Build the server bundle without the `browser` condition.");
+}
+// Reactive ids: one browser registry (`utils/id.ts`); `idScoping` folds the server lookup away.
+export const idScoping = false;
+export function scopedIdUpdaters() {
+    return undefined;
+}
+// DOM-backed loader data (DOM-DATA): browsers register no rows (folds away).
+export function domRowItem(_item) { }

package/collections/server-off.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from "@rivetjs/reactivity";
+export declare const slotProbing = false;
+export declare function probeSlots(_values: readonly (readonly [Context<any>, unknown])[], _content: unknown): void;
+export declare const idScoping = false;
+export declare function scopedIdUpdaters(): Map<string, unknown> | undefined;
+export declare function domRowItem(_item: unknown): void;

package/collections/server-off.js

@@ -0,0 +1,9 @@
+export const slotProbing = false;
+export function probeSlots(_values, _content) { }
+// Reactive ids: one browser registry (`utils/id.ts`); `idScoping` folds the server lookup away.
+export const idScoping = false;
+export function scopedIdUpdaters() {
+    return undefined;
+}
+// DOM-backed loader data (DOM-DATA): browsers register no rows (folds away).
+export function domRowItem(_item) { }

package/collections/server-on.d.ts

@@ -0,0 +1,29 @@
+import { type Context } from "@rivetjs/reactivity";
+/**
+ * Server: true while a field probes which of its slotted parts render (`probeSlots`; synchronous, module state). Parts
+ * check it first: a hideable part that consumes a slot id (`Text` description / errorMessage, `ComboBoxValue`) marks it
+ * (`probeSlot`) and renders nothing; Label / Input / FieldError, the ui wrappers and nested field owners return `null`
+ * at once (their subtrees hold no slot of this field). Browser: the constant `false`.
+ */
+export declare let slotProbing: boolean;
+/**
+ * Rivet (server): run the field's `content` once with `values` (its context providers) and `slotProbing` on, before the
+ * field renders the element whose `aria-describedby` names its parts (RA `useSlotId` drops a missing part after
+ * hydration; a resumed page never re-renders). The parts that render mark their slot ids, so the owner writes
+ * `slotIdRef(id, false)`. Isolation: untracked, unrecorded (no resume regions / ids), inside a throwaway root disposed
+ * at the end (nothing the probe creates stays owned), effects inert (`_wrapEffects`: created, never run); a throw is
+ * swallowed (the real render reports it). Field children therefore render twice on the server: keep them pure. Pass
+ * the same providers as the real render (a part reading a missing context throws). Popover content is not probed
+ * (its contexts are cleared there). Browser: a no-op.
+ */
+export declare function probeSlots(values: readonly (readonly [Context<any>, unknown])[], content: unknown): void;
+/** Server: reactive ids (`idSignal`) are registered per render id scope (`utils/id.ts`). Browser: the constant `false`. */
+export declare const idScoping = true;
+/**
+ * Server: the `idSignal` registry of the current render (`withIdScope`: the router opens one per request), or undefined
+ * outside any scope (process-wide `rvs` ids: `utils/id.ts` keeps its module map). Id strings restart per scope, so
+ * concurrent streaming renders share them; one registry per scope keeps a `mergeIds` of request B from changing request
+ * A's ids. Held weakly by the scope object: dropped with the render.
+ */
+export declare function scopedIdUpdaters(): Map<string, unknown> | undefined;
+export declare function domRowItem(item: unknown): void;

package/collections/server-on.jsx

@@ -0,0 +1,86 @@
+// Server half of the field slot probe: the default resolution of the cdk `#server` import and of
+// `@rivetjs/cdk/slot-probe` (package.json). `.tsx`: server-compiled with its importers (one `slotProbing` instance).
+// Browsers resolve `./server-off.ts` (`slotProbing` is the constant `false`, `probeSlots` a no-op), so DOM bundles fold
+// every probe branch away: 0 bytes.
+import { _wrapEffects, createRoot, provide, untrack } from "@rivetjs/reactivity";
+import { _rUnrecorded } from "@rivetjs/runtime/resume-format";
+import { _idScope } from "@rivetjs/runtime/id";
+import { _probeTree } from "./components.jsx";
+/**
+ * Server: true while a field probes which of its slotted parts render (`probeSlots`; synchronous, module state). Parts
+ * check it first: a hideable part that consumes a slot id (`Text` description / errorMessage, `ComboBoxValue`) marks it
+ * (`probeSlot`) and renders nothing; Label / Input / FieldError, the ui wrappers and nested field owners return `null`
+ * at once (their subtrees hold no slot of this field). Browser: the constant `false`.
+ */
+export let slotProbing = false;
+/**
+ * Rivet (server): run the field's `content` once with `values` (its context providers) and `slotProbing` on, before the
+ * field renders the element whose `aria-describedby` names its parts (RA `useSlotId` drops a missing part after
+ * hydration; a resumed page never re-renders). The parts that render mark their slot ids, so the owner writes
+ * `slotIdRef(id, false)`. Isolation: untracked, unrecorded (no resume regions / ids), inside a throwaway root disposed
+ * at the end (nothing the probe creates stays owned), effects inert (`_wrapEffects`: created, never run); a throw is
+ * swallowed (the real render reports it). Field children therefore render twice on the server: keep them pure. Pass
+ * the same providers as the real render (a part reading a missing context throws). Popover content is not probed
+ * (its contexts are cleared there). Browser: a no-op.
+ */
+export function probeSlots(values, content) {
+    const previous = slotProbing;
+    slotProbing = true;
+    // Effects the probed children create are inert (their run is a no-op; server effects run once, in the real render).
+    const wrap = _wrapEffects(inert);
+    try {
+        _rUnrecorded(() => untrack(() => createRoot((dispose) => {
+            try {
+                provideAll(values, 0, content);
+            }
+            catch {
+                // A part that throws without the real render's surroundings: nothing more is marked; the real render that
+                // follows reports a genuine error.
+            }
+            finally {
+                dispose();
+            }
+        })));
+    }
+    finally {
+        _wrapEffects(wrap);
+        slotProbing = previous;
+    }
+}
+const noop = () => { };
+const inert = () => noop;
+/** Provides `values` from `i` on (nested `provide`s), then walks the content. */
+function provideAll(values, i, content) {
+    if (i < values.length)
+        provide(values[i][0], values[i][1], () => provideAll(values, i + 1, content));
+    else
+        _probeTree(content);
+}
+/** Server: reactive ids (`idSignal`) are registered per render id scope (`utils/id.ts`). Browser: the constant `false`. */
+export const idScoping = true;
+const scopedIds = new WeakMap();
+/**
+ * Server: the `idSignal` registry of the current render (`withIdScope`: the router opens one per request), or undefined
+ * outside any scope (process-wide `rvs` ids: `utils/id.ts` keeps its module map). Id strings restart per scope, so
+ * concurrent streaming renders share them; one registry per scope keeps a `mergeIds` of request B from changing request
+ * A's ids. Held weakly by the scope object: dropped with the render.
+ */
+export function scopedIdUpdaters() {
+    const scope = _idScope();
+    if (!scope)
+        return undefined;
+    let map = scopedIds.get(scope);
+    if (!map)
+        scopedIds.set(scope, (map = new Map()));
+    return map;
+}
+/**
+ * DOM-backed loader data (DOM-DATA, `resume: { domData: true }` servers): a built collection row renders `item` (the
+ * node's `value`, the user's data object) although its `For` iterates keys. `@rivetjs/runtime/server-resume` installs the
+ * hook only in domData builds (`Symbol.for("rivet.domRowItem")`): the row then registers that object, so the item's
+ * strings the row shows as an element's whole text / a plain attribute travel as DOM paths. Elsewhere: nothing.
+ */
+const DOM_ROW_ITEM = Symbol.for("rivet.domRowItem");
+export function domRowItem(item) {
+    globalThis[DOM_ROW_ITEM]?.(item);
+}

package/collections/table.d.ts

@@ -0,0 +1,114 @@
+import { GridCollection, type GridNode, type IGridCollection } from "./grid.js";
+import type { CollectionElement, Key, LinkDOMProps, LoadingState, Node, Rendered, SelectionMode, SortDescriptor, SortDirection } from "./types.js";
+export interface ITableCollection<T> extends IGridCollection<T> {
+    /** A list of header row nodes in the table (one per tier of nested columns). */
+    headerRows: GridNode<T>[];
+    /** A list of (leaf) column nodes in the table. */
+    columns: GridNode<T>[];
+    /** Column keys that serve as the row header. */
+    rowHeaderColumnKeys: Set<Key>;
+    /** The node that makes up the header of the table. */
+    head?: GridNode<T>;
+    /** The node that makes up the body of the table. */
+    body: GridNode<T>;
+}
+export interface TableCollectionOptions {
+    showSelectionCheckboxes?: boolean | undefined;
+    showDragButtons?: boolean | undefined;
+}
+export declare const ROW_HEADER_COLUMN_KEY = "row-header-column-$selection";
+export declare const ROW_HEADER_COLUMN_KEY_DRAG = "row-header-column-$drag";
+/** @private Build the header rows from (leaf) columns and their ancestors. */
+export declare function buildHeaderRows<T>(keyMap: Map<Key, GridNode<T>>, columnNodes: GridNode<T>[]): GridNode<T>[];
+export declare class TableCollection<T> extends GridCollection<T> implements ITableCollection<T> {
+    headerRows: GridNode<T>[];
+    columns: GridNode<T>[];
+    rowHeaderColumnKeys: Set<Key>;
+    body: GridNode<T>;
+    _size: number;
+    constructor(nodes: Iterable<GridNode<T>>, _prev?: ITableCollection<T> | null, opts?: TableCollectionOptions);
+    [Symbol.iterator](): IterableIterator<GridNode<T>>;
+    get size(): number;
+    getKeys(): IterableIterator<Key>;
+    getKeyBefore(key: Key): Key | null;
+    getKeyAfter(key: Key): Key | null;
+    getFirstKey(): Key | null;
+    getLastKey(): Key | null;
+    getItem(key: Key): GridNode<T> | null;
+    at(idx: number): GridNode<T> | null;
+    getChildren(key: Key): Iterable<GridNode<T>>;
+    getTextValue(key: Key): string;
+}
+/** Builder context shared by TableHeader / Column / Row (react-stately `CollectionBuilderContext`). */
+export interface TableBuilderContext<T> {
+    showSelectionCheckboxes: boolean;
+    showDragButtons: boolean;
+    selectionMode: SelectionMode;
+    columns: Node<T>[];
+}
+/** Context for building a table collection (`useTableState`'s memoized context). */
+export declare function tableBuilderContext<T>(options?: {
+    showSelectionCheckboxes?: boolean;
+    showDragButtons?: boolean;
+    selectionMode?: SelectionMode;
+}): TableBuilderContext<T>;
+export type ColumnStaticSize = number | `${number}` | `${number}%`;
+export type ColumnDynamicSize = `${number}fr`;
+export type ColumnSize = ColumnStaticSize | ColumnDynamicSize;
+export interface ColumnProps<T> {
+    key?: Key | undefined;
+    title?: Rendered;
+    children?: Rendered | CollectionElement<T> | CollectionElement<T>[];
+    childColumns?: T[] | undefined;
+    width?: ColumnSize | null | undefined;
+    minWidth?: ColumnStaticSize | null | undefined;
+    maxWidth?: ColumnStaticSize | null | undefined;
+    defaultWidth?: ColumnSize | null | undefined;
+    allowsResizing?: boolean | undefined;
+    allowsSorting?: boolean | undefined;
+    isRowHeader?: boolean | undefined;
+    textValue?: string | undefined;
+    "aria-label"?: string | undefined;
+    [prop: string]: unknown;
+}
+export interface TableHeaderProps<T> {
+    key?: Key | undefined;
+    columns?: readonly T[] | undefined;
+    children: CollectionElement<T> | CollectionElement<T>[] | ((item: T) => CollectionElement<T>);
+}
+export interface TableBodyProps<T> {
+    key?: Key | undefined;
+    children: CollectionElement<T> | CollectionElement<T>[] | ((item: T) => CollectionElement<T>);
+    items?: Iterable<T> | undefined;
+    loadingState?: LoadingState | undefined;
+    onLoadMore?: (() => unknown) | undefined;
+}
+export interface RowProps<T> extends LinkDOMProps {
+    key?: Key | undefined;
+    UNSTABLE_childItems?: Iterable<T> | undefined;
+    children: CollectionElement<T> | CollectionElement<T>[] | ((columnKey: Key) => CollectionElement<T>);
+    textValue?: string | undefined;
+    "aria-label"?: string | undefined;
+    [prop: string]: unknown;
+}
+export interface CellProps {
+    key?: Key | undefined;
+    children?: Rendered;
+    textValue?: string | undefined;
+    colSpan?: number | undefined;
+    "aria-label"?: string | undefined;
+    [prop: string]: unknown;
+}
+export declare const TableHeader: <T>(props: TableHeaderProps<T>) => CollectionElement<T, TableHeaderProps<T>>;
+export declare const TableBody: <T>(props: TableBodyProps<T>) => CollectionElement<T, TableBodyProps<T>>;
+export declare const Column: <T>(props: ColumnProps<T>) => CollectionElement<T, ColumnProps<T>>;
+export declare const Row: <T>(props: RowProps<T>) => CollectionElement<T, RowProps<T>>;
+export declare const Cell: (props: CellProps) => CollectionElement<unknown, CellProps>;
+export declare const OPPOSITE_SORT_DIRECTION: Readonly<Record<SortDirection, SortDirection>>;
+/**
+ * The descriptor `useTableState().sort(columnKey, direction?)` passes to `onSortChange`: the given
+ * direction, else the opposite of the current one for the same column, else ascending.
+ */
+export declare function nextSortDescriptor(current: SortDescriptor | null | undefined, column: Key, direction?: SortDirection): SortDescriptor;
+/** `aria-sort` value of a column under `descriptor` ("none" for sortable, unsorted columns). */
+export declare function ariaSort(descriptor: SortDescriptor | null | undefined, column: Key, allowsSorting?: boolean): "ascending" | "descending" | "none" | undefined;