@connextar/house 0.2.0 → 0.3.0

package/dist/ux/use-action.d.ts

@@ -0,0 +1,60 @@
+export interface ActionOptions<R> {
+    /**
+     * What to say when it works. A function gets the result, and may return
+     * nothing for "this one is not worth a toast".
+     */
+    success?: string | ((result: R) => string | null | undefined);
+    /** The heading when it fails; the thrown message becomes the detail. */
+    error?: string;
+    onSuccess?: (result: R) => void;
+    /**
+     * Runs *in addition* to the failure being reported — usually to put back
+     * whatever was changed ahead of the answer. Silencing the report is a
+     * separate decision, and a deliberate one: see `silent`.
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * Say nothing on failure. Only for a control that shows the refusal itself,
+     * in place. A rolled-back change with no explanation is the failure mode
+     * this whole layer exists to avoid.
+     */
+    silent?: boolean;
+}
+export interface Action<A extends unknown[], R> {
+    /**
+     * Run it. Never throws: a failure is reported and comes back as `undefined`,
+     * because the caller is an `onClick` and an unhandled rejection there is an
+     * error in the console and nothing on the screen.
+     */
+    run: (...args: A) => Promise<R | undefined>;
+    /** In flight. Feed this straight to a button's `loading`. */
+    pending: boolean;
+    /** The last failure's wording, for showing it in place rather than in a toast. */
+    error: string | null;
+}
+/**
+ * One asynchronous thing a control does, with the pending flag that control
+ * needs and the reporting it would otherwise repeat.
+ *
+ * Re-entry is refused rather than queued. Two clicks on **Pay** are one
+ * intention, and the second is almost always the person telling you the first
+ * one gave them nothing to look at — which is the very problem the `pending`
+ * flag fixes.
+ */
+export declare function useAction<A extends unknown[], R>(action: (...args: A) => Promise<R>, options?: ActionOptions<R>): Action<A, R>;
+export interface KeyedAction {
+    /** Run something for one row; a second run for the same row is refused. */
+    run: <R>(key: string, action: () => Promise<R>, options?: ActionOptions<R>) => Promise<R | undefined>;
+    isPending: (key: string) => boolean;
+    /** Any row busy at all — for disabling a whole toolbar. */
+    pending: boolean;
+    /** The busy rows, where a component would rather read the set itself. */
+    keys: ReadonlySet<string>;
+}
+/**
+ * The same, for a list where each row has its own button. Keeps a set of busy
+ * keys so one row's spinner does not disable the rest of the table — the
+ * commonest small cruelty in a list screen.
+ */
+export declare function useKeyedAction(defaults?: ActionOptions<unknown>): KeyedAction;
+//# sourceMappingURL=use-action.d.ts.map

package/dist/ux/use-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-action.d.ts","sourceRoot":"","sources":["../../src/ux/use-action.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAC9D,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,MAAM,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC;IAC5C;;;;OAIG;IACH,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC5C,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EAC9C,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAClC,OAAO,GAAE,aAAa,CAAC,CAAC,CAAM,GAC7B,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAyCd;AAED,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACtG,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACpC,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,GAAE,aAAa,CAAC,OAAO,CAAM,GAAG,WAAW,CAyCjF"}

package/dist/ux/use-action.js

