@appinternalleads/ui 0.2.0

package/src/components/onboarding/data-view/runtime.ts

@@ -0,0 +1,254 @@
+import { useCallback, useEffect, useMemo } from 'react';
+import { useBlockMotion } from '../../../core';
+import { abortableDelay, useOperationRunner } from '../../../runtime/operations';
+import type { OnboardingResult } from '../shared/contract';
+import { useSeededReducer } from '../shared/runtime';
+import type { ComboboxOperations } from '../combobox/runtime';
+import type { ComboboxSettings } from '../combobox/contract';
+import { DATA_VIEW_TIMING, type BulkAction, type DataRow, type DataViewSettings, type Person, type SortKey } from './contract';
+import {
+  createDemoServer, peopleOf, type BulkOperation, type PageOperation, type SearchOperation, type SuggestOperation,
+} from './demoSource';
+import {
+  assignedText, cycleSort, dataViewModel, demoFirstPage, initialDataView, mergedRow, reduceDataView,
+  type DataToast, type DataViewAction, type DataViewSeed, type DataViewState, type Overlay,
+} from './engine';
+import { countNoun, dataViewToText } from './registry';
+
+/**
+ * **What a host implements** — the server side of the data view (README `DataViewProps`, as
+ * boundary operations): the next page under a sort, a bulk action, and C14's people search.
+ */
+export type DataViewOperations = {
+  page: PageOperation;
+  bulk: BulkOperation;
+  searchPeople: SearchOperation;
+  suggestPeople: SuggestOperation;
+};
+
+/** The host's first page — rows, the next cursor, the total. Without it the view fetches one. */
+export type DataViewPage = { rows: DataRow[]; cursor: string | null; totalCount: number };
+
+export type DataViewEvents = {
+  onOpen?: (id: string) => void;
+  onSortChange?: (sort: SortKey[]) => void;
+  onSelectionChange?: (ids: string[]) => void;
+  onBulk?: (action: BulkAction, ids: string[], arg?: unknown) => void;
+};
+
+let toastSeq = 100;
+const toast = (tone: DataToast['tone'], text: string, retry?: 'delete'): DataToast => ({ id: ++toastSeq, tone, text, retry });
+
+/**
+ * **The data-view runtime** — the engine, the host's operations (or the demo server), the C14
+ * wiring for Assign, the Export modal's close and "Copy as text". Table and Grid call this once
+ * and draw its result.
+ */
+export function useDataView({
+  config, operations, data, result = 'success', initial, onOpen, onSortChange, onSelectionChange, onBulk,
+}: {
+  config: DataViewSettings;
+  operations?: Partial<DataViewOperations>;
+  data?: DataViewPage;
+  result?: OnboardingResult;
+  initial?: DataViewSeed;
+} & DataViewEvents) {
+  const m = useBlockMotion();
+  const configKey = JSON.stringify(config);
+  /* The demo server stands in for whatever the host did not supply. */
+  const server = useMemo(() => createDemoServer(config, { result }), [configKey, result]);
+  const ops: DataViewOperations = {
+    page: operations?.page ?? server.page,
+    bulk: operations?.bulk ?? server.bulk,
+    searchPeople: operations?.searchPeople ?? server.searchPeople,
+    suggestPeople: operations?.suggestPeople ?? server.suggestPeople,
+  };
+  const hostPaged = Boolean(operations?.page);
+  const runner = useOperationRunner();
+  const key = JSON.stringify([configKey, initial ?? null, data ?? null]);
+  const seed = (): DataViewState => {
+    const first = initial?.rows
+      ? { rows: initial.rows, cursor: initial.cursor ?? null, total: initial.total ?? initial.rows.length }
+      : data ? { rows: data.rows, cursor: data.cursor, total: data.totalCount }
+      : hostPaged ? { rows: [], cursor: null, total: 0 }
+      : demoFirstPage(config);
+    const s = initialDataView(config, first, initial);
+    /* A host that pages but gave no first page: fetch it (the body shows the skeleton meanwhile). */
+    return !initial?.rows && !data && hostPaged ? { ...s, pend: s.sort } : s;
+  };
+  const [state, send, ref] = useSeededReducer<DataViewState, DataViewAction>(reduceDataView, seed, key, () => runner.abortAll());
+  const model = dataViewModel(config, state);
+
+  const runSort = useCallback((next: SortKey[]) => {
+    runner.run('page', ctx => ops.page({ sort: next, cursor: null, pageSize: config.pageSize }, ctx), {
+      onOk: r => send(r.ok ? { type: 'sorted', sort: next, rows: r.rows, cursor: r.cursor, total: r.totalCount } : { type: 'sortFailed' }),
+      onError: () => send({ type: 'sortFailed' }),
+    });
+  }, [runner, ops.page, config.pageSize]);
+
+  const runMore = useCallback(() => {
+    const s = ref.current;
+    runner.run('page', ctx => ops.page({ sort: s.sort, cursor: s.cursor, pageSize: config.pageSize }, ctx), {
+      onOk: r => send(r.ok ? { type: 'moreDone', rows: r.rows, cursor: r.cursor, total: r.totalCount, fresh: !m.reduced } : { type: 'moreFailed' }),
+      onError: () => send({ type: 'moreFailed' }),
+    });
+  }, [runner, ops.page, config.pageSize, m.reduced]);
+
+  const runDelete = useCallback(() => {
+    const ids = ref.current.sel.slice();
+    const n = ids.length;
+    runner.run('bulk', ctx => ops.bulk({ action: 'delete', ids }, ctx), {
+      onOk: r => {
+        if (!r.ok) { send({ type: 'deleteFailed', toast: toast('apricot', `Couldn’t delete ${countNoun(n, config.noun, config.nouns)}`, 'delete') }); return; }
+        send({ type: 'deleteDone', ids, animate: !m.reduced, toast: toast('neutral', `${countNoun(n, config.noun, config.nouns)} deleted`) });
+        onBulk?.('delete', ids);
+        if (!m.reduced) setTimeout(() => send({ type: 'deleteGone', ids }), DATA_VIEW_TIMING.leave);
+      },
+      onError: () => send({ type: 'deleteFailed', toast: toast('apricot', `Couldn’t delete ${countNoun(n, config.noun, config.nouns)}`, 'delete') }),
+    });
+  }, [runner, ops.bulk, config.noun, config.nouns, m.reduced, onBulk]);
+
+  /* A restored scene finishes what it was doing: a sort, a page, a delete in flight. */
+  useEffect(() => {
+    const s = ref.current;
+    if (s.pend) runSort(s.pend);
+    if (s.more === 'loading') runMore();
+    if (s.bulk === 'deleting') runDelete();
+  }, [key]);
+
+  /* Appended rows fade in once; afterwards they are ordinary rows. */
+  useEffect(() => {
+    if (state.fresh === null) return undefined;
+    const t = setTimeout(() => send({ type: 'freshDone' }), 300);
+    return () => clearTimeout(t);
+  }, [state.fresh]);
+
+  /* A toast without an action dismisses itself after 6s. */
+  const autoToast = state.toast && !state.toast.retry ? state.toast.id : null;
+  useEffect(() => {
+    if (autoToast === null) return undefined;
+    const t = setTimeout(() => send({ type: 'dropToast', id: autoToast }), DATA_VIEW_TIMING.toast);
+    return () => clearTimeout(t);
+  }, [autoToast]);
+
+  const selKey = state.sel.join(',');
+  useEffect(() => { onSelectionChange?.(ref.current.sel); }, [selKey]);
+
+  /* ── C14 for Assign: search and suggest are the host's; apply is the bulk `assign`. ───────── */
+  const people = useMemo(() => peopleOf(config), [configKey]);
+  const comboConfig: ComboboxSettings = {
+    people,
+    value: [],
+    suggestions: people.slice(0, 5).map(p => p.id),
+    fieldLabel: 'Assign',
+    emptyLabel: 'Assign to…',
+    dialogLabel: model.assignTitle,
+    sheetTitle: model.assignTitle,
+    placeholder: 'Search people',
+    applyLabel: model.applyLabel,
+    max: 0,
+    demoQuery: 'ay',
+    noMatchQuery: 'zoe',
+    viewport: 'web',
+    openDraft: null,
+    loadErrorTitle: config.loadErrorTitle,
+    loadErrorBody: config.loadErrorBody,
+    retryLabel: config.retryLabel,
+    emptyCta: config.emptyCta,
+  };
+  const comboOps = useMemo<ComboboxOperations>(() => ({
+    search: ops.searchPeople,
+    suggest: ops.suggestPeople,
+    apply: async (req, ctx) => {
+      const ids = ref.current.sel.slice();
+      if (!operations?.bulk) {
+        /* The demo: C14's apply (900ms; with result=error the first one fails), then the server's write. */
+        const r = await server.apply(req, ctx);
+        if (!r.ok) return r;
+      }
+      return ops.bulk({ action: 'assign', ids, people: req.people }, ctx);
+    },
+  }), [server, operations?.bulk, operations?.searchPeople, operations?.suggestPeople]);
+
+  const assigned = (ppl: Person[]) => {
+    const ids = ref.current.sel.slice();
+    send({ type: 'assigned', ids, col: config.assignCol, names: ppl.map(p => p.name), toast: toast('mint', assignedText(config, ids.length, ppl)) });
+    onBulk?.('assign', ids, ppl);
+  };
+
+  const visibleRows = state.rows.map(r => mergedRow(state, r));
+
+  return {
+    state,
+    model,
+    rows: visibleRows,
+    comboConfig,
+    comboOps,
+    assigned,
+    sort: (id: string, add: boolean) => {
+      const s = ref.current;
+      const next = cycleSort(s.pend ?? s.sort, id, add);
+      send({ type: 'sortRequest', sort: next });
+      onSortChange?.(next);
+      runSort(next);
+    },
+    setSort: (next: SortKey[]) => {
+      send({ type: 'sortRequest', sort: next });
+      onSortChange?.(next);
+      runSort(next);
+    },
+    loadMore: () => {
+      const s = ref.current;
+      if (s.more === 'loading' || s.pend || !s.cursor) return;
+      send({ type: 'moreStart' });
+      runMore();
+    },
+    toggle: (id: string) => send({ type: 'toggle', id }),
+    toggleAll: () => send({ type: 'toggleAll', ids: ref.current.rows.map(r => r.id) }),
+    clearSel: () => send({ type: 'clearSel' }),
+    overlay: (o: Overlay) => send({ type: 'overlay', overlay: o }),
+    deleteNow: () => {
+      if (ref.current.bulk === 'deleting') return;
+      send({ type: 'deleteStart' });
+      runDelete();
+    },
+    open: (id: string, title: string) => {
+      send({ type: 'toast', toast: toast('neutral', `Opened ${title}`) });
+      onOpen?.(id);
+    },
+    dropToast: () => { const t = ref.current.toast; if (t) send({ type: 'dropToast', id: t.id }); },
+    toastAction: () => {
+      const t = ref.current.toast;
+      if (!t) return;
+      send({ type: 'dropToast', id: t.id });
+      if (t.retry === 'delete') { send({ type: 'deleteStart' }); runDelete(); }
+    },
+    /** Export Format reported `exported`: the modal closes after 700ms and a mint toast confirms. */
+    exported: () => {
+      setTimeout(() => {
+        const ids = ref.current.sel.slice();
+        send({ type: 'overlay', overlay: null });
+        send({ type: 'toast', toast: toast('mint', `Exported ${countNoun(ids.length, config.noun, config.nouns)}`) });
+        onBulk?.('export', ids);
+      }, DATA_VIEW_TIMING.exportClose);
+    },
+    copy: async (onCopy?: (text: string) => void | Promise<void>) => {
+      const s = ref.current;
+      const text = dataViewToText(config, s.rows.map(r => mergedRow(s, r)), s.total);
+      const clip = (globalThis as { navigator?: { clipboard?: { writeText: (t: string) => Promise<void> } } }).navigator?.clipboard;
+      try {
+        if (onCopy) await onCopy(text);
+        else await clip?.writeText(text);
+      } catch {
+        return;
+      }
+      send({ type: 'copied', on: true });
+      runner.run('copied', ctx => abortableDelay(DATA_VIEW_TIMING.copied, ctx.signal), {
+        onOk: () => send({ type: 'copied', on: false }),
+        onError: () => send({ type: 'copied', on: false }),
+      });
+    },
+  };
+}
+
+export type DataViewApi = ReturnType<typeof useDataView>;

