@appinternalleads/ui 0.2.0

package/src/components/onboarding/data-view/parts.tsx

@@ -0,0 +1,358 @@
+import { useEffect, type ReactNode, type Ref } from 'react';
+import { Animated, Platform, View } from 'react-native';
+import { Box, ExternalLink, Icon, MotionView, Pressable, Text, usePresence, useTween, type IconName } from '../../../core';
+import { SkeletonBar } from '../../../ds';
+import { blockRadii, useDs } from '../../../tokens';
+import { Spinner } from '../shared/parts';
+import { compactValue, type CellModel } from './registry';
+import { VizBar, ToneText } from '../shared/viz';
+
+/**
+ * **What Table, Grid and C14 draw the same way** — the 44px select box, the small ghost button,
+ * the card toast, one registry value, the list sentinel. Each is a composition of the Solarium
+ * primitives, named once.
+ */
+
+/** react-native-web forwards key and mouse events on a View; React Native's types do not list them. */
+export type WebEvents = {
+  onKeyDown?: (e: { key: string; shiftKey?: boolean; preventDefault: () => void }) => void;
+  onMouseDown?: (e: { preventDefault: () => void }) => void;
+  onClick?: (e: { target: unknown }) => void;
+};
+export const webOnly = <T extends object>(p: T): T | Record<string, never> => (Platform.OS === 'web' ? p : {});
+
+/**
+ * **The row checkbox (M7)** — 18×18, radius 4, a 1.5px rim: muted off; coral rim and fill with a
+ * white 12px check that scales .6→1 when on; a white 8×2 dash when mixed. It sits in a 44×44 target,
+ * so the box is its own hit area and never nests inside the row's open button.
+ */
+export function SelectBox({ checked, onChange, label, disabled }: { checked: boolean | 'mixed'; onChange: () => void; label: string; disabled?: boolean }) {
+  const { colors } = useDs();
+  const on = checked !== false;
+  const t = useTween(checked === true ? 1 : 0);
+  const dash = useTween(checked === 'mixed' ? 1 : 0);
+  return (
+    <Pressable role="checkbox" aria-checked={checked} aria-label={label} onPress={onChange} disabled={disabled} width={44} height={44} press="scale" style={{ flexShrink: 0 }}>
+      <Box
+        width={18}
+        height={18}
+        align="center"
+        justify="center"
+        style={{ borderRadius: blockRadii.key, borderWidth: 1.5, borderColor: on ? colors.accentFill : colors.textSecondary, backgroundColor: on ? colors.accentFill : colors.surface1 }}>
+        <MotionView style={{ position: 'absolute', opacity: t, transform: [{ scale: t.interpolate({ inputRange: [0, 1], outputRange: [0.6, 1] }) }] }}>
+          <Icon name="tick" size={12} color={colors.accentOnFill} />
+        </MotionView>
+        <MotionView style={{ position: 'absolute', width: 8, height: 2, borderRadius: 999, backgroundColor: colors.accentOnFill, opacity: dash }} />
+      </Box>
+    </Pressable>
+  );
+}
+
+/**
+ * **A small ghost button** — white, a 1px line edge, ink 12/600, 28–32px, radius 8; the well on
+ * hover, scale .98 on press. `tone="apricot"` is the bold apricot-deep Delete (no red, decision 2).
+ * Takes a ref, so focus can move to it and back.
+ */
+export function Ghost({
+  label, onPress, height = 32, tone, disabled, busy, ref, expanded, haspopup, ariaLabel, grow,
+}: {
+  label: string; onPress: () => void; height?: number; tone?: 'apricot'; disabled?: boolean; busy?: boolean;
+  ref?: Ref<View>; expanded?: boolean; haspopup?: 'dialog' | 'menu' | 'listbox'; ariaLabel?: string; grow?: boolean;
+}) {
+  const { colors } = useDs();
+  return (
+    <Pressable
+      ref={ref}
+      onPress={onPress}
+      disabled={disabled && !busy}
+      aria-busy={busy || undefined}
+      aria-expanded={expanded}
+      aria-haspopup={haspopup}
+      aria-label={ariaLabel ?? label}
+      press="scale"
+      row
+      height={height}
+      style={{
+        paddingHorizontal: height <= 28 ? 10 : 12,
+        borderRadius: blockRadii.inset,
+        boxShadow: `0 0 0 1px ${colors.hairlineStrong}`,
+        backgroundColor: colors.surface1,
+        flexGrow: grow ? 1 : 0,
+        ...(busy ? { opacity: 1 } : null),
+      }}>
+      <Text
+        numberOfLines={1}
+        numeric
+        style={{ fontSize: 12, fontWeight: tone === 'apricot' ? '700' : '600', color: tone === 'apricot' ? colors.status.needsUser : colors.textPrimary }}>
+        {label}
+      </Text>
+    </Pressable>
+  );
+}
+
+export type ToastTone = 'neutral' | 'mint' | 'apricot';
+
+/**
+ * **The card toast (O1)** — 300 wide, radius 16, lift-2; a 24px round tile (mint check, apricot "!",
+ * neutral "i"), the text (600, or 700 apricot deep for a failure), an optional small ghost action
+ * and a close icon button. Enters with M10 (opacity and a 4px rise). `role="alert"` for apricot.
+ */
+export function CardToast({
+  tone, text, action, onAction, onClose, style,
+}: { tone: ToastTone; text: string; action?: string; onAction?: () => void; onClose: () => void; style?: object }) {
+  const { colors, lift2 } = useDs();
+  const p = usePresence(true, { appear: true, distance: -4 });
+  const tile = tone === 'mint' ? { bg: colors.statusBg.executed, fg: colors.status.executed, icon: 'tick' as IconName }
+    : tone === 'apricot' ? { bg: colors.statusBg.needsUser, fg: colors.status.needsUser, icon: 'exclamation' as IconName }
+    : { bg: colors.band, fg: colors.textSecondary, icon: 'info' as IconName };
+  return (
+    <Animated.View
+      role={tone === 'apricot' ? 'alert' : 'status'}
+      style={[{
+        position: 'absolute', zIndex: 7, width: 300, maxWidth: '92%', flexDirection: 'row', alignItems: 'flex-start', gap: 10,
+        paddingVertical: 12, paddingLeft: 12, paddingRight: 8, borderRadius: blockRadii.major, borderWidth: 1, borderColor: colors.hairlineStrong,
+        backgroundColor: colors.surface1, boxShadow: lift2, opacity: p.opacity, transform: [{ translateY: p.translateY }],
+      }, style]}>
+      <Box width={24} height={24} radius="pill" align="center" justify="center" aria-hidden style={{ marginTop: 2, backgroundColor: tile.bg }}>
+        <Icon name={tile.icon} size={13} color={tile.fg} />
+      </Box>
+      <Box flex={1} gap="s2" style={{ minWidth: 0, paddingTop: 5 }}>
+        <Text numeric style={{ fontSize: 13, fontWeight: tone === 'apricot' ? '700' : '600', color: tone === 'apricot' ? colors.status.needsUser : colors.textPrimary }}>{text}</Text>
+        {action && onAction ? <Box row><Ghost label={action} onPress={onAction} height={28} /></Box> : null}
+      </Box>
+      <Pressable aria-label="Dismiss notification" onPress={onClose} width={32} height={32} radius="pill">
+        <Icon name="close" size={15} color={colors.textSecondary} />
+      </Pressable>
+    </Animated.View>
+  );
+}
+
+/**
+ * The full value as the browser's tooltip (`title`) — a truncated text cell, a date's absolute
+ * time. react-native-web does not forward `title`, so it is set on the node itself; native has no
+ * tooltip and the value is read in full by the screen reader either way.
+ */
+export function Titled({ title, children, style }: { title?: string; children: ReactNode; style?: object }) {
+  return (
+    <View
+      style={[{ minWidth: 0 }, style]}
+      ref={el => {
+        const node = el as unknown as { setAttribute?: (k: string, v: string) => void; removeAttribute?: (k: string) => void } | null;
+        if (Platform.OS !== 'web' || !node?.setAttribute) return;
+        if (title) node.setAttribute('title', title);
+        else node.removeAttribute?.('title');
+      }}>
+      {children}
+    </View>
+  );
+}
+
+/** A 24px initials circle — the `avatar` type. People, not categories: the line-soft ground. */
+export function Initials({ text, size = 24, ring = false, offset = false }: { text: string; size?: number; ring?: boolean; offset?: boolean }) {
+  const { colors } = useDs();
+  return (
+    <Box
+      width={size}
+      height={size}
+      radius="pill"
+      align="center"
+      justify="center"
+      aria-hidden
+      style={{
+        flexShrink: 0,
+        backgroundColor: colors.band,
+        ...(ring ? { borderWidth: 2, borderColor: colors.surface1 } : null),
+        ...(offset ? { marginLeft: -6 } : null),
+      }}>
+      <Text numeric style={{ fontSize: size <= 22 ? 10 : size >= 32 ? 12 : 11, fontWeight: '600', color: colors.textPrimary }}>{text}</Text>
+    </Box>
+  );
+}
+
+/** The D5 group as a cell draws it: up to 3 circles with a 2px white ring, −6px overlap, then "+n". */
+export function MiniAvatarGroup({ items, size = 24 }: { items: string[]; size?: number }) {
+  return (
+    <Box row aria-hidden style={{ paddingLeft: 6, flexShrink: 0 }}>
+      {items.map((a, i) => <Initials key={`${a}-${i}`} text={a} size={size} ring offset />)}
+    </Box>
+  );
+}
+
+/** One registry value, drawn (see `registry.ts` for what each type shows). */
+export function Cell({ m, card = false, fill = 1, tone = 1, scale }: {
+  m: CellModel;
+  card?: boolean;
+  /** M15: a bar's fill and a figure's count, 0–1 (default: done). */
+  fill?: number;
+  /** M15: a score's tone layer, 0–1, after its count ends. */
+  tone?: number;
+  /** A bar's scale when the loaded max is tweening; default `m.ratio`. */
+  scale?: number;
+}) {
+  const { colors } = useDs();
+  switch (m.kind) {
+    case 'bar': {
+      const text = fill >= 1 ? m.text : compactValue(Math.round(m.value * fill));
+      const s = (scale ?? m.ratio) * fill;
+      const a11y = { role: 'meter' as const, label: m.label, now: m.value, max: Math.max(m.value, m.value / (m.ratio || 1)), text: `${m.label}: ${m.value.toLocaleString('en-US')}` };
+      return card ? (
+        <Box gap="s1">
+          <Text numeric style={{ fontSize: 13, color: colors.textPrimary }}>{text}</Text>
+          <VizBar scale={s} height={4} color={colors.textSecondary} track={colors.band} a11y={a11y} />
+        </Box>
+      ) : (
+        <Box row align="center" gap="s2" style={{ flex: 1 }}>
+          <View style={{ flex: 1 }}><VizBar scale={s} height={6} color={colors.textSecondary} track={colors.band} a11y={a11y} /></View>
+          <Text numeric style={{ minWidth: 44, textAlign: 'right', fontSize: 13, color: colors.textPrimary }}>{text}</Text>
+        </Box>
+      );
+    }
+    case 'score': {
+      const toneColor = m.tier === 'good' ? colors.status.executed : m.tier === 'fair' ? colors.status.needsUser : undefined;
+      return (
+        <View style={{ alignItems: card ? 'flex-start' : 'flex-end' }}>
+          <ToneText color={colors.textSecondary} tone={toneColor} toneOpacity={tone} weight="600" size={13} align={card ? 'left' : 'right'}>
+            {String(Math.round(m.value * fill))}
+          </ToneText>
+          {/* The tier in words — colour never carries it alone. */}
+          <Text style={{ position: 'absolute', width: 1, height: 1, overflow: 'hidden', opacity: 0 }}>{` (${m.tier})`}</Text>
+        </View>
+      );
+    }
+    case 'status': {
+      const tone = m.tone === 'mint' ? { bg: colors.statusBg.executed, fg: colors.status.executed }
+        : m.tone === 'apricot' ? { bg: colors.statusBg.needsUser, fg: colors.status.needsUser }
+        : { bg: colors.band, fg: colors.textSecondary };
+      return (
+        <Box row align="center" gap="s1" alignSelf="flex-start" height={22} radius="pill" style={{ paddingHorizontal: 8, gap: 6, backgroundColor: tone.bg }}>
+          {m.tone !== 'plain' ? <Box width={6} height={6} radius="pill" aria-hidden style={{ backgroundColor: tone.fg }} /> : null}
+          <Text numberOfLines={1} style={{ fontSize: 12, fontWeight: '600', color: tone.fg }}>{m.text}</Text>
+        </Box>
+      );
+    }
+    case 'avatar':
+      return (
+        <Box row align="center" gap="s2" style={{ minWidth: 0, maxWidth: '100%' }}>
+          <Initials text={m.initials} />
+          <Text numberOfLines={1} style={{ fontSize: 13, color: colors.textPrimary, flexShrink: 1 }}>{m.text}</Text>
+        </Box>
+      );
+    case 'avatars':
+      return (
+        <Titled title={m.title} style={{ flexDirection: 'row', alignItems: 'center', gap: 8, minWidth: 0, maxWidth: '100%' }}>
+          {m.group ? <MiniAvatarGroup items={m.avatars} /> : null}
+          <Text numberOfLines={card ? 2 : 1} style={{ fontSize: 13, color: colors.textPrimary, flexShrink: 1 }}>{m.text}</Text>
+        </Titled>
+      );
+    case 'link':
+      return (
+        <ExternalLink
+          href={m.href}
+          aria-label={m.external ? `${m.text} (opens in a new tab)` : m.text}
+          style={{ alignSelf: 'flex-start', flexDirection: 'row', alignItems: 'center', gap: 4, paddingHorizontal: 4, paddingVertical: 2, marginHorizontal: -4, marginVertical: -2, borderRadius: blockRadii.key }}>
+          <Text numberOfLines={1} style={{ fontSize: 13, fontWeight: '600', color: colors.accentInk }}>{m.text}</Text>
+          {m.external ? <Icon name="external" size={12} color={colors.accentInk} /> : null}
+        </ExternalLink>
+      );
+    case 'progress':
+      return (
+        <Box row align="center" gap="s2">
+          <Box
+            role="progressbar"
+            aria-label={m.label}
+            aria-valuemin={0}
+            aria-valuemax={100}
+            aria-valuenow={m.pct}
+            width={56}
+            height={4}
+            radius="pill"
+            style={{ backgroundColor: colors.band, overflow: 'hidden' }}>
+            <Box style={{ height: 4, width: `${Math.max(0, Math.min(100, m.pct))}%`, backgroundColor: colors.textPrimary }} />
+          </Box>
+          <Text numeric style={{ fontSize: 12, color: colors.textPrimary }}>{m.text}</Text>
+        </Box>
+      );
+    default:
+      return (
+        <Titled title={m.title}>
+          <Text
+            numeric
+            numberOfLines={m.clamp ? 2 : 1}
+            style={{ fontSize: 13, color: m.muted ? colors.textSecondary : colors.textPrimary, textAlign: m.end ? 'right' : 'left' }}>
+            {m.text}
+          </Text>
+        </Titled>
+      );
+  }
+}
+
+/** Apricot row — "Couldn’t load more" with Retry; C14's "Couldn’t search people". `role="alert"`. */
+export function AlertRow({ text, action, onAction, compact }: { text: string; action?: string; onAction?: () => void; compact?: boolean }) {
+  const { colors } = useDs();
+  return (
+    <Box
+      role="alert"
+      row
+      align="center"
+      style={{ flexGrow: 1, gap: 10, paddingVertical: compact ? 8 : 8, paddingLeft: 12, paddingRight: 8, borderRadius: blockRadii.inset, backgroundColor: colors.statusBg.needsUser }}>
+      <Icon name="alert" size={15} color={colors.status.needsUser} />
+      <Text style={{ flex: 1, fontSize: compact ? 12 : 13, fontWeight: '700', color: colors.status.needsUser }}>{text}</Text>
+      {action && onAction ? <Ghost label={action} onPress={onAction} height={28} /> : null}
+    </Box>
+  );
+}
+
+/** "Loading more…" with the 16px spinner, `role="status"`. */
+export function LoadingMore({ label = 'Loading more…' }: { label?: string }) {
+  const { colors } = useDs();
+  return (
+    <Box role="status" row align="center" gap="s2">
+      <Spinner size={16} />
+      <Text style={{ fontSize: 12, color: colors.textPrimary }}>{label}</Text>
+    </Box>
+  );
+}
+
+/**
+ * **The sentinel at the end of the list** — idle: a ghost Load more (keyboard and reduced-motion
+ * users; scrolling near the end also loads); loading: the spinner; error: the apricot row with
+ * Retry; end: "All 64 invoices loaded".
+ */
+export function Sentinel({ state, endLabel, onMore }: { state: 'idle' | 'loading' | 'error' | 'end' | 'none'; endLabel: string; onMore: () => void }) {
+  const { colors } = useDs();
+  return (
+    <Box row align="center" justify="center" gap="s2" style={{ minHeight: 52, paddingVertical: 8, paddingHorizontal: 12 }}>
+      {state === 'loading' ? <LoadingMore /> : null}
+      {state === 'error' ? <AlertRow text="Couldn’t load more" action="Retry" onAction={onMore} /> : null}
+      {state === 'idle' ? <Ghost label="Load more" onPress={onMore} height={28} /> : null}
+      {state === 'end' ? <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{endLabel}</Text> : null}
+    </Box>
+  );
+}
+
+/** A row that fades in when appended by a page (opacity only), and fades up 6px when deleted (M14). */
+export function RowMotion({ fresh, leaving, children, style }: { fresh: boolean; leaving: boolean; children: ReactNode; style?: object }) {
+  const appear = usePresence(true, { appear: fresh, distance: 0 });
+  const leave = useTween(leaving ? 1 : 0);
+  return (
+    <Animated.View
+      style={[style, {
+        opacity: Animated.multiply(appear.opacity, leave.interpolate({ inputRange: [0, 1], outputRange: [1, 0] })),
+        transform: [{ translateY: leave.interpolate({ inputRange: [0, 1], outputRange: [0, -6] }) }],
+      }]}>
+      {children}
+    </Animated.View>
+  );
+}
+
+/** A skeleton pill (#F1EFE7) — no shimmer (0.2.0). */
+export const Pill = SkeletonBar;
+
+/** Fire `fn` once after `ms`, cleared on unmount or when `key` changes. */
+export function useLater(key: unknown, ms: number, fn: () => void) {
+  useEffect(() => {
+    if (key === null || key === undefined || key === false) return undefined;
+    const t = setTimeout(fn, ms);
+    return () => clearTimeout(t);
+  }, [key]);
+}

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

