portal-mojo 0.2.3 → 0.2.5

package/src/ui/form-autosave.ts

@@ -20,6 +20,12 @@
 //   · zod failure: the save of that field is blocked client-side; the message
 //     occupies the same error slot. Hidden (showWhen) fields never queue and
 //     their transient state clears.
+//   · beforeSave (optional): runs once per batch BEFORE the POST, with the
+//     wire body. While it awaits the batch counts as in flight (the timer
+//     cannot re-fire; a commit meanwhile joins the NEXT batch). `false`
+//     DROPS the batch: its names revert to the server snapshot and go idle
+//     — no error, no toast (a guardrail the operator declined is not a
+//     failure). An object REPLACES the body. true/undefined proceeds.
 //
 // Shape: ALL machine state lives in ONE reducer (draft values, server
 // snapshot, per-field status, the pending batch, the in-flight flag) so every
@@ -168,6 +174,8 @@ export type AutosaveAction =
     | { type: 'SAVE_OK'; names: string[]; sent: Record<string, FieldValue>; server: FieldValues }
     /** Batch rejected: REVERT names to the snapshot, pin the server message. */
     | { type: 'SAVE_FAIL'; names: string[]; error: string }
+    /** beforeSave vetoed: REVERT names to the snapshot, status idle, no error. */
+    | { type: 'BATCH_DROP'; names: string[] }
     /** The ~1.5s saved flash ended. */
     | { type: 'FLASH_DONE'; name: string }
     /** The row prop changed (refetch/invalidate) or fields arrived late. */
@@ -366,6 +374,22 @@ export function autosaveReducer(state: AutosaveState, action: AutosaveAction): A
             return { ...state, draft, pending, fieldState, fieldError, inflight: false };
         }
 
+        case 'BATCH_DROP': {
+            const draft = { ...state.draft };
+            const fieldState = { ...state.fieldState };
+            const fieldError = { ...state.fieldError };
+            for (const n of action.names) {
+                // A field re-committed while beforeSave awaited belongs to the
+                // NEXT batch (SAVE_OK precedent) — the veto covers only what
+                // this batch carried.
+                if (n in state.pending) continue;
+                if (n in state.server) draft[n] = state.server[n]!;
+                fieldState[n] = 'idle';
+                fieldError[n] = null;
+            }
+            return { ...state, draft, fieldState, fieldError, inflight: false };
+        }
+
         case 'FLASH_DONE': {
             if (state.fieldState[action.name] !== 'saved') return state;
             return { ...state, fieldState: { ...state.fieldState, [action.name]: 'idle' } };
@@ -387,6 +411,83 @@ export function autosaveReducer(state: AutosaveState, action: AutosaveAction): A
     }
 }
 
