@startsimpli/ui 0.4.140 → 0.4.142

package/src/components/history/RecordHistoryPanel.tsx

@@ -40,30 +40,60 @@
  *    because this route serves every historical value a record ever held, so it
  *    is a richer leak than the row read — and because a `{}` rendered silently
  *    reads as data loss.
- * 3. THAT THE TRAIL IS NOT THE WHOLE STORY. Four write paths record NO revision
- *    today — `annotate`, `move-scope`, `DELETE` and the ingestion worker
- *    (bd startsim-jkkn7.6). The version sequence is still provably gapless
- *    (a write that records nothing allocates no number), so there is no hole to
- *    see — which is exactly why it has to be SAID. A reader must not conclude
- *    from a quiet trail that no machine touched this record. The panel
- *    therefore never claims completeness, and its empty state says "no edits
- *    recorded" and not "never changed".
+ * 3. WHEN HISTORY IS DECLARED OFF FOR THIS KIND OF RECORD. Every write path
+ *    records a revision now — `annotate`, `move-scope`, `DELETE` and the
+ *    ingestion worker were the last four, closed by bd startsim-jkkn7.6 — so the
+ *    old standing caveat that "some writes are not recorded yet" described a gap
+ *    that no longer exists, and was removed (bd startsim-jkkn7.11). What CAN
+ *    still leave a trail empty is a DECLARATION: `EntityTypeDef.config.history
+ *    = {"enabled": false}` on the type (or the reserved `"*"` row). That is a
+ *    decision somebody made, not a silent door, so it gets different words —
+ *    "history is not recorded for this kind of record" — and it is said only
+ *    when the policy says so: the host's `historyEnabled={false}`, or — since
+ *    bd startsim-jkkn7.17 put the resolved policy on the revisions envelope —
+ *    `history.enabled: false` on the first page. Otherwise the empty state
+ *    says "no edits recorded" and nothing more — and never "never changed".
+ *
+ * ── RESTORE (bd startsim-zkyk4; route bd startsim-ti1yv) ────────────────────
+ *
+ * "Restore this value" on a changed field and "Restore this version" on a row,
+ * offered only when the host injects `client.restore` and only where it would
+ * change something. Nothing is written until {@link RestoreConfirmDialog} has
+ * shown what will move, computed from the trail this panel already holds by the
+ * same backwards undo the server runs. Every restore carries the version the
+ * HOST holds (`currentVersion`, read at confirm time so an autosave in between
+ * is honoured) — the route 428s without one — and a 412 reuses StaleSaveDialog,
+ * where only an explicit "restore anyway" adopts the version the refusal named.
+ * A narrowed (`?field=`) trail is that field's own, so it never offers a
+ * whole-record restore.
  */
-import { ReactNode, useMemo } from 'react';
-import { useInfiniteQuery } from '@tanstack/react-query';
-import { Bot, FilePlus2, Pencil, ShieldAlert, Tag } from 'lucide-react';
+import { ReactNode, useCallback, useMemo, useRef, useState } from 'react';
+import { useInfiniteQuery, useQueryClient } from '@tanstack/react-query';
+import { Bot, FilePlus2, Pencil, ShieldAlert, Tag, Undo2, X } from 'lucide-react';
 
 import { ActivityTimeline, type ActivityTimelineItem } from '../ActivityTimeline';
 import { ErrorState } from '../states';
 import { RevisionFields } from './RevisionFields';
+import { RestoreConfirmDialog } from './RestoreConfirmDialog';
+import { StaleSaveDialog } from './StaleSaveDialog';
+import type { StaleSaveConflict } from './useConditionalSave';
+import { newestRevision } from './conditional-write';
+import {
+  latestFieldVersions,
+  parseRestoreOutcome,
+  restorePreview,
+  type ParsedRestoreOutcome,
+  type RestorePreview,
+} from './restore';
 import {
   COLLAPSE_WINDOW_MS,
   foldRevisions,
+  normalizeRevision,
   sittingHeadline,
   sittingSummary,
   type RevisionSitting,
 } from './revision-history';
