@connextar/house 0.1.1 → 0.3.0

package/dist/ux/optimistic.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The patch queue behind the optimistic hooks — no React, no transport, no
+ * framework. All of the thinking is here so it can be tested as a function.
+ *
+ * ## The shape of the problem
+ *
+ * A screen shows rows the server sent. Someone ticks one. Three things then
+ * have to be true at once:
+ *
+ * 1. The tick shows **now**, before any request goes out.
+ * 2. If the write fails, the tick goes away again and the person is told.
+ * 3. When the server's own rows arrive, they win — including when they say
+ *    something different from what was guessed.
+ *
+ * React's `useOptimistic` solves (1) and (2) for a server action, because the
+ * action *is* the transition and React knows when it ends. It does not solve
+ * (3) for an app that writes over `fetch` and then calls `router.refresh()`:
+ * `router.refresh()` is not awaitable, so the transition ends before the new
+ * rows land and the optimistic value snaps back to the stale one — a visible
+ * flash of the old answer on every single write. That is the reason this
+ * module exists rather than a wrapper around `useOptimistic`.
+ *
+ * ## How it works
+ *
+ * The server's rows are the *base*. Every optimistic change is a *patch* held
+ * beside the base, never merged into it. What the screen renders is the base
+ * with the patches applied, recomputed on each render.
+ *
+ * A patch is `pending` while its write is in flight, then either:
+ *
+ * - **dropped** — the write failed, so the base alone is the truth again; or
+ * - **settled** — the write landed. It keeps being applied, because the base
+ *   is still the *old* rows until a refresh arrives, and taking the patch away
+ *   at this point is precisely the flash we are avoiding.
+ *
+ * A settled patch is dropped when fresh rows arrive that account for it. That
+ * is the whole reconciliation rule, and it is deliberately evidence-based
+ * rather than timed: see `shouldDropSettled`.
+ */
+/** How a row is identified. Ids are strings here; numbers stringify fine. */
+export type RowKey = string;
+export type PatchKind = "insert" | "update" | "remove" | "move";
+export interface Patch<T> {
+    readonly id: string;
+    readonly kind: PatchKind;
+    /**
+     * The row this patch concerns. For an insert this starts as a made-up key
+     * and becomes the server's own key once the write lands.
+     */
+    readonly key: RowKey;
+    /** `insert`: the row to show. */
+    readonly row?: T;
+    /** `update`: the fields to lay over the row. */
+    readonly fields?: Partial<T>;
+    /** `insert`: which end of the list to show it at. */
+    readonly at?: "start" | "end";
+    /** `move`: the key this row now sits before; `null` means last. */
+    readonly before?: RowKey | null;
+    readonly settled: boolean;
+    /**
+     * What the base said about `key` at the moment the write landed. Fresh rows
+     * are recognised by disagreeing with it — see `shouldDropSettled`.
+     */
+    readonly witness?: T | null;
+}
+/** A patch id. Unique within a session; never stored or sent anywhere. */
+export declare function nextPatchId(): string;
+/**
+ * The rows to render: the server's, with every patch laid over them in the
+ * order they were made, so a later change to the same row wins.
+ */
+export declare function applyPatches<T>(base: readonly T[], patches: readonly Patch<T>[], keyOf: (row: T) => RowKey): readonly T[];
+/** Shallow, own-keys equality. Enough to tell "the same row" from "new data". */
+export declare function sameRow<T>(a: T | null | undefined, b: T | null | undefined): boolean;
+/**
+ * Does the base already say what this patch says? A redundant patch has
+ * nothing left to show and can go.
+ */
+export declare function isRedundant<T>(patch: Patch<T>, base: readonly T[], keyOf: (row: T) => RowKey): boolean;
+/**
+ * Whether a settled patch has been overtaken by fresh server rows.
+ *
+ * Two ways it can have been, and they cover the two endings the person cares
+ * about:
+ *
+ * - **The base agrees** — the refresh carried the change through. Dropping the
+ *   patch changes nothing on screen, which is exactly the point.
+ * - **The base disagrees with what it said when the write landed** — new data
+ *   for this row has arrived. It wins, whatever it says. This is the case
+ *   where the server did something other than what was guessed (clamped a
+ *   value, renamed on save, reordered), and the screen corrects itself.
+ *
+ * A base that has not changed at all leaves the patch applied, however long it
+ * has been there. There is no timeout on purpose: a screen that never refetches
+ * has no truth to fall back to, and snapping to stale rows after N seconds
+ * would be a bug that only shows up on slow connections.
+ *
+ * Only ever called when the base is a *different array* from the one the patch
+ * settled against, so a parent that rebuilds its rows on every render cannot
+ * shake patches loose.
+ */
+export declare function shouldDropSettled<T>(patch: Patch<T>, base: readonly T[], keyOf: (row: T) => RowKey): boolean;
+/**
+ * The queue after fresh rows arrived: pending writes are left alone, settled
+ * ones are dropped once the rows account for them.
+ */
+export declare function reconcile<T>(patches: readonly Patch<T>[], base: readonly T[], keyOf: (row: T) => RowKey): readonly Patch<T>[];
+/**
+ * Mark a landed write as settled, taking the server's own answer over the
+ * guess where it sent one — the correction in "confirm or correct" — and
+ * noting what the base said, so the next refresh can be recognised.
+ *
+ * What it takes from that answer is deliberately narrow. A write endpoint
+ * often returns a *thinner* record than the list endpoint does — no joined
+ * learner, no counts — because the caller did not need them. Laying that over
+ * the row wholesale would blank the columns beside the one that was edited,
+ * which looks exactly like data loss and is the reason this is a `pick` and a
+ * merge rather than an assignment.
+ */
+export declare function settlePatch<T>(patch: Patch<T>, serverRow: T | undefined, base: readonly T[], keyOf: (row: T) => RowKey): Patch<T>;
+/**
+ * Drop what a write that has just landed supersedes: earlier *settled* changes
+ * to the same rows. Writes still in flight stay — each has a request that can
+ * still come back refused and needs rolling back on its own.
+ *
+ * This happens on landing, never on queueing. A change that succeeded is still
+ * true while a later one is being attempted, and clearing it early means a
+ * failed second write rolls the first one back with it.
+ */
+export declare function supersede<T>(patches: readonly Patch<T>[], keys: ReadonlySet<RowKey>): readonly Patch<T>[];
+/**
+ * A stand-in key for a row that does not exist server-side yet. Distinctive on
+ * purpose: if one of these ever reaches a request body or a URL, the resulting
+ * 404 should say why at a glance.
+ */
+export declare function tempKey(prefix?: string): string;
+/** Whether a key came from `tempKey` — a row that is still being created. */
+export declare function isTempKey(key: RowKey): boolean;
+//# sourceMappingURL=optimistic.d.ts.map

