@startsimpli/ui 0.4.140 → 0.4.142

package/src/components/collection/__tests__/drawer-precondition.test.tsx

@@ -0,0 +1,175 @@
+/**
+ * RED for bd startsim-jkkn7.20 — a drawer decision asserts the version of the
+ * blob it MERGED OVER, never a newer one.
+ *
+ * ReviewDrawer seeds its local `data` once per record id and every decision,
+ * the note and the status override merge onto it. It wrote through the
+ * two-argument `updateEntity(id, input)`, so the app could only assert the
+ * newest version its registry had seen — and every list refetch moves that. The
+ * reproduction (marketing-agents-web drawer-precondition.test.tsx): open at v3,
+ * another writer sets the angle (v4), the list refetches, Save note → If-Match
+ * "4" with the v3 angle, 200, the other writer's angle erased.
+ *
+ * The fix pinned here:
+ *   1. the drawer keeps the version WITH the data it holds, from `record.version`;
+ *   2. `updateEntity` takes an optional third argument `{ expectedVersion }`;
+ *   3. a successful write moves the drawer onto the SAVED record's version;
+ *   4. the Edit-fields `saved(record)` callback reseeds data and version.
+ * Same class, lower exposure: InlineReviewActions merges onto a list row and
+ * now asserts that row's version.
+ */
+import * as React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { ReviewDrawer } from '../ReviewDrawer';
+import { InlineReviewActions } from '../InlineReviewActions';
+import type { CollectionClient, EntityRecord, EntityTypeDef, Paginated } from '../types';
+
+const TOPIC_TYPE: EntityTypeDef = {
+  id: 1,
+  key: 'topic',
+  label: 'Topic',
+  attributes: [
+    {
+      id: 'status',
+      name: 'status',
+      dataType: 'enum',
+      required: false,
+      config: { choices: ['suggested', 'ready', 'written', 'rejected'] },
+    },
+    { id: 'title', name: 'title', dataType: 'text', required: false, config: {} },
+    { id: 'angle', name: 'angle', dataType: 'text', required: false, config: {} },
+    { id: 'team_verdict', name: 'team_verdict', dataType: 'text', required: false, config: {} },
+    { id: 'team_notes', name: 'team_notes', dataType: 'text', required: false, config: {} },
+  ],
+};
+
+function topic(version: number | undefined, data: Record<string, unknown> = {}): EntityRecord {
+  return {
+    id: 7,
+    entityType: 'topic',
+    externalId: null,
+    name: 'Qatar',
+    data: { title: 'Qatar', status: 'suggested', angle: 'v3 angle', ...data },
+    createdAt: '2026-09-01T00:00:00Z',
+    ...(version !== undefined ? { version } : {}),
+  };
+}
+
+const page = <T,>(results: T[]): Paginated<T> => ({ count: results.length, next: null, previous: null, results });
+
+function stubClient(nextVersion = 4) {
+  let v = nextVersion;
+  const updateEntity = jest.fn(
+    async (id: number | string, input: { data?: Record<string, unknown> }, _opts?: { expectedVersion?: number }) => ({
+      ...topic(v++, {}),
+      id: Number(id),
+      data: input.data ?? {},
+    }),
+  );
+  return {
+    listTypes: jest.fn(async () => page([TOPIC_TYPE])),
+    listAllEntities: jest.fn(async () => []),
+    updateEntity,
+  } as CollectionClient & { updateEntity: typeof updateEntity };
+}
+
+function drawer(client: CollectionClient, record: EntityRecord, extra: Partial<React.ComponentProps<typeof ReviewDrawer>> = {}) {
+  return (
+    <ReviewDrawer
+      client={client}
+      type={TOPIC_TYPE}
+      records={[record]}
+      record={record}
+      onClose={() => {}}
+      onNavigate={() => {}}
+      {...extra}
+    />
+  );
+}
+
+describe('ReviewDrawer — the precondition is the version of the blob it holds', () => {
+  it('a decision asserts the version the drawer opened at', async () => {
+    const client = stubClient();
+    render(drawer(client, topic(3)));
+    await userEvent.click(screen.getByRole('button', { name: /Reject/ }));
+    await waitFor(() => expect(client.updateEntity).toHaveBeenCalledTimes(1));
+    expect(client.updateEntity.mock.calls[0]![2]).toEqual({ expectedVersion: 3 });
+  });
+
+  it('a LIST REFETCH handing the drawer a newer record does NOT move the asserted version', async () => {
+    const client = stubClient();
+    const view = render(drawer(client, topic(3)));
+    // Another writer set the angle (v4); the parent's list refetched and re-renders
+    // the open drawer with the new row. The drawer still holds the v3 blob.
+    view.rerender(drawer(client, topic(4, { angle: 'colleague angle' })));
+    await userEvent.click(screen.getByRole('button', { name: /Reject/ }));
+    await waitFor(() => expect(client.updateEntity).toHaveBeenCalledTimes(1));
+    const [, input, opts] = client.updateEntity.mock.calls[0]!;
+    // The blob it sends is the v3 one, so the version it asserts must be 3 —
+    // which the server refuses with a 412 instead of erasing the angle.
+    expect(input.data?.angle).toBe('v3 angle');
+    expect(opts).toEqual({ expectedVersion: 3 });
+  });
+
+  it('a successful write moves the drawer onto the SAVED version', async () => {
+    const client = stubClient(4);
+    render(drawer(client, topic(3)));
+    await userEvent.click(screen.getByRole('button', { name: /Reject/ }));
+    await waitFor(() => expect(client.updateEntity).toHaveBeenCalledTimes(1));
+    await userEvent.click(screen.getByRole('button', { name: /Approve/ }));
+    await waitFor(() => expect(client.updateEntity).toHaveBeenCalledTimes(2));
+    expect(client.updateEntity.mock.calls[1]![2]).toEqual({ expectedVersion: 4 });
+  });
+
+  it('a FAILED write keeps the version it had', async () => {
+    const client = stubClient();
+    client.updateEntity.mockRejectedValueOnce(Object.assign(new Error('stale'), { status: 412 }));
+    render(drawer(client, topic(3)));
+    await userEvent.click(screen.getByRole('button', { name: /Reject/ }));
+    await waitFor(() => expect(client.updateEntity).toHaveBeenCalledTimes(1));
+    await userEvent.click(screen.getByRole('button', { name: /Approve/ }));
+    await waitFor(() => expect(client.updateEntity).toHaveBeenCalledTimes(2));
+    expect(client.updateEntity.mock.calls[1]![2]).toEqual({ expectedVersion: 3 });
+  });
+
+  it('a record with no version sends no precondition (an older tenant build)', async () => {
+    const client = stubClient();
+    render(drawer(client, topic(undefined)));
+    await userEvent.click(screen.getByRole('button', { name: /Reject/ }));
+    await waitFor(() => expect(client.updateEntity).toHaveBeenCalledTimes(1));
+    expect(client.updateEntity.mock.calls[0]![2]).toBeUndefined();
+  });
+
+  it('Edit fields → saved(record) reseeds the data AND the version from the saved record', async () => {
+    const client = stubClient(9);
+    let save!: (record?: EntityRecord) => void;
+    render(
+      drawer(client, topic(3), {
+        renderEditFields: ({ saved }) => {
+          save = saved;
+          return <p>editor</p>;
+        },
+      }),
+    );
+    await userEvent.click(screen.getByRole('button', { name: /Edit fields/ }));
+    React.act(() => save(topic(6, { title: 'Edited title', angle: 'edited angle' })));
+    expect(await screen.findByRole('heading', { name: 'Edited title' })).toBeInTheDocument();
+    await userEvent.click(screen.getByRole('button', { name: /Reject/ }));
+    await waitFor(() => expect(client.updateEntity).toHaveBeenCalledTimes(1));
+    const [, input, opts] = client.updateEntity.mock.calls[0]!;
+    expect(input.data?.angle).toBe('edited angle');
+    expect(opts).toEqual({ expectedVersion: 6 });
+  });
+});
+
+describe('InlineReviewActions — asserts the row it merged over', () => {
+  it('passes the row version', async () => {
+    const client = stubClient();
+    render(<InlineReviewActions client={client} type={TOPIC_TYPE} record={topic(5)} />);
+    await userEvent.click(screen.getAllByRole('button', { name: /Reject/ })[0]!);
+    await waitFor(() => expect(client.updateEntity).toHaveBeenCalledTimes(1));
+    expect(client.updateEntity.mock.calls[0]![2]).toEqual({ expectedVersion: 5 });
+  });
+});

