@appinternalleads/ui 0.2.0

package/src/components/onboarding/tag-cloud/TagCloudView.tsx

@@ -0,0 +1,287 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { View } from 'react-native';
+import { Box, Icon, Pressable, Text } from '../../../core';
+import { Button } from '../../../ds';
+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 { ExpandRegion } from '../shared/parts';
+import { ApricotAlert, InlineAction, WellStrip } from '../shared/insight-parts';
+import { M15, progress } from '../shared/m15';
+import { useInView, useRevealClock } from '../shared/viz';
+import { useOperationRunner } from '../../../runtime/operations';
+import type { OnboardingOutcome } from '../shared/mock';
+import { TAG_CLOUD_PRESETS, TAG_SENTIMENTS, validateTagCloud, type TagCloudSettings, type TagMention, type TagSentiment } from './contract';
+import {
+  GROW_END, GROW_MS, TIER_SIZE, changedTiers, filteredIds, growStart, initialTagCloud, mentionsFor, mentionsHeading, sentimentCounts, tagCloudScene, tagCloudSeed, tagRows, wordName,
+  type TagCloudRow, type TagCloudSeed,
+} from './engine';
+
+export type TagCloudOperations = {
+  /** The items the picked words were extracted from — answer `{ ok: true, items: [{ word, text, source }] }`. Without it, `mentions` from the config. */
+  loadMentions: (req: { ids: string[] }, ctx: { signal: AbortSignal }) => Promise<OnboardingOutcome & { items?: TagMention[] }>;
+};
+
+export type TagCloudProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<TagCloudSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  /** Read-only; accepted for the shared shape. */
+  result?: OnboardingResult;
+  reload?: OnboardingOperation<void>;
+  initial?: TagCloudSeed;
+  operations?: Partial<TagCloudOperations>;
+  /** The words the filter picks, whenever it changes (empty: no filter). */
+  onFilter?: (ids: string[]) => void;
+  replay?: number;
+  forceReduced?: boolean;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/** Changed words fade out over 160ms, then grow back at their new size. */
+const FADE_MS = 160;
+
+/**
+ * **Weighted Tag Cloud** — a header legend of sentiment toggles (a dot and "10 positive"); the words
+ * in centred lines, sized 12 / 14 / 16 / 20 / 24 by quantile tier and shuffled by id; a filter bar
+ * (Filtering: chips, Clear) that eases open; "+N more"; the footer strip. A word is a toggle
+ * (`aria-pressed`) named "build quality, 142 mentions, positive"; arrow keys move between words.
+ */
+function TagCloudView(props: TagCloudProps) {
+  const config = resolveConfig(TAG_CLOUD_PRESETS, props.preset, props.config);
+  const issues = validateTagCloud(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, operations, onFilter, replay, forceReduced, onScene, testID,
+}: Omit<TagCloudProps, 'config'> & { config: TagCloudSettings }) {
+  const { colors } = useDs();
+  const key = JSON.stringify([config, initial ?? null]);
+  const seed = useMemo(() => initialTagCloud(config, initial ?? (config.ship ? tagCloudSeed(config, config.ship) : {})), [key]);
+  const [sel, setSel] = useState(seed.sel);
+  const [sent, setSent] = useState<TagSentiment[]>(seed.sent);
+  const [all, setAll] = useState(false);
+  const [alt, setAlt] = useState(false);
+  /* Data change: which words fade, then grow; and the "+N more" words growing in. */
+  const [shift, setShift] = useState<{ phase: 'out' | 'in'; ids: string[]; n: number } | null>(null);
+  const [more, setMore] = useState<string[]>([]);
+  useEffect(() => { setSel(seed.sel); setSent(seed.sent); setAll(false); setAlt(false); setShift(null); setMore([]); }, [seed]);
+
+  const { rows, hidden } = tagRows(config, alt, all);
+  const pattern = usePatternStatus(status ?? (seed.loadReady ? 'loading' : config.words.length ? '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', GROW_END, `${replay ?? 0}|${pattern.status}`, forceReduced);
+  const moreClock = useRevealClock(more.length > 0, GROW_END, `more|${more.join(',')}`, forceReduced);
+  const shiftClock = useRevealClock(shift !== null, shift?.phase === 'out' ? FADE_MS : GROW_MS, `shift|${shift?.n ?? 0}|${shift?.phase ?? ''}`, forceReduced);
+
+  const dataChange = () => {
+    if (!config.altWeights) return;
+    const ids = changedTiers(config, alt);
+    if (clock.reduced) { setAlt(a => !a); return; }
+    const n = (shift?.n ?? 0) + 1;
+    setShift({ phase: 'out', ids, n });
+    setTimeout(() => { setAlt(a => !a); setShift({ phase: 'in', ids, n }); }, FADE_MS + 10);
+    setTimeout(() => setShift(s => (s && s.n === n ? null : s)), FADE_MS + GROW_MS + 60);
+  };
+  /* The Data change scene shifts once, after the grow. */
+  useEffect(() => {
+    if (!seed.shift || !clock.done) return;
+    const t = setTimeout(dataChange, 300);
+    return () => clearTimeout(t);
+  }, [seed, clock.done]);
+
+  const active = filteredIds(rows, sel, sent);
+  const filtering = sel.length > 0 || sent.length > 0;
+  const firstFilter = useRef(true);
+  useEffect(() => {
+    if (firstFilter.current) { firstFilter.current = false; return; }
+    onFilter?.(active);
+  }, [sel.join(','), sent.join(',')]);
+  useSceneReport(pattern.status === 'ready' ? (seed.loadReady ? 'loadReady' : shift ? 'shift' : tagCloudScene({ sel, sent })) : pattern.status, onScene);
+
+  /* The extracted items for the picked words: the words picked by hand first, then those of a picked sentiment by weight. */
+  const pickedIds = [...sel, ...[...rows].sort((a, b) => b.weight - a.weight).filter(r => !sel.includes(r.id) && r.sentiment !== null && sent.includes(r.sentiment)).map(r => r.id)];
+  const pickedKey = pickedIds.join(',');
+  const [items, setItems] = useState<{ phase: 'ready' | 'loading' | 'failed'; list: (TagMention & { label: string })[] }>({ phase: 'ready', list: [] });
+  const [showAll, setShowAll] = useState(false);
+  const runner = useOperationRunner();
+  const loadItems = () => {
+    setShowAll(false);
+    if (!pickedIds.length) { setItems({ phase: 'ready', list: [] }); return; }
+    const host = operations?.loadMentions;
+    if (!host) { setItems({ phase: 'ready', list: mentionsFor(config, pickedIds) }); return; }
+    setItems(x => ({ ...x, phase: 'loading' }));
+    const labels = new Map(config.words.map(w => [w.id ?? w.label, w.label]));
+    runner.run('loadMentions', ctx => host({ ids: pickedIds }, { signal: ctx.signal }), {
+      onOk: (r: OnboardingOutcome & { items?: TagMention[] }) => setItems(r.ok
+        ? { phase: 'ready', list: (r.items ?? []).map(m => ({ ...m, label: labels.get(m.word) ?? m.word })) }
+        : { phase: 'failed', list: [] }),
+      onError: () => setItems({ phase: 'failed', list: [] }),
+    });
+  };
+  useEffect(loadItems, [pickedKey, key]);
+  const ITEMS_SHOWN = 5;
+  const pickedLabels = pickedIds.map(id => rows.find(r => r.id === id)?.label ?? id);
+
+  const toggleWord = (id: string) => setSel(s => (s.includes(id) ? s.filter(x => x !== id) : [...s, id]));
+  const toggleSent = (x: TagSentiment) => setSent(s => (s.includes(x) ? s.filter(y => y !== x) : [...s, x]));
+  const counts = sentimentCounts(rows);
+  const hasSentiment = rows.some(r => r.sentiment);
+  const dotColor = (s: TagSentiment) => (s === 'positive' ? colors.status.executed : s === 'negative' ? colors.status.needsUser : colors.textSecondary);
+  const label = (s: TagSentiment) => config.sentLabels?.[s] ?? s;
+  const countIn = (v: number) => (clock.done ? v : Math.round(v * progress(clock.t, 0, M15.fillMs)));
+
+  const growOf = (r: TagCloudRow) => {
+    if (shift && shift.ids.includes(r.id)) {
+      return shift.phase === 'out' ? { g: 1, o: 1 - progress(shiftClock.t, 0, FADE_MS) } : { g: progress(shiftClock.t, 0, GROW_MS), o: progress(shiftClock.t, 0, GROW_MS) };
+    }
+    if (more.includes(r.id)) { const g = moreClock.done ? 1 : progress(moreClock.t, growStart(rows.filter(x => more.includes(x.id)), r.id), GROW_MS); return { g, o: g }; }
+    const g = clock.done ? 1 : progress(clock.t, growStart(rows, r.id), GROW_MS);
+    return { g, o: g };
+  };
+
+  const buttons = useRef<Record<string, { focus?: () => void } | null>>({});
+  const move = (i: number, dir: number) => { const r = rows[i + dir]; if (r) buttons.current[r.id]?.focus?.(); };
+
+  const meta = hasSentiment ? (
+    <Box row align="center" gap="s1" style={{ flexWrap: 'wrap', justifyContent: 'flex-end' }}>
+      {TAG_SENTIMENTS.filter(s => counts[s] > 0).map(s => (
+        <Pressable
+          key={s}
+          onPress={() => toggleSent(s)}
+          aria-pressed={sent.includes(s)}
+          aria-label={`${counts[s]} ${label(s)}`}
+          row
+          align="center"
+          gap="s1"
+          minHeight={28}
+          style={{ paddingHorizontal: 8, borderRadius: blockRadii.inset, backgroundColor: sent.includes(s) ? colors.surfaceSunken : 'transparent', borderWidth: sent.includes(s) ? 1.5 : 0, borderColor: colors.textPrimary }}>
+          <Box width={6} height={6} radius="pill" aria-hidden style={{ backgroundColor: dotColor(s) }} />
+          <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{`${countIn(counts[s])} ${label(s)}`}</Text>
+        </Pressable>
+      ))}
+    </Box>
+  ) : undefined;
+
+  const chips = [
+    ...sent.map(s => ({ key: `s:${s}`, text: label(s), remove: () => toggleSent(s) })),
+    ...sel.map(id => ({ key: `w:${id}`, text: rows.find(r => r.id === id)?.label ?? config.words.find(w => (w.id ?? w.label) === id)?.label ?? id, remove: () => toggleWord(id) })),
+  ];
+
+  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 }}>
+        <ExpandRegion open={filtering} role="region" label="Filter">
+          <Box row align="center" gap="s2" style={{ flexWrap: 'wrap', paddingBottom: 4 }}>
+            <Text style={{ fontSize: 12, color: colors.textSecondary }}>Filtering:</Text>
+            {chips.map(c => (
+              <Pressable key={c.key} onPress={c.remove} aria-label={`Remove ${c.text}`} row align="center" gap="s1" minHeight={26} style={{ paddingLeft: 10, paddingRight: 6, borderRadius: 999, backgroundColor: colors.band }}>
+                <Text style={{ fontSize: 12, fontWeight: '600', color: colors.textPrimary }}>{c.text}</Text>
+                <Icon name="close" size={12} color={colors.textSecondary} />
+              </Pressable>
+            ))}
+            <InlineAction label="Clear" onPress={() => { setSel([]); setSent([]); }} accessibilityLabel="Clear filter" />
+          </Box>
+        </ExpandRegion>
+
+        <View role={'list' as never} aria-label={config.title} style={{ flexDirection: 'row', flexWrap: 'wrap', justifyContent: 'center', alignItems: 'center', columnGap: 16, rowGap: 8 } as object}>
+          {rows.map((r, i) => {
+            const on = sel.includes(r.id);
+            const picked = active.includes(r.id);
+            const { g, o } = growOf(r);
+            const dim = filtering && !picked ? 0.5 : 1;
+            return (
+              <View key={r.id} role={'listitem' as never} style={{ opacity: o * dim, transform: [{ scale: 0.4 + 0.6 * g }] }}>
+                <Pressable
+                  ref={((el: unknown) => { buttons.current[r.id] = el as never; }) as never}
+                  onPress={() => toggleWord(r.id)}
+                  aria-pressed={on}
+                  aria-label={wordName(r, config.measure, config.sentLabels)}
+                  onKeyDown={e => {
+                    const d = ({ ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 } as Record<string, number>)[e.key];
+                    if (d) { e.preventDefault(); move(i, d); }
+                  }}
+                  row
+                  align="center"
+                  gap="s1"
+                  minHeight={32}
+                  style={{ paddingHorizontal: 8, borderRadius: blockRadii.inset, backgroundColor: on ? colors.surfaceSunken : 'transparent', boxShadow: on ? `inset 0 0 0 1.5px ${colors.textPrimary}` : 'none' } as object}>
+                  {r.sentiment ? <Box width={6} height={6} radius="pill" aria-hidden style={{ backgroundColor: dotColor(r.sentiment) }} /> : null}
+                  <Text style={{ fontSize: TIER_SIZE[r.tier - 1], fontWeight: r.tier === 5 ? '600' : '400', color: r.tier <= 2 ? colors.textSecondary : colors.textPrimary }}>{r.label}</Text>
+                </Pressable>
+              </View>
+            );
+          })}
+        </View>
+
+        {hidden > 0 || config.altWeights ? (
+          <Box row justify="center" gap="s2">
+            {hidden > 0 ? (
+              <Button variant="secondary" size="small" onPress={() => { const before = new Set(rows.map(r => r.id)); setAll(true); setMore(tagRows(config, alt, true).rows.filter(r => !before.has(r.id)).map(r => r.id)); }}>
+                {`+${hidden} more`}
+              </Button>
+            ) : null}
+            {config.altWeights ? <Button variant="secondary" size="small" onPress={dataChange}>Data change</Button> : null}
+          </Box>
+        ) : null}
+
+        <ExpandRegion open={filtering} role="region" label="Extracted items">
+          <View style={{ gap: 8, paddingTop: 4 }}>
+            <Text numeric style={{ fontSize: 12, fontWeight: '600', color: colors.textSecondary }}>
+              {items.phase === 'ready' ? mentionsHeading(items.list.length, pickedLabels) : `Items for ${pickedLabels.length === 1 ? pickedLabels[0] : `${pickedLabels.length} keywords`}`}
+            </Text>
+            {items.phase === 'loading' ? (
+              <View aria-busy style={{ gap: 8 }}>
+                {[80, 64, 72].map(w => <View key={w} style={{ height: 10, width: `${w}%`, borderRadius: 999, backgroundColor: colors.band }} />)}
+              </View>
+            ) : items.phase === 'failed' ? (
+              <ApricotAlert title="Couldn’t load the items" action={<Button variant="secondary" size="xsmall" onPress={loadItems}>Retry</Button>} />
+            ) : items.list.length === 0 ? (
+              <Text style={{ fontSize: 13, color: colors.textSecondary }}>{`No extracted items for ${pickedLabels.length === 1 ? 'this keyword' : 'these keywords'} yet.`}</Text>
+            ) : (
+              <>
+                <View role={'list' as never} aria-label="Extracted items" style={{ borderRadius: blockRadii.mid, backgroundColor: colors.surfaceSunken, paddingHorizontal: 14 }}>
+                  {(showAll ? items.list : items.list.slice(0, ITEMS_SHOWN)).map((m, i, all) => (
+                    <View key={`${m.word}${i}`} role={'listitem' as never} style={{ paddingVertical: 10, gap: 2, borderBottomWidth: i === all.length - 1 ? 0 : 1, borderBottomColor: colors.hairline }}>
+                      <Text style={{ fontSize: 13, lineHeight: 19, color: colors.textPrimary }}>{m.text}</Text>
+                      <Text numeric style={{ fontSize: 12, color: colors.textSecondary }}>{[pickedIds.length > 1 ? m.label : '', m.source ?? ''].filter(Boolean).join(' · ')}</Text>
+                    </View>
+                  ))}
+                </View>
+                {items.list.length > ITEMS_SHOWN ? (
+                  <InlineAction label={showAll ? 'Show fewer' : `Show all ${items.list.length}`} expanded={showAll} onPress={() => setShowAll(v => !v)} />
+                ) : null}
+              </>
+            )}
+          </View>
+        </ExpandRegion>
+
+        {/* The same words, heaviest first, for a screen reader. */}
+        <View style={{ position: 'absolute', width: 1, height: 1, overflow: 'hidden', left: -10000 }}>
+          <View role={'list' as never} aria-label={`${config.title}, as a list by weight`}>
+            {[...rows].sort((a, b) => b.weight - a.weight).map(r => <Text key={r.id} role={'listitem' as never}>{wordName(r, config.measure, config.sentLabels)}</Text>)}
+          </View>
+        </View>
+
+        {config.footer?.length ? <WellStrip left={config.footer[0]} right={config.footer[1]} /> : null}
+      </View>
+    </OnboardingCard>
+  );
+}
+
+/** TagCloud, guarded: a wrong-kind config is refused by name and a render error is caught (`shared/guard`). */
+export const TagCloud = guarded(TagCloudView, TAG_CLOUD_PRESETS, 'TagCloud');