@@ -0,0 +1,100 @@
+"use client";
+import * as React from "react";
+import { errorMessage } from "./errors.js";
+import { useActionReporter } from "./feedback.js";
+/**
+ * One asynchronous thing a control does, with the pending flag that control
+ * needs and the reporting it would otherwise repeat.
+ *
+ * Re-entry is refused rather than queued. Two clicks on **Pay** are one
+ * intention, and the second is almost always the person telling you the first
+ * one gave them nothing to look at — which is the very problem the `pending`
+ * flag fixes.
+ */
+export function useAction(action, options = {}) {
+    const report = useActionReporter();
+    const [pending, setPending] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    // The "latest ref" pattern: written after the render, so the asynchronous
+    // half always reads current values without any of these callbacks having to
+    // change identity — a callback that changes on every render is how a
+    // memoised row ends up re-rendering for nothing.
+    const latest = React.useRef({ action, options, report });
+    React.useEffect(() => {
+        latest.current = { action, options, report };
+    });
+    const inFlight = React.useRef(false);
+    const run = React.useCallback(async (...args) => {
+        if (inFlight.current)
+            return undefined;
+        inFlight.current = true;
+        setPending(true);
+        setError(null);
+        const { action: fn, options: opts, report: tell } = latest.current;
+        try {
+            const result = await fn(...args);
+            const message = typeof opts.success === "function" ? opts.success(result) : opts.success;
+            if (message)
+                tell({ tone: "success", title: message });
+            opts.onSuccess?.(result);
+            return result;
+        }
+        catch (thrown) {
+            const detail = errorMessage(thrown);
+            setError(detail);
+            opts.onError?.(thrown);
+            if (!opts.silent)
+                tell({ tone: "error", title: opts.error ?? "That didn't work", description: detail });
+            return undefined;
+        }
+        finally {
+            inFlight.current = false;
+            setPending(false);
+        }
+    }, []);
+    return { run, pending, error };
+}
+/**
+ * The same, for a list where each row has its own button. Keeps a set of busy
+ * keys so one row's spinner does not disable the rest of the table — the
+ * commonest small cruelty in a list screen.
+ */
+export function useKeyedAction(defaults = {}) {
+    const report = useActionReporter();
+    const [keys, setKeys] = React.useState(() => new Set());
+    const latest = React.useRef({ defaults, report });
+    React.useEffect(() => {
+        latest.current = { defaults, report };
+    });
+    const busy = React.useRef(new Set());
+    const run = React.useCallback(async (key, action, options) => {
+        if (busy.current.has(key))
+            return undefined;
+        busy.current.add(key);
+        setKeys(new Set(busy.current));
+        const { defaults: base, report: tell } = latest.current;
+        const opts = { ...base, ...options };
+        try {
+            const result = await action();
+            const message = typeof opts.success === "function" ? opts.success(result) : opts.success;
+            if (message)
+                tell({ tone: "success", title: message });
+            opts.onSuccess?.(result);
+            return result;
+        }
+        catch (thrown) {
+            opts.onError?.(thrown);
+            if (!opts.silent) {
+                tell({ tone: "error", title: opts.error ?? "That didn't work", description: errorMessage(thrown) });
+            }
+            return undefined;
+        }
+        finally {
+            busy.current.delete(key);
+            setKeys(new Set(busy.current));
+        }
+    }, []);
+    const isPending = React.useCallback((key) => keys.has(key), [keys]);
+    return { run, isPending, pending: keys.size > 0, keys };
+}
+//# sourceMappingURL=use-action.js.map

package/dist/ux/use-action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-action.js","sourceRoot":"","sources":["../../src/ux/use-action.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAsClD;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CACvB,MAAkC,EAClC,UAA4B,EAAE;IAE9B,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACnC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAE9D,0EAA0E;IAC1E,4EAA4E;IAC5E,qEAAqE;IACrE,iDAAiD;IACjD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACzD,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,MAAM,CAAC,OAAO,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAC/C,CAAC,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAErC,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,IAAO,EAA0B,EAAE;QACzE,IAAI,QAAQ,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QACvC,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;QACxB,UAAU,CAAC,IAAI,CAAC,CAAC;QACjB,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC;QACnE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YACjC,MAAM,OAAO,GAAG,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;YACzF,IAAI,OAAO;gBAAE,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;YACvD,IAAI,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC;YACzB,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,MAAM,EAAE,CAAC;YAChB,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;YACpC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACjB,IAAI,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,MAAM;gBAAE,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,kBAAkB,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC;YACxG,OAAO,SAAS,CAAC;QACnB,CAAC;gBAAS,CAAC;YACT,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAC;YACzB,UAAU,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AACjC,CAAC;AAYD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmC,EAAE;IAClE,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACnC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAsB,GAAG,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC;IAE7E,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAClD,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,MAAM,CAAC,OAAO,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACxC,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,GAAG,EAAU,CAAC,CAAC;IAE7C,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAC3B,KAAK,EAAK,GAAW,EAAE,MAAwB,EAAE,OAA0B,EAA0B,EAAE;QACrG,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,SAAS,CAAC;QAC5C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtB,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAE/B,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC;QACxD,MAAM,IAAI,GAAG,EAAE,GAAI,IAAyB,EAAE,GAAG,OAAO,EAAE,CAAC;QAC3D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE,CAAC;YAC9B,MAAM,OAAO,GAAG,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;YACzF,IAAI,OAAO;gBAAE,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;YACvD,IAAI,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC;YACzB,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACjB,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,kBAAkB,EAAE,WAAW,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACtG,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QACjC,CAAC;IACH,CAAC,EACD,EAAE,CACH,CAAC;IAEF,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAE5E,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;AAC1D,CAAC"}

