@startsimpli/ui 0.4.135 → 0.4.136

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/__tests__/record-history-panel.test.tsx

@@ -0,0 +1,312 @@
+/**
+ * The rendered panel (bd startsim-g4rwo).
+ *
+ * The assertions that matter are the presentation rules, not the markup: a
+ * machine is always marked, a claimed person never is, `unknown` is CALM and
+ * explained once for the panel, a withheld field is named rather than shown as
+ * "changed to nothing", an attempt reads as an attempt, and the empty state
+ * never claims the record was never changed.
+ */
+import { render, screen, waitFor, fireEvent, within } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+import { ActorIdentity } from '../../ActorIdentity'
+import { RecordHistoryPanel } from '../RecordHistoryPanel'
+import type { EntityRevision, RevisionPage } from '../types'
+
+function mount(ui: React.ReactElement) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false, gcTime: 0 } },
+  })
+  return render(<QueryClientProvider client={client}>{ui}</QueryClientProvider>)
+}
+
+const T0 = Date.parse('2026-10-05T12:00:00.000Z')
+const at = (ms: number) => new Date(T0 + ms).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: { blog: { before: 'old', after: 'new' } } },
+    ...over,
+  }
+}
+
+function page(results: EntityRevision[], over: Partial<RevisionPage> = {}): RevisionPage {
+  return { count: results.length, next: null, previous: null, results, ...over }
+}
+
+const clientFor = (p: RevisionPage) => ({ list: jest.fn().mockResolvedValue(p) })
+
+describe('RecordHistoryPanel — the actor axis', () => {
+  it('ALWAYS marks a machine, and distinctly from a person', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([
+            rev({
+              version: 2,
+              actor_sub: 'svc:n8n-ogmc',
+              actor_label: 'svc:n8n-ogmc',
+              actor_kind: 'machine',
+              actor_kind_source: 'inferred',
+            }),
+            rev({ version: 1, created_at: at(-600_000) }),
+          ]),
+        )}
+      />,
+    )
+    const marks = await screen.findAllByTestId('actor-kind')
+    // Exactly ONE marker: the machine row. The claimed person gets none.
+    expect(marks).toHaveLength(1)
+    expect(marks[0]).toHaveTextContent('machine')
+  })
+
+  it('does NOT decorate a claimed person — the calm, common-good case', async () => {
+    mount(<RecordHistoryPanel client={clientFor(page([rev({ version: 1 })]))} />)
+    await screen.findByTestId('record-history-panel')
+    expect(screen.queryByTestId('actor-kind')).not.toBeInTheDocument()
+  })
+
+  it('renders UNKNOWN with no per-row badge, and explains it ONCE for the panel', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([
+            rev({ version: 2, actor_kind: 'unknown', actor_kind_source: 'inferred' }),
+            rev({
+              version: 1,
+              created_at: at(-600_000),
+              actor_kind: 'unknown',
+              actor_kind_source: 'inferred',
+            }),
+          ]),
+        )}
+      />,
+    )
+    const note = await screen.findByTestId('record-history-unknown-kind')
+    // ONE sentence for two unknown rows — not a badge per row, which is what
+    // would make the panel look broken for the whole rollout window.
+    expect(note).toBeInTheDocument()
+    expect(screen.queryByTestId('actor-kind')).not.toBeInTheDocument()
+    // And it must not read as a defect.
+    expect(note.textContent).toMatch(/not recorded/i)
+    expect(note.textContent).not.toMatch(/error|invalid|fail|broken|warning/i)
+  })
+
+  it('still says WHO on an unknown row — only the KIND is unrecorded', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(page([rev({ version: 1, actor_kind: 'unknown' })]))}
+      />,
+    )
+    expect(await screen.findByText('jurga@ogmc.example')).toBeInTheDocument()
+  })
+
+  it('does NOT show the unknown explanation when every row has a kind', async () => {
+    mount(<RecordHistoryPanel client={clientFor(page([rev({ version: 1 })]))} />)
+    await screen.findByTestId('record-history-panel')
+    expect(screen.queryByTestId('record-history-unknown-kind')).not.toBeInTheDocument()
+  })
+
+  it('marks a person whose kind was INFERRED, because that is a guess', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(page([rev({ version: 1, actor_kind_source: 'inferred' })]))}
+      />,
+    )
+    const mark = await screen.findByTestId('actor-kind')
+    expect(mark).toHaveTextContent(/inferred/)
+  })
+})
+
+describe('RecordHistoryPanel — redaction', () => {
+  it('names a withheld field at panel level instead of rendering it as empty', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([rev({ version: 1, metadata: { changed: { body: {} } }, redacted_fields: ['body'] })], {
+            redacted_fields: ['body'],
+          }),
+        )}
+      />,
+    )
+    const note = await screen.findByTestId('record-history-redacted')
+    expect(note).toHaveTextContent(/body/)
+    expect(note).toHaveTextContent(/not shown to you/i)
+  })
+
+  it('says a withheld field was changed but its values are not shown', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([rev({ version: 1, metadata: { changed: { body: {} } }, redacted_fields: ['body'] })]),
+        )}
+      />,
+    )
+    const row = await screen.findByRole('button', { name: /body/ })
+    expect(row).toHaveTextContent(/not shown to you/i)
+    fireEvent.click(row)
+    expect(await screen.findByText(/its\s*values are not shown to you/i)).toBeInTheDocument()
+  })
+
+  it('reads the camelised envelope roll-up too', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([rev({ version: 1, metadata: { changed: { body: {} } }, redactedFields: ['body'] })], {
+            redactedFields: ['body'],
+          }),
+        )}
+      />,
+    )
+    expect(await screen.findByTestId('record-history-redacted')).toHaveTextContent(/body/)
+  })
+})
+
+describe('RecordHistoryPanel — attempts, truncation and completeness', () => {
+  it('an ATTEMPT reads as an attempt, never as a change', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([
+            rev({
+              version: 1,
+              actor_sub: 'svc:n8n-ogmc',
+              actor_label: 'svc:n8n-ogmc',
+              actor_kind: 'machine',
+              actor_kind_source: 'inferred',
+              metadata: { changed: {}, preserved: ['team_verdict'] },
+            }),
+          ]),
+        )}
+      />,
+    )
+    expect(
+      await screen.findByText(/Tried to write team_verdict — held back/),
+    ).toBeInTheDocument()
+    expect(screen.getByTestId('revision-preserved')).toHaveTextContent(/was not written/i)
+  })
+
+  it('REFUSES to diff a truncated side and says why', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([
+            rev({
+              version: 1,
+              metadata: { changed: { blog: { before: 'prefix only', after: 'other', truncated: true } } },
+            }),
+          ]),
+        )}
+      />,
+    )
+    const row = await screen.findByRole('button', { name: /blog/ })
+    expect(row).toHaveTextContent(/too large to store/i)
+    fireEvent.click(row)
+    expect(
+      await screen.findByText(/a missing side means nothing here/i),
+    ).toBeInTheDocument()
+  })
+
+  it('NEVER claims the trail is complete', async () => {
+    mount(<RecordHistoryPanel client={clientFor(page([rev({ version: 1 })]))} />)
+    const note = await screen.findByTestId('record-history-incomplete')
+    expect(note).toHaveTextContent(/not recorded yet/i)
+  })
+
+  it('an empty history says "no edits recorded", not "never changed"', async () => {
+    mount(<RecordHistoryPanel client={clientFor(page([]))} />)
+    expect(await screen.findByText('No edits recorded for this record')).toBeInTheDocument()
+    expect(screen.queryByText(/never been changed|never changed/i)).not.toBeInTheDocument()
+    // The caveat still stands on an empty panel — a quiet trail is the exact
+    // case a reader would otherwise over-read.
+    expect(screen.getByTestId('record-history-incomplete')).toBeInTheDocument()
+  })
+})
+
+describe('RecordHistoryPanel — valid HTML', () => {
+  it('never nests the field list inside a <p>', async () => {
+    // REGRESSION (bd startsim-g4rwo): ActivityTimeline wrapped `detail` in a
+    // <p>, and a <ul>/<div> inside a <p> is invalid HTML that React reparents
+    // during hydration — a hydration mismatch on EVERY row. tsc passed and
+    // jsdom rendered it happily; only a real browser reported it.
+    mount(<RecordHistoryPanel client={clientFor(page([rev({ version: 1 })]))} />)
+    const fields = await screen.findByTestId('revision-fields')
+    expect(fields.closest('p')).toBeNull()
+  })
+})
+
+describe('RecordHistoryPanel — fetching', () => {
+  it('asks the server for pages, never for everything (rule 8)', async () => {
+    const client = clientFor(page([rev({ version: 1 })]))
+    mount(<RecordHistoryPanel client={client} pageSize={25} />)
+    await screen.findByTestId('record-history-panel')
+    expect(client.list).toHaveBeenCalledWith({ page: 1, pageSize: 25 })
+  })
+
+  it('folds across page boundaries — one sitting, not one per page', async () => {
+    const list = jest
+      .fn()
+      .mockResolvedValueOnce(
+        page([rev({ version: 2, created_at: at(2000) })], { count: 3, next: 'p2' }),
+      )
+      .mockResolvedValueOnce(page([rev({ version: 1, created_at: at(0) })], { count: 3 }))
+    mount(<RecordHistoryPanel client={{ list }} pageSize={1} />)
+    await screen.findByTestId('record-history-panel')
+    // jsdom has no IntersectionObserver, so the auto-load sentinel no-ops by
+    // design and the explicit button is the path under test.
+    fireEvent.click(await screen.findByRole('button', { name: 'Load more' }))
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(2))
+    // Both rows are the same actor inside the window, so after the second page
+    // loads they are ONE entry reporting 2 saves.
+    await waitFor(() => expect(screen.getByText('2 saves')).toBeInTheDocument())
+  })
+
+  it('a 404 says the history is not available, never "no history"', async () => {
+    const list = jest.fn().mockRejectedValue(Object.assign(new Error('Not Found'), { status: 404 }))
+    mount(<RecordHistoryPanel client={{ list }} />)
+    expect(await screen.findByText('History is not available to you')).toBeInTheDocument()
+    expect(screen.queryByText('No edits recorded for this record')).not.toBeInTheDocument()
+  })
+
+  it('any other failure offers a retry', async () => {
+    const list = jest.fn().mockRejectedValue(new Error('boom'))
+    mount(<RecordHistoryPanel client={{ list }} />)
+    expect(await screen.findByText('Could not load history')).toBeInTheDocument()
+  })
+})
+
+describe('ActorIdentity — the kind props are additive', () => {
+  it('renders exactly as before when no kind is passed', () => {
+    const { container } = render(<ActorIdentity actor={{ email: 'a@b.com' }} />)
+    expect(container.querySelector('[data-testid="actor-kind"]')).toBeNull()
+    expect(screen.getByTestId('actor-identity')).toHaveTextContent('a@b.com')
+  })
+
+  it('still renders the machine marker when the actor has NO label at all', () => {
+    // A service token can carry no email; dropping the row would hide the one
+    // fact the actor axis exists to record.
+    render(<ActorIdentity actor={{}} kind="machine" kindSource="inferred" />)
+    expect(screen.getByTestId('actor-kind')).toHaveTextContent('machine')
+  })
+
+  it('renders nothing at all when there is neither a label nor a kind worth marking', () => {
+    const { container } = render(<ActorIdentity actor={{}} kind="unknown" />)
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('carries the full truth in the title even when it draws no marker', () => {
+    render(<ActorIdentity actor={{ email: 'a@b.com' }} kind="unknown" />)
+    const el = screen.getByTestId('actor-identity')
+    expect(el).toHaveAttribute('data-actor-kind', 'unknown')
+  })
+})