@@ -0,0 +1,166 @@
+import { COLUMN_TYPES, type ColumnDef, type ColumnType, type DataRow, type StatusTone } from './contract';
+
+/**
+ * **The renderer registry (`REG`) — nine seed types, each with a cell value, a card value and
+ * `toText()`.** Pure: this file decides WHAT a value shows; `parts.tsx` draws it. Table cells, Grid
+ * card values and "Copy as text" all read it, so a column type is added in one place (§1.9: a new
+ * type ships with a cell renderer, a card value and `toText()`, and is then auto-approved).
+ *
+ * Rules (§1.9, batch 4): an empty value renders a muted "—"; alignment is declared (`align`, or the
+ * type's default). Unknown types fall back to `text`.
+ */
+
+const MON = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+export function typeOf(col: ColumnDef): ColumnType {
+  return (COLUMN_TYPES as readonly string[]).includes(col.type) ? (col.type as ColumnType) : 'text';
+}
+
+export function isEmptyValue(v: unknown): boolean {
+  return v === null || v === undefined || v === '' || (Array.isArray(v) && v.length === 0);
+}
+
+/** End-aligned: declared, or number / currency / date / progress by default. */
+export function isEnd(col: ColumnDef): boolean {
+  return col.align ? col.align === 'end' : ['number', 'currency', 'date', 'progress', 'bar', 'score'].includes(typeOf(col));
+}
+
+export function initials(name: string): string {
+  return String(name).split(' ').filter(Boolean).slice(0, 2).map(w => w[0]).join('').toUpperCase();
+}
+
+export function fmtN(n: number): string {
+  return Number(n).toLocaleString('en-US');
+}
+
+export function money(v: number, currency?: string): string {
+  try {
+    return new Intl.NumberFormat('en-US', { style: 'currency', currency: currency || 'USD' }).format(v);
+  } catch {
+    return `$${v}`;
+  }
+}
+
+const pad2 = (n: number) => (n < 10 ? '0' : '') + n;
+
+/** "2h ago", "in 3d" — relative to `now`. */
+export function relTime(ts: number, now: number): string {
+  const d = (ts - now) / 36e5;
+  const a = Math.abs(d);
+  const s = a < 1 ? `${Math.max(1, Math.round(a * 60))}m` : a < 24 ? `${Math.round(a)}h` : `${Math.round(a / 24)}d`;
+  return d < 0 ? `${s} ago` : `in ${s}`;
+}
+
+/** "24 Sep 2026", or "26 Sep · 09:30" with time. UTC, so a board renders the same everywhere. */
+export function absTime(ts: number, withTime?: boolean): string {
+  const d = new Date(ts);
+  if (withTime) return `${d.getUTCDate()} ${MON[d.getUTCMonth()]} · ${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())}`;
+  return `${d.getUTCDate()} ${MON[d.getUTCMonth()]} ${d.getUTCFullYear()}`;
+}
+
+/** `toText()` per type — "Copy as text", and the text a cell is announced by. */
+const TO_TEXT: Record<ColumnType, (col: ColumnDef, v: unknown) => string> = {
+  text: (_c, v) => String(v),
+  number: (c, v) => fmtN(Number(v)) + (c.suffix ?? ''),
+  currency: (c, v) => money(Number(v), c.currency),
+  date: (c, v) => new Date(Number(v)).toISOString().slice(0, c.withTime ? 16 : 10).replace('T', ' '),
+  status: (_c, v) => String(v),
+  avatar: (_c, v) => String(v),
+  link: (c, v) => (c.href ?? '') + String(v),
+  avatars: (_c, v) => ([] as unknown[]).concat(v).join(', '),
+  progress: (_c, v) => `${Math.round(Number(v))}%`,
+  bar: (_c, v) => fmtN(Number(v)),
+  score: (c, v) => `${Math.round(Number(v))} (${scoreTier(c, Number(v))})`,
+};
+
+/** A `score`'s tier by its thresholds — [good, fair], default [85, 70]. */
+export function scoreTier(col: ColumnDef, v: number): 'good' | 'fair' | 'low' {
+  const [good, fair] = col.thresholds ?? [85, 70];
+  return v >= good ? 'good' : v >= fair ? 'fair' : 'low';
+}
+
+/** "48.2K", "1.1K", "982" — a bar's value, compact. */
+export function compactValue(v: number): string {
+  try { return new Intl.NumberFormat('en-US', { notation: 'compact', maximumSignificantDigits: 3 }).format(v); } catch { return fmtN(v); }
+}
+
+export function toTextValue(col: ColumnDef, v: unknown): string {
+  return isEmptyValue(v) ? '' : TO_TEXT[typeOf(col)](col, v);
+}
+
+/**
+ * **What one value renders as** — in a Table cell (`cell`) or a card's `<dd>` (`card`). The view
+ * switches on `kind`; everything else is data it draws.
+ */
+export type CellModel =
+  | { kind: 'text'; text: string; title?: string; muted?: boolean; end: boolean; clamp: boolean }
+  | { kind: 'status'; text: string; tone: StatusTone }
+  | { kind: 'avatar'; text: string; initials: string }
+  | { kind: 'avatars'; text: string; title: string; avatars: string[]; group: boolean }
+  | { kind: 'link'; text: string; href: string; external: boolean }
+  | { kind: 'progress'; text: string; pct: number; label: string }
+  /** `ratio`: value ÷ the largest loaded value (0–1). */
+  | { kind: 'bar'; text: string; value: number; ratio: number; label: string }
+  | { kind: 'score'; text: string; value: number; tier: 'good' | 'fair' | 'low' };
+
+export function cellModel(col: ColumnDef, v: unknown, where: 'cell' | 'card', now: number, ctx: { max?: number } = {}): CellModel {
+  const t = typeOf(col);
+  const card = where === 'card';
+  const end = !card && isEnd(col);
+  if (isEmptyValue(v)) return { kind: 'text', text: '—', muted: true, end, clamp: card };
+  if (t === 'status') return { kind: 'status', text: String(v), tone: col.tones?.[String(v)] ?? 'plain' };
+  if (t === 'avatars') {
+    const people = ([] as unknown[]).concat(v).map(String);
+    return {
+      kind: 'avatars',
+      /* Card value: the names. Cell: the name when there is one person, "3 people" otherwise. */
+      text: card ? people.join(', ') : people.length === 1 ? people[0]! : `${people.length} people`,
+      title: people.join(', '),
+      avatars: people.slice(0, 3).map(initials).concat(people.length > 3 ? [`+${people.length - 3}`] : []),
+      group: !card,
+    };
+  }
+  if (t === 'avatar') return { kind: 'avatar', text: String(v), initials: initials(String(v)) };
+  if (t === 'link') return { kind: 'link', text: String(v), href: (col.href ?? '#') + String(v), external: Boolean(col.external) };
+  if (t === 'progress') {
+    const pct = Math.round(Number(v));
+    return { kind: 'progress', text: `${pct}%`, pct, label: col.label };
+  }
+  if (t === 'bar') {
+    const value = Number(v);
+    const max = ctx.max && ctx.max > 0 ? ctx.max : value || 1;
+    return { kind: 'bar', text: compactValue(value), value, ratio: Math.max(0, Math.min(1, value / max)), label: col.label };
+  }
+  if (t === 'score') {
+    const value = Math.round(Number(v));
+    return { kind: 'score', text: String(value), value, tier: scoreTier(col, value) };
+  }
+  if (t === 'date') {
+    const ts = Number(v);
+    return { kind: 'text', text: card || col.withTime ? absTime(ts, col.withTime) : relTime(ts, now), title: absTime(ts, col.withTime), end, clamp: card };
+  }
+  return { kind: 'text', text: TO_TEXT[t](col, v), title: t === 'text' ? String(v) : undefined, end, clamp: card };
+}
+
+/** "5 invoices", "1 invoice". */
+export function countNoun(n: number, noun: string, nouns: string): string {
+  return `${fmtN(n)} ${n === 1 ? noun : nouns}`;
+}
+
+/**
+ * **Table/Grid `toText()`** — "{title} · {N} {nouns}", then each loaded row as a block of
+ * `Label: value` lines, up to 20 rows, then "and N more".
+ */
+export function dataViewToText(
+  c: { title: string; noun: string; nouns: string; columns: ColumnDef[] },
+  rows: DataRow[],
+  total: number,
+): string {
+  const lines = [`${c.title} · ${countNoun(total, c.noun, c.nouns)}`];
+  rows.slice(0, 20).forEach(r => {
+    lines.push('');
+    c.columns.forEach(col => lines.push(`${col.label}: ${toTextValue(col, r[col.id])}`));
+  });
+  if (rows.length > 20) lines.push('', `and ${rows.length - 20} more`);
+  return lines.join('\n');
+}

