@startsimpli/ui 0.4.135 → 0.4.137

package/src/components/history/RevisionFields.tsx

@@ -0,0 +1,224 @@
+'use client';
+
+/**
+ * What moved inside one sitting, field by field (bd startsim-g4rwo).
+ *
+ * ── THE THREE WAYS A FIELD CAN BE NAMED WITHOUT ITS VALUES ──────────────────
+ *
+ * All three arrive as `{}` and they mean different things, so rendering them
+ * the same way — or worse, rendering `{}` as "changed to nothing" — turns a
+ * permission boundary and a storage cap into apparent data loss. Each gets its
+ * own sentence:
+ *
+ * - WITHHELD (`redacted_fields` names it): you are not allowed to read this
+ *   field, so you may not read its history either. The FACT of the edit is
+ *   real and is shown; the values are not. This route serves every historical
+ *   value a record ever held, which makes it a RICHER leak than the row read —
+ *   so the gate is honoured here and SAID OUT LOUD, because silence reads as
+ *   data loss and would send somebody looking for a bug.
+ * - OMITTED (`metadata.values_omitted`): the whole revision was over the byte
+ *   cap, so every field is named and no values were stored. Nobody is being
+ *   kept out; the values were never written.
+ * - TRUNCATED (`truncated: true` on the entry): the value was too large to
+ *   store. The critical consequence is that A MISSING SIDE NOW SAYS NOTHING —
+ *   everywhere else a missing `after` means the write DELETED the key — so the
+ *   created/deleted inference is suppressed and the diff is REFUSED with its
+ *   reason, rather than showing a deletion that never happened.
+ */
+import { useState } from 'react';
+import { ChevronRight, EyeOff, Scissors } from 'lucide-react';
+
+import { cn } from '../../lib/utils';
+import { DiffViewer } from '../diff';
+import {
+  canDiffFieldChange,
+  classifyFieldChange,
+  type FoldedFieldChange,
+  type RevisionSitting,
+} from './revision-history';
+import { unifiedTextDiff } from './text-diff';
+
+/** A stored value as one line of text, for the side-by-side summary. Objects
+ *  are JSON so a reader can at least see the shape; nothing is invented. */
+function preview(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (value === null) return 'null';
+  if (value === undefined) return '';
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+const CLAMP = 'max-h-40 overflow-y-auto whitespace-pre-wrap break-words';
+
+/** One side of a change. ABSENCE IS RENDERED AS ABSENCE — an em dash with
+ *  screen-reader text — never as an empty box that looks like "" was stored. */
+function Side({ label, has, value }: { label: string; has: boolean; value: unknown }) {
+  return (
+    <div className="min-w-0 flex-1">
+      <div className="mb-1 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">
+        {label}
+      </div>
+      {has ? (
+        <pre className={cn('rounded border border-border bg-muted/40 p-2 font-mono text-xs', CLAMP)}>
+          {preview(value)}
+        </pre>
+      ) : (
+        <p className="rounded border border-dashed border-border p-2 text-xs text-muted-foreground">
+          <span aria-hidden="true">—</span>
+          <span className="sr-only">not set</span>
+          <span className="ms-1">not set</span>
+        </p>
+      )}
+    </div>
+  );
+}
+
+function FieldBody({ field, change }: { field: string; change: FoldedFieldChange }) {
+  const kind = classifyFieldChange(change);
+
+  if (kind === 'withheld') {
+    return (
+      <p className="flex items-start gap-2 text-xs text-muted-foreground">
+        <EyeOff className="mt-px h-3.5 w-3.5 shrink-0" aria-hidden="true" />
+        <span>
+          This field was changed, but <strong className="font-medium text-foreground">its
+          values are not shown to you</strong> — your access does not include reading{' '}
+          <code className="rounded bg-muted px-1">{field}</code> on this record. The edit itself
+          is real and is recorded.
+        </span>
+      </p>
+    );
+  }
+
+  if (kind === 'omitted') {
+    return (
+      <p className="flex items-start gap-2 text-xs text-muted-foreground">
+        <Scissors className="mt-px h-3.5 w-3.5 shrink-0" aria-hidden="true" />
+        <span>
+          This field changed, but this revision was too large to store its values. The field
+          names were kept; the before and after were not written.
+        </span>
+      </p>
+    );
+  }
+
+  return (
+    <div className="space-y-2">
+      {kind === 'truncated' && (
+        <p className="flex items-start gap-2 text-xs text-muted-foreground">
+          <Scissors className="mt-px h-3.5 w-3.5 shrink-0" aria-hidden="true" />
+          <span>
+            This value was too large to store in full, so what is shown may be a prefix and{' '}
+            <strong className="font-medium text-foreground">a missing side means nothing
+            here</strong>. No comparison is offered, because a comparison against a shortened
+            value would show a deletion that never happened.
+          </span>
+        </p>
+      )}
+      <div className="flex flex-wrap gap-3 sm:flex-nowrap">
+        <Side label="Before" has={change.hasBefore} value={change.before} />
+        <Side label="After" has={change.hasAfter} value={change.after} />
+      </div>
+      {canDiffFieldChange(change) && (
+        <DiffViewer
+          diff={unifiedTextDiff(String(change.before), String(change.after), field)}
+          emptyLabel="No line-level change"
+          className="max-h-72 overflow-auto rounded border border-border"
+        />
+      )}
+    </div>
+  );
+}
+
+/** The one-word verdict next to a field name. Neutral tokens throughout: a
+ *  deletion is a thing a reviewer did on purpose far more often than it is an
+ *  accident, so it is not painted as an error. */
+const KIND_LABEL: Record<ReturnType<typeof classifyFieldChange>, string> = {
+  withheld: 'not shown to you',
+  omitted: 'values not stored',
+  truncated: 'too large to store',
+  created: 'set',
+  deleted: 'cleared',
+  updated: 'changed',
+};
+
+export interface RevisionFieldsProps {
+  sitting: RevisionSitting;
+  /** Map a wire field name to something a reader recognises. Identity by
+   *  default — see `types.ts` on why this module never re-cases a name. */
+  fieldLabel?: (field: string) => string;
+}
+
+export function RevisionFields({ sitting, fieldLabel = (f) => f }: RevisionFieldsProps) {
+  const [open, setOpen] = useState<string | null>(null);
+  const entries: Array<[string, FoldedFieldChange]> = [
+    ...Object.keys(sitting.changed)
+      .sort()
+      .map((field) => [field, sitting.changed[field]!] as [string, FoldedFieldChange]),
+    // The name COLUMN, kept namespaced away from the data keys because a tenant
+    // may declare a data key literally called "name".
+    ...(sitting.name ? ([['name (title)', sitting.name]] as Array<[string, FoldedFieldChange]>) : []),
+  ];
+
+  return (
+    <div className="space-y-2" data-testid="revision-fields">
+      {/* AN ATTEMPT IS NOT A CHANGE. A machine tried to write and
+          `human_edits.guard_machine_write` stopped it, so the record did not
+          move — and the whole value of this row is that the attempt is on the
+          record. It is listed separately from `changed` for that reason. */}
+      {sitting.preserved.length > 0 && (
+        <ul className="space-y-1" data-testid="revision-preserved">
+          {sitting.preserved.map((field) => (
+            <li key={field} className="text-xs text-muted-foreground">
+              <code className="rounded bg-muted px-1 text-foreground">{fieldLabel(field)}</code>{' '}
+              was not written — a person&apos;s edit was kept instead.
+            </li>
+          ))}
+        </ul>
+      )}
+
+      {sitting.regenerate.length > 0 && (
+        <p className="text-xs text-muted-foreground" data-testid="revision-regenerate">
+          Claimed permission to re-author{' '}
+          {sitting.regenerate.map((f) => fieldLabel(f)).join(', ')}.
+        </p>
+      )}
+
+      {entries.length > 0 && (
+        <ul className="divide-y divide-border rounded border border-border">
+          {entries.map(([field, change]) => {
+            const kind = classifyFieldChange(change);
+            const isOpen = open === field;
+            return (
+              <li key={field}>
+                <button
+                  type="button"
+                  aria-expanded={isOpen}
+                  onClick={() => setOpen(isOpen ? null : field)}
+                  className="flex w-full items-center gap-2 px-2 py-1.5 text-left text-xs transition-colors hover:bg-accent"
+                >
+                  <ChevronRight
+                    className={cn('h-3.5 w-3.5 shrink-0 transition-transform', isOpen && 'rotate-90')}
+                    aria-hidden="true"
+                  />
+                  <code className="min-w-0 truncate font-mono text-foreground">
+                    {fieldLabel(field)}
+                  </code>
+                  <span className="ms-auto shrink-0 text-muted-foreground">{KIND_LABEL[kind]}</span>
+                </button>
+                {isOpen && (
+                  <div className="border-t border-border bg-muted/20 px-3 py-2">
+                    <FieldBody field={field} change={change} />
+                  </div>
+                )}
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </div>
+  );
+}

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