@appinternalleads/ui 0.2.0

package/src/ds/blockControls.tsx

@@ -0,0 +1,1055 @@
+import { useEffect, useRef, useState } from 'react';
+import type { TextInput, View } from 'react-native';
+import {
+  ColorSwatch, Box, Icon, Input, MotionView, Pressable, Text, usePresence, useTween, type IconName,
+} from '../core';
+import { blockRadii, useDs, type DataType, type Hue } from '../tokens';
+import { TypeTile } from './blocks';
+import { HEX_EXAMPLE as HEX_EXAMPLE_VALUE } from '../tokens';
+
+/**
+ * **Solarium Building Blocks — controls.** C1 Checkbox · C2 Radio · C4 Selectable card ·
+ * C8 Number stepper · C9 OTP · C11 Tag input · C12 Colour field. (C6 Select is the platform-split
+ * primitive `core/Select`; C3, C5, C7, C10 and C13 already existed — see
+ * `docs/HANDOFF-SOLARIUM-BLOCKS.md` §3.)
+ *
+ * Every control here is **controlled**: it takes `value` and reports `onChange`, and owns only
+ * presentation state (focus, a draft being typed). That is the convention every field and widget
+ * in this library follows — the host owns the answer.
+ *
+ * Focus: the Solarium 0.2.0 coral ring on keyboard focus, drawn by `core/Pressable` and
+ * `core/Input` (`focusRingFor`) — every control here inherits it.
+ */
+
+/* ── Roving focus — one tab stop per group, arrows move and select ──────── */
+
+/**
+ * The radio-group keyboard contract (WAI-ARIA APG): Tab reaches the checked item, or the first
+ * when none is; arrows move AND select, wrapping; Home/End jump. Shared by `RadioGroup` and
+ * `SelectableCardGroup`, which are the same control with different faces — and exported for a
+ * radio group whose rows need more than those faces carry (onboarding Plan Selection).
+ */
+export function useRovingSelect<T>(values: T[], value: T | undefined, onChange: (v: T) => void, disabled?: boolean) {
+  const refs = useRef<(View | null)[]>([]);
+  const checked = value === undefined ? -1 : values.indexOf(value);
+  const stop = checked >= 0 ? checked : 0;
+
+  const move = (to: number) => {
+    const n = (to + values.length) % values.length;
+    onChange(values[n]!);
+    refs.current[n]?.focus();
+  };
+
+  return {
+    tabIndex: (i: number): 0 | -1 => (i === stop ? 0 : -1),
+    ref: (i: number) => (el: View | null) => { refs.current[i] = el; },
+    onKeyDown: (i: number) => (e: { key: string; preventDefault: () => void }) => {
+      if (disabled) return;
+      const from = checked >= 0 ? checked : i;
+      if (e.key === 'ArrowDown' || e.key === 'ArrowRight') { e.preventDefault(); move(from + 1); }
+      else if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') { e.preventDefault(); move(from - 1); }
+      else if (e.key === 'Home') { e.preventDefault(); move(0); }
+      else if (e.key === 'End') { e.preventDefault(); move(values.length - 1); }
+    },
+  };
+}
+
+/* ── C1 · Checkbox ───────────────────────────────────────────────────────── */
+
+export type CheckState = boolean | 'mixed';
+
+/**
+ * **18px box, radius `key` (4), a 1.5px `controlBorder` rim; on is the strong coral with a white
+ * tick; mixed is a dash.** The whole row is the target, not the 18px box.
+ *
+ * `role="checkbox"` with `aria-checked` — including `"mixed"` — so the state is announced, not
+ * merely drawn. Pressing a mixed box reports `true`: the parent of a partly-checked set checks all.
+ */
+export function Checkbox({
+  checked, onChange, label, labelSuffix, description, disabled, locked = false, describedBy,
+}: {
+  checked: CheckState;
+  onChange: (next: boolean) => void;
+  label: string;
+  /** Muted words after the label — " (optional)". Part of the accessible name. */
+  labelSuffix?: string;
+  description?: string;
+  disabled?: boolean;
+  /**
+   * Always on and not changeable (a role's "View projects"): checked, disabled, drawn on the
+   * line-soft ground with a muted check. Pair it with a helper ("Always on") via `describedBy`.
+   */
+  locked?: boolean;
+  /** The id of text that explains this box — a locked box's "Always on". */
+  describedBy?: string;
+}) {
+  const { colors, density } = useDs();
+  const value: CheckState = locked ? true : checked;
+  const on = value !== false;
+  /* M7: the check scales .6 → 1 as it appears. */
+  const t = useTween(on ? 1 : 0);
+  const box = locked ? { edge: colors.hairlineStrong, fill: colors.band, ink: colors.textSecondary }
+    : on ? { edge: colors.accentInk, fill: colors.accentInk, ink: colors.accentOnFill }
+    : { edge: colors.controlBorder, fill: colors.surface1, ink: colors.accentOnFill };
+  return (
+    <Pressable
+      role="checkbox"
+      aria-checked={value}
+      aria-label={labelSuffix ? `${label}${labelSuffix}` : label}
+      aria-describedby={describedBy}
+      disabled={disabled || locked}
+      onPress={() => onChange(checked !== true)}
+      row
+      align="center"
+      justify="flex-start"
+      gap="s2"
+      minHeight={Math.min(density.controlH, 44)}>
+      <Box
+        width={18}
+        height={18}
+        align="center"
+        justify="center"
+        style={{ borderRadius: blockRadii.key, borderWidth: 1.5, borderColor: box.edge, backgroundColor: box.fill }}>
+        <MotionView style={{ opacity: t, transform: [{ scale: t.interpolate({ inputRange: [0, 1], outputRange: [0.6, 1] }) }] }}>
+          {value === 'mixed'
+            ? <Icon name="minus" size={12} color={box.ink} />
+            : <Icon name="tick" size={12} color={box.ink} />}
+        </MotionView>
+      </Box>
+      <Box flex={1} gap="s1">
+        <Text variant="caption" style={{ color: locked ? colors.textSecondary : colors.textPrimary, fontWeight: labelSuffix !== undefined ? '600' : undefined }}>
+          {label}
+          {labelSuffix ? <Text variant="caption" color="textSecondary" style={{ fontWeight: '400' }}>{labelSuffix}</Text> : null}
+        </Text>
+        {description ? <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{description}</Text> : null}
+      </Box>
+    </Pressable>
+  );
+}
+
+/**
+ * **A parent checkbox over its children.** The parent is derived — never stored — from the
+ * children: all → checked, some → mixed, none → unchecked. Pressing it cycles all ↔ none.
+ */
+export function CheckboxGroup<T extends string>({
+  label, options, value, onChange, disabled,
+}: {
+  label: string;
+  options: { value: T; label: string; description?: string }[];
+  value: T[];
+  onChange: (next: T[]) => void;
+  disabled?: boolean;
+}) {
+  const count = options.filter(o => value.includes(o.value)).length;
+  const parent: CheckState = count === 0 ? false : count === options.length ? true : 'mixed';
+  return (
+    <Box role="group" aria-label={label} gap="s1">
+      <Checkbox
+        label={label}
+        checked={parent}
+        disabled={disabled}
+        onChange={() => onChange(parent === true ? [] : options.map(o => o.value))}
+      />
+      <Box pl="s6" gap="s1">
+        {options.map(o => (
+          <Checkbox
+            key={o.value}
+            label={o.label}
+            description={o.description}
+            disabled={disabled}
+            checked={value.includes(o.value)}
+            onChange={on => onChange(on
+              ? options.filter(x => x.value === o.value || value.includes(x.value)).map(x => x.value)
+              : value.filter(v => v !== o.value))}
+          />
+        ))}
+      </Box>
+    </Box>
+  );
+}
+
+/* ── C2 · Radio ──────────────────────────────────────────────────────────── */
+
+function RadioDot({ on }: { on: boolean }) {
+  const { colors } = useDs();
+  /* M7 select (0.2.0): the 8px dot fades in and scales .6 → 1; under reduced motion it jumps. */
+  const t = useTween(on ? 1 : 0);
+  return (
+    <Box
+      width={18}
+      height={18}
+      align="center"
+      justify="center"
+      radius="pill"
+      style={{ borderWidth: 1.5, borderColor: on ? colors.accentInk : colors.controlBorder, backgroundColor: colors.surface1 }}>
+      <MotionView style={{
+        width: 8, height: 8, borderRadius: 4, backgroundColor: colors.accentInk, opacity: t,
+        transform: [{ scale: t.interpolate({ inputRange: [0, 1], outputRange: [0.6, 1] }) }],
+      }} />
+    </Box>
+  );
+}
+
+export type RadioOption<T extends string> = {
+  value: T;
+  label: string;
+  description?: string;
+  /** A leading tile — `rows` only. */
+  icon?: IconName;
+  type?: DataType;
+  hue?: Hue;
+};
+
+/**
+ * **Row + dot. Arrows move and select; roving tabindex.** One tab stop for the whole group.
+ *
+ * `variant="rows"` is the onboarding handoff's option row (B3): each option a bordered row (radius 8,
+ * density's row height), label 13/600 and a description line, an optional leading tile, and on
+ * select a 2px coral ring that fades in (M7) while the dot scales in. The keyboard contract is
+ * the same.
+ */
+export function RadioGroup<T extends string>({
+  label, options, value, onChange, disabled, row = false, variant = 'plain',
+}: {
+  label: string;
+  options: RadioOption<T>[];
+  value: T | undefined;
+  onChange: (next: T) => void;
+  disabled?: boolean;
+  /** Lay the options out in a row, wrapping. `plain` only. */
+  row?: boolean;
+  variant?: 'plain' | 'rows';
+}) {
+  const { density } = useDs();
+  const roving = useRovingSelect(options.map(o => o.value), value, onChange, disabled);
+  if (variant === 'rows') {
+    return (
+      <Box role="radiogroup" aria-label={label} gap="s2">
+        {options.map((o, i) => (
+          <OptionRow
+            key={o.value}
+            option={o}
+            on={o.value === value}
+            disabled={disabled}
+            minHeight={density.rowH}
+            pressRef={roving.ref(i)}
+            tabIndex={roving.tabIndex(i)}
+            onKeyDown={roving.onKeyDown(i)}
+            onPress={() => onChange(o.value)}
+          />
+        ))}
+      </Box>
+    );
+  }
+  return (
+    <Box role="radiogroup" aria-label={label} gap="s1" row={row} wrap={row}>
+      {options.map((o, i) => {
+        const on = o.value === value;
+        return (
+          <Pressable
+            key={o.value}
+            ref={roving.ref(i)}
+            role="radio"
+            aria-checked={on}
+            aria-label={o.label}
+            tabIndex={roving.tabIndex(i)}
+            onKeyDown={roving.onKeyDown(i)}
+            disabled={disabled}
+            onPress={() => onChange(o.value)}
+            row
+            align="center"
+            justify="flex-start"
+            gap="s2"
+            minHeight={Math.min(density.controlH, 44)}
+            style={row ? { paddingRight: 12 } : undefined}>
+            <RadioDot on={on} />
+            <Box flex={row ? undefined : 1} gap="s1">
+              <Text variant="caption" color="textPrimary">{o.label}</Text>
+              {o.description ? <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{o.description}</Text> : null}
+            </Box>
+          </Pressable>
+        );
+      })}
+    </Box>
+  );
+}
+
+/** The 2px coral "selected" ring, as an overlay that fades (M7) — never a fill, never a layout shift. */
+function SelectRing({ on, radius }: { on: boolean; radius: number }) {
+  const { colors } = useDs();
+  const t = useTween(on ? 1 : 0);
+  return (
+    <MotionView
+      aria-hidden
+      pointerEvents="none"
+      style={{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, borderRadius: radius, borderWidth: 2, borderColor: colors.accentFill, opacity: t }}
+    />
+  );
+}
+
+function OptionRow<T extends string>({
+  option: o, on, disabled, minHeight, pressRef, tabIndex, onKeyDown, onPress,
+}: {
+  option: RadioOption<T>;
+  on: boolean;
+  disabled?: boolean;
+  minHeight: number;
+  pressRef: (el: View | null) => void;
+  tabIndex: 0 | -1;
+  onKeyDown: (e: { key: string; preventDefault: () => void }) => void;
+  onPress: () => void;
+}) {
+  const { colors } = useDs();
+  return (
+    <Pressable
+      ref={pressRef}
+      role="radio"
+      aria-checked={on}
+      aria-label={o.label}
+      tabIndex={tabIndex}
+      onKeyDown={onKeyDown}
+      disabled={disabled}
+      onPress={onPress}
+      row
+      align="center"
+      justify="flex-start"
+      gap="s3"
+      minHeight={minHeight}
+      style={{ paddingVertical: 10, paddingHorizontal: 12, borderRadius: blockRadii.inset, borderWidth: 1, borderColor: colors.hairlineStrong, backgroundColor: colors.surface1 }}>
+      <RadioDot on={on} />
+      {o.icon ? <TypeTile icon={o.icon} type={o.type} hue={o.hue} size={32} /> : null}
+      <Box flex={1} style={{ minWidth: 0 }}>
+        <Text variant="caption" color="textPrimary" style={{ fontWeight: '600' }}>{o.label}</Text>
+        {o.description ? <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{o.description}</Text> : null}
+      </Box>
+      <SelectRing on={on} radius={blockRadii.inset} />
+    </Pressable>
+  );
+}
+
+/* ── C4 · Selectable card ────────────────────────────────────────────────── */
+
+export type SelectableCardOption<T extends string> = {
+  value: T;
+  title: string;
+  description?: string;
+  /** Right of the title — a price, a count. */
+  meta?: string;
+};
+
+/**
+ * **Cards that behave as one radio group.** Selected is a 2px coral ring, never a fill; heights
+ * are equal (the row stretches every card to the tallest). Same keyboard contract as `RadioGroup`.
+ */
+export function SelectableCardGroup<T extends string>({
+  label, options, value, onChange, disabled, columns,
+}: {
+  label: string;
+  options: SelectableCardOption<T>[];
+  value: T | undefined;
+  onChange: (next: T) => void;
+  disabled?: boolean;
+  /** Minimum width per card before the row wraps. Default 160 — the card grid's own floor. */
+  columns?: { minWidth: number };
+}) {
+  const { colors } = useDs();
+  const roving = useRovingSelect(options.map(o => o.value), value, onChange, disabled);
+  return (
+    <Box role="radiogroup" aria-label={label} row wrap gap="s3" align="stretch">
+      {options.map((o, i) => {
+        const on = o.value === value;
+        return (
+          <Pressable
+            key={o.value}
+            ref={roving.ref(i)}
+            role="radio"
+            aria-checked={on}
+            aria-label={o.title}
+            tabIndex={roving.tabIndex(i)}
+            onKeyDown={roving.onKeyDown(i)}
+            disabled={disabled}
+            onPress={() => onChange(o.value)}
+            align="stretch"
+            justify="flex-start"
+            p="s3"
+            style={{
+              flexGrow: 1,
+              flexBasis: columns?.minWidth ?? 160,
+              minWidth: 0,
+              borderRadius: blockRadii.mid,
+              backgroundColor: colors.surface1,
+              boxShadow: on ? `0 0 0 2px ${colors.accentFill}` : `0 0 0 1px ${colors.hairlineStrong}`,
+            }}>
+            <Box row justify="space-between" gap="s2">
+              <Text variant="label" style={{ fontWeight: '600', flexShrink: 1 }}>{o.title}</Text>
+              {o.meta ? <Text variant="caption" color="textSecondary" numeric>{o.meta}</Text> : null}
+            </Box>
+            {o.description ? <Text variant="caption" color="textSecondary" style={{ marginTop: 4 }}>{o.description}</Text> : null}
+          </Pressable>
+        );
+      })}
+    </Box>
+  );
+}
+
+/* ── C4 · Toggle cards (multi-select, onboarding B4) ─────────────────────── */
+
+export type ToggleCardOption<T extends string> = {
+  value: T;
+  title: string;
+  description?: string;
+  icon?: IconName;
+  type?: DataType;
+  hue?: Hue;
+};
+
+function CheckIndicator({ on }: { on: boolean }) {
+  const { colors } = useDs();
+  const t = useTween(on ? 1 : 0);
+  return (
+    <Box
+      width={20}
+      height={20}
+      radius="pill"
+      align="center"
+      justify="center"
+      style={{ position: 'absolute', top: 12, right: 12, borderWidth: on ? 0 : 1.5, borderColor: colors.textSecondary, backgroundColor: on ? colors.accentFill : colors.surface1 }}>
+      <MotionView style={{ opacity: t, transform: [{ scale: t.interpolate({ inputRange: [0, 1], outputRange: [0.6, 1] }) }] }}>
+        <Icon name="tick" size={12} color={colors.accentOnFill} />
+      </MotionView>
+    </Box>
+  );
+}
+
+/**
+ * **Cards you switch on and off — several at once (C4, multi-select; decision D15).**
+ *
+ * Each card is a toggle button (`aria-pressed`), not a radio: selecting one never deselects another.
+ * Selected is the 2px coral ring overlay (M7) plus a 20px check that scales .6→1; the leading tile
+ * keeps its category hue either way. At `max`, the unselected cards are disabled (dimmed, still in
+ * place) so the limit is visible rather than a surprise. Two columns, equal heights.
+ *
+ * A separate export from `SelectableCardGroup` rather than a `mode` on it: the value is an array,
+ * the role is different, and a union prop that changes both is a type nobody can read.
+ */
+export function ToggleCardGroup<T extends string>({
+  label, options, value, onChange, max, disabled, columns = 2,
+}: {
+  label: string;
+  options: ToggleCardOption<T>[];
+  value: T[];
+  onChange: (next: T[]) => void;
+  /** At this many, the unselected cards disable. */
+  max?: number;
+  disabled?: boolean;
+  columns?: number;
+}) {
+  const { colors, density } = useDs();
+  const full = max !== undefined && value.length >= max;
+  return (
+    <Box role="group" aria-label={label} row wrap align="stretch" style={{ gap: density.gap }}>
+      {options.map(o => {
+        const on = value.includes(o.value);
+        const off = disabled || (full && !on);
+        return (
+          <Pressable
+            key={o.value}
+            aria-pressed={on}
+            aria-label={o.description ? `${o.title}, ${o.description}` : o.title}
+            disabled={off}
+            onPress={() => onChange(on ? value.filter(v => v !== o.value) : [...value, o.value])}
+            row
+            align="center"
+            justify="flex-start"
+            gap="s3"
+            minHeight={72}
+            style={{
+              flexBasis: `${Math.floor(100 / columns) - 3}%`,
+              flexGrow: 1,
+              minWidth: 140,
+              paddingVertical: density.padY,
+              paddingLeft: 12,
+              paddingRight: 40,
+              borderRadius: blockRadii.mid,
+              borderWidth: 1,
+              borderColor: colors.hairlineStrong,
+              backgroundColor: colors.surface1,
+              opacity: off && !disabled ? 0.5 : 1,
+            }}>
+            {o.icon ? <TypeTile icon={o.icon} type={o.type} hue={o.hue} size={32} /> : null}
+            <Box flex={1} style={{ minWidth: 0 }}>
+              <Text variant="caption" color="textPrimary" style={{ fontWeight: '600' }} numberOfLines={1}>{o.title}</Text>
+              {o.description ? <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }} numberOfLines={1}>{o.description}</Text> : null}
+            </Box>
+            <CheckIndicator on={on} />
+            <SelectRing on={on} radius={blockRadii.mid} />
+          </Pressable>
+        );
+      })}
+    </Box>
+  );
+}
+
+/* ── C7 · Amount field (onboarding B7) ───────────────────────────────────── */
+
+/** Digits only, at most 9 — the handoff's amount rule. Empty is `null`, not 0. */
+export function parseAmount(raw: string): number | null {
+  const digits = raw.replace(/[^0-9]/g, '').slice(0, 9);
+  return digits === '' ? null : Number(digits);
+}
+
+/**
+ * **A number field that shows `2,000` at rest and exactly what was typed while editing (B7).**
+ *
+ * The draft rule ThresholdFlow proved: focus does NOT reformat the text — swapping "2,000" for
+ * "2000" on focus reset the selection the browser had just made, so select-all-then-type appended.
+ * The typed text is kept verbatim until blur, then the value shows grouped. Prefix and suffix are
+ * the field's affixes, outside the value.
+ */
+export function AmountField({
+  value, onChange, onChangeText, label, prefix, suffix, error, disabled, describedBy, width, minHeight,
+}: {
+  value: number | null;
+  onChange?: (next: number | null) => void;
+  /** The raw text on every keystroke, for a caller that parses itself. */
+  onChangeText?: (raw: string) => void;
+  /** The field's accessible name. */
+  label: string;
+  prefix?: string;
+  suffix?: string;
+  error?: boolean;
+  disabled?: boolean;
+  describedBy?: string;
+  width?: number;
+  minHeight?: number;
+}) {
+  const [draft, setDraft] = useState<string | null>(null);
+  const shown = draft ?? (value === null ? '' : value.toLocaleString('en-US'));
+  return (
+    <Box style={width ? { width } : undefined}>
+      <Input
+        value={shown}
+        onChangeText={t => { setDraft(t); onChangeText?.(t); onChange?.(parseAmount(t)); }}
+        onBlur={() => setDraft(null)}
+        numeric
+        disabled={disabled}
+        prefix={prefix || undefined}
+        suffix={suffix || undefined}
+        error={error}
+        aria-invalid={error}
+        aria-describedby={describedBy}
+        aria-label={label}
+        style={minHeight ? { minHeight } : undefined}
+      />
+    </Box>
+  );
+}
+
+/* ── C8 · Number stepper ─────────────────────────────────────────────────── */
+
+/** Hold-to-repeat: a first repeat after this, then one per `REPEAT_MS`. */
+export const STEPPER_HOLD_MS = 400;
+export const STEPPER_REPEAT_MS = 80;
+
+/**
+ * **− value +, grouped.** The value is a `spinbutton` — ArrowUp/Down step, Home/End jump to the
+ * limits — and each button disables at its limit rather than vanishing. Holding a button repeats.
+ */
+export function NumberStepper({
+  label, value, onChange, min, max, step = 1, disabled, format,
+}: {
+  label: string;
+  value: number;
+  onChange: (next: number) => void;
+  min: number;
+  max: number;
+  step?: number;
+  disabled?: boolean;
+  /** The value in words for a screen reader and the display — "4 seats". */
+  format?: (n: number) => string;
+}) {
+  const { colors, density } = useDs();
+  const clamp = (n: number) => Math.min(max, Math.max(min, n));
+  const latest = useRef(value);
+  latest.current = value;
+  const hold = useRef<{ start?: ReturnType<typeof setTimeout>; repeat?: ReturnType<typeof setInterval> }>({});
+
+  const stopHold = () => {
+    if (hold.current.start) clearTimeout(hold.current.start);
+    if (hold.current.repeat) clearInterval(hold.current.repeat);
+    hold.current = {};
+  };
+  useEffect(() => stopHold, []);
+
+  const bump = (dir: 1 | -1) => {
+    const next = clamp(latest.current + dir * step);
+    if (next !== latest.current) { latest.current = next; onChange(next); }
+  };
+  const startHold = (dir: 1 | -1) => {
+    stopHold();
+    hold.current.start = setTimeout(() => {
+      hold.current.repeat = setInterval(() => bump(dir), STEPPER_REPEAT_MS);
+    }, STEPPER_HOLD_MS);
+  };
+
+  const text = format ? format(value) : String(value);
+  const button = (dir: 1 | -1) => {
+    const atLimit = dir === 1 ? value >= max : value <= min;
+    return (
+      <Pressable
+        aria-label={dir === 1 ? `Increase ${label}` : `Decrease ${label}`}
+        disabled={disabled || atLimit}
+        onPress={() => bump(dir)}
+        onPressIn={() => startHold(dir)}
+        onPressOut={stopHold}
+        width={32}
+        height={density.controlH}
+        tabIndex={-1}>
+        <Icon name={dir === 1 ? 'plus' : 'minus'} size={14} color={colors.textPrimary} />
+      </Pressable>
+    );
+  };
+
+  return (
+    <Box
+      row
+      align="center"
+      alignSelf="flex-start"
+      style={{ borderRadius: blockRadii.inset, boxShadow: `0 0 0 1px ${colors.hairlineStrong}`, backgroundColor: colors.surface1 }}>
+      {button(-1)}
+      <Pressable
+        role="spinbutton"
+        aria-label={label}
+        aria-valuenow={value}
+        aria-valuemin={min}
+        aria-valuemax={max}
+        aria-valuetext={text}
+        tabIndex={disabled ? -1 : 0}
+        onKeyDown={e => {
+          if (disabled) return;
+          if (e.key === 'ArrowUp') { e.preventDefault(); bump(1); }
+          else if (e.key === 'ArrowDown') { e.preventDefault(); bump(-1); }
+          else if (e.key === 'Home') { e.preventDefault(); onChange(min); }
+          else if (e.key === 'End') { e.preventDefault(); onChange(max); }
+        }}
+        height={density.controlH}
+        px="s2"
+        style={{ minWidth: 40 }}>
+        <Text numeric style={{ fontSize: 15, fontWeight: '600', color: colors.textPrimary }}>{String(value)}</Text>
+      </Pressable>
+      {button(1)}
+    </Box>
+  );
+}
+
+/* ── C9 · One-time code ──────────────────────────────────────────────────── */
+
+/**
+ * **Six slots, 3–3; ONE real input underneath.** The slots are a drawing of the input's value, so
+ * paste, autofill (`oneTimeCode`) and a screen reader all meet a single ordinary text field — the
+ * failure of six separate inputs is that a pasted code lands in the first box only.
+ */
+export function OtpInput({
+  label, value, onChange, length = 6, groups = [3, 3], error, onComplete, mode = 'single', onSubmit, focusKey, disabled,
+}: {
+  label: string;
+  value: string;
+  onChange: (next: string) => void;
+  length?: number;
+  /** Slot grouping, summing to `length`. The gap between groups is 16px; within, 6px. `single` only. */
+  groups?: number[];
+  error?: boolean;
+  onComplete?: (code: string) => void;
+  /**
+   * `slots` is the onboarding handoff's C9 (Two Factor): one real input per digit — 44×48, 18/600,
+   * named "Digit n of 6", `one-time-code`. Typing advances, Backspace on an empty slot goes back,
+   * ←/→ move, a paste fills every slot, Enter submits. `single` (default) is one input under a
+   * drawing of the slots.
+   */
+  mode?: 'single' | 'slots';
+  /** Enter, with every digit in (`slots`). */
+  onSubmit?: () => void;
+  /** Change it to move focus to the first slot — after an invalid code clears (`slots`). */
+  focusKey?: number;
+  disabled?: boolean;
+}) {
+  if (mode === 'slots') {
+    return <OtpSlots label={label} value={value} onChange={onChange} length={length} error={error} onComplete={onComplete} onSubmit={onSubmit} focusKey={focusKey} disabled={disabled} />;
+  }
+  return <OtpSingle label={label} value={value} onChange={onChange} length={length} groups={groups} error={error} onComplete={onComplete} />;
+}
+
+function OtpSlots({
+  label, value, onChange, length, error, onComplete, onSubmit, focusKey, disabled,
+}: {
+  label: string; value: string; onChange: (next: string) => void; length: number; error?: boolean;
+  onComplete?: (code: string) => void; onSubmit?: () => void; focusKey?: number; disabled?: boolean;
+}) {
+  const { colors } = useDs();
+  const refs = useRef<(TextInput | null)[]>([]);
+  const digits = Array.from({ length }, (_, i) => value[i] ?? '');
+  const focusNow = (i: number) => refs.current[Math.max(0, Math.min(length - 1, i))]?.focus();
+  const focus = (i: number) => setTimeout(() => focusNow(i), 0);
+  const first = useRef(true);
+  useEffect(() => {
+    if (first.current) { first.current = false; return; }
+    focus(0);
+  }, [focusKey]);
+
+  const write = (code: string[]) => {
+    const next = code.join('');
+    onChange(next);
+    if (code.every(Boolean)) onComplete?.(next);
+  };
+
+  return (
+    <Box row role="group" aria-label={label} alignSelf="stretch" style={{ gap: 6, maxWidth: length * 44 + (length - 1) * 6 }}>
+      {digits.map((d, i) => (
+        /* 44px each, shrinking together on a narrow screen so the code stays on one line. */
+        <Box key={i} style={{ flexGrow: 1, flexShrink: 1, flexBasis: 44, maxWidth: 44, minWidth: 34 }}>
+          <Input
+            ref={el => { refs.current[i] = el; }}
+            value={d}
+            numeric
+            oneTimeCode
+            disabled={disabled}
+            maxLength={length}
+            error={error}
+            aria-invalid={error}
+            aria-label={`Digit ${i + 1} of ${length}`}
+            onChangeText={raw => {
+              const typed = raw.replace(/\D/g, '');
+              const code = digits.slice();
+              if (!typed) { code[i] = ''; write(code); return; }
+              /* A key pressed in a filled slot arrives beside the digit already there (the caret sits
+                 after it): keep that digit, and carry the new ones on into the next slots. A single
+                 digit (the slot's text replaced) takes the slot. */
+              let k = i;
+              let rest = typed;
+              if (d && typed.length > 1 && typed.includes(d)) { k = i + 1; rest = typed.replace(d, ''); }
+              for (const ch of rest) { if (k >= length) break; code[k++] = ch; }
+              write(code);
+              focusNow(Math.min(length - 1, k));
+            }}
+            onKey={key => {
+              if (key === 'Backspace' && !digits[i] && i > 0) {
+                const code = digits.slice();
+                code[i - 1] = '';
+                write(code);
+                focusNow(i - 1);
+              } else if (key === 'ArrowLeft') focusNow(i - 1);
+              else if (key === 'ArrowRight') focusNow(i + 1);
+            }}
+            onSubmit={() => { if (digits.every(Boolean)) onSubmit?.(); }}
+            style={{ height: 48, paddingVertical: 0, paddingHorizontal: 0, textAlign: 'center', fontSize: 18, fontWeight: '600', backgroundColor: d ? colors.surfaceSunken : colors.surface1 }}
+          />
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+function OtpSingle({
+  label, value, onChange, length, groups, error, onComplete,
+}: {
+  label: string; value: string; onChange: (next: string) => void; length: number; groups: number[]; error?: boolean; onComplete?: (code: string) => void;
+}) {
+  const { colors } = useDs();
+  const [focused, setFocused] = useState(false);
+  const active = Math.min(value.length, length - 1);
+  let offset = 0;
+
+  return (
+    <Box alignSelf="flex-start" style={{ position: 'relative' }}>
+      <Box row gap="s4" aria-hidden>
+        {groups.map((n, g) => {
+          const start = offset;
+          offset += n;
+          return (
+            <Box key={g} row style={{ gap: 6 }}>
+              {Array.from({ length: n }, (_, k) => {
+                const i = start + k;
+                const isActive = focused && i === active;
+                return (
+                  <Box
+                    key={i}
+                    width={30}
+                    height={40}
+                    align="center"
+                    justify="center"
+                    style={{
+                      borderRadius: blockRadii.inset,
+                      backgroundColor: colors.surface1,
+                      boxShadow: isActive
+                        ? `0 0 0 2px ${colors.accentFill}`
+                        : `0 0 0 1px ${error ? colors.status.needsUser : colors.hairlineStrong}`,
+                    }}>
+                    <Text numeric style={{ fontSize: 17, fontWeight: '600', color: colors.textPrimary }}>{value[i] ?? ''}</Text>
+                  </Box>
+                );
+              })}
+            </Box>
+          );
+        })}
+      </Box>
+      <Input
+        value={value}
+        onChangeText={raw => {
+          const next = raw.replace(/\D/g, '').slice(0, length);
+          onChange(next);
+          if (next.length === length) onComplete?.(next);
+        }}
+        onFocus={() => setFocused(true)}
+        onBlur={() => setFocused(false)}
+        numeric
+        oneTimeCode
+        maxLength={length}
+        aria-label={label}
+        aria-invalid={error}
+        style={{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, opacity: 0, boxShadow: 'none' }}
+      />
+    </Box>
+  );
+}
+
+/* ── C11 · Tag input ─────────────────────────────────────────────────────── */
+
+/**
+ * **Chips plus a field.** Enter or a comma adds (trimmed, no duplicates, at most `max`); Backspace
+ * in an empty field removes the last chip. Each chip's remove button is named "Remove {tag}".
+ */
+export function TagInput({
+  label, value, onChange, max = 5, placeholder = 'Add a tag', variant = 'outline', draft: draftProp, onDraftChange, error, helper, disabled,
+}: {
+  label: string;
+  value: string[];
+  onChange: (next: string[]) => void;
+  max?: number;
+  placeholder?: string;
+  /**
+   * `filled` is the onboarding handoff's C11 (Tag Creation): 28px tags on the line-soft ground with
+   * 24px remove buttons, tags adding and leaving with M14 (opacity and −6px), and the field's own
+   * edge. A duplicate is kept in the field (the caller shows `error`) rather than silently cleared.
+   */
+  variant?: 'outline' | 'filled';
+  /** Controlled draft text. */
+  draft?: string;
+  onDraftChange?: (text: string) => void;
+  /** Shown under the field in apricot; the edge turns apricot. */
+  error?: string;
+  /** The line under the field — "Press Enter or comma to add · 3 of 10". Announced when it changes. */
+  helper?: string;
+  disabled?: boolean;
+}) {
+  const { colors, density } = useDs();
+  const [ownDraft, setOwnDraft] = useState('');
+  const draft = draftProp ?? ownDraft;
+  const setDraft = (t: string) => { setOwnDraft(t); onDraftChange?.(t); };
+  const field = useRef<TextInput>(null);
+  const full = value.length >= max;
+  const filled = variant === 'filled';
+  const [leaving, setLeaving] = useState<string[]>([]);
+  const helpId = useRef(`tags-${Math.random().toString(36).slice(2, 8)}`).current;
+
+  const add = (raw: string) => {
+    const tag = raw.trim();
+    const dup = value.some(v => v.toLowerCase() === tag.toLowerCase());
+    if (filled && dup) { setDraft(tag); return; }
+    setDraft('');
+    if (!tag || full || dup) return;
+    onChange([...value, tag]);
+  };
+  const remove = (tag: string) => {
+    if (filled) setLeaving(l => [...l, tag]);
+    else onChange(value.filter(v => v !== tag));
+    field.current?.focus();
+  };
+
+  const body = (
+    <Box
+      row
+      wrap
+      align="center"
+      gap="s2"
+      p="s2"
+      role="group"
+      aria-label={label}
+      style={filled ? {
+        minHeight: density.controlH, paddingVertical: 4, paddingHorizontal: 8, borderRadius: blockRadii.inset,
+        boxShadow: error ? `0 0 0 1px ${colors.status.needsUser}, 0 0 0 4px ${colors.statusBg.needsUser}` : `0 0 0 1px ${colors.hairlineStrong}`,
+        backgroundColor: full || disabled ? colors.surfaceSunken : colors.surface1,
+      } : { borderRadius: blockRadii.inset, boxShadow: `0 0 0 1px ${colors.hairlineStrong}`, backgroundColor: colors.surface1 }}>
+      {value.map(tag => filled ? (
+        <FilledTag
+          key={tag}
+          tag={tag}
+          leaving={leaving.includes(tag)}
+          disabled={disabled}
+          onRemove={() => remove(tag)}
+          onGone={() => { setLeaving(l => l.filter(x => x !== tag)); onChange(value.filter(v => v !== tag)); }}
+        />
+      ) : (
+        <Box
+          key={tag}
+          row
+          align="center"
+          gap="s1"
+          height={26}
+          radius="pill"
+          style={{ paddingLeft: 10, paddingRight: 4, boxShadow: `0 0 0 1px ${colors.hairlineStrong}` }}>
+          <Text variant="caption" numberOfLines={1} style={{ fontSize: 12, fontWeight: '600', color: colors.textPrimary, maxWidth: 180 }}>{tag}</Text>
+          <Pressable
+            aria-label={`Remove ${tag}`}
+            onPress={() => remove(tag)}
+            width={18}
+            height={18}
+            radius="pill">
+            <Icon name="close" size={11} color={colors.textSecondary} />
+          </Pressable>
+        </Box>
+      ))}
+      <Box style={filled ? { flexGrow: 1, flexShrink: 1, flexBasis: 120, minWidth: 96 } : { flex: 1, minWidth: 96 }}>
+        <Input
+          ref={field}
+          value={draft}
+          disabled={disabled || (filled && full)}
+          onChangeText={t => (t.includes(',') ? add(t.replace(/,/g, '')) : setDraft(t))}
+          onSubmit={() => add(draft)}
+          onKey={key => {
+            if (key !== 'Backspace' || draft !== '' || !value.length) return;
+            if (filled) remove(value[value.length - 1]!);
+            else onChange(value.slice(0, -1));
+          }}
+          placeholder={full ? (filled ? '' : `${max} of ${max}`) : placeholder}
+          aria-label={label}
+          aria-invalid={Boolean(error)}
+          aria-describedby={filled && (error || helper) ? helpId : undefined}
+          style={{ boxShadow: 'none', paddingVertical: 4, paddingHorizontal: 4, backgroundColor: 'transparent' }}
+        />
+      </Box>
+    </Box>
+  );
+  if (!filled) return body;
+  return (
+    <Box gap="s1">
+      {body}
+      <Box role="status" aria-live="polite">
+        <Text nativeID={helpId} variant="caption" style={{ fontSize: 12, color: error ? colors.status.needsUser : colors.textSecondary }}>{error ?? helper ?? ''}</Text>
+      </Box>
+    </Box>
+  );
+}
+
+/** A `filled` tag: 28px on line-soft, 12/600, a 24px round remove button; M14 in and out. */
+function FilledTag({ tag, leaving, disabled, onRemove, onGone }: { tag: string; leaving: boolean; disabled?: boolean; onRemove: () => void; onGone: () => void }) {
+  const { colors } = useDs();
+  const presence = usePresence(!leaving, { speed: 'list', appear: true });
+  useEffect(() => { if (leaving && !presence.mounted) onGone(); }, [leaving, presence.mounted]);
+  if (!presence.mounted) return null;
+  return (
+    <MotionView aria-hidden={leaving || undefined} style={{ opacity: presence.opacity, transform: [{ translateY: presence.translateY }] }}>
+      <Box row align="center" gap="s1" height={28} radius="pill" style={{ paddingLeft: 10, paddingRight: 2, backgroundColor: colors.band }}>
+        <Text variant="caption" numberOfLines={1} style={{ fontSize: 12, fontWeight: '600', color: colors.textPrimary, maxWidth: 180 }}>{tag}</Text>
+        <Pressable aria-label={`Remove ${tag}`} onPress={onRemove} disabled={disabled || leaving} width={24} height={24} radius="pill">
+          <Icon name="close" size={12} color={colors.textSecondary} />
+        </Pressable>
+      </Box>
+    </MotionView>
+  );
+}
+
+/* ── C12 · Colour field ──────────────────────────────────────────────────── */
+
+const HEX = /^#[0-9A-Fa-f]{6}$/;
+
+/** True for exactly `#RRGGBB`. The only form the field accepts. */
+export const isHexColor = (v: string) => HEX.test(v);
+
+/**
+ * **A 24px swatch and a mono hex field.** Only a complete `#RRGGBB` reaches `onChange`; anything
+ * else stays in the field as a draft and the swatch keeps the last good colour — a swatch that
+ * went blank on every keystroke would flash while the user types.
+ *
+ * Validation (onboarding B2): uppercase, at most 7 characters, tabular. Once the field has been
+ * **touched** and holds an invalid value, the edge turns apricot and the message says how to fix
+ * it: "Use a 6-digit hex, like #1F6FEB". `text`/`onChangeText`/`touched` let a caller own the raw
+ * text (a saved draft that ships invalid); without them the field keeps its own draft.
+ *
+ * The swatch paints the USER'S value, which is data, not a token: the one colour in the library
+ * that is legitimately not from the palette.
+ */
+export function ColorField({
+  label, value, onChange, text, onChangeText, touched: touchedProp, onBlur, showLabel = false, fluid = false, message,
+}: {
+  label: string;
+  /** The last valid colour — what the swatch paints. */
+  value: string;
+  onChange: (hex: string) => void;
+  /** Controlled raw text. Omit to let the field keep its own draft. */
+  text?: string;
+  onChangeText?: (raw: string, valid: boolean) => void;
+  /** Controlled "touched". Default: touched after the first edit or blur. */
+  touched?: boolean;
+  onBlur?: () => void;
+  /** Draw the label above the field (12/600). Otherwise it is the accessible name only. */
+  showLabel?: boolean;
+  /** Fill the width available instead of the fixed 120px field. */
+  fluid?: boolean;
+  /** The invalid message. Default "Use a 6-digit hex, like #1F6FEB". */
+  message?: string;
+}) {
+  const { colors } = useDs();
+  const [ownDraft, setOwnDraft] = useState(value);
+  const [ownTouched, setOwnTouched] = useState(false);
+  useEffect(() => { if (text === undefined) setOwnDraft(value); }, [value, text]);
+  const draft = text ?? ownDraft;
+  const touched = touchedProp ?? ownTouched;
+  const invalid = !isHexColor(draft);
+  const showError = touched && invalid;
+  const msgId = useRef(`cf-${Math.random().toString(36).slice(2, 8)}`).current;
+
+  return (
+    <Box gap="s1" alignSelf={fluid ? 'stretch' : 'flex-start'} style={fluid ? { minWidth: 0 } : undefined}>
+      {showLabel ? <Text variant="caption" color="textPrimary" style={{ fontSize: 12, fontWeight: '600' }}>{label}</Text> : null}
+      <Box row align="center" gap="s2">
+        {/* The swatch is the colour picker (web: the browser's; native: a sheet of the hues). A pick
+            is a complete, valid value, so it reaches onChange at once and replaces any draft. */}
+        <ColorSwatch
+          value={value}
+          label={label}
+          onPick={hex => {
+            setOwnDraft(hex);
+            setOwnTouched(true);
+            onChangeText?.(hex, true);
+            onChange(hex);
+          }}
+        />
+        <Box style={fluid ? { flex: 1, minWidth: 0 } : { width: 120 }}>
+          <Input
+            value={draft}
+            mono
+            maxLength={7}
+            error={showError}
+            aria-invalid={showError}
+            aria-describedby={showError ? msgId : undefined}
+            aria-label={label}
+            onBlur={() => { setOwnTouched(true); onBlur?.(); }}
+            onChangeText={t => {
+              const next = (t.startsWith('#') ? t : `#${t}`).toUpperCase().slice(0, 7);
+              const ok = isHexColor(next);
+              setOwnDraft(next);
+              setOwnTouched(true);
+              onChangeText?.(next, ok);
+              if (ok) onChange(next);
+            }}
+          />
+        </Box>
+      </Box>
+      {showError ? (
+        <Text nativeID={msgId} variant="caption" style={{ fontSize: 12, color: colors.status.needsUser }}>
+          {message ?? `Use a 6-digit hex, like ${HEX_EXAMPLE_VALUE}`}
+        </Text>
+      ) : null}
+    </Box>
+  );
+}