package/src/components/onboarding/tag-cloud/contract.ts

@@ -0,0 +1,72 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/**
+ * **Weighted Tag Cloud (batch 6 §4.5)** — keywords sized by weight in five quantile tiers,
+ * shuffled deterministically, with filter on click. Read-only; the only entrance animation is
+ * M15's grow (heaviest tier first).
+ */
+
+export const TAG_SENTIMENTS = ['positive', 'neutral', 'negative'] as const;
+export type TagSentiment = (typeof TAG_SENTIMENTS)[number];
+export type TagWord = { id?: string; label: string; weight: number; sentiment?: TagSentiment | null };
+/** One item a keyword was extracted from — a review, a ticket, a request. `word` is the word's id. */
+export type TagMention = { word: string; text: string; source?: string };
+
+export const TAG_CLOUD_SCENES = ['default', 'none', 'filter1', 'filter3', 'sentFilter', 'shift', 'loadReady', 'loading', 'empty', 'error'] as const;
+export type TagCloudScene = (typeof TAG_CLOUD_SCENES)[number];
+export const TAG_CLOUD_IN_FLIGHT: readonly string[] = [];
+
+export type TagCloudSettings = HeaderConfig & LoadCopy & {
+  /** The unit of weight — "mentions", "tickets", "votes". */
+  measure: string;
+  /** The footer well strip: one line left, one right. */
+  footer: string[];
+  words: TagWord[];
+  /** The items each word was extracted from — shown below the cloud for the words a filter picks. */
+  mentions: TagMention[];
+  /** Word ids filtered on arrival. */
+  selected: string[];
+  /** The heaviest this many show; "+N more" shows the rest. */
+  maxVisible: number;
+  /** Demo-only: other weights by id — "Data change" swaps to them and back. */
+  altWeights: Record<string, number> | null;
+  /** What the dot means, when it is not sentiment — `{ positive: 'rising', neutral: 'flat', negative: 'falling' }`. */
+  sentLabels: Partial<Record<TagSentiment, string>> | null;
+  /** Demo-only: the scene this case ships in. */
+  ship: TagCloudScene | null;
+};
+
+export const TAG_CLOUD_PRESETS = presetsJson as unknown as PresetsFile<TagCloudSettings>;
+
+export function validateTagCloud(c: TagCloudSettings): OnboardingIssue[] {
+  if (!c || typeof c !== 'object') return [{ path: 'config', message: 'must be an object.' }];
+  if (!Array.isArray(c.words)) return [{ path: 'words', message: 'words is a list of { label, weight }.' }];
+  const out: OnboardingIssue[] = [];
+  const ids = new Set<string>();
+  c.words.forEach((w, i) => {
+    const p = `words[${i}]`;
+    if (!w || typeof w !== 'object') { out.push({ path: p, message: 'Each word is { label, weight }.' }); return; }
+    if (typeof w.label !== 'string' || !w.label.trim()) out.push({ path: `${p}.label`, message: 'Every word needs a label.' });
+    if (typeof w.weight !== 'number' || !Number.isFinite(w.weight) || w.weight < 0) out.push({ path: `${p}.weight`, message: 'weight is a number, 0 or more.' });
+    if (w.sentiment !== undefined && w.sentiment !== null && (w.sentiment as string) !== '' && !(TAG_SENTIMENTS as readonly string[]).includes(w.sentiment)) {
+      out.push({ path: `${p}.sentiment`, message: `sentiment is ${TAG_SENTIMENTS.join(', ')} — or empty.` });
+    }
+    const id = w.id ?? w.label;
+    if (typeof id === 'string') { if (ids.has(id)) out.push({ path: `${p}.id`, message: `“${id}” is used twice.` }); ids.add(id); }
+  });
+  if (c.mentions !== undefined && c.mentions !== null) {
+    if (!Array.isArray(c.mentions)) out.push({ path: 'mentions', message: 'mentions is a list of { word, text, source }.' });
+    else c.mentions.forEach((m, i) => {
+      if (!m || typeof m !== 'object' || typeof m.word !== 'string' || !m.word) out.push({ path: `mentions[${i}].word`, message: 'Every mention names its word (the word’s id).' });
+      else if (typeof m.text !== 'string' || !m.text.trim()) out.push({ path: `mentions[${i}].text`, message: 'Every mention needs its text.' });
+    });
+  }
+  if (c.selected !== undefined && !(Array.isArray(c.selected) && c.selected.every(s => typeof s === 'string'))) out.push({ path: 'selected', message: 'selected is a list of word ids.' });
+  if (c.maxVisible !== undefined && !(typeof c.maxVisible === 'number' && c.maxVisible >= 1)) out.push({ path: 'maxVisible', message: 'maxVisible is a number, 1 or more.' });
+  if (c.altWeights !== null && c.altWeights !== undefined && (typeof c.altWeights !== 'object' || Array.isArray(c.altWeights) || Object.values(c.altWeights).some(v => typeof v !== 'number'))) {
+    out.push({ path: 'altWeights', message: 'altWeights is { wordId: weight } — or null.' });
+  }
+  if (c.footer !== undefined && c.footer !== null && !(Array.isArray(c.footer) && c.footer.every(s => typeof s === 'string'))) out.push({ path: 'footer', message: 'footer is a list of text (left, right).' });
+  return out;
+}

