@startsimpli/ui 0.4.136 → 0.4.137

package/src/components/history/useConditionalSave.ts

@@ -0,0 +1,356 @@
+'use client';
+
+/**
+ * useConditionalSave — every write carries the version it loaded, and a refusal
+ * KEEPS THE REVIEWER'S TEXT (bd startsim-jkkn7.3; server bd startsim-3c2wc).
+ *
+ * The loss this closes, as a person experiences it: two reviewers open one
+ * draft, the second save carries the first reviewer's field as the second page
+ * loaded it, the rewrite is gone and the response is 200. The server now refuses
+ * that second save with a 412 — and this hook is the half that decides what
+ * happens to the three paragraphs the reviewer had just typed.
+ *
+ * ── THE ONE INVARIANT, AND IT IS THE WHOLE BEAD ─────────────────────────────
+ *
+ * A 412 NEVER ADVANCES THE HELD VERSION, AND NEVER RETRIES.
+ *
+ * The tempting shortcut is to read `current_version` off the refusal, adopt it,
+ * and re-send. It makes the error go away and every happy-path test still
+ * passes — and it reduces the guard to a decoration, because a blind retry at
+ * the current version is EXACTLY the overwrite the 412 just prevented, with one
+ * extra round-trip. So the held version advances from one place only: a write
+ * that SUCCEEDED. Adopting `current_version` is a deliberate act a person takes
+ * ({@link ConditionalSave.keepMine} / {@link ConditionalSave.acceptTheirs}), and
+ * `a refusal does not advance the held version` is a test, not a comment.
+ *
+ * ── WHAT "KEEP THE USER'S TEXT" MEANS MECHANICALLY ──────────────────────────
+ *
+ * Three things, because the promise is worth nothing as an intention:
+ *
+ * 1. THIS HOOK NEVER OWNS THE DRAFT and never clears, resets or reverts it. A
+ *    refused save touches no local state but the conflict itself, so whatever is
+ *    in the editor stays in the editor.
+ * 2. THE REFUSED PAYLOAD IS RETAINED, on {@link StaleSaveConflict.refusedBody}.
+ *    This is the part that survives the ACCIDENTAL path, which is not the user
+ *    clicking something rash — it is the host refetching the record to show
+ *    "what changed" and its own load-into-editor effect overwriting the text
+ *    with the server's copy. The bytes are still here when that happens, so the
+ *    reviewer's work is recoverable rather than merely promised.
+ * 3. AUTOSAVE PAUSES AND THE CONFLICT SURFACES ONCE. The draft editor debounces
+ *    at 1,200 ms, so a 412 that neither paused nor deduplicated would repaint a
+ *    modal on every keystroke burst — worse than no dialog at all. While
+ *    {@link ConditionalSave.paused} holds, `save` returns without sending.
+ *
+ * DISMISSING IS NOT RESOLVING. Escape, the backdrop and the close button all
+ * land on {@link ConditionalSave.dismissConflict}, which closes the dialog and
+ * leaves the conflict and the pause in place. The reviewer keeps their text and
+ * can still reopen; what they cannot do is wander back into autosaving over
+ * somebody else's change because they pressed Escape.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import {
+  isVersion,
+  parseStaleSaveRefusal,
+  preconditionFor,
+  versionFromWriteOutcome,
+  newestRevision,
+  type PreconditionSpelling,
+  type ResponseHeaders,
+} from './conditional-write';
+import { normalizeRevision, type NormalizedRevision } from './revision-history';
+import type { RevisionClient } from './types';
+
+/** What the host sends. Merge `headers` into the request headers and `body` is
+ *  the request body — the precondition is already in whichever one the chosen
+ *  spelling uses. */
+export interface ConditionalWriteAttempt {
+  body: Record<string, unknown>;
+  headers: Record<string, string>;
+}
+
+/** What the host hands back. A plain `fetch` adapter is about eight lines. */
+export interface ConditionalWriteOutcome {
+  status?: number;
+  body?: unknown;
+  headers?: ResponseHeaders;
+}
+
+/**
+ * The one call this hook needs, injected exactly like {@link RevisionClient} —
+ * which is what keeps @startsimpli/api out of packages/ui.
+ *
+ * It may RESOLVE with a 412 outcome or THROW one; both are understood, because
+ * a plain `fetch` does the first and a wrapper does the second.
+ */
+export interface ConditionalWriteClient {
+  write: (attempt: ConditionalWriteAttempt) => Promise<ConditionalWriteOutcome>;
+}
+
+/** Why the dialog cannot name a person. Each reads differently to a reviewer,
+ *  and none of them may be rendered as "a machine did this". */
+export type IdentityGap = 'forbidden' | 'empty' | 'error' | 'no-client';
+
+export interface StaleSaveConflict {
+  /** The version the record is at NOW, straight off the refusal. */
+  currentVersion?: number;
+  /** The server's sentence. It names both versions and is safe to show. */
+  detail?: string;
+  /** The version the editor was holding when it was refused. */
+  sentVersion?: number;
+  /**
+   * THE REVIEWER'S TEXT, as the server refused it. Retained so it is
+   * recoverable even if the host reloaded the server's copy over the editor.
+   */
+  refusedBody: Record<string, unknown>;
+  /** The newest row of the trail — who changed it, when, and which fields.
+   *  Absent whenever {@link identityGap} is set. */
+  changedBy?: NormalizedRevision;
+  /** Set when the trail could not say who. The dialog still works. */
+  identityGap?: IdentityGap;
+}
+
+export type ConditionalSaveResult =
+  | { status: 'saved'; version?: number; outcome: ConditionalWriteOutcome }
+  | { status: 'refused'; conflict: StaleSaveConflict }
+  /** A conflict is already open: nothing was sent. */
+  | { status: 'paused' }
+  | { status: 'failed'; error: unknown };
+
+export interface UseConditionalSaveOptions {
+  client: ConditionalWriteClient;
+  /** The version the record was loaded at. Seeding this is what makes the FIRST
+   *  save guarded; without it the first write is unguarded and the trail says
+   *  so (`precondition: "none"`). */
+  version?: number;
+  /** Reads `/api/v1/entities/<id>/revisions/` for the human-readable half. The
+   *  412 carries no identity by design (bd startsim-j4kx6) — without this the
+   *  dialog still opens and simply does not name anyone. */
+  revisions?: RevisionClient;
+  /** `header` (default) sends `If-Match` and leaves the body untouched. */
+  spelling?: PreconditionSpelling;
+}
+
+export interface ConditionalSave {
+  /** The version every write will assert. `undefined` means unguarded. */
+  version?: number;
+  /** Seed or re-seed it — on load, and after the host reloads the record. */
+  setVersion: (version: number | undefined) => void;
+  /** Whether the next save will actually assert a version. */
+  guarded: boolean;
+  save: (body: Record<string, unknown>) => Promise<ConditionalSaveResult>;
+  conflict: StaleSaveConflict | null;
+  /** An unresolved conflict: autosave must not fire. Stays true across a
+   *  dismissal, because dismissing is not resolving. */
+  paused: boolean;
+  /** Whether the dialog should be on screen. */
+  dialogOpen: boolean;
+  /** Close the dialog. KEEPS the text, the conflict and the pause. */
+  dismissConflict: () => void;
+  reopenConflict: () => void;
+  /** Deliberately overwrite their change with the refused text, at the version
+   *  the server named. The only path that adopts `current_version`. */
+  keepMine: () => Promise<ConditionalSaveResult>;
+  /** Give up the local edit: clear the conflict and adopt their version so the
+   *  host can reload. Destructive to the reviewer's text BY DESIGN, which is
+   *  why nothing but an explicit choice reaches it. */
+  acceptTheirs: () => void;
+  /** A `keepMine` is in flight. */
+  resolving: boolean;
+  /** The last non-412 failure, since `save` reports rather than throws. */
+  lastError: unknown;
+}
+
+export function useConditionalSave({
+  client,
+  version: initialVersion,
+  revisions,
+  spelling = 'header',
+}: UseConditionalSaveOptions): ConditionalSave {
+  const [version, setVersionState] = useState<number | undefined>(initialVersion);
+  const [conflict, setConflict] = useState<StaleSaveConflict | null>(null);
+  const [dismissed, setDismissed] = useState(false);
+  const [resolving, setResolving] = useState(false);
+  const [lastError, setLastError] = useState<unknown>(null);
+
+  // Read inside `save` so a stale closure cannot send a version the hook has
+  // already moved past, and so `paused` is evaluated against the live conflict
+  // rather than the one captured when the debounce was scheduled.
+  const versionRef = useRef(version);
+  versionRef.current = version;
+  const conflictRef = useRef(conflict);
+  conflictRef.current = conflict;
+
+  // The identity fetch resolves after the conflict is already on screen, so it
+  // must not write into a hook that has unmounted or already moved on.
+  const alive = useRef(true);
+  useEffect(() => {
+    alive.current = true;
+    return () => {
+      alive.current = false;
+    };
+  }, []);
+
+  const setVersion = useCallback((next: number | undefined) => {
+    setVersionState(isVersion(next) ? next : undefined);
+  }, []);
+
+  // Re-seed when the host loads a different record. Guarded on the value so a
+  // save's own advance is not stomped by a re-render carrying the old prop.
+  const seeded = useRef(initialVersion);
+  useEffect(() => {
+    if (seeded.current !== initialVersion) {
+      seeded.current = initialVersion;
+      setVersionState(isVersion(initialVersion) ? initialVersion : undefined);
+    }
+  }, [initialVersion]);
+
+  /** Fill in "who changed it" after the dialog is already up. Never blocks the
+   *  conflict from surfacing, and never throws into the save path. */
+  const resolveIdentity = useCallback(
+    async (key: StaleSaveConflict) => {
+      const patch = (gap: IdentityGap) => {
+        if (!alive.current) return;
+        setConflict((current) => (current === key ? { ...current, identityGap: gap } : current));
+      };
+      if (!revisions) return patch('no-client');
+      try {
+        const page = await revisions.list({ page: 1, pageSize: 1 });
+        const row = newestRevision(page?.results);
+        if (!alive.current) return;
+        if (!row) return patch('empty');
+        setConflict((current) =>
+          current === key ? { ...current, changedBy: normalizeRevision(row) } : current,
+        );
+      } catch (error) {
+        // A 404 on this nested route means the caller may not read the PARENT
+        // record, so history is withheld rather than absent — a different
+        // sentence, and never an empty trail.
+        patch(parseStatus(error) === 404 ? 'forbidden' : 'error');
+      }
+    },
+    [revisions],
+  );
+
+  const refuse = useCallback(
+    (
+      refusedBody: Record<string, unknown>,
+      sent: number | undefined,
+      refusal: { currentVersion?: number; detail?: string },
+    ): ConditionalSaveResult => {
+      const next: StaleSaveConflict = {
+        ...refusal,
+        ...(sent !== undefined ? { sentVersion: sent } : {}),
+        refusedBody,
+      };
+      if (alive.current) {
+        // NOTE WHAT IS NOT HERE: setVersionState. The refusal names the current
+        // version and this hook deliberately declines to take it.
+        setConflict(next);
+        setDismissed(false);
+        setLastError(null);
+        void resolveIdentity(next);
+      }
+      return { status: 'refused', conflict: next };
+    },
+    [resolveIdentity],
+  );
+
+  const attempt = useCallback(
+    async (
+      body: Record<string, unknown>,
+      assertVersion: number | undefined,
+    ): Promise<ConditionalSaveResult> => {
+      const parts = preconditionFor(assertVersion, spelling);
+      try {
+        const outcome = await client.write({
+          body: { ...body, ...parts.body },
+          headers: { ...parts.headers },
+        });
+        const refusal = parseStaleSaveRefusal(outcome);
+        if (refusal) return refuse(body, assertVersion, refusal);
+        const next = versionFromWriteOutcome(outcome ?? {});
+        if (alive.current) {
+          // THE ONLY PLACE THE HELD VERSION ADVANCES.
+          if (next !== undefined) setVersionState(next);
+          setConflict(null);
+          setDismissed(false);
+          setLastError(null);
+        }
+        return { status: 'saved', ...(next !== undefined ? { version: next } : {}), outcome };
+      } catch (error) {
+        const refusal = parseStaleSaveRefusal(error);
+        if (refusal) return refuse(body, assertVersion, refusal);
+        if (alive.current) setLastError(error);
+        return { status: 'failed', error };
+      }
+    },
+    [client, refuse, spelling],
+  );
+
+  const save = useCallback(
+    async (body: Record<string, unknown>): Promise<ConditionalSaveResult> => {
+      // Surfaced once, not retried. An unresolved conflict means the reviewer
+      // still has a decision to make and their keystrokes must not re-send.
+      if (conflictRef.current) return { status: 'paused' };
+      return attempt(body, versionRef.current);
+    },
+    [attempt],
+  );
+
+  const keepMine = useCallback(async (): Promise<ConditionalSaveResult> => {
+    const current = conflictRef.current;
+    if (!current) return { status: 'paused' };
+    // Adopting `current_version` is legitimate HERE and nowhere else: a person
+    // has been told what changed and has chosen to replace it.
+    const target = isVersion(current.currentVersion) ? current.currentVersion : undefined;
+    // The pause is NOT lifted here. `save` stays refused for the whole of this
+    // round-trip, so a debounce that fires mid-resolution cannot send the same
+    // body a second time and race the write this call is already making.
+    setResolving(true);
+    try {
+      return await attempt(current.refusedBody, target);
+    } finally {
+      if (alive.current) setResolving(false);
+    }
+  }, [attempt]);
+
+  const acceptTheirs = useCallback(() => {
+    const current = conflictRef.current;
+    setVersionState(isVersion(current?.currentVersion) ? current!.currentVersion : undefined);
+    setConflict(null);
+    setDismissed(false);
+  }, []);
+
+  const dismissConflict = useCallback(() => setDismissed(true), []);
+  const reopenConflict = useCallback(() => setDismissed(false), []);
+
+  return {
+    ...(version !== undefined ? { version } : {}),
+    setVersion,
+    guarded: isVersion(version),
+    save,
+    conflict,
+    paused: conflict !== null,
+    dialogOpen: conflict !== null && !dismissed,
+    dismissConflict,
+    reopenConflict,
+    keepMine,
+    acceptTheirs,
+    resolving,
+    lastError,
+  };
+}
+
+function parseStatus(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object') return undefined;
+  const candidate = error as {
+    status?: unknown;
+    statusCode?: unknown;
+    response?: { status?: unknown };
+  };
+  for (const raw of [candidate.status, candidate.statusCode, candidate.response?.status]) {
+    if (typeof raw === 'number') return raw;
+  }
+  return undefined;
+}