package/dist/ux/use-optimistic-list.d.ts

@@ -0,0 +1,69 @@
+import { tempKey, type RowKey } from "./optimistic.js";
+export interface OptimisticListOptions<T> {
+    /** How a row is identified. Must be stable for the life of the row. */
+    key: (row: T) => RowKey;
+    /** Heading for the toast when a write fails. */
+    error?: string;
+    /**
+     * Run after a write lands. This is where the caller refetches — the hook
+     * cannot know whether that is `router.refresh()`, a reload callback or
+     * nothing at all, and it deliberately keeps working if it is nothing.
+     */
+    onSettled?: () => void;
+}
+/** Per-call overrides. */
+export interface WriteOptions {
+    /** What to say when it works. Nothing said by default: the row moving is the feedback. */
+    success?: string;
+    /** Heading when it fails. */
+    error?: string;
+    /** Skip the list-level `onSettled` for this one write. */
+    silentSettle?: boolean;
+}
+export interface OptimisticList<T> {
+    /** What to render: the server's rows with every un-dropped change laid over. */
+    items: T[];
+    /** This row has a write in flight — dim it, spin its button, leave the rest alone. */
+    isPending: (key: RowKey) => boolean;
+    /** Anything at all in flight. */
+    pending: boolean;
+    /** Show a new row now; the commit's returned row replaces the stand-in. */
+    insert: (row: T, commit: () => Promise<T | void>, options?: WriteOptions) => Promise<boolean>;
+    /** Show an edit now. The commit may return the row as the server has it. */
+    update: (key: RowKey, fields: Partial<T>, commit: () => Promise<T | void>, options?: WriteOptions) => Promise<boolean>;
+    /** Take a row off the list now. */
+    remove: (key: RowKey, commit: () => Promise<unknown>, options?: WriteOptions) => Promise<boolean>;
+    /** Put a row before another one (`null` = last) now. */
+    move: (key: RowKey, before: RowKey | null, commit: () => Promise<unknown>, options?: WriteOptions) => Promise<boolean>;
+    /**
+     * Several rows under one write — "mark all read", "archive the selected".
+     * They settle and roll back together, because the request did.
+     */
+    bulk: (changes: readonly {
+        key: RowKey;
+        fields: Partial<T>;
+    }[], commit: () => Promise<unknown>, options?: WriteOptions) => Promise<boolean>;
+}
+/**
+ * A list the screen can change before the server has agreed.
+ *
+ * `base` is whatever the server last said — a server component's prop, or
+ * state filled by a fetch. Never write to it: the hook keeps its changes
+ * beside it and folds them in on render, which is what lets fresh rows take
+ * over cleanly whenever they turn up. See `optimistic.ts` for the rules.
+ *
+ * ```tsx
+ * const list = useOptimisticList(tasks, { key: (t) => t.id, onSettled: router.refresh });
+ *
+ * <Checkbox
+ *   checked={task.done}
+ *   disabled={list.isPending(task.id)}
+ *   onCheckedChange={(done) =>
+ *     list.update(task.id, { done }, () => commitApi(`/api/tasks/${task.id}`, { method: "PATCH", … }))
+ *   }
+ * />
+ * ```
+ */
+export declare function useOptimisticList<T>(base: readonly T[], options: OptimisticListOptions<T>): OptimisticList<T>;
+export { tempKey };
+//# sourceMappingURL=use-optimistic-list.d.ts.map