package/src/components/collection/data.ts

@@ -42,7 +42,7 @@
  *
  * Pure + framework-free.
  */
-import type { EntityRecord } from './types';
+import type { EntityRecord, EntityWriteOptions } from './types';
 
 /** The spelling the shared client produces from a wire key. */
 export function toCamelKey(name: string): string {
@@ -143,3 +143,18 @@ export function declaredBlob(
   }
   return out;
 }
+
+/** An integer version, and only that. `0` IS a version (every record that
+ *  predates the trail reads 0), so `if (version)` would unguard the oldest rows. */
+export function isVersionNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value);
+}
+
+/**
+ * The write options for a blob merged over `record` (bd startsim-jkkn7.20): its
+ * OWN version, or nothing when it carries none. Never a newer version from
+ * elsewhere — that would make this blob look current.
+ */
+export function writeOptionsFor(record: { version?: unknown } | null | undefined): EntityWriteOptions | undefined {
+  return isVersionNumber(record?.version) ? { expectedVersion: record!.version as number } : undefined;
+}

package/src/components/collection/index.ts

@@ -32,6 +32,7 @@ export {
 } from './review';
 export type {
   CollectionClient,
+  EntityWriteOptions,
   EntityRecord,
   EntityTypeDef,
   AttributeDef,
@@ -52,7 +53,7 @@ export {
   SCOPE_FILTER,
   type ScopedCollectionClient,
 } from './scoped-client';
-export { readData, toCamelKey, writeData, declaredBlob, isLossyName } from './data';
+export { readData, toCamelKey, writeData, declaredBlob, isLossyName, isVersionNumber, writeOptionsFor } from './data';
 export {
   parseSources,
   normUrl,

package/src/components/collection/scoped-client.ts

@@ -150,6 +150,9 @@ export function withScope(
       return client.listAllEntities(type, next);
     },
 
-    updateEntity: (id, input) => client.updateEntity(id, input),
+    // The precondition passes straight through; a call without one stays a
+    // two-argument call, so wrapping an old client is not a behaviour change.
+    updateEntity: (id, input, options) =>
+      options === undefined ? client.updateEntity(id, input) : client.updateEntity(id, input, options),
   };
 }

