@startsimpli/ui 0.4.53 → 0.4.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.53",
+  "version": "0.4.54",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -41,8 +41,8 @@
     "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.44",
-    "@startsimpli/auth": "0.4.29"
+    "@startsimpli/auth": "0.4.29",
+    "@startsimpli/api": "0.5.44"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/catalog/catalog.ts

@@ -190,6 +190,24 @@ export const UI_CATALOG: CatalogEntry[] = [
     dataNeeds: 'A content type carrying a judge verdict + auto-checks (and the editable content fields to recheck).',
     source: { export: 'ValidationChecklist', from: '@startsimpli/ui' },
   },
+  {
+    id: 'review-scorecard',
+    category: 'component',
+    title: 'Review scorecard',
+    description:
+      "A controlled scorecard for a human reviewer's structured judgement of an AI-generated draft: an overall verdict segmented control (Approve / Revise / Reject, toned green/amber/red), one 1–5 score + note row per guardrail dimension (defaults to political-sensitivity, source-reliability, recency, tone-and-voice, accuracy — overridable), and an overall note. Bring-your-own-data + onChange (the app owns persistence); the captured verdict + scores drive a downstream AI revise loop. Pair it with the validation-checklist (machine review) and review-notes (section critique).",
+    dataNeeds: 'A content type carrying a reviewer verdict + per-dimension scores/notes.',
+    source: { export: 'ReviewScorecard', from: '@startsimpli/ui' },
+  },
+  {
+    id: 'review-notes',
+    category: 'component',
+    title: 'Review notes',
+    description:
+      "A lightweight critique thread for an AI-generated draft, used per content section or overall: a list of reviewer notes (author, relative time, resolve action, resolved styling) plus a composer. Purely presentational + bring-your-own-data (onAdd / onResolve callbacks; no fetching). Pair it with the review-scorecard to capture section-level feedback that feeds the AI revise loop.",
+    dataNeeds: 'A review-note / comment type (body + optional author, timestamp, section, resolved flag).',
+    source: { export: 'ReviewNotes', from: '@startsimpli/ui' },
+  },
   {
     id: 'chat',
     category: 'component',

package/src/components/index.ts

@@ -173,3 +173,8 @@ export * from './record-detail'
 // runContentChecks recompute util. Light (React + lucide only), so it ships on
 // the main barrel rather than a subpath.
 export * from './validation'
+
+// Reviewer feedback (768w.16.10.4) — ReviewScorecard (verdict + per-guardrail
+// scorecard) + ReviewNotes (critique thread). Controlled + presentational; light
+// (React + lucide only), so they ride the main barrel like health / validation.
+export * from './review'

package/src/components/review/ReviewNotes.tsx

@@ -0,0 +1,130 @@
+import * as React from 'react';
+import { MessageSquare, Check } from 'lucide-react';
+import { cn } from '../../lib/utils';
+import { formatRelativeTime } from '../../utils';
+
+/** One critique note in a review thread (used per content section or overall). */
+export interface ReviewNote {
+  id: string;
+  body: string;
+  author?: string;
+  /** When the note was recorded — rendered as a relative time if present. */
+  at?: string | Date;
+  resolved?: boolean;
+  /** Optional section/anchor the note is about. */
+  section?: string;
+}
+
+export interface ReviewNotesProps {
+  /** The notes to render. */
+  notes: ReviewNote[];
+  /** Provide to show a composer. Called with the new note body. */
+  onAdd?: (body: string) => void;
+  /** Provide to show a Resolve action on unresolved notes. */
+  onResolve?: (id: string) => void;
+  emptyMessage?: string;
+  title?: string;
+  /** Hide the composer + resolve actions (view-only). */
+  readOnly?: boolean;
+  className?: string;
+}
+
+/**
+ * A lightweight note/critique thread (768w.16.10.4) — the section-level or overall
+ * companion to ReviewScorecard. Purely presentational + bring-your-own-data: it
+ * lists notes (author, relative time, resolved styling), exposes a Resolve action
+ * and a composer when the callbacks are provided, and never fetches or persists.
+ */
+export function ReviewNotes({
+  notes,
+  onAdd,
+  onResolve,
+  emptyMessage = 'No notes yet.',
+  title = 'Notes',
+  readOnly,
+  className,
+}: ReviewNotesProps) {
+  const [draft, setDraft] = React.useState('');
+  const canCompose = !readOnly && !!onAdd;
+
+  const submit = () => {
+    const body = draft.trim();
+    if (!body) return;
+    onAdd?.(body);
+    setDraft('');
+  };
+
+  return (
+    <div className={cn('rounded-xl border bg-card text-card-foreground shadow p-5 space-y-4', className)}>
+      <div className="flex items-center gap-2 min-w-0">
+        <MessageSquare className="w-4 h-4 text-gray-400 flex-shrink-0" aria-hidden="true" />
+        <h3 className="text-sm font-semibold text-gray-900 truncate">{title}</h3>
+        {notes.length > 0 && <span className="text-xs text-gray-400">{notes.length}</span>}
+      </div>
+
+      {notes.length === 0 ? (
+        <p className="text-sm text-gray-500 py-2 text-center">{emptyMessage}</p>
+      ) : (
+        <ul className="space-y-2">
+          {notes.map((note) => (
+            <li
+              key={note.id}
+              className={cn('rounded-lg border p-3 text-sm space-y-1', note.resolved && 'opacity-60')}
+            >
+              <div className="flex items-center justify-between gap-3">
+                <div className="flex items-center gap-2 min-w-0 text-xs text-gray-500 flex-wrap">
+                  {note.author && <span className="font-medium text-gray-700">{note.author}</span>}
+                  {note.section && (
+                    <span className="rounded bg-gray-100 px-1.5 py-0.5 text-[10px] text-gray-600">{note.section}</span>
+                  )}
+                  {note.at && <span>{formatRelativeTime(note.at)}</span>}
+                </div>
+                {note.resolved ? (
+                  <span className="inline-flex items-center gap-1 text-xs font-medium text-emerald-600 flex-shrink-0">
+                    <Check className="w-3.5 h-3.5" aria-hidden="true" />
+                    Resolved
+                  </span>
+                ) : (
+                  onResolve &&
+                  !readOnly && (
+                    <button
+                      type="button"
+                      onClick={() => onResolve(note.id)}
+                      className="text-xs font-medium text-gray-500 hover:text-gray-900 flex-shrink-0"
+                    >
+                      Resolve
+                    </button>
+                  )
+                )}
+              </div>
+              <p className={cn('text-gray-900 break-words', note.resolved && 'line-through text-gray-500')}>
+                {note.body}
+              </p>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      {canCompose && (
+        <div className="space-y-2 border-t pt-3">
+          <textarea
+            value={draft}
+            onChange={(e) => setDraft(e.target.value)}
+            rows={2}
+            placeholder="Add a note…"
+            aria-label="Add a note"
+            className="w-full rounded-md border px-2 py-1 text-sm"
+          />
+          <button
+            type="button"
+            disabled={draft.trim().length === 0}
+            onClick={submit}
+            className="rounded-md bg-gray-900 px-2.5 py-1 text-xs font-medium text-white disabled:opacity-40"
+          >
+            Add note
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/review/ReviewScorecard.tsx

@@ -0,0 +1,226 @@
+import * as React from 'react';
+import { ClipboardCheck } from 'lucide-react';
+import { cn } from '../../lib/utils';
+
+/** One guardrail/dimension the reviewer scores (key drives storage, label is shown). */
+export interface ReviewDimension {
+  key: string;
+  label: string;
+}
+
+/**
+ * A reviewer's structured judgement of an AI-generated draft: an overall verdict
+ * plus per-guardrail scores/notes and a free-text overall note. Drives the
+ * downstream AI revise loop.
+ */
+export interface ReviewScore {
+  /** Overall verdict — the primary signal for the revise loop. */
+  verdict?: 'approve' | 'revise' | 'reject';
+  /** Per-dimension score (1–5) + optional note, keyed by dimension key. */
+  dimensions?: Record<string, { score?: number; note?: string }>;
+  /** Free-text overall note. */
+  overallNote?: string;
+}
+
+/**
+ * The default guardrail dimensions, mirroring a content-guardrail judge. Callers
+ * can override with any dimension set — the scorecard renders whatever it's given,
+ * so it stays generic (this is one sensible instance, not the design driver).
+ */
+export const DEFAULT_REVIEW_DIMENSIONS: ReviewDimension[] = [
+  { key: 'political-sensitivity', label: 'Political sensitivity' },
+  { key: 'source-reliability', label: 'Source reliability' },
+  { key: 'recency', label: 'Recency' },
+  { key: 'tone-and-voice', label: 'Tone and voice' },
+  { key: 'accuracy', label: 'Accuracy' },
+];
+
+type Verdict = NonNullable<ReviewScore['verdict']>;
+
+/** Redundant (color + label) tone per verdict — never rely on color alone. */
+const VERDICT_TONE: Record<Verdict, { label: string; bg: string; text: string }> = {
+  approve: { label: 'Approve', bg: 'bg-emerald-600', text: 'text-white' },
+  revise: { label: 'Revise', bg: 'bg-amber-500', text: 'text-white' },
+  reject: { label: 'Reject', bg: 'bg-red-600', text: 'text-white' },
+};
+
+const VERDICTS: Verdict[] = ['approve', 'revise', 'reject'];
+const SCORE_VALUES = [1, 2, 3, 4, 5];
+
+export interface ReviewScorecardProps {
+  /** Controlled value — the reviewer's current judgement. */
+  value: ReviewScore;
+  /** Called with the next value on every change (immutable). */
+  onChange: (next: ReviewScore) => void;
+  /** The dimensions to score. Defaults to DEFAULT_REVIEW_DIMENSIONS. */
+  dimensions?: ReviewDimension[];
+  /** Render values as read-only (no inputs). */
+  readOnly?: boolean;
+  title?: string;
+  className?: string;
+}
+
+/** A 1–5 score picker (clickable dots), read-only when the scorecard is. */
+function ScorePicker({
+  label,
+  value,
+  onChange,
+  readOnly,
+}: {
+  label: string;
+  value?: number;
+  onChange: (score: number) => void;
+  readOnly?: boolean;
+}) {
+  return (
+    <div className="flex items-center gap-1" role="group" aria-label={`${label} score`}>
+      {SCORE_VALUES.map((n) => {
+        const filled = value != null && n <= value;
+        if (readOnly) {
+          return (
+            <span
+              key={n}
+              className={cn('inline-block w-3.5 h-3.5 rounded-full', filled ? 'bg-gray-900' : 'bg-gray-200')}
+              aria-hidden="true"
+            />
+          );
+        }
+        return (
+          <button
+            key={n}
+            type="button"
+            onClick={() => onChange(n)}
+            aria-label={`${label} score ${n}`}
+            aria-pressed={value === n}
+            className={cn(
+              'w-4 h-4 rounded-full transition-colors',
+              filled ? 'bg-gray-900' : 'bg-gray-200 hover:bg-gray-300',
+            )}
+          />
+        );
+      })}
+      <span className="ml-1.5 text-xs text-gray-500 tabular-nums">{value != null ? `${value}/5` : '—'}</span>
+    </div>
+  );
+}
+
+/**
+ * A controlled scorecard for a reviewer's structured judgement of an AI-generated
+ * draft (768w.16.10.4). Presentational + bring-your-own-data: it renders a verdict
+ * segmented control, one scored row per guardrail dimension, and an overall note —
+ * emitting the next ReviewScore (immutably) on every change. It never fetches or
+ * persists; the app owns the data and the downstream revise loop.
+ */
+export function ReviewScorecard({
+  value,
+  onChange,
+  dimensions = DEFAULT_REVIEW_DIMENSIONS,
+  readOnly,
+  title = 'Review',
+  className,
+}: ReviewScorecardProps) {
+  const setDimension = (key: string, patch: { score?: number; note?: string }) => {
+    const prev = value.dimensions?.[key] ?? {};
+    onChange({
+      ...value,
+      dimensions: { ...value.dimensions, [key]: { ...prev, ...patch } },
+    });
+  };
+
+  return (
+    <div className={cn('rounded-xl border bg-card text-card-foreground shadow p-5 space-y-4', className)}>
+      {/* Header + verdict */}
+      <div className="flex items-center justify-between gap-3">
+        <div className="flex items-center gap-2 min-w-0">
+          <ClipboardCheck className="w-4 h-4 text-gray-400 flex-shrink-0" aria-hidden="true" />
+          <h3 className="text-sm font-semibold text-gray-900 truncate">{title}</h3>
+        </div>
+        {readOnly ? (
+          value.verdict ? (
+            <span
+              className={cn(
+                'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium flex-shrink-0',
+                VERDICT_TONE[value.verdict].bg,
+                VERDICT_TONE[value.verdict].text,
+              )}
+            >
+              {VERDICT_TONE[value.verdict].label}
+            </span>
+          ) : (
+            <span className="text-xs text-gray-500 flex-shrink-0">No verdict</span>
+          )
+        ) : (
+          <div className="inline-flex rounded-lg border bg-gray-50 p-0.5 flex-shrink-0" role="group" aria-label="Verdict">
+            {VERDICTS.map((v) => {
+              const tone = VERDICT_TONE[v];
+              const selected = value.verdict === v;
+              return (
+                <button
+                  key={v}
+                  type="button"
+                  onClick={() => onChange({ ...value, verdict: v })}
+                  aria-pressed={selected}
+                  className={cn(
+                    'px-3 py-1 text-xs font-medium rounded-md transition-colors',
+                    selected ? cn(tone.bg, tone.text) : 'text-gray-600 hover:text-gray-900',
+                  )}
+                >
+                  {tone.label}
+                </button>
+              );
+            })}
+          </div>
+        )}
+      </div>
+
+      {/* Per-dimension rows */}
+      <div className="space-y-3">
+        {dimensions.map((dim) => {
+          const dimVal = value.dimensions?.[dim.key] ?? {};
+          return (
+            <div key={dim.key} className="space-y-1.5">
+              <div className="flex items-center justify-between gap-3">
+                <span className="text-sm text-gray-900">{dim.label}</span>
+                <ScorePicker
+                  label={dim.label}
+                  value={dimVal.score}
+                  onChange={(score) => setDimension(dim.key, { score })}
+                  readOnly={readOnly}
+                />
+              </div>
+              {readOnly ? (
+                dimVal.note ? <p className="text-xs text-gray-500 break-words">{dimVal.note}</p> : null
+              ) : (
+                <input
+                  type="text"
+                  value={dimVal.note ?? ''}
+                  onChange={(e) => setDimension(dim.key, { note: e.target.value })}
+                  aria-label={`${dim.label} note`}
+                  placeholder="Add a note…"
+                  className="w-full rounded-md border px-2 py-1 text-xs"
+                />
+              )}
+            </div>
+          );
+        })}
+      </div>
+
+      {/* Overall note */}
+      <div className="border-t pt-3 space-y-1.5">
+        <span className="text-xs font-medium text-gray-600">Overall note</span>
+        {readOnly ? (
+          <p className="text-sm text-gray-700 break-words">{value.overallNote || <span className="text-gray-400">—</span>}</p>
+        ) : (
+          <textarea
+            value={value.overallNote ?? ''}
+            onChange={(e) => onChange({ ...value, overallNote: e.target.value })}
+            aria-label="Overall note"
+            rows={2}
+            placeholder="Summarise your feedback…"
+            className="w-full rounded-md border px-2 py-1 text-sm"
+          />
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/review/__tests__/review.test.tsx

@@ -0,0 +1,114 @@
+import * as React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { ReviewScorecard, ReviewNotes, DEFAULT_REVIEW_DIMENSIONS } from '../index';
+import type { ReviewScore, ReviewNote } from '../index';
+
+describe('ReviewScorecard', () => {
+  it('exposes the default guardrail dimensions', () => {
+    expect(DEFAULT_REVIEW_DIMENSIONS.map((d) => d.key)).toEqual([
+      'political-sensitivity',
+      'source-reliability',
+      'recency',
+      'tone-and-voice',
+      'accuracy',
+    ]);
+  });
+
+  it('emits the next value when a verdict is chosen', () => {
+    const onChange = jest.fn();
+    render(<ReviewScorecard value={{}} onChange={onChange} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Revise' }));
+    expect(onChange).toHaveBeenCalledWith({ verdict: 'revise' });
+  });
+
+  it('emits the next value (immutably) when a dimension score is clicked', () => {
+    const onChange = jest.fn();
+    const value: ReviewScore = { verdict: 'approve' };
+    render(<ReviewScorecard value={value} onChange={onChange} />);
+    fireEvent.click(screen.getByLabelText('Accuracy score 4'));
+    expect(onChange).toHaveBeenCalledWith({ verdict: 'approve', dimensions: { accuracy: { score: 4 } } });
+    // original value not mutated
+    expect(value).toEqual({ verdict: 'approve' });
+  });
+
+  it('merges a dimension note without dropping an existing score', () => {
+    const onChange = jest.fn();
+    render(
+      <ReviewScorecard value={{ dimensions: { accuracy: { score: 5 } } }} onChange={onChange} />,
+    );
+    fireEvent.change(screen.getByLabelText('Accuracy note'), { target: { value: 'Well cited' } });
+    expect(onChange).toHaveBeenCalledWith({ dimensions: { accuracy: { score: 5, note: 'Well cited' } } });
+  });
+
+  it('emits the overall note', () => {
+    const onChange = jest.fn();
+    render(<ReviewScorecard value={{}} onChange={onChange} />);
+    fireEvent.change(screen.getByLabelText('Overall note'), { target: { value: 'Looks solid.' } });
+    expect(onChange).toHaveBeenCalledWith({ overallNote: 'Looks solid.' });
+  });
+
+  it('renders read-only values with no inputs', () => {
+    render(
+      <ReviewScorecard
+        readOnly
+        onChange={jest.fn()}
+        dimensions={[{ key: 'accuracy', label: 'Accuracy' }]}
+        value={{ verdict: 'approve', dimensions: { accuracy: { score: 5, note: 'Solid sourcing' } }, overallNote: 'Ship it' }}
+      />,
+    );
+    expect(screen.getByText('Approve')).toBeInTheDocument();
+    expect(screen.getByText('Solid sourcing')).toBeInTheDocument();
+    expect(screen.getByText('Ship it')).toBeInTheDocument();
+    // no interactive inputs in read-only mode
+    expect(screen.queryByRole('textbox')).not.toBeInTheDocument();
+    expect(screen.queryByLabelText('Accuracy score 5')).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Revise' })).not.toBeInTheDocument();
+  });
+});
+
+describe('ReviewNotes', () => {
+  const notes: ReviewNote[] = [
+    { id: 'n1', body: 'Tighten the intro.', author: 'Alex', at: new Date().toISOString() },
+    { id: 'n2', body: 'Fixed the citation.', author: 'Sam', resolved: true },
+  ];
+
+  it('shows the empty message when there are no notes', () => {
+    render(<ReviewNotes notes={[]} emptyMessage="Nothing flagged." />);
+    expect(screen.getByText('Nothing flagged.')).toBeInTheDocument();
+  });
+
+  it('renders notes with author and resolved styling', () => {
+    render(<ReviewNotes notes={notes} />);
+    expect(screen.getByText('Tighten the intro.')).toBeInTheDocument();
+    expect(screen.getByText('Alex')).toBeInTheDocument();
+    expect(screen.getByText('Resolved')).toBeInTheDocument();
+    expect(screen.getByText('Today')).toBeInTheDocument();
+  });
+
+  it('adds a note via the composer', () => {
+    const onAdd = jest.fn();
+    render(<ReviewNotes notes={[]} onAdd={onAdd} />);
+    fireEvent.change(screen.getByLabelText('Add a note'), { target: { value: '  Needs a stronger hook  ' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Add note' }));
+    expect(onAdd).toHaveBeenCalledWith('Needs a stronger hook');
+  });
+
+  it('disables the add button until there is text', () => {
+    render(<ReviewNotes notes={[]} onAdd={jest.fn()} />);
+    expect(screen.getByRole('button', { name: 'Add note' })).toBeDisabled();
+  });
+
+  it('resolves an unresolved note', () => {
+    const onResolve = jest.fn();
+    render(<ReviewNotes notes={notes} onResolve={onResolve} />);
+    // only the unresolved note (n1) exposes a Resolve action
+    fireEvent.click(screen.getByRole('button', { name: 'Resolve' }));
+    expect(onResolve).toHaveBeenCalledWith('n1');
+  });
+
+  it('hides the composer and resolve actions in read-only mode', () => {
+    render(<ReviewNotes notes={notes} onAdd={jest.fn()} onResolve={jest.fn()} readOnly />);
+    expect(screen.queryByRole('button', { name: 'Add note' })).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Resolve' })).not.toBeInTheDocument();
+  });
+});

package/src/components/review/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Reviewer feedback surfaces (768w.16.10.4) — presentational, bring-your-own-data
+ * controls for recording a human reviewer's structured judgement of an AI draft:
+ * an overall verdict + per-guardrail scorecard (ReviewScorecard) and section/overall
+ * critique threads (ReviewNotes). Controlled (value + onChange / callbacks); they
+ * never fetch or persist. The captured feedback drives a downstream AI revise loop.
+ * Light (React + lucide only), so they ride the main components barrel like the
+ * health / validation blocks — no dedicated subpath.
+ */
+export { ReviewScorecard, DEFAULT_REVIEW_DIMENSIONS } from './ReviewScorecard';
+export type { ReviewScorecardProps, ReviewScore, ReviewDimension } from './ReviewScorecard';
+
+export { ReviewNotes } from './ReviewNotes';
+export type { ReviewNotesProps, ReviewNote } from './ReviewNotes';