@startsimpli/ui 0.4.136 → 0.4.137

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.136",
+  "version": "0.4.137",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -48,9 +48,9 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/api": "^0.5.66",
     "@startsimpli/auth": "^0.4.38",
-    "@startsimpli/i18n": "^0.1.3"
+    "@startsimpli/i18n": "^0.1.3",
+    "@startsimpli/api": "^0.5.66"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -124,8 +124,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/realtime": "0.0.2",
-    "@startsimpli/i18n": "0.1.3"
+    "@startsimpli/i18n": "0.1.3",
+    "@startsimpli/realtime": "0.0.2"
   },
   "keywords": [
     "ui",

package/src/components/history/StaleSaveDialog.tsx

@@ -0,0 +1,277 @@
+'use client';
+
+/**
+ * StaleSaveDialog — "Jurga changed this while you were editing", and your three
+ * paragraphs are still on screen (bd startsim-jkkn7.3).
+ *
+ * The refusal this renders is the right outcome: the server declined to let one
+ * reviewer's save destroy another's text. But a refusal that DISCARDS the typed
+ * work is worse than the overwrite it prevented — at least the overwrite kept
+ * somebody's text — so the first thing this dialog says is that nothing was
+ * lost, before it says anything about versions.
+ *
+ * ── PURE ON PURPOSE ─────────────────────────────────────────────────────────
+ *
+ * No data fetching, no react-query, and therefore NO `QueryClientProvider`
+ * requirement. {@link useConditionalSave} has already resolved who changed the
+ * record by the time this mounts. That split is deliberate: this component only
+ * ever appears when a save has just been refused, which is the worst possible
+ * moment to discover that a modal throws because of a missing provider.
+ *
+ * ── WHY THE SAFE ACTION IS THE DEFAULT ──────────────────────────────────────
+ *
+ * Three things a reviewer can do, and they are ordered by how recoverable they
+ * are rather than by how likely:
+ *
+ * - SEE WHAT CHANGED — default focus. Non-destructive, and it is the only one of
+ *   the three that makes the other two informed choices.
+ * - SAVE MINE ANYWAY — legitimate, and labelled with what it does to the other
+ *   person's change rather than as a neutral "retry". This is the only path that
+ *   adopts the version named in the refusal; a client that adopted it
+ *   automatically would have reduced the guard to a decoration.
+ * - DISCARD MY EDITS — the only control that destroys the text this dialog
+ *   exists to protect, so it is a de-emphasised link and never a button.
+ *
+ * ESCAPE, THE BACKDROP AND THE CLOSE BUTTON ARE NOT A FOURTH OPTION. They
+ * dismiss to the editor with the text intact and autosave still paused. That is
+ * the accidental path, and it must not resolve anything.
+ *
+ * ── AND THE SENTENCE IT REFUSES TO SAY ──────────────────────────────────────
+ *
+ * `actorKind: 'unknown'` means CENTRAL DID NOT SAY — the claim is minted at
+ * login, so for up to the 14-day refresh expiry after rollout a genuine human
+ * edit carries no kind at all. It is rendered through `ActorIdentity`, which
+ * marks a machine and stays quiet otherwise, so an unrecorded kind NEVER reads
+ * as "a machine did this". That conflation is the specific confusion this epic
+ * exists to end, and it would be worst here, where the reviewer is deciding
+ * whether to overwrite somebody.
+ */
+import { useEffect, useRef, type ReactNode } from 'react';
+
+import { ActorIdentity } from '../ActorIdentity';
+import type { StaleSaveConflict } from './useConditionalSave';
+import {
+  STALE_SAVE_DIALOG_DEFAULTS,
+  type StaleSaveDialogClassNames,
+} from './stale-save-dialog-default-class-names';
+
+export interface StaleSaveDialogProps {
+  conflict: StaleSaveConflict | null;
+  /** Usually `dialogOpen` off {@link useConditionalSave}. */
+  open?: boolean;
+  /** What the record is called, for the headline — "this draft", "this topic".
+   *  Generic by default so a fork that forgets still reads correctly. */
+  recordLabel?: string;
+  /** Escape, the backdrop and the close button. KEEPS the text and the pause. */
+  onDismiss: () => void;
+  /** Overwrite their change with the refused text. Omit to hide the action. */
+  onKeepMine?: () => void;
+  /** Throw the local edit away and load theirs. Omit to hide the action. */
+  onAcceptTheirs?: () => void;
+  /** Show the host's own diff or history panel. Omit to hide the action. */
+  onReviewChange?: () => void;
+  /** A resolution is in flight. */
+  busy?: boolean;
+  /** Map a wire field name to something a reader recognises. Identity by
+   *  default — this module never re-cases a declared attribute name. */
+  fieldLabel?: (field: string) => string;
+  /** Extra content, below the fields and above the footer. */
+  children?: ReactNode;
+  classNames?: StaleSaveDialogClassNames;
+}
+
+/** A timestamp a person can read, falling back to the raw string rather than to
+ *  "Invalid Date" — a row from an older build may carry anything. */
+function when(iso: string): string {
+  if (!iso) return '';
+  const parsed = new Date(iso);
+  return Number.isNaN(parsed.getTime()) ? iso : parsed.toLocaleString();
+}
+
+/** Why we cannot name a person — one sentence each, and not one of them
+ *  speculates about a machine. */
+function identityNotice(conflict: StaleSaveConflict): string {
+  switch (conflict.identityGap) {
+    case 'forbidden':
+      // The revisions route is nested, so a 404 means the PARENT record is
+      // unreadable to this principal — history is withheld, not absent.
+      return 'This record’s history is not available to you, so we cannot show who changed it.';
+    case 'empty':
+      return 'No change was recorded for this record, so we cannot show who changed it.';
+    case 'error':
+      return 'We could not load who changed it. Your edits are unaffected.';
+    case 'no-client':
+      return '';
+    default:
+      return '';
+  }
+}
+
+export function StaleSaveDialog({
+  conflict,
+  open = true,
+  recordLabel = 'this record',
+  onDismiss,
+  onKeepMine,
+  onAcceptTheirs,
+  onReviewChange,
+  busy = false,
+  fieldLabel = (field) => field,
+  children,
+  classNames,
+}: StaleSaveDialogProps) {
+  const css = { ...STALE_SAVE_DIALOG_DEFAULTS, ...classNames };
+  const focusTarget = useRef<HTMLButtonElement | null>(null);
+  const visible = open && conflict !== null;
+
+  // Escape dismisses. Bound on the document rather than the dialog so it works
+  // before anything inside has been focused.
+  useEffect(() => {
+    if (!visible) return;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') onDismiss();
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [visible, onDismiss]);
+
+  // Focus lands on the SAFE action, never on one that writes or discards.
+  useEffect(() => {
+    if (visible) focusTarget.current?.focus();
+  }, [visible]);
+
+  if (!visible || !conflict) return null;
+
+  const actor = conflict.changedBy;
+  const label = (actor?.actorLabel ?? '').trim();
+  const fields = actor ? Object.keys(actor.changed).sort() : [];
+  const notice = identityNotice(conflict);
+  const at = actor ? when(actor.createdAt) : '';
+
+  return (
+    <div
+      className={css.backdrop}
+      data-testid="stale-save-backdrop"
+      // A click on the backdrop is a dismissal, not a resolution. Guarded on the
+      // target so a click that merely BUBBLES out of the dialog does not close it.
+      onClick={(event) => {
+        if (event.target === event.currentTarget) onDismiss();
+      }}
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="stale-save-title"
+        className={css.dialog}
+        data-testid="stale-save-dialog"
+      >
+        <div className={css.header}>
+          <h2 id="stale-save-title" data-testid="stale-save-title" className={css.title}>
+            {label ? (
+              <>
+                <ActorIdentity
+                  actor={{ email: label }}
+                  showInitials={false}
+                  {...(actor?.actorKind ? { kind: actor.actorKind } : {})}
+                  {...(actor?.actorKindSource ? { kindSource: actor.actorKindSource } : {})}
+                />
+                <span>changed {recordLabel} while you were editing.</span>
+              </>
+            ) : (
+              /* NEVER "someone", and never a guess at a machine. The record
+                 changed; who is a separate question this dialog answers only
+                 when the trail actually said. */
+              <span>{`${recordLabel.charAt(0).toUpperCase()}${recordLabel.slice(1)} changed while you were editing.`}</span>
+            )}
+          </h2>
+          {/* THE LOAD-BEARING SENTENCE, and it comes first for that reason. */}
+          <p className={css.reassurance} data-testid="stale-save-reassurance">
+            Your edits are still here and have not been saved.
+          </p>
+        </div>
+
+        <div className={css.body}>
+          {at && (
+            <p className={css.notice} data-testid="stale-save-when">
+              Changed {at}.
+            </p>
+          )}
+
+          {fields.length > 0 && (
+            <div className={css.fieldList} data-testid="stale-save-fields">
+              {fields.map((field) => (
+                /* Rendered EXACTLY as received. These are the tenant's declared
+                   attribute names and there is no safe inverse for a camelising
+                   client, so guessing one would print a name nobody declared. */
+                <code key={field} className={css.field}>
+                  {fieldLabel(field)}
+                </code>
+              ))}
+            </div>
+          )}
+
+          {notice && (
+            <p className={css.notice} data-testid="stale-save-identity-gap">
+              {notice}
+            </p>
+          )}
+
+          {conflict.detail && (
+            <p className={css.notice} data-testid="stale-save-detail">
+              {conflict.detail}
+            </p>
+          )}
+
+          {children}
+        </div>
+
+        <div className={css.footer}>
+          {onAcceptTheirs && (
+            <button
+              type="button"
+              className={css.destructiveAction}
+              data-testid="stale-save-accept-theirs"
+              disabled={busy}
+              onClick={onAcceptTheirs}
+            >
+              Discard my edits and load theirs
+            </button>
+          )}
+          <button
+            type="button"
+            /* Focus falls here only when there is nothing to review. Either way
+               it lands on a control that cannot write and cannot discard. */
+            ref={onReviewChange ? undefined : focusTarget}
+            className={css.secondaryAction}
+            data-testid="stale-save-dismiss"
+            onClick={onDismiss}
+          >
+            Keep editing
+          </button>
+          {onReviewChange && (
+            <button
+              type="button"
+              ref={focusTarget}
+              className={css.secondaryAction}
+              data-testid="stale-save-review"
+              onClick={onReviewChange}
+            >
+              See what changed
+            </button>
+          )}
+          {onKeepMine && (
+            <button
+              type="button"
+              className={css.primaryAction}
+              data-testid="stale-save-keep-mine"
+              disabled={busy}
+              onClick={onKeepMine}
+            >
+              {busy ? 'Saving…' : 'Save mine, replacing their change'}
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,252 @@
+/**
+ * The precondition rules (bd startsim-jkkn7.3; server bd startsim-3c2wc).
+ *
+ * Every case here is pinned against `tenant-starter/apps/api/preconditions.py`
+ * as merged, not against the design — the two disagree about the 412 body and
+ * the server is the one that ships.
+ */
+import {
+  CONDITIONAL_WRITES_UNKNOWN,
+  PRECONDITION_BODY_FIELD,
+  PRECONDITION_HEADER,
+  etagFor,
+  isVersion,
+  newestRevision,
+  parseStaleSaveRefusal,
+  preconditionFor,
+  readConditionalWriteCapability,
+  toVersion,
+  versionFromEtag,
+  versionFromRecord,
+  versionFromWriteOutcome,
+} from '../conditional-write';
+
+describe('version 0 is a real version', () => {
+  // Every record predating the revision trail reads 0, and the server accepts 0
+  // back. `if (version)` would silently unguard exactly the oldest records.
+  it('treats 0 as a version and sends it', () => {
+    expect(isVersion(0)).toBe(true);
+    expect(preconditionFor(0)).toEqual({
+      headers: { [PRECONDITION_HEADER]: '"0"' },
+      body: {},
+      guards: true,
+    });
+  });
+
+  it('rejects the values that are not integer versions', () => {
+    for (const bad of [undefined, null, '', 'x', 1.5, true, false, NaN, {}, []]) {
+      expect(isVersion(bad)).toBe(false);
+    }
+  });
+
+  it('honours a numeric string but never a bool', () => {
+    expect(toVersion('3')).toBe(3);
+    expect(toVersion(' 3 ')).toBe(3);
+    expect(toVersion('-1')).toBe(-1);
+    expect(toVersion(true)).toBeUndefined();
+    expect(toVersion('1.5')).toBeUndefined();
+  });
+});
+
+describe('an unknown version still saves', () => {
+  // THE POSTURE: enforced when present, optional when absent. A guard that can
+  // make a save impossible is worse than the overwrite it prevents.
+  it('asserts nothing rather than refusing to build a write', () => {
+    expect(preconditionFor(undefined)).toEqual({ headers: {}, body: {}, guards: false });
+  });
+});
+
+describe('one spelling per call', () => {
+  // `preconditions.enforce` checks BOTH sources and refuses if EITHER disagrees,
+  // so a stale If-Match beside a fresh expected_version refuses itself with a
+  // 412 that looks exactly like a real conflict.
+  it('sends If-Match and leaves the body untouched', () => {
+    const parts = preconditionFor(7, 'header');
+    expect(parts.headers).toEqual({ 'If-Match': '"7"' });
+    expect(parts.body).toEqual({});
+  });
+
+  it('sends expected_version and leaves the headers untouched', () => {
+    const parts = preconditionFor(7, 'body');
+    expect(parts.body).toEqual({ expected_version: 7 });
+    expect(parts.headers).toEqual({});
+  });
+
+  it('names the body field at the top level, never inside data', () => {
+    // Inside the blob it stops being a precondition and starts being stored.
+    expect(PRECONDITION_BODY_FIELD).toBe('expected_version');
+    expect(Object.keys(preconditionFor(1, 'body').body)).toEqual(['expected_version']);
+  });
+
+  it('quotes the validator strongly, with no W/', () => {
+    expect(etagFor(12)).toBe('"12"');
+  });
+});
+
+describe('reading the version back', () => {
+  it('reads the read-only field off a record', () => {
+    expect(versionFromRecord({ id: 'a', version: 4 })).toBe(4);
+    expect(versionFromRecord({ id: 'a' })).toBeUndefined();
+    expect(versionFromRecord(null)).toBeUndefined();
+  });
+
+  it('parses a quoted ETag, a list and a weak validator', () => {
+    expect(versionFromEtag('"3"')).toBe(3);
+    expect(versionFromEtag('"1", "3"')).toBe(1);
+    expect(versionFromEtag('W/"5"')).toBe(5);
+    expect(versionFromEtag('"0"')).toBe(0);
+  });
+
+  it('reads * as no version at all', () => {
+    // It asserts only that a representation exists, so it guards nothing — and
+    // sending it back would record `precondition: none` for a write the client
+    // believed it had checked.
+    expect(versionFromEtag('*')).toBeUndefined();
+    expect(versionFromEtag('')).toBeUndefined();
+    expect(versionFromEtag(undefined)).toBeUndefined();
+  });
+
+  describe('off the WRITE response — the one that makes autosave free', () => {
+    // THE BODY IS AUTHORITATIVE, not the header. ETag is not CORS-safelisted and
+    // tenant-starter sets no CORS_EXPOSE_HEADERS, so a cross-origin caller reads
+    // null — silently, and only on the write path. The server stamps the header
+    // FROM `response.data["version"]`, so the two cannot disagree.
+    it('prefers the body field over the header', () => {
+      expect(
+        versionFromWriteOutcome({
+          body: { version: 9 },
+          headers: new Headers({ ETag: '"9"' }),
+        }),
+      ).toBe(9);
+    });
+
+    it('still reads the version when the header is invisible', () => {
+      expect(versionFromWriteOutcome({ body: { version: 9 }, headers: undefined })).toBe(9);
+    });
+
+    it('falls back to the header when the body carries no version', () => {
+      expect(versionFromWriteOutcome({ body: {}, headers: new Headers({ ETag: '"4"' }) })).toBe(4);
+    });
+
+    it('reads a plain header record case-insensitively', () => {
+      expect(versionFromWriteOutcome({ headers: { etag: '"6"' } })).toBe(6);
+    });
+
+    it('is undefined when nothing said — leaving the next save unguarded, not broken', () => {
+      expect(versionFromWriteOutcome({})).toBeUndefined();
+    });
+  });
+});
+
+describe('the refusal', () => {
+  const body = {
+    detail: 'the record changed since it was loaded: version 2 was sent and the record is now at version 3. Reload it, re-apply the change and save again.',
+    current_version: 3,
+  };
+
+  it('is read off a resolved 412 outcome', () => {
+    expect(parseStaleSaveRefusal({ status: 412, body })).toEqual({
+      currentVersion: 3,
+      detail: body.detail,
+    });
+  });
+
+  it('is read off a THROWN 412, which is what a wrapper does', () => {
+    expect(parseStaleSaveRefusal({ response: { status: 412, data: body } })).toEqual({
+      currentVersion: 3,
+      detail: body.detail,
+    });
+    expect(parseStaleSaveRefusal({ statusCode: 412, data: body })?.currentVersion).toBe(3);
+  });
+
+  it('reads currentVersion in the camelised spelling too', () => {
+    // The shared API client camelCases every response key recursively and has no
+    // preserve list — including on an error body, which is where it would be
+    // found last.
+    expect(parseStaleSaveRefusal({ status: 412, body: { currentVersion: 5 } })).toEqual({
+      currentVersion: 5,
+    });
+  });
+
+  it('keeps current_version an integer', () => {
+    // The server assigns `detail` after super().__init__ specifically so DRF
+    // does not coerce this to "3". Retrying with the exact value lands.
+    const parsed = parseStaleSaveRefusal({ status: 412, body });
+    expect(typeof parsed?.currentVersion).toBe('number');
+  });
+
+  it('survives a 412 that names nothing, because the dialog must still open', () => {
+    expect(parseStaleSaveRefusal({ status: 412 })).toEqual({});
+    expect(parseStaleSaveRefusal({ status: 412, body: 'nope' })).toEqual({});
+  });
+
+  it('is not a refusal for any other status', () => {
+    for (const status of [200, 201, 400, 403, 404, 409, 500, undefined]) {
+      expect(parseStaleSaveRefusal({ status, body })).toBeUndefined();
+    }
+    // 412 and not 409: 409 is what this viewset answers when the resource's own
+    // STATE refuses a change. A stale validator is a different thing.
+    expect(parseStaleSaveRefusal({ status: 409, body })).toBeUndefined();
+  });
+});
+
+describe('feature detection', () => {
+  const live = {
+    entities: {
+      conditional_writes: true,
+      precondition_required: false,
+      precondition: {
+        token: 'version',
+        header: 'If-Match',
+        body_field: 'expected_version',
+        refused_with: 412,
+        inert_without_type_history: true,
+      },
+    },
+  };
+
+  it('reads the live document', () => {
+    expect(readConditionalWriteCapability(live)).toEqual({
+      conditionalWrites: true,
+      preconditionRequired: false,
+      inertWithoutTypeHistory: true,
+      header: 'If-Match',
+      bodyField: 'expected_version',
+    });
+  });
+
+  it('defaults a fork that does not answer to NOT guarded', () => {
+    // A build predating 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.
+    for (const absent of [undefined, null, {}, { entities: {} }, 'nope']) {
+      expect(readConditionalWriteCapability(absent).conditionalWrites).toBe(false);
+    }
+    expect(CONDITIONAL_WRITES_UNKNOWN.conditionalWrites).toBe(false);
+  });
+
+  it('reads the camelised document too', () => {
+    expect(
+      readConditionalWriteCapability({ entities: { conditionalWrites: true } }).conditionalWrites,
+    ).toBe(true);
+  });
+
+  it('never reports precondition_required, which no build sets', () => {
+    // A client reading `true` here would stop making writes it is entitled to.
+    expect(readConditionalWriteCapability(live).preconditionRequired).toBe(false);
+  });
+});
+
+describe('row 0 of the trail is the newest', () => {
+  // The route orders `-version, -created_at`. An ordering flip would make the
+  // dialog confidently name whoever CREATED the record.
+  it('picks the highest version', () => {
+    expect(newestRevision([{ id: 'c', version: 3 }, { id: 'a', version: 1 }])?.id).toBe('c');
+    expect(newestRevision([{ id: 'a', version: 1 }, { id: 'c', version: 3 }])?.id).toBe('c');
+  });
+
+  it('is undefined on an empty or absent page', () => {
+    expect(newestRevision([])).toBeUndefined();
+    expect(newestRevision(undefined)).toBeUndefined();
+  });
+});