@onboarding-yak/react-native 0.0.0-stage → 0.6.1

package/src/logic.ts

@@ -0,0 +1,36 @@
+// Mirrors lib/flow-schema.ts so the SDK branches and fills copy exactly like the studio preview.
+/** Show a screen only when an earlier choice question's answer matches (or, with `not`, doesn't match) one of `anyOf`. */
+export type ScreenCondition = { screen: string; anyOf: string[]; not?: boolean };
+/** Let people pick several options. The button stays disabled until `min` are picked. */
+export type MultipleChoice = { min?: number; max?: number };
+
+/** Whether a screen should show, given the options picked so far (keyed by screen id). Unanswered conditions hide the screen. */
+export function screenVisible(screen: { showIf?: ScreenCondition }, picked: Record<string, string[]>) {
+  const rule = screen.showIf;
+  if (!rule || !rule.screen || !Array.isArray(rule.anyOf)) return true;
+  const values = picked[rule.screen];
+  if (!values) return !!rule.not;
+  const hit = values.some((value) => rule.anyOf.includes(value));
+  return rule.not ? !hit : hit;
+}
+
+/** The next screen index to show after `from` in a direction, skipping screens whose condition fails; -1 when there is none. */
+export function nextVisibleIndex(screens: { showIf?: ScreenCondition }[], from: number, picked: Record<string, string[]>) {
+  for (let index = from + 1; index < screens.length; index += 1) if (screenVisible(screens[index], picked)) return index;
+  return -1;
+}
+
+const TOKEN = /\{([a-z][a-z0-9_]{0,23})(?:\|([^{}]{0,40}))?\}/gi;
+
+/** Replaces {name} with a saved answer, or {name|fallback} with the fallback when there is no answer yet. */
+export function fillTokens(text: string, values: Record<string, string>) {
+  return text.replace(TOKEN, (_, name: string, fallback?: string) => {
+    const value = values[name.toLowerCase()];
+    return value && value.trim() ? value : fallback ?? '';
+  });
+}
+
+/** Token names used in a piece of copy, for hints and checks. */
+export function tokensIn(text: string) {
+  return [...text.matchAll(TOKEN)].map((match) => match[1].toLowerCase());
+}

package/src/pickers.tsx