package/dist/ux/use-optimistic-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-optimistic-list.d.ts","sourceRoot":"","sources":["../../src/ux/use-optimistic-list.ts"],"names":[],"mappings":"AAMA,OAAO,EAML,OAAO,EAEP,KAAK,MAAM,EACZ,MAAM,iBAAiB,CAAC;AAIzB,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,uEAAuE;IACvE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC;IACxB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,0BAA0B;AAC1B,MAAM,WAAW,YAAY;IAC3B,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,gFAAgF;IAChF,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,sFAAsF;IACtF,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACpC,iCAAiC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9F,4EAA4E;IAC5E,MAAM,EAAE,CACN,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAC/B,OAAO,CAAC,EAAE,YAAY,KACnB,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,mCAAmC;IACnC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClG,wDAAwD;IACxD,IAAI,EAAE,CACJ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE,YAAY,KACnB,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB;;;OAGG;IACH,IAAI,EAAE,CACJ,OAAO,EAAE,SAAS;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;KAAE,EAAE,EACvD,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE,YAAY,KACnB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CA8H7G;AAED,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/ux/use-optimistic-list.js

@@ -0,0 +1,115 @@
+"use client";
+import * as React from "react";
+import { errorMessage } from "./errors.js";
+import { useActionReporter } from "./feedback.js";
+import { applyPatches, nextPatchId, reconcile, settlePatch, supersede, tempKey, } from "./optimistic.js";
+const NO_PATCHES = [];
+/**
+ * A list the screen can change before the server has agreed.
+ *
+ * `base` is whatever the server last said — a server component's prop, or
+ * state filled by a fetch. Never write to it: the hook keeps its changes
+ * beside it and folds them in on render, which is what lets fresh rows take
+ * over cleanly whenever they turn up. See `optimistic.ts` for the rules.
+ *
+ * ```tsx
+ * const list = useOptimisticList(tasks, { key: (t) => t.id, onSettled: router.refresh });
+ *
+ * <Checkbox
+ *   checked={task.done}
+ *   disabled={list.isPending(task.id)}
+ *   onCheckedChange={(done) =>
+ *     list.update(task.id, { done }, () => commitApi(`/api/tasks/${task.id}`, { method: "PATCH", … }))
+ *   }
+ * />
+ * ```
+ */
+export function useOptimisticList(base, options) {
+    const report = useActionReporter();
+    const [patches, setPatches] = React.useState(NO_PATCHES);
+    // Everything the asynchronous half needs, read at the time it runs.
+    const latest = React.useRef({ base, options, report });
+    React.useEffect(() => {
+        latest.current = { base, options, report };
+    });
+    // What is still worth applying, worked out fresh on every render rather than
+    // stored. A settled patch knows what the rows said when it landed, so
+    // `reconcile` can tell "nothing has refetched yet" from "new rows are here"
+    // without this hook having to watch the array — and it must not watch it:
+    // `useOptimisticList(rows.filter(…), …)` hands it a different array every
+    // render, and any state keyed on that identity renders forever.
+    const live = reconcile(patches, base, options.key);
+    const write = React.useCallback(async (batch, commit, per) => {
+        // Queued at the end, where it wins on render, and *without* clearing
+        // what is already held for these rows. An earlier change that succeeded
+        // is still true: rolling this one back must not take it down too.
+        //
+        // Reconciling here as well is the only pruning the stored queue gets.
+        // Render works out what to apply without touching state — it has to, or
+        // a caller passing `rows.filter(…)` would render forever — so this is
+        // where changes the rows have caught up with are actually let go of.
+        setPatches((previous) => [...reconcile(previous, latest.current.base, latest.current.options.key), ...batch]);
+        const ids = new Set(batch.map((patch) => patch.id));
+        const { options: opts, report: tell } = latest.current;
+        try {
+            const result = (await commit());
+            // A single write may be answered with the row as the server has it; a
+            // batch has no one row to be answered with.
+            const answer = batch.length === 1 ? (result ?? undefined) : undefined;
+            setPatches((previous) => {
+                const { base: rows, options: current } = latest.current;
+                const landed = previous
+                    .filter((held) => ids.has(held.id))
+                    .map((held) => settlePatch(held, answer, rows, current.key));
+                // Now that this one has landed it supersedes what was already held
+                // for the same rows. Writes still in flight are left: each has a
+                // request of its own that can still come back refused.
+                const keys = new Set(landed.map((held) => held.key));
+                const kept = supersede(previous.filter((held) => !ids.has(held.id)), keys);
+                return [...kept, ...landed];
+            });
+            if (per?.success)
+                tell({ tone: "success", title: per.success });
+            if (!per?.silentSettle)
+                opts.onSettled?.();
+            return true;
+        }
+        catch (thrown) {
+            // Roll back: the rows go back to whatever the server last said, which
+            // `base` still holds untouched.
+            setPatches((previous) => previous.filter((held) => !ids.has(held.id)));
+            tell({
+                tone: "error",
+                title: per?.error ?? opts.error ?? "That didn't save",
+                description: errorMessage(thrown),
+            });
+            return false;
+        }
+    }, []);
+    const insert = React.useCallback((row, commit, per) => {
+        const key = latest.current.options.key(row);
+        return write([{ id: nextPatchId(), kind: "insert", key, row, at: "end", settled: false }], commit, per);
+    }, [write]);
+    const update = React.useCallback((key, fields, commit, per) => write([{ id: nextPatchId(), kind: "update", key, fields, settled: false }], commit, per), [write]);
+    const remove = React.useCallback((key, commit, per) => write([{ id: nextPatchId(), kind: "remove", key, settled: false }], commit, per), [write]);
+    const move = React.useCallback((key, before, commit, per) => write([{ id: nextPatchId(), kind: "move", key, before, settled: false }], commit, per), [write]);
+    const bulk = React.useCallback((changes, commit, per) => write(changes.map(({ key, fields }) => ({
+        id: nextPatchId(),
+        kind: "update",
+        key,
+        fields,
+        settled: false,
+    })), commit, per), [write]);
+    const items = applyPatches(base, live, options.key);
+    const busy = React.useMemo(() => {
+        const keys = new Set();
+        for (const patch of live)
+            if (!patch.settled)
+                keys.add(patch.key);
+        return keys;
+    }, [live]);
+    const isPending = React.useCallback((key) => busy.has(key), [busy]);
+    return { items, isPending, pending: busy.size > 0, insert, update, remove, move, bulk };
+}
+export { tempKey };
+//# sourceMappingURL=use-optimistic-list.js.map

