@startsimpli/ui 0.4.135 → 0.4.137

package/src/components/history/__tests__/use-conditional-save.test.tsx

@@ -0,0 +1,387 @@
+/**
+ * The conflict state machine (bd startsim-jkkn7.3).
+ *
+ * The first describe block is the bead. Everything else is support.
+ */
+import { act, renderHook, waitFor } from '@testing-library/react';
+
+import {
+  useConditionalSave,
+  type ConditionalWriteAttempt,
+  type ConditionalWriteOutcome,
+} from '../useConditionalSave';
+import type { RevisionClient } from '../types';
+
+const REFUSAL = {
+  status: 412,
+  body: {
+    detail: 'the record changed since it was loaded: version 2 was sent and the record is now at version 3.',
+    current_version: 3,
+  },
+};
+
+function writer(outcomes: ConditionalWriteOutcome[]) {
+  const sent: ConditionalWriteAttempt[] = [];
+  const write = jest.fn(async (attempt: ConditionalWriteAttempt) => {
+    sent.push(attempt);
+    return outcomes[Math.min(sent.length - 1, outcomes.length - 1)]!;
+  });
+  return { client: { write }, sent, write };
+}
+
+const trail = (rows: unknown[]): RevisionClient => ({
+  list: jest.fn(async () => ({ results: rows as never[] })),
+});
+
+const JURGA = {
+  id: 'r3',
+  version: 3,
+  action: 'updated',
+  created_at: '2026-10-06T12:00:00Z',
+  actor_label: 'jurga@ogmc.example',
+  actor_kind: 'person',
+  actor_kind_source: 'claim',
+  metadata: { changed: { blog: { before: 'old', after: 'new' }, judge_verdict: { after: 'pass' } } },
+};
+
+describe('a refusal does not advance the held version', () => {
+  /* ─────────────────────────────────────────────────────────────────────────
+     THIS IS THE BEAD. The tempting shortcut is to read `current_version` off
+     the refusal, adopt it, and re-send: the error goes away and every
+     happy-path test still passes. It also reduces the guard to a decoration,
+     because a blind retry at the current version IS the overwrite the 412 just
+     prevented, with one extra round-trip.
+     ───────────────────────────────────────────────────────────────────────── */
+  it('keeps the loaded version after a 412 and never retries', async () => {
+    const { client, sent } = writer([REFUSAL]);
+    const { result } = renderHook(() => useConditionalSave({ client, version: 2 }));
+
+    await act(async () => {
+      await result.current.save({ data: { blog: 'three paragraphs' } });
+    });
+
+    expect(result.current.version).toBe(2);
+    expect(result.current.conflict?.currentVersion).toBe(3);
+    // One attempt. No retry at version 3.
+    expect(sent).toHaveLength(1);
+    expect(sent[0]!.headers).toEqual({ 'If-Match': '"2"' });
+  });
+
+  it('keeps the reviewer text on the conflict so it survives a reload', async () => {
+    // The accidental path is not a rash click — it is the host refetching the
+    // record to show "what changed" and its load-into-editor effect overwriting
+    // the text. The bytes are still here when that happens.
+    const { client } = writer([REFUSAL]);
+    const { result } = renderHook(() => useConditionalSave({ client, version: 2 }));
+    const typed = { data: { blog: 'three paragraphs the reviewer typed' } };
+
+    await act(async () => {
+      await result.current.save(typed);
+    });
+
+    expect(result.current.conflict?.refusedBody).toEqual(typed);
+  });
+
+  it('pauses autosave and sends nothing more while the conflict is open', async () => {
+    // The editor debounces at 1,200 ms. A 412 that neither paused nor
+    // deduplicated would repaint a modal on every keystroke burst.
+    const { client, sent } = writer([REFUSAL]);
+    const { result } = renderHook(() => useConditionalSave({ client, version: 2 }));
+
+    await act(async () => {
+      await result.current.save({ data: { blog: 'a' } });
+    });
+    expect(result.current.paused).toBe(true);
+
+    for (const keystroke of ['ab', 'abc', 'abcd']) {
+      await act(async () => {
+        const outcome = await result.current.save({ data: { blog: keystroke } });
+        expect(outcome.status).toBe('paused');
+      });
+    }
+    expect(sent).toHaveLength(1);
+  });
+
+  it('dismissing closes the dialog but does NOT resolve or resume', async () => {
+    // Escape, the backdrop and the close button are not a fourth option.
+    const { client, sent } = writer([REFUSAL]);
+    const { result } = renderHook(() => useConditionalSave({ client, version: 2 }));
+
+    await act(async () => {
+      await result.current.save({ data: { blog: 'a' } });
+    });
+    expect(result.current.dialogOpen).toBe(true);
+
+    act(() => result.current.dismissConflict());
+
+    expect(result.current.dialogOpen).toBe(false);
+    expect(result.current.paused).toBe(true);
+    expect(result.current.conflict).not.toBeNull();
+    expect(result.current.version).toBe(2);
+
+    await act(async () => {
+      expect((await result.current.save({ data: { blog: 'b' } })).status).toBe('paused');
+    });
+    expect(sent).toHaveLength(1);
+
+    act(() => result.current.reopenConflict());
+    expect(result.current.dialogOpen).toBe(true);
+  });
+});
+
+describe('the version is sent on every write', () => {
+  it('advances the held version from the write response body', async () => {
+    // This is what stops a 1,200 ms autosave needing a GET between saves.
+    const { client, sent } = writer([
+      { status: 200, body: { id: 'e1', version: 3 } },
+      { status: 200, body: { id: 'e1', version: 4 } },
+    ]);
+    const { result } = renderHook(() => useConditionalSave({ client, version: 2 }));
+
+    await act(async () => {
+      await result.current.save({ data: { blog: 'a' } });
+    });
+    expect(result.current.version).toBe(3);
+
+    await act(async () => {
+      await result.current.save({ data: { blog: 'b' } });
+    });
+    expect(result.current.version).toBe(4);
+
+    expect(sent.map((s) => s.headers['If-Match'])).toEqual(['"2"', '"3"']);
+  });
+
+  it('falls back to the ETag when the response body carries no version', async () => {
+    const { client, sent } = writer([
+      { status: 200, body: {}, headers: new Headers({ ETag: '"8"' }) },
+      { status: 200, body: {} },
+    ]);
+    const { result } = renderHook(() => useConditionalSave({ client, version: 2 }));
+
+    await act(async () => {
+      await result.current.save({ data: {} });
+    });
+    expect(result.current.version).toBe(8);
+
+    await act(async () => {
+      await result.current.save({ data: {} });
+    });
+    expect(sent[1]!.headers).toEqual({ 'If-Match': '"8"' });
+  });
+
+  it('saves unguarded rather than not at all when no version is known', async () => {
+    // Every caller in production today sends none; failing closed here would be
+    // a write outage on seven live tenants.
+    const { client, sent } = writer([{ status: 200, body: { version: 1 } }]);
+    const { result } = renderHook(() => useConditionalSave({ client }));
+
+    expect(result.current.guarded).toBe(false);
+    await act(async () => {
+      expect((await result.current.save({ data: { blog: 'a' } })).status).toBe('saved');
+    });
+    expect(sent[0]!.headers).toEqual({});
+    expect(sent[0]!.body).toEqual({ data: { blog: 'a' } });
+  });
+
+  it('uses the body spelling when headers cannot be set', async () => {
+    const { client, sent } = writer([{ status: 200, body: { version: 3 } }]);
+    const { result } = renderHook(() =>
+      useConditionalSave({ client, version: 2, spelling: 'body' }),
+    );
+
+    await act(async () => {
+      await result.current.save({ data: { blog: 'a' } });
+    });
+    expect(sent[0]!.body).toEqual({ data: { blog: 'a' }, expected_version: 2 });
+    expect(sent[0]!.headers).toEqual({});
+  });
+
+  it('understands a client that THROWS the 412 instead of resolving it', async () => {
+    const write = jest.fn(async () => {
+      throw { response: { status: 412, data: { current_version: 9 } } };
+    });
+    const { result } = renderHook(() => useConditionalSave({ client: { write }, version: 2 }));
+
+    await act(async () => {
+      expect((await result.current.save({ data: {} })).status).toBe('refused');
+    });
+    expect(result.current.conflict?.currentVersion).toBe(9);
+    expect(result.current.version).toBe(2);
+  });
+
+  it('reports a non-412 failure rather than throwing into an autosave', async () => {
+    const boom = new Error('gateway');
+    const write = jest.fn(async () => {
+      throw boom;
+    });
+    const { result } = renderHook(() => useConditionalSave({ client: { write }, version: 2 }));
+
+    await act(async () => {
+      expect(await result.current.save({ data: {} })).toEqual({ status: 'failed', error: boom });
+    });
+    // A transport failure is not a conflict: nothing is paused and nothing pops.
+    expect(result.current.conflict).toBeNull();
+    expect(result.current.paused).toBe(false);
+    expect(result.current.lastError).toBe(boom);
+  });
+});
+
+describe('who changed it comes from the trail, not from the 412', () => {
+  it('names the actor from the newest revision row', async () => {
+    const { client } = writer([REFUSAL]);
+    const { result } = renderHook(() =>
+      useConditionalSave({ client, version: 2, revisions: trail([JURGA]) }),
+    );
+
+    await act(async () => {
+      await result.current.save({ data: {} });
+    });
+    await waitFor(() => expect(result.current.conflict?.changedBy).toBeDefined());
+
+    expect(result.current.conflict?.changedBy?.actorLabel).toBe('jurga@ogmc.example');
+    expect(result.current.conflict?.changedBy?.actorKind).toBe('person');
+    // Field names are the tenant's declared attribute names and are never recased.
+    expect(Object.keys(result.current.conflict!.changedBy!.changed).sort()).toEqual([
+      'blog',
+      'judge_verdict',
+    ]);
+  });
+
+  it('reads an unrecorded kind as unknown and never as a machine', async () => {
+    const { client } = writer([REFUSAL]);
+    const { result } = renderHook(() =>
+      useConditionalSave({
+        client,
+        version: 2,
+        revisions: trail([{ ...JURGA, actor_kind: undefined, actor_kind_source: undefined }]),
+      }),
+    );
+
+    await act(async () => {
+      await result.current.save({ data: {} });
+    });
+    await waitFor(() => expect(result.current.conflict?.changedBy).toBeDefined());
+    expect(result.current.conflict?.changedBy?.actorKind).toBe('unknown');
+  });
+
+  it('opens the dialog anyway when the trail 404s, which means forbidden', async () => {
+    // The route is nested: a 404 says the PARENT record is unreadable, so
+    // history is withheld rather than absent.
+    const { client } = writer([REFUSAL]);
+    const revisions: RevisionClient = {
+      list: jest.fn(async () => {
+        throw { status: 404 };
+      }),
+    };
+    const { result } = renderHook(() => useConditionalSave({ client, version: 2, revisions }));
+
+    await act(async () => {
+      await result.current.save({ data: {} });
+    });
+    await waitFor(() => expect(result.current.conflict?.identityGap).toBe('forbidden'));
+    // Useful on current_version alone.
+    expect(result.current.conflict?.currentVersion).toBe(3);
+    expect(result.current.dialogOpen).toBe(true);
+  });
+
+  it('opens the dialog with no trail client at all', async () => {
+    const { client } = writer([REFUSAL]);
+    const { result } = renderHook(() => useConditionalSave({ client, version: 2 }));
+
+    await act(async () => {
+      await result.current.save({ data: {} });
+    });
+    await waitFor(() => expect(result.current.conflict?.identityGap).toBe('no-client'));
+    expect(result.current.dialogOpen).toBe(true);
+  });
+
+  it('reports an empty trail as empty rather than as nobody', async () => {
+    const { client } = writer([REFUSAL]);
+    const { result } = renderHook(() =>
+      useConditionalSave({ client, version: 2, revisions: trail([]) }),
+    );
+
+    await act(async () => {
+      await result.current.save({ data: {} });
+    });
+    await waitFor(() => expect(result.current.conflict?.identityGap).toBe('empty'));
+  });
+});
+
+describe('resolving is a deliberate act', () => {
+  it('keepMine re-sends the refused text at the version the server named', async () => {
+    const { client, sent } = writer([REFUSAL, { status: 200, body: { version: 4 } }]);
+    const { result } = renderHook(() => useConditionalSave({ client, version: 2 }));
+    const typed = { data: { blog: 'three paragraphs' } };
+
+    await act(async () => {
+      await result.current.save(typed);
+    });
+    await act(async () => {
+      expect((await result.current.keepMine()).status).toBe('saved');
+    });
+
+    expect(sent).toHaveLength(2);
+    // Adopting current_version is legitimate HERE and nowhere else.
+    expect(sent[1]!.headers).toEqual({ 'If-Match': '"3"' });
+    expect(sent[1]!.body).toEqual(typed);
+    expect(result.current.version).toBe(4);
+    expect(result.current.conflict).toBeNull();
+    expect(result.current.paused).toBe(false);
+  });
+
+  it('raises a FRESH conflict when keepMine is itself refused', async () => {
+    // A third writer moved the record again while the dialog was open.
+    const { client } = writer([
+      REFUSAL,
+      { status: 412, body: { detail: 'again', current_version: 5 } },
+    ]);
+    const { result } = renderHook(() => useConditionalSave({ client, version: 2 }));
+
+    await act(async () => {
+      await result.current.save({ data: { blog: 'mine' } });
+    });
+    await act(async () => {
+      expect((await result.current.keepMine()).status).toBe('refused');
+    });
+
+    expect(result.current.conflict?.currentVersion).toBe(5);
+    expect(result.current.conflict?.refusedBody).toEqual({ data: { blog: 'mine' } });
+    expect(result.current.paused).toBe(true);
+    expect(result.current.version).toBe(2);
+  });
+
+  it('acceptTheirs clears the conflict and adopts their version for the reload', async () => {
+    const { client } = writer([REFUSAL]);
+    const { result } = renderHook(() => useConditionalSave({ client, version: 2 }));
+
+    await act(async () => {
+      await result.current.save({ data: {} });
+    });
+    act(() => result.current.acceptTheirs());
+
+    expect(result.current.conflict).toBeNull();
+    expect(result.current.paused).toBe(false);
+    expect(result.current.version).toBe(3);
+  });
+
+  it('re-seeds when the host loads a different record', async () => {
+    const { client } = writer([{ status: 200, body: { version: 2 } }]);
+    const { result, rerender } = renderHook(
+      ({ version }: { version?: number }) => useConditionalSave({ client, version }),
+      { initialProps: { version: undefined as number | undefined } },
+    );
+
+    expect(result.current.version).toBeUndefined();
+    rerender({ version: 7 });
+    expect(result.current.version).toBe(7);
+
+    // A save's own advance is not stomped by a re-render carrying the old prop.
+    await act(async () => {
+      await result.current.save({ data: {} });
+    });
+    expect(result.current.version).toBe(2);
+    rerender({ version: 7 });
+    expect(result.current.version).toBe(2);
+  });
+});