package/src/components/onboarding/tag-cloud/engine.ts

@@ -0,0 +1,104 @@
+import { fnv, tiersOf } from '../shared/insight';
+import type { TagCloudScene, TagCloudSettings, TagMention, TagSentiment, TagWord } from './contract';
+
+/** **The Tag Cloud engine** — pure: tiers, the shuffle, what is visible, filters and the grow's timing. */
+
+export type TagCloudRow = { id: string; label: string; weight: number; sentiment: TagSentiment | null; tier: number };
+
+export const TIER_SIZE = [12, 14, 16, 20, 24] as const;
+
+export function tagWords(c: TagCloudSettings, alt: boolean): (TagWord & { id: string })[] {
+  return c.words.map(w => {
+    const id = w.id ?? w.label;
+    const a = alt && c.altWeights ? c.altWeights[id] : undefined;
+    return { ...w, id, weight: typeof a === 'number' ? a : w.weight };
+  });
+}
+
+/**
+ * The words to draw, in their shuffled order (FNV of the id) — the heaviest `maxVisible` unless
+ * `all`. Each with its tier among every word.
+ */
+export function tagRows(c: TagCloudSettings, alt: boolean, all: boolean): { rows: TagCloudRow[]; hidden: number } {
+  const words = tagWords(c, alt);
+  const tiers = tiersOf(words);
+  const byWeight = [...words].sort((a, b) => b.weight - a.weight);
+  const limit = Math.max(1, c.maxVisible ?? 40);
+  const shown = new Set((all ? byWeight : byWeight.slice(0, limit)).map(w => w.id));
+  const rows = words
+    .filter(w => shown.has(w.id))
+    .sort((a, b) => fnv(a.id) - fnv(b.id) || a.id.localeCompare(b.id))
+    .map(w => ({ id: w.id, label: w.label, weight: w.weight, sentiment: (w.sentiment || null) as TagSentiment | null, tier: tiers[w.id] ?? 1 }));
+  return { rows, hidden: words.length - shown.size };
+}
+
+/** The words that change tier when the weights swap — they fade out, then grow back. */
+export function changedTiers(c: TagCloudSettings, alt: boolean): string[] {
+  const a = tiersOf(tagWords(c, alt)), b = tiersOf(tagWords(c, !alt));
+  return Object.keys(a).filter(k => a[k] !== b[k]);
+}
+
+/** Grow: tier 5 at 0ms, 4 at 150 … 1 at 600; within a tier 20ms apart, capped at 150ms. */
+export function growStart(rows: TagCloudRow[], id: string): number {
+  const row = rows.find(r => r.id === id);
+  if (!row) return 0;
+  const k = rows.filter(r => r.tier === row.tier).findIndex(r => r.id === id);
+  return (5 - row.tier) * 150 + Math.min(k * 20, 150);
+}
+export const GROW_MS = 300;
+export const GROW_END = 600 + 150 + GROW_MS;
+
+export const sentimentCounts = (rows: { sentiment: TagSentiment | null }[]) => {
+  const n: Record<TagSentiment, number> = { positive: 0, neutral: 0, negative: 0 };
+  rows.forEach(r => { if (r.sentiment) n[r.sentiment]++; });
+  return n;
+};
+
+/** The words a filter picks: those selected, and those of a selected sentiment. */
+export function filteredIds(rows: TagCloudRow[], sel: string[], sent: TagSentiment[]): string[] {
+  return rows.filter(r => sel.includes(r.id) || (r.sentiment !== null && sent.includes(r.sentiment))).map(r => r.id);
+}
+
+/** "build quality, 142 mentions, positive" */
+export function wordName(r: TagCloudRow, measure: string, labels?: Partial<Record<TagSentiment, string>> | null): string {
+  const s = r.sentiment ? `, ${labels?.[r.sentiment] ?? r.sentiment}` : '';
+  return `${r.label}, ${r.weight.toLocaleString('en-US')} ${measure}${s}`;
+}
+
+export type TagCloudState = { sel: string[]; sent: TagSentiment[]; shift: boolean; loadReady: boolean };
+export type TagCloudSeed = Partial<TagCloudState>;
+
+export function initialTagCloud(c: TagCloudSettings, seed: TagCloudSeed = {}): TagCloudState {
+  const ids = new Set(tagWords(c, false).map(w => w.id));
+  return { sel: (seed.sel ?? c.selected ?? []).filter(id => ids.has(id)), sent: seed.sent ?? [], shift: seed.shift ?? false, loadReady: seed.loadReady ?? false };
+}
+
+export function tagCloudSeed(c: TagCloudSettings, scene: TagCloudScene): TagCloudSeed {
+  const ws = [...tagWords(c, false)].sort((a, b) => b.weight - a.weight);
+  if (scene === 'none') return { sel: [] };
+  if (scene === 'filter1') return { sel: ws[0] ? [ws[0].id] : [] };
+  if (scene === 'filter3') return { sel: [ws[0], ws[3], ws[6]].filter(Boolean).map(w => w!.id) };
+  if (scene === 'sentFilter') return { sel: [], sent: ['negative'] };
+  if (scene === 'shift') return { shift: true };
+  if (scene === 'loadReady') return { loadReady: true };
+  return {};
+}
+
+export function tagCloudScene(s: { sel: string[]; sent: TagSentiment[] }): TagCloudScene {
+  if (s.sent.length) return 'sentFilter';
+  if (!s.sel.length) return 'none';
+  return s.sel.length === 1 ? 'filter1' : 'filter3';
+}
+
+/** The items behind the picked words, in the order the words were picked (then as listed). */
+export function mentionsFor(c: TagCloudSettings, ids: string[]): (TagMention & { label: string })[] {
+  const label = new Map(tagWords(c, false).map(w => [w.id, w.label]));
+  const list = Array.isArray(c.mentions) ? c.mentions : [];
+  return ids.flatMap(id => list.filter(m => m && m.word === id).map(m => ({ ...m, label: label.get(id) ?? id })));
+}
+
+/** The panel's heading: "3 items for build quality", "5 items for 2 keywords". */
+export function mentionsHeading(n: number, words: string[]): string {
+  const what = words.length === 1 ? words[0] : `${words.length} keywords`;
+  return `${n} ${n === 1 ? 'item' : 'items'} for ${what}`;
+}

package/src/components/onboarding/tag-cloud/index.ts

@@ -0,0 +1,9 @@
+export {
+  TAG_CLOUD_IN_FLIGHT, TAG_CLOUD_PRESETS, TAG_CLOUD_SCENES, TAG_SENTIMENTS, validateTagCloud,
+  type TagCloudScene, type TagCloudSettings, type TagMention, type TagSentiment, type TagWord,
+} from './contract';
+export {
+  GROW_END, GROW_MS, TIER_SIZE, changedTiers, filteredIds, growStart, initialTagCloud, mentionsFor, mentionsHeading, sentimentCounts, tagCloudScene, tagCloudSeed, tagRows, tagWords, wordName,
+  type TagCloudRow, type TagCloudSeed, type TagCloudState,
+} from './engine';
+export { TagCloud, type TagCloudOperations, type TagCloudProps } from './TagCloudView';