@startsimpli/ui 0.4.134 → 0.4.136

package/src/components/history/text-diff.ts

@@ -0,0 +1,139 @@
+/**
+ * Turn two revisions of one text field into a git-style unified diff string
+ * (bd startsim-g4rwo; originally marketing-agents-web `src/lib/blog-diff.ts`,
+ * bd 768w.16.10.5).
+ *
+ * This is what makes the epic's answer to "which paragraph moved" nearly free
+ * rather than a second build: {@link DiffViewer} already renders a RAW unified
+ * diff (it splits on `diff --git` headers, colourises `@@` hunks and `+`/`-`
+ * lines) and does no diffing itself, so showing a field against its previous
+ * value only needs that string synthesised from the two values. Pure and
+ * line-based (LCS), so it unit-tests without a backend and adds no dependency.
+ *
+ * RENAMED FROM `blog-diff` / `unifiedBlogDiff` ON THE WAY IN, deliberately.
+ * The algorithm never knew what a blog was — it takes two strings and a path
+ * label — and `packages/ui` is consumed by every foundry fork, most of which
+ * have no blogs. A shared module carrying one tenant's vocabulary is how
+ * surfaces end up unable to reuse it. `path` is what names the field in the
+ * rendered header, so a caller passes the field's own name.
+ *
+ * DO NOT CALL THIS ON A TRUNCATED SIDE. A diff over a silently truncated value
+ * shows a deletion that never happened; `canDiffFieldChange` in
+ * `revision-history.ts` is the gate, and the panel says why it refused rather
+ * than rendering nothing.
+ *
+ * The algorithm: an LCS edit script over lines, grouped into hunks with a few
+ * lines of surrounding context (like `git diff -U<n>`). Identical inputs yield
+ * '' so the viewer shows its own empty state rather than an all-context block.
+ */
+
+type Op = { type: 'eq' | 'del' | 'ins'; line: string };
+
+/** Split into lines, tolerating CRLF and a trailing newline (no phantom last line). */
+function toLines(text: string): string[] {
+  if (text === '') return [];
+  return text.replace(/\r\n/g, '\n').replace(/\n$/, '').split('\n');
+}
+
+/**
+ * A minimal LCS edit script between two line arrays. O(n*m) DP — a record field is a
+ * few hundred lines at most. Returns ops in output order: equal/deleted/inserted.
+ */
+export function diffLines(oldLines: string[], newLines: string[]): Op[] {
+  const n = oldLines.length;
+  const m = newLines.length;
+  // lcs[i][j] = LCS length of oldLines[i:] and newLines[j:].
+  const lcs: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      lcs[i][j] =
+        oldLines[i] === newLines[j]
+          ? lcs[i + 1][j + 1] + 1
+          : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+
+  const ops: Op[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (oldLines[i] === newLines[j]) {
+      ops.push({ type: 'eq', line: oldLines[i] });
+      i++;
+      j++;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      ops.push({ type: 'del', line: oldLines[i] });
+      i++;
+    } else {
+      ops.push({ type: 'ins', line: newLines[j] });
+      j++;
+    }
+  }
+  while (i < n) ops.push({ type: 'del', line: oldLines[i++] });
+  while (j < m) ops.push({ type: 'ins', line: newLines[j++] });
+  return ops;
+}
+
+/** A prefixed diff body line: ' ' context, '-' deletion, '+' insertion. */
+function prefixed(op: Op): string {
+  const mark = op.type === 'eq' ? ' ' : op.type === 'del' ? '-' : '+';
+  return `${mark}${op.line}`;
+}
+
+/**
+ * Build the unified diff of two text values as a single-file `diff --git` block the
+ * DiffViewer can render. `context` is the number of unchanged lines kept around
+ * each change (git's default 3). Returns '' when the bodies are identical.
+ */
+export function unifiedTextDiff(
+  oldText: string,
+  newText: string,
+  path = 'value.txt',
+  context = 3,
+): string {
+  if (oldText === newText) return '';
+  const ops = diffLines(toLines(oldText), toLines(newText));
+  if (!ops.some((op) => op.type !== 'eq')) return '';
+
+  // Indices of ops that are actual changes, expanded by `context` on each side and
+  // merged into contiguous hunk ranges.
+  const changed: number[] = [];
+  ops.forEach((op, idx) => {
+    if (op.type !== 'eq') changed.push(idx);
+  });
+
+  const ranges: Array<[number, number]> = [];
+  for (const idx of changed) {
+    const start = Math.max(0, idx - context);
+    const end = Math.min(ops.length - 1, idx + context);
+    const last = ranges[ranges.length - 1];
+    if (last && start <= last[1] + 1) {
+      last[1] = Math.max(last[1], end);
+    } else {
+      ranges.push([start, end]);
+    }
+  }
+
+  const lines: string[] = [`diff --git a/${path} b/${path}`];
+  for (const [start, end] of ranges) {
+    // 1-based line numbers of the hunk's first old/new line.
+    let oldStart = 1;
+    let newStart = 1;
+    for (let k = 0; k < start; k++) {
+      if (ops[k].type !== 'ins') oldStart++;
+      if (ops[k].type !== 'del') newStart++;
+    }
+    let oldCount = 0;
+    let newCount = 0;
+    const body: string[] = [];
+    for (let k = start; k <= end; k++) {
+      const op = ops[k];
+      if (op.type !== 'ins') oldCount++;
+      if (op.type !== 'del') newCount++;
+      body.push(prefixed(op));
+    }
+    lines.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
+    lines.push(...body);
+  }
+  return lines.join('\n');
+}

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/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'