@startsimpli/ui 0.4.135 → 0.4.136

package/src/components/history/__tests__/revision-history.test.ts

@@ -0,0 +1,355 @@
+/**
+ * The fold, and what one field change SAYS (bd startsim-g4rwo).
+ *
+ * Every case here is one of the server contract's edge cases that a naive
+ * reading gets wrong — absence vs null, truncation gating the delete
+ * inference, `{}` meaning three different things, and the four fold refusals.
+ * Pure module, so none of it needs a render or a backend.
+ */
+import {
+  COLLAPSE_WINDOW_MS,
+  actorKindOf,
+  actorKindSourceOf,
+  canDiffFieldChange,
+  classifyFieldChange,
+  foldRevisions,
+  normalizeFieldChange,
+  normalizeRevision,
+  sittingHeadline,
+  sittingSummary,
+} from '../revision-history'
+import type { EntityRevision } from '../types'
+
+const T0 = Date.parse('2026-10-05T12:00:00.000Z')
+const at = (msAfter: number) => new Date(T0 + msAfter).toISOString()
+
+function rev(over: Partial<EntityRevision> & { version: number }): EntityRevision {
+  return {
+    id: `r${over.version}`,
+    action: 'updated',
+    source: 'patch',
+    precondition: 'none',
+    created_at: at(0),
+    actor_sub: 'u1',
+    actor_label: 'jurga@ogmc.example',
+    actor_kind: 'person',
+    actor_kind_source: 'claim',
+    metadata: { changed: {} },
+    ...over,
+  }
+}
+
+describe('actorKindOf — three-state, failing closed', () => {
+  it('reads person and machine', () => {
+    expect(actorKindOf(rev({ version: 1, actor_kind: 'person' }))).toBe('person')
+    expect(actorKindOf(rev({ version: 1, actor_kind: 'machine' }))).toBe('machine')
+  })
+
+  it('reads an ABSENT kind as unknown, never as person', () => {
+    expect(actorKindOf({ id: 'x', version: 1 })).toBe('unknown')
+    expect(actorKindOf(rev({ version: 1, actor_kind: null }))).toBe('unknown')
+    expect(actorKindOf(rev({ version: 1, actor_kind: '' }))).toBe('unknown')
+  })
+
+  it('reads a value from outside the vocabulary as unknown', () => {
+    expect(actorKindOf(rev({ version: 1, actor_kind: 'robot' }))).toBe('unknown')
+  })
+
+  it('reads the CAMELISED spelling the shared API client produces', () => {
+    expect(actorKindOf({ id: 'x', version: 1, actorKind: 'machine' })).toBe('machine')
+    expect(actorKindSourceOf({ id: 'x', version: 1, actorKindSource: 'inferred' })).toBe('inferred')
+  })
+
+  it('distinguishes a claimed kind from an inferred one', () => {
+    expect(actorKindSourceOf(rev({ version: 1, actor_kind_source: 'claim' }))).toBe('claim')
+    expect(actorKindSourceOf(rev({ version: 1, actor_kind_source: 'inferred' }))).toBe('inferred')
+    expect(actorKindSourceOf({ id: 'x', version: 1 })).toBeUndefined()
+  })
+})
+
+describe('normalizeFieldChange — absence is the payload', () => {
+  it('a CREATED key has after and no before', () => {
+    const c = normalizeFieldChange({ after: 'hello' })
+    expect(c.hasBefore).toBe(false)
+    expect(c.hasAfter).toBe(true)
+    expect(classifyFieldChange(c)).toBe('created')
+  })
+
+  it('a DELETED key has before and no after', () => {
+    const c = normalizeFieldChange({ before: 'gone' })
+    expect(c.hasAfter).toBe(false)
+    expect(classifyFieldChange(c)).toBe('deleted')
+  })
+
+  it('a key set to NULL is an update, not a deletion — null is a real value', () => {
+    const c = normalizeFieldChange({ before: 'x', after: null })
+    expect(c.hasAfter).toBe(true)
+    expect(c.after).toBeNull()
+    expect(classifyFieldChange(c)).toBe('updated')
+  })
+
+  it('a key created AS null is created, not deleted', () => {
+    const c = normalizeFieldChange({ after: null })
+    expect(classifyFieldChange(c)).toBe('created')
+  })
+
+  it('a WITHHELD key is {} and classifies as withheld, not as a deletion', () => {
+    expect(classifyFieldChange(normalizeFieldChange({}, { withheld: true }))).toBe('withheld')
+  })
+
+  it('an OMITTED row’s key is {} and classifies as omitted', () => {
+    expect(classifyFieldChange(normalizeFieldChange({}, { omitted: true }))).toBe('omitted')
+  })
+
+  it('TRUNCATION WINS over the delete inference — a missing side says nothing', () => {
+    // before present, after absent, but truncated: this is NOT a deletion.
+    const c = normalizeFieldChange({ before: 'a very long prefix', truncated: true })
+    expect(classifyFieldChange(c)).toBe('truncated')
+    expect(classifyFieldChange(c)).not.toBe('deleted')
+  })
+
+  it('refuses to diff a truncated, withheld or omitted side', () => {
+    expect(canDiffFieldChange(normalizeFieldChange({ before: 'a', after: 'b', truncated: true }))).toBe(false)
+    expect(canDiffFieldChange(normalizeFieldChange({}, { withheld: true }))).toBe(false)
+    expect(canDiffFieldChange(normalizeFieldChange({}, { omitted: true }))).toBe(false)
+  })
+
+  it('diffs only when both sides are text', () => {
+    expect(canDiffFieldChange(normalizeFieldChange({ before: 'a', after: 'b' }))).toBe(true)
+    expect(canDiffFieldChange(normalizeFieldChange({ before: { a: 1 }, after: { a: 2 } }))).toBe(false)
+    expect(canDiffFieldChange(normalizeFieldChange({ after: 'new' }))).toBe(false)
+  })
+})
+
+describe('normalizeRevision', () => {
+  it('marks a field named in redacted_fields as withheld', () => {
+    const n = normalizeRevision(
+      rev({ version: 3, metadata: { changed: { body: {} } }, redacted_fields: ['body'] }),
+    )
+    expect(n.changed.body!.withheld).toBe(true)
+    expect(n.redacted).toEqual(['body'])
+  })
+
+  it('marks every field omitted when the ROW was over the cap', () => {
+    const n = normalizeRevision(
+      rev({ version: 3, metadata: { changed: { a: {}, b: {} }, values_omitted: true } }),
+    )
+    expect(n.valuesOmitted).toBe(true)
+    expect(n.changed.a!.omitted).toBe(true)
+    expect(n.changed.b!.omitted).toBe(true)
+  })
+
+  it('reads values_omitted in its camelised spelling too', () => {
+    const n = normalizeRevision(rev({ version: 1, metadata: { changed: { a: {} }, valuesOmitted: true } }))
+    expect(n.valuesOmitted).toBe(true)
+  })
+
+  it('a PRESERVED row with no changes is an ATTEMPT', () => {
+    const n = normalizeRevision(
+      rev({ version: 4, metadata: { changed: {}, preserved: ['blog'] } }),
+    )
+    expect(n.isAttempt).toBe(true)
+    expect(n.preserved).toEqual(['blog'])
+  })
+
+  it('a row that both changed and preserved something is NOT an attempt', () => {
+    const n = normalizeRevision(
+      rev({ version: 4, metadata: { changed: { seo: { after: 'x' } }, preserved: ['blog'] } }),
+    )
+    expect(n.isAttempt).toBe(false)
+  })
+
+  it('survives a row with no metadata at all', () => {
+    const n = normalizeRevision({ id: 'x', version: 1 })
+    expect(n.changed).toEqual({})
+    expect(n.isAttempt).toBe(false)
+    expect(n.actorKind).toBe('unknown')
+  })
+})
+
+describe('foldRevisions', () => {
+  it('folds consecutive same-actor saves inside the window into one sitting', () => {
+    const rows = [
+      rev({ version: 3, created_at: at(4000), metadata: { changed: { blog: { before: 'b', after: 'c' } } } }),
+      rev({ version: 2, created_at: at(2000), metadata: { changed: { blog: { before: 'a', after: 'b' } } } }),
+      rev({ version: 1, created_at: at(0), action: 'created', metadata: { changed: { blog: { after: 'a' } } } }),
+    ]
+    const folded = foldRevisions(rows)
+    // The create does not absorb the later edits.
+    expect(folded).toHaveLength(2)
+    expect(folded[0]!.saves).toBe(2)
+    expect(folded[1]!.action).toBe('created')
+  })
+
+  it('takes BEFORE from the oldest row and AFTER from the newest', () => {
+    const rows = [
+      rev({ version: 3, created_at: at(4000), metadata: { changed: { blog: { before: 'two', after: 'three' } } } }),
+      rev({ version: 2, created_at: at(2000), metadata: { changed: { blog: { before: 'one', after: 'two' } } } }),
+    ]
+    const [sitting] = foldRevisions(rows)
+    expect(sitting!.changed.blog!.before).toBe('one')
+    expect(sitting!.changed.blog!.after).toBe('three')
+    expect(sitting!.fromVersion).toBe(2)
+    expect(sitting!.toVersion).toBe(3)
+  })
+
+  it('does not fold across the window', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(COLLAPSE_WINDOW_MS + 1000) }),
+      rev({ version: 1, created_at: at(0) }),
+    ]
+    expect(foldRevisions(rows)).toHaveLength(2)
+  })
+
+  it('does not fold two different actors', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(1000), actor_sub: 'u2', actor_label: 'b@x' }),
+      rev({ version: 1, created_at: at(0), actor_sub: 'u1', actor_label: 'a@x' }),
+    ]
+    expect(foldRevisions(rows)).toHaveLength(2)
+  })
+
+  it('REFUSES to fold across a differing actor_kind even when the sub matches', () => {
+    // The healing window: one person's rows read unknown then person. Folding
+    // would stamp the sitting with whichever end won.
+    const rows = [
+      rev({ version: 2, created_at: at(1000), actor_kind: 'person', actor_kind_source: 'claim' }),
+      rev({ version: 1, created_at: at(0), actor_kind: 'unknown', actor_kind_source: 'inferred' }),
+    ]
+    const folded = foldRevisions(rows)
+    expect(folded).toHaveLength(2)
+    expect(folded[0]!.actorKind).toBe('person')
+    expect(folded[1]!.actorKind).toBe('unknown')
+  })
+
+  it('REFUSES to fold across a differing actor_kind_source', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(1000), actor_kind_source: 'claim' }),
+      rev({ version: 1, created_at: at(0), actor_kind_source: 'inferred' }),
+    ]
+    expect(foldRevisions(rows)).toHaveLength(2)
+  })
+
+  it('REFUSES to fold an ATTEMPT into a change', () => {
+    const rows = [
+      rev({
+        version: 2,
+        created_at: at(1000),
+        actor_sub: 'svc:n8n',
+        actor_kind: 'machine',
+        actor_kind_source: 'inferred',
+        metadata: { changed: {}, preserved: ['blog'] },
+      }),
+      rev({
+        version: 1,
+        created_at: at(0),
+        actor_sub: 'svc:n8n',
+        actor_kind: 'machine',
+        actor_kind_source: 'inferred',
+        metadata: { changed: { seo: { after: 'x' } } },
+      }),
+    ]
+    const folded = foldRevisions(rows)
+    expect(folded).toHaveLength(2)
+    expect(folded[0]!.isAttempt).toBe(true)
+    expect(folded[1]!.isAttempt).toBe(false)
+  })
+
+  it('folds two attempts together', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(1000), metadata: { changed: {}, preserved: ['seo'] } }),
+      rev({ version: 1, created_at: at(0), metadata: { changed: {}, preserved: ['blog'] } }),
+    ]
+    const folded = foldRevisions(rows)
+    expect(folded).toHaveLength(1)
+    expect(folded[0]!.preserved).toEqual(['blog', 'seo'])
+  })
+
+  it('carries a withheld flag FORWARD through a fold rather than dropping it', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(1000), metadata: { changed: { body: { before: 'x', after: 'y' } } } }),
+      rev({ version: 1, created_at: at(0), metadata: { changed: { body: {} } }, redacted_fields: ['body'] }),
+    ]
+    const [sitting] = foldRevisions(rows)
+    expect(sitting!.saves).toBe(2)
+    expect(sitting!.changed.body!.withheld).toBe(true)
+    expect(sitting!.redacted).toEqual(['body'])
+    expect(canDiffFieldChange(sitting!.changed.body!)).toBe(false)
+  })
+
+  it('carries a truncated flag forward, so a fold never produces a clean diff from a capped side', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(1000), metadata: { changed: { blog: { before: 'b', after: 'c' } } } }),
+      rev({ version: 1, created_at: at(0), metadata: { changed: { blog: { before: 'a', truncated: true } } } }),
+    ]
+    const [sitting] = foldRevisions(rows)
+    expect(sitting!.changed.blog!.truncated).toBe(true)
+    expect(canDiffFieldChange(sitting!.changed.blog!)).toBe(false)
+  })
+
+  it('windowMs of 0 renders a row per save', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(1000) }),
+      rev({ version: 1, created_at: at(0) }),
+    ]
+    expect(foldRevisions(rows, 0)).toHaveLength(2)
+  })
+
+  it('treats an out-of-order clock as the same sitting rather than inventing a precedence', () => {
+    const rows = [rev({ version: 2, created_at: at(0) }), rev({ version: 1, created_at: at(0) })]
+    expect(foldRevisions(rows)).toHaveLength(1)
+  })
+
+  it('returns nothing for an empty trail', () => {
+    expect(foldRevisions([])).toEqual([])
+  })
+})
+
+describe('sittingSummary / sittingHeadline', () => {
+  const sit = (rows: EntityRevision[]) => foldRevisions(rows)[0]!
+
+  it('a single save does not claim to be a sitting', () => {
+    expect(sittingSummary(sit([rev({ version: 1 })]))).toBe('1 save')
+  })
+
+  it('a collapsed sitting says it is a collapse, with its span', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(120_000) }),
+      rev({ version: 1, created_at: at(0) }),
+    ]
+    expect(sittingSummary(sit(rows))).toBe('2 saves over 2 min')
+  })
+
+  it('a sub-minute burst reports the count without a misleading 0 min', () => {
+    const rows = [rev({ version: 2, created_at: at(3000) }), rev({ version: 1, created_at: at(0) })]
+    expect(sittingSummary(sit(rows))).toBe('2 saves')
+  })
+
+  it('names the fields it edited', () => {
+    const s = sit([rev({ version: 1, metadata: { changed: { blog: { after: 'x' }, seo: { after: 'y' } } } })])
+    expect(sittingHeadline(s)).toBe('Edited blog and seo')
+  })
+
+  it('counts instead of listing beyond three fields', () => {
+    const changed = Object.fromEntries(['a', 'b', 'c', 'd'].map((k) => [k, { after: '1' }]))
+    const s = sit([rev({ version: 1, metadata: { changed } })])
+    expect(sittingHeadline(s)).toBe('Edited 4 fields')
+  })
+
+  it('AN ATTEMPT READS AS AN ATTEMPT — the sentence nobody could produce', () => {
+    const s = sit([
+      rev({ version: 1, metadata: { changed: {}, preserved: ['team_verdict'] } }),
+    ])
+    expect(sittingHeadline(s)).toBe('Tried to write team_verdict — held back')
+  })
+
+  it('a name-only move reads as a rename', () => {
+    const s = sit([rev({ version: 2, metadata: { changed: {}, name: { before: 'a', after: 'b' } } })])
+    expect(sittingHeadline(s)).toBe('Renamed the record')
+  })
+
+  it('applies a fieldLabel mapping', () => {
+    const s = sit([rev({ version: 1, metadata: { changed: { team_verdict: { after: 'x' } } } })])
+    expect(sittingHeadline(s, (f) => f.replace('_', ' '))).toBe('Edited team verdict')
+  })
+})

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