package/dist/ux/use-optimistic-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-optimistic-list.js","sourceRoot":"","sources":["../../src/ux/use-optimistic-list.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,YAAY,EACZ,WAAW,EACX,SAAS,EACT,WAAW,EACX,SAAS,EACT,OAAO,GAGR,MAAM,iBAAiB,CAAC;AAEzB,MAAM,UAAU,GAA4B,EAAE,CAAC;AA6D/C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAAI,IAAkB,EAAE,OAAiC;IACxF,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACnC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAsB,UAAiC,CAAC,CAAC;IAErG,oEAAoE;IACpE,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACvD,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,MAAM,CAAC,OAAO,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,6EAA6E;IAC7E,sEAAsE;IACtE,4EAA4E;IAC5E,0EAA0E;IAC1E,0EAA0E;IAC1E,gEAAgE;IAChE,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IAEnD,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAC7B,KAAK,EACH,KAA0B,EAC1B,MAA8B,EAC9B,GAA6B,EACX,EAAE;QACpB,qEAAqE;QACrE,wEAAwE;QACxE,kEAAkE;QAClE,EAAE;QACF,sEAAsE;QACtE,wEAAwE;QACxE,sEAAsE;QACtE,qEAAqE;QACrE,UAAU,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC;QAE9G,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;QACpD,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC;QACvD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,EAAE,CAAkB,CAAC;YACjD,sEAAsE;YACtE,4CAA4C;YAC5C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACtE,UAAU,CAAC,CAAC,QAAQ,EAAE,EAAE;gBACtB,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC;gBACxD,MAAM,MAAM,GAAG,QAAQ;qBACpB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;qBAClC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;gBAC/D,mEAAmE;gBACnE,iEAAiE;gBACjE,uDAAuD;gBACvD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;gBACrD,MAAM,IAAI,GAAG,SAAS,CACpB,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAC5C,IAAI,CACL,CAAC;gBACF,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC,CAAC;YAC9B,CAAC,CAAC,CAAC;YACH,IAAI,GAAG,EAAE,OAAO;gBAAE,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YAChE,IAAI,CAAC,GAAG,EAAE,YAAY;gBAAE,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;YAC3C,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,MAAM,EAAE,CAAC;YAChB,sEAAsE;YACtE,gCAAgC;YAChC,UAAU,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACvE,IAAI,CAAC;gBACH,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,GAAG,EAAE,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,kBAAkB;gBACrD,WAAW,EAAE,YAAY,CAAC,MAAM,CAAC;aAClC,CAAC,CAAC;YACH,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC,EACD,EAAE,CACH,CAAC;IAEF,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,CAC9B,CAAC,GAAM,EAAE,MAA+B,EAAE,GAAkB,EAAE,EAAE;QAC9D,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5C,OAAO,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1G,CAAC,EACD,CAAC,KAAK,CAAC,CACR,CAAC;IAEF,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,CAC9B,CAAC,GAAW,EAAE,MAAkB,EAAE,MAA+B,EAAE,GAAkB,EAAE,EAAE,CACvF,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAC1F,CAAC,KAAK,CAAC,CACR,CAAC;IAEF,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,CAC9B,CAAC,GAAW,EAAE,MAA8B,EAAE,GAAkB,EAAE,EAAE,CAClE,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAClF,CAAC,KAAK,CAAC,CACR,CAAC;IAEF,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,CAC5B,CAAC,GAAW,EAAE,MAAqB,EAAE,MAA8B,EAAE,GAAkB,EAAE,EAAE,CACzF,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EACxF,CAAC,KAAK,CAAC,CACR,CAAC;IAEF,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,CAC5B,CAAC,OAAuD,EAAE,MAA8B,EAAE,GAAkB,EAAE,EAAE,CAC9G,KAAK,CACH,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QAChC,EAAE,EAAE,WAAW,EAAE;QACjB,IAAI,EAAE,QAAiB;QACvB,GAAG;QACH,MAAM;QACN,OAAO,EAAE,KAAK;KACf,CAAC,CAAC,EACH,MAAM,EACN,GAAG,CACJ,EACH,CAAC,KAAK,CAAC,CACR,CAAC;IAEF,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAQ,CAAC;IAC3D,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE;QAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,IAAI;YAAE,IAAI,CAAC,KAAK,CAAC,OAAO;gBAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC;IACd,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAEX,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAE5E,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC1F,CAAC;AAED,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/ux/use-optimistic-value.d.ts

