@startsimpli/ui 0.4.135 → 0.4.137

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

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