@appinternalleads/ui 0.2.0

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

@@ -0,0 +1,171 @@
+import {
+  stageErrors, type ThresholdFlowConfig, type ThresholdFlowDocument, type ThresholdItem,
+} from './contract';
+
+/**
+ * **The ThresholdFlow state machine — pure, no React, no timers.**
+ *
+ * ```
+ *            activate (valid, non-empty)            resolve ok
+ *  editing ───────────────────────────▶ activating ───────────▶ live
+ *     ▲                                    │                     │
+ *     │ edit                               │ resolve fail        │ edit
+ *     │                                    ▼                     │
+ *     └──────────────────────────────── error ◀──────────────────┘ (via editing)
+ *                  activate (retry) ───────┘
+ * ```
+ *
+ * One `phase` field instead of `isLive`/`isActivating`/`isError` booleans that can disagree.
+ * `activating` and `live` LOCK the stages: every edit action is refused in them. `error` does not —
+ * the point of the error is that the person fixes something and tries again.
+ *
+ * **Stale results are refused by attempt number.** Each `activate` increments `attempt`, and a
+ * `resolve` carrying an older attempt is ignored — so a slow first attempt that lands after a retry
+ * cannot overwrite the retry's outcome. (The operations runner also aborts the superseded call;
+ * this is the second guard, and the one a test can prove without a clock.)
+ */
+
+export type ThresholdPhase = 'editing' | 'activating' | 'live' | 'error';
+
+/** A stage being edited. `value` is `null` while its field is empty. `leaving` is mid-exit (M2). */
+export type DraftStage = {
+  id: string;
+  title: string;
+  role?: string;
+  value: number | null;
+  toggle: boolean;
+  leaving?: boolean;
+};
+
+export type ActivationFailure = { message: string; stageId?: string };
+
+export type ThresholdFlowState = {
+  phase: ThresholdPhase;
+  stages: DraftStage[];
+  /** Monotonic, per flow — added stages get `${slug}-${nextId}`. Never `Date.now()`. */
+  nextId: number;
+  attempt: number;
+  error: ActivationFailure | null;
+};
+
+export type ThresholdAction =
+  | { type: 'edit-value'; id: string; raw: string }
+  | { type: 'toggle'; id: string }
+  | { type: 'add' }
+  | { type: 'remove'; id: string; immediate?: boolean }
+  | { type: 'drop'; id: string }
+  | { type: 'activate' }
+  | { type: 'resolve'; attempt: number; outcome: { ok: true } | ({ ok: false } & ActivationFailure) }
+  | { type: 'edit-flow' }
+  | { type: 'reset'; doc: ThresholdFlowDocument };
+
+export function slug(title: string): string {
+  return String(title).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'stage';
+}
+
+/**
+ * The seed a flow opens with. `initial` restores a session — a story, a preview, a flow reopened
+ * live — and is never part of the document.
+ */
+export type ThresholdFlowSeed = {
+  phase?: Exclude<ThresholdPhase, 'activating'>;
+  error?: ActivationFailure;
+  /** Override stage values by id — `null` for an emptied field. */
+  values?: Record<string, number | null>;
+};
+
+export function initialState(doc: ThresholdFlowDocument, seed: ThresholdFlowSeed = {}): ThresholdFlowState {
+  return {
+    phase: seed.phase ?? 'editing',
+    stages: doc.props.defaultItems.map(i => ({
+      id: i.id,
+      title: i.title,
+      ...(i.role !== undefined ? { role: i.role } : {}),
+      value: seed.values && i.id in seed.values ? seed.values[i.id]! : i.value,
+      toggle: doc.props.toggleLabel ? Boolean(i.toggle) : false,
+    })),
+    nextId: 1,
+    attempt: 0,
+    error: seed.phase === 'error' ? (seed.error ?? { message: '' }) : null,
+  };
+}
+
+/** The stages that count — not mid-exit. */
+export const liveStages = (s: ThresholdFlowState) => s.stages.filter(x => !x.leaving);
+
+export const isLocked = (s: ThresholdFlowState) => s.phase === 'activating' || s.phase === 'live';
+
+/** Per-stage messages, derived. */
+export function errorsOf(s: ThresholdFlowState, config: ThresholdFlowConfig): Record<string, string> {
+  return stageErrors(liveStages(s), config.unit);
+}
+
+export function canAdd(s: ThresholdFlowState, config: ThresholdFlowConfig): boolean {
+  const n = liveStages(s).length;
+  return !isLocked(s) && (config.templates?.length ?? 0) > n;
+}
+
+export function canActivate(s: ThresholdFlowState, config: ThresholdFlowConfig): boolean {
+  return (s.phase === 'editing' || s.phase === 'error')
+    && liveStages(s).length > 0
+    && Object.keys(errorsOf(s, config)).length === 0;
+}
+
+/**
+ * The stages as the host receives them — numbers, no leaving rows, no empty fields. Only called
+ * on a flow that `canActivate`, so every value is a number; the filter is belt-and-braces.
+ */
+export function itemsOf(s: ThresholdFlowState): ThresholdItem[] {
+  return liveStages(s)
+    .filter((x): x is DraftStage & { value: number } => x.value !== null)
+    .map(x => ({ id: x.id, title: x.title, ...(x.role !== undefined ? { role: x.role } : {}), value: x.value, toggle: x.toggle }));
+}
+
+/** Digits only, at most 9 — the prototype's input rule. Empty is `null`, not 0. */
+export function parseValue(raw: string): number | null {
+  const digits = raw.replace(/[^0-9]/g, '').slice(0, 9);
+  return digits === '' ? null : Number(digits);
+}
+
+export function reduce(config: ThresholdFlowConfig, s: ThresholdFlowState, a: ThresholdAction): ThresholdFlowState {
+  const editable = !isLocked(s);
+  const patch = (id: string, fn: (x: DraftStage) => DraftStage) => ({ ...s, stages: s.stages.map(x => (x.id === id ? fn(x) : x)) });
+
+  switch (a.type) {
+    case 'edit-value':
+      return editable ? patch(a.id, x => ({ ...x, value: parseValue(a.raw) })) : s;
+    case 'toggle':
+      return editable && config.toggleLabel ? patch(a.id, x => ({ ...x, toggle: !x.toggle })) : s;
+    case 'add': {
+      if (!canAdd(s, config)) return s;
+      const t = config.templates![liveStages(s).length]!;
+      const stage: DraftStage = {
+        id: `${slug(t.title)}-${s.nextId}`,
+        title: t.title,
+        ...(t.role !== undefined ? { role: t.role } : {}),
+        value: t.value,
+        toggle: config.toggleLabel ? Boolean(t.toggle) : false,
+      };
+      return { ...s, stages: [...s.stages, stage], nextId: s.nextId + 1 };
+    }
+    case 'remove':
+      if (!editable) return s;
+      return a.immediate
+        ? { ...s, stages: s.stages.filter(x => x.id !== a.id) }
+        : patch(a.id, x => ({ ...x, leaving: true }));
+    case 'drop':
+      return { ...s, stages: s.stages.filter(x => x.id !== a.id) };
+    case 'activate':
+      if (!canActivate(s, config)) return s;
+      return { ...s, phase: 'activating', attempt: s.attempt + 1, error: null };
+    case 'resolve':
+      if (s.phase !== 'activating' || a.attempt !== s.attempt) return s; // stale or superseded
+      return a.outcome.ok
+        ? { ...s, phase: 'live', error: null }
+        : { ...s, phase: 'error', error: { message: a.outcome.message, ...(a.outcome.stageId ? { stageId: a.outcome.stageId } : {}) } };
+    case 'edit-flow':
+      return s.phase === 'live' ? { ...s, phase: 'editing' } : s;
+    case 'reset':
+      return initialState(a.doc);
+  }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * **ThresholdFlow — the third component family.** Ordered stages with strictly increasing
+ * thresholds, an optional switch per stage, and an activation the host performs. Portable as a
+ * `threshold-flow/1` document (`spec/families/threshold-flow.schema.json`). Design:
+ * `docs/components/threshold-flow/THRESHOLD-FLOW.md`.
+ */
+export {
+  THRESHOLD_FLOW_SCHEMA, MAX_STAGES, DEFAULT_NOUN,
+  answerOf, copyFor, formatValue, nounFor, stageErrors, validateThresholdFlow,
+  type ThresholdFlowConfig, type ThresholdFlowCopy, type ThresholdFlowDocument, type ThresholdFlowIssue,
+  type ThresholdItem, type ThresholdTemplate, type ThresholdUnit,
+} from './contract';
+export {
+  canActivate, canAdd, errorsOf, initialState, isLocked, itemsOf, liveStages, parseValue, reduce, slug,
+  type ActivationFailure, type DraftStage, type ThresholdAction, type ThresholdFlowSeed,
+  type ThresholdFlowState, type ThresholdPhase,
+} from './engine';
+export {
+  useThresholdFlow,
+  type ThresholdActivation, type ThresholdActivationResult, type ThresholdFlowOperations, type ThresholdFlowRuntime,
+} from './runtime';
+export {
+  createMockThresholdOperations, CASE_STUDY_REFUSALS, THRESHOLD_LATENCY,
+  type MockThresholdOperationsOptions,
+} from './mock';
+export { ThresholdFlowView, type ThresholdFlowViewProps } from './ThresholdFlowView';

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

@@ -0,0 +1,66 @@
+import { abortableDelay, resolveLatency } from '../../runtime/operations';
+import type {
+  ThresholdActivation, ThresholdActivationResult, ThresholdFlowOperations,
+} from './runtime';
+
+/**
+ * **The deterministic mock activation — every timer in the ThresholdFlow family lives here.**
+ *
+ * The same constraint `createMockChecklistOperations` inherits: latency is a number or a function
+ * of the request and the 0-based call index, failure is a predicate, and there is no `Math.random`
+ * and no `Date.now`. A test that can make call 1 slower than call 2 can *prove* a superseded
+ * activation is discarded; a random one could only prove it usually is.
+ */
+
+/** The prototype's own activation time, and two presets either side of it. */
+export const THRESHOLD_LATENCY = { fast: 120, normal: 1400, slow: 4000 } as const;
+
+export type MockThresholdOperationsOptions = {
+  latencyMs?: number | ((req: ThresholdActivation, callIndex: number) => number);
+  /**
+   * Refuse this call. Return a refusal (with the message and, optionally, the stage it concerns)
+   * or `null` to let it through. Deterministic by construction — a function of the call.
+   */
+  refuse?: (req: ThresholdActivation, callIndex: number) => { message: string; stageId?: string } | null;
+  /** Throw instead of refusing — a transport failure rather than a business refusal. */
+  throwWhen?: (req: ThresholdActivation, callIndex: number) => boolean;
+  onCall?: (req: ThresholdActivation, callIndex: number) => void;
+};
+
+export function createMockThresholdOperations(opts: MockThresholdOperationsOptions = {}): ThresholdFlowOperations {
+  let calls = 0;
+  return {
+    activate: async (req, { signal }): Promise<ThresholdActivationResult> => {
+      const callIndex = calls++;
+      opts.onCall?.(req, callIndex);
+      await abortableDelay(resolveLatency(opts.latencyMs, req, callIndex), signal);
+      if (opts.throwWhen?.(req, callIndex)) throw new Error('The activation could not be sent.');
+      const refusal = opts.refuse?.(req, callIndex);
+      return refusal ? { ok: false, ...refusal } : { ok: true };
+    },
+  };
+}
+
+/**
+ * **The four case studies' refusals, verbatim from the handoff** — the error each study's
+ * prototype shows, and the stage it names. Keyed by document `key`. Kept here rather than in the
+ * fixtures because a refusal is the HOST'S answer, not part of the document.
+ */
+export const CASE_STUDY_REFUSALS: Record<string, { message: string; stageId: string }> = {
+  refund_approval: {
+    message: 'The Finance team has no approvers assigned, so refunds over $2,000 would never be paid out. Add an approver or turn on auto-approve for that stage, then try again.',
+    stageId: 'finance-review',
+  },
+  resume_shortlisting: {
+    message: 'The interview panel has no interviewers assigned, so candidates scoring 85 or more would stall. Assign an interviewer or turn on auto-advance for that stage, then try again.',
+    stageId: 'final-interview',
+  },
+  alert_escalation: {
+    message: 'Nobody is scheduled on the backup rotation this week, so unresolved alerts would skip straight to the manager. Add someone to the rotation or remove that level, then try again.',
+    stageId: 'secondary-on-call',
+  },
+  usage_alerts: {
+    message: 'This workspace has no admin email, so warnings at 75% would reach nobody. Add an admin email or turn off emails for that level, then try again.',
+    stageId: 'warn',
+  },
+};

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

@@ -0,0 +1,116 @@
+import { useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
+import { useOperationRunner } from '../../runtime/operations';
+import type { ThresholdFlowDocument, ThresholdItem } from './contract';
+import {
+  canActivate, canAdd, errorsOf, initialState, isLocked, itemsOf, reduce,
+  type ThresholdAction, type ThresholdFlowSeed, type ThresholdFlowState,
+} from './engine';
+
+/**
+ * **The ThresholdFlow runtime** — `Document → engine → runtime → View`.
+ *
+ * It owns the reducer and the ONE boundary operation, activation, through
+ * `src/runtime/operations` — the same runner Checklist and the File Upload engine use. Every
+ * timer lives in the host's operation (or `mock.ts`); the view never waits on anything.
+ *
+ * Without `operations` the flow is local-only: Activate goes live at once, because there is
+ * nothing to ask. That is a real mode (a builder previewing its own flow), not a stub.
+ */
+
+/** What the host is asked to do on Activate. */
+export type ThresholdActivation = { key: string; items: ThresholdItem[] };
+
+/**
+ * The host's answer. A refusal can name the stage it is about, which the view marks — "the
+ * Finance team has no approvers" points at the Finance stage. A thrown error is also a refusal,
+ * with its message; an abort (unmount, superseded retry) is neither and changes nothing.
+ */
+export type ThresholdActivationResult = { ok: true } | { ok: false; message: string; stageId?: string };
+
+export type ThresholdFlowOperations = {
+  activate: (req: ThresholdActivation, ctx: { signal: AbortSignal }) => Promise<ThresholdActivationResult>;
+};
+
+export type ThresholdFlowRuntime = {
+  state: ThresholdFlowState;
+  errors: Record<string, string>;
+  canAdd: boolean;
+  canActivate: boolean;
+  locked: boolean;
+  dispatch: (a: ThresholdAction) => void;
+  activate: () => void;
+};
+
+export function useThresholdFlow({
+  doc, operations, initial, onChange, onActivate,
+}: {
+  doc: ThresholdFlowDocument;
+  operations?: ThresholdFlowOperations;
+  initial?: ThresholdFlowSeed;
+  /** The stages as numbers, every time they change. */
+  onChange?: (items: ThresholdItem[]) => void;
+  /** Fires once per successful activation, with the stages that went live. */
+  onActivate?: (items: ThresholdItem[]) => void;
+}): ThresholdFlowRuntime {
+  const config = doc.props;
+  const [state, send] = useReducer(
+    (s: ThresholdFlowState, a: ThresholdAction) => reduce(config, s, a),
+    undefined,
+    () => initialState(doc, initial),
+  );
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const runner = useOperationRunner();
+
+  /* Reseed only when the document genuinely changes — the same rule `useChecklistRuntime` states:
+     a parent that re-renders with an equal document must not wipe the person's edits. */
+  const seeded = useRef(JSON.stringify(doc));
+  useEffect(() => {
+    const next = JSON.stringify(doc);
+    if (next === seeded.current) return;
+    seeded.current = next;
+    runner.cancel('activate');
+    send({ type: 'reset', doc });
+  }, [doc, runner]);
+
+  /* Report the stages as numbers whenever the live set changes (not on a leaving flag). */
+  const items = useMemo(() => itemsOf(state), [state]);
+  const itemsKey = JSON.stringify(items);
+  const reported = useRef<string | null>(null);
+  useEffect(() => {
+    if (reported.current === itemsKey) return;
+    reported.current = itemsKey;
+    onChange?.(items);
+  }, [itemsKey, items, onChange]);
+
+  const activate = useCallback(() => {
+    const s = stateRef.current;
+    if (!canActivate(s, config)) return;
+    const attempt = s.attempt + 1;
+    const req: ThresholdActivation = { key: doc.key, items: itemsOf(s) };
+    send({ type: 'activate' });
+    if (!operations) {
+      send({ type: 'resolve', attempt, outcome: { ok: true } });
+      onActivate?.(req.items);
+      return;
+    }
+    runner.run('activate', ctx => operations.activate(req, { signal: ctx.signal }), {
+      onOk: result => {
+        send({ type: 'resolve', attempt, outcome: result });
+        if (result.ok) onActivate?.(req.items);
+      },
+      onError: error => send({ type: 'resolve', attempt, outcome: { ok: false, message: error.message } }),
+    });
+  }, [config, doc.key, operations, runner, onActivate]);
+
+  return {
+    state,
+    errors: errorsOf(state, config),
+    canAdd: canAdd(state, config),
+    canActivate: canActivate(state, config),
+    locked: isLocked(state),
+    dispatch: send,
+    activate,
+  };
+}
+

package/src/core/Arc.tsx

@@ -0,0 +1,93 @@
+import Svg, { Circle, Path } from 'react-native-svg';
+
+/**
+ * **Arcs, donuts and pies — the one thing CSS does with `conic-gradient` that RN cannot.**
+ *
+ * Three widgets in the input handoff (16 pie, 18 arc, 24 ring) specify their fill as a
+ * `conic-gradient`. React Native has no such gradient, so the geometry is drawn instead — and
+ * because it is drawn with `react-native-svg`, it lives HERE. `src/core/` and `src/tokens/` are
+ * the only places allowed to import a platform module; a widget reaching for SVG directly would
+ * put a renderer dependency two layers above where the invariant says it can be.
+ *
+ * Angles are **degrees clockwise from 12 o'clock**, which is what `conic-gradient(from …)`
+ * measures too, so a handoff value transfers without conversion.
+ */
+export type ArcSegment = {
+  /** Degrees of sweep. Zero-length segments are skipped rather than drawn as a dot. */
+  sweep: number;
+  color: string;
+};
+
+/** A point on the circle. 0° is 12 o'clock because that is where a gradient starts. */
+function pointAt(cx: number, cy: number, r: number, deg: number) {
+  const rad = ((deg - 90) * Math.PI) / 180;
+  return { x: cx + r * Math.cos(rad), y: cy + r * Math.sin(rad) };
+}
+
+function arcPath(cx: number, cy: number, r: number, from: number, to: number) {
+  const a = pointAt(cx, cy, r, from);
+  const b = pointAt(cx, cy, r, to);
+  const large = to - from > 180 ? 1 : 0;
+  return `M ${a.x} ${a.y} A ${r} ${r} 0 ${large} 1 ${b.x} ${b.y}`;
+}
+
+export type ArcProps = {
+  /** The full circle's diameter, even when only part of it is visible. */
+  size: number;
+  /** Ring width. Equal to `size / 2` draws a solid pie rather than a donut. */
+  thickness: number;
+  segments: ArcSegment[];
+  /** Degrees clockwise from 12 o'clock. `270` starts at 9 o'clock, as widget 18 does. */
+  startAngle?: number;
+  /**
+   * Height of the drawn box. A semicircular dial sets this to just over half the size and lets
+   * the rest fall outside the viewBox — the handoff's `overflow: hidden` viewport, expressed as
+   * a crop rather than a clip.
+   */
+  height?: number;
+  testID?: string;
+};
+
+export function Arc({
+  size, thickness, segments, startAngle = 0, height, testID,
+}: ArcProps) {
+  const r = (size - thickness) / 2;
+  const c = size / 2;
+  const h = height ?? size;
+
+  let cursor = startAngle;
+  const drawn = segments.map((s, i) => {
+    const from = cursor;
+    cursor += s.sweep;
+    if (s.sweep <= 0) return null;
+    /* A full turn has no two distinct endpoints, so it is a circle rather than an arc. */
+    if (s.sweep >= 359.999) {
+      return (
+        <Circle
+          key={i}
+          cx={c}
+          cy={c}
+          r={r}
+          stroke={s.color}
+          strokeWidth={thickness}
+          fill="none"
+        />
+      );
+    }
+    return (
+      <Path
+        key={i}
+        d={arcPath(c, c, r, from, from + s.sweep)}
+        stroke={s.color}
+        strokeWidth={thickness}
+        fill="none"
+      />
+    );
+  });
+
+  return (
+    <Svg width={size} height={h} viewBox={`0 0 ${size} ${h}`} testID={testID}>
+      {drawn}
+    </Svg>
+  );
+}

package/src/core/Box.tsx

@@ -0,0 +1,180 @@
+import type { ReactNode, Ref } from 'react';
+import { View, type LayoutChangeEvent, type StyleProp, type ViewStyle } from 'react-native';
+import { fieldEdge, outlineEdge, scrim, space, useDs } from '../tokens';
+import { groundFor, lineFor, radiusFor, type GroundToken, type LineToken, type RadiusToken } from './roles';
+
+type SpaceToken = keyof typeof space;
+
+export type BoxProps = {
+  children?: ReactNode;
+
+  /** Row instead of the RN default column. Named for the common case rather than `direction`. */
+  row?: boolean;
+  align?: ViewStyle['alignItems'];
+  /** How this box sits in its PARENT's cross axis. A pill shrinks to its text with `flex-start`. */
+  alignSelf?: ViewStyle['alignSelf'];
+  justify?: ViewStyle['justifyContent'];
+  wrap?: boolean;
+  flex?: number;
+  gap?: SpaceToken;
+
+  p?: SpaceToken; px?: SpaceToken; py?: SpaceToken;
+  pt?: SpaceToken; pr?: SpaceToken; pb?: SpaceToken; pl?: SpaceToken;
+  m?: SpaceToken; mx?: SpaceToken; my?: SpaceToken;
+  mt?: SpaceToken; mr?: SpaceToken; mb?: SpaceToken; ml?: SpaceToken;
+
+  bg?: GroundToken;
+  /**
+   * The ground behind a modal. Separate from `bg` because a scrim is not a surface — it is the
+   * absence of one, and it is the only translucent value the system has.
+   */
+  scrim?: 'default' | 'destructive';
+  radius?: RadiusToken;
+
+  /**
+   * Elevation. **1** rows, cards and sheets · **2** tab and nav bars · **3** dialogs.
+   *
+   * Read from the context rather than the module constants, because `lift1`/`lift2` are
+   * evaluated at import time — before an app has said which theme it wants — and so cannot
+   * follow it.
+   */
+  lift?: 1 | 2 | 3;
+  /** The field hairline, in its three states. A field never lifts, so this is not elevation. */
+  edge?: 'field' | 'fieldFocus' | 'fieldError' | 'outline';
+  /** A single-side rule. `lift`/`edge` already carry their own ring — see the note below. */
+  hairline?: { side: 'top' | 'bottom'; color?: LineToken };
+
+  width?: ViewStyle['width'];
+  height?: ViewStyle['height'];
+  minHeight?: ViewStyle['minHeight'];
+  opacity?: number;
+
+  /**
+   * The escape hatch, and it is narrow on purpose. Anything expressible through a prop above
+   * belongs there — a value inlined here is invisible to the generator and to the no-hex rule.
+   */
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+  /**
+   * The box this view actually got. Needed for container-query layout — a card that reads the
+   * VIEWPORT cannot know it is in a 400px side panel on a desktop.
+   */
+  onLayout?: (e: LayoutChangeEvent) => void;
+  role?:
+    | 'form' | 'group' | 'list' | 'listitem' | 'none' | 'progressbar' | 'region'
+    | 'radiogroup' | 'menu' | 'status' | 'alert' | 'img' | 'navigation' | 'tooltip';
+  /** A region whose changes a screen reader should announce — a status line, a toast. */
+  'aria-live'?: 'polite' | 'assertive' | 'off';
+  'aria-busy'?: boolean;
+  'aria-describedby'?: string;
+  /** Hidden from assistive technology — decoration, or a row mid-exit that is no longer real. */
+  'aria-hidden'?: boolean;
+  /** A progressbar's value in words — "86% · near limit" — when the number alone misleads. */
+  'aria-valuetext'?: string;
+  /** For measuring or focusing — a collapsible's inert body, a layer's anchor. */
+  ref?: Ref<View>;
+  /** The current item of a set — a stepper's current step. */
+  'aria-current'?: 'step' | 'page' | boolean;
+  /** An id, so another element can point at this one (`aria-controls`, `aria-describedby`). */
+  nativeID?: string;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  /** Only meaningful with `role="progressbar"` — a determinate progress value (0–100) and its
+      bounds. Forwarded as-is; react-native-web maps these to the DOM's own `aria-value*`. */
+  'aria-valuenow'?: number;
+  'aria-valuemin'?: number;
+  'aria-valuemax'?: number;
+};
+
+/**
+ * The layout primitive.
+ *
+ * **There is no `borderWidth` and no `borderColor`, and the absence is the point.** Every
+ * elevation in this system is a hairline plus two shadows where *the `0 0 0 1px` ring IS the
+ * border* — contract §2.5. A `border` alongside a `lift` draws the edge twice, and it is the
+ * most common way this material gets implemented wrong. `hairline` exists for the one legitimate
+ * case a shadow ring cannot express: a rule on a single side.
+ */
+export function Box({
+  children, row, align, alignSelf, justify, wrap, flex, gap,
+  p, px, py, pt, pr, pb, pl, m, mx, my, mt, mr, mb, ml,
+  bg, scrim: scrimTone, radius, lift, edge, hairline,
+  width, height, minHeight, opacity, style, testID, onLayout, role, nativeID,
+  'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy,
+  'aria-live': ariaLive, 'aria-busy': ariaBusy, 'aria-describedby': ariaDescribedBy,
+  'aria-hidden': ariaHidden, 'aria-valuetext': ariaValueText, 'aria-current': ariaCurrent, ref,
+  'aria-valuenow': ariaValueNow, 'aria-valuemin': ariaValueMin, 'aria-valuemax': ariaValueMax,
+}: BoxProps) {
+  const ds = useDs();
+  const s = (t?: SpaceToken) => (t === undefined ? undefined : space[t]);
+
+  const shadow =
+    lift === 3 ? ds.edge3
+    : lift === 2 ? ds.lift2
+    : lift === 1 ? ds.lift1
+    /* `fieldEdge` and `outlineEdge` are module constants rather than context fields, and
+       correctly so: a field's hairline is the same in every theme. Only the LIFTS are
+       theme-aware, which is why those three come off `ds`. */
+    : edge === 'field' ? fieldEdge.default
+    : edge === 'fieldFocus' ? fieldEdge.focus
+    : edge === 'fieldError' ? fieldEdge.error
+    : edge === 'outline' ? outlineEdge
+    : undefined;
+
+  return (
+    <View
+      ref={ref}
+      testID={testID}
+      onLayout={onLayout}
+      role={role}
+      nativeID={nativeID}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      aria-live={ariaLive}
+      aria-busy={ariaBusy}
+      aria-describedby={ariaDescribedBy}
+      aria-hidden={ariaHidden}
+      aria-valuetext={ariaValueText}
+      aria-current={ariaCurrent}
+      aria-valuenow={ariaValueNow}
+      aria-valuemin={ariaValueMin}
+      aria-valuemax={ariaValueMax}
+      style={[
+        {
+          flexDirection: row ? 'row' : 'column',
+          alignItems: align,
+          alignSelf,
+          justifyContent: justify,
+          flexWrap: wrap ? 'wrap' : undefined,
+          flex,
+          gap: s(gap),
+          padding: s(p),
+          paddingHorizontal: s(px),
+          paddingVertical: s(py),
+          paddingTop: s(pt),
+          paddingRight: s(pr),
+          paddingBottom: s(pb),
+          paddingLeft: s(pl),
+          margin: s(m),
+          marginHorizontal: s(mx),
+          marginVertical: s(my),
+          marginTop: s(mt),
+          marginRight: s(mr),
+          marginBottom: s(mb),
+          marginLeft: s(ml),
+          backgroundColor: scrimTone ? scrim[scrimTone] : bg ? groundFor(ds.colors, bg) : undefined,
+          borderRadius: radius ? radiusFor(radius) : undefined,
+          boxShadow: shadow,
+          width, height, minHeight, opacity,
+        },
+        hairline && {
+          [hairline.side === 'top' ? 'borderTopWidth' : 'borderBottomWidth']: 1,
+          [hairline.side === 'top' ? 'borderTopColor' : 'borderBottomColor']:
+            lineFor(ds.colors, hairline.color ?? 'hairline'),
+        },
+        style,
+      ]}>
+      {children}
+    </View>
+  );
+}