@appinternalleads/ui 0.2.0

package/src/components/onboarding/expandable-feed/ExpandableFeedView.tsx

@@ -0,0 +1,336 @@
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
+import { Animated, View } from 'react-native';
+import { Box, Icon, Pressable, Text, useTween } from '../../../core';
+import { blockRadii, useDs, type DensityName } from '../../../tokens';
+import { iconFor, resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import { runOutcome, useDefaultOperation, usePatternStatus, useSceneReport } from '../shared/runtime';
+import type { OnboardingOperation } from '../shared/mock';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { OnboardingCard } from '../shared/OnboardingCard';
+import { guarded } from '../shared/guard';
+import { CrossFadeText, ExpandRegion, Hidden, HueTile, PlainChip } from '../shared/parts';
+import { ApricotAlert, ClampText, Initials, SplitWells, Stars, WellStrip } from '../shared/insight-parts';
+import { M15, progress, rowReveal } from '../shared/m15';
+import { RevealRow, useInView, useRevealClock } from '../shared/viz';
+import { useOperationRunner } from '../../../runtime/operations';
+import { FEED_PRESETS, validateFeed, type FeedBlock, type FeedSettings } from './contract';
+import { feedRevealEnd, feedRows, feedScene, feedSeed, initialFeed, nextVote, type FeedRow, type FeedSeed } from './engine';
+
+export type FeedOperations = {
+  /** Save a Helpful vote. Without it (and with no action for `vote`), the demo saves after 600ms — or fails with `result="error"`. */
+  vote: OnboardingOperation<{ id: string; pressed: boolean; count: number }>;
+};
+
+export type ExpandableFeedProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<FeedSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  /** `error`: a Helpful vote fails, reverts after 600ms, and says so for 3.2s. */
+  result?: OnboardingResult;
+  reload?: OnboardingOperation<void>;
+  operations?: Partial<FeedOperations>;
+  initial?: FeedSeed;
+  /** `mobile`: split wells stack. */
+  viewport?: 'web' | 'mobile';
+  /** A row opened (its id) or everything closed (`null`). */
+  onOpenChange?: (id: string | null) => void;
+  /** Helpful pressed or unpressed. */
+  onFeedback?: (id: string, pressed: boolean) => void;
+  replay?: number;
+  forceReduced?: boolean;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+const TEXT_LIMIT = 320;
+const VOTE_MS = 600;
+const VOTE_ALERT_MS = 3200;
+const SWITCH_MS = 900;
+
+/**
+ * **Expandable Feed** — a header count chip and summary (stars, the rating counting up, up to three
+ * muted items); rows that are one `<button aria-expanded aria-controls>` each (leading initials or
+ * tile, title with an optional mint check, meta with stars, a chevron that turns 180°); a detail
+ * region per row of typed blocks (person, text, split, keyvalue, feedback) that opens with the
+ * blocks fading in 60 + j×40ms apart. One row open at a time; ↑/↓ move between rows.
+ */
+function ExpandableFeedView(props: ExpandableFeedProps) {
+  const config = resolveConfig(FEED_PRESETS, props.preset, props.config);
+  const issues = validateFeed(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+function Valid({
+  config, density, status, result, reload, operations, initial, viewport = 'web', onOpenChange, onFeedback, replay, forceReduced, onScene, testID,
+}: Omit<ExpandableFeedProps, 'config'> & { config: FeedSettings }) {
+  const { colors } = useDs();
+  const uid = useId().replace(/:/g, '');
+  const key = JSON.stringify([config, initial ?? null]);
+  const rows = useMemo(() => feedRows(config), [key]);
+  const seed = useMemo(() => initialFeed(config, initial ?? (config.ship ? feedSeed(config, config.ship) : {})), [key]);
+  const [open, setOpen] = useState(seed.open);
+  const [switched, setSwitched] = useState(false);
+  useEffect(() => { setOpen(seed.open); setSwitched(false); }, [seed]);
+
+  const pattern = usePatternStatus(status ?? (seed.loadReady ? 'loading' : rows.length ? 'ready' : 'empty'), reload);
+  useEffect(() => {
+    if (!seed.loadReady || status) return;
+    const t = setTimeout(() => pattern.set('ready'), 1200);
+    return () => clearTimeout(t);
+  }, [seed, status, replay]);
+  /* Support tickets: ticket 1 is open, then the feed switches to ticket 3 — the first closes as the third opens. */
+  useEffect(() => {
+    if (!seed.switchTo || pattern.status !== 'ready') return;
+    const t = setTimeout(() => { setOpen(seed.switchTo); setSwitched(true); }, SWITCH_MS);
+    return () => clearTimeout(t);
+  }, [seed, pattern.status]);
+  useSceneReport(pattern.status === 'ready' ? (seed.loadReady ? 'loadReady' : switched ? 'switched' : feedScene({ ...seed, open })) : pattern.status, onScene);
+
+  const [ref, inView] = useInView();
+  const clock = useRevealClock(inView && pattern.status === 'ready', feedRevealEnd(rows.length), `${replay ?? 0}|${pattern.status}`, forceReduced);
+  const rating = config.summary?.rating;
+  const shownRating = typeof rating === 'number' ? (clock.done ? rating : rating * progress(clock.t, 0, M15.fillMs)) : null;
+
+  /* Helpful: the vote shows at once; a failed save puts it back and says so. */
+  const [votes, setVotes] = useState<Record<string, { pressed: boolean; count: number }>>({});
+  const [voteFailed, setVoteFailed] = useState<string | null>(null);
+  useEffect(() => { setVotes({}); setVoteFailed(null); }, [seed]);
+  const runner = useOperationRunner();
+  const vote = useDefaultOperation(operations?.vote, VOTE_MS, () => result === 'error');
+  const alertTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => () => { if (alertTimer.current) clearTimeout(alertTimer.current); }, []);
+  const press = (row: FeedRow, b: Extract<FeedBlock, { kind: 'feedback' }>) => {
+    const cur = votes[row.id] ?? { pressed: Boolean(b.pressed), count: b.count };
+    const next = nextVote(cur);
+    setVotes(v => ({ ...v, [row.id]: next }));
+    setVoteFailed(null);
+    onFeedback?.(row.id, next.pressed);
+    runOutcome(runner, `vote:${row.id}`, vote, { id: row.id, ...next }, {
+      ok: () => {},
+      fail: () => {
+        setVotes(v => ({ ...v, [row.id]: cur }));
+        setVoteFailed(row.id);
+        if (alertTimer.current) clearTimeout(alertTimer.current);
+        alertTimer.current = setTimeout(() => setVoteFailed(null), VOTE_ALERT_MS);
+      },
+    });
+  };
+
+  const toggle = (id: string) => {
+    const next = open === id ? null : id;
+    setOpen(next);
+    onOpenChange?.(next);
+  };
+  const buttons = useRef<Record<string, { focus?: () => void } | null>>({});
+  const move = (i: number, dir: 1 | -1) => {
+    const target = rows[i + dir];
+    if (target) buttons.current[target.id]?.focus?.();
+  };
+
+  const summary = config.summary;
+  const meta = (config.count || summary) ? (
+    <Box row align="center" gap="s2" style={{ flexWrap: 'wrap', justifyContent: 'flex-end' }}>
+      {typeof shownRating === 'number' ? (
+        <Box row align="center" gap="s1">
+          <Stars value={rating as number} size={13} />
+          <Text numeric style={{ fontSize: 13, fontWeight: '600', color: colors.textPrimary }}>{shownRating.toFixed(1)}</Text>
+        </Box>
+      ) : null}
+      {(summary?.items ?? []).slice(0, 3).map(s => <Text key={s} numeric style={{ fontSize: 12, color: colors.textSecondary }}>{s}</Text>)}
+      {config.count ? <PlainChip>{String(config.count)}</PlainChip> : null}
+    </Box>
+  ) : undefined;
+
+  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: 12 }}>
+        <View role={'list' as never} aria-label={config.title}>
+          {rows.map((row, i) => {
+            const rv = clock.reduced ? { opacity: 1, y: 0 } : rowReveal(i, clock.t);
+            return (
+              <RevealRow key={row.id} opacity={rv.opacity} y={rv.y}>
+                <FeedRowView
+                  row={row}
+                  uid={uid}
+                  open={open === row.id}
+                  last={i === rows.length - 1}
+                  mobile={viewport === 'mobile'}
+                  verifiedLabel={config.verifiedLabel}
+                  onToggle={() => toggle(row.id)}
+                  onKey={dir => move(i, dir)}
+                  setRef={el => { buttons.current[row.id] = el as never; }}
+                  votes={votes[row.id]}
+                  voteFailed={voteFailed === row.id}
+                  onVote={b => press(row, b)}
+                  reduced={clock.reduced}
+                />
+              </RevealRow>
+            );
+          })}
+        </View>
+        {config.footer?.length ? <WellStrip left={config.footer[0]} right={config.footer[1]} /> : null}
+      </View>
+    </OnboardingCard>
+  );
+}
+
+function FeedRowView({
+  row, uid, open, last, mobile, verifiedLabel, onToggle, onKey, setRef, votes, voteFailed, onVote, reduced,
+}: {
+  row: FeedRow; uid: string; open: boolean; last: boolean; mobile: boolean; verifiedLabel?: string;
+  onToggle: () => void; onKey: (dir: 1 | -1) => void; setRef: (el: unknown) => void;
+  votes?: { pressed: boolean; count: number }; voteFailed: boolean; onVote: (b: Extract<FeedBlock, { kind: 'feedback' }>) => void; reduced: boolean;
+}) {
+  const { colors, density } = useDs();
+  const [hover, setHover] = useState(false);
+  const turn = useTween(open ? 1 : 0);
+  const btnId = `${uid}-b-${row.id}`;
+  const regionId = `${uid}-d-${row.id}`;
+  const leading = row.initials ? <Initials text={row.initials} /> : row.icon ? <HueTile icon={iconFor(row.icon)} type={row.iconType} /> : null;
+  return (
+    <View role={'listitem' as never} style={{ borderBottomWidth: last ? 0 : 1, borderBottomColor: colors.hairline }}>
+      <Pressable
+        ref={setRef as never}
+        nativeID={btnId}
+        onPress={onToggle}
+        aria-expanded={open}
+        aria-controls={regionId}
+        onHoverIn={() => setHover(true)}
+        onHoverOut={() => setHover(false)}
+        onKeyDown={e => {
+          if (e.key === 'ArrowDown') { e.preventDefault(); onKey(1); }
+          if (e.key === 'ArrowUp') { e.preventDefault(); onKey(-1); }
+        }}
+        row
+        align="center"
+        gap="s3"
+       
+        minHeight={density.rowH}
+        style={{ padding: 8, marginVertical: 2, borderRadius: blockRadii.inset, backgroundColor: hover ? colors.surfaceSunken : 'transparent' }}>
+        {leading}
+        <View style={{ flex: 1, minWidth: 0, gap: 2 }}>
+          <View style={{ flexDirection: 'row', alignItems: 'center', gap: 6 }}>
+            <Text numberOfLines={1} style={{ flexShrink: 1, fontSize: 14, fontWeight: '600', letterSpacing: -0.2, color: colors.textPrimary }}>{row.title}</Text>
+            {row.verified ? (
+              <>
+                <View aria-hidden><Icon name="check" size={15} color={colors.status.executed} /></View>
+                <Hidden>{verifiedLabel || 'Verified'}</Hidden>
+              </>
+            ) : null}
+          </View>
+          {typeof row.rating === 'number' || row.meta.length ? (
+            <View style={{ flexDirection: 'row', alignItems: 'center', gap: 6, flexWrap: 'wrap' }}>
+              {typeof row.rating === 'number' ? <Stars value={row.rating} size={12} /> : null}
+              {row.meta.length ? (
+                <Text numeric numberOfLines={1} style={{ flexShrink: 1, fontSize: 12, color: colors.textSecondary }}>
+                  {`${typeof row.rating === 'number' ? '· ' : ''}${row.meta.join(' · ')}`}
+                </Text>
+              ) : null}
+            </View>
+          ) : null}
+        </View>
+        <Animated.View aria-hidden style={{ transform: [{ rotate: turn.interpolate({ inputRange: [0, 1], outputRange: ['0deg', '180deg'] }) }] }}>
+          <Icon name="chev-d" size={16} color={colors.textSecondary} />
+        </Animated.View>
+      </Pressable>
+      <ExpandRegion open={open} nativeID={regionId} role="region" labelledBy={btnId}>
+        <View style={{ paddingLeft: leading ? 44 : 8, paddingRight: 8, paddingTop: 4, paddingBottom: 16, gap: 12 }}>
+          {row.detail.map((b, j) => (
+            <BlockIn key={j} open={open} j={j} reduced={reduced}>
+              <Block block={b} id={`${regionId}-${j}`} mobile={mobile} votes={votes} voteFailed={voteFailed} onVote={onVote} />
+            </BlockIn>
+          ))}
+        </View>
+      </ExpandRegion>
+    </View>
+  );
+}
+
+/** A block fades in 160ms, 60 + j×40ms after its row opens; out over 160ms as it closes. */
+function BlockIn({ open, j, reduced, children }: { open: boolean; j: number; reduced: boolean; children: React.ReactNode }) {
+  const v = useRef(new Animated.Value(open ? 1 : 0)).current;
+  useEffect(() => {
+    if (reduced) { v.setValue(open ? 1 : 0); return; }
+    const a = Animated.timing(v, { toValue: open ? 1 : 0, duration: 160, delay: open ? 60 + j * 40 : 0, useNativeDriver: false });
+    a.start();
+    return () => a.stop();
+  }, [open, reduced]);
+  return <Animated.View style={{ opacity: v }}>{children}</Animated.View>;
+}
+
+function Block({ block, id, mobile, votes, voteFailed, onVote }: {
+  block: FeedBlock; id: string; mobile: boolean;
+  votes?: { pressed: boolean; count: number }; voteFailed: boolean; onVote: (b: Extract<FeedBlock, { kind: 'feedback' }>) => void;
+}) {
+  const { colors } = useDs();
+  switch (block.kind) {
+    case 'person':
+      return (
+        <View style={{ flexDirection: 'row', alignItems: 'center', gap: 6, flexWrap: 'wrap' }}>
+          <Text style={{ fontSize: 13, fontWeight: '600', color: colors.textPrimary }}>{block.name}</Text>
+          {block.role ? <Text style={{ fontSize: 12, color: colors.textSecondary }}>{block.role}</Text> : null}
+          {block.count ? <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{`· ${block.count}`}</Text> : null}
+          {block.chip ? <PlainChip height={22}>{block.chip}</PlainChip> : null}
+        </View>
+      );
+    case 'text':
+      return <ClampText body={block.body} limit={TEXT_LIMIT} lines={6} nativeID={`${id}-t`} style={{ lineHeight: 21 }} />;
+    case 'split':
+      return <SplitWells positiveTitle={block.positiveTitle} positive={block.positive} negativeTitle={block.negativeTitle} negative={block.negative} stacked={mobile} />;
+    case 'keyvalue':
+      return (
+        <View>
+          {block.rows.map((r, k) => (
+            <View key={k} style={{ flexDirection: 'row', gap: 12, paddingVertical: 6, borderBottomWidth: 1, borderBottomColor: colors.hairline }}>
+              <Text style={{ width: 120, fontSize: 12, color: colors.textSecondary }}>{r.label}</Text>
+              <Text numeric style={{ flex: 1, fontSize: 13, color: colors.textPrimary }}>{String(r.value ?? '')}</Text>
+            </View>
+          ))}
+        </View>
+      );
+    case 'feedback': {
+      const v = votes ?? { pressed: Boolean(block.pressed), count: block.count };
+      return (
+        <View style={{ gap: 8 }}>
+          <View style={{ flexDirection: 'row', alignItems: 'center', gap: 10 }}>
+            <Pressable
+              onPress={() => onVote(block)}
+              aria-pressed={v.pressed}
+              aria-label={`${block.label || 'Helpful'} (${v.count})`}
+              row
+              align="center"
+              gap="s1"
+             
+              press="scale"
+              minHeight={32}
+              style={{ paddingHorizontal: 10, borderRadius: blockRadii.inset, borderWidth: 1, borderColor: colors.hairlineStrong, backgroundColor: v.pressed ? colors.surfaceSunken : colors.surface1 }}>
+              <ThumbPop on={v.pressed} />
+              <Text style={{ fontSize: 13, fontWeight: '600', color: colors.textPrimary }}>{block.label || 'Helpful'}</Text>
+              <CrossFadeText value={`(${v.count})`} style={{ fontSize: 13, color: colors.textSecondary }} />
+            </Pressable>
+            {block.time ? <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{block.time}</Text> : null}
+          </View>
+          {voteFailed ? <ApricotAlert title="Couldn’t save your vote" body="The count has been put back. Try again in a moment." /> : null}
+        </View>
+      );
+    }
+    default:
+      return null;
+  }
+}
+
+/** M7: the thumb fills and pops (scale .6 → 1) when pressed. */
+function ThumbPop({ on }: { on: boolean }) {
+  const { colors } = useDs();
+  const s = useTween(on ? 1 : 0);
+  return (
+    <Animated.View aria-hidden style={{ transform: [{ scale: on ? s.interpolate({ inputRange: [0, 1], outputRange: [0.6, 1] }) : 1 }] }}>
+      <Icon name="thumbs-up" size={15} filled={on} color={on ? colors.textPrimary : colors.textSecondary} />
+    </Animated.View>
+  );
+}
+
+/** ExpandableFeed, guarded: a wrong-kind config is refused by name and a render error is caught (`shared/guard`). */
+export const ExpandableFeed = guarded(ExpandableFeedView, FEED_PRESETS, 'ExpandableFeed');