@@ -0,0 +1,40 @@
+export interface OptimisticValueOptions {
+    /** Heading for the toast when the write fails. */
+    error?: string;
+    /** Run after the write lands — usually `router.refresh()`. */
+    onSettled?: () => void;
+}
+export interface OptimisticValue<T> {
+    /** What to render: the change if one is held, otherwise the server's value. */
+    value: T;
+    /** A write is in flight. */
+    pending: boolean;
+    /**
+     * Show `next` now, then commit it. The commit may resolve with the value as
+     * the server has it — and must resolve with **that value's own shape** or
+     * nothing at all. A write route often answers with some other record
+     * entirely, which would replace the value with something that is not one:
+     * `async () => { await save(); }` is the right wrapper in that case.
+     */
+    set: (next: T, commit: () => Promise<T | void>, options?: {
+        success?: string;
+        error?: string;
+    }) => Promise<boolean>;
+    /** The same for an object value: lay these fields over it. */
+    merge: (fields: Partial<T>, commit: () => Promise<T | void>, options?: {
+        success?: string;
+        error?: string;
+    }) => Promise<boolean>;
+}
+/**
+ * One value the screen can change before the server has agreed: a switch, a
+ * status, a counter, a settings record.
+ *
+ * Same rules as `useOptimisticList` and for the same reasons — the change is
+ * held beside the server's value rather than replacing it, so a failure rolls
+ * back to something real and a refresh always wins. A switch is the case where
+ * getting this wrong is most obvious: flipping back a second after it was
+ * flipped, with no explanation, is worse than not moving at all.
+ */
+export declare function useOptimisticValue<T>(base: T, options?: OptimisticValueOptions): OptimisticValue<T>;
+//# sourceMappingURL=use-optimistic-value.d.ts.map