+// ── The batch runner ──────────────────────────────────────────────────
+// Pure orchestration over the reducer — exported so the contract (veto /
+// amend / concurrent commit / no-hook parity) is unit-testable without a
+// DOM (scripts/verify-form-autosave.mjs). The hook binds it to its refs.
+
+export interface AutosaveBatchRunnerDeps<T> {
+    /** The state snapshot at fire time. */
+    state: AutosaveState;
+    /** Current options, captured once for this batch and its settlement. */
+    opts: () => Pick<UseFormAutosaveOptions<T>, 'fields' | 'row' | 'save' | 'beforeSave' | 'onSaved' | 'onSaveError'>;
+    dispatch: (action: AutosaveAction) => void;
+    /** Re-arm the batch window (drain anything committed mid-flight). */
+    armBatchTimer: () => void;
+    /** Start a field's saved flash. */
+    armFlashTimer: (name: string) => void;
+}
+
+/**
+ * Fire one batch from `state.pending`. Resolves when the batch has settled
+ * (saved, failed, or dropped); resolves immediately when nothing fires
+ * (in flight, or nothing pending).
+ */
+export function runAutosaveBatch<T>(deps: AutosaveBatchRunnerDeps<T>): Promise<void> {
+    const { state: s, opts, dispatch, armBatchTimer, armFlashTimer } = deps;
+    if (s.inflight) return Promise.resolve(); // completion re-arms the timer (serialize)
+    const names = Object.keys(s.pending);
+    if (names.length === 0) return Promise.resolve();
+    const sent: Record<string, FieldValue> = { ...s.pending };
+    const changes = expandDotted(sent);
+    // The approval, write target and callbacks belong to the same batch.
+    // Reading opts again after a gate can redirect an approved write to a
+    // different row/model rendered while the confirmation was open.
+    const batch = opts();
+    dispatch({ type: 'BATCH_START', names });
+
+    const post = (body: Record<string, unknown>): Promise<void> => batch.save(body).then(
+        (savedRow) => {
+            const server = serverValuesFor(batch.fields, savedRow);
+            dispatch({ type: 'SAVE_OK', names, sent, server });
+            for (const n of names) armFlashTimer(n);
+            batch.onSaved?.({ changes: body, fields: names, row: savedRow });
+            armBatchTimer(); // drain anything committed mid-flight
+        },
+        (err: unknown) => fail(body, err),
+    );
+    const fail = (body: Record<string, unknown>, err: unknown) => {
+        const error = err instanceof Error ? err : new Error('Save failed');
+        dispatch({ type: 'SAVE_FAIL', names, error: error.message });
+        batch.onSaveError?.({ changes: body, fields: names, error });
+        armBatchTimer();
+    };
+
+    const beforeSave = batch.beforeSave;
+    if (!beforeSave) return post(changes); // no hook: the pre-existing path, unchanged
+
+    // The gate. BATCH_START already flagged inflight, so the window cannot
+    // re-fire while this awaits and commits meanwhile queue the NEXT batch.
+    let verdict: Promise<boolean | void | Record<string, unknown>>;
+    try {
+        verdict = Promise.resolve(beforeSave({ changes, names, row: batch.row }));
+    } catch (err) {
+        verdict = Promise.reject(err);
+    }
+    return verdict.then(
+        (v) => {
+            if (v === false) {
+                dispatch({ type: 'BATCH_DROP', names });
+                armBatchTimer(); // a commit made during the await fires next
+                return;
+            }
+            const body = v !== null && typeof v === 'object' ? v : changes;
+            return post(body);
+        },
+        (err: unknown) => fail(changes, err),
+    );
+}
+
 // ── The hook ──────────────────────────────────────────────────────────
 
 export interface AutosaveBatchInfo {
@@ -396,6 +497,24 @@ export interface AutosaveBatchInfo {
     fields: string[];
 }
 
+export interface AutosaveBeforeSaveInfo<T> {
+    /** The wire body about to POST (dotted names expanded). */
+    changes: Record<string, unknown>;
+    /** Flat field names the batch carries (`permissions.manage_group`, …). */
+    names: string[];
+    /** The server row the batch edits. */
+    row: T;
+}
+
+/**
+ * Pre-save gate. `false` drops the batch (fields revert to server values,
+ * status → idle, no error toast); an object replaces `changes`; `true` /
+ * `undefined` proceeds. A thrown/rejected hook is a bug, not a veto — it is
+ * surfaced like a failed save (revert + pinned error + onSaveError).
+ */
+export type AutosaveBeforeSave<T> = (info: AutosaveBeforeSaveInfo<T>) =>
+    boolean | void | Record<string, unknown> | Promise<boolean | void | Record<string, unknown>>;
+
 export interface UseFormAutosaveOptions<T> {
     /** EVERY saveable field — flat fields plus every tab's fields. */
     fields: Field[];
@@ -403,6 +522,14 @@ export interface UseFormAutosaveOptions<T> {
     row: T;
     /** One batch POST. MUST reject on failure (defineModel useSave contract). */
     save: (changes: Record<string, unknown>) => Promise<T>;
+    /**
+     * Runs before a batch POSTs. Return false to drop the batch (fields
+     * revert to server values, status → idle, no error toast); return an
+     * object to replace `changes`; true/undefined to proceed. While it awaits
+     * the batch is in flight: the timer cannot re-fire and a commit meanwhile
+     * joins the NEXT batch.
+     */
+    beforeSave?: AutosaveBeforeSave<T>;
     /** Batch window after the last commit (web-mojo: 300). */
     debounceMs?: number;
     /** How long the 'saved' check shows before returning to idle. */
@@ -485,29 +612,13 @@ export function useFormAutosave<T>(opts: UseFormAutosaveOptions<T>): FormAutosav
 
     // ── the batch runner ──────────────────────────────────────────────
     const fireBatch = useCallback(() => {
-        const s = stateRef.current;
-        if (s.inflight) return; // completion re-arms the timer (serialize)
-        const names = Object.keys(s.pending);
-        if (names.length === 0) return;
-        const sent: Record<string, FieldValue> = { ...s.pending };
-        const changes = expandDotted(sent);
-        dispatch({ type: 'BATCH_START', names });
-
-        optsRef.current.save(changes).then(
-            (savedRow) => {
-                const server = serverValuesFor(optsRef.current.fields, savedRow);
-                dispatch({ type: 'SAVE_OK', names, sent, server });
-                for (const n of names) armFlashTimer(n);
-                optsRef.current.onSaved?.({ changes, fields: names, row: savedRow });
-                armBatchTimer(); // drain anything committed mid-flight
-            },
-            (err: unknown) => {
-                const error = err instanceof Error ? err : new Error('Save failed');
-                dispatch({ type: 'SAVE_FAIL', names, error: error.message });
-                optsRef.current.onSaveError?.({ changes, fields: names, error });
-                armBatchTimer();
-            },
-        );
+        void runAutosaveBatch<T>({
+            state: stateRef.current,
+            opts: () => optsRef.current,
+            dispatch,
+            armBatchTimer,
+            armFlashTimer,
+        });
     }, [armBatchTimer, armFlashTimer]);
     fireBatchRef.current = fireBatch;
 

package/src/ui/guardrail.tsx

@@ -0,0 +1,125 @@
+// Guardrail — the "are you sure, and here is WHY" stop in front of a change
+// that takes a tenant dark, moves money, or cannot be undone if made by
+// accident. One shape for every breaking knob so the operator learns to read
+// it: what happens the moment it lands, why that is dangerous (concrete
+// consequences, not adjectives), how to get back — and, for the sharpest
+// knobs, a typed literal before the button arms.
+//
+// Promoted from wmx-admin-v2 `src/lib/guardrail.tsx` (bc3e900) verbatim in
+// contract and markup so the app's copy keeps working when it swaps the
+// import. Built on the native-<dialog> `modal.open` stack, so it stacks
+// correctly over a formModal that is still open.
+//
+// Which stop to reach for:
+//   · `modal.confirm`    — reversible / low blast radius; a yes-no.
+//   · `ArmedButton`      — irreversible, needs no input, inline (row actions).
+//   · `confirmGuardrail` — anything that takes a tenant dark, moves money, or
+//                          can't be undone — the operator must read WHY.
+//
+// Usage — `if (!(await confirmGuardrail({...}))) return;` before the mutation.
+// The dialog resolves false on Escape / backdrop / Cancel, true only on the
+// armed confirm button.
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { modal } from './modal';
+
+export interface Guardrail {
+    /** Question form, naming the target: "Disable Alea for Club Axo?" */
+    title: string;
+    /** What happens the moment this lands — present tense, one or two sentences. */
+    effect: ReactNode;
+    /** Why it is dangerous — each item one concrete consequence. */
+    why: ReactNode[];
+    /** How to get back, or that you can't. */
+    undo?: ReactNode;
+    confirmText: string;
+    cancelText?: string;
+    /**
+     * Highest tier: the operator must type this literal (the brand name, a
+     * count, "DISABLE") before the confirm button arms. Compared trimmed and
+     * case-insensitively.
+     */
+    typeToConfirm?: string;
+    /** false = primary button + warn tint for a stop that is not destructive. Default true. */
+    danger?: boolean;
+}
+
+function GuardrailBody({ g, close }: { g: Guardrail; close: (v: boolean) => void }) {
+    const [typed, setTyped] = useState('');
+    const inputRef = useRef<HTMLInputElement>(null);
+    const needsTyping = Boolean(g.typeToConfirm);
+    const armed = !needsTyping || typed.trim().toLowerCase() === g.typeToConfirm!.trim().toLowerCase();
+    const danger = g.danger !== false;
+
+    useEffect(() => {
+        if (needsTyping) inputRef.current?.focus();
+    }, [needsTyping]);
+
+    return (
+        <div className={danger ? 'modal-pad guardrail' : 'modal-pad guardrail guardrail-warn'}>
+            <h2 className="modal-title">
+                <i className={`bi ${danger ? 'bi-exclamation-octagon-fill' : 'bi-exclamation-triangle-fill'} guardrail-icon`} /> {g.title}
+            </h2>
+            <div className="modal-message">
+                <p className="guardrail-effect">{g.effect}</p>
+                <div className="guardrail-why">
+                    <div className="guardrail-why-head">Why this is dangerous</div>
+                    <ul>
+                        {g.why.map((w, i) => <li key={i}>{w}</li>)}
+                    </ul>
+                </div>
+                {g.undo && (
+                    <p className="guardrail-undo"><i className="bi bi-arrow-counterclockwise" /> {g.undo}</p>
+                )}
+                {needsTyping && (
+                    <label className="guardrail-type">
+                        <span>Type <b>{g.typeToConfirm}</b> to confirm</span>
+                        <input
+                            ref={inputRef}
+                            className="input"
+                            value={typed}
+                            autoComplete="off"
+                            spellCheck={false}
+                            onChange={(e) => setTyped(e.target.value)}
+                            onKeyDown={(e) => { if (e.key === 'Enter' && armed) close(true); }}
+                        />
+                    </label>
+                )}
+            </div>
+            <div className="modal-actions">
+                <button type="button" className="btn" onClick={() => close(false)}>{g.cancelText ?? 'Cancel'}</button>
+                <button
+                    type="button"
+                    className={danger ? 'btn btn-danger' : 'btn btn-primary'}
+                    disabled={!armed}
+                    onClick={() => close(true)}
+                >
+                    {g.confirmText}
+                </button>
+            </div>
+        </div>
+    );
+}
+
+/** Open the guardrail and resolve true only when the operator confirms. */
+export function confirmGuardrail(g: Guardrail): Promise<boolean> {
+    return modal.open<boolean>((close) => <GuardrailBody g={g} close={close} />, { size: 'sm' })
+        .then((v) => v === true);
+}
+
+/**
+ * Diff helper for config-form saves: which of the watched keys changed
+ * between what the form was seeded with and what came back. Lets a save
+ * confirm ONLY the fields that break things (environment, currency codes…)
+ * and pass silently otherwise.
+ */
+export function changedKeys(
+    initial: Record<string, unknown>,
+    next: Record<string, unknown>,
+    watch: readonly string[],
+): string[] {
+    return watch.filter((k) => {
+        const a = initial[k]; const b = next[k];
+        const norm = (v: unknown) => (v == null || v === '' ? '' : String(v));
+        return norm(a) !== norm(b);
+    });
+}

package/src/ui/index.ts

@@ -9,6 +9,7 @@ export * from './RequiresGroup';
 export * from './menu-registry';
 export * from './SidebarNav';
 export * from './armed-button';
+export * from './guardrail';
 export * from './loading';
 export * from './CollectionMultiSelect';
 export * from './CollectionSelect';

package/src/ui/toast.tsx

@@ -18,7 +18,8 @@
 // Visual spec from web-mojo's toast.css (left accent bar, compact card,
 // bottom-right); idiom styles live in the app's theme/idioms.css — tokens
 // only, both themes.
-import { useSyncExternalStore } from 'react';
+import { useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { createPortal } from 'react-dom';
 
 type Level = 'success' | 'error' | 'info' | 'warning';
 
@@ -187,8 +188,50 @@ export function ToastHost() {
         (cb) => { listeners.add(cb); return () => listeners.delete(cb); },
         () => toasts,
     );
-    return (
-        <div className="toast-host" role="status" aria-live="polite">
+    // Keep one portal target so moving above a new modal preserves live cards.
+    const [host] = useState(() => typeof document === 'undefined' ? null : document.createElement('div'));
+    const visible = useRef(false);
+    visible.current = items.length > 0;
+    const syncHost = useRef<() => void>(() => {});
+    useLayoutEffect(() => {
+        if (!host) return;
+        host.className = 'toast-host';
+        host.setAttribute('role', 'status');
+        host.setAttribute('aria-live', 'polite');
+        const supportsPopover = typeof host.showPopover === 'function';
+        if (supportsPopover) host.setAttribute('popover', 'manual');
+        let dialogs: HTMLDialogElement[] = [];
+        const sync = (records: MutationRecord[] = []) => {
+            const open = Array.from(document.querySelectorAll('dialog')).filter(dialog => dialog.matches(':modal'));
+            dialogs = dialogs.filter(dialog => open.includes(dialog));
+            for (const dialog of open) if (!dialogs.includes(dialog)) dialogs.push(dialog);
+            // Opening order, not DOM order, determines the active native modal.
+            for (const record of records) {
+                if (record.type !== 'attributes' || record.oldValue !== null || !(record.target instanceof HTMLDialogElement) || !open.includes(record.target)) continue;
+                dialogs = [...dialogs.filter(dialog => dialog !== record.target), record.target];
+            }
+            const parent = dialogs.at(-1) ?? document.body;
+            const moved = host.parentElement !== parent;
+            if (supportsPopover && host.matches(':popover-open') && (moved || !visible.current)) host.hidePopover();
+            // A body-level popover paints above dialogs but remains inert.
+            // Modal-local ancestry is required for Undo/Cancel and keyboard use.
+            if (moved) parent.appendChild(host);
+            if (supportsPopover && visible.current && !host.matches(':popover-open')) host.showPopover();
+        };
+        syncHost.current = sync;
+        const observer = new MutationObserver(sync);
+        observer.observe(document.body, { subtree: true, childList: true, attributes: true, attributeFilter: ['open'], attributeOldValue: true });
+        sync();
+        return () => {
+            observer.disconnect();
+            syncHost.current = () => {};
+            if (supportsPopover && host.matches(':popover-open')) host.hidePopover();
+            host.remove();
+        };
+    }, [host]);
+    useLayoutEffect(() => { syncHost.current(); }, [items.length > 0]);
+    return host ? createPortal(
+        <>
             {items.map((t) => {
                 if (t.kind === 'basic') {
                     return (
@@ -214,6 +257,6 @@ export function ToastHost() {
                 }
                 return <ProgressCard key={t.id} t={t} />;
             })}
-        </div>
-    );
+        </>, host,
+    ) : null;
 }