@startsimpli/ui 0.4.135 → 0.4.137

package/src/components/history/types.ts

@@ -0,0 +1,167 @@
+/**
+ * @startsimpli/ui/history — the shapes the shared record history panel renders
+ * (bd startsim-g4rwo; trail bd startsim-o1qib).
+ *
+ * Structural on purpose, exactly like `activity/types.ts`: packages/ui imports
+ * no API client, so these mirror one `/api/v1/entities/<id>/revisions/` row
+ * without depending on @startsimpli/api. The consuming app injects its own
+ * authed client (see {@link RevisionClient}).
+ *
+ * ── THE SPELLING TRAP, AND WHY EVERY KEY HERE IS OPTIONAL TWICE ─────────────
+ *
+ * The wire is snake_case. The shared API client
+ * (`packages/api/src/utils/case-transform.ts`) camelCases every response key
+ * RECURSIVELY and has no preserve list, so an app that fetches this route
+ * through `FetchWrapper` receives `actorKind`, `createdAt`, `redactedFields`
+ * and `valuesOmitted`. Both spellings are therefore declared and
+ * {@link normalizeRevision} reads either, because a panel that renders blank
+ * actors against a camelising client — and correctly against a raw one — is a
+ * bug nobody would find twice.
+ *
+ * WHAT THAT TRANSFORM BREAKS AND THIS MODULE CANNOT FIX: the keys INSIDE
+ * `metadata.changed` are the tenant's own declared attribute names, so a
+ * camelising client renames `team_verdict` to `teamVerdict` and there is no
+ * safe inverse — `snake_to_camel` is not injective, and guessing one would
+ * print a field name the tenant never declared. So field names are rendered
+ * EXACTLY as received and never re-cased. A consumer that wants the declared
+ * spellings must fetch this route without the case transform; one that cannot
+ * should pass `fieldLabel` to map them. Stated here rather than discovered
+ * later, because the same transform already corrupted declared names once.
+ */
+
+/**
+ * The actor vocabulary lives on `ActorIdentity`, which is the component that
+ * RENDERS it, and is re-exported here so a consumer of this module needs one
+ * import rather than two. Declared once (rule #1): a second union would be a
+ * second place for "person | machine | unknown" to drift, and the three-state
+ * shape is the one thing in this epic that must not.
+ */
+import type { ActorKind, ActorKindSource } from '../ActorIdentity';
+
+export type { ActorKind, ActorKindSource };
+
+/** `deleted` is declared server-side and not yet written — bd startsim-jkkn7.6. */
+export type RevisionAction = 'created' | 'updated' | 'deleted';
+
+/** Which endpoint wrote. `server` is a management command or a worker — a real
+ *  write that must not claim to be an endpoint. */
+export type RevisionSource = 'create' | 'patch' | 'put' | 'upsert' | 'server';
+
+/** `none` always, today; `matched` arrives with the conditional write
+ *  (bd startsim-3c2wc). */
+export type RevisionPrecondition = 'none' | 'matched';
+
+/**
+ * One `metadata.changed` entry, straight off the wire.
+ *
+ * THE ABSENCE OF A SIDE IS THE PAYLOAD, which is why neither key is nullable
+ * rather than optional-and-nullable:
+ *
+ * - a field the write CREATED has `after` and NO `before` key;
+ * - a field the write DELETED has `before` and NO `after` key — the server
+ *   never writes `after: null`, because a key a person deleted is a different
+ *   fact from a key set to `null`, and `null` IS a legal stored value;
+ * - a field the read gate WITHHELD is `{}` and the row's `redacted_fields`
+ *   names it;
+ * - a row over the byte cap has `{}` for EVERY field and
+ *   `metadata.values_omitted` set.
+ *
+ * So `'after' in entry` is the only correct test and `entry.after === undefined`
+ * is wrong. {@link normalizeFieldChange} is the one place that does it.
+ */
+export interface RevisionFieldChange {
+  before?: unknown;
+  after?: unknown;
+  /** The value was too large to store. WHEN THIS IS TRUE A MISSING SIDE SAYS
+   *  NOTHING — it was dropped, not deleted — so the delete inference above is
+   *  invalid and a diff over this entry would show a deletion that never
+   *  happened. */
+  truncated?: boolean;
+}
+
+export interface RevisionMetadata {
+  /** ALWAYS PRESENT, possibly `{}`. Keyed by the tenant's declared attribute
+   *  names — see the spelling trap in this module's header. */
+  changed?: Record<string, RevisionFieldChange>;
+  /** Present only when the name COLUMN moved. Namespaced away from `changed`
+   *  because a tenant may declare a data key literally called "name". */
+  name?: RevisionFieldChange;
+  /** Fields `human_edits.guard_machine_write` HELD BACK. A row carrying these
+   *  is a machine ATTEMPT, not a change, and its `changed` is `{}` — which is
+   *  correct, not a bug. */
+  preserved?: string[];
+  /** What an upsert CLAIMED it was re-authoring. The one override that
+   *  legitimately destroys a person's text, so it is shown. */
+  regenerate?: string[];
+  /** The whole row exceeded the row cap: every field is still NAMED in
+   *  `changed`, every value is `{}`. */
+  values_omitted?: boolean;
+  /** Camelised alias — see the header. */
+  valuesOmitted?: boolean;
+}
+
+/** One row of the append-only revision trail. Only `id` and `version` are
+ *  relied on; everything else is treated as optional so a row from a tenant
+ *  running an older build still renders. */
+export interface EntityRevision {
+  id: string;
+  /** 1-based, GAPLESS 1..N per entity, DB-unique. A hole is a provably lost
+   *  revision — which is what the unique constraint exists to make visible. */
+  version: number;
+  action?: RevisionAction | string;
+  source?: RevisionSource | string;
+  precondition?: RevisionPrecondition | string;
+  created_at?: string | null;
+  createdAt?: string | null;
+  /** May be `""`. */
+  actor_sub?: string | null;
+  actorSub?: string | null;
+  /** The actor's email, denormalised at write time. For a machine this is
+   *  often not an address at all (`svc:n8n-ogmc`). */
+  actor_label?: string | null;
+  actorLabel?: string | null;
+  actor_kind?: ActorKind | string | null;
+  actorKind?: ActorKind | string | null;
+  actor_kind_source?: ActorKindSource | string | null;
+  actorKindSource?: ActorKindSource | string | null;
+  metadata?: RevisionMetadata | null;
+  /** PRESENT ONLY when the per-field gate withheld something on this row. */
+  redacted_fields?: string[] | null;
+  redactedFields?: string[] | null;
+}
+
+/** The DRF envelope. `redacted_fields` is the server's roll-up of every row on
+ *  this page (`apps/api/pagination.py`), present only when something really
+ *  was held back. */
+export interface RevisionPage {
+  count?: number;
+  next?: string | null;
+  previous?: string | null;
+  results?: EntityRevision[];
+  redacted_fields?: string[] | null;
+  redactedFields?: string[] | null;
+}
+
+/** Narrowing the panel asks for. Server-side paginated (repo rule 8) — the
+ *  route caps `page_size` at 200 and 400s a parameter it does not recognise,
+ *  so this stays deliberately minimal. */
+export interface RevisionQuery {
+  page?: number;
+  pageSize?: number;
+  // Index signature so this satisfies an API client's query-params type; the
+  // injected client is the app's own.
+  [key: string]: unknown;
+}
+
+/**
+ * The one call the panel needs. The consuming app injects its authed client
+ * (`{ list: (p) => api.entities.revisions(id, p) }`), which is what keeps
+ * @startsimpli/api out of packages/ui and the app wrapper under ten lines.
+ *
+ * A 404 from this route means the caller may not read the PARENT record — the
+ * route is nested and an unreadable row is simply absent. The panel surfaces
+ * that as "you cannot see this record's history", never as an empty trail.
+ */
+export interface RevisionClient {
+  list: (query: RevisionQuery) => Promise<RevisionPage>;
+}

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;
+}

package/src/components/index.ts

@@ -155,7 +155,13 @@ export * from './calendar'
 // display name is never printed alone as if it were an identity
 // (startsim-768w.19.8.1).
 export { ActorIdentity, actorInitials, actorLabel, actorHandle } from './ActorIdentity'
-export type { ActorIdentityProps, ActorIdentityValue } from './ActorIdentity'
+export { actorKindTitle } from './ActorIdentity'
+export type {
+  ActorIdentityProps,
+  ActorIdentityValue,
+  ActorKind,
+  ActorKindSource,
+} from './ActorIdentity'
 
 // Activity components (timeline, quick log, log dialog)
 export { ActivityTimeline, dayHeading } from './ActivityTimeline'
@@ -168,6 +174,10 @@ export type {
 // The shared, filterable activity feed: filter bar + page-level composer over
 // any append-only event stream (startsim-768w.19.5).
 export * from './activity'
+
+// The shared record history panel: who changed which field, from what, to
+// what, and whether a machine did it (bd startsim-g4rwo).
+export * from './history'
 export { QuickLogButtons } from './QuickLogButtons'
 export type { QuickLogButtonsProps, QuickLogAction } from './QuickLogButtons'
 export { LogActivityDialog } from './LogActivityDialog'