@appinternalleads/ui 0.2.0

package/src/components/onboarding/activity-heatmap/ActivityHeatmapView.tsx

@@ -0,0 +1,351 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { ScrollView, View } from 'react-native';
+import { Box, Icon, Pressable, Text } from '../../../core';
+import { Button } from '../../../ds';
+import { HUE, blockRadii, hueForType, useDs, type DensityName } from '../../../tokens';
+import { resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import type { OnboardingOutcome } from '../shared/mock';
+import type { OnboardingOperation } from '../shared/mock';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { OnboardingCard } from '../shared/OnboardingCard';
+import { usePatternStatus, useSceneReport } from '../shared/runtime';
+import { guarded } from '../shared/guard';
+import { PlainChip } from '../shared/parts';
+import { ApricotAlert } from '../shared/insight-parts';
+import { countOf, longDay, parseDay, rampOf, shortDay } from '../shared/insight';
+import { M15, progress } from '../shared/m15';
+import { DataTip, useInView, useRevealClock } from '../shared/viz';
+import { useOperationRunner } from '../../../runtime/operations';
+import { HEATMAP_PRESETS, validateHeatmap, type HeatmapItem, type HeatmapReveal, type HeatmapSettings } from './contract';
+import {
+  HEAT_REVEAL_END, LEVEL_CHIP, cellDelay, comparedToAverage, headerTotal, heatModel, heatmapSeed, initialHeatmap, levelRanges, moveFocus, peakText,
+  type HeatCell, type HeatSeed,
+} from './engine';
+
+export type HeatmapOperations = {
+  /** A day's items for the popover — answer `{ ok: true, items: [{ title, meta }] }`. Without it, `sample` shows after 700ms. */
+  loadDay: (req: { date: string; count: number }, ctx: { signal: AbortSignal }) => Promise<OnboardingOutcome & { items?: HeatmapItem[] }>;
+};
+
+export type ActivityHeatmapProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<HeatmapSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  /** `error`: the popover's first load fails — "Couldn't load this day", with Retry. */
+  result?: OnboardingResult;
+  reload?: OnboardingOperation<void>;
+  operations?: Partial<HeatmapOperations>;
+  initial?: HeatSeed;
+  /** Overrides `config.reveal` — the board's Reveal control. */
+  reveal?: HeatmapReveal;
+  /** "View all 22" in the popover — the day, YYYY-MM-DD. */
+  onOpen?: (date: string) => void;
+  /** A day's popover opened (its date) or closed (`null`). */
+  onDaySelect?: (date: string | null) => void;
+  replay?: number;
+  forceReduced?: boolean;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+const CELL = 12, GAP = 3, PITCH = CELL + GAP, LABEL_W = 28, POP_W = 280;
+const SKELETON_MS = 700;
+const AUTO_POP_MS = 1300;
+
+/**
+ * **Activity Heatmap** — a period chip and "705 reviews in 81 days"; a stats well (Daily avg,
+ * Peak, Streak); the grid — 7 rows, a column a week from the Monday on or before the start, 12px
+ * cells on the hue ramp, future days outlined, today ringed in ink — scrolled to the latest week;
+ * the legend. A day opens a popover: its date, count and level, a 700ms skeleton, then up to three
+ * items, a comparison with the daily average, and View all. Roving focus: ↑/↓ a day, ←/→ a week.
+ */
+function ActivityHeatmapView(props: ActivityHeatmapProps) {
+  const config = resolveConfig(HEATMAP_PRESETS, props.preset, props.config);
+  const issues = validateHeatmap(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+type Pop = { index: number; phase: 'loading' | 'ready' | 'failed'; items: HeatmapItem[] };
+
+function Valid({
+  config, density, status, result, reload, operations, initial, reveal, onOpen, onDaySelect, replay, forceReduced, onScene, testID,
+}: Omit<ActivityHeatmapProps, 'config'> & { config: HeatmapSettings }) {
+  const { colors, lift2 } = useDs();
+  const key = JSON.stringify([config, initial ?? null]);
+  const m = useMemo(() => heatModel(config), [key]);
+  const seed = useMemo(() => initialHeatmap(config, initial ?? (config.ship ? heatmapSeed(config, config.ship) : {})), [key]);
+  const mode = reveal ?? config.reveal;
+  const hue = HUE[hueForType(config.type)];
+  const ramp = [colors.band, ...rampOf(hue.hs, hue.hd)];
+
+  const pattern = usePatternStatus(status ?? (seed.loadReady ? 'loading' : m.active ? 'ready' : 'empty'), reload);
+  useEffect(() => {
+    if (!seed.loadReady || status) return;
+    const t = setTimeout(() => pattern.set('ready'), 1200);
+    return () => clearTimeout(t);
+  }, [seed, status, replay]);
+
+  const [ref, inView] = useInView();
+  const clock = useRevealClock(inView && pattern.status === 'ready', HEAT_REVEAL_END, `${replay ?? 0}|${pattern.status}|${mode}`, forceReduced);
+  const t = clock.t;
+  const stat = (v: number) => (clock.done ? v : v * progress(t, 0, M15.fillMs));
+
+  /* Focus and the popover. */
+  const lastIndex = useMemo(() => {
+    let best = -1;
+    m.cells.forEach((c, i) => { if (c.inRange && !c.future) best = i; });
+    return best >= 0 ? best : m.cells.findIndex(c => c.inRange);
+  }, [m]);
+  const [focusIndex, setFocusIndex] = useState(lastIndex);
+  useEffect(() => setFocusIndex(lastIndex), [lastIndex]);
+  const [hover, setHover] = useState<number | null>(null);
+  const [pop, setPop] = useState<Pop | null>(null);
+  const cellRefs = useRef<Record<number, { focus?: () => void } | null>>({});
+  const popRef = useRef<{ focus?: () => void } | null>(null);
+  const runner = useOperationRunner();
+  const attempts = useRef(0);
+  const [width, setWidth] = useState(0);
+  const [scrollX, setScrollX] = useState(0);
+  /* The card clips what overflows it, so the grid's area grows to hold an open popover. */
+  const [popH, setPopH] = useState(0);
+  const scroller = useRef<ScrollView>(null);
+
+  const load = (index: number) => {
+    const cell = m.cells[index]!;
+    setPop({ index, phase: 'loading', items: [] });
+    if (!cell.count) { setPop({ index, phase: 'ready', items: [] }); return; }
+    const attempt = attempts.current++;
+    const host = operations?.loadDay;
+    runner.run('loadDay', async ctx => {
+      if (host) return host({ date: cell.key, count: cell.count }, { signal: ctx.signal });
+      await new Promise(r => setTimeout(r, SKELETON_MS));
+      return result === 'error' && attempt === 0 ? { ok: false as const } : { ok: true as const, items: config.sample ?? [] };
+    }, {
+      onOk: (r: OnboardingOutcome & { items?: HeatmapItem[] }) => setPop(p => (p && p.index === index ? { index, phase: r.ok ? 'ready' : 'failed', items: r.ok ? (r.items ?? []).slice(0, 3) : [] } : p)),
+      onError: () => setPop(p => (p && p.index === index ? { ...p, phase: 'failed' } : p)),
+    });
+  };
+  /* A press moves focus into the popover; the demo's own opening does not (it must not pull the page). */
+  const openDay = (index: number, focus = true) => {
+    if (pop?.index === index) { closePop(); return; }
+    attempts.current = 0;
+    setFocusIndex(index);
+    load(index);
+    onDaySelect?.(m.cells[index]!.key);
+    if (focus) setTimeout(() => popRef.current?.focus?.(), 40);
+  };
+  const closePop = () => {
+    const i = pop?.index;
+    setPop(null);
+    onDaySelect?.(null);
+    if (i !== undefined) setTimeout(() => cellRefs.current[i]?.focus?.(), 20);
+  };
+  useEffect(() => { setPop(null); attempts.current = 0; }, [key]);
+  /* A press outside the popover and its cell closes it (web). */
+  const popOpen = pop !== null;
+  useEffect(() => {
+    const doc = (globalThis as { document?: Document }).document;
+    if (!popOpen || !doc) return;
+    const onDown = (e: Event) => {
+      const box = popRef.current as unknown as { contains?: (n: Node) => boolean } | null;
+      const cell = pop ? (cellRefs.current[pop.index] as unknown as { contains?: (n: Node) => boolean } | null) : null;
+      const target = e.target as Node;
+      if (box?.contains?.(target) || cell?.contains?.(target)) return;
+      setPop(null);
+      onDaySelect?.(null);
+    };
+    doc.addEventListener('pointerdown', onDown);
+    return () => doc.removeEventListener('pointerdown', onDown);
+  }, [popOpen, pop?.index]);
+
+  /* The case that ships with a popover opens it once the grid has revealed. */
+  useEffect(() => {
+    if (!seed.pop || pattern.status !== 'ready') return;
+    const date = seed.pop === 'peak' ? m.peakDate : m.zeroDate;
+    const index = m.cells.findIndex(c => c.key === date);
+    if (index < 0) return;
+    const tm = setTimeout(() => openDay(index, false), AUTO_POP_MS);
+    return () => clearTimeout(tm);
+  }, [seed, pattern.status]);
+
+  const popCell = pop ? m.cells[pop.index] : undefined;
+  useSceneReport(pattern.status === 'ready' ? (seed.loadReady ? 'loadReady' : popCell ? (popCell.count ? 'popover' : 'zeroDay') : 'default') : pattern.status, onScene);
+
+  const noun = config.noun, one = config.nounOne;
+  const ranges = levelRanges(m, noun, one);
+  const meta = (
+    <Box row align="center" gap="s2" style={{ flexWrap: 'wrap', justifyContent: 'flex-end' }}>
+      <PlainChip>{config.periodLabel}</PlainChip>
+      <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{headerTotal(m, noun, one)}</Text>
+    </Box>
+  );
+
+  const cellView = (c: HeatCell, i: number) => {
+    if (!c.inRange) return <View key={c.key} style={{ width: CELL, height: CELL }} />;
+    const delay = cellDelay(mode, c, m.cols);
+    const q = clock.done ? 1 : progress(t, delay, M15.toneMs);
+    const intensity = mode === 'intensity';
+    const colourIn = clock.done ? 1 : intensity ? progress(t, delay, 200) : 1;
+    const shownQ = intensity ? 1 : q;
+    const popped = pop?.index === i;
+    const label = `${longDay(c.t)} · ${c.future ? 'upcoming' : countOf(c.count, noun, one)}${c.today ? ' · today' : ''}`;
+    return (
+      <View key={c.key} style={{ width: CELL, height: CELL, zIndex: popped ? 3 : 0 }}>
+        <Pressable
+          ref={((el: unknown) => { cellRefs.current[i] = el as never; }) as never}
+          aria-label={label}
+          aria-expanded={popped}
+          tabIndex={i === focusIndex ? 0 : -1}
+          onPress={() => { if (!c.future) openDay(i); }}
+          onFocus={() => setFocusIndex(i)}
+          onHoverIn={() => setHover(i)}
+          onHoverOut={() => setHover(h => (h === i ? null : h))}
+          onKeyDown={e => {
+            if (e.key === 'Escape' && pop) { e.preventDefault(); closePop(); return; }
+            const to = moveFocus(m.cells, i, e.key);
+            if (to !== i) { e.preventDefault(); setFocusIndex(to); cellRefs.current[to]?.focus?.(); }
+          }}
+          width={CELL}
+          height={CELL}
+          style={{
+            borderRadius: 4,
+            opacity: shownQ,
+            transform: [{ scale: popped ? 1.5 : 0.6 + 0.4 * shownQ }],
+            backgroundColor: c.future ? 'transparent' : ramp[0],
+            borderWidth: c.today ? 1.5 : c.future ? 1 : 0,
+            borderColor: c.today ? colors.textPrimary : colors.hairlineStrong,
+            ...(popped ? { boxShadow: `0 0 0 2px ${colors.textPrimary}, ${lift2}` } : null),
+          } as object}>
+          {c.level > 0 ? <View pointerEvents="none" style={{ position: 'absolute', left: 0, right: 0, top: 0, bottom: 0, borderRadius: 4, backgroundColor: ramp[c.level], opacity: colourIn }} /> : null}
+        </Pressable>
+      </View>
+    );
+  };
+
+  const hovered = hover !== null ? m.cells[hover] : undefined;
+  const cellX = (i: number) => LABEL_W + m.cells[i]!.col * PITCH - scrollX;
+  const popLeft = pop ? Math.max(0, Math.min(cellX(pop.index) - POP_W / 2 + CELL / 2, Math.max(0, width - POP_W))) : 0;
+  const popTop = popCell ? 16 + (popCell.row + 1) * PITCH + 8 : 0;
+
+  return (
+    <OnboardingCard testID={testID} header={config} copy={config} density={density} status={pattern.status} onRetry={pattern.retry} onEmptyAction={pattern.retry} meta={meta} metaWraps>
+      <View ref={ref} style={{ opacity: clock.reduced ? clock.fade : 1, gap: 14 }}>
+        <View role={'list' as never} aria-label="Stats" style={{ flexDirection: 'row', paddingVertical: 12, paddingHorizontal: 14, gap: 12, borderRadius: blockRadii.mid, backgroundColor: colors.surfaceSunken }}>
+          {[
+            ['Daily avg', stat(m.avg).toFixed(1), null],
+            ['Peak', m.peakDate ? `${Math.round(stat(m.peak))} on ${shortDay(parseDay(m.peakDate))}` : peakText(m), null],
+            ['Streak', `${Math.round(stat(m.streak))}d`, `best ${Math.round(stat(m.best))}d`],
+          ].map(([dt, dd, extra]) => (
+            <View key={dt as string} role={'listitem' as never} style={{ flex: 1, minWidth: 0, gap: 2 }}>
+              <Text style={{ fontSize: 12, color: colors.textSecondary }}>{dt as string}</Text>
+              <Box row align="center" gap="s1" style={{ flexWrap: 'wrap' }}>
+                {dt === 'Streak' ? <View aria-hidden><Icon name="flame" size={15} color={colors.textPrimary} /></View> : null}
+                <Text numeric style={{ fontSize: 20, fontWeight: '600', letterSpacing: -0.3, color: colors.textPrimary }}>{dd as string}</Text>
+                {extra ? <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{extra as string}</Text> : null}
+              </Box>
+            </View>
+          ))}
+        </View>
+
+        <View style={{ position: 'relative', minHeight: pop && popH ? popTop + popH + 4 : undefined }} onLayout={e => setWidth(e.nativeEvent.layout.width)}>
+          <View style={{ flexDirection: 'row' }}>
+            <View aria-hidden style={{ width: LABEL_W, paddingTop: 16 }}>
+              {[0, 1, 2, 3, 4, 5, 6].map(r => (
+                <Text key={r} style={{ height: PITCH, fontSize: 10, lineHeight: CELL, color: colors.textSecondary }}>{r % 2 === 0 && r < 6 ? ['Mon', '', 'Wed', '', 'Fri'][r] : ''}</Text>
+              ))}
+            </View>
+            <ScrollView
+              ref={scroller}
+              horizontal
+              showsHorizontalScrollIndicator
+              onContentSizeChange={() => scroller.current?.scrollToEnd({ animated: false })}
+              onScroll={e => setScrollX(e.nativeEvent.contentOffset.x)}
+              scrollEventThrottle={16}
+              style={{ flex: 1 }}>
+              <View style={{ paddingBottom: 4 }}>
+                <View aria-hidden style={{ height: 16, position: 'relative', width: m.cols * PITCH }}>
+                  {m.months.map(mo => (
+                    <Text key={`${mo.col}${mo.label}`} style={{ position: 'absolute', left: mo.col * PITCH, top: 0, fontSize: 10, color: colors.textSecondary }}>{mo.label}</Text>
+                  ))}
+                </View>
+                <View role={'grid' as never} aria-label={`${config.title}, ${config.periodLabel}`} style={{ flexDirection: 'row', gap: GAP }}>
+                  {Array.from({ length: m.cols }, (_, col) => (
+                    <View key={col} style={{ gap: GAP }}>
+                      {m.cells.slice(col * 7, col * 7 + 7).map((c, row) => cellView(c, col * 7 + row))}
+                    </View>
+                  ))}
+                </View>
+              </View>
+            </ScrollView>
+          </View>
+
+          {hovered && !pop ? (
+            <View pointerEvents="none" role="tooltip" style={{ position: 'absolute', zIndex: 4, left: Math.max(0, cellX(hover!) - 40), top: hovered.row * PITCH - 16, paddingVertical: 6, paddingHorizontal: 10, borderRadius: blockRadii.inset, backgroundColor: colors.textPrimary, boxShadow: lift2 } as object}>
+              <Text numeric style={{ fontSize: 12, color: colors.surface1 }}>{`${shortDay(hovered.t)} · ${hovered.future ? 'upcoming' : countOf(hovered.count, noun, one)}`}</Text>
+            </View>
+          ) : null}
+
+          {pop && popCell ? (
+            <>
+              <View
+                ref={popRef as never}
+                role="dialog"
+                aria-label={longDay(popCell.t)}
+                {...({ tabIndex: -1, onKeyDown: (e: { key: string }) => { if (e.key === 'Escape') closePop(); } } as object)}
+                onLayout={e => setPopH(e.nativeEvent.layout.height)}
+                style={{ position: 'absolute', zIndex: 6, left: popLeft, top: popTop, width: Math.min(POP_W, width || POP_W), padding: 14, gap: 10, borderRadius: blockRadii.mid, backgroundColor: colors.surface1, borderWidth: 1, borderColor: colors.hairline, boxShadow: lift2 } as object}>
+                <Box row align="center" justify="space-between" gap="s2">
+                  <View style={{ gap: 2, flexShrink: 1 }}>
+                    <Text style={{ fontSize: 13, fontWeight: '600', color: colors.textPrimary }}>{longDay(popCell.t)}</Text>
+                    <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{countOf(popCell.count, noun, one)}</Text>
+                  </View>
+                  {popCell.level ? <PlainChip height={22}>{String(LEVEL_CHIP[popCell.level])}</PlainChip> : null}
+                </Box>
+                {!popCell.count ? (
+                  <Text style={{ fontSize: 13, color: colors.textSecondary }}>{`No ${noun} on this day`}</Text>
+                ) : pop.phase === 'loading' ? (
+                  <View aria-busy style={{ gap: 8 }}>
+                    {[70, 55, 62].map(w => <View key={w} style={{ height: 10, width: `${w}%`, borderRadius: 999, backgroundColor: colors.band }} />)}
+                  </View>
+                ) : pop.phase === 'failed' ? (
+                  <ApricotAlert title="Couldn’t load this day" action={<Button variant="secondary" size="xsmall" onPress={() => load(pop.index)}>Retry</Button>} />
+                ) : (
+                  <>
+                    <View role={'list' as never} aria-label={`${noun} on ${shortDay(popCell.t)}`} style={{ gap: 8 }}>
+                      {pop.items.map((it, k) => (
+                        <View key={k} role={'listitem' as never} style={{ gap: 1 }}>
+                          <Text numberOfLines={1} style={{ fontSize: 13, color: colors.textPrimary }}>{it.title}</Text>
+                          {it.meta ? <Text numeric numberOfLines={1} style={{ fontSize: 12, color: colors.textSecondary }}>{it.meta}</Text> : null}
+                        </View>
+                      ))}
+                    </View>
+                    {comparedToAverage(popCell.count, m.avg) ? <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{comparedToAverage(popCell.count, m.avg)}</Text> : null}
+                    <Button variant="secondary" size="small" onPress={() => onOpen?.(popCell.key)}>{`View all ${popCell.count}`}</Button>
+                  </>
+                )}
+              </View>
+            </>
+          ) : null}
+        </View>
+
+        <Box row align="center" justify="space-between" gap="s2" style={{ flexWrap: 'wrap' }}>
+          <Box row align="center" gap="s1">
+            <Text style={{ fontSize: 11, color: colors.textSecondary }}>Less</Text>
+            {ramp.map((col, lv) => (
+              <DataTip key={lv} label={ranges[lv]!} style={{ padding: 1 }}>
+                <View style={{ width: CELL, height: CELL, borderRadius: 4, backgroundColor: col }} />
+              </DataTip>
+            ))}
+            <Text style={{ fontSize: 11, color: colors.textSecondary }}>More</Text>
+          </Box>
+          <Text style={{ fontSize: 11, color: colors.textSecondary }}>Click a day for details</Text>
+        </Box>
+      </View>
+    </OnboardingCard>
+  );
+}
+
+/** ActivityHeatmap, guarded: a wrong-kind config is refused by name and a render error is caught (`shared/guard`). */
+export const ActivityHeatmap = guarded(ActivityHeatmapView, HEATMAP_PRESETS, 'ActivityHeatmap');

package/src/components/onboarding/activity-heatmap/contract.ts

@@ -0,0 +1,68 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import { ISO_DATE, parseDay } from '../shared/insight';
+import presetsJson from './presets.json';
+
+/**
+ * **Activity Heatmap (batch 6 §4.4)** — a daily-count grid on the card's hue ramp: stats, a
+ * GitHub-style week grid that scrolls to the latest week, a legend, and a day popover. Read-only
+ * but for the popover, which loads a day's items through `operations.loadDay`. M15 reveals the
+ * grid in one of three modes, within 900ms.
+ */
+
+export type HeatmapDay = { date: string; count: number };
+export type HeatmapItem = { title: string; meta?: string };
+
+export const HEATMAP_REVEALS = ['sweep', 'diagonal', 'intensity'] as const;
+export type HeatmapReveal = (typeof HEATMAP_REVEALS)[number];
+
+export const HEATMAP_SCENES = ['default', 'popover', 'zeroDay', 'loadReady', 'loading', 'empty', 'error'] as const;
+export type HeatmapScene = (typeof HEATMAP_SCENES)[number];
+export const HEATMAP_IN_FLIGHT: readonly string[] = [];
+
+export type HeatmapSettings = HeaderConfig & LoadCopy & {
+  /** "reviews" / "review". */
+  noun: string;
+  nounOne: string;
+  /** The header chip — "Jan–Mar 2026". */
+  periodLabel: string;
+  /** The grid's first and last day (YYYY-MM-DD). `null`: the first and last day in `days`. */
+  range: { start: string; end: string } | null;
+  /** One row per day — `{ date: YYYY-MM-DD, count }` — or a `date → count` record. A missing day is 0. */
+  days: HeatmapDay[] | Record<string, number>;
+  reveal: HeatmapReveal;
+  /** The day drawn as today (ink outline); later days are the future (outlined, empty). `null`: the real today. */
+  today: string | null;
+  /** The popover's items when there is no `loadDay` — up to three show. */
+  sample: HeatmapItem[];
+  /** Demo-only: the scene this case ships in. */
+  ship: HeatmapScene | null;
+};
+
+export const HEATMAP_PRESETS = presetsJson as unknown as PresetsFile<HeatmapSettings>;
+
+export function validateHeatmap(c: HeatmapSettings): OnboardingIssue[] {
+  if (!c || typeof c !== 'object') return [{ path: 'config', message: 'must be an object.' }];
+  const out: OnboardingIssue[] = [];
+  if (Array.isArray(c.days)) {
+    c.days.forEach((d, i) => {
+      if (!d || typeof d !== 'object') { out.push({ path: `days[${i}]`, message: 'Each day is { date, count }.' }); return; }
+      if (typeof d.date !== 'string' || !Number.isFinite(parseDay(d.date))) out.push({ path: `days[${i}].date`, message: 'date is YYYY-MM-DD.' });
+      if (typeof d.count !== 'number' || !Number.isFinite(d.count) || d.count < 0) out.push({ path: `days[${i}].count`, message: 'count is a number, 0 or more.' });
+    });
+  } else if (c.days && typeof c.days === 'object') {
+    for (const [k, v] of Object.entries(c.days)) {
+      if (!ISO_DATE.test(k) || !Number.isFinite(parseDay(k))) out.push({ path: `days.${k}`, message: 'Keys are dates, YYYY-MM-DD.' });
+      else if (typeof v !== 'number' || !Number.isFinite(v) || v < 0) out.push({ path: `days.${k}`, message: 'Each count is a number, 0 or more.' });
+    }
+  } else out.push({ path: 'days', message: 'days is a list of { date, count }.' });
+  if (c.range !== null && c.range !== undefined) {
+    const s = parseDay((c.range as { start?: string }).start as string), e = parseDay((c.range as { end?: string }).end as string);
+    if (!Number.isFinite(s) || !Number.isFinite(e)) out.push({ path: 'range', message: 'range is { start, end }, each YYYY-MM-DD — or null.' });
+    else if (e < s) out.push({ path: 'range', message: 'range.end is before range.start.' });
+    else if ((e - s) / 864e5 > 800) out.push({ path: 'range', message: 'range is at most about two years.' });
+  }
+  if (!(HEATMAP_REVEALS as readonly string[]).includes(c.reveal)) out.push({ path: 'reveal', message: `reveal is ${HEATMAP_REVEALS.join(', ')}.` });
+  if (c.today !== null && c.today !== undefined && !Number.isFinite(parseDay(c.today))) out.push({ path: 'today', message: 'today is YYYY-MM-DD, or null for the real today.' });
+  if (c.sample !== undefined && !(Array.isArray(c.sample) && c.sample.every(s => s && typeof s.title === 'string'))) out.push({ path: 'sample', message: 'sample is a list of { title, meta }.' });
+  return out;
+}

package/src/components/onboarding/activity-heatmap/engine.ts

@@ -0,0 +1,146 @@
+import { DAY_MS, MONTHS, countOf, dayKey, parseDay, quantile, shortDay, todayKey, weekday } from '../shared/insight';
+import type { HeatmapReveal, HeatmapScene, HeatmapSettings } from './contract';
+
+/** **The Activity Heatmap engine** — pure: the grid, the levels, the stats and the reveal's timing. */
+
+export type HeatCell = {
+  key: string; t: number; col: number; row: number;
+  /** Inside the range (a cell outside it is not drawn). */
+  inRange: boolean;
+  future: boolean;
+  today: boolean;
+  count: number;
+  /** 0 (none) … 4, from quantiles of the non-zero days. */
+  level: number;
+};
+
+export type HeatModel = {
+  cells: HeatCell[];
+  cols: number;
+  /** Days counted (the range up to today), their total and the days with activity. */
+  days: number; total: number; active: number;
+  avg: number;
+  peak: number; peakDate: string | null;
+  /** The latest day with nothing — the zero-day demo's popover. */
+  zeroDate: string | null;
+  streak: number; best: number;
+  /** The level cut-offs: ≤ q1 is 1, ≤ q2 is 2, ≤ q3 is 3, above is 4. */
+  q: [number, number, number];
+  min: number; max: number;
+  months: { col: number; label: string }[];
+};
+
+export function dayCounts(c: HeatmapSettings): Record<string, number> {
+  if (Array.isArray(c.days)) {
+    const out: Record<string, number> = {};
+    for (const d of c.days) if (d && typeof d.date === 'string') out[d.date] = (out[d.date] ?? 0) + (Number(d.count) || 0);
+    return out;
+  }
+  return { ...(c.days ?? {}) };
+}
+
+/** The grid's range: the configured one, or the first and last day given. */
+export function rangeOf(c: HeatmapSettings): { start: string; end: string } | null {
+  if (c.range) return c.range;
+  const keys = Object.keys(dayCounts(c)).filter(k => Number.isFinite(parseDay(k))).sort();
+  return keys.length ? { start: keys[0]!, end: keys[keys.length - 1]! } : null;
+}
+
+export function heatModel(c: HeatmapSettings, today = c.today ?? todayKey()): HeatModel {
+  const r = rangeOf(c);
+  const empty: HeatModel = { cells: [], cols: 0, days: 0, total: 0, active: 0, avg: 0, peak: 0, peakDate: null, zeroDate: null, streak: 0, best: 0, q: [0, 0, 0], min: 0, max: 0, months: [] };
+  if (!r) return empty;
+  const counts = dayCounts(c);
+  const s = parseDay(r.start), e = parseDay(r.end), now = parseDay(today);
+  if (!Number.isFinite(s) || !Number.isFinite(e) || e < s) return empty;
+  const g0 = s - weekday(s) * DAY_MS;
+  const cols = Math.floor((e - g0) / DAY_MS / 7) + 1;
+  const nz: number[] = [];
+  let total = 0, n = 0, peak = 0, peakDate: string | null = null, zeroDate: string | null = null, run = 0, best = 0;
+  for (let t = s; t <= Math.min(e, now); t += DAY_MS) {
+    const k = dayKey(t), v = counts[k] ?? 0;
+    n++; total += v;
+    if (v > 0) { nz.push(v); run++; best = Math.max(best, run); } else { run = 0; zeroDate = k; }
+    if (v > peak) { peak = v; peakDate = k; }
+  }
+  nz.sort((a, b) => a - b);
+  const q: [number, number, number] = [quantile(nz, 0.25), quantile(nz, 0.5), quantile(nz, 0.75)];
+  const cells: HeatCell[] = [];
+  for (let col = 0; col < cols; col++) {
+    for (let row = 0; row < 7; row++) {
+      const t = g0 + (col * 7 + row) * DAY_MS, k = dayKey(t);
+      const inRange = t >= s && t <= e, future = t > now, v = counts[k] ?? 0;
+      cells.push({ key: k, t, col, row, inRange, future, today: t === now, count: v, level: !inRange || future || !v ? 0 : v <= q[0] ? 1 : v <= q[1] ? 2 : v <= q[2] ? 3 : 4 });
+    }
+  }
+  const months: HeatModel['months'] = [];
+  for (let col = 0; col < cols; col++) {
+    const m = new Date(g0 + (col * 7 + 6) * DAY_MS).getUTCMonth();
+    const prev = col ? new Date(g0 + ((col - 1) * 7 + 6) * DAY_MS).getUTCMonth() : -1;
+    if (m !== prev) months.push({ col, label: MONTHS[m]! });
+  }
+  return { cells, cols, days: n, total, active: nz.length, avg: n ? total / n : 0, peak, peakDate, zeroDate, streak: run, best, q, min: nz[0] ?? 0, max: nz[nz.length - 1] ?? 0, months };
+}
+
+/** The legend's ranges — "Level 3 · 8–14 reviews". Level 0 is "No reviews". */
+export function levelRanges(m: HeatModel, noun: string, one: string): string[] {
+  const span = (a: number, b: number) => (a >= b ? countOf(b, noun, one) : `${a}–${b} ${noun}`);
+  return [
+    `Level 0 · No ${noun}`,
+    `Level 1 · ${span(m.min, m.q[0])}`,
+    `Level 2 · ${span(m.q[0] + 1, m.q[1])}`,
+    `Level 3 · ${span(m.q[1] + 1, m.q[2])}`,
+    `Level 4 · ${span(m.q[2] + 1, m.max)}`,
+  ];
+}
+
+/** A day's chip: Top 25% day, Above median, Below median, Quiet day. */
+export const LEVEL_CHIP = ['', 'Quiet day', 'Below median', 'Above median', 'Top 25% day'] as const;
+
+/** "2.8× your daily average" — or "About your daily average", or "Below your daily average". */
+export function comparedToAverage(count: number, avg: number): string {
+  if (!avg) return '';
+  const x = count / avg;
+  if (x >= 1.15) return `${x.toFixed(1)}× your daily average`;
+  if (x >= 0.85) return 'About your daily average';
+  return 'Below your daily average';
+}
+
+/** "22 on Mar 14" */
+export const peakText = (m: HeatModel) => (m.peakDate ? `${m.peak} on ${shortDay(parseDay(m.peakDate))}` : '—');
+
+/** "705 reviews in 81 days" — the days with activity. */
+export const headerTotal = (m: HeatModel, noun: string, one: string) => `${countOf(m.total, noun, one)} in ${countOf(m.active, 'days', 'day')}`;
+
+/**
+ * **The reveal (all within 900ms)**. `sweep`: by column. `diagonal`: by column + row. `intensity`:
+ * every cell shows at level 0, then colour arrives lightest level first, 200ms apart.
+ */
+export function cellDelay(mode: HeatmapReveal, cell: { col: number; row: number; level: number }, cols: number): number {
+  if (mode === 'diagonal') return ((cell.col + cell.row) * 900) / (cols + 6);
+  if (mode === 'intensity') return Math.max(0, cell.level - 1) * 200;
+  return (cell.col * 900) / Math.max(1, cols);
+}
+export const HEAT_REVEAL_END = 900 + 200;
+
+export type HeatState = { pop: 'peak' | 'zero' | null; loadReady: boolean };
+export type HeatSeed = Partial<HeatState>;
+
+export function initialHeatmap(_c: HeatmapSettings, seed: HeatSeed = {}): HeatState {
+  return { pop: seed.pop ?? null, loadReady: seed.loadReady ?? false };
+}
+
+export function heatmapSeed(_c: HeatmapSettings, scene: HeatmapScene): HeatSeed {
+  if (scene === 'popover') return { pop: 'peak' };
+  if (scene === 'zeroDay') return { pop: 'zero' };
+  if (scene === 'loadReady') return { loadReady: true };
+  return {};
+}
+
+/** Roving focus: ↑/↓ a day, ←/→ a week — to the nearest drawn cell, or stay. */
+export function moveFocus(cells: HeatCell[], from: number, key: string): number {
+  const step = ({ ArrowUp: -1, ArrowDown: 1, ArrowLeft: -7, ArrowRight: 7 } as Record<string, number>)[key];
+  if (!step) return from;
+  const to = from + step;
+  return cells[to]?.inRange ? to : from;
+}

package/src/components/onboarding/activity-heatmap/index.ts

@@ -0,0 +1,9 @@
+export {
+  HEATMAP_IN_FLIGHT, HEATMAP_PRESETS, HEATMAP_REVEALS, HEATMAP_SCENES, validateHeatmap,
+  type HeatmapDay, type HeatmapItem, type HeatmapReveal, type HeatmapScene, type HeatmapSettings,
+} from './contract';
+export {
+  HEAT_REVEAL_END, LEVEL_CHIP, cellDelay, comparedToAverage, dayCounts, headerTotal, heatModel, heatmapSeed, initialHeatmap, levelRanges, moveFocus, peakText, rangeOf,
+  type HeatCell, type HeatModel, type HeatSeed, type HeatState,
+} from './engine';
+export { ActivityHeatmap, type ActivityHeatmapProps, type HeatmapOperations } from './ActivityHeatmapView';