package/dist/ux/optimistic.d.ts.map

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

package/dist/ux/optimistic.js

@@ -0,0 +1,242 @@
+/**
+ * The patch queue behind the optimistic hooks — no React, no transport, no
+ * framework. All of the thinking is here so it can be tested as a function.
+ *
+ * ## The shape of the problem
+ *
+ * A screen shows rows the server sent. Someone ticks one. Three things then
+ * have to be true at once:
+ *
+ * 1. The tick shows **now**, before any request goes out.
+ * 2. If the write fails, the tick goes away again and the person is told.
+ * 3. When the server's own rows arrive, they win — including when they say
+ *    something different from what was guessed.
+ *
+ * React's `useOptimistic` solves (1) and (2) for a server action, because the
+ * action *is* the transition and React knows when it ends. It does not solve
+ * (3) for an app that writes over `fetch` and then calls `router.refresh()`:
+ * `router.refresh()` is not awaitable, so the transition ends before the new
+ * rows land and the optimistic value snaps back to the stale one — a visible
+ * flash of the old answer on every single write. That is the reason this
+ * module exists rather than a wrapper around `useOptimistic`.
+ *
+ * ## How it works
+ *
+ * The server's rows are the *base*. Every optimistic change is a *patch* held
+ * beside the base, never merged into it. What the screen renders is the base
+ * with the patches applied, recomputed on each render.
+ *
+ * A patch is `pending` while its write is in flight, then either:
+ *
+ * - **dropped** — the write failed, so the base alone is the truth again; or
+ * - **settled** — the write landed. It keeps being applied, because the base
+ *   is still the *old* rows until a refresh arrives, and taking the patch away
+ *   at this point is precisely the flash we are avoiding.
+ *
+ * A settled patch is dropped when fresh rows arrive that account for it. That
+ * is the whole reconciliation rule, and it is deliberately evidence-based
+ * rather than timed: see `shouldDropSettled`.
+ */
+let counter = 0;
+/** A patch id. Unique within a session; never stored or sent anywhere. */
+export function nextPatchId() {
+    counter += 1;
+    return `p${counter}`;
+}
+function find(rows, key, keyOf) {
+    for (const row of rows)
+        if (keyOf(row) === key)
+            return row;
+    return null;
+}
+/**
+ * The rows to render: the server's, with every patch laid over them in the
+ * order they were made, so a later change to the same row wins.
+ */
+export function applyPatches(base, patches, keyOf) {
+    if (patches.length === 0)
+        return base;
+    let rows = [...base];
+    for (const patch of patches) {
+        switch (patch.kind) {
+            case "insert": {
+                // The server's own copy has arrived under this key: show that one
+                // rather than two of the same thing.
+                if (patch.row === undefined || find(rows, patch.key, keyOf) !== null)
+                    break;
+                if (patch.at === "start")
+                    rows.unshift(patch.row);
+                else
+                    rows.push(patch.row);
+                break;
+            }
+            case "update": {
+                rows = rows.map((row) => (keyOf(row) === patch.key ? { ...row, ...patch.fields } : row));
+                break;
+            }
+            case "remove": {
+                rows = rows.filter((row) => keyOf(row) !== patch.key);
+                break;
+            }
+            case "move": {
+                const from = rows.findIndex((row) => keyOf(row) === patch.key);
+                if (from < 0)
+                    break;
+                const moved = rows.splice(from, 1);
+                // `splice` above removed exactly one row at a known index, so this is
+                // never empty; the check is for the type, not for the case.
+                if (moved.length === 0)
+                    break;
+                const to = patch.before == null ? -1 : rows.findIndex((other) => keyOf(other) === patch.before);
+                rows.splice(to < 0 ? rows.length : to, 0, ...moved);
+                break;
+            }
+        }
+    }
+    return rows;
+}
+/** The key that follows `key` in `rows`; `null` at the end. */
+function neighbourAfter(rows, key, keyOf) {
+    const index = rows.findIndex((row) => keyOf(row) === key);
+    if (index < 0)
+        return null;
+    const next = rows[index + 1];
+    return next === undefined ? null : keyOf(next);
+}
+/** Shallow, own-keys equality. Enough to tell "the same row" from "new data". */
+export function sameRow(a, b) {
+    if (a === b)
+        return true;
+    if (a == null || b == null)
+        return false;
+    if (typeof a !== "object" || typeof b !== "object")
+        return Object.is(a, b);
+    const left = a;
+    const right = b;
+    const keys = Object.keys(left);
+    if (keys.length !== Object.keys(right).length)
+        return false;
+    return keys.every((key) => Object.is(left[key], right[key]));
+}
+/**
+ * Does the base already say what this patch says? A redundant patch has
+ * nothing left to show and can go.
+ */
+export function isRedundant(patch, base, keyOf) {
+    const current = find(base, patch.key, keyOf);
+    switch (patch.kind) {
+        case "insert":
+            return current !== null;
+        case "remove":
+            return current === null;
+        case "update": {
+            // A row that is no longer there cannot be waiting for an edit.
+            if (current === null)
+                return true;
+            const fields = (patch.fields ?? {});
+            const row = current;
+            return Object.keys(fields).every((key) => Object.is(row[key], fields[key]));
+        }
+        case "move":
+            return find(base, patch.key, keyOf) !== null && neighbourAfter(base, patch.key, keyOf) === patch.before;
+    }
+}
+/**
+ * Whether a settled patch has been overtaken by fresh server rows.
+ *
+ * Two ways it can have been, and they cover the two endings the person cares
+ * about:
+ *
+ * - **The base agrees** — the refresh carried the change through. Dropping the
+ *   patch changes nothing on screen, which is exactly the point.
+ * - **The base disagrees with what it said when the write landed** — new data
+ *   for this row has arrived. It wins, whatever it says. This is the case
+ *   where the server did something other than what was guessed (clamped a
+ *   value, renamed on save, reordered), and the screen corrects itself.
+ *
+ * A base that has not changed at all leaves the patch applied, however long it
+ * has been there. There is no timeout on purpose: a screen that never refetches
+ * has no truth to fall back to, and snapping to stale rows after N seconds
+ * would be a bug that only shows up on slow connections.
+ *
+ * Only ever called when the base is a *different array* from the one the patch
+ * settled against, so a parent that rebuilds its rows on every render cannot
+ * shake patches loose.
+ */
+export function shouldDropSettled(patch, base, keyOf) {
+    if (isRedundant(patch, base, keyOf))
+        return true;
+    return !sameRow(find(base, patch.key, keyOf), patch.witness ?? null);
+}
+/**
+ * The queue after fresh rows arrived: pending writes are left alone, settled
+ * ones are dropped once the rows account for them.
+ */
+export function reconcile(patches, base, keyOf) {
+    if (patches.length === 0)
+        return patches;
+    const kept = patches.filter((patch) => !patch.settled || !shouldDropSettled(patch, base, keyOf));
+    return kept.length === patches.length ? patches : kept;
+}
+/**
+ * Mark a landed write as settled, taking the server's own answer over the
+ * guess where it sent one — the correction in "confirm or correct" — and
+ * noting what the base said, so the next refresh can be recognised.
+ *
+ * What it takes from that answer is deliberately narrow. A write endpoint
+ * often returns a *thinner* record than the list endpoint does — no joined
+ * learner, no counts — because the caller did not need them. Laying that over
+ * the row wholesale would blank the columns beside the one that was edited,
+ * which looks exactly like data loss and is the reason this is a `pick` and a
+ * merge rather than an assignment.
+ */
+export function settlePatch(patch, serverRow, base, keyOf) {
+    const settled = { ...patch, settled: true, witness: find(base, patch.key, keyOf) };
+    if (serverRow === null || serverRow === undefined || typeof serverRow !== "object")
+        return settled;
+    if (patch.kind === "insert" && patch.row !== undefined) {
+        // The guess fills in whatever the create did not answer with; the key
+        // comes from the server, because that is the one thing only it knows.
+        const row = { ...patch.row, ...serverRow };
+        const key = keyOf(row);
+        return { ...settled, key, row, witness: find(base, key, keyOf) };
+    }
+    if (patch.kind === "update" && patch.fields) {
+        // Only the fields this write set, and only those the answer carried: a
+        // price rounded on save, a title trimmed, a status the server chose.
+        const answer = serverRow;
+        const corrected = { ...patch.fields };
+        for (const field of Object.keys(corrected)) {
+            if (field in answer)
+                corrected[field] = answer[field];
+        }
+        return { ...settled, fields: corrected };
+    }
+    return settled;
+}
+/**
+ * Drop what a write that has just landed supersedes: earlier *settled* changes
+ * to the same rows. Writes still in flight stay — each has a request that can
+ * still come back refused and needs rolling back on its own.
+ *
+ * This happens on landing, never on queueing. A change that succeeded is still
+ * true while a later one is being attempted, and clearing it early means a
+ * failed second write rolls the first one back with it.
+ */
+export function supersede(patches, keys) {
+    return patches.filter((patch) => !(patch.settled && keys.has(patch.key)));
+}
+/**
+ * A stand-in key for a row that does not exist server-side yet. Distinctive on
+ * purpose: if one of these ever reaches a request body or a URL, the resulting
+ * 404 should say why at a glance.
+ */
+export function tempKey(prefix = "tmp") {
+    counter += 1;
+    return `${prefix}:${counter}:${Date.now().toString(36)}`;
+}
+/** Whether a key came from `tempKey` — a row that is still being created. */
+export function isTempKey(key) {
+    return key.startsWith("tmp:");
+}
+//# sourceMappingURL=optimistic.js.map

package/dist/ux/optimistic.js.map

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

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":"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"}

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"}