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

package/compare/index.d.ts

@@ -0,0 +1,58 @@
+import type { Content } from "@rivetjs/runtime/jsx-runtime";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import { type CompareState, type CompareStateOptions } from "./behaviour.js";
+export { COMPARE_DURATION, COMPARE_FRICTION, COMPARE_KEYS, compareDragEnd, comparePosition, compareSetValue, compareValue, compareValueAt, compareValueText, createCompareState, isCompareDisabled, type CompareMotionOptions, type CompareOrientation, type CompareState, type CompareStateOptions, } from "./behaviour.js";
+/** The compare state of the nearest `Compare` (null outside one). */
+export declare const CompareContext: import("@rivetjs/reactivity").Context<CompareState | null>;
+type Style = Record<string, string | number | undefined>;
+export interface CompareProps extends Omit<CompareStateOptions, "direction" | "locale">, GlobalDOMAttributes<HTMLDivElement> {
+    /** A state from `createCompareState` (else one is created from the props). */
+    state?: CompareState;
+    id?: string;
+    /** @default "rv-Compare" */
+    class?: string;
+    /** Extra inline style (the behaviour styles win). */
+    style?: Style;
+    /** The layers and the handle. */
+    children?: Content;
+}
+/** Root: provides the state to the parts; with `dragAnywhere` a press on the surface jumps there and drags. */
+export declare function Compare(props: CompareProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+export interface CompareLayerProps extends GlobalDOMAttributes<HTMLDivElement> {
+    id?: string;
+    /** @default "rv-CompareBefore" / "rv-CompareAfter" */
+    class?: string;
+    style?: Style;
+    children?: Content;
+}
+/** The "before" layer: in flow (it sizes the compare), shown on the start side of the divider. */
+export declare function CompareBefore(props: CompareLayerProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** The "after" layer: absolutely stacked over the before layer, clipped to the end side of the divider (inline clip-path). */
+export declare function CompareAfter(props: CompareLayerProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+export interface CompareHandleProps extends GlobalDOMAttributes<HTMLDivElement> {
+    id?: string;
+    /** @default "rv-CompareHandle" */
+    class?: string;
+    style?: Style;
+    /** @default "Comparison position" */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    /** Overrides the default percent text (a string, or an accessor of the value). */
+    "aria-valuetext"?: string | ((value: number) => string);
+    /** Runs after the handle's own key handling (native `KeyboardEvent`). */
+    onKeyDown?: (event: KeyboardEvent) => void;
+    /** The handle's look (divider line, grip). */
+    children?: Content;
+}
+/** The divider handle: an ARIA slider (focusable, keys) that a pointer drags. */
+export declare function CompareHandle(props: CompareHandleProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement | null;
+export interface CompareDividerProps extends GlobalDOMAttributes<HTMLSpanElement> {
+    id?: string;
+    /** @default "rv-CompareDivider" */
+    class?: string;
+    style?: Style;
+}
+export declare function CompareDivider(props: CompareDividerProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** The divider position (percent) of the nearest `Compare`, as an accessor (the settle position while it animates). */
+export declare function useComparePosition(): () => number;

package/compare/index.jsx

@@ -0,0 +1,129 @@
+// Rivet-authored (no upstream: React Aria / React Aria Components / Angular CDK have no compare slider): headless
+// before / after comparison — `Compare` (root), `CompareBefore` / `CompareAfter` (the two overlapped layers),
+// `CompareHandle` (the draggable divider, an ARIA slider) and `CompareDivider` (a decorative line for inside the handle).
+// Behaviour + motion: `./behaviour.ts` (house motion `@rivetjs/cdk/motion`, embla-carousel 8.6.0 physics, MIT,
+// © David Jerleke).
+// - DOM: root `div[data-rv-compare]` (`rv-Compare`; inline `position: relative; overflow: hidden`,
+//   `--rv-compare-position`; `data-orientation`, `data-dragging`, `data-moving` while a settle animates, `data-disabled`)
+//   > `div` before layer (`rv-CompareBefore`, in flow: it sizes the root) + `div` after layer (`rv-CompareAfter`;
+//   inline `position: absolute; inset: 0; clip-path: inset(…)`) + `div[role=slider][data-rv-compare-handle]`
+//   (`rv-CompareHandle`; inline position / translate / `touch-action: none`; `aria-valuenow` / min / max / valuetext,
+//   `aria-orientation`, `aria-label` default "Comparison position"; `data-focus-visible`, `data-focused`, `data-hovered`,
+//   `data-dragging`). The stylesheet sizes the handle (its cross-axis width = the hit area) and draws its children.
+// - Resumable: state = plain signals (`createCompareState`, provided by `CompareContext`), handlers are inline arrows
+//   calling `./behaviour.ts`; nothing runs before the first pointer / key event (the root carries `preload="visible"`:
+//   the handler chunks are fetched while visible, so a cold drag follows at once).
+import { untrack } from "@rivetjs/reactivity";
+import { Provider } from "@rivetjs/runtime/dom";
+import { resumableContext } from "@rivetjs/runtime/resume-format";
+import { createContext, useContext } from "@rivetjs/reactivity";
+import { useLocale } from "../i18n/index.js";
+import { dataBool, focusStateIn, hoverStateOver } from "../utils/data-attrs.jsx";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { liveOptions } from "../utils/live.jsx";
+import { COMPARE_KEYS, compareAfterStyle, compareDispose, compareHandleStyle, compareKeyDown, comparePointerDown, comparePosition, compareRootStyle, compareValue, compareValueText, createCompareState, isCompareDisabled, } from "./behaviour.js";
+export { COMPARE_DURATION, COMPARE_FRICTION, COMPARE_KEYS, compareDragEnd, comparePosition, compareSetValue, compareValue, compareValueAt, compareValueText, createCompareState, isCompareDisabled, } from "./behaviour.js";
+/** The compare state of the nearest `Compare` (null outside one). */
+export const CompareContext = resumableContext(createContext(null, { id: "rv-compare" }));
+const ROOT_OWNED = ["onPointerDown", "style"];
+/** Root: provides the state to the parts; with `dragAnywhere` a press on the surface jumps there and drags. */
+export function Compare(props) {
+    const { locale, direction } = useLocale();
+    // Live props: `value` (controlled) / `isDisabled` become accessors at the boundary; the rest is read once.
+    const merged = liveOptions(props, ["isDisabled"], ["value"]);
+    return untrack(() => compareRoot(merged, locale, direction));
+}
+function compareRoot(props, locale, direction) {
+    const state = props.state ??
+        createCompareState({
+            value: props.value,
+            defaultValue: props.defaultValue,
+            onChange: props.onChange,
+            onChangeEnd: props.onChangeEnd,
+            orientation: props.orientation,
+            isDisabled: props.isDisabled,
+            step: props.step,
+            pageStep: props.pageStep,
+            dragAnywhere: props.dragAnywhere,
+            animation: props.animation,
+            direction: props.dir === "rtl" ? "rtl" : props.dir === "ltr" ? "ltr" : direction,
+            locale,
+        });
+    const { id, children } = props;
+    const className = props.class ?? "rv-Compare";
+    const userStyle = props.style;
+    const userPointerDown = props.onPointerDown;
+    const dom = globalDOMProps(props, ROOT_OWNED);
+    return (<Provider token={CompareContext} value={state}>
+      <div {...dom} id={id} class={className} data-rv-compare="" data-orientation={state.orientation} data-dragging={dataBool(state.dragging())} data-moving={dataBool(state.position() !== null)} data-disabled={dataBool(isCompareDisabled(state))} style={{ ...userStyle, ...compareRootStyle(state) }} preload="visible" onPointerDown={(event) => {
+            comparePointerDown(event, state, true);
+            userPointerDown?.(event);
+        }}>
+        {children}
+      </div>
+    </Provider>);
+}
+/** The "before" layer: in flow (it sizes the compare), shown on the start side of the divider. */
+export function CompareBefore(props) {
+    const state = useContext(CompareContext);
+    const { id, children } = props;
+    const className = props.class ?? "rv-CompareBefore";
+    const style = props.style;
+    const dom = globalDOMProps(props, ["style"]);
+    return (<div {...dom} id={id} class={className} data-rv-compare-before="" data-orientation={state?.orientation} style={style}>
+      {children}
+    </div>);
+}
+/** The "after" layer: absolutely stacked over the before layer, clipped to the end side of the divider (inline clip-path). */
+export function CompareAfter(props) {
+    const state = useContext(CompareContext);
+    const { id, children } = props;
+    const className = props.class ?? "rv-CompareAfter";
+    const style = props.style;
+    const dom = globalDOMProps(props, ["style"]);
+    return (<div {...dom} id={id} class={className} data-rv-compare-after="" data-orientation={state?.orientation} style={state ? { ...style, ...compareAfterStyle(state) } : style}>
+      {children}
+    </div>);
+}
+const HANDLE_OWNED = ["onPointerDown", "onPointerOver", "onKeyDown", "style"];
+/** The divider handle: an ARIA slider (focusable, keys) that a pointer drags. */
+export function CompareHandle(props) {
+    const state = useContext(CompareContext);
+    const { id, children } = props;
+    const className = props.class ?? "rv-CompareHandle";
+    const style = props.style;
+    const labelledBy = props["aria-labelledby"];
+    const label = props["aria-label"] ?? (labelledBy ? undefined : "Comparison position");
+    const describedBy = props["aria-describedby"];
+    const valueText = props["aria-valuetext"];
+    const userDown = props.onPointerDown;
+    const userOver = props.onPointerOver;
+    const userKey = props.onKeyDown;
+    const dom = globalDOMProps(props, HANDLE_OWNED);
+    const interaction = {};
+    if (!state)
+        return null;
+    return (<div {...dom} id={id} class={className} role="slider" tabIndex={isCompareDisabled(state) ? undefined : 0} aria-label={label} aria-labelledby={labelledBy} aria-describedby={describedBy} aria-orientation={state.orientation} aria-valuemin={0} aria-valuemax={100} aria-valuenow={Math.round(compareValue(state))} aria-valuetext={typeof valueText === "function" ? valueText(compareValue(state)) : (valueText ?? compareValueText(state))} aria-disabled={isCompareDisabled(state) ? "true" : undefined} data-rv-compare-handle="" data-rk={COMPARE_KEYS} data-orientation={state.orientation} data-dragging={dataBool(state.dragging())} data-disabled={dataBool(isCompareDisabled(state))} style={{ ...style, ...compareHandleStyle(state) }} onPointerDown={(event) => {
+            comparePointerDown(event, state, false);
+            userDown?.(event);
+        }} onPointerOver={(event) => {
+            hoverStateOver(interaction, event);
+            userOver?.(event);
+        }} onFocusIn={(event) => focusStateIn(interaction, event)} onKeyDown={(event) => {
+            compareKeyDown(event, state);
+            userKey?.(event);
+        }}>
+      {children}
+    </div>);
+}
+export function CompareDivider(props) {
+    const state = useContext(CompareContext);
+    const className = props.class ?? "rv-CompareDivider";
+    const dom = globalDOMProps(props, ["style"]);
+    return (<span {...dom} id={props.id} class={className} aria-hidden="true" data-rv-compare-divider="" data-orientation={state?.orientation} style={props.style}/>);
+}
+/** The divider position (percent) of the nearest `Compare`, as an accessor (the settle position while it animates). */
+export function useComparePosition() {
+    const state = useContext(CompareContext);
+    return () => (state ? comparePosition(state) : 50);
+}

package/data/async-list.d.ts

@@ -0,0 +1,78 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { Key, LoadingState, Selection, SortDescriptor } from "../collections/types.js";
+import { type ListActions } from "./list-data.jsx";
+export interface AsyncListOptions<T, C> {
+    /** The keys for the initially selected items. */
+    initialSelectedKeys?: "all" | Iterable<Key> | undefined;
+    /** The initial sort descriptor. */
+    initialSortDescriptor?: SortDescriptor | undefined;
+    /** The initial filter text. */
+    initialFilterText?: string | undefined;
+    /** A function that returns a unique key for an item object. Default `item.id || item.key`. */
+    getKey?: ((item: T) => Key) | undefined;
+    /** A function that loads the data for the items in the list. */
+    load: AsyncListLoadFunction<T, C>;
+    /** An optional function that performs sorting. If not provided, `sortDescriptor` is passed to `load`. */
+    sort?: AsyncListLoadFunction<T, C, AsyncListLoadOptions<T, C> & {
+        sortDescriptor: SortDescriptor;
+    }> | undefined;
+}
+export type AsyncListLoadFunction<T, C, S extends AsyncListLoadOptions<T, C> = AsyncListLoadOptions<T, C>> = (state: S) => AsyncListStateUpdate<T, C> | Promise<AsyncListStateUpdate<T, C>>;
+export interface AsyncListLoadOptions<T, C> {
+    /** The items currently in the list. */
+    items: T[];
+    /** The keys of the currently selected items in the list. */
+    selectedKeys: Selection;
+    /** The current sort descriptor for the list. */
+    sortDescriptor?: SortDescriptor | undefined;
+    /** An abort signal used to notify the load function that the request has been aborted. */
+    signal: AbortSignal;
+    /** The pagination cursor returned from the last page load. */
+    cursor?: C | undefined;
+    /** The current filter text used to perform server side filtering. */
+    filterText?: string | undefined;
+    /** The current loading state of the list. */
+    loadingState?: LoadingState | undefined;
+}
+export interface AsyncListStateUpdate<T, C> {
+    /** The new items to append to the list. */
+    items: Iterable<T>;
+    /** The keys to add to the selection. */
+    selectedKeys?: Iterable<Key> | "all" | undefined;
+    /** The sort descriptor to set. */
+    sortDescriptor?: SortDescriptor | undefined;
+    /** The pagination cursor to be used for the next page load. */
+    cursor?: C | undefined;
+    /** The updated filter text for the list. */
+    filterText?: string | undefined;
+}
+export interface AsyncListData<T> extends ListActions<T> {
+    /** The items in the list. Reads state. */
+    readonly items: () => T[];
+    /** The keys of the currently selected items in the list (two-way signal). */
+    readonly selectedKeys: Signal<Selection>;
+    /** The current filter text. Reads state. */
+    readonly filterText: () => string;
+    /** Gets an item from the list by key. */
+    getItem(key: Key): T | undefined;
+    /** Whether data is currently being loaded. Reads state. */
+    readonly isLoading: () => boolean;
+    /** If loading data failed, then this contains the error that occurred. Reads state. */
+    readonly error: () => Error | undefined;
+    /** The current sort descriptor for the list. Reads state. */
+    readonly sortDescriptor: () => SortDescriptor | undefined;
+    /** The current loading state for the list. Reads state. */
+    readonly loadingState: () => LoadingState;
+    /** Reloads the data in the list. */
+    reload(): void;
+    /** Loads the next page of data in the list. */
+    loadMore(): void;
+    /** Triggers sorting for the list. */
+    sort(descriptor: SortDescriptor): void;
+}
+/**
+ * Manages state for an immutable async loaded list data structure, and provides convenience methods
+ * to update the data over time. Manages loading and error states, pagination, and sorting
+ * (react-stately `useAsyncList`).
+ */
+export declare function createAsyncList<T, C = string>(options: AsyncListOptions<T, C>): AsyncListData<T>;

package/data/async-list.jsx

@@ -0,0 +1,257 @@
+// Ported from @react-stately/data (useAsyncList.ts), Apache-2.0, © Adobe.
+//
+// Rivet:
+// - `useAsyncList` → `createAsyncList` (wave-2 decision 7). Returns a plain object of signals +
+//   arrow functions (resumable; `.tsx` so the arrows are R2 symbols). Reactive members are
+//   accessors: `items()`, `isLoading()`, `loadingState()`, `error()`, `sortDescriptor()`,
+//   `filterText()`; `selectedKeys` is a two-way `Signal<Selection>`.
+// - The reducer state is one signal (`data`); the in-flight AbortController lives outside it, in a
+//   browser-only WeakMap keyed by that signal (controllers do not serialize).
+// - React's mount effect (initial `loading` fetch) is a `clientEffect` when called under an owner
+//   (component body: runs once in the browser after mount, also on a resumed page), else it runs
+//   at once (no owner = no mount to wait for). A server render shows the initial `loading` state, as react-aria's SSR does.
+// - `load` / `sort` / `getKey` options must be inline arrows or local functions (captured).
+// - react-stately's methods read the reducer state of the current render (a closure): calls made
+//   in one synchronous task (one event handler) all see the state as it was when the task started.
+//   Rivet keeps that: `rendered()` snapshots the state on first read and drops the snapshot in a
+//   microtask, so e.g. three `loadMore()` calls in one handler each start (and the reducer aborts
+//   the duplicates), as upstream.
+import { batch, computed, getOwner, signal, untrack, _regionState } from "@rivetjs/reactivity";
+import { clientEffect } from "@rivetjs/runtime/dom";
+import { createListActions } from "./list-data.jsx";
+// In-flight AbortControllers per list (browser-only, never serialized).
+const controllers = new WeakMap();
+// A const holder, not a `let`: resume chunks import module bindings read-only (an imported `let` cannot be incremented).
+const requests = { next: 0 };
+function abortRequest(owner, request, reason) {
+    if (request == null)
+        return;
+    controllers.get(owner)?.get(request)?.abort(reason);
+}
+function reducer(owner, data, action) {
+    let selectedKeys;
+    switch (data.state) {
+        case "idle":
+        case "error":
+            switch (action.type) {
+                case "loading":
+                case "loadingMore":
+                case "sorting":
+                case "filtering":
+                    return {
+                        ...data,
+                        filterText: action.filterText ?? data.filterText,
+                        state: action.type,
+                        // Reset items to an empty list if loading, but not when sorting.
+                        items: action.type === "loading" ? [] : data.items,
+                        sortDescriptor: action.sortDescriptor ?? data.sortDescriptor,
+                        request: action.request,
+                    };
+                case "update":
+                    return { ...data, ...action.updater?.(data) };
+                case "success":
+                case "error":
+                    return data;
+                default:
+                    throw new Error(`Invalid action "${action.type}" in state "${data.state}"`);
+            }
+        case "loading":
+        case "sorting":
+        case "filtering":
+            switch (action.type) {
+                case "success":
+                    // Ignore if there is a newer request in state: multiple requests were going at once and we
+                    // only take the latest result.
+                    if (action.request !== data.request)
+                        return data;
+                    selectedKeys = action.selectedKeys ?? data.selectedKeys;
+                    return {
+                        ...data,
+                        filterText: action.filterText ?? data.filterText,
+                        state: "idle",
+                        items: [...(action.items ?? [])],
+                        selectedKeys: selectedKeys === "all" ? "all" : new Set(selectedKeys),
+                        sortDescriptor: action.sortDescriptor ?? data.sortDescriptor,
+                        request: undefined,
+                        cursor: action.cursor,
+                    };
+                case "error":
+                    if (action.request !== data.request)
+                        return data;
+                    return { ...data, state: "error", error: action.error, request: undefined };
+                case "loading":
+                case "loadingMore":
+                case "sorting":
+                case "filtering":
+                    // Already loading, and another load was triggered at the same time: abort the previous
+                    // load and start a new one.
+                    abortRequest(owner, data.request, "aborting current load and starting new one");
+                    return {
+                        ...data,
+                        filterText: action.filterText ?? data.filterText,
+                        state: action.type,
+                        // Reset items to an empty list if loading, but not when sorting.
+                        items: action.type === "loading" ? [] : data.items,
+                        request: action.request,
+                    };
+                case "update":
+                    // An update happened while loading (e.g. selection changed): update without aborting.
+                    return { ...data, ...action.updater?.(data) };
+                default:
+                    throw new Error(`Invalid action "${action.type}" in state "${data.state}"`);
+            }
+        case "loadingMore":
+            switch (action.type) {
+                case "success":
+                    selectedKeys = data.selectedKeys === "all" || action.selectedKeys === "all" ? "all" : new Set([...data.selectedKeys, ...(action.selectedKeys ?? [])]);
+                    // Append the new items.
+                    return {
+                        ...data,
+                        state: "idle",
+                        items: [...data.items, ...(action.items ?? [])],
+                        selectedKeys: selectedKeys,
+                        sortDescriptor: action.sortDescriptor ?? data.sortDescriptor,
+                        request: undefined,
+                        cursor: action.cursor,
+                    };
+                case "error":
+                    if (action.request !== data.request)
+                        return data;
+                    return { ...data, state: "error", error: action.error };
+                case "loading":
+                case "sorting":
+                case "filtering":
+                    // Already loading more, and another load was triggered: abort the load more, start anew.
+                    abortRequest(owner, data.request);
+                    return {
+                        ...data,
+                        filterText: action.filterText ?? data.filterText,
+                        state: action.type,
+                        // Reset items to an empty list if loading, but not when sorting.
+                        items: action.type === "loading" ? [] : data.items,
+                        request: action.request,
+                    };
+                case "loadingMore":
+                    // A duplicate load more (the cursor has not been updated): abort the new one and keep
+                    // the current request.
+                    abortRequest(owner, action.request);
+                    return data;
+                case "update":
+                    return { ...data, ...action.updater?.(data) };
+                default:
+                    throw new Error(`Invalid action "${action.type}" in state "${data.state}"`);
+            }
+        default:
+            throw new Error(`Invalid state "${data.state}"`);
+    }
+}
+const defaultAsyncKey = (item) => item.id || item.key;
+/**
+ * Manages state for an immutable async loaded list data structure, and provides convenience methods
+ * to update the data over time. Manages loading and error states, pagination, and sorting
+ * (react-stately `useAsyncList`).
+ */
+export function createAsyncList(options) {
+    return _regionState(() => {
+        const { load, sort, initialSelectedKeys, initialSortDescriptor, initialFilterText = "" } = options;
+        // Resumable: a module-level default is not a serializable capture; the fallback is an object-literal arrow (a resume symbol).
+        const userKey = options.getKey;
+        const keys = { get: (item) => (userKey ? userKey(item) : defaultAsyncKey(item)) };
+        const getKey = keys.get;
+        const data = signal({
+            state: "idle",
+            error: undefined,
+            items: [],
+            selectedKeys: initialSelectedKeys === "all" ? "all" : new Set(initialSelectedKeys),
+            sortDescriptor: initialSortDescriptor,
+            filterText: initialFilterText,
+        });
+        // `selectedKeys` is its own signal (two-way, like createListData); the reducer state mirrors it.
+        const selectedKeys = signal(untrack(data).selectedKeys);
+        const read = () => ({ ...untrack(data), selectedKeys: untrack(selectedKeys) });
+        // The "current render" state (see header): one snapshot per synchronous task.
+        let snapshot;
+        const rendered = () => {
+            if (!snapshot) {
+                snapshot = read();
+                queueMicrotask(() => (snapshot = undefined));
+            }
+            return snapshot;
+        };
+        const dispatch = (action) => batch(() => {
+            const prev = read();
+            const next = reducer(data, prev, action);
+            if (next === prev)
+                return;
+            data.set(next);
+            if (next.selectedKeys !== prev.selectedKeys)
+                selectedKeys.set(next.selectedKeys);
+        });
+        const dispatchFetch = async (action, fn) => {
+            const abortController = new AbortController();
+            const request = ++requests.next;
+            let map = controllers.get(data);
+            if (!map)
+                controllers.set(data, (map = new Map()));
+            map.set(request, abortController);
+            const current = rendered();
+            try {
+                dispatch({ ...action, request });
+                const previousFilterText = action.filterText ?? current.filterText;
+                const response = await fn({
+                    items: current.items.slice(),
+                    selectedKeys: current.selectedKeys,
+                    sortDescriptor: action.sortDescriptor ?? current.sortDescriptor,
+                    signal: abortController.signal,
+                    cursor: action.type === "loadingMore" ? current.cursor : undefined,
+                    filterText: previousFilterText,
+                    loadingState: current.state,
+                });
+                const filterText = response.filterText ?? previousFilterText;
+                dispatch({ type: "success", ...response, request });
+                // Fetch a new filtered list if filterText was updated by the `load` response rather than
+                // setFilterText — only when not aborted (another filter action may have started meanwhile).
+                if (filterText && filterText !== previousFilterText && !abortController.signal.aborted)
+                    void dispatchFetch({ type: "filtering", filterText }, load);
+            }
+            catch (e) {
+                dispatch({ type: "error", error: e, request });
+            }
+            finally {
+                map.delete(request);
+            }
+        };
+        // Resumable: the actions' dispatch is an object-literal arrow (a bare argument arrow is not a resume symbol).
+        const io = { update: (fn) => dispatch({ type: "update", updater: fn }) };
+        const isLoading = computed(() => {
+            const state = data().state;
+            return state === "loading" || state === "loadingMore" || state === "sorting" || state === "filtering";
+        });
+        const initial = () => void dispatchFetch({ type: "loading" }, load);
+        if (getOwner())
+            clientEffect(() => untrack(initial));
+        else
+            initial();
+        return {
+            items: () => data().items,
+            selectedKeys,
+            sortDescriptor: () => data().sortDescriptor,
+            isLoading,
+            loadingState: () => data().state,
+            error: () => data().error,
+            filterText: () => data().filterText,
+            getItem: (key) => data().items.find((item) => getKey(item) === key),
+            reload: () => void dispatchFetch({ type: "loading" }, load),
+            loadMore: () => {
+                const current = rendered();
+                // Ignore if already loading more or if performing server side filtering.
+                if (current.state === "loading" || current.state === "loadingMore" || current.state === "filtering" || current.cursor == null)
+                    return;
+                void dispatchFetch({ type: "loadingMore" }, load);
+            },
+            sort: (sortDescriptor) => void dispatchFetch({ type: "sorting", sortDescriptor }, (sort || load)),
+            ...createListActions({ ...options, getKey, cursor: () => untrack(data).cursor }, io.update),
+            setFilterText: (filterText) => void dispatchFetch({ type: "filtering", filterText }, load),
+        };
+    });
+}

package/data/index.d.ts

@@ -0,0 +1,3 @@
+export { createListData, createListActions, listDataState, type ListOptions, type ListData, type ListActions, type ListState as ListDataState, } from "./list-data.jsx";
+export { createTreeData, type TreeOptions, type TreeData, type TreeNode } from "./tree-data.jsx";
+export { createAsyncList, type AsyncListOptions, type AsyncListData, type AsyncListLoadFunction, type AsyncListLoadOptions, type AsyncListStateUpdate, } from "./async-list.jsx";

package/data/index.jsx

@@ -0,0 +1,6 @@
+// @rivetjs/cdk/data — react-stately data hooks (@react-stately/data, Apache-2.0, © Adobe) as
+// resumable factories: useListData → createListData, useTreeData → createTreeData, useAsyncList →
+// createAsyncList. `.tsx` (no JSX) so the returned objects' arrow functions are resume symbols.
+export { createListData, createListActions, listDataState, } from "./list-data.jsx";
+export { createTreeData } from "./tree-data.jsx";
+export { createAsyncList, } from "./async-list.jsx";

package/data/list-data.d.ts

@@ -0,0 +1,88 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { Key, Selection } from "../collections/types.js";
+export interface ListOptions<T> {
+    /** Initial items in the list. */
+    initialItems?: T[] | undefined;
+    /** The keys for the initially selected items. */
+    initialSelectedKeys?: "all" | Iterable<Key> | undefined;
+    /** The initial text to filter the list by. */
+    initialFilterText?: string | undefined;
+    /** A function that returns a unique key for an item object. Default `item.id ?? item.key`. */
+    getKey?: ((item: T) => Key) | undefined;
+    /** A function that returns whether a item matches the current filter text. */
+    filter?: ((item: T, filterText: string) => boolean) | undefined;
+}
+/** The list operations shared by `createListData` and `createAsyncList` (react-stately `createListActions` result). */
+export interface ListActions<T> {
+    /** Sets the selected keys. */
+    setSelectedKeys(keys: Selection): void;
+    /** Adds the given keys to the current selected keys. */
+    addKeysToSelection(keys: Selection): void;
+    /** Removes the given keys from the current selected keys. */
+    removeKeysFromSelection(keys: Selection): void;
+    /** Sets the filter text. */
+    setFilterText(filterText: string): void;
+    /** Inserts items into the list at the given index. */
+    insert(index: number, ...values: T[]): void;
+    /** Inserts items into the list before the item at the given key. */
+    insertBefore(key: Key, ...values: T[]): void;
+    /** Inserts items into the list after the item at the given key. */
+    insertAfter(key: Key, ...values: T[]): void;
+    /** Appends items to the list. */
+    append(...values: T[]): void;
+    /** Prepends items to the list. */
+    prepend(...values: T[]): void;
+    /** Removes items from the list by their keys. */
+    remove(...keys: Key[]): void;
+    /** Removes all items from the list that are currently in the set of selected items. */
+    removeSelectedItems(): void;
+    /** Moves an item within the list. */
+    move(key: Key, toIndex: number): void;
+    /** Moves one or more items before a given key. */
+    moveBefore(key: Key, keys: Iterable<Key>): void;
+    /** Moves one or more items after a given key. */
+    moveAfter(key: Key, keys: Iterable<Key>): void;
+    /** Updates an item in the list (new value, or a function of the previous value). */
+    update(key: Key, newValue: T | ((prev: T) => T)): void;
+}
+export interface ListData<T> extends ListActions<T> {
+    /** The items in the list (filtered by `filterText` when a `filter` is given). Reads state. */
+    readonly items: () => T[];
+    /** The keys of the currently selected items in the list (two-way signal). */
+    readonly selectedKeys: Signal<Selection>;
+    /** The current filter text. Reads state. */
+    readonly filterText: () => string;
+    /** Gets an item from the (unfiltered) list by key. */
+    getItem(key: Key): T | undefined;
+}
+/** The plain state react-stately's list reducer works on. */
+export interface ListState<T> {
+    items: T[];
+    selectedKeys: Selection;
+    filterText: string;
+}
+/** The signals behind a list (`createListActions` reads and writes them). */
+export interface ListStore<T> {
+    readonly rawItems: Signal<T[]>;
+    readonly selectedKeys: Signal<Selection>;
+    readonly filterTextSignal: Signal<string>;
+}
+export interface CreateListOptions<T, C> extends ListOptions<T> {
+    /** The pagination cursor (async lists): read when the last item is removed. */
+    cursor?: (() => C | undefined) | undefined;
+}
+/** Snapshot of the list state (react-stately's `state`; reads the signals). */
+export declare function listStoreState<T>(store: ListStore<T>): ListState<T>;
+/** Applies a reducer step to the store: writes back the fields that changed (one batch). */
+export declare function dispatchList<T>(store: ListStore<T>, updater: (state: ListState<T>) => ListState<T>): void;
+/** The list operations over a dispatch function (react-stately `createListActions`). */
+export declare function createListActions<T, C>(opts: CreateListOptions<T, C>, dispatch: (updater: (state: ListState<T>) => ListState<T>) => void): ListActions<T>;
+/** Default item key: `item.id ?? item.key` (react-stately). */
+export declare const defaultGetKey: (item: any) => Key;
+/**
+ * Manages state for an immutable list data structure, and provides convenience methods to update
+ * the data over time (react-stately `useListData`).
+ */
+export declare function createListData<T>(options?: ListOptions<T>): ListData<T>;
+/** react-stately's `{...state}` snapshot of a list (items filtered). Reads state. */
+export declare function listDataState<T>(list: ListData<T>): ListState<T>;