package/src/components/onboarding/data-view/reveal.tsx

@@ -0,0 +1,69 @@
+import { createContext, useContext, useEffect, useRef, useState } from 'react';
+import { M15, barFill, barStart, rowReveal, toneIn } from '../shared/m15';
+import { useTweenedValues } from '../shared/viz';
+import { typeOf } from './registry';
+import type { DataRow, DataViewSettings } from './contract';
+
+/**
+ * **M15 on a data view** (batch 5 §4.4) — only when `config.m15`. Every page staggers: a row is
+ * stamped with the moment its page arrived and its place in that page (60ms apart, capped at 8), so
+ * the stagger restarts at each page's first row and rows already on screen never move. Bars fill
+ * from row delay + 160ms over 600ms; bar and score figures count with them; a score's tone fades in
+ * after its count. A `bar` column with `scale: 'loaded-max'` scales to the largest loaded value, and
+ * when a page raises it every bar re-scales in one 600ms tween. A sort re-orders — nothing re-staggers.
+ */
+
+export type RowReveal = { opacity: number; y: number; fill: number; tone: number };
+type RevealApi = { row: (id: string) => RowReveal; scale: (colId: string, value: number) => number | undefined; max: (colId: string) => number | undefined };
+
+const DONE: RowReveal = { opacity: 1, y: 0, fill: 1, tone: 1 };
+const HIDDEN: RowReveal = { opacity: 0, y: -M15.dropPx, fill: 0, tone: 0 };
+const OFF: RevealApi = { row: () => DONE, scale: () => undefined, max: () => undefined };
+
+export const RevealContext = createContext<RevealApi>(OFF);
+export const useRowReveal = () => useContext(RevealContext);
+
+export function useDataViewReveal(config: DataViewSettings, rows: DataRow[], active: boolean, replay: unknown, reduced: boolean): RevealApi {
+  const on = Boolean(config.m15);
+  const stamps = useRef(new Map<string, { t0: number; idx: number }>());
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => { stamps.current = new Map(); setNow(Date.now()); }, [replay]);
+
+  /* Stamp the rows this page brought, in order, all with the page's arrival time. */
+  const ids = rows.map(r => r.id).join('|');
+  useEffect(() => {
+    if (!on || !active) return;
+    const t0 = Date.now();
+    let idx = 0;
+    for (const r of rows) if (!stamps.current.has(r.id)) stamps.current.set(r.id, { t0, idx: idx++ });
+    if (idx) setNow(t0);
+  }, [on, active, ids]);
+
+  /* The clock runs while any row is still revealing. */
+  const busyUntil = Math.max(0, ...[...stamps.current.values()].map(s => s.t0 + barStart(s.idx) + M15.fillMs + M15.toneMs));
+  useEffect(() => {
+    if (!on || reduced || now >= busyUntil) return;
+    const iv = setInterval(() => { const n = Date.now(); setNow(n); if (n >= busyUntil) clearInterval(iv); }, 16);
+    return () => clearInterval(iv);
+  }, [on, reduced, busyUntil]);
+
+  /* The loaded max of each bar column — one tween re-scales every bar when a page raises it. */
+  const barCols = config.columns.filter(c => typeOf(c) === 'bar');
+  const maxes = barCols.map(c => Math.max(0, ...rows.map(r => Number(r[c.id]) || 0)));
+  const settled = stamps.current.size > 0 && now >= busyUntil;
+  const shownMax = useTweenedValues(maxes, M15.fillMs, settled, reduced);
+
+  if (!on) return OFF;
+  return {
+    row: id => {
+      if (reduced) return DONE;
+      const s = stamps.current.get(id);
+      if (!s) return HIDDEN;
+      const t = now - s.t0;
+      const rv = rowReveal(s.idx, t);
+      return { opacity: rv.opacity, y: rv.y, fill: barFill(s.idx, t), tone: toneIn(barStart(s.idx) + M15.fillMs, t) };
+    },
+    max: colId => { const k = barCols.findIndex(c => c.id === colId); return k >= 0 ? shownMax[k] : undefined; },
+    scale: (colId, value) => { const k = barCols.findIndex(c => c.id === colId); return k >= 0 && shownMax[k]! > 0 ? Math.min(1, value / shownMax[k]!) : undefined; },
+  };
+}