@@ -0,0 +1,253 @@
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import { Animated, Easing, Pressable, ScrollView, StyleSheet, Text, TextInput, View } from 'react-native';
+import { COUNTRIES, flagOf } from './countries';
+import { nearestIndex, toBaseUnit, unitChoices, unitLabel, unitValues, type UnitChoice, type UnitOption } from './units';
+import { formatNumber } from './variables';
+
+/** The value as shown in the unit the person chose, e.g. "154 lb" or "5′ 9″". */
+const shownIn = (value: number, choice: UnitChoice) => choice.display === 'feet-inches' ? unitLabel(value, choice) : `${formatNumber(value)}${choice.unit ? ` ${choice.unit}` : ''}`;
+
+type Colors = { text: string; muted: string; primary: string; card: string; line: string; font?: string; bodyFont?: string; onPrimary?: string };
+
+const ROW = 44;
+const VISIBLE = 5;
+
+// A snapping wheel; the middle row is the selection.
+function Wheel({ values, index, onIndex, colors, label, flex = 1 }: { values: string[]; index: number; onIndex: (index: number) => void; colors: Colors; label: string; flex?: number }) {
+  const scroller = useRef<React.ComponentRef<typeof ScrollView>>(null);
+  const [current, setCurrent] = useState(index);
+  const placed = useRef(false);
+  useEffect(() => { setCurrent(index); scroller.current?.scrollTo({ y: index * ROW, animated: false }); }, [index]);
+  const settle = (offset: number) => {
+    const next = Math.max(0, Math.min(values.length - 1, Math.round(offset / ROW)));
+    setCurrent(next);
+    if (next !== index) onIndex(next);
+  };
+  return <View style={{ flex, height: ROW * VISIBLE }} accessible accessibilityRole="adjustable" accessibilityLabel={label} accessibilityValue={{ text: values[current] }}
+    accessibilityActions={[{ name: 'increment' }, { name: 'decrement' }]}
+    onAccessibilityAction={(event) => { const next = Math.max(0, Math.min(values.length - 1, current + (event.nativeEvent.actionName === 'increment' ? 1 : -1))); onIndex(next); }}>
+    <ScrollView ref={scroller} showsVerticalScrollIndicator={false} snapToInterval={ROW} decelerationRate="fast" nestedScrollEnabled
+      contentOffset={{ x: 0, y: index * ROW }} contentContainerStyle={{ paddingVertical: ROW * 2 }}
+      // Android ignores contentOffset and drops scrollTo calls made before layout, so place the wheel once its content is measured.
+      onContentSizeChange={() => { if (!placed.current) { placed.current = true; scroller.current?.scrollTo({ y: index * ROW, animated: false }); } }}
+      onScroll={(event) => setCurrent(Math.max(0, Math.min(values.length - 1, Math.round(event.nativeEvent.contentOffset.y / ROW))))} scrollEventThrottle={32}
+      onMomentumScrollEnd={(event) => settle(event.nativeEvent.contentOffset.y)}
+      onScrollEndDrag={(event) => { if (!event.nativeEvent.velocity?.y) settle(event.nativeEvent.contentOffset.y); }}>
+      {values.map((value, valueIndex) => {
+        const distance = Math.abs(valueIndex - current);
+        return <View key={valueIndex} style={styles.wheelRow}><Text style={{ color: distance === 0 ? colors.text : colors.muted, opacity: distance === 0 ? 1 : distance === 1 ? 0.6 : 0.3, fontSize: distance === 0 ? 22 : 18, fontWeight: distance === 0 ? '700' : '500', fontFamily: colors.font }}>{value}</Text></View>;
+      })}
+    </ScrollView>
+  </View>;
+}
+
+function Band({ colors }: { colors: Colors }) {
+  return <View pointerEvents="none" style={[styles.band, { top: ROW * 2, backgroundColor: colors.card, borderColor: colors.line }]} />;
+}
+
+// Segmented control for switching units, e.g. kg / lb.
+function UnitTabs({ units, active, onSelect, colors }: { units: string[]; active: number; onSelect: (index: number) => void; colors: Colors }) {
+  return <View style={[styles.tabs, { backgroundColor: colors.card, borderColor: colors.line }]} accessibilityRole="tablist">
+    {units.map((unit, index) => {
+      const on = index === active;
+      return <Pressable key={unit} accessibilityRole="tab" accessibilityState={{ selected: on }} onPress={() => onSelect(index)} style={[styles.tab, on && { backgroundColor: colors.primary }]}>
+        <Text style={{ color: on ? colors.onPrimary : colors.muted, fontSize: 14, fontWeight: '700', fontFamily: colors.bodyFont }}>{unit}</Text>
+      </Pressable>;
+    })}
+  </View>;
+}
+
+type UnitInput = { min?: number; max?: number; step?: number; initial?: number; unit?: string; units?: UnitOption[] };
+
+/** A number wheel with an optional unit switch. The answer is always in the base unit. */
+export function NumberWheel({ input, onChange, colors }: { input: UnitInput; onChange: (value: string, display?: string) => void; colors: Colors }) {
+  const choices = useMemo(() => unitChoices(input), [input]);
+  const [unitIndex, setUnitIndex] = useState(0);
+  const choice = choices[unitIndex] ?? choices[0];
+  const values = useMemo(() => unitValues(choice), [choice]);
+  const baseValues = useMemo(() => unitValues(choices[0]), [choices]);
+  const start = nearestIndex(baseValues, input.initial ?? baseValues[Math.floor(baseValues.length / 2)] ?? 0);
+  const [index, setIndex] = useState(start);
+  const report = (value: number | undefined, from = choice) => { if (value !== undefined) onChange(String(toBaseUnit(value, from, choices[0])), shownIn(value, from)); };
+  useEffect(() => { report(baseValues[start], choices[0]); }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  const switchUnit = (next: number) => {
+    if (next === unitIndex) return;
+    const target = choices[next];
+    const base = toBaseUnit(values[index] ?? 0, choice, choices[0]);
+    const nextValues = unitValues(target);
+    const nextIndex = nearestIndex(nextValues, base * target.factor);
+    setUnitIndex(next);
+    setIndex(nextIndex);
+    report(nextValues[nextIndex], target);
+  };
+  return <View style={styles.wheelField}>
+    {choices.length > 1 ? <UnitTabs units={choices.map((item) => item.unit)} active={unitIndex} onSelect={switchUnit} colors={colors} /> : null}
+    <View style={styles.wheelWrap}>
+      <Band colors={colors} />
+      <Wheel key={unitIndex} values={values.map((value) => unitLabel(value, choice))} index={index} label={choice.unit ? `Value in ${choice.unit}` : 'Value'} colors={colors} onIndex={(next) => { setIndex(next); report(values[next]); }} />
+      {choice.unit && choice.display !== 'feet-inches' ? <View pointerEvents="none" style={[styles.unit, { top: ROW * 2 }]}><Text style={{ color: colors.muted, fontSize: 16, fontWeight: '600', fontFamily: colors.bodyFont }}>{choice.unit}</Text></View> : null}
+    </View>
+  </View>;
+}
+
+/** A large number field with the number keypad and an optional unit switch. The answer is always in the base unit. */
+export function NumberEntry({ input, placeholder, onChange, colors, size }: { input: UnitInput; placeholder?: string; onChange: (value: string, display?: string) => void; colors: Colors; size: number }) {
+  const choices = useMemo(() => unitChoices(input), [input]);
+  const [unitIndex, setUnitIndex] = useState(0);
+  const [text, setText] = useState('');
+  const choice = choices[unitIndex] ?? choices[0];
+  const report = (raw: string, from = choice) => {
+    const value = Number(raw.replace(',', '.'));
+    onChange(raw && Number.isFinite(value) ? String(toBaseUnit(value, from, choices[0])) : '', raw && Number.isFinite(value) ? shownIn(value, from) : undefined);
+  };
+  const switchUnit = (next: number) => {
+    const value = Number(text.replace(',', '.'));
+    const target = choices[next];
+    const converted = text && Number.isFinite(value) ? String(Math.round(toBaseUnit(value, choice, choices[0]) * target.factor * 10) / 10) : '';
+    setUnitIndex(next);
+    setText(converted);
+    report(converted, target);
+  };
+  return <View style={styles.wheelField}>
+    {choices.length > 1 ? <UnitTabs units={choices.map((item) => item.unit)} active={unitIndex} onSelect={switchUnit} colors={colors} /> : null}
+    <View style={[styles.numberRow, { borderColor: text ? colors.primary : colors.line }]}>
+      <TextInput accessibilityLabel={choice.unit ? `Your answer in ${choice.unit}` : 'Your answer'} keyboardType="decimal-pad" value={text} onChangeText={(raw) => { const clean = raw.replace(/[^\d.,]/g, ''); setText(clean); report(clean); }}
+        placeholder={unitIndex === 0 ? placeholder ?? '0' : '0'} placeholderTextColor={colors.muted} style={[styles.numberInput, { color: colors.text, fontFamily: colors.font, fontSize: size }]} />
+      {choice.unit ? <Text style={{ color: colors.muted, fontSize: 17, fontWeight: '600', fontFamily: colors.bodyFont }}>{choice.unit}</Text> : null}
+    </View>
+  </View>;
+}
+
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+const daysIn = (year: number, month: number) => new Date(year, month + 1, 0).getDate();
+
+/** Month, day, and year wheels. The answer is an ISO date, YYYY-MM-DD. */
+export function DateWheels({ minYear, maxYear, initialYear, onChange, colors }: { minYear?: number; maxYear?: number; initialYear?: number; onChange: (value: string) => void; colors: Colors }) {
+  const thisYear = new Date().getFullYear();
+  const lowest = Math.round(minYear ?? thisYear - 100);
+  const highest = Math.max(lowest, Math.round(maxYear ?? thisYear));
+  const years = useMemo(() => Array.from({ length: highest - lowest + 1 }, (_, offset) => lowest + offset), [lowest, highest]);
+  const [year, setYear] = useState(Math.min(highest, Math.max(lowest, Math.round(initialYear ?? Math.min(highest, thisYear - 25)))));
+  const [month, setMonth] = useState(0);
+  const [day, setDay] = useState(1);
+  const days = daysIn(year, month);
+  const safeDay = Math.min(day, days);
+  useEffect(() => { onChange(`${year}-${String(month + 1).padStart(2, '0')}-${String(safeDay).padStart(2, '0')}`); }, [year, month, safeDay]); // eslint-disable-line react-hooks/exhaustive-deps
+  return <View style={[styles.wheelWrap, styles.dateRow]}>
+    <Band colors={colors} />
+    <Wheel flex={1.6} values={MONTHS} index={month} label="Month" colors={colors} onIndex={setMonth} />
+    <Wheel flex={0.8} values={Array.from({ length: days }, (_, offset) => String(offset + 1))} index={safeDay - 1} label="Day" colors={colors} onIndex={(next) => setDay(next + 1)} />
+    <Wheel flex={1.1} values={years.map(String)} index={years.indexOf(year)} label="Year" colors={colors} onIndex={(next) => setYear(years[next])} />
+  </View>;
+}
+
+/** A searchable country list. The answer is the country's English name. */
+export function CountryPicker({ value, onChange, colors, placeholder }: { value: string; onChange: (value: string) => void; colors: Colors; placeholder?: string }) {
+  const [query, setQuery] = useState('');
+  const needle = query.trim().toLowerCase();
+  const matches = needle ? COUNTRIES.filter(([code, name]) => name.toLowerCase().includes(needle) || code.toLowerCase() === needle) : COUNTRIES;
+  return <View style={styles.country}>
+    <TextInput value={query} onChangeText={setQuery} placeholder={placeholder ?? 'Search countries'} placeholderTextColor={colors.muted} accessibilityLabel="Search countries" autoCorrect={false}
+      style={[styles.countrySearch, { color: colors.text, borderColor: colors.line, backgroundColor: colors.card, fontFamily: colors.bodyFont }]} />
+    {matches.map(([code, name]) => {
+      const picked = value === name;
+      return <Pressable key={code} accessibilityRole="radio" accessibilityState={{ checked: picked }} onPress={() => onChange(name)} style={[styles.countryRow, { borderColor: picked ? colors.primary : colors.line, backgroundColor: picked ? `${colors.primary}1f` : colors.card }]}>
+        <Text style={styles.countryFlag}>{flagOf(code)}</Text>
+        <Text style={{ flex: 1, color: colors.text, fontSize: 15, fontWeight: picked ? '700' : '500', fontFamily: colors.bodyFont }}>{name}</Text>
+        {picked ? <Text style={{ color: colors.primary, fontSize: 16, fontWeight: '700' }}>✓</Text> : null}
+      </Pressable>;
+    })}
+    {!matches.length ? <Text style={{ color: colors.muted, textAlign: 'center', paddingVertical: 12 }}>No countries match “{query}”</Text> : null}
+  </View>;
+}
+
+const STARS = (count: number) => '★★★★★'.slice(0, Math.max(0, Math.min(5, Math.round(count)))) + '☆☆☆☆☆'.slice(0, 5 - Math.max(0, Math.min(5, Math.round(count))));
+
+type Proof = { rating?: { score: number; count?: string; label?: string }; testimonials?: { quote: string; author: string; detail?: string; stars?: number }[]; stat?: string };
+
+/** Star rating, testimonials, and a stat line; cards rise in one after another. */
+export function ProofBlock({ proof, colors, reduceMotion, align }: { proof: Proof; colors: Colors; reduceMotion: boolean; align: 'left' | 'center' | 'right' }) {
+  const items = proof.testimonials?.filter((entry) => entry.quote.trim()).slice(0, 3) ?? [];
+  const rise = useRef([0, 1, 2, 3, 4].map(() => new Animated.Value(reduceMotion ? 1 : 0))).current;
+  useEffect(() => {
+    if (reduceMotion) return;
+    Animated.stagger(110, rise.map((value) => Animated.timing(value, { toValue: 1, duration: 420, easing: Easing.out(Easing.cubic), useNativeDriver: true }))).start();
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  const enter = (index: number) => ({ opacity: rise[index], transform: [{ translateY: rise[index].interpolate({ inputRange: [0, 1], outputRange: [10, 0] }) }] });
+  const cross = align === 'center' ? 'center' as const : align === 'right' ? 'flex-end' as const : 'flex-start' as const;
+  return <View style={styles.proof}>
+    {proof.rating ? <Animated.View style={[styles.proofRating, { alignItems: cross }, enter(0)]} accessible accessibilityLabel={`Rated ${proof.rating.score} out of 5${proof.rating.count ? `, ${proof.rating.count}` : ''}`}>
+      <View style={styles.proofScoreRow}>
+        <Text style={{ color: colors.text, fontSize: 34, fontWeight: '800', fontFamily: colors.font }}>{proof.rating.score.toFixed(1)}</Text>
+        <Text style={{ color: '#f5b301', fontSize: 22, letterSpacing: 2 }}>{STARS(proof.rating.score)}</Text>
+      </View>
+      {proof.rating.count || proof.rating.label ? <Text style={{ color: colors.muted, fontSize: 13, fontFamily: colors.bodyFont }}>{[proof.rating.count, proof.rating.label].filter(Boolean).join(' · ')}</Text> : null}
+    </Animated.View> : null}
+    {proof.stat ? <Animated.Text style={[{ color: colors.text, fontSize: 15, fontWeight: '700', textAlign: align, fontFamily: colors.bodyFont }, enter(1)]}>{proof.stat}</Animated.Text> : null}
+    {items.map((entry, index) => <Animated.View key={index} style={[styles.proofCard, { backgroundColor: colors.card, borderColor: colors.line }, enter(index + 2)]}>
+      {entry.stars ? <Text style={{ color: '#f5b301', fontSize: 14, letterSpacing: 1 }} accessibilityLabel={`${entry.stars} out of 5 stars`}>{STARS(entry.stars)}</Text> : null}
+      <Text style={{ color: colors.text, fontSize: 15, lineHeight: 21, fontFamily: colors.bodyFont }}>“{entry.quote}”</Text>
+      <Text style={{ color: colors.muted, fontSize: 13, fontWeight: '600', fontFamily: colors.bodyFont }}>{entry.author}{entry.detail ? ` · ${entry.detail}` : ''}</Text>
+    </Animated.View>)}
+  </View>;
+}
+
+const TICKS = 60;
+
+/** A ring that fills to 100% while each step gets a check mark; calls onDone when finished. */
+export function LoaderBlock({ steps, duration, colors, track, onDone }: { steps: string[]; duration: number; colors: Colors; track: string; onDone: () => void }) {
+  const progress = useRef(new Animated.Value(0)).current;
+  const [percent, setPercent] = useState(0);
+  const finished = useRef(false);
+  useEffect(() => {
+    const id = progress.addListener(({ value }) => setPercent(Math.round(value * 100)));
+    Animated.timing(progress, { toValue: 1, duration, easing: Easing.inOut(Easing.quad), useNativeDriver: false }).start(({ finished: done }) => {
+      if (done && !finished.current) { finished.current = true; onDone(); }
+    });
+    return () => progress.removeListener(id);
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  return <View style={styles.loader}>
+    <View style={styles.ring} accessible accessibilityRole="progressbar" accessibilityValue={{ min: 0, max: 100, now: percent }}>
+      {Array.from({ length: TICKS }, (_, index) => <View key={index} style={[styles.ringTickWrap, { transform: [{ rotate: `${(index / TICKS) * 360}deg` }] }]}><View style={[styles.ringTick, { backgroundColor: index / TICKS < percent / 100 ? colors.primary : track }]} /></View>)}
+      <Text style={[styles.ringValue, { color: colors.text, fontFamily: colors.font }]}>{percent}%</Text>
+    </View>
+    <View style={styles.steps}>{steps.map((label, index) => {
+      const done = percent >= Math.round(((index + 1) / steps.length) * 100);
+      const active = !done && percent >= Math.round((index / steps.length) * 100);
+      return <View key={`${index}-${label}`} style={styles.stepRow}>
+        <View style={[styles.stepMark, { borderColor: done ? colors.primary : colors.line, backgroundColor: done ? colors.primary : 'transparent' }]}>{done ? <Text style={[styles.stepGlyph, { color: colors.card }]}>✓</Text> : null}</View>
+        <Text style={{ flex: 1, color: done || active ? colors.text : colors.muted, fontSize: 15, fontWeight: active ? '700' : '500', fontFamily: colors.bodyFont }}>{label}</Text>
+      </View>;
+    })}</View>
+  </View>;
+}
+
+const styles = StyleSheet.create({
+  wheelWrap: { alignSelf: 'stretch', height: ROW * VISIBLE, justifyContent: 'center' },
+  wheelField: { alignSelf: 'stretch', gap: 14 },
+  tabs: { flexDirection: 'row', alignSelf: 'center', padding: 3, borderRadius: 12, borderWidth: 1 },
+  tab: { minWidth: 64, paddingVertical: 7, paddingHorizontal: 14, borderRadius: 9, alignItems: 'center' },
+  numberRow: { alignSelf: 'stretch', flexDirection: 'row', alignItems: 'baseline', justifyContent: 'center', gap: 8, borderBottomWidth: 2, paddingVertical: 10 },
+  numberInput: { minWidth: 72, textAlign: 'center', fontWeight: '700', padding: 0 },
+  dateRow: { flexDirection: 'row', gap: 4 },
+  wheelRow: { height: ROW, alignItems: 'center', justifyContent: 'center' },
+  band: { position: 'absolute', left: 0, right: 0, height: ROW, borderRadius: 12, borderWidth: 1 },
+  unit: { position: 'absolute', right: 18, height: ROW, justifyContent: 'center' },
+  country: { alignSelf: 'stretch', gap: 8 },
+  countrySearch: { minHeight: 46, borderWidth: 1, borderRadius: 12, paddingHorizontal: 14, fontSize: 15 },
+  countryRow: { minHeight: 48, flexDirection: 'row', alignItems: 'center', gap: 12, paddingHorizontal: 14, borderWidth: 1, borderRadius: 12 },
+  countryFlag: { fontSize: 22 },
+  loader: { alignSelf: 'stretch', alignItems: 'center', gap: 22 },
+  proof: { alignSelf: 'stretch', gap: 12 },
+  proofRating: { gap: 2 },
+  proofScoreRow: { flexDirection: 'row', alignItems: 'center', gap: 10 },
+  proofCard: { gap: 6, padding: 14, borderRadius: 14, borderWidth: 1 },
+  ring: { width: 148, height: 148, alignItems: 'center', justifyContent: 'center' },
+  ringTickWrap: { position: 'absolute', width: 148, height: 148, alignItems: 'center' },
+  ringTick: { width: 4, height: 14, borderRadius: 2 },
+  ringValue: { fontSize: 32, fontWeight: '800' },
+  steps: { alignSelf: 'stretch', gap: 12 },
+  stepRow: { flexDirection: 'row', alignItems: 'center', gap: 12 },
+  stepMark: { width: 24, height: 24, borderRadius: 12, borderWidth: 2, alignItems: 'center', justifyContent: 'center' },
+  stepGlyph: { fontSize: 13, fontWeight: '800', lineHeight: 16 },
+});

package/src/units.ts

@@ -0,0 +1,41 @@
+// Mirrors lib/flow-schema.ts so the SDK converts units exactly like the studio preview.
+/** An extra unit people can switch to, e.g. lb for a kg wheel. `factor` converts from the base unit: other = base × factor. */
+export type UnitOption = { unit: string; factor: number; min?: number; max?: number; step?: number; display?: 'feet-inches' };
+export type UnitChoice = { unit: string; factor: number; min: number; max: number; step: number; display?: 'feet-inches' };
+
+const decimalsOf = (value: number) => (String(value).split('.')[1] ?? '').length;
+
+/** The base unit first, then up to two switchable units with ranges derived from the base when left out. */
+export function unitChoices(input: { unit?: string; min?: number; max?: number; step?: number; units?: UnitOption[] } | undefined): UnitChoice[] {
+  const step = input?.step && input.step > 0 ? input.step : 1;
+  const base: UnitChoice = { unit: input?.unit ?? '', factor: 1, min: input?.min ?? 0, max: input?.max ?? 100, step };
+  const extra = (input?.units ?? []).filter((option) => option && typeof option.unit === 'string' && option.unit && Number.isFinite(option.factor) && option.factor > 0).slice(0, 2)
+    .map((option): UnitChoice => ({ unit: option.unit, factor: option.factor, min: option.min ?? Math.round(base.min * option.factor), max: option.max ?? Math.round(base.max * option.factor), step: option.step && option.step > 0 ? option.step : 1, display: option.display }));
+  return [base, ...extra];
+}
+
+export function unitValues(choice: UnitChoice) {
+  const list: number[] = [];
+  for (let value = choice.min; value <= choice.max + 1e-9 && list.length < 2000; value += choice.step) list.push(Math.round(value * 100) / 100);
+  return list;
+}
+
+/** 69 → 5′ 9″ for feet-inches; otherwise the number as is. */
+export function unitLabel(value: number, choice: UnitChoice) {
+  if (choice.display !== 'feet-inches') return String(value);
+  const inches = Math.round(value);
+  return `${Math.floor(inches / 12)}′ ${inches % 12}″`;
+}
+
+/** Answers are always reported in the base unit, rounded to the base step's precision. */
+export function toBaseUnit(value: number, choice: UnitChoice, base: UnitChoice) {
+  if (choice.factor === 1) return value;
+  const places = decimalsOf(base.step);
+  return Math.round((value / choice.factor) * 10 ** places) / 10 ** places;
+}
+
+export function nearestIndex(values: number[], target: number) {
+  let best = 0;
+  for (let index = 1; index < values.length; index += 1) if (Math.abs(values[index] - target) < Math.abs(values[best] - target)) best = index;
+  return best;
+}

package/src/variables.ts

@@ -0,0 +1,80 @@
+// Mirrors lib/flow-schema.ts so recalled variables read the same in the app as in the studio preview.
+export type VariableType = 'text' | 'number' | 'money' | 'date' | 'choice' | 'list' | 'country';
+export type DateStyle = 'long' | 'medium' | 'short' | 'numeric';
+/** How a question's saved answer is shown when recalled: a currency turns a number into money; dates pick a style. */
+export type VariableFormat = { currency?: string; dateStyle?: DateStyle };
+/** What the app receives for each variable: the raw value for logic or storage, and the text the onboarding showed. */
+export type VariableValue = { type: VariableType; value: string | number | string[]; unit?: string; currency?: string; display: string };
+
+/** Always available in copy; question answers can't use these names. */
+export const BUILT_IN_VARIABLES = ['app_name', 'first_name', 'today', 'weekday'] as const;
+export const CURRENCY_SYMBOLS: Record<string, string> = { USD: '$', EUR: '€', GBP: '£', JPY: '¥', CNY: '¥', INR: '₹', BRL: 'R$', MXN: 'MX$', CAD: 'CA$', AUD: 'A$', CHF: 'CHF ', SEK: 'kr ', NOK: 'kr ', DKK: 'kr ', KRW: '₩', ZAR: 'R ', TRY: '₺', PLN: 'zł ', SGD: 'S$', NZD: 'NZ$' };
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+/** The variable type a question produces, from its answer format. */
+export function variableType(screen: { answerType?: string; multiple?: unknown; input?: { format?: string }; variableFormat?: VariableFormat }): VariableType {
+  if (screen.answerType === 'singleChoice') return screen.multiple ? 'list' : 'choice';
+  const format = screen.input?.format;
+  if (format === 'number' || format === 'wheel') return screen.variableFormat?.currency ? 'money' : 'number';
+  if (format === 'date') return 'date';
+  if (format === 'country') return 'country';
+  return 'text';
+}
+
+/** 3000 → "3,000"; 70.5 → "70.5". Done by hand so it reads the same on every device and JavaScript engine. */
+export function formatNumber(value: number) {
+  const fixed = Math.round(value * 100) / 100;
+  const [whole, fraction] = String(Math.abs(fixed)).split('.');
+  const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  return `${fixed < 0 ? '-' : ''}${grouped}${fraction ? `.${fraction}` : ''}`;
+}
+
+export function formatMoney(value: number, currency: string) {
+  const symbol = CURRENCY_SYMBOLS[currency.toUpperCase()] ?? `${currency.toUpperCase()} `;
+  return `${symbol}${formatNumber(value)}`;
+}
+
+/** "1995-01-04" → "January 4, 1995" (long), "Jan 4, 1995" (medium), "Jan 4" (short), "1/4/1995" (numeric). */
+export function formatDate(iso: string, style: DateStyle = 'long') {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+  if (!match) return iso;
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  const name = MONTHS[month - 1] ?? '';
+  if (style === 'numeric') return `${month}/${day}/${year}`;
+  if (style === 'short') return `${name.slice(0, 3)} ${day}`;
+  if (style === 'medium') return `${name.slice(0, 3)} ${day}, ${year}`;
+  return `${name} ${day}, ${year}`;
+}
+
+/** ["Dairy", "Nuts", "Gluten"] → "Dairy, Nuts and Gluten". */
+export function joinList(items: string[]) {
+  if (items.length <= 1) return items[0] ?? '';
+  return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
+
+/** A question's answer as a typed variable. `display` from a number wheel or field carries the unit the person chose (e.g. "154 lb"). */
+export function variableValue(screen: { answerType?: string; multiple?: unknown; input?: { format?: string; unit?: string }; variableFormat?: VariableFormat }, answer: string, picks: string[] = [], display?: string): VariableValue | null {
+  const type = variableType(screen);
+  if (type === 'list') return picks.length ? { type, value: picks, display: joinList(picks) } : null;
+  if (!answer.trim()) return null;
+  if (type === 'number' || type === 'money') {
+    const number = Number(answer.replace(',', '.'));
+    if (!Number.isFinite(number)) return { type: 'text', value: answer, display: answer };
+    if (type === 'money') { const currency = (screen.variableFormat?.currency ?? 'USD').toUpperCase(); return { type, value: number, currency, display: formatMoney(number, currency) }; }
+    const unit = screen.input?.unit || undefined;
+    return { type, value: number, unit, display: display || `${formatNumber(number)}${unit ? ` ${unit}` : ''}` };
+  }
+  if (type === 'date') return { type, value: answer, display: formatDate(answer, screen.variableFormat?.dateStyle) };
+  return { type, value: answer, display: answer };
+}
+
+/** Values for the built-in variables. */
+export function builtInValues(appName: string | undefined, values: Record<string, string>, now = new Date()) {
+  return {
+    app_name: appName ?? '',
+    first_name: (values.name ?? '').trim().split(/\s+/)[0] ?? '',
+    today: `${MONTHS[now.getMonth()]} ${now.getDate()}`,
+    weekday: WEEKDAYS[now.getDay()],
+  };
+}