package/src/components/collection/types.ts

@@ -33,6 +33,19 @@ export interface EntityRecord {
   name: string;
   data: Record<string, unknown>;
   createdAt: string;
+  /** The record's version (bd startsim-3c2wc). Absent on a tenant build that
+   *  predates the revision trail. */
+  version?: number;
+}
+
+/**
+ * What a write asserts (bd startsim-jkkn7.20). `expectedVersion` is the version
+ * of the blob the caller MERGED OVER — not the newest version anybody has seen.
+ * A consumer maps it to its precondition (If-Match / expected_version); absent
+ * means the caller holds no version and the write goes unguarded, as before.
+ */
+export interface EntityWriteOptions {
+  expectedVersion?: number;
 }
 
 export interface Paginated<T> {
@@ -101,5 +114,10 @@ export interface ListEntitiesOptions {
 export interface CollectionClient {
   listTypes(): Promise<Paginated<EntityTypeDef>>;
   listAllEntities(type: string, options?: ListEntitiesOptions): Promise<EntityRecord[]>;
-  updateEntity(id: number | string, input: { name?: string; data?: Record<string, unknown> }): Promise<EntityRecord>;
+  /** Resolves with the SAVED record, whose `version` the caller moves onto. */
+  updateEntity(
+    id: number | string,
+    input: { name?: string; data?: Record<string, unknown> },
+    options?: EntityWriteOptions,
+  ): Promise<EntityRecord>;
 }

package/src/components/history/FieldAttribution.tsx

@@ -0,0 +1,308 @@
+'use client';
+
+/**
+ * FieldAttribution — "edited by Jurga · 2h ago" beside a field, and a machine
+ * marked as a machine (bd startsim-vjhbw; read bd startsim-6sso4).
+ *
+ * The customer's ask was Google-Sheets-like: see who edited which piece and
+ * when. The history panel answers "what happened"; this answers the glance —
+ * on the field itself, who touched it last — and clicking it opens that field's
+ * own history (the panel narrowed with `?field=`).
+ *
+ * ── THREE READINGS THAT MUST NEVER BE CONFUSED ──────────────────────────────
+ *
+ * 1. AN ENTRY. Say who, through `ActorIdentity` — the same kind marker and the
+ *    same accessible title as every attributed surface, so a machine reads as a
+ *    machine here exactly as it does in the panel.
+ * 2. NO ENTRY. "Not edited since <the trail began>". Live rows PREDATE the trail
+ *    (`trail_starts.from_creation: false`), so an absent field means nobody has
+ *    edited it SINCE history started — never "never edited", which would be a
+ *    confident claim about a period nobody recorded.
+ * 3. HISTORY OFF (`recorded: false`, `fields: null`). We do not know, and say
+ *    so. Rendering that as (2) would tell a reader nobody edited a field when the
+ *    truth is that nobody was keeping track.
+ *
+ * Injected client, like the panel: `{ get: () => fetch(.../field-authors) }`.
+ */
+import type { ReactNode } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { formatDistanceToNow } from 'date-fns';
+import { Undo2 } from 'lucide-react';
+
+import { cn } from '../../lib/utils';
+import { ActorIdentity, type ActorKind, type ActorKindSource } from '../ActorIdentity';
+import type { FieldAuthor, FieldAuthorsClient, FieldAuthorsResponse } from './types';
+
+/* -------------------------------------------------------------------------- */
+/*  NORMALISATION — either spelling, failing closed on kind                   */
+/* -------------------------------------------------------------------------- */
+
+export interface NormalizedFieldAuthor {
+  version?: number;
+  at: string;
+  actorSub: string;
+  actorLabel: string;
+  actorKind: ActorKind;
+  actorKindSource?: ActorKindSource;
+  source: string;
+  restoredFrom?: number;
+}
+
+export interface NormalizedFieldAuthors {
+  version?: number;
+  /** `false` = history is off for this type; NOTHING may be inferred. */
+  recorded: boolean;
+  historyEnabled?: boolean;
+  trailStarts: { version?: number; at: string; fromCreation: boolean } | null;
+  fields: Record<string, NormalizedFieldAuthor>;
+  name?: NormalizedFieldAuthor;
+  detail?: string;
+}
+
+function pick<T>(...values: Array<T | null | undefined>): T | undefined {
+  for (const v of values) if (v !== null && v !== undefined && v !== '') return v;
+  return undefined;
+}
+
+function normalizeAuthor(raw: FieldAuthor | null | undefined): NormalizedFieldAuthor | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const kind = pick(raw.actor_kind, raw.actorKind);
+  const source = pick(raw.actor_kind_source, raw.actorKindSource);
+  const restored = pick(raw.restored_from, raw.restoredFrom);
+  return {
+    ...(typeof raw.version === 'number' ? { version: raw.version } : {}),
+    at: String(pick(raw.at) ?? ''),
+    actorSub: String(pick(raw.actor_sub, raw.actorSub) ?? ''),
+    actorLabel: String(pick(raw.actor_label, raw.actorLabel) ?? ''),
+    // FAIL CLOSED: anything outside the vocabulary is `unknown`, never `person`.
+    actorKind: kind === 'person' || kind === 'machine' ? kind : 'unknown',
+    ...(source === 'claim' || source === 'inferred' ? { actorKindSource: source } : {}),
+    source: String(pick(raw.source) ?? ''),
+    ...(typeof restored === 'number' ? { restoredFrom: restored } : {}),
+  };
+}
+
+export function normalizeFieldAuthors(raw: FieldAuthorsResponse): NormalizedFieldAuthors {
+  const r = (raw ?? {}) as FieldAuthorsResponse;
+  const ts = pick(r.trail_starts, r.trailStarts);
+  const fields: Record<string, NormalizedFieldAuthor> = {};
+  for (const [key, value] of Object.entries(r.fields ?? {})) {
+    const a = normalizeAuthor(value);
+    if (a) fields[key] = a;
+  }
+  const name = normalizeAuthor(r.name);
+  // `recorded` absent on an older build: infer from `fields`, never assume.
+  const recorded = typeof r.recorded === 'boolean' ? r.recorded : r.fields != null;
+  return {
+    ...(typeof r.version === 'number' ? { version: r.version } : {}),
+    recorded,
+    ...(typeof r.history?.enabled === 'boolean' ? { historyEnabled: r.history.enabled } : {}),
+    trailStarts: ts
+      ? {
+          ...(typeof ts.version === 'number' ? { version: ts.version } : {}),
+          at: String(ts.at ?? ''),
+          fromCreation: (ts.from_creation ?? ts.fromCreation) === true,
+        }
+      : null,
+    fields: recorded ? fields : {},
+    ...(recorded && name ? { name } : {}),
+    ...(typeof r.detail === 'string' ? { detail: r.detail } : {}),
+  };
+}
+
+function isNormalized(v: unknown): v is NormalizedFieldAuthors {
+  return !!v && typeof v === 'object' && 'trailStarts' in v && 'recorded' in v && !('trail_starts' in v);
+}
+
+function asNormalized(
+  authors: FieldAuthorsResponse | NormalizedFieldAuthors | undefined | null,
+): NormalizedFieldAuthors | undefined {
+  if (!authors) return undefined;
+  return isNormalized(authors) ? authors : normalizeFieldAuthors(authors as FieldAuthorsResponse);
+}
+
+/** The latest author of one field, or undefined (not edited since the trail
+ *  began, OR history off — check `recorded` before reading meaning into it). */
+export function fieldAuthorOf(
+  authors: FieldAuthorsResponse | NormalizedFieldAuthors | undefined,
+  field: string,
+): NormalizedFieldAuthor | undefined {
+  const n = asNormalized(authors);
+  if (!n || !n.recorded) return undefined;
+  return Object.prototype.hasOwnProperty.call(n.fields, field) ? n.fields[field] : undefined;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  THE HOOK                                                                  */
+/* -------------------------------------------------------------------------- */
+
+export interface UseFieldAuthorsOptions {
+  client: FieldAuthorsClient;
+  /** Put the record's VERSION in this key, so a save re-reads the authors. */
+  queryKey: readonly unknown[];
+  enabled?: boolean;
+}
+
+export function useFieldAuthors({ client, queryKey, enabled = true }: UseFieldAuthorsOptions) {
+  return useQuery({
+    queryKey: [...queryKey],
+    queryFn: async () => normalizeFieldAuthors(await client.get()),
+    enabled,
+  });
+}
+
+/* -------------------------------------------------------------------------- */
+/*  THE COMPONENTS                                                            */
+/* -------------------------------------------------------------------------- */
+
+function ago(iso: string): string {
+  const d = new Date(iso);
+  if (!iso || Number.isNaN(d.getTime())) return '';
+  try {
+    return formatDistanceToNow(d, { addSuffix: true });
+  } catch {
+    return '';
+  }
+}
+
+function day(iso: string): string {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime())
+    ? ''
+    : d.toLocaleDateString(undefined, { month: 'short', day: 'numeric', year: 'numeric' });
+}
+
+export interface FieldAttributionProps {
+  /** The field-authors read, raw or normalised. Undefined while loading. */
+  authors: FieldAuthorsResponse | NormalizedFieldAuthors | undefined | null;
+  /** The data key, exactly as declared. */
+  field: string;
+  /** Read the NAME column's author instead of `fields[field]`. */
+  nameColumn?: boolean;
+  /** Open this field's history (the panel narrowed with `?field=`). Omit and the
+   *  attribution is plain text rather than a button. */
+  onOpenHistory?: (field: string) => void;
+  /** A URL for "their recent edits" — e.g. `/activity?actor=<sub>`. */
+  actorHref?: (actorSub: string) => string;
+  /** Rendered as the link when `actorHref` is set. */
+  renderLink?: (props: { href: string; className: string; children: ReactNode }) => ReactNode;
+  fieldLabel?: (field: string) => string;
+  className?: string;
+}
+
+const ROOT = 'inline-flex flex-wrap items-center gap-x-1 text-xs text-muted-foreground';
+
+export function FieldAttribution({
+  authors,
+  field,
+  nameColumn = false,
+  onOpenHistory,
+  actorHref,
+  renderLink,
+  fieldLabel = (f) => f,
+  className,
+}: FieldAttributionProps) {
+  const n = asNormalized(authors);
+  if (!n) return null;
+  const testId = `field-attribution-${field}`;
+  const label = fieldLabel(field);
+
+  const wrap = (body: ReactNode, title?: string) =>
+    onOpenHistory ? (
+      <button
+        type="button"
+        data-testid={testId}
+        aria-label={`History of ${label}`}
+        title={title}
+        onClick={() => onOpenHistory(field)}
+        className={cn(ROOT, 'rounded px-0.5 hover:bg-accent hover:text-foreground', className)}
+      >
+        {body}
+      </button>
+    ) : (
+      <span data-testid={testId} title={title} className={cn(ROOT, className)}>
+        {body}
+      </span>
+    );
+
+  if (!n.recorded) {
+    return wrap(
+      <span>Edit history not recorded</span>,
+      n.detail ?? 'History is switched off for this kind of record, so who edits it is not recorded.',
+    );
+  }
+
+  const author = nameColumn ? n.name : n.fields[field];
+  if (!author) {
+    const ts = n.trailStarts;
+    const since = !ts
+      ? 'No edits recorded'
+      : ts.fromCreation
+        ? 'Not edited since it was created'
+        : `Not edited since ${day(ts.at) || `v${ts.version ?? ''}`}`;
+    return wrap(
+      <span>{since}</span>,
+      ts && !ts.fromCreation
+        ? 'History began after this record was created; edits before then were not recorded.'
+        : undefined,
+    );
+  }
+
+  const when = ago(author.at);
+  const restored = author.restoredFrom !== undefined;
+  const link =
+    actorHref && author.actorSub
+      ? (() => {
+          const href = actorHref(author.actorSub);
+          const className = 'underline underline-offset-2 hover:text-foreground';
+          const children = 'their recent edits';
+          return renderLink ? (
+            renderLink({ href, className, children })
+          ) : (
+            <a href={href} className={className}>
+              {children}
+            </a>
+          );
+        })()
+      : null;
+
+  return (
+    <span className="inline-flex flex-wrap items-center gap-x-1.5">
+      {wrap(
+        <>
+          {restored && <Undo2 className="h-3 w-3" aria-hidden="true" />}
+          <span>{restored ? 'Restored by' : 'Edited by'}</span>
+          <ActorIdentity
+            actor={{ email: author.actorLabel }}
+            showInitials={false}
+            kind={author.actorKind}
+            {...(author.actorKindSource ? { kindSource: author.actorKindSource } : {})}
+            className="inline-flex flex-wrap items-center gap-x-1 text-foreground"
+          />
+          {restored && <span>from v{author.restoredFrom}</span>}
+          {when && <span aria-hidden="true">·</span>}
+          {when && <time dateTime={author.at}>{when}</time>}
+        </>,
+      )}
+      {link && <span className="text-xs text-muted-foreground">{link}</span>}
+    </span>
+  );
+}
+
+/** The server's sentence when history is off — said ONCE for a form, not per
+ *  field. Renders nothing when history is recorded. */
+export function FieldAuthorsNotice({
+  authors,
+  className = 'text-xs text-muted-foreground',
+}: {
+  authors: FieldAuthorsResponse | NormalizedFieldAuthors | undefined | null;
+  className?: string;
+}) {
+  const n = asNormalized(authors);
+  if (!n || n.recorded) return null;
+  return (
+    <p data-testid="field-authors-notice" className={className}>
+      {n.detail ?? 'History is switched off for this kind of record, so who edits each field is not recorded.'}
+    </p>
+  );
+}