@startsimpli/ui 0.4.112 → 0.4.113

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.112",
+  "version": "0.4.113",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -123,8 +123,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/i18n": "0.1.3",
-    "@startsimpli/realtime": "0.0.2"
+    "@startsimpli/realtime": "0.0.2",
+    "@startsimpli/i18n": "0.1.3"
   },
   "keywords": [
     "ui",

package/src/components/collection/ReviewDrawer.tsx

@@ -79,7 +79,15 @@ export interface ReviewDrawerProps {
     /** Refetch the parent + return to review mode. */
     saved: () => void;
   }) => ReactNode;
-  /** App-specific extra content under the record (e.g. a topic's drafts). Optional. */
+  /**
+   * App-specific extra content under the record (e.g. a topic's drafts).
+   * Optional.
+   *
+   * Handed the record AS DECIDED — the drawer's optimistic `data`, not the
+   * `record` prop (bd startsim-t1t1k). An extra slot is where a consumer puts
+   * the action a decision UNLOCKS, so it is the one place that most needs to
+   * see the decision that was just made.
+   */
   renderExtra?: (record: EntityRecord, type: EntityTypeDef) => ReactNode;
 }
 
@@ -119,6 +127,18 @@ function ReviewDrawerInner({
   const title = fieldStr(data, cfg.titleAttr) || record.name || `#${record.id}`;
   const summary = fieldStr(data, cfg.summaryAttr);
   const rank = fieldStr(data, cfg.rankAttr);
+  /**
+   * The record AS DECIDED — the `record` prop carrying this drawer's own
+   * optimistic `data` (bd startsim-t1t1k).
+   *
+   * Everything else here already renders from `data`; `renderExtra` was the one
+   * slot still reading the untouched prop, so a consumer affordance gated on
+   * status (OGMC's "Generate drafts", legal only once the topic is approved)
+   * kept reading the PRE-decision status and kept refusing. The parent's
+   * refetch cannot fix that on its own — it invalidates a list, while the
+   * drawer holds a record object the parent chose before the decision existed.
+   */
+  const decided = useMemo(() => ({ ...record, data }), [record, data]);
 
   /** Merge changes into the (camelCased) blob and PATCH; the backend REPLACES data. */
   async function patch(changes: Record<string, unknown>, key: string, advance = false) {
@@ -304,7 +324,9 @@ function ReviewDrawerInner({
 
               <ReviewSources data={data} sourceAttrs={cfg.sourceAttrs} tierByHost={sourceTierByHost} />
 
-              {renderExtra ? <div className="mt-6 border-t border-border pt-4">{renderExtra(record, type)}</div> : null}
+              {renderExtra ? (
+                <div className="mt-6 border-t border-border pt-4">{renderExtra(decided, type)}</div>
+              ) : null}
             </div>
 
             <footer className="space-y-3 border-t border-border px-4 py-3">

package/src/components/collection/__tests__/approve-unlocks.test.tsx

@@ -0,0 +1,169 @@
+/**
+ * Approving a record must leave the reviewer standing on the record they
+ * approved, holding whatever the approval unlocked (bd startsim-t1t1k).
+ *
+ * The report, verbatim: "To create a draft, you first have to approve the
+ * Topic, then click out of the window, refresh the page, filter the 'Ready'
+ * topics, find the same topic, click approve again and then it generates
+ * drafts." Six steps to reach a button that should have been one — and the
+ * second approve writes nothing new, so what the reload actually bought was a
+ * FRESH RECORD.
+ *
+ * Two independent mechanisms in this component produced that, and both are
+ * pinned below:
+ *
+ *   1. THE EXTRA SLOT SAW A STALE RECORD. Every other thing the drawer renders
+ *      — heading, meta chips, the status Select, which decision reads as active
+ *      — is derived from the optimistic `data` a decision writes. `renderExtra`
+ *      alone was handed the untouched `record` prop, so the consumer's
+ *      follow-on affordance (OGMC's "Generate drafts", gated on
+ *      status === the approve status) kept reading the PRE-approval status and
+ *      kept refusing. Exactly the state a page reload cures.
+ *   2. THE DRAWER MOVED ON. Approve auto-advances, so even once the gate opened
+ *      it opened on a record that was no longer on screen.
+ *
+ * Neither test asserts a colour or a class: they assert that the thing the
+ * approval unlocked is reachable, for the record that was approved.
+ */
+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 { readData } from '../data';
+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: {} },
+  ],
+};
+
+function topic(id: number, title: string): EntityRecord {
+  return {
+    id,
+    entityType: 'topic',
+    externalId: null,
+    name: title,
+    data: { title, status: 'suggested' },
+    createdAt: '2026-09-01T00:00:00Z',
+  };
+}
+
+function page<T>(results: T[]): Paginated<T> {
+  return { count: results.length, next: null, previous: null, results };
+}
+
+function stubClient(): CollectionClient & { updateEntity: jest.Mock } {
+  const updateEntity = jest.fn(async (id: number | string, input: { data?: Record<string, unknown> }) => ({
+    ...topic(Number(id), 'x'),
+    data: input.data ?? {},
+  }));
+  return {
+    listTypes: jest.fn(async () => page([TOPIC_TYPE])),
+    listAllEntities: jest.fn(async () => []),
+    updateEntity,
+  } as CollectionClient & { updateEntity: jest.Mock };
+}
+
+/**
+ * The consumer's follow-on affordance, standing in for OGMC's "Generate
+ * drafts": legal only once the record has reached the approve status, and it
+ * says WHY when it is not — a disabled control the reader cannot explain is the
+ * same defect in another shape.
+ */
+function GenerateStub(record: EntityRecord) {
+  const approved = String(readData(record.data, 'status') ?? '') === 'ready';
+  return approved ? (
+    <button type="button">Generate drafts</button>
+  ) : (
+    <span>Approve this topic to generate drafts.</span>
+  );
+}
+
+function renderDrawer(overrides: Partial<React.ComponentProps<typeof ReviewDrawer>> = {}) {
+  const client = stubClient();
+  const onNavigate = jest.fn();
+  const onSaved = jest.fn();
+  const first = topic(1, 'Desalination in Riyadh');
+  const utils = render(
+    <ReviewDrawer
+      client={client}
+      type={TOPIC_TYPE}
+      records={[first, topic(2, 'A different topic entirely')]}
+      record={first}
+      onClose={jest.fn()}
+      onNavigate={onNavigate}
+      onSaved={onSaved}
+      renderExtra={GenerateStub}
+      {...overrides}
+    />,
+  );
+  return { ...utils, client, onNavigate, onSaved, first };
+}
+
+describe('approving a topic unlocks its follow-on action in place', () => {
+  it('hands renderExtra the record AS DECIDED, not the stale prop', async () => {
+    const user = userEvent.setup();
+    const { client } = renderDrawer({ config: { holdAfter: ['approve'] } });
+
+    // Before: the follow-on is refused, in words.
+    expect(screen.getByText('Approve this topic to generate drafts.')).toBeInTheDocument();
+
+    await user.click(screen.getByRole('button', { name: /Approve/ }));
+
+    // The write itself carries the coherent pair the pipeline reads.
+    await waitFor(() => expect(client.updateEntity).toHaveBeenCalled());
+    expect(client.updateEntity.mock.calls[0][1].data).toMatchObject({
+      status: 'ready',
+      teamVerdict: 'good',
+    });
+
+    // And the drawer's extra slot reflects it WITHOUT a refetch, a reopen, or a
+    // second approve — the parent has not sent a new `record` prop at all.
+    expect(await screen.findByRole('button', { name: 'Generate drafts' })).toBeInTheDocument();
+    expect(screen.queryByText('Approve this topic to generate drafts.')).not.toBeInTheDocument();
+  });
+
+  it('stays on the approved record when the consumer holds that decision', async () => {
+    const user = userEvent.setup();
+    const { onNavigate, onSaved } = renderDrawer({ config: { holdAfter: ['approve'] } });
+
+    await user.click(screen.getByRole('button', { name: /Approve/ }));
+
+    await waitFor(() => expect(onSaved).toHaveBeenCalled());
+    expect(onNavigate).not.toHaveBeenCalled();
+    // The heading is still the topic that was decided, not the next one.
+    expect(screen.getByRole('heading', { name: 'Desalination in Riyadh' })).toBeInTheDocument();
+  });
+
+  it('still advances after a decision the consumer did NOT hold', async () => {
+    const user = userEvent.setup();
+    const { onNavigate } = renderDrawer({ config: { holdAfter: ['approve'] } });
+
+    await user.click(screen.getByRole('button', { name: /Reject/ }));
+
+    await waitFor(() => expect(onNavigate).toHaveBeenCalled());
+    expect(onNavigate.mock.calls[0][0].id).toBe(2);
+  });
+
+  it('advances after Approve for a consumer that holds nothing (unchanged default)', async () => {
+    const user = userEvent.setup();
+    const { onNavigate } = renderDrawer();
+
+    await user.click(screen.getByRole('button', { name: /Approve/ }));
+
+    await waitFor(() => expect(onNavigate).toHaveBeenCalled());
+    expect(onNavigate.mock.calls[0][0].id).toBe(2);
+  });
+});

package/src/components/collection/__tests__/review.test.ts

@@ -284,3 +284,62 @@ describe('decision labels are the consumer’s to name', () => {
     );
   });
 });