package/src/components/onboarding/expandable-feed/contract.ts

@@ -0,0 +1,104 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/**
+ * **Expandable Feed (batch 6 §4.1)** — rows that open to typed detail blocks, one row open at a
+ * time. Read-only but for Helpful: a vote is the one piece of work, run through `operations.vote`.
+ * The only entrance animation is M15 (rows drop in, the summary rating counts).
+ */
+
+/** Detail blocks, rendered in order. JSON-typed by design: a row's detail is a small document. */
+export type FeedBlock =
+  | { kind: 'person'; name: string; role?: string; count?: string; chip?: string }
+  | { kind: 'text'; body: string }
+  | { kind: 'split'; positiveTitle: string; positive: string[]; negativeTitle: string; negative: string[] }
+  | { kind: 'keyvalue'; rows: { label: string; value: string }[] }
+  | { kind: 'feedback'; label?: string; count: number; time?: string; pressed?: boolean };
+export const FEED_BLOCK_KINDS = ['person', 'text', 'split', 'keyvalue', 'feedback'] as const;
+
+/**
+ * One row. The leading slot is `initials` (a 32px circle) or `icon` (+ `iconType`, a 32px tile) or
+ * nothing. `rating` shows as stars first in the meta line; `meta` is the rest, joined by "·".
+ */
+export type FeedItem = {
+  id?: string;
+  title: string;
+  verified?: boolean;
+  initials?: string;
+  icon?: string;
+  iconType?: HeaderConfig['type'];
+  rating?: number;
+  meta?: string[];
+  detail?: FeedBlock[];
+};
+
+export const FEED_SCENES = ['default', 'collapsed', 'oneOpen', 'switch', 'showMore', 'loadReady', 'loading', 'empty', 'error'] as const;
+export type FeedScene = (typeof FEED_SCENES)[number];
+/** Nothing holds still: a vote settles on its own. */
+export const FEED_IN_FLIGHT: readonly string[] = [];
+
+export type FeedSettings = HeaderConfig & LoadCopy & {
+  /** The plain chip beside the title — "5 reviews". `null`: none. */
+  count: string | null;
+  /** The hidden words for the mint check — "Verified purchase". */
+  verifiedLabel?: string;
+  /** The header's right side: stars and the rating (counts up), then up to three muted items. */
+  summary: { rating?: number | null; items?: string[] } | null;
+  /** The footer well strip: one line left, one right. */
+  footer: string[];
+  /** The row open on arrival. */
+  defaultOpenId: string | null;
+  items: FeedItem[];
+  /** Demo-only: the row whose long text shows Show more. */
+  moreId: string | null;
+  /** Demo-only: the scene this case ships in. */
+  ship: FeedScene | null;
+};
+
+export const FEED_PRESETS = presetsJson as unknown as PresetsFile<FeedSettings>;
+
+const str = (v: unknown) => typeof v === 'string';
+const strList = (v: unknown) => Array.isArray(v) && v.every(str);
+
+function blockIssues(b: unknown, path: string): OnboardingIssue[] {
+  if (!b || typeof b !== 'object') return [{ path, message: 'Each detail block is an object with a kind.' }];
+  const x = b as Record<string, unknown>;
+  switch (x.kind) {
+    case 'person': return str(x.name) ? [] : [{ path: `${path}.name`, message: 'A person block needs a name.' }];
+    case 'text': return str(x.body) ? [] : [{ path: `${path}.body`, message: 'A text block needs a body.' }];
+    case 'split': return strList(x.positive) && strList(x.negative) ? [] : [{ path, message: 'A split block has positive and negative lists of text.' }];
+    case 'keyvalue': return Array.isArray(x.rows) && x.rows.every(r => r && str((r as { label?: unknown }).label)) ? [] : [{ path: `${path}.rows`, message: 'A keyvalue block has rows of { label, value }.' }];
+    case 'feedback': return typeof x.count === 'number' && Number.isFinite(x.count) ? [] : [{ path: `${path}.count`, message: 'A feedback block has a count (a number).' }];
+    default: return [{ path: `${path}.kind`, message: `kind is one of ${FEED_BLOCK_KINDS.join(', ')}.` }];
+  }
+}
+
+export function validateFeed(c: FeedSettings): OnboardingIssue[] {
+  if (!c || typeof c !== 'object') return [{ path: 'config', message: 'must be an object.' }];
+  if (!Array.isArray(c.items)) return [{ path: 'items', message: 'items must be a list.' }];
+  const out: OnboardingIssue[] = [];
+  const ids = new Set<string>();
+  c.items.forEach((it: FeedItem | null, i) => {
+    const p = `items[${i}]`;
+    if (!it || typeof it !== 'object') { out.push({ path: p, message: 'Each item is { title, … }.' }); return; }
+    if (!str(it.title) || !it.title.trim()) out.push({ path: `${p}.title`, message: 'Every item needs a title.' });
+    if (it.id !== undefined) {
+      if (!str(it.id)) out.push({ path: `${p}.id`, message: 'id is text.' });
+      else if (ids.has(it.id)) out.push({ path: `${p}.id`, message: `“${it.id}” is used twice.` });
+      else ids.add(it.id);
+    }
+    if (it.rating !== undefined && it.rating !== null && !(typeof it.rating === 'number' && it.rating >= 0 && it.rating <= 5)) out.push({ path: `${p}.rating`, message: 'rating is a number from 0 to 5.' });
+    if (it.meta !== undefined && !strList(it.meta)) out.push({ path: `${p}.meta`, message: 'meta is a list of text.' });
+    if (it.detail !== undefined) {
+      if (!Array.isArray(it.detail)) out.push({ path: `${p}.detail`, message: 'detail is a list of blocks.' });
+      else it.detail.forEach((b, j) => out.push(...blockIssues(b, `${p}.detail[${j}]`)));
+    }
+  });
+  if (c.footer !== undefined && c.footer !== null && !strList(c.footer)) out.push({ path: 'footer', message: 'footer is a list of text (left, right).' });
+  if (c.summary && typeof c.summary === 'object') {
+    const r = c.summary.rating;
+    if (r !== undefined && r !== null && !(typeof r === 'number' && Number.isFinite(r))) out.push({ path: 'summary.rating', message: 'summary.rating is a number.' });
+    if (c.summary.items !== undefined && !strList(c.summary.items)) out.push({ path: 'summary.items', message: 'summary.items is a list of text.' });
+  }
+  return out;
+}

