@appinternalleads/ui 0.2.0

package/src/components/onboarding/score-summary/ScoreSummaryView.tsx

@@ -0,0 +1,268 @@
+import { useEffect, useMemo, useState, type ReactNode } from 'react';
+import { View } from 'react-native';
+import { Box, Select, Text } from '../../../core';
+import { blockRadii, useDs, type DensityName } from '../../../tokens';
+import { resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+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 { BandChip, Stars } from '../shared/insight-parts';
+import { M15, grouped, progress, toneIn } from '../shared/m15';
+import { DataTip, RevealRow, VizBar, useInView, useRevealClock, useTweenedValues } from '../shared/viz';
+import { SCORE_PRESETS, validateScoreSummary, type ScoreSettings } from './contract';
+import { initialScore, scorePanels, scoreRevealEnd, scoreScene, scoreSeed, scoreStarts, scoreText, type ScoreSeed } from './engine';
+
+export type ScoreSummaryProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<ScoreSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  /** Read-only; accepted for the shared shape. */
+  result?: OnboardingResult;
+  reload?: OnboardingOperation<void>;
+  initial?: ScoreSeed;
+  /** `mobile`: the panels stack. */
+  viewport?: 'web' | 'mobile';
+  /** A distribution row pressed — its bucket id. Without it, a row is focusable only (to reach its tooltip). */
+  onFilter?: (bucketId: string) => void;
+  onPeriodChange?: (period: string) => void;
+  replay?: number;
+  forceReduced?: boolean;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **Score Summary** — the panels given, in a 2-column grid with line-soft dividers (four: 2 × 2;
+ * three: two, then one full width; two: one row; mobile: stacked). A · the score at 48/700 with
+ * stars and a band chip; B · the distribution, relative to the largest bucket; C · categories,
+ * absolute to `max`; D · sentiment, a stacked bar of three segments. M15 runs the panels in turn;
+ * a period switch tweens every value with no cascade.
+ */
+function ScoreSummaryView(props: ScoreSummaryProps) {
+  const config = resolveConfig(SCORE_PRESETS, props.preset, props.config);
+  const issues = validateScoreSummary(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+function Valid({
+  config, density, status, reload, initial, viewport = 'web', onFilter, onPeriodChange, replay, forceReduced, onScene, testID,
+}: Omit<ScoreSummaryProps, 'config'> & { config: ScoreSettings }) {
+  const { colors } = useDs();
+  const key = JSON.stringify([config, initial ?? null]);
+  const seed = useMemo(() => initialScore(config, initial ?? (config.ship ? scoreSeed(config, config.ship) : {})), [key]);
+  const [period, setPeriod] = useState(seed.period);
+  useEffect(() => setPeriod(seed.period), [seed]);
+  const state = { ...seed, period };
+  const p = scorePanels(config, state);
+
+  const pattern = usePatternStatus(status ?? (seed.loadReady ? 'loading' : p.present.length ? 'ready' : 'empty'), reload);
+  useEffect(() => {
+    if (!seed.loadReady || status) return;
+    const t = setTimeout(() => pattern.set('ready'), 1200);
+    return () => clearTimeout(t);
+  }, [seed, status, replay]);
+  useSceneReport(pattern.status === 'ready' ? (seed.loadReady ? 'loadReady' : scoreScene(state, config)) : pattern.status, onScene);
+
+  const [ref, inView] = useInView();
+  const clock = useRevealClock(inView && pattern.status === 'ready', scoreRevealEnd(p), `${replay ?? 0}|${pattern.status}`, forceReduced);
+  const t = clock.t;
+  const st = scoreStarts(p.present);
+  const nb = p.buckets.length, nc = p.cats.length;
+  const sent = p.sentiment;
+  const targets = [
+    p.score?.value ?? 0,
+    ...p.buckets.map(b => b.count), ...p.buckets.map(b => b.ratio),
+    ...p.cats.map(x => x.value), ...p.cats.map(x => x.ratio),
+    sent?.positivePct ?? 0,
+    ...(sent && sent.total ? [sent.positive / sent.total, sent.neutral / sent.total, sent.negative / sent.total] : [0, 0, 0]),
+  ];
+  const shown = useTweenedValues(targets, M15.fillMs, clock.done, clock.reduced);
+  const at = (i: number, reveal: () => number) => (clock.done ? shown[i]! : reveal());
+
+  const mobile = viewport === 'mobile';
+  const cols = mobile || p.present.length === 1 ? 1 : 2;
+  const tones = { good: colors.status.executed, mid: colors.statusBg.needsUser, bad: colors.status.needsUser };
+
+  const meta = config.periods.length > 1 ? (
+    <Box style={{ minWidth: 132 }}>
+      <Select aria-label="Period" value={period} options={config.periods.map(x => ({ value: x, label: x }))} onChange={x => { setPeriod(x); onPeriodChange?.(x); }} />
+    </Box>
+  ) : <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{config.period}</Text>;
+
+  const panels: Record<'a' | 'b' | 'c' | 'd', () => ReactNode> = {
+    a: () => {
+      const s = p.score!;
+      const a = st.a ?? 0;
+      const v = at(0, () => s.value * progress(t, a, M15.fillMs));
+      const bandIn = clock.done ? 1 : progress(t, a + M15.fillMs, M15.toneMs);
+      return (
+        <>
+          <Box row align="flex-end" gap="s1">
+            <Text numeric style={{ fontSize: 48, lineHeight: 52, fontWeight: '700', letterSpacing: -1, color: colors.textPrimary }}>{scoreText(v, s.digits, s.signed)}</Text>
+            <Text numeric style={{ fontSize: 14, color: colors.textSecondary, marginBottom: 8 }}>{s.maxLabel ?? `/ ${s.max}`}</Text>
+          </Box>
+          {s.stars ? (
+            <Stars value={s.value} max={s.max} size={18} pop={clock.done ? undefined : i => { const q = progress(t, a + i * 60, M15.toneMs); return { opacity: q, scale: 0.6 + 0.4 * q }; }} />
+          ) : null}
+          <View style={{ opacity: bandIn }}><BandChip label={s.band.label} tone={s.band.tone} /></View>
+          {s.count ? <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{s.count}</Text> : null}
+          {s.stat ? <Text numeric style={{ fontSize: 13, fontWeight: '600', color: colors.textPrimary }}>{s.stat}</Text> : null}
+        </>
+      );
+    },
+    b: () => {
+      const b0 = st.b ?? 0;
+      const lw = p.distribution?.labelWidth ?? 36;
+      return (
+        <>
+          <PanelTitle>{p.distribution?.title ?? ''}</PanelTitle>
+          <View role={'list' as never} aria-label={p.distribution?.title}>
+            {p.buckets.map((b, j) => {
+              const start = b0 + j * 60;
+              const fill = progress(t, start, M15.fillMs);
+              const toneP = clock.done ? 1 : toneIn(start + M15.fillMs, t);
+              const rowIn = clock.reduced ? 1 : progress(t, start, M15.rowMs);
+              return (
+                <RevealRow key={b.id} opacity={rowIn} y={-M15.dropPx * (1 - rowIn)}>
+                  <View role={'listitem' as never}>
+                    <DataTip label={b.tip} onPress={onFilter ? () => onFilter(b.id) : undefined} style={{ paddingHorizontal: 6, paddingVertical: 5 }}>
+                      <Box row align="center" gap="s2">
+                        <Text numeric numberOfLines={1} style={{ width: lw, fontSize: 12, color: colors.textSecondary }}>{b.label}</Text>
+                        <View style={{ flex: 1 }}>
+                          <VizBar
+                            scale={at(1 + nb + j, () => b.ratio * fill)}
+                            color={toneP >= 1 ? tones[b.tone] : colors.textSecondary}
+                            track={colors.band}
+                            overlay={toneP >= 1 ? undefined : { color: tones[b.tone], opacity: toneP }}
+                            a11y={{ role: 'meter', label: b.tipLabel ?? b.label, now: b.pct, max: 100, text: b.tip }}
+                          />
+                        </View>
+                        <Text numeric style={{ minWidth: 44, textAlign: 'right', fontSize: 12, color: colors.textPrimary }}>{grouped(at(1 + j, () => b.count * fill))}</Text>
+                      </Box>
+                    </DataTip>
+                  </View>
+                </RevealRow>
+              );
+            })}
+          </View>
+        </>
+      );
+    },
+    c: () => {
+      const c0 = st.c ?? 0;
+      const max = p.categories?.max ?? 5;
+      return (
+        <>
+          <PanelTitle>{p.categories?.title ?? ''}</PanelTitle>
+          <View role={'list' as never} aria-label={p.categories?.title} style={{ gap: 8 }}>
+            {p.cats.map((x, j) => {
+              const start = c0 + j * 60;
+              const fill = progress(t, start, M15.fillMs);
+              const rowIn = clock.reduced ? 1 : progress(t, start, M15.rowMs);
+              const v = at(1 + 2 * nb + j, () => x.value * fill);
+              return (
+                <RevealRow key={`${x.label}${j}`} opacity={rowIn} y={-M15.dropPx * (1 - rowIn)}>
+                  <Box row align="center" gap="s2" role={'listitem' as never}>
+                    <Text numberOfLines={1} style={{ width: 96, fontSize: 12, color: colors.textPrimary }}>{x.label}</Text>
+                    <View style={{ flex: 1 }}>
+                      <VizBar
+                        scale={at(1 + 2 * nb + nc + j, () => x.ratio * fill)}
+                        color={colors.textSecondary}
+                        track={colors.band}
+                        a11y={{ role: 'meter', label: x.label, now: x.value, max, text: `${x.value.toFixed(x.digits)} out of ${max}` }}
+                      />
+                    </View>
+                    <Text numeric style={{ minWidth: 32, textAlign: 'right', fontSize: 12, fontWeight: '600', color: colors.textPrimary }}>{v.toFixed(x.digits)}</Text>
+                  </Box>
+                </RevealRow>
+              );
+            })}
+          </View>
+        </>
+      );
+    },
+    d: () => {
+      const s = sent!;
+      const d0 = st.d ?? 0;
+      const base = 1 + 2 * nb + 2 * nc;
+      const pct = at(base, () => s.positivePct * progress(t, d0, 900));
+      const shares = [0, 1, 2].map(k => (s.total ? [s.positive, s.neutral, s.negative][k]! / s.total : 0));
+      const segColor = [colors.status.executed, colors.textSecondary, colors.status.needsUser];
+      let left = 0;
+      return (
+        <>
+          <Box row align="center" justify="space-between" gap="s2">
+            <PanelTitle>{s.title}</PanelTitle>
+            {s.period ? <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{s.period}</Text> : null}
+          </Box>
+          <Text numeric style={{ fontSize: 20, fontWeight: '600', letterSpacing: -0.3, color: colors.textPrimary }}>{`${Math.round(pct)}% positive`}</Text>
+          <View
+            role="img"
+            aria-label={`${s.labels[0]}: ${grouped(s.positive)}, ${s.labels[1]}: ${grouped(s.neutral)}, ${s.labels[2]}: ${grouped(s.negative)}`}
+            style={{ height: 10, borderRadius: 999, backgroundColor: colors.band, overflow: 'hidden', position: 'relative' }}>
+            {shares.map((share, k) => {
+              const w = clock.done ? shown[base + 1 + k]! : share;
+              const l = left;
+              left += w;
+              const fill = clock.done ? 1 : progress(t, d0 + k * 300, 300);
+              return w > 0 ? (
+                <View key={k} style={{ position: 'absolute', top: 0, bottom: 0, left: `${l * 100}%`, width: `${w * 100}%`, backgroundColor: segColor[k], transform: [{ scaleX: fill }], transformOrigin: 'left' } as object} />
+              ) : null;
+            })}
+          </View>
+          <Box row gap="s3" style={{ flexWrap: 'wrap' }}>
+            {s.labels.map((label, k) => (
+              <Box key={label} row align="center" gap="s1">
+                <Box width={8} height={8} radius="pill" aria-hidden style={{ backgroundColor: segColor[k] }} />
+                <Text style={{ fontSize: 12, color: colors.textSecondary }}>{label}</Text>
+                <Text numeric style={{ fontSize: 12, fontWeight: '600', color: colors.textPrimary }}>{grouped([s.positive, s.neutral, s.negative][k]!)}</Text>
+              </Box>
+            ))}
+          </Box>
+          {s.note ? (
+            <View style={{ paddingVertical: 8, paddingHorizontal: 12, borderRadius: blockRadii.mid, backgroundColor: colors.surfaceSunken }}>
+              <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{s.note}</Text>
+            </View>
+          ) : null}
+        </>
+      );
+    },
+  };
+
+  return (
+    <OnboardingCard testID={testID} header={config} copy={config} density={density} status={pattern.status} onRetry={pattern.retry} onEmptyAction={pattern.retry} meta={meta} flush>
+      <View ref={ref} style={{ opacity: clock.reduced ? clock.fade : 1, flexDirection: 'row', flexWrap: 'wrap' }}>
+        {p.present.map((k, i) => {
+          const full = cols === 1 || (p.present.length === 3 && i === 2);
+          const col = full ? 0 : i % 2;
+          const row = cols === 1 ? i : Math.floor(i / 2);
+          return (
+            <View
+              key={k}
+              style={{
+                width: full ? '100%' : '50%',
+                paddingTop: 18, paddingHorizontal: 20, paddingBottom: 20, gap: 10,
+                borderRightWidth: cols === 2 && col === 0 && !full ? 1 : 0,
+                borderTopWidth: row > 0 ? 1 : 0,
+                borderColor: colors.hairline,
+              }}>
+              {panels[k]()}
+            </View>
+          );
+        })}
+      </View>
+    </OnboardingCard>
+  );
+}
+
+function PanelTitle({ children }: { children: string }) {
+  const { colors } = useDs();
+  return <Text style={{ fontSize: 13, fontWeight: '600', color: colors.textPrimary }}>{children}</Text>;
+}
+
+/** ScoreSummary, guarded: a wrong-kind config is refused by name and a render error is caught (`shared/guard`). */
+export const ScoreSummary = guarded(ScoreSummaryView, SCORE_PRESETS, 'ScoreSummary');

package/src/components/onboarding/score-summary/contract.ts

@@ -0,0 +1,96 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import type { Band } from '../shared/insight';
+import presetsJson from './presets.json';
+
+/**
+ * **Score Summary (batch 6 §4.2)** — up to four panels in a 2 × 2 card: A · Score, B ·
+ * Distribution, C · Categories, D · Sentiment. Only the panels given are drawn. Read-only; the
+ * only entrance animation is M15, one panel after another (~2.4s for all four).
+ *
+ * The data sits in lists a sheet can fill (`buckets`, `categoryScores`, `periodScores`), each row
+ * naming its `period` when there are several; the panel objects hold only titles and options.
+ */
+
+export type ScoreBucket = { id?: string; label: string; count: number; tone: 'good' | 'mid' | 'bad'; tipLabel?: string; period?: string };
+export type ScoreCategory = { label: string; value: number; period?: string };
+export type ScorePanelA = {
+  value: number;
+  max: number;
+  stars?: boolean;
+  /** "3,842 reviews" */
+  count?: string;
+  /** "94% would recommend" */
+  stat?: string;
+  /** Replaces "/ 5" — "NPS". */
+  maxLabel?: string;
+  /** A "+" before a positive value (NPS). */
+  signed?: boolean;
+  /** Highest `min` first or not — they are sorted. Default: 90 / 80 / 60% of max. */
+  bands?: Band[];
+};
+
+export const SCORE_SCENES = ['default', 'period', 'loadReady', 'loading', 'empty', 'error'] as const;
+export type ScoreScene = (typeof SCORE_SCENES)[number];
+export const SCORE_IN_FLIGHT: readonly string[] = [];
+
+export type ScoreSettings = HeaderConfig & LoadCopy & {
+  period: string;
+  /** More than one: a period select in the header; switching tweens every value, no cascade. */
+  periods: string[];
+  /** Panel A. `null`: no score panel. */
+  score: ScorePanelA | null;
+  /** Per-period score values — `{ period, value, count }` — over `score` for that period. */
+  periodScores: { period: string; value: number; count?: string }[];
+  /** Panel B's title and options; its rows are `buckets`. `null`: no distribution panel. */
+  distribution: { title: string; noun?: string; labelWidth?: number } | null;
+  buckets: ScoreBucket[];
+  /** Panel C's title and scale; its rows are `categoryScores`. `null`: no categories panel. */
+  categories: { title: string; max: number } | null;
+  categoryScores: ScoreCategory[];
+  /** Panel D. `labels` replace Positive / Neutral / Negative (Thumbs up / No rating / Thumbs down). */
+  sentiment: { title: string; period?: string; positive: number; neutral: number; negative: number; labels?: string[]; note?: string } | null;
+  /** Demo-only: the scene this case ships in. */
+  ship: ScoreScene | null;
+};
+
+export const SCORE_PRESETS = presetsJson as unknown as PresetsFile<ScoreSettings>;
+
+const num = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+const TONES = ['good', 'mid', 'bad'];
+
+export function validateScoreSummary(c: ScoreSettings): OnboardingIssue[] {
+  if (!c || typeof c !== 'object') return [{ path: 'config', message: 'must be an object.' }];
+  const out: OnboardingIssue[] = [];
+  if (c.score !== null && c.score !== undefined) {
+    if (typeof c.score !== 'object') out.push({ path: 'score', message: 'score is { value, max, … } or null.' });
+    else {
+      if (!num(c.score.value)) out.push({ path: 'score.value', message: 'score.value is a number.' });
+      if (!num(c.score.max) || c.score.max <= 0) out.push({ path: 'score.max', message: 'score.max is a number above 0.' });
+      if (c.score.bands !== undefined && !(Array.isArray(c.score.bands) && c.score.bands.every(b => b && num(b.min) && typeof b.label === 'string'))) {
+        out.push({ path: 'score.bands', message: 'bands are { min, label, tone } — tone mint, plain or apricot.' });
+      }
+    }
+  }
+  if (!Array.isArray(c.buckets)) out.push({ path: 'buckets', message: 'buckets is a list.' });
+  else c.buckets.forEach((b, i) => {
+    if (!b || typeof b !== 'object') { out.push({ path: `buckets[${i}]`, message: 'Each bucket is { label, count, tone }.' }); return; }
+    if (typeof b.label !== 'string') out.push({ path: `buckets[${i}].label`, message: 'Every bucket needs a label.' });
+    if (!num(b.count) || b.count < 0) out.push({ path: `buckets[${i}].count`, message: 'count is a number, 0 or more.' });
+    if (!TONES.includes(b.tone)) out.push({ path: `buckets[${i}].tone`, message: 'tone is good, mid or bad.' });
+  });
+  if (!Array.isArray(c.categoryScores)) out.push({ path: 'categoryScores', message: 'categoryScores is a list.' });
+  else c.categoryScores.forEach((x, i) => {
+    if (!x || typeof x !== 'object' || typeof x.label !== 'string') out.push({ path: `categoryScores[${i}].label`, message: 'Every category needs a label.' });
+    else if (!num(x.value)) out.push({ path: `categoryScores[${i}].value`, message: 'value is a number.' });
+  });
+  if (c.categories && typeof c.categories === 'object' && !(num(c.categories.max) && c.categories.max > 0)) out.push({ path: 'categories.max', message: 'categories.max is a number above 0.' });
+  if (c.sentiment && typeof c.sentiment === 'object') {
+    for (const k of ['positive', 'neutral', 'negative'] as const) if (!num(c.sentiment[k]) || c.sentiment[k] < 0) out.push({ path: `sentiment.${k}`, message: `${k} is a number, 0 or more.` });
+  }
+  if (c.periodScores !== undefined && !(Array.isArray(c.periodScores) && c.periodScores.every(p => p && typeof p.period === 'string' && num(p.value)))) {
+    out.push({ path: 'periodScores', message: 'periodScores are { period, value, count }.' });
+  }
+  if (!Array.isArray(c.periods) || c.periods.some(p => typeof p !== 'string')) out.push({ path: 'periods', message: 'periods is a list of period names.' });
+  else if (c.periods.length > 1 && !c.periods.includes(c.period)) out.push({ path: 'period', message: `“${c.period}” is not one of the periods.` });
+  return out;
+}

package/src/components/onboarding/score-summary/engine.ts

@@ -0,0 +1,97 @@
+import { bandOf, decimalsOf, defaultBands, type Band } from '../shared/insight';
+import { grouped } from '../shared/m15';
+import type { ScoreBucket, ScorePanelA, ScoreScene, ScoreSettings } from './contract';
+
+/** **The Score Summary engine** — pure: which panels, their figures, and the cascade's timing. */
+
+export type ScoreState = { period: string; loadReady: boolean };
+export type ScoreSeed = Partial<ScoreState>;
+
+export function initialScore(c: ScoreSettings, seed: ScoreSeed = {}): ScoreState {
+  return { period: seed.period ?? c.period, loadReady: seed.loadReady ?? false };
+}
+
+export function scoreSeed(c: ScoreSettings, scene: ScoreScene): ScoreSeed {
+  if (scene === 'period') {
+    const i = c.periods.indexOf(c.period);
+    return { period: c.periods.length > 1 ? c.periods[(i + 1) % c.periods.length]! : c.period };
+  }
+  if (scene === 'loadReady') return { loadReady: true };
+  return {};
+}
+
+const forPeriod = <T extends { period?: string }>(rows: T[], period: string) => rows.filter(r => !r.period || r.period === period);
+
+export type ScorePanels = {
+  score: (ScorePanelA & { band: Band; digits: number }) | null;
+  buckets: (ScoreBucket & { id: string; ratio: number; pct: number; tip: string })[];
+  distribution: ScoreSettings['distribution'];
+  categories: ScoreSettings['categories'];
+  cats: { label: string; value: number; ratio: number; digits: number }[];
+  sentiment: (NonNullable<ScoreSettings['sentiment']> & { total: number; positivePct: number; labels: string[] }) | null;
+  /** Which panels show, in order: a, b, c, d. */
+  present: ('a' | 'b' | 'c' | 'd')[];
+};
+
+export function scorePanels(c: ScoreSettings, s: ScoreState): ScorePanels {
+  const ps = (c.periodScores ?? []).find(p => p.period === s.period);
+  const score = c.score ? { ...c.score, ...(ps ? { value: ps.value, ...(ps.count ? { count: ps.count } : {}) } : {}) } : null;
+  const rawBuckets = c.distribution ? forPeriod(c.buckets ?? [], s.period) : [];
+  const largest = Math.max(0, ...rawBuckets.map(b => b.count));
+  const total = rawBuckets.reduce((a, b) => a + b.count, 0);
+  const noun = c.distribution?.noun ?? 'reviews';
+  const buckets = rawBuckets.map((b, i) => {
+    const pct = total ? Math.round((b.count / total) * 100) : 0;
+    return { ...b, id: b.id ?? `b${i}`, ratio: largest ? b.count / largest : 0, pct, tip: `${b.tipLabel ?? b.label} · ${grouped(b.count)} ${noun} · ${pct}%` };
+  });
+  const catMax = c.categories?.max ?? 5;
+  const rawCats = c.categories ? forPeriod(c.categoryScores ?? [], s.period) : [];
+  const catDigits = decimalsOf(...rawCats.map(x => x.value));
+  const cats = rawCats.map(x => ({ label: x.label, value: x.value, ratio: catMax ? Math.max(0, Math.min(1, x.value / catMax)) : 0, digits: catDigits }));
+  const sent = c.sentiment;
+  const sTotal = sent ? sent.positive + sent.neutral + sent.negative : 0;
+  const sentiment = sent ? { ...sent, total: sTotal, positivePct: sTotal ? (sent.positive / sTotal) * 100 : 0, labels: sent.labels?.length === 3 ? sent.labels : ['Positive', 'Neutral', 'Negative'] } : null;
+  const present: ScorePanels['present'] = [];
+  if (score) present.push('a');
+  if (buckets.length) present.push('b');
+  if (cats.length) present.push('c');
+  if (sentiment) present.push('d');
+  return {
+    score: score ? { ...score, band: bandOf(score.value, score.bands?.length ? score.bands : defaultBands(score.max)), digits: decimalsOf(score.value) } : null,
+    buckets, distribution: c.distribution, categories: c.categories, cats, sentiment, present,
+  };
+}
+
+/** "4.7", "+42" — the score as drawn. */
+export function scoreText(v: number, digits: number, signed?: boolean): string {
+  const t = v.toFixed(digits);
+  return signed && v > 0 ? `+${t}` : t;
+}
+
+/**
+ * **The cascade** — A at 0 (a 600ms count), then B 300ms later, C 600ms after B, D 600ms after C;
+ * a missing panel is skipped. Rows start 60ms apart and fill over 600ms; D's segments fill 300ms
+ * apart, 300ms each, while "% positive" counts over 900ms.
+ */
+export function scoreStarts(present: ScorePanels['present']): Partial<Record<'a' | 'b' | 'c' | 'd', number>> {
+  let t = 0;
+  const s: Partial<Record<'a' | 'b' | 'c' | 'd', number>> = {};
+  if (present.includes('a')) { s.a = t; t += 300; }
+  if (present.includes('b')) { s.b = t; t += 600; }
+  if (present.includes('c')) { s.c = t; t += 600; }
+  if (present.includes('d')) s.d = t;
+  return s;
+}
+
+export function scoreRevealEnd(p: ScorePanels): number {
+  const s = scoreStarts(p.present);
+  let e = 600;
+  if (s.b !== undefined) e = Math.max(e, s.b + (p.buckets.length - 1) * 60 + 600);
+  if (s.c !== undefined) e = Math.max(e, s.c + (p.cats.length - 1) * 60 + 600);
+  if (s.d !== undefined) e = Math.max(e, s.d + 900);
+  return e + 160;
+}
+
+export function scoreScene(s: ScoreState, c: ScoreSettings): ScoreScene {
+  return s.period !== c.period ? 'period' : 'default';
+}

package/src/components/onboarding/score-summary/index.ts

@@ -0,0 +1,9 @@
+export {
+  SCORE_IN_FLIGHT, SCORE_PRESETS, SCORE_SCENES, validateScoreSummary,
+  type ScoreBucket, type ScoreCategory, type ScorePanelA, type ScoreScene, type ScoreSettings,
+} from './contract';
+export {
+  initialScore, scorePanels, scoreRevealEnd, scoreScene, scoreSeed, scoreStarts, scoreText,
+  type ScorePanels, type ScoreSeed, type ScoreState,
+} from './engine';
+export { ScoreSummary, type ScoreSummaryProps } from './ScoreSummaryView';