@phis/ui 0.2.1 → 0.3.0

package/components/state/history-store.js

@@ -27,33 +27,35 @@ export function createPhiHistoryStore(storeId, options) {
             };
         });
     }
+    /** Takes the newest step back and answers with it, so the caller can say what it took back. */
     function undo(scopeKey, apply) {
         openGestures.delete(scopeKey);
         const current = store.getSnapshot(scopeKey);
         const entry = current.past.at(-1);
         if (!entry) {
-            return false;
+            return null;
         }
         apply(entry.before);
         store.replace(scopeKey, {
             past: current.past.slice(0, -1),
             future: [...current.future, entry],
         });
-        return true;
+        return entry;
     }
+    /** Brings the last step taken back again and answers with it. */
     function redo(scopeKey, apply) {
         openGestures.delete(scopeKey);
         const current = store.getSnapshot(scopeKey);
         const entry = current.future.at(-1);
         if (!entry) {
-            return false;
+            return null;
         }
         apply(entry.after);
         store.replace(scopeKey, {
             past: [...current.past, entry],
             future: current.future.slice(0, -1),
         });
-        return true;
+        return entry;
     }
     /**
      * Ends whatever gesture is still open, so the next record starts an entry of its own. Called when the
@@ -75,6 +77,8 @@ export function createPhiHistoryStore(storeId, options) {
         return {
             canUndo: state.past.length > 0,
             canRedo: state.future.length > 0,
+            undoAction: state.past.at(-1)?.action ?? null,
+            redoAction: state.future.at(-1)?.action ?? null,
         };
     }
     /**
@@ -93,6 +97,8 @@ export function createPhiHistoryStore(storeId, options) {
         return {
             canUndo: state.past.length > 0,
             canRedo: state.future.length > 0,
+            undoAction: state.past.at(-1)?.action ?? null,
+            redoAction: state.future.at(-1)?.action ?? null,
         };
     }
     return {

package/components/surface/phi-surface-ground.d.ts

@@ -0,0 +1,16 @@
+import type { PhiSurfaceGround } from "../../helpers/surface-style";
+/**
+ * Where the paint lies when it is larger than the box: one picture across several boxes, each showing
+ * its own part of it. `left` and `width` in CSS lengths relative to the box; the box clips the rest.
+ */
+export type PhiSurfaceGroundFrame = {
+    left: string;
+    width: string;
+};
+export declare function PhiSurfaceGroundLayer({ ground, className, frame, }: {
+    ground: PhiSurfaceGround | null | undefined;
+    /** For a caller that moves the paint itself, a hover zoom for one. */
+    className?: string;
+    /** The paint's own extent, where it reaches past the box (the Split Card's two cards). */
+    frame?: PhiSurfaceGroundFrame;
+}): import("react").JSX.Element | null;