@@ -0,0 +1,59 @@
+/**
+ * Ported from marketing-agents-web `src/lib/__tests__/blog-diff.test.ts` with
+ * the module (bd startsim-g4rwo). Same assertions, jest instead of vitest, and
+ * the generic `unifiedTextDiff` name — see `text-diff.ts` on the rename.
+ */
+import { parseDiffFiles } from '../../diff'
+import { diffLines, unifiedTextDiff } from '../text-diff'
+
+describe('diffLines', () => {
+  it('marks equal / deleted / inserted lines in output order', () => {
+    expect(diffLines(['a', 'b', 'c'], ['a', 'x', 'c'])).toEqual([
+      { type: 'eq', line: 'a' },
+      { type: 'del', line: 'b' },
+      { type: 'ins', line: 'x' },
+      { type: 'eq', line: 'c' },
+    ])
+  })
+})
+
+describe('unifiedTextDiff', () => {
+  it('returns "" for identical values', () => {
+    expect(unifiedTextDiff('same\ntext', 'same\ntext')).toBe('')
+  })
+
+  it('emits a git-style block the shared DiffViewer parser can read', () => {
+    const diff = unifiedTextDiff(
+      'Line one\nLine two\nLine three',
+      'Line one\nLine 2\nLine three',
+      'blog',
+    )
+    expect(diff).toContain('diff --git a/blog b/blog')
+    expect(diff).toMatch(/^@@ -\d+,\d+ \+\d+,\d+ @@$/m)
+    expect(diff).toContain('-Line two')
+    expect(diff).toContain('+Line 2')
+    const files = parseDiffFiles(diff)
+    expect(files).toHaveLength(1)
+    expect(files[0]!.filePath).toBe('blog')
+  })
+
+  it('keeps context lines but not the whole document', () => {
+    const oldText = Array.from({ length: 20 }, (_, i) => `line ${i}`).join('\n')
+    const newText = oldText.replace('line 10', 'LINE TEN')
+    const body = unifiedTextDiff(oldText, newText)
+      .split('\n')
+      .filter((l) => /^[ +-]/.test(l) && !l.startsWith('+++') && !l.startsWith('---'))
+    expect(body).toContain('-line 10')
+    expect(body).toContain('+LINE TEN')
+    expect(body).toContain(' line 7')
+    expect(body).not.toContain(' line 0')
+  })
+
+  it('names the field in the header, so the rendered diff says what moved', () => {
+    expect(unifiedTextDiff('a', 'b', 'linkedin')).toContain('diff --git a/linkedin b/linkedin')
+  })
+
+  it('tolerates CRLF and a trailing newline without inventing a last line', () => {
+    expect(unifiedTextDiff('a\r\nb\r\n', 'a\nb\n')).toBe('')
+  })
+})

