@startsimpli/ui 0.4.136 → 0.4.137

package/src/components/history/conditional-write.ts

@@ -0,0 +1,340 @@
+/**
+ * The record-version precondition, client side — "send the version on every
+ * write" (bd startsim-jkkn7.3; server bd startsim-3c2wc; design bd
+ * startsim-j4kx6 §6).
+ *
+ * Pure and React-free on purpose, like `revision-history.ts` beside it: the
+ * rules below are the half that decides whether a save is guarded at all, and
+ * they are worth testing without a DOM. {@link useConditionalSave} is the
+ * stateful half and {@link StaleSaveDialog} is what a person sees.
+ *
+ * ── THE POSTURE, AND WHY A MISSING VERSION MUST STILL SAVE ──────────────────
+ *
+ * The server is ENFORCED WHEN PRESENT, OPTIONAL WHEN ABSENT, and that is not a
+ * tolerance to be tidied up later — it is the only posture that could be rolled
+ * to seven live tenants in one merge, because every caller in production sends
+ * no version. So every function here fails toward "send nothing and let the
+ * write through", NEVER toward "refuse to save because we could not work out a
+ * version". A conflict guard that can make a save impossible is a worse bug
+ * than the overwrite it prevents.
+ *
+ * ── WHERE THE VERSION COMES FROM, AND THE ONE THE CONTRACT GETS WRONG ───────
+ *
+ * Three exposures exist server-side: the read-only `version` field, the `ETag`
+ * on the detail read, and the `ETag` on the WRITE response — the last being what
+ * lets a 1,200 ms autosave guard itself without a GET between every save.
+ *
+ * BUT THE WRITE RESPONSE'S HEADER IS NOT RELIABLY READABLE IN A BROWSER, and
+ * this module is the place that has to know it. `ETag` is not a CORS-safelisted
+ * response header, `tenant-starter/config/settings/base.py` sets
+ * `CORS_ALLOWED_ORIGINS` and `CORS_ALLOW_CREDENTIALS` and NO
+ * `CORS_EXPOSE_HEADERS`, and django-cors-headers defaults that to `[]`. So a
+ * fork served from its own origin reads the header fine and any cross-origin
+ * caller reads `null` — silently, and only on the write path, which is the one
+ * place a missing validator turns the guard off.
+ *
+ * The fix costs nothing, because the server stamps the header FROM the body:
+ * `EntityViewSet._offer_etag` reads `response.data["version"]`, so ETag-present
+ * and body-`version`-present are the same condition and the two can never
+ * disagree. {@link versionFromWriteOutcome} therefore reads the BODY FIRST and
+ * falls back to the header. Body-first is strictly more robust, and the
+ * server's own docstring says a client "may read either".
+ */
+import type { EntityRevision } from './types';
+
+/** The header spelling. Whatever a read emitted as `ETag`, sent back. */
+export const PRECONDITION_HEADER = 'If-Match';
+
+/** The body spelling, for callers behind a proxy that strips `If-Match`. It is
+ *  a TOP-LEVEL field and must never be folded into `data` — inside the blob it
+ *  stops being a precondition and starts being stored on the record. */
+export const PRECONDITION_BODY_FIELD = 'expected_version';
+
+/** The refusal. 412 and not 409: the write is well-formed and would be legal,
+ *  and the only thing wrong with it is the validator the caller supplied. */
+export const STALE_SAVE_STATUS = 412;
+
+/** Which spelling to send. `header` by default — it leaves the request body
+ *  completely untouched, so there is no path by which a precondition can end up
+ *  written onto the record. */
+export type PreconditionSpelling = 'header' | 'body';
+
+/** Anything we can read a response header out of: a real `Headers`, or the
+ *  plain object an API wrapper hands back. */
+export interface HeaderReader {
+  get(name: string): string | null | undefined;
+}
+
+export type ResponseHeaders =
+  | HeaderReader
+  | Record<string, string | null | undefined>;
+
+/**
+ * An integer version, and ONLY an integer.
+ *
+ * `version` IS LEGITIMATELY 0 — every record that predates the revision trail
+ * reads 0, and 0 is a version the server accepts back — so `if (version)` is a
+ * bug that silently unguards exactly the oldest records. Booleans are excluded
+ * explicitly because `Number.isInteger` already rejects them but a reader
+ * should not have to check.
+ */
+export function isVersion(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value);
+}
+
+/** Coerce what a JSON client might hand us. A numeric STRING is accepted
+ *  because clients stringify integers routinely and the server honours one; a
+ *  bool is not, because `expected_version: true` is not a version anybody
+ *  meant. */
+export function toVersion(value: unknown): number | undefined {
+  if (isVersion(value)) return value;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (/^-?\d+$/.test(trimmed)) return Number.parseInt(trimmed, 10);
+  }
+  return undefined;
+}
+
+/** The strong validator for a row at `version` — quoted, no `W/`, matching
+ *  `apps/api/preconditions.etag`. RFC 9110 §13.1.1 requires STRONG comparison
+ *  for `If-Match`, so a weak tag could not legally do this job. */
+export function etagFor(version: number): string {
+  return `"${version}"`;
+}
+
+function headerValue(headers: ResponseHeaders | undefined, name: string): string | undefined {
+  if (!headers) return undefined;
+  const reader = headers as HeaderReader;
+  if (typeof reader.get === 'function') {
+    const found = reader.get(name);
+    return typeof found === 'string' ? found : undefined;
+  }
+  // A plain record, whose casing we do not control.
+  const lower = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers as Record<string, unknown>)) {
+    if (key.toLowerCase() === lower && typeof value === 'string') return value;
+  }
+  return undefined;
+}
+
+/**
+ * The version an `ETag` names, or `undefined` when it names none.
+ *
+ * `*` RETURNS UNDEFINED RATHER THAN A MATCH, which mirrors the server: it
+ * asserts only that a current representation exists, so it is no guard against
+ * a lost update at all, and sending it back would record `precondition: none`
+ * on the trail for a write the client believed it had checked. A list is parsed
+ * (RFC 9110 allows `"1", "3"`) and a `W/` prefix is tolerated, because tolerating
+ * what we will never emit costs one line and a mystery 412 costs an afternoon.
+ */
+export function versionFromEtag(raw: unknown): number | undefined {
+  if (typeof raw !== 'string' || !raw.trim()) return undefined;
+  for (const part of raw.split(',')) {
+    let tag = part.trim();
+    if (tag.slice(0, 2).toUpperCase() === 'W/') tag = tag.slice(2).trim();
+    tag = tag.replace(/^"|"$/g, '').trim();
+    if (!tag || tag === '*') continue;
+    const version = toVersion(tag);
+    if (version !== undefined) return version;
+  }
+  return undefined;
+}
+
+/** The version on a record payload — the read-only `version` field, which no
+ *  case transform renames. */
+export function versionFromRecord(record: unknown): number | undefined {
+  if (!record || typeof record !== 'object') return undefined;
+  return toVersion((record as { version?: unknown }).version);
+}
+
+/**
+ * The version a WRITE just produced — the one that makes the next autosave free.
+ *
+ * Body first, header second. See this module's header for why: the body field is
+ * always readable and the header is not, and the server derives one from the
+ * other so they cannot disagree.
+ */
+export function versionFromWriteOutcome(outcome: {
+  body?: unknown;
+  headers?: ResponseHeaders;
+}): number | undefined {
+  const fromBody = versionFromRecord(outcome?.body);
+  if (fromBody !== undefined) return fromBody;
+  return versionFromEtag(headerValue(outcome?.headers, 'ETag'));
+}
+
+/** What a write should carry. Exactly one of the two is ever populated. */
+export interface PreconditionParts {
+  headers: Record<string, string>;
+  /** Merge at the TOP LEVEL of the request body, never inside `data`. */
+  body: Record<string, number>;
+  /** Whether this actually asserts a version. False when no version was known —
+   *  the write still goes, unguarded and visibly so (`precondition: "none"`). */
+  guards: boolean;
+}
+
+/**
+ * The precondition for a held version, in one spelling.
+ *
+ * NEVER BOTH SPELLINGS AT ONCE, and this is the subtle one. `preconditions.
+ * enforce` checks BOTH sources rather than the first it finds, and refuses if
+ * EITHER disagrees — deliberately, since a caller holding two beliefs about the
+ * row can be right about at most one. So a request carrying a stale `If-Match`
+ * beside a fresh `expected_version` refuses ITSELF, with a 412 that looks for
+ * all the world like a real conflict. One spelling per call.
+ */
+export function preconditionFor(
+  version: number | undefined,
+  spelling: PreconditionSpelling = 'header',
+): PreconditionParts {
+  if (!isVersion(version)) return { headers: {}, body: {}, guards: false };
+  return spelling === 'body'
+    ? { headers: {}, body: { [PRECONDITION_BODY_FIELD]: version }, guards: true }
+    : { headers: { [PRECONDITION_HEADER]: etagFor(version) }, body: {}, guards: true };
+}
+
+/** What the server said when it refused. Both keys are optional: the dialog has
+ *  to open and be useful on `current_version` alone, and on neither. */
+export interface StaleSaveRefusal {
+  /** The version the record is at NOW. Retrying with exactly this value lands —
+   *  which is why it must survive as an INTEGER and not as `"3"`. */
+  currentVersion?: number;
+  /** The server's sentence, which names both versions and is safe to show. */
+  detail?: string;
+}
+
+function statusOf(source: unknown): number | undefined {
+  if (!source || typeof source !== 'object') return undefined;
+  const candidate = source as {
+    status?: unknown;
+    statusCode?: unknown;
+    response?: { status?: unknown };
+  };
+  for (const raw of [candidate.status, candidate.statusCode, candidate.response?.status]) {
+    const value = toVersion(raw);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+function bodyOf(source: unknown): unknown {
+  if (!source || typeof source !== 'object') return undefined;
+  const candidate = source as {
+    body?: unknown;
+    data?: unknown;
+    response?: { data?: unknown; body?: unknown };
+  };
+  return (
+    candidate.body ??
+    candidate.data ??
+    candidate.response?.data ??
+    candidate.response?.body
+  );
+}
+
+/**
+ * Read a 412 out of an outcome OR a thrown error, or `undefined` when it is not
+ * one.
+ *
+ * BOTH SHAPES, because the two client styles in this monorepo disagree about
+ * which a failure is: a plain `fetch` resolves with `{ status: 412 }` and a
+ * wrapper throws. A guard that only understood one would let the other fall
+ * through to a generic "save failed" — losing the one piece of data the whole
+ * recovery depends on.
+ *
+ * `currentVersion` IS READ IN BOTH SPELLINGS. The shared API client camelCases
+ * every response key recursively and has no preserve list, so it renames
+ * `current_version` to `currentVersion` on the ERROR body too — same trap this
+ * module's neighbours carry, and the error path is where it would be found last.
+ */
+export function parseStaleSaveRefusal(source: unknown): StaleSaveRefusal | undefined {
+  if (statusOf(source) !== STALE_SAVE_STATUS) return undefined;
+  const body = bodyOf(source);
+  const record = body && typeof body === 'object' ? (body as Record<string, unknown>) : {};
+  const currentVersion = toVersion(record.current_version ?? record.currentVersion);
+  const detail = typeof record.detail === 'string' ? record.detail : undefined;
+  return {
+    ...(currentVersion !== undefined ? { currentVersion } : {}),
+    ...(detail ? { detail } : {}),
+  };
+}
+
+/** What `/api/v1/capabilities/` says about the guard. */
+export interface ConditionalWriteCapability {
+  /** The build enforces a precondition it is handed. */
+  conditionalWrites: boolean;
+  /** Whether a write MUST carry one. False everywhere today. */
+  preconditionRequired: boolean;
+  /** The guard does nothing on a type whose history has been silenced, and a
+   *  client cannot tell which types those are — so UI copy must not promise
+   *  protection per record. */
+  inertWithoutTypeHistory: boolean;
+  header: string;
+  bodyField: string;
+}
+
+/**
+ * The honest default for a build that has not answered: NOT GUARDED.
+ *
+ * A fork built before bd startsim-3c2wc accepts `expected_version` and silently
+ * ignores it, answering 200 either way — so a client cannot learn this from a
+ * write and must not assume it.
+ */
+export const CONDITIONAL_WRITES_UNKNOWN: ConditionalWriteCapability = {
+  conditionalWrites: false,
+  preconditionRequired: false,
+  inertWithoutTypeHistory: false,
+  header: PRECONDITION_HEADER,
+  bodyField: PRECONDITION_BODY_FIELD,
+};
+
+/**
+ * Read the capabilities document, defensively and in either spelling.
+ *
+ * WHAT THIS IS FOR, AND WHAT IT IS NOT FOR. It decides what the UI may CLAIM,
+ * not whether to send a precondition. Sending one to an older build is inert,
+ * not harmful — unknown body fields are ignored and an unknown header is
+ * ignored — so gating the send on this would buy nothing and would turn a
+ * failed capability fetch into an unguarded save. Send always; promise only
+ * when this says `conditionalWrites`.
+ */
+export function readConditionalWriteCapability(doc: unknown): ConditionalWriteCapability {
+  if (!doc || typeof doc !== 'object') return CONDITIONAL_WRITES_UNKNOWN;
+  const root = doc as Record<string, unknown>;
+  const entities = root.entities && typeof root.entities === 'object'
+    ? (root.entities as Record<string, unknown>)
+    : root;
+  const precondition =
+    entities.precondition && typeof entities.precondition === 'object'
+      ? (entities.precondition as Record<string, unknown>)
+      : {};
+  const flag = (...keys: string[]) =>
+    keys.some((key) => entities[key] === true || precondition[key] === true);
+  const text = (fallback: string, ...keys: string[]) => {
+    for (const key of keys) {
+      const value = precondition[key];
+      if (typeof value === 'string' && value) return value;
+    }
+    return fallback;
+  };
+  return {
+    conditionalWrites: flag('conditional_writes', 'conditionalWrites'),
+    preconditionRequired: flag('precondition_required', 'preconditionRequired'),
+    inertWithoutTypeHistory: flag('inert_without_type_history', 'inertWithoutTypeHistory'),
+    header: text(PRECONDITION_HEADER, 'header'),
+    bodyField: text(PRECONDITION_BODY_FIELD, 'body_field', 'bodyField'),
+  };
+}
+
+/** Row 0 of `/api/v1/entities/<id>/revisions/` is the NEWEST — the route orders
+ *  `-version, -created_at` — so the newest row is who to name in the dialog.
+ *  Asserted here rather than assumed at the call site, because an ordering flip
+ *  would make the dialog confidently name whoever CREATED the record. */
+export function newestRevision(rows: EntityRevision[] | undefined): EntityRevision | undefined {
+  if (!rows || rows.length === 0) return undefined;
+  return rows.reduce((newest, row) => {
+    const a = isVersion(row?.version) ? row.version : -1;
+    const b = isVersion(newest?.version) ? newest.version : -1;
+    return a > b ? row : newest;
+  });
+}

package/src/components/history/index.ts

@@ -1,5 +1,7 @@
 /**
- * @startsimpli/ui/history — the shared record history panel (bd startsim-g4rwo).
+ * @startsimpli/ui/history — the client half of record versions: the shared
+ * history panel (bd startsim-g4rwo) AND the conditional-write guard that keeps
+ * a reviewer's text when a stale save is refused (bd startsim-jkkn7.3).
  *
  * "Who edited what piece of the text and when", over the append-only revision
  * trail (bd startsim-o1qib). A page-level composer plus the pure helpers it
@@ -7,6 +9,13 @@
  * classNames rather than its own timeline, its own fold and its own idea of
  * what `{}` means (rule #9).
  *
+ * THE TWO HALVES SHIP FROM ONE SUBPATH DELIBERATELY. The conflict dialog reads
+ * the SAME trail through the SAME injected {@link RevisionClient} and names its
+ * actor through the SAME `ActorIdentity`, because the 412 carries no identity by
+ * design (bd startsim-j4kx6). A second subpath would be a second place for the
+ * three-state actor vocabulary to drift, and that vocabulary is the one thing in
+ * this epic that must not.
+ *
  * THE ONE THING A CONSUMER MUST NOT GET WRONG: `actorKind` is THREE-state, and
  * `unknown` is the common case for genuine human edits for up to 14 days after
  * rollout. Render it through this panel — or through `ActorIdentity` with
@@ -47,6 +56,60 @@ export type {
 
 export { diffLines, unifiedTextDiff } from './text-diff';
 
+/* -------------------------------------------------------------------------- */
+/*  THE CONDITIONAL WRITE (bd startsim-jkkn7.3)                               */
+/*                                                                            */
+/*  Send the version on every write; on a 412 keep the reviewer's text, pause  */
+/*  autosave and say who changed the record. The ONE contract a consumer must  */
+/*  not break: never adopt `current_version` and retry on the client's own     */
+/*  initiative — that is the overwrite the 412 just prevented.                 */
+/* -------------------------------------------------------------------------- */
+
+export { useConditionalSave } from './useConditionalSave';
+export type {
+  ConditionalSave,
+  ConditionalSaveResult,
+  ConditionalWriteAttempt,
+  ConditionalWriteClient,
+  ConditionalWriteOutcome,
+  IdentityGap,
+  StaleSaveConflict,
+  UseConditionalSaveOptions,
+} from './useConditionalSave';
+
+export { StaleSaveDialog } from './StaleSaveDialog';
+export type { StaleSaveDialogProps } from './StaleSaveDialog';
+
+export {
+  STALE_SAVE_DIALOG_DEFAULTS,
+  type StaleSaveDialogClassNames,
+} from './stale-save-dialog-default-class-names';
+
+export {
+  CONDITIONAL_WRITES_UNKNOWN,
+  PRECONDITION_BODY_FIELD,
+  PRECONDITION_HEADER,
+  STALE_SAVE_STATUS,
+  etagFor,
+  isVersion,
+  newestRevision,
+  parseStaleSaveRefusal,
+  preconditionFor,
+  readConditionalWriteCapability,
+  toVersion,
+  versionFromEtag,
+  versionFromRecord,
+  versionFromWriteOutcome,
+} from './conditional-write';
+export type {
+  ConditionalWriteCapability,
+  HeaderReader,
+  PreconditionParts,
+  PreconditionSpelling,
+  ResponseHeaders,
+  StaleSaveRefusal,
+} from './conditional-write';
+
 export type {
   ActorKind,
   ActorKindSource,

package/src/components/history/stale-save-dialog-default-class-names.ts

@@ -0,0 +1,45 @@
+/** Default Tailwind classes for {@link StaleSaveDialog}. bd startsim-jkkn7.3.
+ *  Semantic tokens only (startsim-1f3n) — theme-driven, dark-mode safe, and no
+ *  literal colour, so a dark tenant theme recolours this without a fork. */
+
+export interface StaleSaveDialogClassNames {
+  backdrop?: string;
+  dialog?: string;
+  header?: string;
+  title?: string;
+  /** The line that tells the reviewer their text is still here. */
+  reassurance?: string;
+  body?: string;
+  /** The server's sentence, and the "we could not say who" sentences. */
+  notice?: string;
+  fieldList?: string;
+  field?: string;
+  footer?: string;
+  primaryAction?: string;
+  secondaryAction?: string;
+  /** The one action that throws the reviewer's own text away. */
+  destructiveAction?: string;
+}
+
+const BUTTON = 'inline-flex items-center justify-center rounded-md px-3 py-1.5 text-sm font-medium disabled:opacity-50';
+
+export const STALE_SAVE_DIALOG_DEFAULTS: Required<StaleSaveDialogClassNames> = {
+  backdrop: 'fixed inset-0 z-50 flex items-center justify-center bg-background/80 p-4',
+  dialog: 'w-full max-w-lg rounded-lg border border-border bg-card shadow-lg',
+  header: 'space-y-2 border-b border-border px-5 py-4',
+  title: 'flex flex-wrap items-center gap-x-1.5 gap-y-1 font-medium text-foreground',
+  // NOT a warning colour. The reviewer's work is safe; this sentence is the
+  // reassurance, and painting it like a failure would say the opposite.
+  reassurance: 'text-sm text-foreground',
+  body: 'space-y-3 px-5 py-4',
+  notice: 'text-xs text-muted-foreground',
+  fieldList: 'flex flex-wrap gap-1',
+  field: 'rounded bg-muted px-1.5 py-0.5 text-xs text-foreground',
+  footer: 'flex flex-wrap items-center justify-end gap-2 border-t border-border px-5 py-3',
+  primaryAction: `${BUTTON} bg-primary text-primary-foreground`,
+  secondaryAction: `${BUTTON} border border-border bg-background text-foreground`,
+  // Underplayed ON PURPOSE. It is the only control here that destroys the text
+  // this dialog exists to protect, so it must never be the thing a hurried
+  // reviewer clicks by muscle memory.
+  destructiveAction: 'text-xs text-muted-foreground underline underline-offset-2',
+};