package/components/surface/phi-surface-ground.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PHI_BACKGROUND_BLUR_RADIUS_PX } from "../widgets/config/background";
+import { PhiBackgroundMotionLayer } from "../cms/clients/phi-background-motion-layer-lazy";
+/**
+ * The layer a Surface's paint lives on when the box cannot carry it (see `PhiSurfaceGround`).
+ *
+ * Rendered as the box's first child, behind the content at `z-index: -1`, clipped to the box and its
+ * corners. A still paint is rendered on the server like any other markup -- a softened picture must not
+ * arrive sharp and blur after hydration -- and only a moving one hands over to the motion layer, which
+ * carries the same softening.
+ *
+ * No hooks and no Client boundary of its own, so a Server Component and a Client Component render it
+ * alike.
+ */
+const PHI_SURFACE_GROUND_HOST = {
+    position: "absolute",
+    inset: 0,
+    overflow: "hidden",
+    borderRadius: "inherit",
+    pointerEvents: "none",
+    zIndex: -1,
+};
+/*
+ * A blurred paint fades towards its own edges, so the layer reaches past the box by twice the radius and
+ * the box clips it: what shows is softened all the way to the corner instead of thinning at the rim.
+ */
+const PHI_SURFACE_GROUND_BLEED = `${-2 * PHI_BACKGROUND_BLUR_RADIUS_PX}px`;
+function resolvePhiSurfaceGroundPaintBox(bleeds, frame) {
+    const edge = bleeds ? PHI_SURFACE_GROUND_BLEED : "0px";
+    if (!frame) {
+        return { top: edge, right: edge, bottom: edge, left: edge };
+    }
+    return {
+        top: edge,
+        bottom: edge,
+        left: bleeds ? `calc(${frame.left} + ${PHI_SURFACE_GROUND_BLEED})` : frame.left,
+        width: bleeds ? `calc(${frame.width} - 2 * ${PHI_SURFACE_GROUND_BLEED})` : frame.width,
+    };
+}
+export function PhiSurfaceGroundLayer({ ground, className, frame, }) {
+    if (!ground) {
+        return null;
+    }
+    if (ground.motion) {
+        return _jsx(PhiBackgroundMotionLayer, { config: ground.motion });
+    }
+    return (_jsx("div", { "aria-hidden": "true", "data-phi-surface-ground": "true", style: PHI_SURFACE_GROUND_HOST, children: _jsx("div", { className: className, "data-phi-surface-ground-paint": "true", style: {
+                ...ground.paint,
+                position: "absolute",
+                // Longhands only: React refuses a shorthand beside the longhands a frame sets on a rerender.
+                ...resolvePhiSurfaceGroundPaintBox(ground.filter != null, frame),
+                ...(ground.filter ? { filter: ground.filter } : {}),
+            } }) }));
+}

