@appinternalleads/ui 0.2.0

package/src/components/threshold-flow/ThresholdFlowView.tsx

@@ -0,0 +1,275 @@
+import { useEffect, useMemo, useRef } from 'react';
+import {
+  Box, Icon, MotionView, Pressable, Switch, Text, useBlockMotion, usePresence, useSwap,
+  type IconName,
+} from '../../core';
+import { AmountField, BlockCard, Button, Callout, MetaChip } from '../../ds';
+import { DENSITIES, useDs, type DataType, type DensityName } from '../../tokens';
+import {
+  copyFor, nounFor, validateThresholdFlow,
+  type ThresholdFlowConfig, type ThresholdFlowDocument, type ThresholdItem,
+} from './contract';
+import { liveStages, type DraftStage, type ThresholdFlowSeed } from './engine';
+import { useThresholdFlow, type ThresholdFlowOperations } from './runtime';
+
+/**
+ * **ThresholdFlow — the view.** A pure render of `useThresholdFlow`'s state, composed from the
+ * Building Blocks: `BlockCard` (S1) for the shell and its loading/empty/error bodies, `MetaChip`
+ * (D1) for the status, `Callout` (D9) for the refusal, `Input` (C7) with prefix/suffix for each
+ * threshold, `Switch` (C3) for each stage's switch, `Button` (C13) for the actions. It draws no
+ * control of its own and holds no timer.
+ *
+ * UI-only state kept here, never in the document or the engine: the text of a field being edited
+ * (shown verbatim until blur, then grouped as `2,000`) and which rows have played their entrance.
+ */
+
+/** A leading glyph per data type. The hue comes from `TYPE_HUE`; this is only the mark. */
+const TYPE_ICON: Record<DataType, IconName> = {
+  schedule: 'refresh', date: 'refresh', action: 'bolt', automation: 'flow', email: 'mail',
+  agent: 'spark', file: 'file-other', design: 'canvas', data: 'data', unclassified: 'settings',
+};
+
+/** Space below each stage, per density — the prototype's 14 / 18 / 22. */
+const STAGE_PAD: Record<DensityName, number> = { compact: 14, default: 18, comfortable: 22 };
+
+export type ThresholdFlowViewProps = {
+  doc: ThresholdFlowDocument;
+  /** The host's activation. Omit for local-only mode — Activate goes live at once. */
+  operations?: ThresholdFlowOperations;
+  /** Restore a session (a story, a preview, a flow reopened live). Never part of the document. */
+  initial?: ThresholdFlowSeed;
+  /** The host is still fetching the flow — skeleton body, no footer. */
+  loading?: boolean;
+  /** Presentation, and the host's choice — overrides the provider's density for this flow only. */
+  density?: DensityName;
+  onChange?: (items: ThresholdItem[]) => void;
+  onActivate?: (items: ThresholdItem[]) => void;
+  testID?: string;
+};
+
+export function ThresholdFlowView(props: ThresholdFlowViewProps) {
+  const issues = useMemo(() => validateThresholdFlow(props.doc), [props.doc]);
+  if (issues.length) {
+    /* Refused, deterministically, and said out loud — an invalid document never half-renders. */
+    return (
+      <BlockCard title={typeof props.doc?.props?.title === 'string' ? props.doc.props.title : 'ThresholdFlow'} testID={props.testID}>
+        <Callout alert title="This flow can’t be shown">
+          {issues.map(i => i.message).join(' ')}
+        </Callout>
+      </BlockCard>
+    );
+  }
+  return <ValidFlow {...props} />;
+}
+
+function ValidFlow({ doc, operations, initial, loading = false, density, onChange, onActivate, testID }: ThresholdFlowViewProps) {
+  const config = doc.props;
+  const copy = copyFor(config);
+  const ds = useDs();
+  const densityName = density ?? ds.densityName;
+  const d = DENSITIES[densityName];
+  const rt = useThresholdFlow({ doc, operations, initial, onChange, onActivate });
+  const { state, errors, locked } = rt;
+  const motion = useBlockMotion();
+
+  const live = liveStages(state);
+  const total = live.length;
+  const errCount = Object.keys(errors).length;
+  const isEmpty = !loading && state.stages.length === 0;
+  const lastLive = live[live.length - 1]?.id;
+
+  /* Rows present at mount do not animate in; rows added later do (M1). */
+  const initialIds = useRef(new Set(state.stages.map(s => s.id))).current;
+
+  /* ── Header status (M9 swaps between these) ── */
+  const chip = state.phase === 'live' ? <MetaChip kind="status" status="executed">Live</MetaChip>
+    : state.phase === 'activating' ? <MetaChip kind="count" hue="neutral">{copy.activating}</MetaChip>
+    : state.phase === 'error' || errCount ? <MetaChip kind="status" status="needsUser">Needs attention</MetaChip>
+    : <MetaChip kind="count" hue="neutral">{`${total} ${nounFor(config, total)}`}</MetaChip>;
+  const chipKey = state.phase === 'editing' && errCount ? 'attention' : state.phase === 'editing' ? `count-${total}` : state.phase;
+  const chipFade = useSwap(chipKey);
+
+  /* ── Footer ── */
+  const hint = state.phase === 'live' ? copy.live
+    : state.phase === 'activating' ? copy.checking
+    : errCount ? (errCount === 1 ? `1 ${nounFor(config, 1)} needs fixing` : `${errCount} ${nounFor(config, errCount)} need fixing`)
+    : `${total} ${nounFor(config, total)}${copy.unit ? ` · ${copy.unit}` : ''}`;
+  const primaryLabel = state.phase === 'activating' ? copy.activating : state.phase === 'error' ? copy.retry : copy.action;
+  const primaryFade = useSwap(primaryLabel);
+
+  const actions = state.phase === 'live'
+    ? <Button variant="outline" size="small" onPress={() => rt.dispatch({ type: 'edit-flow' })}>{copy.edit}</Button>
+    : (
+      <>
+        {(config.templates?.length ?? 0) > total ? (
+          <Button variant="ghost" size="small" leadingGlyph="plus" disabled={!rt.canAdd} onPress={() => rt.dispatch({ type: 'add' })}>
+            {`Add ${nounFor(config, 1)}`}
+          </Button>
+        ) : null}
+        <MotionView style={{ opacity: primaryFade }}>
+          <Button
+            variant="primary"
+            size="small"
+            busy={state.phase === 'activating'}
+            disabled={!rt.canActivate}
+            onPress={rt.activate}>
+            {primaryLabel}
+          </Button>
+        </MotionView>
+      </>
+    );
+
+  /* An activation refusal is the component's OWN failure, not the card's load failure (Solarium
+     0.2.0 BlockCard): the stages stay on screen, with the host's message above them. */
+  const status = loading ? 'loading' : isEmpty ? 'empty' : 'ready';
+
+  return (
+    <BlockCard
+      testID={testID}
+      title={config.title}
+      subtitle={config.description}
+      icon={TYPE_ICON[config.type ?? 'unclassified']}
+      type={config.type}
+      hue={config.hue}
+      meta={loading ? undefined : <MotionView style={{ opacity: chipFade }}>{chip}</MotionView>}
+      status={status}
+      empty={{
+        title: copy.emptyTitle,
+        body: copy.emptyBody,
+        action: (config.templates?.length ?? 0) > 0
+          ? <Button variant="primary" size="small" leadingGlyph="plus" onPress={() => rt.dispatch({ type: 'add' })}>{copy.emptyCta}</Button>
+          : undefined,
+      }}
+      hint={hint}
+      actions={actions}>
+      {state.phase === 'error' ? <Callout alert title={copy.errorTitle}>{state.error?.message ?? ''}</Callout> : null}
+      {/* Locked (activating, live) is carried by disabled fields and the absence of Remove — NOT the
+          prototype's 55% opacity, which would take secondary text below AA contrast. */}
+      <Box role="list" aria-label={`${config.title} ${nounFor(config, 2)}`}>
+        {state.stages.map(stage => (
+          <StageRow
+            key={stage.id}
+            stage={stage}
+            index={live.findIndex(x => x.id === stage.id)}
+            config={config}
+            error={stage.leaving ? undefined : errors[stage.id]}
+            flagged={state.phase === 'error' && state.error?.stageId === stage.id}
+            live={state.phase === 'live'}
+            locked={locked}
+            last={stage.id === lastLive}
+            appear={!initialIds.has(stage.id)}
+            controlH={d.controlH}
+            pad={STAGE_PAD[densityName]}
+            onEdit={raw => rt.dispatch({ type: 'edit-value', id: stage.id, raw })}
+            onToggle={() => rt.dispatch({ type: 'toggle', id: stage.id })}
+            onRemove={() => rt.dispatch({ type: 'remove', id: stage.id, immediate: motion.reduced })}
+            onGone={() => rt.dispatch({ type: 'drop', id: stage.id })}
+          />
+        ))}
+      </Box>
+    </BlockCard>
+  );
+}
+
+function StageRow({
+  stage, index, config, error, flagged, live, locked, last, appear, controlH, pad,
+  onEdit, onToggle, onRemove, onGone,
+}: {
+  stage: DraftStage;
+  index: number;
+  config: ThresholdFlowConfig;
+  error?: string;
+  flagged: boolean;
+  live: boolean;
+  locked: boolean;
+  last: boolean;
+  appear: boolean;
+  controlH: number;
+  pad: number;
+  onEdit: (raw: string) => void;
+  onToggle: () => void;
+  onRemove: () => void;
+  onGone: () => void;
+}) {
+  const { colors } = useDs();
+  /* M14 on add and remove: fade + 6px, then the engine drops the row once the exit finishes. The
+     grouped-at-rest, verbatim-while-typing field is the shared `AmountField` (onboarding B7). */
+  const presence = usePresence(!stage.leaving, { distance: 6, speed: 'list', appear });
+  useEffect(() => { if (stage.leaving && !presence.mounted) onGone(); }, [stage.leaving, presence.mounted, onGone]);
+
+  const msgId = `tf-msg-${stage.id}`;
+  const node = live
+    ? { bg: colors.statusBg.executed, ink: colors.status.executed }
+    : error || flagged
+      ? { bg: colors.statusBg.needsUser, ink: colors.status.needsUser }
+      : { bg: colors.band, ink: colors.textPrimary };
+  const unitWords = config.unit?.prefix || config.unit?.suffix ? ` (${[config.unit.prefix, config.unit.suffix].filter(Boolean).join(' ').trim()})` : '';
+
+  return (
+    <MotionView
+      role="listitem"
+      aria-hidden={stage.leaving || undefined}
+      style={{ opacity: presence.opacity, transform: [{ translateY: presence.translateY }] }}>
+      <Box row gap="s3">
+        {/* The node and the connector. The number is the stage's position, not its id. */}
+        <Box align="center" style={{ width: 24 }}>
+          <Box width={24} height={24} radius="pill" align="center" justify="center" style={{ backgroundColor: node.bg }}>
+            {live
+              ? <Icon name="check" size={12} color={node.ink} />
+              : <Text variant="caption" numeric style={{ fontSize: 12, fontWeight: '600', color: node.ink }}>{stage.leaving ? '–' : String(index + 1)}</Text>}
+          </Box>
+          {!last ? <Box flex={1} style={{ width: 2, marginVertical: 4, backgroundColor: colors.hairlineStrong, borderRadius: 1 }} /> : null}
+        </Box>
+
+        <Box flex={1} gap="s2" style={{ minWidth: 0, paddingBottom: last ? 0 : pad }}>
+          <Box row align="flex-start" gap="s2">
+            <Box flex={1} style={{ minWidth: 0 }}>
+              <Text variant="caption" color="textPrimary" style={{ fontWeight: '600' }}>{stage.title}</Text>
+              {stage.role ? <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{stage.role}</Text> : null}
+            </Box>
+            {!locked && !stage.leaving ? (
+              <Pressable aria-label={`Remove ${stage.title}`} onPress={onRemove} width={32} height={32} radius="pill">
+                <Icon name="trash" size={15} color={colors.textSecondary} />
+              </Pressable>
+            ) : null}
+          </Box>
+
+          <Box row wrap align="flex-end" gap="s3">
+            <Box gap="s1" style={{ flexGrow: 1, flexBasis: 140, maxWidth: 220, minWidth: 0 }}>
+              <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{config.valueLabel}</Text>
+              <AmountField
+                value={stage.value}
+                onChangeText={onEdit}
+                disabled={locked}
+                prefix={config.unit?.prefix || undefined}
+                suffix={config.unit?.suffix?.trim() || undefined}
+                error={Boolean(error)}
+                describedBy={error ? msgId : undefined}
+                label={`${config.valueLabel}${unitWords} — ${stage.title}`}
+                minHeight={controlH - 2}
+              />
+            </Box>
+            {config.toggleLabel ? (
+              <Box row align="center" gap="s2" style={{ minHeight: controlH }}>
+                <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{config.toggleLabel}</Text>
+                <Switch
+                  value={stage.toggle}
+                  onChange={onToggle}
+                  disabled={locked}
+                  aria-label={`${config.toggleLabel} — ${stage.title}`}
+                />
+              </Box>
+            ) : null}
+          </Box>
+
+          {error ? (
+            <Box row gap="s1" align="center">
+              <Icon name="alert" size={13} color={colors.status.needsUser} />
+              <Text nativeID={msgId} variant="caption" style={{ fontSize: 12, color: colors.status.needsUser }}>{error}</Text>
+            </Box>
+          ) : null}
+        </Box>
+      </Box>
+    </MotionView>
+  );
+}