package/src/components/history/index.ts

@@ -0,0 +1,62 @@
+/**
+ * @startsimpli/ui/history — the shared record history panel (bd startsim-g4rwo).
+ *
+ * "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
+ * folds with, so a foundry fork holds an injected client and its theme
+ * classNames rather than its own timeline, its own fold and its own idea of
+ * what `{}` means (rule #9).
+ *
+ * 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
+ * `kind`/`kindSource` — rather than deciding locally, because "absent" read as
+ * "a machine did this" is the single worst failure available here.
+ */
+export { RecordHistoryPanel, REVISION_ENTRY_TYPES } from './RecordHistoryPanel';
+export type { RecordHistoryPanelProps } from './RecordHistoryPanel';
+
+export { RevisionFields } from './RevisionFields';
+export type { RevisionFieldsProps } from './RevisionFields';
+
+export {
+  RECORD_HISTORY_PANEL_DEFAULTS,
+  type RecordHistoryPanelClassNames,
+} from './record-history-panel-default-class-names';
+
+export {
+  COLLAPSE_WINDOW_MS,
+  actorKindOf,
+  actorKindSourceOf,
+  canDiffFieldChange,
+  classifyFieldChange,
+  foldRevisions,
+  joinNames,
+  normalizeFieldChange,
+  normalizeRevision,
+  sittingFields,
+  sittingHeadline,
+  sittingSummary,
+} from './revision-history';
+export type {
+  FieldChangeKind,
+  FoldedFieldChange,
+  NormalizedRevision,
+  RevisionSitting,
+} from './revision-history';
+
+export { diffLines, unifiedTextDiff } from './text-diff';
+
+export type {
+  ActorKind,
+  ActorKindSource,
+  EntityRevision,
+  RevisionAction,
+  RevisionClient,
+  RevisionFieldChange,
+  RevisionMetadata,
+  RevisionPage,
+  RevisionPrecondition,
+  RevisionQuery,
+  RevisionSource,
+} from './types';