package/components/surface/phi-surface-tone-scope.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+import type { PhiThemeToneSource } from "../root/phi-theme-tone-source";
+import type { PhiThemeMode } from "../../theme/phi-theme-presets";
+/**
+ * The other mode, around a Surface's content -- the heavy half of a tone, loaded only where a Surface
+ * asks for a mode its content is not in. The Theme comes from the root, which resolved both modes; its
+ * variables are written under `cssVarKey`, the class the Surface's box carries (`phi-tone-*`).
+ */
+export declare function PhiSurfaceToneScope({ mode, cssVarKey, source, children, }: {
+    mode: PhiThemeMode;
+    cssVarKey: string;
+    source: PhiThemeToneSource;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/components/surface/phi-surface-tone-scope.js

@@ -0,0 +1,11 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PhiNestedModeConfigProvider } from "../root/phi-config-provider";
+/**
+ * The other mode, around a Surface's content -- the heavy half of a tone, loaded only where a Surface
+ * asks for a mode its content is not in. The Theme comes from the root, which resolved both modes; its
+ * variables are written under `cssVarKey`, the class the Surface's box carries (`phi-tone-*`).
+ */
+export function PhiSurfaceToneScope({ mode, cssVarKey, source, children, }) {
+    return (_jsx(PhiNestedModeConfigProvider, { mode: mode, theme: source.themes[mode], cssVarKey: cssVarKey, locale: source.locale, customColors: source.customColorsByMode[mode], children: children }));
+}

package/components/surface/phi-surface-tone.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+import type { PhiThemeMode } from "../../theme/phi-theme-presets";
+import { type PhiSurfaceTone as PhiSurfaceToneValue } from "../../types/surface";
+/** The mode a tone asks for: `inverse` is the other mode than the page's. */
+export declare function resolvePhiSurfaceToneMode(tone: PhiSurfaceToneValue, pageMode: PhiThemeMode): PhiThemeMode | null;
+/**
+ * A Surface's content in the mode its `tone` asks for.
+ *
+ * Rendered inside the box, around its content; the box itself carries the tone's class
+ * (`resolvePhiSurfaceToneClassName`), and that class is where the other mode's variables are written. When
+ * the content is already in that mode -- the page is, or a Surface around it is -- nothing is mounted: the
+ * class then has no variables of its own and the content inherits the right ones. Otherwise the scope is
+ * loaded on its own, rendered on the server like everything else, and only where a page uses it.
+ */
+export declare function PhiSurfaceTone({ tone, children, }: {
+    tone: PhiSurfaceToneValue | null | undefined;
+    children: ReactNode;
+}): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;

package/components/surface/phi-surface-tone.js

@@ -0,0 +1,36 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { lazy, Suspense } from "react";
+import { usePhiConfig } from "../root/phi-config-provider";
+import { usePhiThemeToneSource } from "../root/phi-theme-tone-source";
+import { resolvePhiSurfaceToneClassName } from "../../types/surface";
+const PhiSurfaceToneScope = lazy(async () => ({
+    default: (await import("./phi-surface-tone-scope")).PhiSurfaceToneScope,
+}));
+/** The mode a tone asks for: `inverse` is the other mode than the page's. */
+export function resolvePhiSurfaceToneMode(tone, pageMode) {
+    if (tone === "light" || tone === "dark")
+        return tone;
+    if (tone === "inverse")
+        return pageMode === "dark" ? "light" : "dark";
+    return null;
+}
+/**
+ * A Surface's content in the mode its `tone` asks for.
+ *
+ * Rendered inside the box, around its content; the box itself carries the tone's class
+ * (`resolvePhiSurfaceToneClassName`), and that class is where the other mode's variables are written. When
+ * the content is already in that mode -- the page is, or a Surface around it is -- nothing is mounted: the
+ * class then has no variables of its own and the content inherits the right ones. Otherwise the scope is
+ * loaded on its own, rendered on the server like everything else, and only where a page uses it.
+ */
+export function PhiSurfaceTone({ tone, children, }) {
+    const { mode } = usePhiConfig();
+    const source = usePhiThemeToneSource();
+    const cssVarKey = resolvePhiSurfaceToneClassName(tone);
+    const target = tone && source ? resolvePhiSurfaceToneMode(tone, source.pageMode) : null;
+    if (!target || !source || !cssVarKey || target === mode) {
+        return children;
+    }
+    return (_jsx(Suspense, { fallback: null, children: _jsx(PhiSurfaceToneScope, { mode: target, cssVarKey: cssVarKey, source: source, children: children }) }));
+}

package/components/tables/client/phi-table-binding.d.ts

@@ -1,4 +1,4 @@
-import type { PhiTableProviderActionMutationRequest, PhiTableProviderDropMutationRequest, PhiTableProviderFieldMutationRequest, PhiTableProviderMutationRequest, PhiTableProviderMutationResult, PhiTableProviderQueryResult, PhiTableProviderResourceDescriptor, PhiTableProviderRowMoveMutationRequest, PhiTableProviderRowPatchMutationRequest, PhiTableQuery, PhiTableRowIdentity, PhiTableSummaryValue } from "../../../types/table-widget";
+import type { PhiTableProviderActionMutationRequest, PhiTableProviderDropMutationRequest, PhiTableProviderFieldMutationRequest, PhiTableProviderMutationRequest, PhiTableProviderMutationResult, PhiTableProviderQueryResult, PhiTableProviderResourceDescriptor, PhiTableProviderRowMoveMutationRequest, PhiTableProviderRowPatchMutationRequest, PhiTableQuery, PhiTableQueryValue, PhiTableRowIdentity, PhiTableSummaryValue } from "../../../types/table-widget";
 import type { PhiProviderResourceSource } from "../../../types/runtime-data-provider";
 import { PhiTableProviderError } from "../../../types/table-widget";
 type TableRow = Record<string, unknown>;
@@ -7,6 +7,8 @@ export type PhiTableBindingInput = {
     source: PhiProviderResourceSource | null;
     initialQuery?: PhiTableQuery;
     externalQuery?: PhiTableQuery;
+    /** Merged into every query last; see `PhiTableWidgetConfig.fixedFilters`. */
+    fixedFilters?: Readonly<Record<string, PhiTableQueryValue>>;
     externalSearch?: string;
     defaultPageSize?: number;
     refreshKey?: string | number;
@@ -16,7 +18,7 @@ export type PhiTableBindingInput = {
     onMutation?: (result: PhiTableProviderMutationResult) => void;
     validateResource?: (resource: PhiTableProviderResourceDescriptor) => string | null;
 };
-export declare function usePhiTableBinding({ source, initialQuery, externalQuery, externalSearch, defaultPageSize, refreshKey, preserveSelectedRowIdentities, initialExpandedRowIdentities, onData, onMutation, validateResource, }: PhiTableBindingInput): {
+export declare function usePhiTableBinding({ source, initialQuery, externalQuery, fixedFilters, externalSearch, defaultPageSize, refreshKey, preserveSelectedRowIdentities, initialExpandedRowIdentities, onData, onMutation, validateResource, }: PhiTableBindingInput): {
     resource: PhiTableProviderResourceDescriptor | null;
     bindingError: string | null;
     rows: readonly TableRow[];

package/components/tables/client/phi-table-binding.js

@@ -1,7 +1,8 @@
 "use client";
+import { isPhiRecord } from "../../../helpers/is-record";
 import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { PhiTableProviderError, readPhiTableProviderError, readPhiTableProviderMutationResult, readPhiTableProviderQueryResult, validatePhiTableProviderFieldValue, } from "../../../types/table-widget";
-import { movePhiTableBindingRows, movePhiTableBindingTreeRows, patchPhiTableBindingRows, readPhiTableRowIdentity, readPhiTableRowValue, restorePhiTableBindingRowOrder, } from "../../../helpers/table-binding";
+import { mergePhiTableQueryFilters, movePhiTableBindingRows, movePhiTableBindingTreeRows, patchPhiTableBindingRows, readPhiTableRowIdentity, readPhiTableRowValue, restorePhiTableBindingRowOrder, } from "../../../helpers/table-binding";
 import { usePhiTableProvider } from "../../widgets/client/shared/phi-table-provider";
 function validateProviderSummary(resource, summary) {
     if (!summary)
@@ -52,20 +53,17 @@ function createPhiTableQueryKey(query) {
         expandedRowIdentities: query.expandedRowIdentities ?? [],
     });
 }
-function resolvePhiTableQuery(query, externalQuery, externalSearch, expandedRowIdentities) {
+function resolvePhiTableQuery(query, externalQuery, externalSearch, expandedRowIdentities, fixedFilters) {
     return {
         ...query,
         ...externalQuery,
         search: externalSearch ?? externalQuery?.search ?? query.search,
         sorts: externalQuery?.sorts ?? query.sorts,
-        filters: {
-            ...(query.filters ?? {}),
-            ...(externalQuery?.filters ?? {}),
-        },
+        filters: mergePhiTableQueryFilters(query, externalQuery, fixedFilters),
         expandedRowIdentities,
     };
 }
-export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, externalSearch, defaultPageSize = 20, refreshKey, preserveSelectedRowIdentities = false, initialExpandedRowIdentities = [], onData, onMutation, validateResource, }) {
+export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, fixedFilters, externalSearch, defaultPageSize = 20, refreshKey, preserveSelectedRowIdentities = false, initialExpandedRowIdentities = [], onData, onMutation, validateResource, }) {
     const { provider, resource, bindingError } = usePhiTableProvider(source);
     const resourceError = resource ? validateResource?.(resource) ?? null : null;
     const [query, setQuery] = useState(() => ({
@@ -127,7 +125,13 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, e
         });
         return () => { cancelled = true; };
     }, [sourceKey]);
-    const resolvedQuery = useMemo(() => resolvePhiTableQuery(query, externalQuery, externalSearch, expandedRowIdentities), [expandedRowIdentities, externalQuery, externalSearch, query]);
+    /*
+     * Held by content, not identity: a caller that writes the object inline hands in a new one every
+     * render, and the query effect below would fetch again each time.
+     */
+    const fixedFiltersKey = JSON.stringify(fixedFilters ?? null);
+    const stableFixedFilters = useMemo(() => JSON.parse(fixedFiltersKey) ?? undefined, [fixedFiltersKey]);
+    const resolvedQuery = useMemo(() => resolvePhiTableQuery(query, externalQuery, externalSearch, expandedRowIdentities, stableFixedFilters), [expandedRowIdentities, externalQuery, externalSearch, stableFixedFilters, query]);
     const resolvedQueryKey = useMemo(() => createPhiTableQueryKey(resolvedQuery), [resolvedQuery]);
     const updateMutationTargetPending = useCallback((targetKey, pending) => {
         const current = pendingMutationCountsByTarget.current.get(targetKey) ?? 0;
@@ -233,7 +237,7 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, e
                 const resolvedQueryPatch = data.resolvedQuery;
                 if (resolvedQueryPatch) {
                     const canonicalInternalQuery = mergePhiTableQuery(query, resolvedQueryPatch);
-                    const canonicalQuery = resolvePhiTableQuery(canonicalInternalQuery, externalQuery, externalSearch, expandedRowIdentities);
+                    const canonicalQuery = resolvePhiTableQuery(canonicalInternalQuery, externalQuery, externalSearch, expandedRowIdentities, stableFixedFilters);
                     const canonicalQueryKey = createPhiTableQueryKey(canonicalQuery);
                     if (canonicalQueryKey !== resolvedQueryKey) {
                         acceptedResolvedQuery.current = {
@@ -258,7 +262,7 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, e
             }
         });
         return () => abortController.abort();
-    }, [applyData, expandedRowIdentities, externalQuery, externalSearch, provider, query, refreshKey, refreshRequest, resolvedQuery, resolvedQueryKey, resource, resourceError, source]);
+    }, [applyData, expandedRowIdentities, externalQuery, externalSearch, provider, query, refreshKey, refreshRequest, resolvedQuery, resolvedQueryKey, resource, resourceError, source, stableFixedFilters]);
     const reload = useCallback(() => setRefreshRequest((current) => ({
         revision: current.revision + 1,
         background: false,
@@ -419,7 +423,7 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, e
                             ? Array.isArray(value) && value.every((entry) => typeof entry === "string")
                             : action.valueType === "number[]"
                                 ? Array.isArray(value) && value.every((entry) => typeof entry === "number" && Number.isFinite(entry))
-                                : Boolean(value) && typeof value === "object" && !Array.isArray(value);
+                                : isPhiRecord(value);
         if (!valueValid) {
             const valueError = new PhiTableProviderError("action-value-invalid", `Table action "${request.actionKey}" received an incompatible value.`);
             setError(valueError);

package/components/trees/client/phi-tree-binding.js

@@ -23,6 +23,29 @@ function moveNodeOptimistically(nodes, identityPath, parentPath, request) {
     }
     return [...remaining.slice(0, insertIndex), moved, ...remaining.slice(insertIndex)];
 }
+/**
+ * Puts one moved node back where the snapshot from before its move had it: its old parent and its old
+ * place among the nodes, and nothing else. Whatever other changes landed since stay.
+ */
+function restoreMovedNode(nodes, previous, identityPath, parentPath, movedNodeIdentity) {
+    const matches = (node) => String(readPath(node, identityPath)) === String(movedNodeIdentity);
+    const previousIndex = previous.findIndex(matches);
+    const current = nodes.find(matches);
+    if (previousIndex < 0 || !current)
+        return nodes;
+    const remaining = nodes.filter((node) => !matches(node));
+    const restored = { ...current, [parentPath]: readPath(previous[previousIndex], parentPath) ?? null };
+    const insertIndex = Math.min(previousIndex, remaining.length);
+    return [...remaining.slice(0, insertIndex), restored, ...remaining.slice(insertIndex)];
+}
+/** What a mutation changes, so a later one on the same thing supersedes it and nothing else. */
+function readTreeMutationTarget(request) {
+    if (request.kind === "field")
+        return `field:${String(request.nodeIdentity)}:${request.fieldKey}`;
+    if (request.kind === "node-move")
+        return `move:${String(request.movedNodeIdentity)}`;
+    return null;
+}
 function validateTree(nodes, identityPath, parentPath) {
     const identities = new Set();
     for (const node of nodes) {
@@ -68,8 +91,19 @@ export function usePhiTreeBinding({ source, initialQuery = PHI_TREE_DEFAULT_INIT
     const [expandedNodeIdentities, setExpandedNodeIdentities] = useState(defaultExpandedNodeIdentities);
     const [refreshRevision, setRefreshRevision] = useState(0);
     const expandedInitialSnapshot = useRef(false);
+    const mutationSequence = useRef(0);
+    const latestMutationByTarget = useRef(new Map());
+    const mutationControllers = useRef(new Set());
     const sourceKey = useMemo(() => JSON.stringify(source), [source]);
     useEffect(() => { nodesRef.current = nodes; }, [nodes]);
+    useEffect(() => {
+        const controllers = mutationControllers.current;
+        return () => {
+            for (const controller of controllers)
+                controller.abort();
+            controllers.clear();
+        };
+    }, []);
     useEffect(() => {
         expandedInitialSnapshot.current = false;
         let cancelled = false;
@@ -124,6 +158,15 @@ export function usePhiTreeBinding({ source, initialQuery = PHI_TREE_DEFAULT_INIT
         });
         return () => controller.abort();
     }, [defaultExpandAll, provider, query, refreshRevision, resource, source]);
+    /*
+     * One change, shown before it is confirmed where the caller passes what it will look like.
+     *
+     * A failure takes back that change and nothing else -- the way the Table binding does: a field gets
+     * its original value back, a moved node its old parent and place. Restoring the whole snapshot from
+     * before the request used to throw away every change that landed in the meantime, so two quick edits
+     * whose first one failed lost the second as well. A later mutation of the same target supersedes an
+     * earlier one, whose answer is then not applied; leaving the tree aborts what is still in flight.
+     */
     const mutate = useCallback(async (request, optimisticNodes) => {
         if (bindingError || !provider || !resource || !source) {
             throw new PhiTreeProviderError("provider-unavailable", bindingError ?? "Tree Provider is unavailable.");
@@ -131,18 +174,39 @@ export function usePhiTreeBinding({ source, initialQuery = PHI_TREE_DEFAULT_INIT
         if (!provider.mutate)
             throw new PhiTreeProviderError("provider-read-only", `Tree Provider "${source.providerKey}" is read-only.`);
         const previous = nodesRef.current;
+        const targetKey = readTreeMutationTarget(request);
+        const requestId = ++mutationSequence.current;
+        if (targetKey)
+            latestMutationByTarget.current.set(targetKey, requestId);
+        const superseded = () => targetKey != null && latestMutationByTarget.current.get(targetKey) !== requestId;
         if (optimisticNodes) {
             nodesRef.current = optimisticNodes;
             setNodes(optimisticNodes);
         }
+        const restore = () => {
+            if (!optimisticNodes)
+                return;
+            const restored = request.kind === "field"
+                ? patchNode(nodesRef.current, resource.nodeIdentityPath, request.nodeIdentity, { [request.fieldKey]: request.originalValue })
+                : request.kind === "node-move"
+                    ? restoreMovedNode(nodesRef.current, previous, resource.nodeIdentityPath, resource.parentNodeIdentityPath, request.movedNodeIdentity)
+                    : nodesRef.current;
+            nodesRef.current = restored;
+            setNodes(restored);
+        };
+        const controller = new AbortController();
+        mutationControllers.current.add(controller);
         try {
-            const rawResult = await provider.mutate({ ...request, resourceKey: source.resourceKey, params: source.params, signal: new AbortController().signal });
+            const rawResult = await provider.mutate({ ...request, resourceKey: source.resourceKey, params: source.params, signal: controller.signal });
             const result = readPhiTreeProviderMutationResult(rawResult);
             if (!result)
                 throw new PhiTreeProviderError("invalid-mutation-result", "Tree Provider returned an invalid mutation result.");
+            if (controller.signal.aborted || superseded())
+                return result;
+            if (targetKey)
+                latestMutationByTarget.current.delete(targetKey);
             if (result.status === "rejected") {
-                nodesRef.current = previous;
-                setNodes(previous);
+                restore();
                 setError(new PhiTreeProviderError(result.errorCode ?? "mutation-rejected", result.message ?? "Tree change was rejected."));
             }
             else if (request.kind === "field") {
@@ -159,12 +223,20 @@ export function usePhiTreeBinding({ source, initialQuery = PHI_TREE_DEFAULT_INIT
             return result;
         }
         catch (mutationError) {
-            nodesRef.current = previous;
-            setNodes(previous);
             const nextError = readPhiTreeProviderError(mutationError);
+            if (controller.signal.aborted)
+                throw nextError;
+            if (!superseded()) {
+                if (targetKey)
+                    latestMutationByTarget.current.delete(targetKey);
+                restore();
+            }
             setError(nextError);
             throw nextError;
         }
+        finally {
+            mutationControllers.current.delete(controller);
+        }
     }, [bindingError, provider, resource, source]);
     const commitField = useCallback(async (nodeIdentity, fieldKey, proposedValue) => {
         if (!resource)
@@ -181,13 +253,19 @@ export function usePhiTreeBinding({ source, initialQuery = PHI_TREE_DEFAULT_INIT
         return mutate({ kind: "field", nodeIdentity, fieldKey, originalValue, proposedValue }, patchNode(nodesRef.current, resource.nodeIdentityPath, nodeIdentity, { [fieldKey]: proposedValue }));
     }, [mutate, resource]);
     const executeAction = useCallback((actionKey, nodeIdentity, actionValue) => mutate({ kind: "action", actionKey, nodeIdentity, selectedNodeIdentities, actionValue, query }), [mutate, query, selectedNodeIdentities]);
-    const moveNode = useCallback((request) => {
+    /*
+     * Async, so a move it refuses arrives as a rejection like any failed mutation -- a synchronous throw
+     * passed every `.catch` on the way -- and stands as the Tree's error, where the reader sees it.
+     */
+    const moveNode = useCallback(async (request) => {
         if (!resource)
             throw new PhiTreeProviderError("resource-unavailable", "Tree resource is unavailable.");
         let ancestor = request.targetParentNodeIdentity;
         while (ancestor != null) {
             if (String(ancestor) === String(request.movedNodeIdentity)) {
-                throw new PhiTreeProviderError("invalid-node-move", "A Tree node cannot be moved into itself or one of its descendants.");
+                const refused = new PhiTreeProviderError("invalid-node-move", "A Tree node cannot be moved into itself or one of its descendants.");
+                setError(refused);
+                throw refused;
             }
             const ancestorNode = nodesRef.current.find((node) => String(readPath(node, resource.nodeIdentityPath)) === String(ancestor));
             ancestor = ancestorNode ? readPath(ancestorNode, resource.parentNodeIdentityPath) : null;

package/components/widgets/builder/phi-static-options-picker.d.ts

@@ -1,4 +1,5 @@
 import type { PhiControlOption } from "../../controls/phi-control-options";
+/** A choice Widget's static options, edited in a dialog from its scaffold toolbar. */
 export declare function PhiStaticOptionsToolButton({ options, disabled, onApply, }: {
     options: readonly PhiControlOption[];
     disabled?: boolean;