package/src/components/threshold-flow/contract.ts

@@ -0,0 +1,238 @@
+import type { DataType, Hue } from '../../tokens';
+import { DATA_TYPES, HUES } from '../../tokens';
+
+/**
+ * **`threshold-flow/1` — the portable ThresholdFlow document.**
+ *
+ * ThresholdFlow is an ordered list of stages, each with a numeric threshold that must strictly
+ * increase from one stage to the next and an optional switch; a person edits them and activates the
+ * flow. One component, configured four different ways in the handoff's case studies (refund
+ * approval, resume shortlisting, alert escalation, usage alerts) — only the document changes.
+ *
+ * Source: `design_handoff_solarium_blocks_case_studies/threshold-flow.schema.json`, corrected — see
+ * `spec/families/threshold-flow.schema.json` and `docs/components/threshold-flow/THRESHOLD-FLOW.md`
+ * §2 for every correction and why. **The schema is authoritative** where it and the handoff's
+ * `case-studies-data.json` disagree; the four studies are re-expressed as schema-valid fixtures in
+ * `spec/examples/components/threshold-flow/`.
+ *
+ * **What is NOT in the document, on purpose.** No phase (editing / activating / live / error), no
+ * loading flag, no density, no per-stage validation message, no callbacks and no pixel value. Phase
+ * is runtime state (`engine.ts`); validation is derived; density is the host's presentation choice
+ * (`ThresholdFlowView`'s `density` prop). A document that carried any of them would render the same
+ * flow differently depending on where it was saved from.
+ */
+
+export const THRESHOLD_FLOW_SCHEMA = 'threshold-flow/1' as const;
+
+/** One stage as the document holds it. `value` is a number — never the "750" string the prototype kept. */
+export type ThresholdItem = {
+  /** Stable, kebab-case. Identity for React keys, error targeting and the host's own mapping. */
+  id: string;
+  title: string;
+  /** Who or what the stage routes to — "Finance team". */
+  role?: string;
+  /** Strictly greater than 0, strictly greater than the previous stage's value, ≤ `unit.max`. */
+  value: number;
+  /** The stage's switch ("Auto-approve"). Only meaningful when the flow has a `toggleLabel`. */
+  toggle?: boolean;
+};
+
+/** What "Add" inserts. The Nth add inserts `templates[current count]`, so the list is also the cap. */
+export type ThresholdTemplate = Omit<ThresholdItem, 'id'>;
+
+export type ThresholdUnit = {
+  /** Before the value: `$`. */
+  prefix?: string;
+  /** After the value: ` min`, `%`, ` / 100`. Written with its own leading space when it wants one. */
+  suffix?: string;
+  /** Inclusive upper bound. Absent means none — never `0` for "none", which the prototype used. */
+  max?: number;
+};
+
+/** Every visible string the flow owns. All optional in the document; `copyFor` fills the rest. */
+export type ThresholdFlowCopy = {
+  /** The primary button: "Activate approval". */
+  action: string;
+  /** The primary button while activating: "Activating…". */
+  activating: string;
+  /** The primary button after a failed activation: "Try again". */
+  retry: string;
+  /** The footer while live: "Live · applies to every new refund". */
+  live: string;
+  /** The footer while activating: "Checking approvers…". */
+  checking: string;
+  /** The footer's unit note: "amounts in USD". */
+  unit: string;
+  /** The button that leaves live and unlocks the stages: "Edit stages". */
+  edit: string;
+  emptyTitle: string;
+  emptyBody: string;
+  emptyCta: string;
+  /** The failed-activation callout's title. Its body is the host's error message. */
+  errorTitle: string;
+};
+
+export type ThresholdFlowConfig = {
+  /** Resolves the hue through `TYPE_HUE`. Preferred over `hue`. */
+  type?: DataType;
+  /** Explicit override; a disagreement with `TYPE_HUE[type]` warns in development. */
+  hue?: Hue;
+  title: string;
+  description?: string;
+  unit?: ThresholdUnit;
+  /** The field label on every stage: "Over", "Min. score", "After". */
+  valueLabel: string;
+  /** The switch label on every stage. Absent → no stage has a switch. */
+  toggleLabel?: string;
+  /** Singular and plural of what a stage is called — "stage"/"stages", "level"/"levels". */
+  noun?: { one: string; other: string };
+  /** The stages the flow opens with. At most `MAX_STAGES`. */
+  defaultItems: ThresholdItem[];
+  /** What Add inserts, in order. Absent → Add is not offered. */
+  templates?: ThresholdTemplate[];
+  copy?: Partial<ThresholdFlowCopy>;
+};
+
+export type ThresholdFlowDocument = {
+  schema: typeof THRESHOLD_FLOW_SCHEMA;
+  /** The answer key: the host files the activated stages under this. */
+  key: string;
+  props: ThresholdFlowConfig;
+};
+
+/** The schema's `maxItems`. More stages than this is a routing table, not a flow. */
+export const MAX_STAGES = 8;
+
+/* ── Defaults ────────────────────────────────────────────────────────────── */
+
+export const DEFAULT_NOUN = { one: 'stage', other: 'stages' } as const;
+
+/** The prototype's own default copy, used for any key the document omits. */
+export function copyFor(config: ThresholdFlowConfig): ThresholdFlowCopy {
+  const noun = config.noun ?? DEFAULT_NOUN;
+  return {
+    action: 'Activate',
+    activating: 'Activating…',
+    retry: 'Try again',
+    live: 'Live',
+    checking: 'Checking…',
+    unit: '',
+    edit: `Edit ${noun.other}`,
+    emptyTitle: `No ${noun.other} yet`,
+    emptyBody: `Add a ${noun.one} to get started.`,
+    emptyCta: `Add first ${noun.one}`,
+    errorTitle: 'Couldn’t activate',
+    ...config.copy,
+  };
+}
+
+export function nounFor(config: ThresholdFlowConfig, count: number): string {
+  const noun = config.noun ?? DEFAULT_NOUN;
+  return count === 1 ? noun.one : noun.other;
+}
+
+/** `$2,000`, `85 / 100`, `15 min`. en-US grouping, as the prototype. */
+export function formatValue(unit: ThresholdUnit | undefined, value: number): string {
+  return `${unit?.prefix ?? ''}${value.toLocaleString('en-US')}${unit?.suffix ?? ''}`;
+}
+
+/* ── Validation ──────────────────────────────────────────────────────────── */
+
+/**
+ * **Why a document was refused.** A JSON schema catches shape; these catch meaning a schema cannot
+ * express — "each value exceeds the previous one" is a relation between array elements.
+ */
+export type ThresholdFlowIssue =
+  | { code: 'schema'; message: string }
+  | { code: 'unknown-type' | 'unknown-hue'; message: string }
+  | { code: 'duplicate-id'; id: string; message: string }
+  | { code: 'not-increasing'; id: string; message: string }
+  | { code: 'not-positive'; id: string; message: string }
+  | { code: 'over-max'; id: string; message: string }
+  | { code: 'too-many'; message: string }
+  | { code: 'toggle-without-label'; id: string; message: string }
+  | { code: 'template-not-increasing'; index: number; message: string };
+
+const ID = /^[a-z0-9-]+$/;
+const KEY = /^[a-z][a-z0-9_]*$/;
+
+/**
+ * Validate a document the way the view needs it. Deterministic: the same document always yields
+ * the same issues in the same order. An empty array is a valid document.
+ *
+ * `defaultItems` must be strictly increasing — a flow must never OPEN invalid. (While a person is
+ * editing, an out-of-order value is an expected, transient state; that is `stageErrors`, not this.)
+ */
+export function validateThresholdFlow(doc: unknown): ThresholdFlowIssue[] {
+  const issues: ThresholdFlowIssue[] = [];
+  const d = doc as Partial<ThresholdFlowDocument> | null;
+  if (!d || typeof d !== 'object') return [{ code: 'schema', message: 'Not an object.' }];
+  if (d.schema !== THRESHOLD_FLOW_SCHEMA) issues.push({ code: 'schema', message: `schema must be "${THRESHOLD_FLOW_SCHEMA}".` });
+  if (typeof d.key !== 'string' || !KEY.test(d.key)) issues.push({ code: 'schema', message: 'key must match ^[a-z][a-z0-9_]*$.' });
+  const p = d.props;
+  if (!p || typeof p !== 'object') return [...issues, { code: 'schema', message: 'props is required.' }];
+  for (const f of ['title', 'valueLabel'] as const) {
+    if (typeof p[f] !== 'string' || !p[f]) issues.push({ code: 'schema', message: `props.${f} is required.` });
+  }
+  if (!Array.isArray(p.defaultItems)) return [...issues, { code: 'schema', message: 'props.defaultItems must be an array.' }];
+  if (p.type !== undefined && !DATA_TYPES.includes(p.type)) issues.push({ code: 'unknown-type', message: `Unknown type "${String(p.type)}".` });
+  if (p.hue !== undefined && !HUES.includes(p.hue)) issues.push({ code: 'unknown-hue', message: `Unknown hue "${String(p.hue)}".` });
+  if (p.defaultItems.length > MAX_STAGES) issues.push({ code: 'too-many', message: `At most ${MAX_STAGES} stages.` });
+
+  const seen = new Set<string>();
+  p.defaultItems.forEach((item, i) => {
+    if (typeof item?.id !== 'string' || !ID.test(item.id)) {
+      issues.push({ code: 'schema', message: `defaultItems[${i}].id must be kebab-case.` });
+      return;
+    }
+    if (seen.has(item.id)) issues.push({ code: 'duplicate-id', id: item.id, message: `Duplicate id "${item.id}".` });
+    seen.add(item.id);
+    if (typeof item.value !== 'number' || !(item.value > 0)) {
+      issues.push({ code: 'not-positive', id: item.id, message: `"${item.title}" must be greater than 0.` });
+    } else if (p.unit?.max !== undefined && item.value > p.unit.max) {
+      issues.push({ code: 'over-max', id: item.id, message: `"${item.title}" is over the maximum of ${p.unit.max}.` });
+    }
+    const prev = p.defaultItems[i - 1];
+    if (prev && typeof prev.value === 'number' && typeof item.value === 'number' && item.value <= prev.value) {
+      issues.push({ code: 'not-increasing', id: item.id, message: `"${item.title}" (${item.value}) must be more than "${prev.title}" (${prev.value}).` });
+    }
+    if (item.toggle !== undefined && !p.toggleLabel) {
+      issues.push({ code: 'toggle-without-label', id: item.id, message: `"${item.title}" sets a switch, but the flow has no toggleLabel.` });
+    }
+  });
+
+  (p.templates ?? []).forEach((t, i, all) => {
+    const prev = all[i - 1];
+    if (prev && t.value <= prev.value) {
+      issues.push({ code: 'template-not-increasing', index: i, message: `Template ${i + 1} ("${t.title}") must be more than template ${i} ("${prev.title}").` });
+    }
+  });
+  return issues;
+}
+
+/**
+ * **Per-stage messages while a person edits** — the prototype's three strings, verbatim. A stage
+ * with no message is valid. Pure and derived: never stored, recomputed from the stages every render.
+ *
+ * `value` is `number | null`: `null` is an empty field, which is its own message rather than 0.
+ */
+export function stageErrors(
+  stages: { id: string; title: string; value: number | null }[],
+  unit?: ThresholdUnit,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  stages.forEach((s, i) => {
+    if (s.value === null || !(s.value > 0)) { out[s.id] = 'Enter a value greater than 0.'; return; }
+    if (unit?.max !== undefined && s.value > unit.max) { out[s.id] = `Must be ${formatValue(unit, unit.max)} or less.`; return; }
+    const prev = stages[i - 1];
+    if (prev && prev.value !== null && s.value <= prev.value) {
+      out[s.id] = `Must be more than ${prev.title} (${formatValue(unit, prev.value)}).`;
+    }
+  });
+  return out;
+}
+
+/** The activated stages under the document's answer key — what a host files. */
+export function answerOf(doc: ThresholdFlowDocument, items: ThresholdItem[]): Record<string, ThresholdItem[]> {
+  return { [doc.key]: items };
+}