-import type { EntityRevision, RevisionClient, RevisionPage } from './types';
+import type { EntityRevision, RestoreRequest, RevisionClient, RevisionPage } from './types';
 import {
   RECORD_HISTORY_PANEL_DEFAULTS,
   type RecordHistoryPanelClassNames,
@@ -77,6 +107,7 @@ export const REVISION_ENTRY_TYPES = {
   renamed: 'revision_renamed',
   attempt: 'revision_attempt',
   machine: 'revision_machine',
+  restored: 'revision_restored',
 } as const;
 
 const DEFAULT_ICONS = {
@@ -85,10 +116,14 @@ const DEFAULT_ICONS = {
   [REVISION_ENTRY_TYPES.renamed]: Tag,
   [REVISION_ENTRY_TYPES.attempt]: ShieldAlert,
   [REVISION_ENTRY_TYPES.machine]: Bot,
+  [REVISION_ENTRY_TYPES.restored]: Undo2,
 };
 
-function entryType(sitting: RevisionSitting): string {
+/** The timeline entry type for a sitting. Exported so the cross-record feed
+ *  (RecordActivityPanel) icons a row exactly as this panel does. */
+export function revisionEntryType(sitting: RevisionSitting): string {
   if (sitting.isAttempt) return REVISION_ENTRY_TYPES.attempt;
+  if (sitting.restoredFrom !== undefined) return REVISION_ENTRY_TYPES.restored;
   if (sitting.action === 'created') return REVISION_ENTRY_TYPES.created;
   if (sitting.actorKind === 'machine') return REVISION_ENTRY_TYPES.machine;
   if (Object.keys(sitting.changed).length === 0 && sitting.name) {
@@ -97,10 +132,12 @@ function entryType(sitting: RevisionSitting): string {
   return REVISION_ENTRY_TYPES.updated;
 }
 
+export const REVISION_ENTRY_ICONS = DEFAULT_ICONS;
+
 /** The version this sitting spans. Shown because `version` is the chain's own
  *  gapless sequence, which is the only thing a reader (or a later span-blame
  *  pass) can use to tell a complete trail from a lossy one. */
-function versionNote(sitting: RevisionSitting): string {
+export function versionNote(sitting: RevisionSitting): string {
   return sitting.fromVersion === sitting.toVersion
     ? `v${sitting.toVersion}`
     : `v${sitting.fromVersion}–v${sitting.toVersion}`;
@@ -140,9 +177,51 @@ export interface RecordHistoryPanelProps {
   errorTitle?: string;
   notFoundTitle?: string;
   notFoundMessage?: string;
-  /** The standing caveat that the trail has known silent write paths. Pass
-   *  `null` only if the surrounding page already says it — not to make the
-   *  panel look more complete than it is. */
+  /** Whether this record's TYPE keeps a history, as resolved from
+   *  `EntityTypeDef.config.history` (the type's own declaration, else the
+   *  reserved `"*"` row, else on). `false` makes the panel say that history is
+   *  not recorded for this kind of record, beside any rows written before it
+   *  was switched off. Omitted or `true` says nothing — the panel never
+   *  invents a caveat it cannot back. bd startsim-jkkn7.11. */
+  historyEnabled?: boolean;
+  /** The sentence shown when {@link historyEnabled} is `false`. */
+  declaredOffNote?: ReactNode;
+  /** Narrow the trail to one field — `?field=` on the read (bd startsim-jkkn7.8).
+   *  What `FieldAttribution` opens. A narrowed panel offers no whole-record
+   *  restore: the narrowed read misses name changes and held-back attempts
+   *  (bd startsim-jkkn7.18), so a preview over it would be partial. */
+  field?: string;
+  /** "Show all fields" while narrowed. Omit to hide the control. */
+  onClearField?: () => void;
+  /** Narrow from inside a row ("only this field's history"). Omit to hide. */
+  onNarrowToField?: (field: string) => void;
+  /** The version the HOST holds for this record — what a restore asserts. A
+   *  function is read at confirm time, so a draft editor can pass its live
+   *  conditional-save version and an autosave between opening the dialog and
+   *  confirming it does not turn the restore into a 412 against the reviewer's
+   *  own save. Falls back to the newest loaded revision on an unnarrowed trail. */
+  currentVersion?: number | (() => number | undefined);
+  /** Whether the viewer may write this record. Restore is offered only when the
+   *  client has `restore` AND this is not `false`. */
+  canRestore?: boolean;
+  /**
+   * Runs before the restore is sent, and BEFORE `currentVersion` is read — the
+   * host's chance to stop pending autosaves and flush unsaved typing, so nothing
+   * lands after the restore with the old text and nothing typed is lost. May
+   * return a cleanup, run once the restore has settled either way (success,
+   * refusal or 412). THROWING ABORTS the restore with the error's message: a
+   * flush that was itself refused must not be followed by a restore.
+   */
+  beforeRestore?: () => void | (() => void) | Promise<void | (() => void)>;
+  /** After a restore landed. The host reloads its own state (an editor's local
+   *  copy) from `outcome.record`; the panel re-reads its trail itself. */
+  onRestored?: (outcome: Extract<ParsedRestoreOutcome, { kind: 'restored' }>) => void | Promise<void>;
+  /** "this draft", "this topic" — for the confirm and stale dialogs. */
+  recordLabel?: string;
+  /** An extra caveat under the trail, for a host that knows something about
+   *  this record's coverage the panel cannot. None by default: since bd
+   *  startsim-jkkn7.6 every write path records, and a standing "some edits may
+   *  be missing" would teach readers to discount a complete trail. */
   incompleteNote?: ReactNode;
   classNames?: RecordHistoryPanelClassNames;
 }
@@ -166,24 +245,187 @@ export function RecordHistoryPanel({
   notFoundTitle = 'History is not available to you',
   notFoundMessage =
     'This record, or your access to it, has changed. Reopen the record to see its history.',
-  incompleteNote =
-    'Some writes are not recorded yet — bulk imports, scope moves, annotations and deletions leave no entry — so a quiet history is not proof that nothing else touched this record.',
+  historyEnabled,
+  declaredOffNote =
+    'History is not recorded for this kind of record — it has been switched off for this type, so new edits do not appear here.',
+  incompleteNote = null,
+  field,
+  onClearField,
+  onNarrowToField,
+  currentVersion,
+  canRestore,
+  beforeRestore,
+  onRestored,
+  recordLabel = 'this record',
   classNames = {},
 }: RecordHistoryPanelProps) {
   const cx = { ...RECORD_HISTORY_PANEL_DEFAULTS, ...classNames };
+  const queryClient = useQueryClient();
 
   const query = useInfiniteQuery<RevisionPage>({
-    queryKey: [...queryKey, { pageSize, windowMs }],
-    queryFn: ({ pageParam }) => client.list({ page: pageParam as number, pageSize }),
+    queryKey: [...queryKey, { pageSize, windowMs, field: field ?? null }],
+    queryFn: ({ pageParam }) =>
+      client.list({ page: pageParam as number, pageSize, ...(field ? { field } : {}) }),
     initialPageParam: 1,
     getNextPageParam: (last, all) => (last?.next ? all.length + 1 : undefined),
   });
 
+  // The host's word wins; otherwise the envelope's resolved policy
+  // (bd startsim-jkkn7.17). Absent from both says nothing.
+  const envelopePolicy = query.data?.pages?.[0]?.history;
+  const declaredOff = (historyEnabled ?? envelopePolicy?.enabled) === false;
+
   const revisions = useMemo<EntityRevision[]>(
     () => (query.data?.pages ?? []).flatMap((p) => p?.results ?? []),
     [query.data],
   );
 
+  /* ------------------------------------------------------------------ */
+  /*  RESTORE                                                            */
+  /* ------------------------------------------------------------------ */
+
+  const restoreEnabled = typeof client.restore === 'function' && canRestore !== false;
+  const latest = useMemo(() => latestFieldVersions(revisions), [revisions]);
+  const newestLoaded = useMemo(
+    () => normalizeRevision(newestRevision(revisions) ?? { id: '', version: 0 }).version,
+    [revisions],
+  );
+
+  const [pending, setPending] = useState<{ target: number; fields?: string[] } | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [restoreError, setRestoreError] = useState<string | null>(null);
+  const [conflict, setConflict] = useState<StaleSaveConflict | null>(null);
+  const [done, setDone] = useState<string | null>(null);
+  /** The request a 412 refused, kept so "restore anyway" re-sends exactly it. */
+  const refused = useRef<RestoreRequest | null>(null);
+  const inFlight = useRef(false);
+
+  const preview = useMemo<RestorePreview | null>(
+    () =>
+      pending
+        ? restorePreview(revisions, pending.target, {
+            ...(pending.fields ? { fields: pending.fields } : {}),
+            narrowed: !!field,
+          })
+        : null,
+    [pending, revisions, field],
+  );
+
+  const heldVersion = useCallback((): number | undefined => {
+    const held = typeof currentVersion === 'function' ? currentVersion() : currentVersion;
+    if (typeof held === 'number' && Number.isInteger(held)) return held;
+    // Only an UNNARROWED trail's newest row is the record's current version.
+    return field ? undefined : newestLoaded || undefined;
+  }, [currentVersion, field, newestLoaded]);
+
+  const refresh = useCallback(
+    () => queryClient.invalidateQueries({ queryKey: [...queryKey] }),
+    [queryClient, queryKey],
+  );
+
+  const send = useCallback(
+    async (request: RestoreRequest) => {
+      if (!client.restore || inFlight.current) return;
+      inFlight.current = true;
+      setBusy(true);
+      setRestoreError(null);
+      let outcome: unknown;
+      try {
+        outcome = await client.restore(request);
+      } catch (error) {
+        outcome = error;
+      }
+      const parsed = parseRestoreOutcome(outcome);
+      try {
+        if (parsed.kind === 'restored') {
+          setPending(null);
+          setConflict(null);
+          refused.current = null;
+          const moved = parsed.summary.fields;
+          const from = `v${parsed.summary.restoredFrom ?? request.version}`;
+          setDone(
+            parsed.summary.revision === null
+              ? `Nothing to restore — already as it was at ${from}.`
+              : `Restored ${moved.length ? moved.map(fieldLabel).join(', ') : 'the record'} from ${from}, saved as v${parsed.summary.revision}.`,
+          );
+          await onRestored?.(parsed);
+          await refresh();
+        } else if (parsed.kind === 'stale') {
+          // NOT retried. The record moved since the version the host holds; a
+          // person decides, in the same dialog an editor's stale save uses.
+          setPending(null);
+          refused.current = request;
+          const next: StaleSaveConflict = {
+            ...(parsed.currentVersion !== undefined ? { currentVersion: parsed.currentVersion } : {}),
+            ...(parsed.detail ? { detail: parsed.detail } : {}),
+            sentVersion: request.expectedVersion,
+            refusedBody: { ...request },
+          };
+          setConflict(next);
+          try {
+            const page = await client.list({ page: 1, pageSize: 1 });
+            const row = newestRevision(page?.results);
+            setConflict((cur) =>
+              cur === next
+                ? row
+                  ? { ...cur, changedBy: normalizeRevision(row) }
+                  : { ...cur, identityGap: 'empty' }
+                : cur,
+            );
+          } catch {
+            setConflict((cur) => (cur === next ? { ...cur, identityGap: 'error' } : cur));
+          }
+        } else {
+          setRestoreError(parsed.message);
+        }
+      } finally {
+        inFlight.current = false;
+        setBusy(false);
+      }
+    },
+    [client, fieldLabel, onRestored, refresh],
+  );
+
+  const confirmRestore = useCallback(async () => {
+    if (!pending || inFlight.current) return;
+    let cleanup: void | (() => void);
+    setBusy(true);
+    try {
+      cleanup = await beforeRestore?.();
+    } catch (error) {
+      setBusy(false);
+      setRestoreError(
+        (error instanceof Error && error.message) ||
+          'Your unsaved edits could not be saved first, so nothing was restored.',
+      );
+      return;
+    }
+    try {
+      // Read AFTER the host flushed: its version may have just advanced.
+      const expectedVersion = heldVersion();
+      if (expectedVersion === undefined) {
+        setBusy(false);
+        setRestoreError(
+          'The current version of this record is not known here, so a restore cannot be checked against it. Reload and try again.',
+        );
+        return;
+      }
+      await send({
+        version: pending.target,
+        ...(pending.fields ? { fields: pending.fields } : {}),
+        expectedVersion,
+      });
+    } finally {
+      if (typeof cleanup === 'function') cleanup();
+    }
+  }, [pending, heldVersion, beforeRestore, send]);
+
+  const openRestore = useCallback((target: number, fields?: string[]) => {
+    setRestoreError(null);
+    setDone(null);
+    setPending({ target, ...(fields ? { fields } : {}) });
+  }, []);
+
   // THE FOLD RUNS OVER THE ACCUMULATION, never per page. See the header.
   const sittings = useMemo(() => foldRevisions(revisions, windowMs), [revisions, windowMs]);
 
@@ -191,7 +433,7 @@ export function RecordHistoryPanel({
     () =>
       sittings.map((sitting) => ({
         id: sitting.id,
-        type: entryType(sitting),
+        type: revisionEntryType(sitting),
         title: sittingHeadline(sitting, fieldLabel),
         occurredAt: sitting.at,
         actor: { email: sitting.actorLabel || undefined, id: sitting.actorSub || undefined },
@@ -203,9 +445,26 @@ export function RecordHistoryPanel({
         tone: sitting.isAttempt ? 'warn' : undefined,
         subtitle: versionNote(sitting),
         note: sitting.saves > 1 ? sittingSummary(sitting) : undefined,
-        detail: <RevisionFields sitting={sitting} fieldLabel={fieldLabel} />,
+        detail: (
+          <RevisionFields
+            sitting={sitting}
+            fieldLabel={fieldLabel}
+            {...(onNarrowToField && !field ? { onNarrowToField } : {})}
+            {...(restoreEnabled && !sitting.isAttempt
+              ? {
+                  // Only where a later row moved the field: on the row whose
+                  // value IS the current one, a restore changes nothing.
+                  canRestoreField: (f: string) => (latest[f] ?? -1) > sitting.toVersion,
+                  onRestoreField: (f: string) => openRestore(sitting.toVersion, [f]),
+                  ...(!field && sitting.toVersion < newestLoaded
+                    ? { onRestoreVersion: () => openRestore(sitting.toVersion) }
+                    : {}),
+                }
+              : {})}
+          />
+        ),
       })),
-    [sittings, fieldLabel],
+    [sittings, fieldLabel, restoreEnabled, latest, field, newestLoaded, openRestore, onNarrowToField],
   );
 
   // Sentence 1 — only when some loaded row really is unknown, so a tenant past
@@ -214,6 +473,13 @@ export function RecordHistoryPanel({
     () => sittings.some((s) => s.actorKind === 'unknown'),
     [sittings],
   );
+  // A claimed person is undecorated exactly like an unknown row, so when both
+  // are loaded "the rest" would sweep in the one row whose kind WAS recorded
+  // (bd startsim-jkkn7.15). Each row's own title/sr-only text says which.
+  const anyClaimedPerson = useMemo(
+    () => sittings.some((s) => s.actorKind === 'person' && s.actorKindSource === 'claim'),
+    [sittings],
+  );
 
   // Sentence 2 — the server's own roll-up over this page's rows, unioned
   // across the pages loaded so far.
@@ -242,12 +508,45 @@ export function RecordHistoryPanel({
         {headerAside}
       </div>
 
+      {field && (
+        <p className={cx.notice} data-testid="record-history-narrowed">
+          Showing changes to <code className="rounded bg-muted px-1 text-foreground">{fieldLabel(field)}</code>{' '}
+          only.{' '}
+          {onClearField && (
+            <button
+              type="button"
+              data-testid="record-history-clear-field"
+              onClick={onClearField}
+              className="inline-flex items-center gap-0.5 underline underline-offset-2 hover:text-foreground"
+            >
+              <X className="h-3 w-3" aria-hidden="true" />
+              Show all fields
+            </button>
+          )}
+        </p>
+      )}
+
+      {done && (
+        <p className={cx.notice} role="status" data-testid="restore-done">
+          {done}
+        </p>
+      )}
+
       {anyUnknownKind && (
         <p className={cx.notice} data-testid="record-history-unknown-kind">
           Entries marked <strong className="font-medium text-foreground">machine</strong> were
-          made by an automation. For the rest, whether a person or a machine made the edit was
-          not recorded — it is not available for edits made before this was switched on, or by
-          anyone who has not signed in since.
+          made by an automation.{' '}
+          {anyClaimedPerson
+            ? 'Some unmarked entries were recorded as made by a person; for the others, whether a person or a machine made the edit was not recorded'
+            : 'For the rest, whether a person or a machine made the edit was not recorded'}{' '}
+          — it is not available for edits made before this was switched on, or by anyone who has
+          not signed in since.{anyClaimedPerson && ' Hover a name to see which.'}
+        </p>
+      )}
+
+      {declaredOff && !query.isError && (
+        <p className={cx.notice} data-testid="record-history-declared-off">
+          {declaredOffNote}
         </p>
       )}
 
@@ -277,7 +576,9 @@ export function RecordHistoryPanel({
             hasMore={!!query.hasNextPage}
             onLoadMore={loadMore}
             emptyTitle={emptyTitle}
-            emptyDescription={emptyDescription}
+            // Declared off: "edits will appear here" would be untrue, and the
+            // notice above already says why the trail is empty.
+            emptyDescription={declaredOff ? '' : emptyDescription}
             activityIcons={DEFAULT_ICONS}
             defaultIcon={Pencil}
             loadMoreLabel={query.isFetchingNextPage ? 'Loading…' : 'Load more'}
@@ -292,12 +593,63 @@ export function RecordHistoryPanel({
         </p>
       )}
 
-      {/* Sentence 3 — always, when there is anything to qualify. */}
+      {/* A host-supplied caveat only; none by default (see sentence 3). */}
       {incompleteNote && !query.isError && (
         <p className={cx.countLine} data-testid="record-history-incomplete">
           {incompleteNote}
         </p>
       )}
+
+      {restoreEnabled && (
+        <>
+          <RestoreConfirmDialog
+            open={pending !== null}
+            preview={preview}
+            {...(pending?.fields ? { fields: pending.fields } : {})}
+            recordLabel={recordLabel}
+            fieldLabel={fieldLabel}
+            busy={busy}
+            error={restoreError}
+            onConfirm={() => void confirmRestore()}
+            onCancel={() => {
+              setPending(null);
+              setRestoreError(null);
+            }}
+          />
+          <StaleSaveDialog
+            conflict={conflict}
+            open={conflict !== null}
+            recordLabel={recordLabel}
+            whilePhrase="after you opened its history"
+            reassurance="Nothing was restored. Restoring now would replace their change too."
+            dismissLabel="Cancel"
+            reviewLabel="See what changed"
+            keepMineLabel="Restore anyway, replacing their change"
+            busy={busy}
+            fieldLabel={fieldLabel}
+            onDismiss={() => {
+              setConflict(null);
+              refused.current = null;
+            }}
+            onReviewChange={() => {
+              setConflict(null);
+              refused.current = null;
+              void refresh();
+            }}
+            // The ONLY path that adopts the version the refusal named — a person
+            // has been shown who changed it and chose to replace it anyway.
+            {...(conflict?.currentVersion !== undefined
+              ? {
+                  onKeepMine: () => {
+                    const request = refused.current;
+                    if (!request || conflict?.currentVersion === undefined) return;
+                    void send({ ...request, expectedVersion: conflict.currentVersion });
+                  },
+                }
+              : {})}
+          />
+        </>
+      )}
     </section>
   );
 }