+
+/**
+ * A decision that UNLOCKS a next action on the same record must not scroll that
+ * record off the screen (bd startsim-t1t1k).
+ *
+ * On OGMC, approving a topic is what makes "Generate drafts" legal for it. The
+ * drawer then auto-advanced to the next topic, so the control the approval had
+ * just unlocked appeared for a record nobody was looking at — and the reviewer's
+ * six-step workaround (close, reload, filter to Ready, find it again, approve a
+ * second time) is what she reported. Rejecting has no such follow-on, so it
+ * still advances: this is opt-in, per decision key, and every type that does not
+ * ask for it is byte-identical.
+ */
+describe('holdAfter — decisions that stay on the record', () => {
+  const type = {
+    id: 't',
+    key: 'topic',
+    label: 'Topic',
+    attributes: [
+      {
+        id: 'a',
+        name: 'status',
+        dataType: 'enum' as const,
+        required: false,
+        config: { choices: ['suggested', 'ready', 'written', 'rejected'] },
+      },
+    ],
+  };
+
+  it('advances after every decision when nothing is held (today’s behaviour)', () => {
+    const byKey = Object.fromEntries(
+      reviewDecisions(resolveReviewConfig(type)).map((d) => [d.key, d.advance]),
+    );
+    expect(byKey.approve).toBe(true);
+    expect(byKey.reject).toBe(true);
+    // "Needs work" already holds — it is meant to be revisited.
+    expect(byKey.needs_work).toBe(false);
+  });
+
+  it('holds the named decision and leaves the others advancing', () => {
+    const cfg = resolveReviewConfig(type, { holdAfter: ['approve'] });
+    const byKey = Object.fromEntries(reviewDecisions(cfg).map((d) => [d.key, d.advance]));
+    expect(byKey.approve).toBe(false);
+    expect(byKey.reject).toBe(true);
+  });
+
+  it('changes ONLY whether the queue moves on — never what gets written', () => {
+    const plain = reviewDecisions(resolveReviewConfig(type));
+    const held = reviewDecisions(resolveReviewConfig(type, { holdAfter: ['approve', 'reject'] }));
+    expect(held.map((d) => [d.key, d.label, d.status, d.verdict, d.tone, d.shortcut])).toEqual(
+      plain.map((d) => [d.key, d.label, d.status, d.verdict, d.tone, d.shortcut]),
+    );
+  });
+
+  it('resolves to an empty hold list when the consumer supplies none', () => {
+    expect(resolveReviewConfig(type).holdAfter).toEqual([]);
+    expect(resolveReviewConfig(type, { holdAfter: ['approve'] }).holdAfter).toEqual(['approve']);
+  });
+});