package/src/components/onboarding/data-view/validate.ts

@@ -0,0 +1,19 @@
+import type { OnboardingIssue } from '../shared/contract';
+import type { DataViewSettings } from './contract';
+
+/** A data view refuses a config it cannot draw, and says why. */
+export function validateDataView(c: DataViewSettings): OnboardingIssue[] {
+  if (!Array.isArray(c.columns) || !c.columns.length) return [{ path: 'columns', message: 'columns must list at least one column (the first is the title).' }];
+  const issues: OnboardingIssue[] = [];
+  const ids = new Set<string>();
+  c.columns.forEach((col, i) => {
+    if (!col.id || !col.label) issues.push({ path: `columns[${i}]`, message: 'Every column needs an id and a label.' });
+    if (ids.has(col.id)) issues.push({ path: `columns[${i}].id`, message: `The id “${col.id}” is used twice.` });
+    ids.add(col.id);
+  });
+  (c.sort ?? []).forEach((k, i) => { if (!ids.has(k.id)) issues.push({ path: `sort[${i}].id`, message: `“${k.id}” is not a column.` }); });
+  if (c.assignCol && !ids.has(c.assignCol)) issues.push({ path: 'assignCol', message: `“${c.assignCol}” is not a column.` });
+  if (!(c.pageSize > 0)) issues.push({ path: 'pageSize', message: 'pageSize must be 1 or more.' });
+  if (!c.noun || !c.nouns) issues.push({ path: 'noun', message: 'noun and nouns name the rows in every line of copy.' });
+  return issues;
+}