package/src/components/history/record-history-panel-default-class-names.ts

@@ -0,0 +1,29 @@
+/** Default Tailwind classes for {@link RecordHistoryPanel}. bd startsim-g4rwo.
+ *  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 RecordHistoryPanelClassNames {
+  root?: string;
+  header?: string;
+  heading?: string;
+  title?: string;
+  description?: string;
+  body?: string;
+  /** The panel-level sentences: the unrecorded-kind explanation, the redaction
+   *  notice and the "some write paths are not recorded" caveat. */
+  notice?: string;
+  footer?: string;
+  countLine?: string;
+}
+
+export const RECORD_HISTORY_PANEL_DEFAULTS: Required<RecordHistoryPanelClassNames> = {
+  root: 'rounded-lg border border-border bg-card',
+  header: 'flex flex-wrap items-start justify-between gap-2 border-b border-border px-5 py-3',
+  heading: 'space-y-1',
+  title: 'font-medium text-foreground',
+  description: 'text-xs text-muted-foreground',
+  body: 'max-h-[32rem] overflow-y-auto px-5 py-4',
+  notice: 'border-b border-border px-5 py-2 text-xs text-muted-foreground',
+  footer: 'border-t border-border px-5 py-3 text-sm',
+  countLine: 'border-t border-border px-5 py-2 text-xs text-muted-foreground',
+};