package/src/components/onboarding/expandable-feed/engine.ts

@@ -0,0 +1,43 @@
+import { M15 } from '../shared/m15';
+import type { FeedBlock, FeedItem, FeedScene, FeedSettings } from './contract';
+
+/** **The Expandable Feed engine** — pure: rows, which one is open, and the scenes. */
+
+export type FeedRow = FeedItem & { id: string; detail: FeedBlock[]; meta: string[] };
+
+export function feedRows(c: FeedSettings): FeedRow[] {
+  return c.items.map((it, i) => ({ ...it, id: it.id ?? `i${i}`, meta: it.meta ?? [], detail: it.detail ?? [] }));
+}
+
+/** `switchTo`: the row the demo opens next (Support tickets: 1 → 3), 900ms after arriving. */
+export type FeedState = { open: string | null; switchTo: string | null; loadReady: boolean };
+export type FeedSeed = Partial<FeedState>;
+
+export function initialFeed(c: FeedSettings, seed: FeedSeed = {}): FeedState {
+  const ids = feedRows(c).map(r => r.id);
+  const open = seed.open !== undefined ? seed.open : c.defaultOpenId;
+  return { open: open && ids.includes(open) ? open : null, switchTo: seed.switchTo ?? null, loadReady: seed.loadReady ?? false };
+}
+
+export function feedSeed(c: FeedSettings, scene: FeedScene): FeedSeed {
+  const ids = feedRows(c).map(r => r.id);
+  if (scene === 'collapsed') return { open: null };
+  if (scene === 'oneOpen') return { open: ids[0] ?? null };
+  if (scene === 'switch') return { open: ids[0] ?? null, switchTo: ids[2] ?? ids[1] ?? null };
+  if (scene === 'showMore') return { open: c.moreId ?? ids[0] ?? null };
+  if (scene === 'loadReady') return { loadReady: true };
+  return {};
+}
+
+/** The scene the view is in — for `onScene`. */
+export function feedScene(s: FeedState): FeedScene | 'switched' {
+  return s.open ? 'oneOpen' : 'collapsed';
+}
+
+/** The reveal: rows (60ms apart, capped at 8) and the rating's 600ms count. */
+export const feedRevealEnd = (n: number) => Math.max(M15.fillMs, Math.min(Math.max(n - 1, 0), M15.cap) * M15.stepMs + M15.rowMs);
+
+/** The vote a Helpful press makes, from where it is now. */
+export function nextVote(cur: { pressed: boolean; count: number }) {
+  return { pressed: !cur.pressed, count: cur.count + (cur.pressed ? -1 : 1) };
+}

package/src/components/onboarding/expandable-feed/index.ts

@@ -0,0 +1,6 @@
+export {
+  FEED_BLOCK_KINDS, FEED_IN_FLIGHT, FEED_PRESETS, FEED_SCENES, validateFeed,
+  type FeedBlock, type FeedItem, type FeedScene, type FeedSettings,
+} from './contract';
+export { feedRevealEnd, feedRows, feedScene, feedSeed, initialFeed, nextVote, type FeedRow, type FeedSeed, type FeedState } from './engine';
+export { ExpandableFeed, type ExpandableFeedProps, type FeedOperations } from './ExpandableFeedView';