@appinternalleads/ui 0.2.0

package/src/ds/blockSequence.tsx

@@ -0,0 +1,340 @@
+import { useEffect, useRef, useState } from 'react';
+import type { ScrollView } from 'react-native';
+import { Box, Icon, MotionView, Pressable, Scroll, Text, useTween } from '../core';
+import { useDs } from '../tokens';
+import { MetaChip } from './blocks';
+
+/**
+ * **Solarium Building Blocks — sequence.** Q1 Vertical stepper · Q2 Horizontal timeline ·
+ * Q3 Dot pager · Q4 Step counter.
+ *
+ * **Always neutral — never hue-coded.** A sequence is progress through ONE thing, so every step is
+ * the same category; colouring steps would make them read as different kinds of work. This is also
+ * why Q1 is "not Solarium's hue-coded Step" (the handoff's own words): `solarium`'s `Step` is a
+ * different component with a different job.
+ */
+
+export type BlockStepState = 'done' | 'current' | 'pending' | 'attention';
+
+export type BlockStep = {
+  id: string;
+  label: string;
+  /** A second line — a date, a branch, "Sep 22". */
+  detail?: string;
+  state: BlockStepState;
+  /** A bold apricot line under the detail — "Delayed". `variant="track"` only. */
+  note?: string;
+};
+
+const STATE_WORD: Record<BlockStepState, string> = {
+  done: 'done', current: 'current step', pending: 'not started', attention: 'needs attention',
+};
+
+/** The 20px node — done is ink with a tick, current an ink ring with a dot, pending a hollow rim. */
+function Node({ state }: { state: BlockStepState }) {
+  const { colors } = useDs();
+  const ring = state === 'current' ? colors.textPrimary
+    : state === 'attention' ? colors.status.needsUser
+    : state === 'done' ? colors.textPrimary
+    : colors.controlBorder;
+  return (
+    <Box
+      width={20}
+      height={20}
+      align="center"
+      justify="center"
+      radius="pill"
+      style={{
+        borderWidth: 1.5,
+        borderColor: ring,
+        backgroundColor: state === 'done' ? colors.textPrimary
+          : state === 'attention' ? colors.statusBg.needsUser
+          : colors.surface1,
+      }}>
+      {state === 'done' ? <Icon name="check" size={11} color={colors.surface1} /> : null}
+      {state === 'current' ? <Box width={8} height={8} radius="pill" style={{ backgroundColor: colors.textPrimary }} /> : null}
+      {state === 'attention' ? <Icon name="alert" size={11} color={colors.status.needsUser} /> : null}
+    </Box>
+  );
+}
+
+/* ── Q1 · Vertical stepper ───────────────────────────────────────────────── */
+
+/**
+ * **Done, current, pending, attention — a list, not a picture of one.** Each step is a list item
+ * whose name includes its state ("Deploy, current step"), and the current one carries
+ * `aria-current="step"`, so a screen reader hears where the user is without seeing the ring.
+ */
+export function VerticalStepper({ label, steps }: { label: string; steps: BlockStep[] }) {
+  const { colors } = useDs();
+  return (
+    <Box role="list" aria-label={label}>
+      {steps.map((s, i) => (
+        <Box
+          key={s.id}
+          role="listitem"
+          aria-label={`${s.label}, ${STATE_WORD[s.state]}`}
+          aria-current={s.state === 'current' ? 'step' : undefined}
+          row
+          gap="s3"
+          style={{ minHeight: 44 }}>
+          <Box align="center" style={{ width: 20 }}>
+            <Node state={s.state} />
+            {i < steps.length - 1 ? (
+              <Box flex={1} style={{
+                width: 2, minHeight: 16, marginVertical: 2, borderRadius: 1,
+                backgroundColor: s.state === 'done' ? colors.textPrimary : colors.hairlineStrong,
+              }} />
+            ) : null}
+          </Box>
+          <Box flex={1} pb="s3" style={{ minWidth: 0 }}>
+            <Text
+              variant="caption"
+              color={s.state === 'pending' ? 'textSecondary' : 'textPrimary'}
+              style={{ fontWeight: s.state === 'current' ? '600' : '400', lineHeight: 20 }}>
+              {s.label}
+            </Text>
+            {s.detail ? <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{s.detail}</Text> : null}
+          </Box>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+/* ── Q2 · Horizontal timeline ────────────────────────────────────────────── */
+
+/** A column never narrower than this; past the container's width the timeline scrolls. */
+export const TIMELINE_MIN_COLUMN = 96;
+
+/**
+ * **Columns at least 96px wide; scrolls when they do not fit, and centres the current step.**
+ * The scroll is the container's, so a long shipment history never widens the page.
+ */
+export function Timeline({ label, steps, variant = 'centred' }: {
+  label: string;
+  steps: BlockStep[];
+  /**
+   * `track` — batch 3's Q2 (Shipping Update): an ordered list whose columns are at least 120px, the
+   * label left-aligned under a node, a connector to the next node whose ink fill grows (M6), and
+   * `attention` drawn as a 3px apricot-deep ring (a delay — no red). Default `centred`: as before.
+   */
+  variant?: 'centred' | 'track';
+}) {
+  if (variant === 'track') return <TrackTimeline label={label} steps={steps} />;
+  return <CentredTimeline label={label} steps={steps} />;
+}
+
+function CentredTimeline({ label, steps }: { label: string; steps: BlockStep[] }) {
+  const { colors } = useDs();
+  const scroll = useRef<ScrollView>(null);
+  const [width, setWidth] = useState(0);
+  const current = Math.max(0, steps.findIndex(s => s.state === 'current'));
+  const column = Math.max(TIMELINE_MIN_COLUMN, steps.length ? width / steps.length : TIMELINE_MIN_COLUMN);
+
+  useEffect(() => {
+    if (!width) return;
+    const x = current * column + column / 2 - width / 2;
+    scroll.current?.scrollTo({ x: Math.max(0, x), animated: false });
+  }, [width, current, column]);
+
+  return (
+    <Box onLayout={e => setWidth(e.nativeEvent.layout.width)} style={{ width: '100%' }}>
+      <Scroll horizontal ref={scroll}>
+        <Box row role="list" aria-label={label}>
+          {steps.map((s, i) => (
+            <Box
+              key={s.id}
+              role="listitem"
+              aria-label={`${s.label}${s.detail ? `, ${s.detail}` : ''}, ${STATE_WORD[s.state]}`}
+              aria-current={s.state === 'current' ? 'step' : undefined}
+              style={{ width: column }}
+              gap="s2">
+              <Box row align="center">
+                <Box flex={1} style={{ height: 2, backgroundColor: i === 0 ? 'transparent' : steps[i - 1]!.state === 'done' ? colors.textPrimary : colors.hairlineStrong }} />
+                <Node state={s.state} />
+                <Box flex={1} style={{ height: 2, backgroundColor: i === steps.length - 1 ? 'transparent' : s.state === 'done' ? colors.textPrimary : colors.hairlineStrong }} />
+              </Box>
+              <Box align="center" px="s1">
+                <Text
+                  variant="caption"
+                  align="center"
+                  numberOfLines={2}
+                  color={s.state === 'pending' ? 'textSecondary' : 'textPrimary'}
+                  style={{ fontWeight: s.state === 'current' ? '600' : '400', fontSize: 12 }}>
+                  {s.label}
+                </Text>
+                {s.detail ? <Text variant="caption" color="textSecondary" align="center" style={{ fontSize: 11 }}>{s.detail}</Text> : null}
+              </Box>
+            </Box>
+          ))}
+        </Box>
+      </Scroll>
+    </Box>
+  );
+}
+
+/** Q2 `track`: a column is never narrower than this — narrow screens scroll the list, not the page. */
+export const TRACK_MIN_COLUMN = 120;
+
+function TrackNode({ state }: { state: BlockStepState }) {
+  const { colors } = useDs();
+  const done = state === 'done';
+  return (
+    <Box
+      width={20}
+      height={20}
+      align="center"
+      justify="center"
+      radius="pill"
+      style={{
+        backgroundColor: done ? colors.textPrimary : colors.surface1,
+        borderWidth: done ? 0 : state === 'attention' ? 3 : state === 'current' ? 2 : 1.5,
+        borderColor: state === 'attention' ? colors.status.needsUser : state === 'current' ? colors.textPrimary : colors.hairlineStrong,
+      }}>
+      {done ? <Icon name="tick" size={12} color={colors.surface1} /> : null}
+      {state === 'current' ? <Box width={6} height={6} radius="pill" style={{ backgroundColor: colors.textPrimary }} /> : null}
+    </Box>
+  );
+}
+
+/** The connector after a node: a 2px track whose ink fill grows from the left (M6). */
+function TrackLine({ filled }: { filled: boolean }) {
+  const { colors } = useDs();
+  const k = useTween(filled ? 1 : 0);
+  return (
+    <Box flex={1} radius="pill" style={{ height: 2, marginHorizontal: 6, overflow: 'hidden', backgroundColor: colors.hairlineStrong }}>
+      <MotionView style={{ height: 2, width: k.interpolate({ inputRange: [0, 1], outputRange: ['0%', '100%'] }), backgroundColor: colors.textPrimary }} />
+    </Box>
+  );
+}
+
+function TrackTimeline({ label, steps }: { label: string; steps: BlockStep[] }) {
+  const { colors } = useDs();
+  const [width, setWidth] = useState(0);
+  const column = Math.max(TRACK_MIN_COLUMN, steps.length && width ? width / steps.length : TRACK_MIN_COLUMN);
+  return (
+    <Box onLayout={e => setWidth(e.nativeEvent.layout.width)} style={{ width: '100%' }}>
+      <Scroll horizontal>
+        <Box row role="list" aria-label={label}>
+          {steps.map((s, i) => (
+            <Box
+              key={s.id}
+              role="listitem"
+              aria-label={`${s.label}${s.detail ? `, ${s.detail}` : ''}, ${STATE_WORD[s.state]}${s.note ? `, ${s.note}` : ''}`}
+              aria-current={s.state === 'current' || s.state === 'attention' ? 'step' : undefined}
+              style={{ width: column }}
+              gap="s1">
+              <Box row align="center" style={{ marginBottom: 2 }}>
+                <TrackNode state={s.state} />
+                {i < steps.length - 1 ? <TrackLine filled={s.state === 'done'} /> : null}
+              </Box>
+              <Text
+                variant="caption"
+                color={s.state === 'pending' ? 'textSecondary' : 'textPrimary'}
+                style={{ fontSize: 13, paddingRight: 8, fontWeight: s.state === 'current' || s.state === 'attention' ? '700' : '600' }}>
+                {s.label}
+              </Text>
+              {s.detail ? <Text variant="caption" color="textSecondary" numeric style={{ fontSize: 12 }}>{s.detail}</Text> : null}
+              {s.note ? <Text variant="caption" style={{ fontSize: 12, fontWeight: '700', color: colors.status.needsUser }}>{s.note}</Text> : null}
+            </Box>
+          ))}
+        </Box>
+      </Scroll>
+    </Box>
+  );
+}
+
+/* ── Q3 · Dot pager ──────────────────────────────────────────────────────── */
+
+/** Past this many pages, a row of dots stops being countable — use `StepCounter`. */
+export const DOT_PAGER_MAX = 7;
+
+function PagerDot({ active, tone }: { active: boolean; tone: 'neutral' | 'accent' }) {
+  const { colors } = useDs();
+  /* Neutral: the active dot widens 6 → 18px. Accent (onboarding carousel): an 8px dot that
+     stretches to scaleX(2.5) and turns coral (M7). Both at `--motion-state`; reduced motion jumps. */
+  const w = useTween(active ? 18 : 6);
+  const k = useTween(active ? 2.5 : 1);
+  if (tone === 'accent') {
+    return (
+      <MotionView style={{
+        height: 8, width: 8, borderRadius: 4, transform: [{ scaleX: k }],
+        backgroundColor: active ? colors.accentFill : colors.hairlineStrong,
+      }} />
+    );
+  }
+  return (
+    <MotionView style={{
+      height: 6, width: w, borderRadius: 3,
+      backgroundColor: active ? colors.textPrimary : colors.controlBorder,
+    }} />
+  );
+}
+
+/**
+ * **A dot per page; the active one widens.** Each dot is a target named "Page 3 of 5" (or the
+ * caller's `itemLabel`), the active one `aria-current`. Over `DOT_PAGER_MAX` pages this warns in
+ * development and still renders — the fix is the caller's (switch to `StepCounter`).
+ *
+ * `tone="accent"` is the onboarding carousel's pager (decision D14): 28×24 targets, an 8px dot, the
+ * active one coral and stretched. Neutral stays the default — the Building Blocks rule that a
+ * sequence is never hue-coded holds everywhere else.
+ */
+export function DotPager({
+  label, count, index, onChange, tone = 'neutral', itemLabel,
+}: {
+  label: string;
+  count: number;
+  index: number;
+  onChange: (next: number) => void;
+  tone?: 'neutral' | 'accent';
+  /** A dot's name. Default "Page 2 of 4". */
+  itemLabel?: (i: number, count: number) => string;
+}) {
+  if (count > DOT_PAGER_MAX && typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+    console.warn(`[DotPager] ${count} pages is past ${DOT_PAGER_MAX} — use StepCounter.`);
+  }
+  return (
+    <Box row align="center" role="group" aria-label={label} alignSelf="center" wrap>
+      {Array.from({ length: count }, (_, i) => (
+        <Pressable
+          key={i}
+          aria-label={itemLabel ? itemLabel(i, count) : `Page ${i + 1} of ${count}`}
+          aria-current={i === index ? (tone === 'accent' ? true : 'page') : undefined}
+          onPress={() => onChange(i)}
+          width={tone === 'accent' ? 28 : 24}
+          height={24}>
+          <PagerDot active={i === index} tone={tone} />
+        </Pressable>
+      ))}
+    </Box>
+  );
+}
+
+/* ── Q4 · Step counter ───────────────────────────────────────────────────── */
+
+/**
+ * **"Step 2 of 5", with what comes next.** The last step shows a mint "All set" chip instead of a
+ * next line — there is no next, and saying so is the point of reaching it.
+ */
+export function StepCounter({
+  index, total, next, doneLabel = 'All set',
+}: {
+  /** 0-based. */
+  index: number;
+  total: number;
+  /** The next step's name. Ignored on the last step. */
+  next?: string;
+  doneLabel?: string;
+}) {
+  const last = index >= total - 1;
+  return (
+    <Box row wrap align="center" gap="s2" role="status" aria-live="polite">
+      <Text variant="caption" numeric style={{ fontWeight: '600' }} color="textPrimary">{`Step ${Math.min(index + 1, total)} of ${total}`}</Text>
+      {last
+        ? <MetaChip kind="status" status="executed">{doneLabel}</MetaChip>
+        : next ? <Text variant="caption" color="textSecondary">{`Up next · ${next}`}</Text> : null}
+    </Box>
+  );
+}

package/src/ds/blocks.tsx

@@ -0,0 +1,337 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { Box, Icon, MotionView, Text, useSwap, type IconName } from '../core';
+import {
+  blockRadii, HUE, hueForType, useDs,
+  type DataType, type Hue, type Status,
+} from '../tokens';
+import { HeaderMeta, SkeletonBar } from './blockDisplay';
+import { Button } from './Button';
+
+/**
+ * **Solarium Building Blocks — the pieces ThresholdFlow is assembled from that did not exist.**
+ *
+ * Source: `design_handoff_solarium_blocks_case_studies`, reconciled in
+ * `docs/HANDOFF-SOLARIUM-BLOCKS.md` (§3 grades each block; this file closes D1, D6, D9 and S1).
+ * Geometry reads `blockRadii` and the handoff's pixel values; colour reads `useDs()` and `HUE`,
+ * never a literal.
+ */
+
+/* ── D9 · Callout ────────────────────────────────────────────────────────── */
+
+export type CalloutTone = 'attention' | 'info';
+
+/**
+ * **Says what happened and what to do. No red.**
+ *
+ * Inline, inside a card — which is what separates it from `Banner`, a screen-level bar. The
+ * default tone is apricot (`status.needsUser`): something needs the user, nothing is broken. The
+ * handoff's "no red" is the point — a callout is a request to act, and `alertInk` is reserved for a
+ * terminal failure (C7). `info` takes sky (`reference`), as `Banner` does.
+ */
+export function Callout({
+  title, children, tone = 'attention', action, alert = false, strong = false, testID, style,
+}: {
+  title: string;
+  /**
+   * A hard failure (batch 3 decision §5.2): the title at 700 — "Couldn't claim your reward",
+   * "Held at customs". Weight, words and a recovery action carry it; still no red.
+   */
+  strong?: boolean;
+  /** Announce on appearance (`role="alert"`) — for a callout that reports something that just
+      happened, like a failed activation. A standing note stays silent. */
+  alert?: boolean;
+  /** What to do about it. */
+  children?: ReactNode;
+  tone?: CalloutTone;
+  action?: ReactNode;
+  testID?: string;
+  style?: StyleProp<ViewStyle>;
+}) {
+  const { colors } = useDs();
+  const skin = tone === 'info'
+    ? { ground: colors.reference.bg, ink: colors.reference.fg, icon: 'info' as IconName }
+    : { ground: colors.statusBg.needsUser, ink: colors.status.needsUser, icon: 'alert' as IconName };
+
+  return (
+    <Box
+      row
+      gap="s2"
+      p="s3"
+      role={alert ? 'alert' : undefined}
+      testID={testID}
+      style={[{ backgroundColor: skin.ground, borderRadius: blockRadii.mid }, style]}>
+      <Box pt="s1"><Icon name={skin.icon} size={14} color={skin.ink} /></Box>
+      <Box flex={1} gap="s1">
+        <Text variant="caption" style={{ color: skin.ink, fontWeight: strong ? '700' : '600' }}>{title}</Text>
+        {children ? (
+          <Text variant="caption" color="textPrimary" style={{ fontSize: 12, lineHeight: 17 }}>{children}</Text>
+        ) : null}
+        {action ? <Box pt="s1" alignSelf="flex-start">{action}</Box> : null}
+      </Box>
+    </Box>
+  );
+}
+
+/* ── D6 · Type tile ──────────────────────────────────────────────────────── */
+
+/**
+ * **The leading tile, its hue looked up from the data type rather than chosen.**
+ *
+ * `type` resolves through `TYPE_HUE`; `hue` is an override `hueForType` warns about when it
+ * disagrees. Resting is the hue's soft ground and deep ink; `active` swaps to the mid rung with
+ * its `on` ink — butter's dark brown included, which is why `on` is read and never assumed white.
+ *
+ * Radius is the ladder's tile rung (6) at every size (Solarium 0.2.0).
+ */
+export function TypeTile({
+  type, hue, icon, size = 28, active = false, label,
+}: {
+  type?: DataType;
+  hue?: Hue;
+  icon: IconName;
+  size?: number;
+  active?: boolean;
+  /** Only when the tile stands alone; beside its own title it is decoration. */
+  label?: string;
+}) {
+  const set = HUE[hueForType(type, hue)];
+  return (
+    <Box
+      width={size}
+      height={size}
+      align="center"
+      justify="center"
+      aria-label={label}
+      style={{
+        backgroundColor: active ? set.h : set.hs,
+        /* `--r-tile` (6) at every size — 0.2.0's radius ladder names the IconTile's rung once. */
+        borderRadius: blockRadii.tile,
+      }}>
+      <Icon name={icon} size={Math.round(size * 0.55)} color={active ? set.on : set.hd} />
+    </Box>
+  );
+}
+
+/* ── D1 · Meta chip ──────────────────────────────────────────────────────── */
+
+export type MetaChipProps =
+  /** A status word on its ground, with a 6px dot. The word carries it; the dot is redundant. */
+  | { kind: 'status'; status: Status; children: string }
+  /** A number or amount in a category's hue pair. */
+  | { kind: 'count'; type?: DataType; hue?: Hue; children: string }
+  /** A field name or value — white, hairline, taller. */
+  | { kind: 'field'; children: string };
+
+/**
+ * **Status, count, field — meaning in the label, not the colour.**
+ *
+ * Not `Chip`: that one is a selectable mono label and is used as such across the widgets. This
+ * one never takes a press — it reports.
+ */
+export function MetaChip(props: MetaChipProps) {
+  const { colors } = useDs();
+  const field = props.kind === 'field';
+  let ground: string;
+  let ink: string;
+  if (props.kind === 'status') {
+    ground = colors.statusBg[props.status];
+    ink = colors.status[props.status];
+  } else if (props.kind === 'count') {
+    const set = HUE[hueForType(props.type, props.hue)];
+    ground = set.hs;
+    ink = set.hd;
+  } else {
+    ground = colors.surface1;
+    ink = colors.textPrimary;
+  }
+
+  return (
+    <Box
+      row
+      align="center"
+      alignSelf="flex-start"
+      gap="s1"
+      height={field ? 28 : 24}
+      radius="pill"
+      style={{
+        /* 0.2.0 StatusChip: 24px, padding 0 10, 12/600 (FieldChip 28px). */
+        paddingHorizontal: field ? 12 : 10,
+        backgroundColor: ground,
+        ...(field && { borderWidth: 1, borderColor: colors.hairlineStrong }),
+      }}>
+      {props.kind === 'status' ? (
+        <Box width={6} height={6} radius="pill" style={{ backgroundColor: ink }} />
+      ) : null}
+      <Text
+        variant="caption"
+        numeric={props.kind === 'count'}
+        numberOfLines={1}
+        style={{ color: ink, fontSize: 12, lineHeight: 16, fontWeight: '600' }}>
+        {props.children}
+      </Text>
+    </Box>
+  );
+}
+
+/* ── S1 · Card shell ─────────────────────────────────────────────────────── */
+
+export type BlockCardStatus = 'ready' | 'loading' | 'empty' | 'error';
+
+export type BlockCardProps = {
+  title: string;
+  /** One line under the title — what the card is for. */
+  subtitle?: string;
+  /** Leading tile. Omit both for a card with no tile. */
+  icon?: IconName;
+  type?: DataType;
+  hue?: Hue;
+  /** Right of the title: a chip, a count. Hidden while loading or empty; replaced while in error. */
+  meta?: ReactNode;
+  status?: BlockCardStatus;
+  /** Body when `status="empty"` — what is missing and **exactly one** way to fix it. */
+  empty?: { title: string; body: string; action?: ReactNode; icon?: IconName };
+  /**
+   * Body when `status="error"` — the pattern's LOAD failure: an apricot alert and a ghost Retry.
+   * `onRetry` renders the Retry button (the host reloads; the card shows `loading` while it does);
+   * `action` replaces it with the caller's own control.
+   */
+  error?: { title: string; body: string; action?: ReactNode; onRetry?: () => void; retryLabel?: string; chipLabel?: string };
+  /** Left of the footer: a line of state — "Live · runs on every new request". */
+  hint?: ReactNode;
+  /** Right of the footer: the card's buttons. One primary per view. */
+  actions?: ReactNode;
+  children?: ReactNode;
+  testID?: string;
+  style?: StyleProp<ViewStyle>;
+  /**
+   * `false` draws no header row — a summary card whose body leads (onboarding Completion). The title
+   * still names the card for assistive technology.
+   */
+  header?: boolean;
+  /**
+   * The body without its padding — for a body that draws to the card's edge: a mock app behind a
+   * toast stack, a side panel with its own rule (batch 3's Floating and Filter Panel).
+   */
+  flush?: boolean;
+  /**
+   * `stacked`: the actions full-width on top, the hint centred under them — one full-width primary
+   * (C13), batch 3's Password Expiry. Default `row`: hint left, actions right.
+   */
+  footer?: 'row' | 'stacked';
+  /**
+   * The header's meta may drop under the title when both do not fit — a wide meta (a chip and a
+   * button: batch 3's Mark Read) at phone width. Default: the meta never wraps and the title shrinks.
+   */
+  metaWraps?: boolean;
+};
+
+/** The skeleton rows' bar widths — the onboarding handoff's, verbatim. */
+const SKELETON_ROWS: [`${number}%`, `${number}%`][] = [['44%', '28%'], ['36%', '22%'], ['50%', '30%'], ['40%', '26%']];
+
+/**
+ * **Header · body · footer, in four pattern states — the shell every Solarium component sits in (S1).**
+ *
+ * Solarium 0.2.0 / the onboarding handoff's shared shell: a 1px line-soft border and the flattened
+ * `--lift-1`; header padding 18/20/16 with a line-soft rule; footer padding 14/20 with a hint left
+ * and the actions right. The pattern status changes the BODY, and while it is not `ready` the footer
+ * and the header chip step aside:
+ * - **loading** — four skeleton rows (a 32px block, two pill bars, an 80px pill), `aria-busy`;
+ * - **empty** — centred, padding 56/32: a 40px tile, a title, a body, exactly one action;
+ * - **error** — an apricot alert and a ghost Retry; the header chip becomes "Needs attention".
+ *
+ * A component's OWN failures (a save that did not land) are not this state — they are part of its
+ * ready body, which keeps the user's work on screen.
+ */
+export function BlockCard({
+  title, subtitle, icon, type, hue, meta, status = 'ready', empty, error, hint, actions, children, testID, style, header = true,
+  flush = false, footer = 'row', metaWraps = false,
+}: BlockCardProps) {
+  const { colors, lift1 } = useDs();
+  /* M4: when the status changes (loading → ready), the new body fades in. */
+  const bodyFade = useSwap(status);
+  const ready = status === 'ready';
+  const hasFooter = ready && (hint !== undefined || actions !== undefined);
+
+  let body: ReactNode = children;
+  if (status === 'loading') {
+    body = (
+      <Box gap="s4" role="progressbar" aria-label={`Loading ${title}`} aria-busy>
+        {SKELETON_ROWS.map(([a, b]) => (
+          <Box key={a} row align="center" gap="s3">
+            <Box width={32} height={32} style={{ borderRadius: blockRadii.tile, backgroundColor: colors.band }} />
+            <Box flex={1} gap="s2">
+              <SkeletonBar width={a} height={10} />
+              <SkeletonBar width={b} height={8} />
+            </Box>
+            <SkeletonBar width={80} height={10} />
+          </Box>
+        ))}
+      </Box>
+    );
+  } else if (status === 'empty' && empty) {
+    body = (
+      <Box align="center" gap="s2" style={{ paddingVertical: 36, paddingHorizontal: 12 }}>
+        <Box width={40} height={40} align="center" justify="center" style={{ borderRadius: blockRadii.inset, backgroundColor: colors.surfaceSunken }}>
+          <Icon name={empty.icon ?? icon ?? 'plus'} size={20} color={colors.textSecondary} />
+        </Box>
+        <Text variant="label" align="center" style={{ fontWeight: '600', fontSize: 14 }}>{empty.title}</Text>
+        <Text variant="caption" color="textSecondary" align="center" style={{ fontSize: 12, maxWidth: 340 }}>{empty.body}</Text>
+        {empty.action ? <Box pt="s2">{empty.action}</Box> : null}
+      </Box>
+    );
+  } else if (status === 'error' && error) {
+    body = (
+      <Callout alert title={error.title} action={error.action ?? (error.onRetry
+        ? <Button variant="secondary" size="small" onPress={error.onRetry}>{error.retryLabel ?? 'Retry'}</Button>
+        : undefined)}>
+        {error.body}
+      </Callout>
+    );
+  }
+
+  const chip = status === 'error'
+    ? <MetaChip kind="status" status="needsUser">{error?.chipLabel ?? 'Needs attention'}</MetaChip>
+    : ready ? meta : undefined;
+
+  return (
+    <Box
+      bg="surface1"
+      testID={testID}
+      aria-label={header ? undefined : title}
+      aria-busy={status === 'loading' || undefined}
+      style={[{ borderRadius: blockRadii.major, borderWidth: 1, borderColor: colors.hairline, boxShadow: lift1, overflow: 'hidden' }, style]}>
+      {header ? <Box row align="center" gap="s3" wrap={metaWraps} style={{ paddingTop: 18, paddingHorizontal: 20, paddingBottom: 16, borderBottomWidth: 1, borderBottomColor: colors.hairline }}>
+        {icon ? <TypeTile icon={icon} type={type} hue={hue} size={32} /> : null}
+        <Box flex={1} style={{ minWidth: metaWraps ? 150 : 0 }}>
+          <Text variant="label" role="heading" aria-level={2} style={{ fontWeight: '600', fontSize: 14, letterSpacing: -0.015 * 14 }} numberOfLines={1}>
+            {title}
+          </Text>
+          {subtitle ? <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{subtitle}</Text> : null}
+        </Box>
+        {chip !== undefined && chip !== null ? (metaWraps ? <Box style={{ marginLeft: 'auto' }}><HeaderMeta>{chip}</HeaderMeta></Box> : <HeaderMeta>{chip}</HeaderMeta>) : null}
+      </Box> : null}
+      <MotionView style={{ opacity: bodyFade }}>
+        {flush && ready ? <Box>{body}</Box> : <Box p="s4" gap="s3" style={{ paddingHorizontal: 20 }}>{body}</Box>}
+      </MotionView>
+      {hasFooter && footer === 'stacked' ? (
+        <Box gap="s2" style={{ paddingVertical: 14, paddingHorizontal: 20, borderTopWidth: 1, borderTopColor: colors.hairline }}>
+          {actions}
+          {typeof hint === 'string'
+            ? <Text variant="caption" color="textSecondary" numeric align="center" style={{ fontSize: 12 }}>{hint}</Text>
+            : hint}
+        </Box>
+      ) : hasFooter ? (
+        /* Wraps rather than squeezes: at phone width the hint takes its own line above the buttons. */
+        <Box row wrap align="center" gap="s3" style={{ paddingVertical: 14, paddingHorizontal: 20, borderTopWidth: 1, borderTopColor: colors.hairline }}>
+          <Box style={{ flexGrow: 1, flexBasis: 160, minWidth: 0 }}>
+            {typeof hint === 'string'
+              ? <Text variant="caption" color="textSecondary" numeric style={{ fontSize: 12 }}>{hint}</Text>
+              : hint}
+          </Box>
+          {actions !== undefined ? <Box row wrap gap="s2" align="center" style={{ marginLeft: 'auto' }}>{actions}</Box> : null}
+        </Box>
+      ) : null}
+    </Box>
+  );
+}