@startsimpli/ui 0.4.60 → 0.4.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.60",
+  "version": "0.4.62",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/components/collection/ReviewDrawer.tsx

@@ -0,0 +1,495 @@
+'use client';
+
+/**
+ * Review-first record drawer — the fast triage surface for a status-carrying
+ * entity type (bd startsim-768w.18.14 / .15).
+ *
+ * Opens READ-OPTIMISED, not as an edit form: the record's title / summary /
+ * sources up top, then a sticky bar with ONE decision — Approve / Needs work /
+ * Reject. Each decision writes BOTH underlying fields coherently (status = the
+ * pipeline gate + team_verdict = the re-rank signal) in a single save, so there's
+ * no separate "verdict" row duplicating Approve/Reject. Approve/Reject advance to
+ * the next record; the current state shows as a badge that doubles as the rare
+ * manual override (mark written, un-reject). ↑/↓ (or j/k) walk the queue; a / w /
+ * x / e are bare-letter shortcuts (guarded while typing). Deep field-editing stays
+ * behind "Edit fields" (the app injects its form via renderEditFields).
+ *
+ * Generic + client-injected: the consumer passes a CollectionClient, the ordered
+ * queue (prev/next), and optional ReviewConfig / render-props. Defaults match the
+ * OGMC content schema but everything is a prop — nothing here is tenant-specific.
+ */
+import { useEffect, useMemo, useState, type ReactNode } from 'react';
+import {
+  ChevronLeft,
+  ChevronRight,
+  Check,
+  X,
+  PencilLine,
+  ExternalLink,
+  ShieldCheck,
+  MessageSquarePlus,
+} from 'lucide-react';
+
+import { Button } from '../ui/button';
+import { Textarea } from '../ui/textarea';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '../ui/select';
+import { notify } from '../toast/use-notify';
+import { cn } from '../../lib/utils';
+import type { CollectionClient, EntityRecord, EntityTypeDef } from './types';
+import { readData, toCamelKey } from './data';
+import { parseSources } from './drafts';
+import {
+  resolveReviewConfig,
+  reviewDecisions,
+  shouldIgnoreShortcut,
+  fieldStr,
+  reviewHostOf,
+  type ReviewConfig,
+  type ReviewDecision,
+} from './review';
+
+export interface ReviewDrawerProps {
+  client: CollectionClient;
+  type: EntityTypeDef;
+  /** The ordered queue the drawer walks with prev/next (the current list/page). */
+  records: EntityRecord[];
+  /** The open record (null closes the drawer). */
+  record: EntityRecord | null;
+  onClose: () => void;
+  /** Move the open record to another (prev/next / auto-advance). */
+  onNavigate: (record: EntityRecord) => void;
+  /** Fired after any successful save so the parent can refetch/invalidate. */
+  onSaved?: () => void;
+  /** Field-map + transition overrides; defaults match the OGMC content schema. */
+  config?: ReviewConfig;
+  /** Map of source host → tier (1 = approved) for the source chips. Optional. */
+  sourceTierByHost?: Map<string, number>;
+  /** The app's deep field editor, shown behind "Edit fields". Optional. */
+  renderEditFields?: (ctx: {
+    record: EntityRecord;
+    type: EntityTypeDef;
+    /** Return to review mode without saving. */
+    back: () => void;
+    /** Refetch the parent + return to review mode. */
+    saved: () => void;
+  }) => ReactNode;
+  /** App-specific extra content under the record (e.g. a topic's drafts). Optional. */
+  renderExtra?: (record: EntityRecord, type: EntityTypeDef) => ReactNode;
+}
+
+export function ReviewDrawer(props: ReviewDrawerProps) {
+  if (!props.record) return null;
+  return <ReviewDrawerInner key={props.record.id} {...props} record={props.record} />;
+}
+
+function ReviewDrawerInner({
+  client,
+  type,
+  records,
+  record,
+  onClose,
+  onNavigate,
+  onSaved,
+  config,
+  sourceTierByHost,
+  renderEditFields,
+  renderExtra,
+}: ReviewDrawerProps & { record: EntityRecord }) {
+  const cfg = useMemo(() => resolveReviewConfig(type, config), [type, config]);
+  const decisions = useMemo(() => reviewDecisions(cfg), [cfg]);
+  const [mode, setMode] = useState<'review' | 'edit'>('review');
+  // Local optimistic copy so a click reflects instantly (the parent also refetches).
+  const [data, setData] = useState<Record<string, unknown>>(() => ({ ...record.data }));
+  const [busy, setBusy] = useState<string | null>(null);
+  const [noteOpen, setNoteOpen] = useState(false);
+  const [note, setNote] = useState(() => fieldStr(record.data, cfg.noteAttr));
+
+  const index = records.findIndex((r) => String(r.id) === String(record.id));
+  const prev = index > 0 ? records[index - 1] : null;
+  const next = index >= 0 && index + 1 < records.length ? records[index + 1] : null;
+
+  const status = fieldStr(data, cfg.statusName);
+  const verdict = fieldStr(data, cfg.verdictAttr);
+  const title = fieldStr(data, cfg.titleAttr) || record.name || `#${record.id}`;
+  const summary = fieldStr(data, cfg.summaryAttr);
+  const rank = fieldStr(data, cfg.rankAttr);
+
+  /** Merge changes into the (camelCased) blob and PATCH; the backend REPLACES data. */
+  async function patch(changes: Record<string, unknown>, key: string, advance = false) {
+    const nextData: Record<string, unknown> = { ...data };
+    for (const [k, v] of Object.entries(changes)) {
+      const camel = toCamelKey(k);
+      if (v === '' || v == null) {
+        delete nextData[camel];
+        delete nextData[k];
+      } else {
+        nextData[camel] = v;
+        if (camel !== k) delete nextData[k];
+      }
+    }
+    setData(nextData); // optimistic
+    setBusy(key);
+    try {
+      await client.updateEntity(record.id, { data: nextData });
+      onSaved?.();
+      if (advance && next) onNavigate(next);
+    } catch (err) {
+      setData({ ...record.data }); // roll back
+      notify.error(err instanceof Error ? err.message : 'Could not save.');
+    } finally {
+      setBusy(null);
+    }
+  }
+
+  /** One decision → write status AND verdict together (the coherent pair). */
+  function applyDecision(d: ReviewDecision) {
+    const changes: Record<string, unknown> = {};
+    if (d.status) changes[cfg.statusName] = d.status;
+    if (d.verdict) changes[cfg.verdictAttr] = d.verdict;
+    if (d.promptNote) setNoteOpen(true);
+    void patch(changes, `decision:${d.key}`, d.advance);
+  }
+
+  /** Manual state override from the badge — status only, no verdict, no advance. */
+  function overrideStatus(value: string) {
+    if (value === status) return;
+    void patch({ [cfg.statusName]: value }, `status:${value}`, false);
+  }
+
+  async function saveNote() {
+    await patch({ [cfg.noteAttr]: note.trim() }, 'note');
+    setNoteOpen(false);
+  }
+
+  // Keyboard: walk the queue + one-key decide. Guarded so it never fires while typing.
+  useEffect(() => {
+    if (mode !== 'review') return;
+    function onKey(e: KeyboardEvent) {
+      if (shouldIgnoreShortcut(e)) return;
+      const d = decisions.find((x) => x.shortcut === e.key);
+      if (d) {
+        e.preventDefault();
+        applyDecision(d);
+        return;
+      }
+      switch (e.key) {
+        case 'j':
+        case 'ArrowDown':
+          if (next) { e.preventDefault(); onNavigate(next); }
+          break;
+        case 'k':
+        case 'ArrowUp':
+          if (prev) { e.preventDefault(); onNavigate(prev); }
+          break;
+        case 'e': e.preventDefault(); setMode('edit'); break;
+        case 'Escape': e.preventDefault(); onClose(); break;
+      }
+    }
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [mode, prev, next, decisions, data]);
+
+  const legend = [...decisions.map((d) => `${d.shortcut} ${d.label.toLowerCase()}`), 'e edit', 'j/k move'].join(' · ');
+
+  return (
+    <div className="fixed inset-0 z-50 flex justify-end" role="dialog" aria-modal="true">
+      <div className="absolute inset-0 bg-black/30" onClick={onClose} aria-hidden />
+      <aside className="relative z-10 flex h-full w-full max-w-2xl flex-col overflow-hidden border-l border-border bg-card shadow-xl">
+        <header className="flex items-center justify-between gap-2 border-b border-border px-4 py-3">
+          <div className="flex min-w-0 items-center gap-3">
+            <span className="text-xs uppercase tracking-wide text-muted-foreground">{type.label}</span>
+            {index >= 0 && records.length > 0 ? (
+              <span className="shrink-0 text-xs text-muted-foreground">
+                {index + 1} / {records.length}
+              </span>
+            ) : null}
+          </div>
+          <div className="flex shrink-0 items-center gap-1">
+            {/* Current state — and the rare manual override (mark written, un-reject). */}
+            {cfg.statusChoices.length > 0 ? (
+              <Select value={status || undefined} onValueChange={overrideStatus}>
+                <SelectTrigger className="h-7 w-auto gap-1 border-border text-xs capitalize">
+                  <SelectValue placeholder="State…" />
+                </SelectTrigger>
+                <SelectContent>
+                  {cfg.statusChoices.map((s) => (
+                    <SelectItem key={s} value={s} className="capitalize">
+                      {s}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            ) : null}
+            <button
+              onClick={() => onNavigate(prev!)}
+              disabled={!prev}
+              className="rounded p-1 text-muted-foreground hover:bg-muted disabled:opacity-30"
+              aria-label="Previous"
+              title="Previous (k / ↑)"
+            >
+              <ChevronLeft className="h-4 w-4" />
+            </button>
+            <button
+              onClick={() => onNavigate(next!)}
+              disabled={!next}
+              className="rounded p-1 text-muted-foreground hover:bg-muted disabled:opacity-30"
+              aria-label="Next"
+              title="Next (j / ↓)"
+            >
+              <ChevronRight className="h-4 w-4" />
+            </button>
+            <button
+              onClick={() => setMode((m) => (m === 'review' ? 'edit' : 'review'))}
+              className="ml-1 rounded border border-border px-2.5 py-1 text-xs hover:bg-muted"
+              title="Edit fields (e)"
+            >
+              {mode === 'review' ? 'Edit fields' : 'Review'}
+            </button>
+            <button
+              onClick={onClose}
+              className="rounded p-1 text-muted-foreground hover:bg-muted"
+              aria-label="Close"
+            >
+              <X className="h-4 w-4" />
+            </button>
+          </div>
+        </header>
+
+        {mode === 'edit' ? (
+          <div className="flex-1 overflow-y-auto px-4 py-4">
+            {renderEditFields ? (
+              renderEditFields({
+                record,
+                type,
+                back: () => setMode('review'),
+                saved: () => {
+                  onSaved?.();
+                  setMode('review');
+                },
+              })
+            ) : (
+              <p className="text-sm text-muted-foreground">No field editor is wired for this type.</p>
+            )}
+          </div>
+        ) : (
+          <>
+            <div className="flex-1 overflow-y-auto px-5 py-4">
+              <h2 className="text-lg font-semibold leading-snug text-foreground">{title}</h2>
+
+              <div className="mt-2 flex flex-wrap items-center gap-1.5 text-xs">
+                {rank ? (
+                  <span className="rounded-full bg-primary-50 px-2 py-0.5 font-semibold text-primary-700">
+                    rank {rank}
+                  </span>
+                ) : null}
+                {cfg.metaAttrs.map((a) => {
+                  const v = fieldStr(data, a);
+                  if (!v) return null;
+                  return (
+                    <span key={a} className="rounded-full bg-muted px-2 py-0.5 text-muted-foreground">
+                      {v.replace(/_/g, ' ')}
+                    </span>
+                  );
+                })}
+              </div>
+
+              {summary ? <p className="mt-3 text-sm leading-relaxed text-foreground/80">{summary}</p> : null}
+
+              <ReviewSources data={data} sourceAttrs={cfg.sourceAttrs} tierByHost={sourceTierByHost} />
+
+              {renderExtra ? <div className="mt-6 border-t border-border pt-4">{renderExtra(record, type)}</div> : null}
+            </div>
+
+            <footer className="space-y-3 border-t border-border px-4 py-3">
+              {decisions.length > 0 ? (
+                <div className="flex items-stretch gap-2">
+                  {decisions.map((d) => (
+                    <DecisionButton
+                      key={d.key}
+                      decision={d}
+                      active={verdict !== '' && d.verdict === verdict}
+                      busy={busy === `decision:${d.key}`}
+                      onClick={() => applyDecision(d)}
+                    />
+                  ))}
+                </div>
+              ) : null}
+
+              <div className="flex items-center gap-2">
+                <button
+                  onClick={() => setNoteOpen((o) => !o)}
+                  className={cn(
+                    'inline-flex items-center gap-1 rounded-md border border-border px-2.5 py-1 text-xs hover:bg-muted',
+                    note && 'text-primary-700',
+                  )}
+                >
+                  <MessageSquarePlus className="h-3.5 w-3.5" />
+                  {note ? 'Note ✓' : 'Add note'}
+                </button>
+                <span className="ml-auto text-[11px] text-muted-foreground">{legend}</span>
+              </div>
+
+              {noteOpen ? (
+                <div className="space-y-2">
+                  <Textarea
+                    value={note}
+                    onChange={(e) => setNote(e.target.value)}
+                    rows={2}
+                    placeholder="Why? — e.g. “good topic, angle too broad; needs a fresher source.”"
+                    className="text-sm"
+                    autoFocus
+                  />
+                  <div className="flex gap-2">
+                    <Button size="sm" onClick={saveNote} disabled={busy === 'note'}>
+                      {busy === 'note' ? 'Saving…' : 'Save note'}
+                    </Button>
+                    <Button
+                      size="sm"
+                      variant="outline"
+                      onClick={() => {
+                        setNote(fieldStr(data, cfg.noteAttr));
+                        setNoteOpen(false);
+                      }}
+                    >
+                      Cancel
+                    </Button>
+                  </div>
+                </div>
+              ) : note ? (
+                <p className="border-l-2 border-border pl-2 text-xs italic text-muted-foreground">{note}</p>
+              ) : null}
+            </footer>
+          </>
+        )}
+      </aside>
+    </div>
+  );
+}
+
+const DECISION_ICON: Record<ReviewDecision['tone'], typeof Check> = {
+  good: Check,
+  bad: X,
+  neutral: PencilLine,
+};
+const DECISION_STYLE: Record<ReviewDecision['tone'], string> = {
+  good: 'bg-emerald-600 text-white hover:bg-emerald-700 border-emerald-600',
+  bad: 'border-rose-300 text-rose-700 hover:bg-rose-50',
+  neutral: 'border-amber-300 text-amber-700 hover:bg-amber-50',
+};
+
+function DecisionButton({
+  decision,
+  active,
+  busy,
+  onClick,
+}: {
+  decision: ReviewDecision;
+  active: boolean;
+  busy: boolean;
+  onClick: () => void;
+}) {
+  const Icon = DECISION_ICON[decision.tone];
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={busy}
+      title={`${decision.label} (${decision.shortcut})`}
+      className={cn(
+        'flex flex-1 flex-col items-center justify-center gap-0.5 rounded-md border px-3 py-2 text-sm font-medium transition disabled:opacity-60',
+        DECISION_STYLE[decision.tone],
+        active && 'ring-2 ring-offset-1 ring-current',
+      )}
+    >
+      <span className="flex items-center gap-1.5">
+        <Icon className="h-4 w-4" />
+        {busy ? 'Saving…' : decision.label}
+      </span>
+      <span className={cn('text-[10px] font-normal', decision.tone === 'good' ? 'text-white/80' : 'opacity-70')}>
+        {decisionHint(decision)}
+      </span>
+    </button>
+  );
+}
+
+/** The tiny "→ ready · good" outcome hint under a decision. */
+function decisionHint(d: ReviewDecision): string {
+  const parts = [d.status ? `→ ${d.status}` : null, d.verdict].filter(Boolean);
+  return parts.join(' · ');
+}
+
+/** Source chips: host + optional tier badge, linked when a url is present. */
+function ReviewSources({
+  data,
+  sourceAttrs,
+  tierByHost,
+}: {
+  data: Record<string, unknown>;
+  sourceAttrs: string[];
+  tierByHost?: Map<string, number>;
+}) {
+  const urls = useMemo(() => {
+    const out: string[] = [];
+    for (const attr of sourceAttrs) {
+      const raw = readData(data, attr);
+      if (raw == null || raw === '') continue;
+      if (attr === 'sources' || Array.isArray(raw)) {
+        for (const s of parseSources(raw)) {
+          const u = (s.url || '').trim();
+          if (u) out.push(u);
+        }
+      } else {
+        out.push(String(raw).trim());
+      }
+    }
+    return out.filter(Boolean);
+  }, [data, sourceAttrs]);
+
+  if (sourceAttrs.length === 0) return null;
+  if (urls.length === 0) {
+    return (
+      <p className="mt-3 text-xs font-medium text-amber-600">No sources — needs verification.</p>
+    );
+  }
+  return (
+    <div className="mt-3 flex flex-wrap items-center gap-1.5">
+      <span className="text-xs text-muted-foreground">Sources:</span>
+      {urls.map((u, i) => {
+        const host = reviewHostOf(u);
+        const tier = host ? tierByHost?.get(host) : undefined;
+        const href = /^https?:\/\//.test(u) ? u : host ? `https://${u}` : undefined;
+        const chip = (
+          <span className="inline-flex items-center gap-1 rounded-full border border-border bg-card px-2 py-0.5 text-xs text-foreground/80">
+            {tier === 1 ? <ShieldCheck className="h-3 w-3 text-emerald-600" /> : null}
+            <span className="max-w-[12rem] truncate">{host || u}</span>
+            {tier != null ? (
+              <span
+                className={cn(
+                  'rounded px-1 text-[10px] font-semibold',
+                  tier === 1 ? 'bg-emerald-100 text-emerald-700' : 'bg-muted text-muted-foreground',
+                )}
+              >
+                T{tier}
+              </span>
+            ) : null}
+            {href ? <ExternalLink className="h-3 w-3 text-muted-foreground" /> : null}
+          </span>
+        );
+        return href ? (
+          <a key={i} href={href} target="_blank" rel="noreferrer" className="hover:opacity-80">
+            {chip}
+          </a>
+        ) : (
+          <span key={i}>{chip}</span>
+        );
+      })}
+    </div>
+  );
+}

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

@@ -0,0 +1,181 @@
+import {
+  deriveReviewTransitions,
+  resolveReviewConfig,
+  reviewDecisions,
+  pickStatusAttr,
+  shouldIgnoreShortcut,
+  nextReviewIndex,
+  reviewHostOf,
+  fieldStr,
+  DEFAULT_VERDICTS,
+} from '../review';
+import type { AttributeDef, EntityTypeDef } from '../types';
+
+function enumAttr(name: string, choices: string[]): AttributeDef {
+  return { id: name, name, dataType: 'enum', required: false, config: { choices } };
+}
+function textAttr(name: string): AttributeDef {
+  return { id: name, name, dataType: 'text', required: false, config: {} };
+}
+function type(attrs: AttributeDef[]): EntityTypeDef {
+  return { id: 'topic', key: 'topic', label: 'Topic', attributes: attrs };
+}
+
+describe('deriveReviewTransitions', () => {
+  it('maps the canonical OGMC pipeline (suggested→ready→rejected→written)', () => {
+    const t = deriveReviewTransitions(['suggested', 'ready', 'rejected', 'written']);
+    expect(t.approve).toBe('ready');
+    expect(t.reject).toBe('rejected');
+  });
+
+  it('skips terminal (published-like) stages when choosing Approve', () => {
+    // No dedicated "ready" — approve should still avoid the terminal "written".
+    const t = deriveReviewTransitions(['new', 'rejected', 'written']);
+    expect(t.reject).toBe('rejected');
+    // only forward non-terminal, non-reject candidate is none → falls back to the
+    // first successor that isn't the reject stage → 'written' (best available).
+    expect(t.approve).toBe('written');
+  });
+
+  it('detects varied rejection words', () => {
+    expect(deriveReviewTransitions(['open', 'approved', 'declined']).reject).toBe('declined');
+    expect(deriveReviewTransitions(['inbox', 'live', 'archived']).reject).toBe('archived');
+  });
+
+  it('honours explicit overrides (including nulling a button off)', () => {
+    const t = deriveReviewTransitions(['a', 'b', 'c'], { approve: 'c', reject: null });
+    expect(t.approve).toBe('c');
+    expect(t.reject).toBeNull();
+  });
+
+  it('returns nulls for an empty choice set', () => {
+    expect(deriveReviewTransitions([])).toEqual({ approve: null, reject: null });
+  });
+});
+
+describe('pickStatusAttr', () => {
+  it('prefers an attr named "status"', () => {
+    const t = type([enumAttr('kind', ['a', 'b']), enumAttr('status', ['x', 'y'])]);
+    expect(pickStatusAttr(t)?.name).toBe('status');
+  });
+  it('falls back to the first enum with choices', () => {
+    const t = type([textAttr('title'), enumAttr('stage', ['x', 'y'])]);
+    expect(pickStatusAttr(t)?.name).toBe('stage');
+  });
+  it('returns null when no enum attr has choices', () => {
+    expect(pickStatusAttr(type([textAttr('title')]))).toBeNull();
+  });
+});
+
+describe('resolveReviewConfig', () => {
+  const topic = type([
+    textAttr('title'),
+    textAttr('angle'),
+    enumAttr('content_type', ['weekly_brief', 'lead_magnet', 'general']),
+    enumAttr('status', ['suggested', 'ready', 'rejected', 'written']),
+    textAttr('market'),
+    textAttr('team_verdict'),
+    textAttr('team_notes'),
+  ]);
+
+  it('resolves the OGMC defaults from the live schema', () => {
+    const r = resolveReviewConfig(topic);
+    expect(r.statusName).toBe('status');
+    expect(r.transitions).toEqual({ approve: 'ready', reject: 'rejected' });
+    expect(r.verdictAttr).toBe('team_verdict');
+    expect(r.noteAttr).toBe('team_notes');
+    expect(r.verdicts).toBe(DEFAULT_VERDICTS);
+  });
+
+  it('drops meta/source attrs the type does not declare', () => {
+    const r = resolveReviewConfig(topic);
+    // default meta ['content_type','market'] both declared; default sources none declared
+    expect(r.metaAttrs).toEqual(['content_type', 'market']);
+    expect(r.sourceAttrs).toEqual([]);
+  });
+
+  it('lets overrides win', () => {
+    const r = resolveReviewConfig(topic, { rejectStatus: 'written', verdictAttr: 'vote' });
+    expect(r.transitions.reject).toBe('written');
+    expect(r.verdictAttr).toBe('vote');
+  });
+});
+
+describe('reviewDecisions', () => {
+  const topic = type([
+    enumAttr('status', ['suggested', 'ready', 'rejected', 'written']),
+    textAttr('team_verdict'),
+  ]);
+
+  it('maps the three decisions to status + verdict pairs on the OGMC schema', () => {
+    const d = reviewDecisions(resolveReviewConfig(topic));
+    expect(d.map((x) => x.key)).toEqual(['approve', 'needs_work', 'reject']);
+    expect(d.find((x) => x.key === 'approve')).toMatchObject({ status: 'ready', verdict: 'good', advance: true });
+    expect(d.find((x) => x.key === 'needs_work')).toMatchObject({ status: 'suggested', verdict: 'edit', advance: false, promptNote: true });
+    expect(d.find((x) => x.key === 'reject')).toMatchObject({ status: 'rejected', verdict: 'bad', advance: true });
+  });
+
+  it('drops decisions whose status target does not resolve', () => {
+    // two-state enum with no rejection word → no Reject; approve resolves to the successor
+    const twoState = type([enumAttr('status', ['open', 'closed']), textAttr('team_verdict')]);
+    const keys = reviewDecisions(resolveReviewConfig(twoState)).map((x) => x.key);
+    expect(keys).toContain('approve');
+    expect(keys).not.toContain('reject');
+  });
+
+  it('uses custom verdict vocab tones', () => {
+    const d = reviewDecisions(
+      resolveReviewConfig(topic, {
+        verdicts: [
+          { value: 'yes', label: 'Yes', tone: 'good' },
+          { value: 'no', label: 'No', tone: 'bad' },
+        ],
+      }),
+    );
+    expect(d.find((x) => x.key === 'approve')?.verdict).toBe('yes');
+    expect(d.find((x) => x.key === 'reject')?.verdict).toBe('no');
+    // no neutral verdict, but an entry stage exists → Needs work still offered (verdict null)
+    expect(d.find((x) => x.key === 'needs_work')).toMatchObject({ verdict: null });
+  });
+});
+
+describe('shouldIgnoreShortcut', () => {
+  it('ignores while typing in a form control', () => {
+    expect(shouldIgnoreShortcut({ key: 'a', target: { tagName: 'INPUT' } })).toBe(true);
+    expect(shouldIgnoreShortcut({ key: 'a', target: { tagName: 'TEXTAREA' } })).toBe(true);
+    expect(shouldIgnoreShortcut({ key: 'a', target: { isContentEditable: true } })).toBe(true);
+  });
+  it('ignores modified keys', () => {
+    expect(shouldIgnoreShortcut({ key: 'a', metaKey: true, target: { tagName: 'DIV' } })).toBe(true);
+  });
+  it('fires on a bare letter over non-input', () => {
+    expect(shouldIgnoreShortcut({ key: 'a', target: { tagName: 'DIV' } })).toBe(false);
+  });
+});
+
+describe('nextReviewIndex', () => {
+  it('advances to the next item', () => {
+    expect(nextReviewIndex(['a', 'b', 'c'], 'a')).toBe(1);
+    expect(nextReviewIndex(['a', 'b', 'c'], 'b')).toBe(2);
+  });
+  it('steps back when acting on the last item', () => {
+    expect(nextReviewIndex(['a', 'b', 'c'], 'c')).toBe(1);
+  });
+  it('returns -1 when the list would empty', () => {
+    expect(nextReviewIndex(['a'], 'a')).toBe(-1);
+    expect(nextReviewIndex([], 'a')).toBe(-1);
+  });
+});
+
+describe('reviewHostOf / fieldStr', () => {
+  it('bare-hosts a url with or without scheme', () => {
+    expect(reviewHostOf('https://www.reuters.com/x')).toBe('reuters.com');
+    expect(reviewHostOf('gov.ae/notice')).toBe('gov.ae');
+    expect(reviewHostOf('not a url')).toBe('');
+  });
+  it('reads camel or snake keys off the data blob', () => {
+    expect(fieldStr({ teamVerdict: 'good' }, 'team_verdict')).toBe('good');
+    expect(fieldStr({ team_verdict: 'bad' }, 'team_verdict')).toBe('bad');
+    expect(fieldStr(undefined, 'x')).toBe('');
+  });
+});

package/src/components/collection/index.ts

@@ -7,6 +7,23 @@
  */
 export { TopicReviewWorkspace, type TopicReviewWorkspaceProps } from './TopicReviewWorkspace';
 export { DraftReviewWorkspace, type DraftReviewWorkspaceProps } from './DraftReviewWorkspace';
+export { ReviewDrawer, type ReviewDrawerProps } from './ReviewDrawer';
+export {
+  resolveReviewConfig,
+  deriveReviewTransitions,
+  reviewDecisions,
+  type ReviewDecision,
+  pickStatusAttr,
+  shouldIgnoreShortcut,
+  nextReviewIndex,
+  choicesOf,
+  DEFAULT_VERDICTS,
+  type ReviewConfig,
+  type ResolvedReview,
+  type ReviewTransitions,
+  type VerdictOption,
+  type VerdictTone,
+} from './review';
 export type { CollectionClient, EntityRecord, EntityTypeDef, AttributeDef, Paginated, DataType } from './types';
 export { readData, toCamelKey } from './data';
 export {

package/src/components/collection/review.ts

@@ -0,0 +1,330 @@
+/**
+ * Pure, framework-free logic for the review-first record drawer (ReviewDrawer).
+ *
+ * A "review" surface turns a status-carrying entity type into a fast triage loop:
+ * read the record, cast a verdict, approve/reject it (a status move), jot a note,
+ * and step to the next one — all without leaving the drawer. Everything that can be
+ * decided WITHOUT React lives here so it unit-tests in isolation and the component
+ * stays thin:
+ *   - resolve the review "field map" from a declared schema (which attr is the
+ *     title / summary / status / verdict / note / rank / sources), with smart
+ *     defaults that match the OGMC content schema but are fully overridable;
+ *   - derive the Approve / Reject status targets from the status enum's choices;
+ *   - the bare-letter keyboard-shortcut guard (never fire while the user is typing).
+ *
+ * Nothing here is tenant-specific — the defaults are conventions, not requirements.
+ */
+import type { AttributeDef, EntityTypeDef } from './types';
+import { readData } from './data';
+
+// ---- keyboard guard (lifted so the drawer + any review surface share it) ----
+
+/** The bit of an event target we need in order to ask "is the user typing?". */
+export interface TypingTarget {
+  tagName?: string;
+  isContentEditable?: boolean;
+}
+
+/** The bit of a KeyboardEvent a shortcut decision depends on. */
+export interface ShortcutEventLike {
+  key: string;
+  metaKey?: boolean;
+  ctrlKey?: boolean;
+  altKey?: boolean;
+  target?: unknown;
+}
+
+const TYPING_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
+
+/** True when the event target takes typed input (form control or contenteditable). */
+export function isTypingTarget(target: unknown): boolean {
+  if (!target || typeof target !== 'object') return false;
+  const el = target as TypingTarget;
+  if (el.isContentEditable === true) return true;
+  return typeof el.tagName === 'string' && TYPING_TAGS.has(el.tagName.toUpperCase());
+}
+
+/**
+ * True when a bare-letter review shortcut must NOT fire. Any of cmd/ctrl/alt means
+ * the user is reaching for a browser/OS command; a form control / contenteditable
+ * means they're typing (a note, an edit) — firing "x" would silently reject.
+ */
+export function shouldIgnoreShortcut(event: ShortcutEventLike): boolean {
+  if (event.metaKey || event.ctrlKey || event.altKey) return true;
+  return isTypingTarget(event.target);
+}
+
+// ---- verdict vocabulary ----
+
+export type VerdictTone = 'good' | 'bad' | 'neutral';
+
+export interface VerdictOption {
+  value: string;
+  label: string;
+  tone: VerdictTone;
+}
+
+/** The default team-verdict vocabulary (👍 good / 👎 bad / ✎ needs-edit). */
+export const DEFAULT_VERDICTS: VerdictOption[] = [
+  { value: 'good', label: 'Good', tone: 'good' },
+  { value: 'bad', label: 'Bad', tone: 'bad' },
+  { value: 'edit', label: 'Edit', tone: 'neutral' },
+];
+
+// ---- status transitions (Approve / Reject) ----
+
+const REJECT_RE = /reject|declin|archiv|spam|discard|dismiss|kill/i;
+const TERMINAL_RE = /written|publish|post|done|complete|sent|live|shipped|closed/i;
+
+/** The declared enum choices of an attribute (coerced to strings), or []. */
+export function choicesOf(attr: AttributeDef | null | undefined): string[] {
+  const c = attr?.config?.choices;
+  return Array.isArray(c) ? c.map((x) => String(x)) : [];
+}
+
+/**
+ * The attribute whose enum choices drive the status pipeline: prefer one named
+ * exactly `preferred` (default "status"), else the first enum attr with choices.
+ * null when the type declares none (the caller falls back / hides the actions).
+ */
+export function pickStatusAttr(
+  type: EntityTypeDef | undefined | null,
+  preferred = 'status',
+): AttributeDef | null {
+  const enums = (type?.attributes ?? []).filter(
+    (a) => a.dataType === 'enum' && choicesOf(a).length > 0,
+  );
+  if (enums.length === 0) return null;
+  return enums.find((a) => a.name === preferred) ?? enums[0];
+}
+
+export interface ReviewTransitions {
+  /** Status value the Approve action moves a record to (null → no Approve button). */
+  approve: string | null;
+  /** Status value the Reject action moves a record to (null → no Reject button). */
+  reject: string | null;
+}
+
+/**
+ * Derive the Approve / Reject status targets from a status enum's choices.
+ *
+ * Convention (matches `suggested → ready → rejected → written`):
+ *   - REJECT = the first choice that reads like a rejection (rejected/declined/…);
+ *   - APPROVE = the first "forward" choice: not the entry (first) stage, not the
+ *     reject stage, and not a terminal/published stage — i.e. the "accepted, ready
+ *     to act" stage. Falls back to the entry stage's immediate successor.
+ * Explicit overrides always win. Returns nulls when nothing sensible resolves, so
+ * a two-state or non-workflow enum simply shows fewer buttons rather than guessing.
+ */
+export function deriveReviewTransitions(
+  choices: string[],
+  override?: { approve?: string | null; reject?: string | null },
+): ReviewTransitions {
+  const reject =
+    override?.reject !== undefined
+      ? override.reject
+      : choices.find((c) => REJECT_RE.test(c)) ?? null;
+
+  let approve: string | null;
+  if (override?.approve !== undefined) {
+    approve = override.approve;
+  } else {
+    const entry = choices[0];
+    approve =
+      choices.find(
+        (c, i) => i > 0 && c !== reject && !TERMINAL_RE.test(c) && c !== entry,
+      ) ??
+      // nothing "forward & non-terminal" → the successor of the entry stage.
+      choices.find((c, i) => i > 0 && c !== reject) ??
+      null;
+  }
+  return { approve, reject };
+}
+
+// ---- resolved review field map ----
+
+/** Consumer-facing overrides for the review field map (all optional). */
+export interface ReviewConfig {
+  /** Enum attr that drives the status pipeline (default: "status", else first enum). */
+  statusAttr?: string;
+  /** Explicit Approve target status (default: derived from the choices). */
+  approveStatus?: string | null;
+  /** Explicit Reject target status (default: derived from the choices). */
+  rejectStatus?: string | null;
+  /** Attr the verdict buttons write (default: "team_verdict"). */
+  verdictAttr?: string;
+  /** Verdict vocabulary (default: good / bad / edit). */
+  verdicts?: VerdictOption[];
+  /** Attr the quick-note writes (default: "team_notes"). */
+  noteAttr?: string;
+  /** Attr used as the readable heading (default: "title", else record.name). */
+  titleAttr?: string;
+  /** Attr used as the one-line summary under the title (default: "angle"). */
+  summaryAttr?: string;
+  /** Numeric attr shown as a rank chip (default: "ai_rank"). */
+  rankAttr?: string;
+  /** Short attrs shown as meta chips (default: ["content_type", "market"]). */
+  metaAttrs?: string[];
+  /** Attrs holding source urls/lines (default: source_1..3 + "sources"). */
+  sourceAttrs?: string[];
+}
+
+export interface ResolvedReview {
+  statusAttr: AttributeDef | null;
+  statusName: string;
+  statusChoices: string[];
+  transitions: ReviewTransitions;
+  verdictAttr: string;
+  verdicts: VerdictOption[];
+  noteAttr: string;
+  titleAttr: string;
+  summaryAttr: string;
+  rankAttr: string;
+  metaAttrs: string[];
+  sourceAttrs: string[];
+}
+
+const DEFAULT_SOURCE_ATTRS = ['source_1', 'source_2', 'source_3', 'sources'];
+const DEFAULT_META_ATTRS = ['content_type', 'market'];
+
+/** Resolve the full review field map from a type's schema + optional overrides. */
+export function resolveReviewConfig(
+  type: EntityTypeDef | undefined | null,
+  config: ReviewConfig = {},
+): ResolvedReview {
+  const statusAttr = pickStatusAttr(type, config.statusAttr ?? 'status');
+  const statusChoices = choicesOf(statusAttr);
+  const declared = new Set((type?.attributes ?? []).map((a) => a.name));
+  return {
+    statusAttr,
+    statusName: statusAttr?.name ?? config.statusAttr ?? 'status',
+    statusChoices,
+    transitions: deriveReviewTransitions(statusChoices, {
+      approve: config.approveStatus,
+      reject: config.rejectStatus,
+    }),
+    verdictAttr: config.verdictAttr ?? 'team_verdict',
+    verdicts: config.verdicts ?? DEFAULT_VERDICTS,
+    noteAttr: config.noteAttr ?? 'team_notes',
+    titleAttr: config.titleAttr ?? 'title',
+    summaryAttr: config.summaryAttr ?? 'angle',
+    rankAttr: config.rankAttr ?? 'ai_rank',
+    metaAttrs: (config.metaAttrs ?? DEFAULT_META_ATTRS).filter((a) => declared.has(a)),
+    // Keep source attrs the caller asked for; default to the ones this type declares.
+    sourceAttrs: (config.sourceAttrs ?? DEFAULT_SOURCE_ATTRS).filter((a) => declared.has(a)),
+  };
+}
+
+// ---- the single review decision (Approve / Needs work / Reject) ----
+//
+// status and team_verdict are two fields with different consumers (status = the
+// pipeline gate the writer keys off; team_verdict = the signal the re-rank agent
+// turns INTO status). Their outcomes overlap, so the reviewer makes ONE decision
+// and we write BOTH fields coherently — never two competing button rows.
+
+export interface ReviewDecision {
+  /** Stable id ('approve' | 'needs_work' | 'reject'). */
+  key: string;
+  label: string;
+  /** Status to write (null → leave status untouched). */
+  status: string | null;
+  /** Verdict to write (null → leave verdict untouched). */
+  verdict: string | null;
+  tone: VerdictTone;
+  /** Auto-advance to the next record after this decision. */
+  advance: boolean;
+  /** Bare-letter shortcut. */
+  shortcut: string;
+  /** Open the note box on this decision (a rejection/hold wants a reason). */
+  promptNote: boolean;
+}
+
+/**
+ * The (up to) three review decisions derived from the resolved config:
+ *   - Approve    → the approve status  + the "good" verdict, auto-advances
+ *   - Needs work → back to the entry stage + the "edit"/neutral verdict, holds
+ *                  (so it's revisited) and prompts a note
+ *   - Reject     → the reject status + the "bad" verdict, auto-advances
+ * 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.
+ */
+export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
+  const verdictOf = (tone: VerdictTone): string | null =>
+    r.verdicts.find((v) => v.tone === tone)?.value ?? null;
+  const entry = r.statusChoices[0] ?? null;
+  const out: ReviewDecision[] = [];
+
+  if (r.transitions.approve) {
+    out.push({
+      key: 'approve',
+      label: 'Approve',
+      status: r.transitions.approve,
+      verdict: verdictOf('good'),
+      tone: 'good',
+      advance: true,
+      shortcut: 'a',
+      promptNote: false,
+    });
+  }
+
+  const editVerdict = verdictOf('neutral');
+  if (entry && (editVerdict || entry !== r.transitions.approve)) {
+    out.push({
+      key: 'needs_work',
+      label: 'Needs work',
+      status: entry,
+      verdict: editVerdict,
+      tone: 'neutral',
+      advance: false,
+      shortcut: 'w',
+      promptNote: true,
+    });
+  }
+
+  if (r.transitions.reject) {
+    out.push({
+      key: 'reject',
+      label: 'Reject',
+      status: r.transitions.reject,
+      verdict: verdictOf('bad'),
+      tone: 'bad',
+      advance: true,
+      shortcut: 'x',
+      promptNote: false,
+    });
+  }
+  return out;
+}
+
+// ---- small read helpers used by the component (kept here so they're tested) ----
+
+/** String read of an attr off a record's data blob ('' when missing). */
+export function fieldStr(data: Record<string, unknown> | undefined, name: string): string {
+  const v = readData(data, name);
+  return v == null ? '' : String(v);
+}
+
+/** Normalise a url to its bare host (lowercased, `www.` stripped). '' if unparseable. */
+export function reviewHostOf(url: string): string {
+  try {
+    return new URL(/^https?:\/\//.test(url) ? url : `https://${url}`).hostname
+      .toLowerCase()
+      .replace(/^www\./, '');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * The index to move to after acting on `current` within `ids`. Returns the next
+ * item, or the previous when acting on the last, or -1 when the list empties — so
+ * an Approve/Reject can auto-advance the reviewer to fresh work without a dead end.
+ */
+export function nextReviewIndex(ids: string[], currentId: string): number {
+  const i = ids.indexOf(currentId);
+  if (i === -1) return ids.length > 0 ? 0 : -1;
+  if (i + 1 < ids.length) return i + 1;
+  if (i - 1 >= 0) return i - 1;
+  return -1;
+}