package/dist/ux/use-optimistic-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-optimistic-value.d.ts","sourceRoot":"","sources":["../../src/ux/use-optimistic-value.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,+EAA+E;IAC/E,KAAK,EAAE,CAAC,CAAC;IACT,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpH,8DAA8D;IAC9D,KAAK,EAAE,CACL,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAC/B,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAC3C,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,GAAE,sBAA2B,GAAG,eAAe,CAAC,CAAC,CAAC,CA8DvG"}

package/dist/ux/use-optimistic-value.js

@@ -0,0 +1,68 @@
+"use client";
+import * as React from "react";
+import { errorMessage } from "./errors.js";
+import { useActionReporter } from "./feedback.js";
+import { sameRow } from "./optimistic.js";
+/**
+ * One value the screen can change before the server has agreed: a switch, a
+ * status, a counter, a settings record.
+ *
+ * Same rules as `useOptimisticList` and for the same reasons — the change is
+ * held beside the server's value rather than replacing it, so a failure rolls
+ * back to something real and a refresh always wins. A switch is the case where
+ * getting this wrong is most obvious: flipping back a second after it was
+ * flipped, with no explanation, is worse than not moving at all.
+ */
+export function useOptimisticValue(base, options = {}) {
+    const report = useActionReporter();
+    // `witness` is what the server's value was when the write landed. A settled
+    // hold stands until that changes, which is how "nothing has refreshed yet"
+    // is told apart from "the server now says something else". Worked out on
+    // each render rather than stored, so an object rebuilt by the parent on
+    // every render cannot start a render loop.
+    const [held, setHeld] = React.useState(null);
+    const latest = React.useRef({ options, report });
+    React.useEffect(() => {
+        latest.current = { options, report };
+    });
+    // Nothing is stored when this flips: the next `set` replaces the hold
+    // anyway, and clearing it from an effect would only add a render.
+    const overtaken = held !== null && held.settled && !sameRow(held.witness, base);
+    const value = held && !overtaken ? held.value : base;
+    const valueRef = React.useRef(value);
+    const baseRef = React.useRef(base);
+    React.useEffect(() => {
+        valueRef.current = value;
+        baseRef.current = base;
+    });
+    const set = React.useCallback(async (next, commit, per) => {
+        setHeld({ value: next, settled: false });
+        const { options: opts, report: tell } = latest.current;
+        try {
+            const result = (await commit());
+            // The server's own value where it sent one, so a clamped or normalised
+            // answer shows now rather than after the next refresh.
+            setHeld({
+                value: result === undefined || result === null ? next : result,
+                settled: true,
+                witness: baseRef.current,
+            });
+            if (per?.success)
+                tell({ tone: "success", title: per.success });
+            opts.onSettled?.();
+            return true;
+        }
+        catch (thrown) {
+            setHeld(null);
+            tell({
+                tone: "error",
+                title: per?.error ?? opts.error ?? "That didn't save",
+                description: errorMessage(thrown),
+            });
+            return false;
+        }
+    }, []);
+    const merge = React.useCallback((fields, commit, per) => set({ ...valueRef.current, ...fields }, commit, per), [set]);
+    return { value, pending: held !== null && !held.settled, set, merge };
+}
+//# sourceMappingURL=use-optimistic-value.js.map

package/dist/ux/use-optimistic-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-optimistic-value.js","sourceRoot":"","sources":["../../src/ux/use-optimistic-value.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connextar/house",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The pieces every app we build needs and none of them should own a copy of.",
   "license": "MIT",
   "repository": {
@@ -42,6 +42,14 @@
       "types": "./dist/trail/index.d.ts",
       "default": "./dist/trail/index.js"
     },
+    "./ux": {
+      "types": "./dist/ux/index.d.ts",
+      "default": "./dist/ux/index.js"
+    },
+    "./ux/navigation": {
+      "types": "./dist/ux/navigation-index.d.ts",
+      "default": "./dist/ux/navigation-index.js"
+    },
     "./editor": {
       "types": "./dist/editor/index.d.ts",
       "default": "./dist/editor/index.js"
@@ -70,7 +78,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "build": "rm -rf dist && tsc --project tsconfig.build.json && cp src/styles/house.css dist/house.css",
-    "verify": "npm run check:ci && npm run test && npm run build",
+    "verify": "npm run check:ci && npm run build && npm run test",
     "prepublishOnly": "npm run verify",
     "check:ci": "npm run lint:check && npm run format:check && npm run typecheck"
   },