@startsimpli/ui 0.4.111 → 0.4.113

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.111",
+  "version": "0.4.113",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -47,9 +47,9 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/api": "^0.5.58",
     "@startsimpli/auth": "^0.4.35",
-    "@startsimpli/i18n": "^0.1.3"
+    "@startsimpli/i18n": "^0.1.3",
+    "@startsimpli/api": "^0.5.58"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/components/collection/DraftReviewWorkspace.tsx

@@ -18,6 +18,7 @@ import { notify } from '../toast/use-notify';
 import { MarkdownRenderer } from '../blog/MarkdownRenderer';
 import type { CollectionClient, EntityRecord } from './types';
 import { readData, toCamelKey } from './data';
+import { scopeKey } from './scoped-client';
 import {
   groupDrafts,
   parseSources,
@@ -58,10 +59,14 @@ export interface DraftReviewWorkspaceProps {
 
 export function DraftReviewWorkspace({ client }: DraftReviewWorkspaceProps) {
   const qc = useQueryClient();
+  // The injected client's bound, in the cache key — see the same note on
+  // TopicReviewWorkspace: a scope change that does not change the key serves the
+  // previous client's drafts under the new client's name.
+  const scope = scopeKey(client);
   const typesQ = useQuery({ queryKey: ['schema-types'], queryFn: () => client.listTypes() });
   const draftType = typesQ.data?.results.find((t) => t.key === 'draft');
   const recordsQ = useQuery({
-    queryKey: ['entities', 'draft', 'all'],
+    queryKey: ['entities', 'draft', 'all', scope],
     queryFn: () => client.listAllEntities('draft'),
     enabled: !!draftType,
   });
@@ -70,8 +75,12 @@ export function DraftReviewWorkspace({ client }: DraftReviewWorkspaceProps) {
   // A story whose topic was rejected shouldn't keep cluttering the review — its
   // drafts collapse into the "Rejected" section, mirroring the topic list
   // (startsim-ay9l follow-up). draft.topic_ref is the topic's entity id.
+  // SCOPED, unlike the source registry below: a topic is a client's own work,
+  // not shared corpus, and this read decides which of THIS board's drafts are
+  // collapsed as rejected. Reading it unscoped would let another client's topic
+  // ids reach the decision.
   const topicsQ = useQuery({
-    queryKey: ['entities', 'topic', 'all'],
+    queryKey: ['entities', 'topic', 'all', scope],
     queryFn: () => client.listAllEntities('topic'),
     enabled: !!draftType,
   });
@@ -83,9 +92,11 @@ export function DraftReviewWorkspace({ client }: DraftReviewWorkspaceProps) {
     return s;
   }, [topicsQ.data]);
 
+  // UNSCOPED — the source registry is shared across scopes (epic
+  // startsim-ux39t) and this is a domain→tier lookup, not the client's work.
   const sourcesQ = useQuery({
     queryKey: ['entities', 'source', 'all'],
-    queryFn: () => client.listAllEntities('source'),
+    queryFn: () => client.listAllEntities('source', { scoped: false }),
     enabled: !!draftType,
   });
   const tierByDomain = useMemo(() => {
@@ -112,6 +123,9 @@ export function DraftReviewWorkspace({ client }: DraftReviewWorkspaceProps) {
   const [showRejected, setShowRejected] = useState(false);
 
   async function writeEntity(record: EntityRecord, changes: Record<string, unknown>) {
+    // The FULL blob, spread from the record: PATCH REPLACES `data`, so an
+    // attribute this board never touches — the scope path included — has to be
+    // sent back to survive. A write is never a move between scopes.
     const data: Record<string, unknown> = { ...record.data };
     for (const [k, v] of Object.entries(changes)) data[toCamelKey(k)] = v;
     return client.updateEntity(record.id, { data });
@@ -153,6 +167,18 @@ export function DraftReviewWorkspace({ client }: DraftReviewWorkspaceProps) {
   if (!draftType) {
     return <p className="text-sm text-gray-500">No “draft” type is defined for this app.</p>;
   }
+  // See TopicReviewWorkspace: a scoped list can be refused (a type with no
+  // declared scope path is a 400), and an unreported refusal renders as an empty
+  // board rather than as a problem.
+  if (recordsQ.isError) {
+    return (
+      <p className="rounded-lg border border-rose-200 bg-rose-50 p-4 text-sm text-rose-700">
+        Could not load drafts
+        {scope === 'all' ? '' : ` for ${scope}`}:{' '}
+        {recordsQ.error instanceof Error ? recordsQ.error.message : 'the request was refused.'}
+      </p>
+    );
+  }
 
   const pickedCount = activeGroups.filter((g) => g.chosen).length;
   const readyCount = activeGroups.filter((g) => g.ready).length;

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/TopicReviewWorkspace.tsx

@@ -18,6 +18,7 @@ import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '.
 import { notify } from '../toast/use-notify';
 import type { CollectionClient, EntityRecord, EntityTypeDef } from './types';
 import { readData, toCamelKey } from './data';
+import { scopeKey } from './scoped-client';
 
 const STATUSES = ['suggested', 'ready', 'rejected', 'written'] as const;
 const VERDICTS = [
@@ -52,18 +53,26 @@ export interface TopicReviewWorkspaceProps {
 
 export function TopicReviewWorkspace({ client, markets = [], renderDetail }: TopicReviewWorkspaceProps) {
   const qc = useQueryClient();
+  // The bound the injected client is carrying. IT IS PART OF THE CACHE KEY, and
+  // that is not bookkeeping: without it a scope change reuses the previous
+  // scope's rows — the request would carry the new scope and the board would
+  // still show the old client's topics, which is worse than not scoping at all.
+  const scope = scopeKey(client);
   const typesQ = useQuery({ queryKey: ['schema-types'], queryFn: () => client.listTypes() });
   const topicType = typesQ.data?.results.find((t) => t.key === 'topic');
   const recordsQ = useQuery({
-    queryKey: ['entities', 'topic', 'all'],
+    queryKey: ['entities', 'topic', 'all', scope],
     queryFn: () => client.listAllEntities('topic'),
     enabled: !!topicType,
   });
   const records = recordsQ.data ?? [];
 
+  // The source registry is SHARED across scopes (epic startsim-ux39t) and this
+  // is a tier lookup, not a list of the client's work — so it is read unscoped
+  // and keyed without the scope, one fetch for every bound rather than one each.
   const sourcesQ = useQuery({
     queryKey: ['entities', 'source', 'all'],
-    queryFn: () => client.listAllEntities('source'),
+    queryFn: () => client.listAllEntities('source', { scoped: false }),
     enabled: !!topicType,
   });
   const tierByDomain = useMemo(() => {
@@ -98,6 +107,9 @@ export function TopicReviewWorkspace({ client, markets = [], renderDetail }: Top
     const data: Record<string, unknown> = { ...record.data };
     for (const [k, v] of Object.entries(changes)) data[toCamelKey(k)] = v;
     try {
+      // The FULL blob, spread from the record — so an attribute this workspace
+      // never touches (the scope path among them) survives a PATCH that
+      // REPLACES the blob rather than merging it. A write is never a move.
       await client.updateEntity(record.id, { data });
       await qc.invalidateQueries({ queryKey: ['entities', 'topic'] });
     } catch (err) {
@@ -111,6 +123,20 @@ export function TopicReviewWorkspace({ client, markets = [], renderDetail }: Top
   if (!topicType) {
     return <p className="text-sm text-gray-500">No “topic” type is defined for this app.</p>;
   }
+  // A SCOPED LIST CAN NOW FAIL, so it has to be able to say so. `?scope=` on a
+  // type that declares no scope path is a 400 (bd startsim-mj609) — and an
+  // unreported error renders as an empty board, which reads as "this client has
+  // no topics". Silently empty under an active bound is the same class of lie
+  // as silently widening.
+  if (recordsQ.isError) {
+    return (
+      <p className="rounded-lg border border-rose-200 bg-rose-50 p-4 text-sm text-rose-700">
+        Could not load topics
+        {scope === 'all' ? '' : ` for ${scope}`}:{' '}
+        {recordsQ.error instanceof Error ? recordsQ.error.message : 'the request was refused.'}
+      </p>
+    );
+  }
 
   return (
     <div className="space-y-6">

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