package/src/components/collection/review.ts

@@ -186,6 +186,24 @@ export interface ReviewConfig {
    * unchanged, so nothing that does not pass this renders differently.
    */
   decisionLabels?: Record<string, string>;
+  /**
+   * Decision keys after which the drawer STAYS on the record instead of
+   * auto-advancing to the next one. Default: none (every decision behaves
+   * exactly as it does today).
+   *
+   * WHY THIS EXISTS (bd startsim-t1t1k). Auto-advance is right for pure triage
+   * — decide, move on — but wrong for a decision that UNLOCKS a next action on
+   * the same record. On OGMC, approving a topic is precisely what makes
+   * "Generate drafts" legal for it; advancing scrolled the newly-legal control
+   * off the screen, and the reviewer's workaround was to close the drawer,
+   * reload, filter to Ready, find the topic again and approve it a second time.
+   * Six steps, and the second approve wrote nothing — what the reload bought
+   * was a fresh record.
+   *
+   * Only the consumer knows whether one of its decisions has a follow-on, so
+   * this is theirs to declare. Rejecting has none, so it keeps advancing.
+   */
+  holdAfter?: string[];
 }
 
 export interface ResolvedReview {
@@ -203,6 +221,7 @@ export interface ResolvedReview {
   sourceAttrs: string[];
   omitNeedsWork: boolean;
   decisionLabels: Record<string, string>;
+  holdAfter: string[];
 }
 
 const DEFAULT_SOURCE_ATTRS = ['source_1', 'source_2', 'source_3', 'sources'];
@@ -235,6 +254,7 @@ export function resolveReviewConfig(
     sourceAttrs: (config.sourceAttrs ?? DEFAULT_SOURCE_ATTRS).filter((a) => declared.has(a)),
     omitNeedsWork: config.omitNeedsWork ?? false,
     decisionLabels: config.decisionLabels ?? {},
+    holdAfter: config.holdAfter ?? [],
   };
 }
 
@@ -284,10 +304,15 @@ export interface ReviewDecision {
  * A decision only appears when its status target resolves (or, for Needs work,
  * when there's an entry stage or an edit verdict) — so a two-state or non-workflow
  * enum simply shows fewer buttons instead of guessing.
+ *
+ * `holdAfter` overrides the advance flag per decision key (bd startsim-t1t1k) —
+ * it changes only whether the queue moves on, never what a decision writes.
  */
 export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
   const verdictOf = (tone: VerdictTone): string | null =>
     r.verdicts.find((v) => v.tone === tone)?.value ?? null;
+  const held = new Set(r.holdAfter ?? []);
+  const advances = (key: string) => !held.has(key);
   const entry = r.statusChoices[0] ?? null;
   const out: ReviewDecision[] = [];
 
@@ -298,7 +323,7 @@ export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
       status: r.transitions.approve,
       verdict: verdictOf('good'),
       tone: 'good',
-      advance: true,
+      advance: advances('approve'),
       shortcut: 'a',
       promptNote: false,
     });
@@ -325,7 +350,7 @@ export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
       status: r.transitions.reject,
       verdict: verdictOf('bad'),
       tone: 'bad',
-      advance: true,
+      advance: advances('reject'),
       shortcut: 'x',
       promptNote: false,
     });