@appinternalleads/ui 0.2.0

package/src/components/checklist/ChecklistView.tsx

@@ -0,0 +1,831 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Box, Icon, Input, Pressable, Text } from '../../core';
+import { Button, Callout, ProgressBar } from '../../ds';
+import { blockRadii, useDs } from '../../tokens';
+import { SurfaceProvider, useMeasuredSurface } from '../../widgets/useSurface';
+import {
+  defaultChecklistConfig, validateChecklistConfig,
+  type Checklist, type ChecklistCapabilities, type ChecklistChange, type ChecklistConfig,
+  type ChecklistOperations, type ChecklistRule, type ChecklistSection, type ChecklistTask,
+  type PeopleAdapter, type Person, type ShareRequest,
+} from './contract';
+import { gateMessage, progressOf, sectionProgressOf, taskViewOf, unsatisfiedGates, type TaskView } from './derive';
+import { useChecklistRuntime, type ChecklistRuntimeState, type PendingChange } from './runtime';
+
+/**
+ * **Checklist — the component.** Tick a task, add one, assign one, share the list.
+ *
+ * It renders `Data + Config + Rules` through one runtime and draws nothing else. Everything a
+ * reader sees that is not in the document is *derived* (`derive.ts`): the count, the bar, each
+ * section's n/m, and whether a task is blocked. There is no progress state in this file, no second
+ * completion flag, and no place to put one — §15.
+ *
+ * **What it never shows.** A status name, a change id, a latency number, an abort signal, an
+ * `AppError`, JSON. A change in flight is invisible until it is slow; a change that failed says
+ * "We could not save that" and offers Try again. The machinery is the Playground's business
+ * (`onRuntimeChange`), never the reader's — §13.
+ *
+ * **There are no timers in this file.** Latency and failure live in the mock operations
+ * (`mock.ts`); the one presentational threshold lives in the runtime. A row's only relationship
+ * with time is reading `slow` off a pending entry.
+ */
+
+export type ChecklistViewProps = {
+  checklist: Checklist;
+  config?: ChecklistConfig;
+  /** User-authored and agent-authored rules in one list — provenance is the `author` field. */
+  rules?: ChecklistRule[];
+  /** The host's transport. Omit for local-only mode: changes apply and nothing can fail. */
+  operations?: ChecklistOperations;
+  /** The host's people lookup. Omit and every assignee renders as an unresolved reference. */
+  people?: PeopleAdapter;
+  capabilities?: ChecklistCapabilities;
+  /** A session fact, never document state (§10). */
+  sharedWith?: string[];
+  onChange?: (doc: Checklist, change: ChecklistChange) => void;
+  /** The developer harness's one read-only window. The component itself has no inspector. */
+  onRuntimeChange?: (state: ChecklistRuntimeState) => void;
+  testID?: string;
+};
+
+const HIT = 44;
+
+/* ── People ──────────────────────────────────────────────────────────────── */
+
+/**
+ * Resolve the ids the document names. An id the adapter does not return is **absent**, and the row
+ * says "Unknown person" rather than "Unassigned" — they are different facts, and this repo already
+ * draws that distinction ("an empty cell is said, not skipped").
+ */
+function usePeopleDirectory(people: PeopleAdapter | undefined, ids: string[]) {
+  const key = ids.join(',');
+  const [map, setMap] = useState<Map<string, Person>>(new Map());
+  useEffect(() => {
+    if (!people || !key) { setMap(new Map()); return; }
+    const controller = new AbortController();
+    let live = true;
+    people.resolve(key.split(','), { signal: controller.signal })
+      .then(found => { if (live) setMap(new Map(found.map(p => [p.id, p]))); })
+      .catch(() => { /* an unresolved directory is the "Unknown person" case, not an error state */ });
+    return () => { live = false; controller.abort(); };
+  }, [people, key]);
+  return map;
+}
+
+/* ── Small shared pieces ─────────────────────────────────────────────────── */
+
+/**
+ * **The row's small action** — Solarium's 28px ghost (`Button size="xsmall"`), or the one coral
+ * primary where a form commits (Save, Add, Share). 8px corners, never a pill (0.2.0).
+ */
+function SmallButton({
+  label, onPress, tone = 'quiet', ariaLabel, busy,
+}: { label: string; onPress: () => void; tone?: 'quiet' | 'accent'; ariaLabel?: string; busy?: boolean }) {
+  return (
+    <Button variant={tone === 'accent' ? 'primary' : 'secondary'} size="xsmall" busy={busy} onPress={onPress} aria-label={ariaLabel ?? label}>
+      {label}
+    </Button>
+  );
+}
+
+/**
+ * **A toggle the reader turns on and off** — a person to assign or share with, a share scope. A
+ * chip (the one place 0.2.0 keeps the pill: chips, bars, skeletons), `aria-pressed`, and — the
+ * current system's "selected" — a coral ring on the coral-soft ground, never a solid fill.
+ */
+function ToggleChip({ label, on, onPress, ariaLabel }: { label: string; on: boolean; onPress: () => void; ariaLabel?: string }) {
+  const { colors } = useDs();
+  return (
+    <Pressable
+      onPress={onPress} aria-pressed={on} aria-label={ariaLabel ?? label} minHeight={32} radius="pill"
+      style={{
+        paddingHorizontal: 12, backgroundColor: on ? colors.accentTint : colors.band,
+        borderWidth: 1.5, borderColor: on ? colors.accentFill : 'transparent',
+      }}>
+      <Text numberOfLines={1} style={{ fontSize: 12.5, fontWeight: '600', color: on ? colors.accentInk : colors.textPrimary }}>{label}</Text>
+    </Pressable>
+  );
+}
+
+/** A task's quiet state word — "Optional", "Skipped": 12px muted on the line-soft ground, a plain D1 chip. */
+function MetaWord({ children }: { children: string }) {
+  const { colors } = useDs();
+  return (
+    <Box row align="center" height={20} radius="pill" style={{ paddingHorizontal: 8, backgroundColor: colors.band }}>
+      <Text style={{ fontSize: 11.5, fontWeight: '600', color: colors.textSecondary }}>{children}</Text>
+    </Box>
+  );
+}
+
+/** The one failure construction, identical to the one `DirectoryView` draws (§16): an apricot Callout with its recovery. */
+function FailureBlock({
+  title, message, onRetry, onDismiss, nativeID,
+}: { title: string; message: string; onRetry?: () => void; onDismiss?: () => void; nativeID?: string }) {
+  return (
+    <Box nativeID={nativeID} role="group" aria-label={title}>
+      <Callout
+        title={title}
+        action={onRetry || onDismiss ? (
+          <Box row wrap style={{ gap: 8 }}>
+            {onRetry ? <SmallButton label="Try again" onPress={onRetry} /> : null}
+            {onDismiss ? <SmallButton label="Dismiss" onPress={onDismiss} /> : null}
+          </Box>
+        ) : undefined}>
+        <Text accessibilityLiveRegion="polite" style={{ fontSize: 12, lineHeight: 17 }}>{message}</Text>
+      </Callout>
+    </Box>
+  );
+}
+
+/**
+ * **A real checkbox** — `role="checkbox"` with `aria-checked`, named by the task's own title.
+ *
+ * A blocked one is *not* disabled: a disabled control tells a person they may not and never why.
+ * It stays pressable, carries the gate's reason as its accessible description, and pressing it
+ * produces that reason (§8).
+ */
+function TaskCheckbox({
+  task, view, onPress, describedBy, disabled,
+}: { task: ChecklistTask; view: TaskView; onPress: () => void; describedBy?: string; disabled?: boolean }) {
+  const { colors } = useDs();
+  const checked = view === 'done';
+  /* C1 (0.2.0): an 18px box, radius `--r-key` (4), a 1.5px rim — `controlBorder` off, coral on and
+     filled. Skipped is the line-soft ground with a muted dash; blocked stays pressable, dimmed. */
+  return (
+    <Pressable
+      onPress={onPress} disabled={disabled} hit={HIT} role="checkbox" aria-checked={checked}
+      aria-label={task.title} aria-describedby={describedBy}
+      style={{ alignItems: 'center', justifyContent: 'center' }}>
+      <Box
+        width={18} height={18} align="center" justify="center"
+        style={{
+          borderRadius: blockRadii.key, borderWidth: 1.5,
+          borderColor: checked ? colors.accentInk : view === 'skipped' ? colors.hairlineStrong : colors.controlBorder,
+          backgroundColor: checked ? colors.accentInk : view === 'skipped' ? colors.band : colors.surface1,
+          opacity: view === 'blocked' ? 0.55 : 1,
+        }}>
+        {checked ? <Icon name="tick" size={12} color={colors.accentOnFill} /> : null}
+        {view === 'skipped' ? <Icon name="minus" size={11} color={colors.textSecondary} /> : null}
+      </Box>
+    </Pressable>
+  );
+}
+
+/* ── The task row ────────────────────────────────────────────────────────── */
+
+type RowActions = {
+  onToggle: () => void;
+  onSkip: () => void;
+  onEdit: (title: string, description: string) => void;
+  onDelete: () => void;
+  onAssign: (assigneeId: string | null) => void;
+  onMove: (delta: number) => void;
+};
+
+function TaskRow({
+  task, checklist, rules, config, people, peopleMap, pending, actions, blockedMessage, onBlockedPress,
+  first, last, isEditing, onStartEdit, onStopEdit, onRetry, onDismiss,
+}: {
+  task: ChecklistTask; checklist: Checklist; rules: ChecklistRule[]; config: ChecklistConfig;
+  people?: PeopleAdapter; peopleMap: Map<string, Person>;
+  pending?: PendingChange; actions: RowActions;
+  blockedMessage: string | null; onBlockedPress: () => void;
+  first: boolean; last: boolean;
+  isEditing: boolean; onStartEdit: () => void; onStopEdit: () => void;
+  onRetry: () => void; onDismiss: () => void;
+}) {
+  const { colors } = useDs();
+  const view = taskViewOf(task, checklist, rules);
+  const [title, setTitle] = useState(task.title);
+  const [description, setDescription] = useState(task.description ?? '');
+  const [assignOpen, setAssignOpen] = useState(false);
+  const [candidates, setCandidates] = useState<Person[]>([]);
+
+  useEffect(() => { setTitle(task.title); setDescription(task.description ?? ''); }, [task.title, task.description]);
+
+  useEffect(() => {
+    if (!assignOpen || !people) return;
+    const controller = new AbortController();
+    let live = true;
+    people.search('', { signal: controller.signal })
+      .then(found => { if (live) setCandidates(found); })
+      .catch(() => { /* no candidates is a quiet empty list, not a failure block */ });
+    return () => { live = false; controller.abort(); };
+  }, [assignOpen, people]);
+
+  const noteId = `${task.id}-note`;
+  const person = task.assigneeId ? peopleMap.get(task.assigneeId) : undefined;
+  /* The difference the design insists on: nobody is on this, versus somebody is and we cannot
+     say who. Silence would merge the two. */
+  const assigneeLabel = !task.assigneeId ? null : (person?.name ?? 'Unknown person');
+
+  const commitEdit = () => {
+    const nextTitle = title.trim();
+    if (nextTitle && (nextTitle !== task.title || description !== (task.description ?? ''))) {
+      actions.onEdit(nextTitle, description);
+    }
+    onStopEdit();
+  };
+  const cancelEdit = () => { setTitle(task.title); setDescription(task.description ?? ''); onStopEdit(); };
+
+  return (
+    <Box
+      role="listitem"
+      style={{
+        paddingVertical: 8, gap: 6,
+        borderTopWidth: first ? 0 : 1, borderTopColor: colors.hairline,
+        /* A change in flight past the threshold reads as *quiet* activity — never a blocked row,
+           because the checkbox beside it must stay interactive (§16). */
+        opacity: pending?.status === 'pending' && pending.slow ? 0.72 : 1,
+      }}>
+      {/* Wraps rather than squeezes: at phone width the row's actions drop under the title instead
+          of crushing it to nothing. */}
+      <Box row wrap align="flex-start" style={{ gap: 10 }}>
+        <TaskCheckbox
+          task={task} view={view}
+          describedBy={blockedMessage ? noteId : undefined}
+          onPress={() => (blockedMessage ? onBlockedPress() : actions.onToggle())}
+          disabled={!config.can.complete}
+        />
+
+        <Box style={{ gap: 3, minWidth: 0, flexGrow: 1, flexShrink: 1, flexBasis: 170 }}>
+          {isEditing ? (
+            <Box style={{ gap: 6 }}>
+              <Input
+                value={title} onChangeText={setTitle} autoFocus aria-label="Task title"
+                onSubmit={commitEdit} onCancel={cancelEdit}
+              />
+              {config.taskDescriptions === 'shown' ? (
+                <Input
+                  value={description} onChangeText={setDescription} placeholder="Description"
+                  aria-label="Task description" onSubmit={commitEdit} onCancel={cancelEdit}
+                />
+              ) : null}
+              <Box row wrap style={{ gap: 8 }}>
+                <SmallButton label="Save" onPress={commitEdit} tone="accent" />
+                <SmallButton label="Cancel" onPress={cancelEdit} />
+              </Box>
+            </Box>
+          ) : (
+            <>
+              <Text
+                numberOfLines={3}
+                style={{
+                  fontSize: 13.5, lineHeight: 19, fontWeight: '600',
+                  color: view === 'done' || view === 'skipped' ? colors.textSecondary : colors.textPrimary,
+                  textDecorationLine: view === 'done' ? 'line-through' : 'none',
+                }}>
+                {task.title}
+              </Text>
+              {config.taskDescriptions === 'shown' && task.description ? (
+                <Text color="textSecondary" numberOfLines={3} style={{ fontSize: 12, lineHeight: 17 }}>
+                  {task.description}
+                </Text>
+              ) : null}
+              <Box row wrap align="center" style={{ gap: 6 }}>
+                {config.assignees !== 'hidden' && assigneeLabel ? (
+                  <Box row align="center" style={{ gap: 4 }}>
+                    <Icon name="user" size={12} color={colors.textSecondary} />
+                    <Text color="textSecondary" style={{ fontSize: 12, lineHeight: 16 }}>{assigneeLabel}</Text>
+                  </Box>
+                ) : null}
+                {task.required === false ? <MetaWord>Optional</MetaWord> : null}
+                {view === 'skipped' ? <MetaWord>Skipped</MetaWord> : null}
+              </Box>
+            </>
+          )}
+
+          {blockedMessage && !isEditing ? (
+            <Box row align="center" style={{ gap: 4 }}>
+              <Icon name="lock" size={12} color={colors.textSecondary} />
+              <Text nativeID={noteId} color="textSecondary" style={{ fontSize: 12, lineHeight: 16, flexShrink: 1 }}>
+                {blockedMessage}
+              </Text>
+            </Box>
+          ) : null}
+        </Box>
+
+        {!isEditing ? (
+          <Box row align="center" style={{ gap: 2, marginLeft: 'auto' }}>
+            {config.can.reorder ? (
+              <>
+                <Pressable onPress={() => actions.onMove(-1)} disabled={first} width={32} height={32} radius="pill" aria-label={`Move “${task.title}” up`}>
+                  <Icon name="chev-u" size={14} color={colors.textSecondary} />
+                </Pressable>
+                <Pressable onPress={() => actions.onMove(1)} disabled={last} width={32} height={32} radius="pill" aria-label={`Move “${task.title}” down`}>
+                  <Icon name="chev-d" size={14} color={colors.textSecondary} />
+                </Pressable>
+              </>
+            ) : null}
+            {config.assignees === 'editable' && config.can.assign ? (
+              <Pressable onPress={() => setAssignOpen(v => !v)} width={32} height={32} radius="pill" aria-label={`Assign “${task.title}”`} aria-expanded={assignOpen}>
+                <Icon name="more" size={15} color={colors.textSecondary} />
+              </Pressable>
+            ) : null}
+            {config.can.skip && view !== 'done' ? (
+              <Pressable onPress={actions.onSkip} width={32} height={32} radius="pill" aria-label={view === 'skipped' ? `Un-skip “${task.title}”` : `Skip “${task.title}”`}>
+                <Icon name="minus" size={15} color={colors.textSecondary} />
+              </Pressable>
+            ) : null}
+            {config.can.editTask ? (
+              <Pressable onPress={onStartEdit} width={32} height={32} radius="pill" aria-label={`Edit “${task.title}”`}>
+                <Icon name="edit" size={15} color={colors.textSecondary} />
+              </Pressable>
+            ) : null}
+            {config.can.deleteTask ? (
+              <Pressable onPress={actions.onDelete} width={32} height={32} radius="pill" aria-label={`Delete “${task.title}”`}>
+                <Icon name="trash" size={15} color={colors.textSecondary} />
+              </Pressable>
+            ) : null}
+          </Box>
+        ) : null}
+      </Box>
+
+      {assignOpen ? (
+        <Box row wrap align="center" style={{ gap: 6, paddingLeft: 28 }}>
+          {candidates.map(p => (
+            <ToggleChip
+              key={p.id} label={p.name} on={task.assigneeId === p.id} ariaLabel={`Assign to ${p.name}`}
+              onPress={() => { actions.onAssign(p.id); setAssignOpen(false); }}
+            />
+          ))}
+          {task.assigneeId ? (
+            <SmallButton label="Unassign" onPress={() => { actions.onAssign(null); setAssignOpen(false); }} />
+          ) : null}
+        </Box>
+      ) : null}
+
+      {pending?.status === 'error' ? (
+        <Box style={{ paddingLeft: 28 }}>
+          <FailureBlock title="Not saved" message="We could not save that." onRetry={onRetry} onDismiss={onDismiss} />
+        </Box>
+      ) : null}
+    </Box>
+  );
+}
+
+/* ── The view ────────────────────────────────────────────────────────────── */
+
+export function ChecklistView({
+  checklist, config: configProp, rules: rulesProp, operations, people, capabilities,
+  sharedWith, onChange, onRuntimeChange, testID,
+}: ChecklistViewProps) {
+  const { colors, lift1 } = useDs();
+  const { surface, onLayout } = useMeasuredSurface();
+  const config = useMemo(() => configProp ?? defaultChecklistConfig(), [configProp]);
+
+  const runtime = useChecklistRuntime({
+    checklist, config, rules: rulesProp, operations, capabilities, sharedWith, onChange,
+  });
+  const { state, rules, apply } = runtime;
+  const doc = state.doc;
+
+  useEffect(() => { onRuntimeChange?.(state); }, [state, onRuntimeChange]);
+
+  const configErrors = useMemo(
+    () => validateChecklistConfig(config, { checklist: doc, rules, capabilities }),
+    [config, doc, rules, capabilities],
+  );
+
+  const assigneeIds = useMemo(
+    () => [...new Set(doc.sections.flatMap(s => s.tasks.map(t => t.assigneeId).filter((x): x is string => !!x)))].sort(),
+    [doc],
+  );
+  const peopleMap = usePeopleDirectory(people, assigneeIds);
+
+  const [editingTaskId, setEditingTaskId] = useState<string | null>(null);
+  const [editingSectionId, setEditingSectionId] = useState<string | null>(null);
+  const [sectionDraft, setSectionDraft] = useState('');
+  const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
+  const [addingIn, setAddingIn] = useState<string | null>(null);
+  const [taskDraft, setTaskDraft] = useState('');
+  const [addingSection, setAddingSection] = useState(false);
+  const [newSectionTitle, setNewSectionTitle] = useState('');
+  const [blocked, setBlocked] = useState<{ taskId: string; message: string } | null>(null);
+  const [shareOpen, setShareOpen] = useState(false);
+  const [recipients, setRecipients] = useState<string[]>([]);
+  const [shareCandidates, setShareCandidates] = useState<Person[]>([]);
+  /** `own` shares each person only the tasks assigned to them — one request per recipient. */
+  const [shareScope, setShareScope] = useState<'checklist' | 'own'>('checklist');
+  const [editingMeta, setEditingMeta] = useState(false);
+  const [titleDraft, setTitleDraft] = useState('');
+  const [descDraft, setDescDraft] = useState('');
+
+  /* Ids for tasks and sections a person creates. Monotonic per view, never `Date.now()` — the
+     same determinism rule the rest of the family follows. */
+  const seq = useRef(0);
+  const newId = (kind: 'task' | 'section') => { seq.current += 1; return `${kind}-${doc.id}-${seq.current}`; };
+
+  useEffect(() => {
+    if (!shareOpen || !people) return;
+    const controller = new AbortController();
+    let live = true;
+    people.search('', { signal: controller.signal })
+      .then(found => { if (live) setShareCandidates(found); })
+      .catch(() => { /* an empty picker, not a failure */ });
+    return () => { live = false; controller.abort(); };
+  }, [shareOpen, people]);
+
+  const progress = progressOf(doc);
+  /** The tasks a given person is assigned, in document order. Derived, never stored. */
+  const tasksFor = (personId: string) =>
+    doc.sections.flatMap(s => s.tasks).filter(t => t.assigneeId === personId);
+  const pendingFor = useCallback(
+    (taskId: string) => state.pending.find(p => 'taskId' in p.change && p.change.taskId === taskId),
+    [state.pending],
+  );
+
+  const attempt = useCallback((body: Parameters<typeof apply>[0]) => {
+    const rejection = apply(body);
+    if (rejection?.reason === 'blocked' && 'taskId' in body) {
+      setBlocked({ taskId: body.taskId as string, message: rejection.message });
+    }
+    return rejection;
+  }, [apply]);
+
+  /* Metadata goes through the SAME pipeline as every other edit: a change, an inverse, the
+     runtime. The builder never writes `title` into React state behind the engine's back. */
+  function commitMeta() {
+    const title = titleDraft.trim();
+    const description = descDraft.trim();
+    if (title && title !== doc.title) attempt({ kind: 'checklist.edit', title });
+    if (description !== (doc.description ?? '')) attempt({ kind: 'checklist.edit', description });
+    setEditingMeta(false);
+  }
+  function cancelMeta() { setEditingMeta(false); }
+
+  if (configErrors.length) {
+    /* A configuration that contradicts itself is shown as a configuration problem, never as a
+       checklist that quietly behaves differently than it was set up to. */
+    return (
+      <Box testID={testID} style={{ borderRadius: blockRadii.major, borderWidth: 1, borderColor: colors.hairline, backgroundColor: colors.surface1, padding: 20 }}>
+        <Callout title="Configuration">
+          {configErrors.join('\n')}
+        </Callout>
+      </Box>
+    );
+  }
+
+  const countLabel = progress.total === 0
+    ? config.copy.emptyLabel
+    : progress.complete ? config.copy.allDoneLabel
+    : `${progress.requiredDone} of ${progress.required} done`;
+
+  const renderTasks = (section: ChecklistSection) => (
+    <Box role="list">
+      {section.tasks.map((task, i) => {
+        const gates = unsatisfiedGates(task.id, doc, rules);
+        const gateNote = gates.length ? gateMessage(gates[0]!, doc) : null;
+        const shown = blocked?.taskId === task.id ? blocked.message : gateNote;
+        return (
+          <TaskRow
+            key={task.id}
+            task={task} checklist={doc} rules={rules} config={config}
+            people={people} peopleMap={peopleMap}
+            pending={pendingFor(task.id)}
+            blockedMessage={shown}
+            onBlockedPress={() => attempt({ kind: 'task.complete', taskId: task.id, done: true })}
+            first={i === 0} last={i === section.tasks.length - 1}
+            isEditing={editingTaskId === task.id}
+            onStartEdit={() => setEditingTaskId(task.id)}
+            onStopEdit={() => setEditingTaskId(null)}
+            onRetry={() => { const p = pendingFor(task.id); if (p) runtime.retry(p.change.id); }}
+            onDismiss={() => { const p = pendingFor(task.id); if (p) runtime.dismiss(p.change.id); }}
+            actions={{
+              onToggle: () => { setBlocked(null); attempt({ kind: 'task.complete', taskId: task.id, done: !task.done }); },
+              onSkip: () => attempt({ kind: 'task.skip', taskId: task.id, skipped: !task.skipped }),
+              onEdit: (title, description) => attempt({ kind: 'task.edit', taskId: task.id, title, description }),
+              onDelete: () => attempt({ kind: 'task.delete', taskId: task.id }),
+              onAssign: assigneeId => attempt({ kind: 'task.assign', taskId: task.id, assigneeId }),
+              onMove: delta => attempt({ kind: 'task.move', taskId: task.id, toSectionId: section.id, toIndex: i + delta }),
+            }}
+          />
+        );
+      })}
+    </Box>
+  );
+
+  const addTaskRow = (section: ChecklistSection) => {
+    if (!config.can.addTask) return null;
+    const commit = () => {
+      const title = taskDraft.trim();
+      if (title) {
+        attempt({
+          kind: 'task.add', sectionId: section.id, index: section.tasks.length,
+          task: { id: newId('task'), title, done: false },
+        });
+      }
+      setTaskDraft(''); setAddingIn(null);
+    };
+    return addingIn === section.id ? (
+      <Box style={{ gap: 6, paddingTop: 8 }}>
+        <Input
+          value={taskDraft} onChangeText={setTaskDraft} autoFocus
+          placeholder={config.copy.addTaskLabel} aria-label={config.copy.addTaskLabel}
+          onSubmit={commit} onCancel={() => { setTaskDraft(''); setAddingIn(null); }}
+        />
+        <Box row wrap style={{ gap: 8 }}>
+          <SmallButton label="Add" onPress={commit} tone="accent" />
+          <SmallButton label="Cancel" onPress={() => { setTaskDraft(''); setAddingIn(null); }} />
+        </Box>
+      </Box>
+    ) : (
+      <Box style={{ paddingTop: 8 }}>
+        <SmallButton
+          label={`+ ${config.copy.addTaskLabel}`}
+          ariaLabel={section.title ? `${config.copy.addTaskLabel} in ${section.title}` : config.copy.addTaskLabel}
+          onPress={() => { setTaskDraft(''); setAddingIn(section.id); }}
+        />
+      </Box>
+    );
+  };
+
+  const shareButton = (
+    <SmallButton
+      label={state.share.status === 'pending' ? 'Sharing…' : `Share with ${recipients.length}`}
+      tone="accent"
+      busy={state.share.status === 'pending'}
+      onPress={() => {
+        if (!recipients.length) return;
+        if (shareScope === 'checklist') {
+          runtime.share({ scope: { kind: 'checklist' }, recipients });
+          return;
+        }
+        /* One request per recipient, each scoped to that person's own tasks — contract-compatible,
+           because a ShareRequest carries one taskIds[] for all of its recipients. A person with
+           nothing assigned is not sent an empty share. */
+        const reqs: ShareRequest[] = recipients
+          .map(id => ({ scope: { kind: 'tasks' as const, taskIds: tasksFor(id).map(t => t.id) }, recipients: [id] }))
+          .filter(r => r.scope.taskIds.length > 0);
+        if (reqs.length) runtime.shareEach(reqs);
+      }}
+    />
+  );
+
+  /* The current card shell (S1, Solarium 0.2.0): 16px corners, a 1px line-soft edge, lift-1; a
+     header at 18/20/16 over a line-soft rule; the body at 16/20. The same metrics `BlockCard` draws —
+     the header is drawn here rather than through `BlockCard` because it edits in place. */
+  return (
+    <SurfaceProvider surface={surface}>
+      <Box onLayout={onLayout} style={{ width: '100%' }}>
+        <Box
+          bg="surface1" testID={testID}
+          style={{ overflow: 'hidden', width: '100%', borderRadius: blockRadii.major, borderWidth: 1, borderColor: colors.hairline, boxShadow: lift1 }}>
+          {/* ── Header ── */}
+          <Box style={{ paddingTop: 18, paddingHorizontal: 20, paddingBottom: 16, gap: 10, borderBottomWidth: 1, borderBottomColor: colors.hairline }}>
+            <Box row align="flex-start" style={{ gap: 10 }}>
+              <Box flex={1} style={{ minWidth: 0, gap: 2 }}>
+                {editingMeta ? (
+                  <Box style={{ gap: 8 }}>
+                    <Input
+                      value={titleDraft} onChangeText={setTitleDraft} autoFocus aria-label="Checklist title"
+                      placeholder="Checklist title" onSubmit={commitMeta} onCancel={cancelMeta}
+                    />
+                    {config.showDescription ? (
+                      <Input
+                        value={descDraft} onChangeText={setDescDraft} placeholder="Description"
+                        aria-label="Checklist description" onSubmit={commitMeta} onCancel={cancelMeta}
+                      />
+                    ) : null}
+                    <Box row wrap style={{ gap: 8 }}>
+                      <SmallButton label="Save" onPress={commitMeta} tone="accent" />
+                      <SmallButton label="Cancel" onPress={cancelMeta} />
+                    </Box>
+                  </Box>
+                ) : (
+                  <>
+                    {/* Level 2, not 1: a Checklist is a card placed inside a page that owns the
+                        document's only <h1>. Without an explicit level every heading here renders
+                        as <h1> and the page's outline collapses — see `Text`'s `aria-level` note. */}
+                    <Text role="heading" aria-level={2} numberOfLines={2}
+                      style={{ fontSize: 14, lineHeight: 19, fontWeight: '600', letterSpacing: -0.21, color: doc.title ? colors.textPrimary : colors.textSecondary }}>
+                      {doc.title || 'Untitled checklist'}
+                    </Text>
+                    {config.showDescription && doc.description ? (
+                      <Text color="textSecondary" numberOfLines={3} style={{ fontSize: 12, lineHeight: 17 }}>
+                        {doc.description}
+                      </Text>
+                    ) : null}
+                  </>
+                )}
+              </Box>
+              {config.can.editChecklist && !editingMeta ? (
+                <Pressable
+                  onPress={() => { setTitleDraft(doc.title); setDescDraft(doc.description ?? ''); setEditingMeta(true); }}
+                  width={32} height={32} radius="pill" aria-label="Edit checklist title and description">
+                  <Icon name="edit" size={15} color={colors.textSecondary} />
+                </Pressable>
+              ) : null}
+              {config.sharing.enabled ? (
+                <Button
+                  variant="secondary" size="xsmall" leadingGlyph={state.share.status === 'ok' ? 'check' : 'share'}
+                  aria-label={state.share.status === 'ok' ? 'Shared' : 'Share'}
+                  aria-expanded={shareOpen}
+                  onPress={() => setShareOpen(v => !v)}>
+                  {state.share.status === 'ok' ? 'Shared' : 'Share'}
+                </Button>
+              ) : null}
+            </Box>
+
+            {/* Derived, never stored (§15), and subordinate to the title: a 12px count and a neutral
+                ink bar — progress is never hue-coded in this system. */}
+            {config.progress !== 'none' && progress.total > 0 ? (
+              <Box style={{ gap: 6 }}>
+                {config.progress === 'count' || config.progress === 'both' ? (
+                  <Text accessibilityLiveRegion="polite" color="textSecondary" numeric style={{ fontSize: 12, lineHeight: 16 }}>
+                    {countLabel}
+                  </Text>
+                ) : null}
+                {config.progress === 'bar' || config.progress === 'both' ? (
+                  <ProgressBar bare tone="ink" height={6} label={countLabel} value={Math.round(progress.fraction * 100)} max={100} format={() => countLabel} />
+                ) : null}
+              </Box>
+            ) : null}
+
+            {shareOpen && config.sharing.enabled ? (
+              <Box style={{ gap: 10, paddingTop: 12, borderTopWidth: 1, borderTopColor: colors.hairline }}>
+                <Text style={{ fontSize: 12, fontWeight: '600' }} color="textPrimary">Share with</Text>
+                <Box row wrap style={{ gap: 6 }}>
+                  {shareCandidates.map(p => {
+                    const on = recipients.includes(p.id);
+                    return (
+                      <ToggleChip
+                        key={p.id} label={p.name} on={on} ariaLabel={`Share with ${p.name}`}
+                        onPress={() => setRecipients(prev => (on ? prev.filter(x => x !== p.id) : [...prev, p.id]))}
+                      />
+                    );
+                  })}
+                </Box>
+                <Box row wrap align="center" style={{ gap: 6 }}>
+                  <Text color="textSecondary" style={{ fontSize: 12, lineHeight: 16 }}>Share</Text>
+                  {([['checklist', 'The whole checklist'], ['own', 'Each person’s own tasks']] as const).map(([id, label]) => (
+                    <ToggleChip key={id} label={label} on={shareScope === id} onPress={() => setShareScope(id)} />
+                  ))}
+                </Box>
+
+                {/* Who gets what, said before it is sent — the whole point of per-recipient scope. */}
+                {shareScope === 'own' && recipients.length ? (
+                  <Box style={{ gap: 3 }}>
+                    {recipients.map(id => {
+                      const person = shareCandidates.find(p => p.id === id);
+                      const theirs = tasksFor(id);
+                      return (
+                        <Text key={id} color="textSecondary" style={{ fontSize: 12, lineHeight: 16 }}>
+                          {theirs.length
+                            ? `${person?.name ?? 'Unknown person'} · ${theirs.map(t => t.title).join(', ')}`
+                            : `${person?.name ?? 'Unknown person'} · no tasks assigned`}
+                        </Text>
+                      );
+                    })}
+                  </Box>
+                ) : null}
+
+                <Box row wrap align="center" style={{ gap: 8 }}>
+                  {shareButton}
+                  {state.share.status === 'ok' && state.share.result ? (
+                    <Box row align="center" style={{ gap: 4, flexShrink: 1 }}>
+                      <Icon name="check" size={13} color={colors.status.executed} />
+                      <Text accessibilityLiveRegion="polite" style={{ fontSize: 12, lineHeight: 16, color: colors.status.executed, flexShrink: 1 }}>
+                        {`Shared with ${state.share.result.sharedWith
+                          .map(id => shareCandidates.find(p => p.id === id)?.name ?? 'Unknown person').join(', ')}`}
+                      </Text>
+                    </Box>
+                  ) : null}
+                </Box>
+                {state.share.status === 'error' ? (
+                  <FailureBlock
+                    title="Not shared" message="We could not share this."
+                    onRetry={runtime.retryShare} onDismiss={runtime.dismissShare}
+                  />
+                ) : null}
+              </Box>
+            ) : null}
+
+            {state.effects.some(e => e.status === 'error') ? (
+              <FailureBlock
+                title="Not notified"
+                message="We could not let everyone know."
+                onRetry={() => {
+                  const failed = state.effects.find(e => e.status === 'error');
+                  if (failed) runtime.retryEffect(failed.effect.id);
+                }}
+              />
+            ) : null}
+          </Box>
+
+          {/* ── Body ── */}
+          <Box style={{ paddingVertical: 16, paddingHorizontal: 20, gap: 16 }}>
+            {progress.total === 0 && doc.sections.every(s => s.tasks.length === 0) && !addingIn ? (
+              <Text color="textSecondary" style={{ fontSize: 13, lineHeight: 18 }}>{config.copy.emptyLabel}</Text>
+            ) : null}
+
+            {doc.sections.map((section, si) => {
+              const grouped = config.sections === 'grouped' && !!section.title;
+              const isCollapsed = config.collapsibleSections && collapsed.has(section.id);
+              const sp = sectionProgressOf(section);
+              const bodyId = `${section.id}-tasks`;
+              return (
+                <Box key={section.id} role="group" aria-label={section.title ?? doc.title} style={{ gap: 2 }}>
+                  {grouped ? (
+                    <Box row wrap align="center" style={{ gap: 6, minHeight: 36 }}>
+                      {config.collapsibleSections ? (
+                        <Pressable
+                          onPress={() => setCollapsed(prev => {
+                            const next = new Set(prev);
+                            if (next.has(section.id)) next.delete(section.id); else next.add(section.id);
+                            return next;
+                          })}
+                          width={32} height={32} radius="pill" aria-label={section.title ?? 'Section'}
+                          aria-expanded={!isCollapsed} aria-controls={bodyId}>
+                          <Icon name={isCollapsed ? 'chev-r' : 'chev-d'} size={14} color={colors.textSecondary} />
+                        </Pressable>
+                      ) : null}
+                      <Box style={{ minWidth: 0, flexGrow: 1, flexShrink: 1, flexBasis: 80 }}>
+                        {editingSectionId === section.id ? (
+                          <Input
+                            value={sectionDraft} onChangeText={setSectionDraft} autoFocus aria-label="Section title"
+                            onSubmit={() => {
+                              const t = sectionDraft.trim();
+                              if (t) attempt({ kind: 'section.edit', sectionId: section.id, title: t });
+                              setEditingSectionId(null);
+                            }}
+                            onCancel={() => setEditingSectionId(null)}
+                          />
+                        ) : (
+                          <Text role="heading" aria-level={3} numberOfLines={1} style={{ fontSize: 12, lineHeight: 16, fontWeight: '600', color: colors.textPrimary }}>
+                            {section.title}
+                          </Text>
+                        )}
+                      </Box>
+                      <Text numeric color="textSecondary" style={{ fontSize: 12, lineHeight: 16 }}>
+                        {`${sp.done}/${sp.total}`}
+                      </Text>
+                      {config.can.editSection && editingSectionId !== section.id ? (
+                        <Pressable
+                          onPress={() => { setSectionDraft(section.title ?? ''); setEditingSectionId(section.id); }}
+                          width={32} height={32} radius="pill" aria-label={`Edit section “${section.title}”`}>
+                          <Icon name="edit" size={14} color={colors.textSecondary} />
+                        </Pressable>
+                      ) : null}
+                      {config.can.reorder ? (
+                        <Pressable
+                          onPress={() => attempt({ kind: 'section.move', sectionId: section.id, toIndex: si - 1 })}
+                          disabled={si === 0} width={32} height={32} radius="pill" aria-label={`Move section “${section.title}” up`}>
+                          <Icon name="chev-u" size={14} color={colors.textSecondary} />
+                        </Pressable>
+                      ) : null}
+                      {config.can.deleteSection ? (
+                        <Pressable
+                          onPress={() => attempt({ kind: 'section.delete', sectionId: section.id })}
+                          width={32} height={32} radius="pill" aria-label={`Delete section “${section.title}”`}>
+                          <Icon name="trash" size={14} color={colors.textSecondary} />
+                        </Pressable>
+                      ) : null}
+                    </Box>
+                  ) : null}
+
+                  {!isCollapsed ? (
+                    <Box nativeID={bodyId}>
+                      {renderTasks(section)}
+                      {addTaskRow(section)}
+                    </Box>
+                  ) : null}
+                </Box>
+              );
+            })}
+
+            {config.can.addSection ? (
+              addingSection ? (
+                <Box style={{ gap: 8 }}>
+                  <Input
+                    value={newSectionTitle} onChangeText={setNewSectionTitle} autoFocus
+                    placeholder={config.copy.addSectionLabel} aria-label={config.copy.addSectionLabel}
+                    onSubmit={() => {
+                      const t = newSectionTitle.trim();
+                      if (t) attempt({ kind: 'section.add', index: doc.sections.length, section: { id: newId('section'), title: t, tasks: [] } });
+                      setNewSectionTitle(''); setAddingSection(false);
+                    }}
+                    onCancel={() => { setNewSectionTitle(''); setAddingSection(false); }}
+                  />
+                  <Box row wrap style={{ gap: 8 }}>
+                    <SmallButton
+                      label="Add" tone="accent"
+                      onPress={() => {
+                        const t = newSectionTitle.trim();
+                        if (t) attempt({ kind: 'section.add', index: doc.sections.length, section: { id: newId('section'), title: t, tasks: [] } });
+                        setNewSectionTitle(''); setAddingSection(false);
+                      }}
+                    />
+                    <SmallButton label="Cancel" onPress={() => { setNewSectionTitle(''); setAddingSection(false); }} />
+                  </Box>
+                </Box>
+              ) : (
+                <SmallButton label={`+ ${config.copy.addSectionLabel}`} onPress={() => setAddingSection(true)} />
+              )
+            ) : null}
+          </Box>
+        </Box>
+      </Box>
+    </SurfaceProvider>
+  );
+}