package/src/components/onboarding/department-setup/DepartmentSetupView.tsx

@@ -0,0 +1,221 @@
+import { useEffect, useRef } from 'react';
+import type { TextInput } from 'react-native';
+import { Box, Input, Icon, MotionView, Pressable, Text, useBlockMotion, usePresence, useTween } from '../../../core';
+import { ActionMenu, Button, TypeTile } from '../../../ds';
+import { useDs, type DensityName } from '../../../tokens';
+import { iconFor, resolveConfig, type OnboardingPreset, type PatternStatus } from '../shared/contract';
+import type { OnboardingOperation } from '../shared/mock';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { FieldLabel, OnboardingCard } from '../shared/OnboardingCard';
+import { PlainChip, RevealRow, Slot } from '../shared/parts';
+import { usePatternStatus, useSceneReport, useSeededReducer } from '../shared/runtime';
+import { DEPARTMENT_PRESETS, validateDepartmentSetup, type DepartmentSettings } from './contract';
+import {
+  departmentSeed, departmentView, initialDepartment, liveRows, reduceDepartment,
+  type DepartmentAction, type DepartmentSeed, type DepartmentState, type NamedRow,
+} from './engine';
+import { guarded } from '../shared/guard';
+
+export type DepartmentSetupProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<DepartmentSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  reload?: OnboardingOperation<void>;
+  initial?: DepartmentSeed;
+  /** The groups, every time they change. */
+  onChange?: (items: { name: string; count: number }[]) => void;
+  onContinue?: (items: { name: string; count: number }[]) => void;
+  onSkip?: () => void;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **Department Setup** — an add row (a field with a live `n/max` counter, + Add, Enter adds; a
+ * duplicate name is apricot with a helper), then the groups: tile, name, a plain count chip, and
+ * Rename / Delete icon buttons that appear on hover or focus-within. Rename swaps the name for an
+ * inline field (M4; Enter saves, Esc cancels). Deleting a non-empty group opens a menu whose danger
+ * item states the consequence; rows leave with M14. The last delete shows the empty state.
+ */
+function DepartmentSetupView(props: DepartmentSetupProps) {
+  const config = resolveConfig(DEPARTMENT_PRESETS, props.preset, props.config);
+  const issues = validateDepartmentSetup(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+function Valid({
+  config, density, status, reload, initial, onChange, onContinue, onSkip, onScene, testID,
+}: Omit<DepartmentSetupProps, 'config'> & { config: DepartmentSettings }) {
+  const { colors } = useDs();
+  const motion = useBlockMotion();
+  const key = JSON.stringify([config, initial ?? null]);
+  const [state, send, ref] = useSeededReducer(
+    (s: DepartmentState, a: DepartmentAction) => reduceDepartment(config, s, a),
+    () => initialDepartment(config, initial ?? (config.ship ? departmentSeed(config, config.ship) : {})),
+    key,
+  );
+  const pattern = usePatternStatus(status ?? (config.items.length ? 'ready' : 'empty'), reload);
+  const v = departmentView(config, state);
+  useSceneReport(pattern.status === 'ready' ? v.scene : pattern.status, onScene);
+  const addRef = useRef<TextInput>(null);
+  const items = () => liveRows(ref.current).map(r => ({ name: r.name, count: r.count }));
+  const itemsKey = JSON.stringify(liveRows(state).map(r => [r.name, r.count]));
+  const first = useRef(true);
+  useEffect(() => { if (first.current) { first.current = false; return; } onChange?.(items()); }, [itemsKey]);
+
+  /* The last row gone: the step is empty. */
+  const wasEmpty = useRef(state.rows.length === 0);
+  useEffect(() => {
+    const empty = state.rows.length === 0;
+    if (empty && !wasEmpty.current && pattern.status === 'ready') pattern.set('empty');
+    wasEmpty.current = empty;
+  }, [state.rows.length]);
+
+  const add = () => send({ type: 'add' });
+
+  return (
+    <OnboardingCard
+      testID={testID}
+      header={config}
+      copy={config}
+      density={density}
+      status={pattern.status}
+      onRetry={pattern.retry}
+      onEmptyAction={() => {
+        send({ type: 'clear' });
+        pattern.set('ready');
+        setTimeout(() => addRef.current?.focus(), 30);
+      }}
+      chip={v.chip}
+      hint={`${v.count} ${v.count === 1 ? config.noun : config.nouns}`}
+      secondary={config.secondaryLabel ? { label: config.secondaryLabel, onPress: () => { onSkip?.(); onScene?.('skipped'); } } : undefined}
+      primary={{ label: config.primaryLabel, onPress: () => { onContinue?.(items()); onScene?.('continued'); }, disabled: !v.canContinue }}>
+      <Box gap="s3">
+        <Box gap="s1">
+          <FieldLabel nativeID="dept-add-label">{config.addLabel}</FieldLabel>
+          <Box row gap="s2" align="flex-start">
+            <Box flex={1} style={{ minWidth: 0 }}>
+              <Input
+                ref={addRef}
+                value={state.add}
+                onChangeText={text => send({ type: 'addText', text })}
+                onSubmit={add}
+                placeholder={config.placeholder}
+                maxLength={config.maxLength}
+                suffix={`${state.add.length}/${config.maxLength}`}
+                error={v.addError}
+                aria-invalid={v.addError}
+                aria-describedby={v.addError ? 'dept-add-error' : undefined}
+                aria-label={config.addLabel}
+              />
+            </Box>
+            <Button variant="secondary" size="small" leadingGlyph="plus" onPress={add} disabled={!v.canAdd}>Add</Button>
+          </Box>
+          {v.addError ? <Text nativeID="dept-add-error" variant="caption" style={{ fontSize: 12, color: colors.status.needsUser }}>{config.duplicateText}</Text> : null}
+        </Box>
+        <Box role="list" aria-label={config.title}>
+          {state.rows.map(r => (
+            <Row key={r.id} row={r} state={state} config={config} send={send} immediate={motion.reduced} />
+          ))}
+        </Box>
+      </Box>
+    </OnboardingCard>
+  );
+}
+
+function Row({ row, state, config, send, immediate }: {
+  row: NamedRow; state: DepartmentState; config: DepartmentSettings; send: (a: DepartmentAction) => void; immediate: boolean;
+}) {
+  const { colors, density } = useDs();
+  const presence = usePresence(!row.leaving, { speed: 'list', appear: row.isNew });
+  useEffect(() => { if (row.leaving && !presence.mounted) send({ type: 'drop', id: row.id }); }, [row.leaving, presence.mounted]);
+  const editing = state.editId === row.id;
+  const menuOpen = state.menuId === row.id;
+  const v = departmentView(config, state);
+  const editRef = useRef<TextInput>(null);
+  useEffect(() => { if (editing) setTimeout(() => editRef.current?.focus(), 30); }, [editing]);
+  if (!presence.mounted) return null;
+  const confirm = config.confirmNonEmpty && row.count > 0;
+
+  return (
+    <MotionView aria-hidden={row.leaving || undefined} style={{ opacity: presence.opacity, transform: [{ translateY: presence.translateY }] }}>
+      <RevealRow
+        role="listitem"
+        force={menuOpen || editing}
+        style={{ flexDirection: 'row', alignItems: 'center', gap: 12, minHeight: density.rowH, paddingVertical: 8, borderBottomWidth: 1, borderBottomColor: colors.hairline }}>
+        {reveal => (
+          <>
+            <TypeTile icon={iconFor(config.itemIcon)} type={config.type} size={32} />
+            <Box flex={1} style={{ minWidth: 0 }}>
+              <Slot slotKey={editing ? 'edit' : 'view'} align="flex-start">
+                {editing ? (
+                  <Box flex={1} gap="s1" style={{ minWidth: 160 }}>
+                    <Input
+                      ref={editRef}
+                      value={state.edit}
+                      onChangeText={text => send({ type: 'editText', text })}
+                      onSubmit={() => send({ type: 'saveEdit' })}
+                      onKey={k => { if (k === 'Escape') send({ type: 'cancelEdit' }); }}
+                      maxLength={config.maxLength}
+                      error={Boolean(v.editError)}
+                      aria-invalid={Boolean(v.editError)}
+                      aria-describedby={`dept-edit-${row.id}`}
+                      aria-label={`Rename ${row.name}`}
+                    />
+                    <Text nativeID={`dept-edit-${row.id}`} variant="caption" style={{ fontSize: 12, color: v.editError ? colors.status.needsUser : colors.textSecondary }}>
+                      {v.editError ?? 'Enter to save · Esc to cancel'}
+                    </Text>
+                  </Box>
+                ) : (
+                  <Box row wrap align="center" gap="s2">
+                    <Text variant="caption" color="textPrimary" style={{ fontWeight: '600', fontSize: 13 }}>{row.name}</Text>
+                    <PlainChip>{v.countWord(row.count)}</PlainChip>
+                  </Box>
+                )}
+              </Slot>
+            </Box>
+            {!editing ? <Actions reveal={reveal} row={row} confirm={confirm} menuOpen={menuOpen} config={config} send={send} immediate={immediate} consequence={v.consequence(row.count)} /> : null}
+          </>
+        )}
+      </RevealRow>
+    </MotionView>
+  );
+}
+
+function Actions({ reveal, row, confirm, menuOpen, config, send, immediate, consequence }: {
+  reveal: boolean; row: NamedRow; confirm: boolean; menuOpen: boolean; config: DepartmentSettings;
+  send: (a: DepartmentAction) => void; immediate: boolean; consequence: string;
+}) {
+  const { colors } = useDs();
+  const t = useTween(reveal ? 1 : 0);
+  return (
+    <MotionView style={{ opacity: t, flexDirection: 'row', alignItems: 'center' }}>
+      <Pressable aria-label={`Rename ${row.name}`} onPress={() => send({ type: 'rename', id: row.id })} width={32} height={32} radius="pill">
+        <Icon name="edit" size={15} color={colors.textSecondary} />
+      </Pressable>
+      {confirm ? (
+        <ActionMenu
+          label={`${config.deleteLabel} ${row.name}`}
+          triggerLabel={`Delete ${row.name}`}
+          triggerIcon="trash"
+          open={menuOpen}
+          onOpenChange={open => send({ type: 'menu', id: open ? row.id : null })}
+          items={[
+            { value: 'delete', label: config.deleteLabel, detail: consequence, tone: 'danger' },
+            { value: 'cancel', label: 'Cancel' },
+          ]}
+          onSelect={choice => { if (choice === 'delete') send({ type: 'remove', id: row.id, immediate }); else send({ type: 'menu', id: null }); }}
+        />
+      ) : (
+        <Pressable aria-label={`Delete ${row.name}`} onPress={() => send({ type: 'remove', id: row.id, immediate })} width={32} height={32} radius="pill">
+          <Icon name="trash" size={15} color={colors.textSecondary} />
+        </Pressable>
+      )}
+    </MotionView>
+  );
+}
+
+/** DepartmentSetup, guarded: a wrong-kind config is refused by name and a render error is caught, never thrown to the page (`shared/guard`). */
+export const DepartmentSetup = guarded(DepartmentSetupView, DEPARTMENT_PRESETS, 'DepartmentSetup');

package/src/components/onboarding/department-setup/contract.ts

@@ -0,0 +1,53 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/**
+ * **Department Setup — "named list CRUD" (batch 2 §3.4)** — create, rename and delete named groups.
+ * No red delete: a non-empty group asks first, with apricot deep text and the consequence.
+ */
+
+export type NamedItem = { name: string; count: number };
+
+export const DEPARTMENT_SCENES = ['default', 'editing', 'confirm', 'duplicate', 'loading', 'empty', 'error'] as const;
+export type DepartmentScene = (typeof DEPARTMENT_SCENES)[number];
+/** Scenes that are an operation in flight — see `sceneProps`. */
+export const DEPARTMENT_IN_FLIGHT: readonly string[] = [];
+
+export type DepartmentSettings = HeaderConfig & LoadCopy & {
+  /** The row glyph. */
+  itemIcon: string;
+  noun: string;
+  nouns: string;
+  countNoun: string;
+  countNouns: string;
+  items: NamedItem[];
+  maxLength: number;
+  /** A group with members asks before it is deleted. */
+  confirmNonEmpty: boolean;
+  /** Which row the "editing" scene opens. Demo only. */
+  editIndex?: number;
+  ship?: DepartmentScene;
+  addLabel: string;
+  placeholder: string;
+  duplicateText: string;
+  deleteLabel: string;
+  /** "become unassigned" — the tail of "12 members become unassigned". */
+  consequence: string;
+  primaryLabel: string;
+  secondaryLabel?: string;
+};
+
+export const DEPARTMENT_PRESETS = presetsJson as unknown as PresetsFile<DepartmentSettings>;
+
+export function validateDepartmentSetup(c: DepartmentSettings): OnboardingIssue[] {
+  if (!Array.isArray(c.items)) return [{ path: 'items', message: 'items must be a list.' }];
+  const issues: OnboardingIssue[] = [];
+  if (!(c.maxLength >= 1)) issues.push({ path: 'maxLength', message: 'maxLength must be at least 1.' });
+  const seen = new Set<string>();
+  c.items.forEach((it, i) => {
+    const k = it.name.trim().toLowerCase();
+    if (seen.has(k)) issues.push({ path: `items[${i}].name`, message: `“${it.name}” is listed twice.` });
+    seen.add(k);
+  });
+  return issues;
+}

package/src/components/onboarding/department-setup/engine.ts

@@ -0,0 +1,107 @@
+import type { DepartmentScene, DepartmentSettings } from './contract';
+
+/** **The Department Setup engine** — pure: rows, the add field, the row being renamed, the confirm. */
+
+export type NamedRow = { id: string; name: string; count: number; leaving: boolean; isNew: boolean };
+export type DepartmentState = {
+  rows: NamedRow[];
+  add: string;
+  addTouched: boolean;
+  editId: string | null;
+  edit: string;
+  /** The row whose delete confirm is open. */
+  menuId: string | null;
+  nextId: number;
+};
+export type DepartmentSeed = Partial<DepartmentState>;
+
+export type DepartmentAction =
+  | { type: 'addText'; text: string }
+  | { type: 'add' }
+  | { type: 'rename'; id: string }
+  | { type: 'editText'; text: string }
+  | { type: 'saveEdit' }
+  | { type: 'cancelEdit' }
+  | { type: 'menu'; id: string | null }
+  | { type: 'remove'; id: string; immediate?: boolean }
+  | { type: 'drop'; id: string }
+  | { type: 'clear' };
+
+export function initialDepartment(c: DepartmentSettings, seed: DepartmentSeed = {}): DepartmentState {
+  return {
+    rows: seed.rows ?? c.items.map((it, i) => ({ id: `n${i}`, name: it.name, count: it.count, leaving: false, isNew: false })),
+    add: seed.add ?? '', addTouched: seed.addTouched ?? false,
+    editId: seed.editId ?? null, edit: seed.edit ?? '', menuId: seed.menuId ?? null, nextId: 100,
+  };
+}
+
+export function departmentSeed(c: DepartmentSettings, scene: DepartmentScene): DepartmentSeed {
+  const rows = initialDepartment(c).rows;
+  if (scene === 'editing') {
+    const r = rows[c.editIndex ?? 1] ?? rows[0];
+    return r ? { editId: r.id, edit: r.name } : {};
+  }
+  if (scene === 'confirm') {
+    const r = rows.find(x => x.count > 0) ?? rows[0];
+    return r ? { menuId: r.id } : {};
+  }
+  if (scene === 'duplicate' && rows[0]) return { add: rows[0].name, addTouched: true };
+  return {};
+}
+
+const norm = (s: string) => s.trim().toLowerCase();
+/** A name another live row already has (case-insensitive). */
+export function isDuplicate(s: DepartmentState, name: string, exceptId?: string): boolean {
+  const n = norm(name);
+  return Boolean(n) && s.rows.some(r => !r.leaving && r.id !== exceptId && norm(r.name) === n);
+}
+export const liveRows = (s: DepartmentState) => s.rows.filter(r => !r.leaving);
+
+export function reduceDepartment(c: DepartmentSettings, s: DepartmentState, a: DepartmentAction): DepartmentState {
+  switch (a.type) {
+    case 'addText': return { ...s, add: a.text.slice(0, c.maxLength), addTouched: true };
+    case 'add': {
+      const v = s.add.trim();
+      if (!v || isDuplicate(s, v)) return { ...s, addTouched: true };
+      return { ...s, rows: [...s.rows, { id: `n${s.nextId}`, name: v, count: 0, leaving: false, isNew: true }], nextId: s.nextId + 1, add: '', addTouched: false };
+    }
+    case 'rename': {
+      const r = s.rows.find(x => x.id === a.id);
+      return r ? { ...s, editId: r.id, edit: r.name, menuId: null } : s;
+    }
+    case 'editText': return { ...s, edit: a.text.slice(0, c.maxLength) };
+    case 'saveEdit': {
+      const v = s.edit.trim();
+      if (!s.editId || !v || isDuplicate(s, v, s.editId)) return s;
+      return { ...s, rows: s.rows.map(r => (r.id === s.editId ? { ...r, name: v } : r)), editId: null };
+    }
+    case 'cancelEdit': return { ...s, editId: null };
+    case 'menu': return { ...s, menuId: a.id };
+    case 'remove':
+      return {
+        ...s, menuId: null, editId: s.editId === a.id ? null : s.editId,
+        rows: a.immediate ? s.rows.filter(r => r.id !== a.id) : s.rows.map(r => (r.id === a.id ? { ...r, leaving: true } : r)),
+      };
+    case 'drop': return { ...s, rows: s.rows.filter(r => r.id !== a.id) };
+    case 'clear': return { ...s, rows: [], editId: null, menuId: null };
+  }
+}
+
+export function departmentView(c: DepartmentSettings, s: DepartmentState) {
+  const n = liveRows(s).length;
+  const addDup = isDuplicate(s, s.add);
+  const editDup = s.editId ? isDuplicate(s, s.edit, s.editId) : false;
+  const editBlank = s.editId ? !s.edit.trim() : false;
+  const countWord = (k: number) => `${k.toLocaleString('en-US')} ${k === 1 ? c.countNoun : c.countNouns}`;
+  return {
+    count: n,
+    scene: (s.menuId ? 'confirm' : s.editId ? 'editing' : s.addTouched && addDup ? 'duplicate' : 'default') as DepartmentScene,
+    chip: { tone: 'neutral' as const, label: `${n} ${n === 1 ? c.noun : c.nouns}` },
+    addError: s.addTouched && addDup,
+    canAdd: Boolean(s.add.trim()),
+    editError: editDup ? c.duplicateText : editBlank ? 'Enter a name' : null,
+    countWord,
+    consequence: (k: number) => `${countWord(k)} ${c.consequence}`,
+    canContinue: n > 0,
+  };
+}

package/src/components/onboarding/department-setup/index.ts

@@ -0,0 +1,9 @@
+export {
+  DEPARTMENT_IN_FLIGHT, DEPARTMENT_PRESETS, DEPARTMENT_SCENES, validateDepartmentSetup,
+  type DepartmentScene, type DepartmentSettings, type NamedItem,
+} from './contract';
+export {
+  departmentSeed, departmentView, initialDepartment, isDuplicate as isDuplicateName, reduceDepartment,
+  type DepartmentAction, type DepartmentSeed, type DepartmentState, type NamedRow,
+} from './engine';
+export { DepartmentSetup, type DepartmentSetupProps } from './DepartmentSetupView';