@wireai/activation 0.1.0

package/src/cards/SelectionCard.tsx

@@ -0,0 +1,270 @@
+/**
+ * Themed SelectionCard — drop-in for the OSS SDK's SelectionCard. Same `name`,
+ * `propsSchema` (including the string|object option preprocess), `defaultProps`,
+ * and `onSelect(string | string[])` contract. Radio/checkbox styling is themed.
+ *
+ * Motion (design-refs/EXTRACTED-SPEC.md rows 1-3): rows tick on press (scale
+ * 0.975 spring), the selected fill/border eases in over 180ms ease-wire (a
+ * native-driver opacity crossfade of a selected-style overlay), and the check
+ * dot pops with a spring. All gated by useReducedMotion (snap, no spring).
+ */
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Animated, Easing, Pressable, StyleSheet, Text, View } from "react-native";
+import { z } from "zod";
+import type { InjectedProps, WireAIComponent } from "wireai-rn";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { labelStyle } from "../theme/typography";
+import { Button } from "../components/Button";
+import { CardLayout } from "../components/CardLayout";
+import {
+  CHECK_SCALE_FROM,
+  CHECK_SPRING,
+  PRESS_SPRING,
+  ROW_PRESS_SCALE,
+  SELECT_FILL_MS,
+  WIRE_BEZIER,
+  scaledMs,
+  stateChangeDuration,
+} from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+
+const optionObjectSchema = z.object({
+  value: z.string().describe("Option value"),
+  label: z.string().describe("Option display label"),
+});
+
+const schema = z.object({
+  title: z.string().describe("Question or prompt for the user"),
+  options: z
+    .preprocess(
+      (arr) =>
+        Array.isArray(arr)
+          ? arr.map((item) => (typeof item === "string" ? { value: item, label: item } : item))
+          : arr,
+      z.array(optionObjectSchema).min(1),
+    )
+    .describe("List of choices"),
+  submitLabel: z.string().optional().describe("Submit button label, default: Continue"),
+  multiSelect: z.boolean().optional().describe("Allow multiple selections"),
+});
+
+type Props = z.infer<typeof schema> &
+  InjectedProps & {
+    onSelect?: (selected: string | string[]) => void;
+    /** Fires as the live selection changes (before Continue), so the flow can prefetch the
+     *  next turn. Same value shape as onSelect. Optional — injected by OnboardingFlow. */
+    onSelectionChange?: (selected: string | string[]) => void;
+  };
+
+type OptionRowProps = {
+  opt: z.infer<typeof optionObjectSchema>;
+  isSelected: boolean;
+  multiSelect: boolean;
+  onToggle: (value: string) => void;
+};
+
+const _OptionRow: React.FC<OptionRowProps> = ({ opt, isSelected, multiSelect, onToggle }) => {
+  const t = useOnboardingTheme();
+  const reduced = useReducedMotion();
+  const handlePress = useCallback(() => onToggle(opt.value), [opt.value, onToggle]);
+
+  // Press tick: scale 1→0.975, spring, native driver. Skipped under reduce motion.
+  const pressScale = useRef(new Animated.Value(1)).current;
+  const pressTo = useCallback(
+    (to: number) => {
+      if (reduced) return;
+      Animated.spring(pressScale, {
+        toValue: to,
+        friction: PRESS_SPRING.friction,
+        tension: PRESS_SPRING.tension,
+        useNativeDriver: true,
+      }).start();
+    },
+    [pressScale, reduced],
+  );
+  const handlePressIn = useCallback(() => pressTo(ROW_PRESS_SCALE), [pressTo]);
+  const handlePressOut = useCallback(() => pressTo(1), [pressTo]);
+
+  // Selected fill: the selected border+bg live on an absolute overlay whose opacity
+  // crossfades in 180ms ease-wire — same visual as a color interpolation, but it
+  // stays on the native driver (see EXTRACTED-SPEC.md D7). Reduce motion: snap.
+  const selectT = useRef(new Animated.Value(isSelected ? 1 : 0)).current;
+  useEffect(() => {
+    const anim = Animated.timing(selectT, {
+      toValue: isSelected ? 1 : 0,
+      duration: scaledMs(stateChangeDuration(reduced, SELECT_FILL_MS)),
+      easing: easeWire,
+      useNativeDriver: true,
+    });
+    anim.start();
+    return () => anim.stop();
+  }, [isSelected, reduced, selectT]);
+
+  // Check pop: scale 0.6→1 + fade, springy. Reduce motion: shown at scale 1 instantly.
+  const checkT = useRef(new Animated.Value(isSelected ? 1 : 0)).current;
+  useEffect(() => {
+    if (!isSelected) {
+      checkT.setValue(0);
+      return;
+    }
+    if (reduced) {
+      checkT.setValue(1);
+      return;
+    }
+    checkT.setValue(0);
+    const anim = Animated.spring(checkT, {
+      toValue: 1,
+      friction: CHECK_SPRING.friction,
+      tension: CHECK_SPRING.tension,
+      useNativeDriver: true,
+    });
+    anim.start();
+    return () => anim.stop();
+  }, [isSelected, reduced, checkT]);
+
+  const checkScale = checkT.interpolate({ inputRange: [0, 1], outputRange: [CHECK_SCALE_FROM, 1] });
+
+  return (
+    <Pressable
+      onPress={handlePress}
+      onPressIn={handlePressIn}
+      onPressOut={handlePressOut}
+      accessibilityRole={multiSelect ? "checkbox" : "radio"}
+      accessibilityState={multiSelect ? { checked: isSelected } : { selected: isSelected }}
+      accessibilityLabel={opt.label}
+    >
+      <Animated.View
+        style={[
+          styles.option,
+          {
+            padding: t.spacing.md,
+            borderRadius: t.radius.md,
+            gap: t.spacing.sm,
+            borderColor: t.colors.border,
+            backgroundColor: t.colors.background,
+            transform: [{ scale: pressScale }],
+          },
+        ]}
+      >
+        <Animated.View
+          pointerEvents="none"
+          style={[
+            StyleSheet.absoluteFill,
+            styles.selectedOverlay,
+            {
+              borderRadius: t.radius.md,
+              borderColor: t.colors.primary,
+              backgroundColor: t.colors.primarySoft,
+              opacity: selectT,
+            },
+          ]}
+        />
+        <View
+          style={[
+            styles.indicator,
+            { borderRadius: t.radius.full },
+            isSelected
+              ? { borderColor: t.colors.primary, backgroundColor: t.colors.primary }
+              : { borderColor: t.colors.borderStrong, backgroundColor: "transparent" },
+          ]}
+        >
+          {isSelected ? (
+            <Animated.Text
+              style={[
+                styles.check,
+                { color: t.colors.onPrimary, opacity: checkT, transform: [{ scale: checkScale }] },
+              ]}
+            >
+              ✓
+            </Animated.Text>
+          ) : null}
+        </View>
+        {/* Accent discipline: the label keeps the text color in both states; the
+            accent lives on the border, fill, and dot only. */}
+        <Text style={[labelStyle(t.fonts), { color: t.colors.text }]}>{opt.label}</Text>
+      </Animated.View>
+    </Pressable>
+  );
+};
+const OptionRow = React.memo(_OptionRow);
+
+const _SelectionCard: React.FC<Props> = ({
+  title,
+  options,
+  submitLabel = "Continue",
+  multiSelect = false,
+  onSelect,
+  onSelectionChange,
+}) => {
+  const t = useOnboardingTheme();
+  const [selected, setSelected] = useState<string[]>([]);
+  const [submitted, setSubmitted] = useState(false);
+
+  // Report the settled selection upward (before Continue) so the flow can prefetch the next
+  // turn. Debouncing lives in the flow; here we just emit on every change once something's picked.
+  useEffect(() => {
+    if (!submitted && selected.length) onSelectionChange?.(multiSelect ? selected : selected[0]!);
+  }, [selected, submitted, multiSelect, onSelectionChange]);
+
+  const toggle = useCallback(
+    (value: string) => {
+      if (submitted) return;
+      if (multiSelect) {
+        setSelected((prev) => (prev.includes(value) ? prev.filter((v) => v !== value) : [...prev, value]));
+      } else {
+        setSelected([value]);
+      }
+    },
+    [submitted, multiSelect],
+  );
+
+  const handleSubmit = useCallback(() => {
+    if (!selected.length || !onSelect || submitted) return;
+    setSubmitted(true);
+    onSelect(multiSelect ? selected : selected[0]!);
+  }, [selected, onSelect, submitted, multiSelect]);
+
+  return (
+    <CardLayout
+      title={title}
+      footer={
+        <Button
+          title={submitLabel}
+          onPress={handleSubmit}
+          variant="primary"
+          disabled={selected.length === 0 || submitted}
+        />
+      }
+    >
+      <View style={{ gap: t.spacing.sm + t.spacing.xs }}>
+        {options.map((opt) => (
+          <OptionRow
+            key={opt.value}
+            opt={opt}
+            isSelected={selected.includes(opt.value)}
+            multiSelect={multiSelect}
+            onToggle={toggle}
+          />
+        ))}
+      </View>
+    </CardLayout>
+  );
+};
+
+export const SelectionCard: WireAIComponent = {
+  name: "SelectionCard",
+  description:
+    "Use for mutually exclusive (radio) or multi-select (checkbox) choices from 2–8 options. Use ChipSelectCard instead when options are short single words.",
+  component: React.memo(_SelectionCard) as WireAIComponent["component"],
+  propsSchema: schema,
+  defaultProps: { submitLabel: "Continue", multiSelect: false },
+};
+
+const styles = StyleSheet.create({
+  option: { borderWidth: 1.5, flexDirection: "row", alignItems: "center", overflow: "hidden" },
+  selectedOverlay: { borderWidth: 1.5 },
+  indicator: { width: 24, height: 24, borderWidth: 2, alignItems: "center", justifyContent: "center" },
+  check: { fontSize: 13, fontWeight: "800", lineHeight: 15 },
+});

package/src/cards/StatusCard.tsx

@@ -0,0 +1,170 @@
+/**
+ * Themed StatusCard — drop-in for the OSS SDK's StatusCard. Same `name`,
+ * `propsSchema`, and the onContinue/onPress/onSubmit callback fallback chain.
+ * The terminal StatusCard is what OnboardingFlow treats as "flow complete".
+ * Status colors read from the theme's semantic palette.
+ *
+ * Motion (design-refs/EXTRACTED-SPEC.md rows 14, 16): the status glyph pops in
+ * with a spring (scale 0.4→1, overshoot) and the copy fades up 80ms behind it.
+ * Reduce motion: final frame instantly. (The terminal payoff with the burst is
+ * CompletionView; this card is the inline status treatment.)
+ */
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Animated, Easing, StyleSheet, Text, View } from "react-native";
+import { z } from "zod";
+import type { InjectedProps, WireAIComponent } from "wireai-rn";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { bodyStyle, headingStyle } from "../theme/typography";
+import { Button } from "../components/Button";
+import { CardLayout } from "../components/CardLayout";
+import {
+  STATUS_COPY_MS,
+  STATUS_COPY_STAGGER_MS,
+  STATUS_POP_SCALE_FROM,
+  STATUS_POP_SPRING,
+  WIRE_BEZIER,
+  scaledMs,
+} from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+
+const schema = z.object({
+  status: z.enum(["success", "warning", "error", "info"]).describe("Status type"),
+  title: z.string().describe("Status title"),
+  message: z.string().optional().describe("Supporting message"),
+  ctaLabel: z
+    .string()
+    .optional()
+    .describe(
+      "Optional call-to-action button label. Always include this on success status to keep the conversation going.",
+    ),
+});
+
+type Props = z.infer<typeof schema> &
+  InjectedProps & {
+    onContinue?: () => void;
+    onPress?: (label: string) => void;
+    onSubmit?: (value: string) => void;
+  };
+
+const STATUS_ICONS: Record<string, string> = {
+  success: "✓",
+  warning: "⚠",
+  error: "✗",
+  info: "ℹ",
+};
+
+const _StatusCard: React.FC<Props> = ({ status, title, message, ctaLabel, onContinue, onPress, onSubmit }) => {
+  const t = useOnboardingTheme();
+  const reduced = useReducedMotion();
+  const [submitted, setSubmitted] = useState(false);
+
+  const colorFor: Record<string, string> = {
+    success: t.colors.success,
+    warning: t.colors.warning,
+    error: t.colors.error,
+    info: t.colors.info,
+  };
+  const color = colorFor[status] ?? t.colors.info;
+
+  // Glyph pop + copy fade-up (final frame under reduce motion).
+  const popT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  const copyT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  useEffect(() => {
+    if (reduced) {
+      popT.setValue(1);
+      copyT.setValue(1);
+      return;
+    }
+    const anims = [
+      Animated.spring(popT, {
+        toValue: 1,
+        friction: STATUS_POP_SPRING.friction,
+        tension: STATUS_POP_SPRING.tension,
+        useNativeDriver: true,
+      }),
+      Animated.timing(copyT, {
+        toValue: 1,
+        duration: scaledMs(STATUS_COPY_MS),
+        delay: scaledMs(STATUS_COPY_STAGGER_MS),
+        easing: easeWire,
+        useNativeDriver: true,
+      }),
+    ];
+    anims.forEach((a) => a.start());
+    return () => anims.forEach((a) => a.stop());
+  }, [reduced, popT, copyT]);
+
+  const popScale = popT.interpolate({ inputRange: [0, 1], outputRange: [STATUS_POP_SCALE_FROM, 1] });
+  const copyRise = copyT.interpolate({ inputRange: [0, 1], outputRange: [10, 0] });
+
+  const handleContinue = useCallback(() => {
+    if (!submitted) {
+      setSubmitted(true);
+      if (onContinue) onContinue();
+      else if (onPress && ctaLabel) onPress(ctaLabel);
+      else if (onSubmit) onSubmit("continue");
+    }
+  }, [submitted, onContinue, onPress, onSubmit, ctaLabel]);
+
+  return (
+    <CardLayout
+      align="center"
+      footer={
+        ctaLabel ? (
+          <Button title={ctaLabel} onPress={handleContinue} variant="primary" disabled={submitted} />
+        ) : undefined
+      }
+    >
+      <View style={[styles.center, { gap: t.spacing.sm }]}>
+        <View style={[styles.titleRow, { gap: t.spacing.sm }]}>
+          <Animated.Text
+            style={[
+              headingStyle(t.fonts),
+              { color, opacity: popT, transform: [{ scale: popScale }] },
+            ]}
+          >
+            {STATUS_ICONS[status] ?? "·"}
+          </Animated.Text>
+          <Animated.Text
+            style={[
+              headingStyle(t.fonts),
+              { color, textAlign: "center", opacity: copyT, transform: [{ translateY: copyRise }] },
+            ]}
+          >
+            {title}
+          </Animated.Text>
+        </View>
+        {message ? (
+          <Animated.Text
+            style={[
+              bodyStyle(t.fonts),
+              {
+                color: t.colors.textMuted,
+                textAlign: "center",
+                opacity: copyT,
+                transform: [{ translateY: copyRise }],
+              },
+            ]}
+          >
+            {message}
+          </Animated.Text>
+        ) : null}
+      </View>
+    </CardLayout>
+  );
+};
+
+export const StatusCard: WireAIComponent = {
+  name: "StatusCard",
+  description:
+    "Use ONLY for real outcomes: booking confirmed, data saved, action completed. NEVER for 'you just viewed X' acknowledgments. Always include ctaLabel so the user can continue after seeing the status.",
+  component: React.memo(_StatusCard) as WireAIComponent["component"],
+  propsSchema: schema,
+};
+
+const styles = StyleSheet.create({
+  center: { width: "100%", alignItems: "center", justifyContent: "center" },
+  titleRow: { flexDirection: "row", alignItems: "center", justifyContent: "center" },
+});

package/src/cards/TextInputCard.tsx

@@ -0,0 +1,147 @@
+/**
+ * Themed TextInputCard — drop-in for the OSS SDK's TextInputCard. Same `name`,
+ * `propsSchema`, `defaultProps`, and `onSubmit(value: string)` contract. The input
+ * is themed and supports an optional inline error string (used by the kit's
+ * per-step validators — e.g. "username taken"), set via the `validationError` prop
+ * which the OnboardingFlow injects through callbackOverrides.
+ *
+ * Open-ended answers (goals, notes, "what would make this better") render a tall
+ * multi-line box by default so the user has room to actually write. Short fields
+ * (a name, a username) set `multiline: false` for the compact single-line height.
+ */
+import React, { useCallback, useState } from "react";
+import { StyleSheet, Text, TextInput, View, useWindowDimensions } from "react-native";
+import { z } from "zod";
+import type { InjectedProps, WireAIComponent } from "wireai-rn";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { bodyStyle, captionStyle } from "../theme/typography";
+import { Button } from "../components/Button";
+import { CardLayout } from "../components/CardLayout";
+
+const schema = z.object({
+  label: z.string().describe("Input field label / the question being asked"),
+  hint: z
+    .string()
+    .optional()
+    .describe(
+      "One short line under the question giving context: what the answer is used for or why you ask. Add it whenever the question alone might be unclear."
+    ),
+  placeholder: z
+    .string()
+    .optional()
+    .describe(
+      'A concrete example answer shown inside the box, phrased like a real user wrote it and starting with "e.g. ". ALWAYS provide one for open-ended questions: it shows the expected answer shape and inspires the user.'
+    ),
+  submitLabel: z.string().optional().describe("Submit button label, default: Submit"),
+  multiline: z
+    .boolean()
+    .optional()
+    .describe(
+      "Tall multi-line box for open-ended answers (goals, notes, feedback). Default true. Set false for a single-line field like a name or username."
+    ),
+  lines: z
+    .number()
+    .optional()
+    .describe("Approx visible rows when multiline (default 6). Height is capped at 40% of the screen."),
+});
+
+type Props = z.infer<typeof schema> &
+  InjectedProps & {
+    onSubmit?: (value: string) => void;
+    /**
+     * Inline error injected by OnboardingFlow when a validator rejects the value
+     * (e.g. username already taken). Re-enables the input so the user can edit.
+     */
+    validationError?: string;
+  };
+
+const _TextInputCard: React.FC<Props> = ({
+  label,
+  hint,
+  placeholder,
+  submitLabel = "Submit",
+  onSubmit,
+  validationError,
+  multiline = true,
+  lines = 6,
+}) => {
+  const t = useOnboardingTheme();
+  const { height: screenHeight } = useWindowDimensions();
+  const [value, setValue] = useState("");
+  const [submitted, setSubmitted] = useState(false);
+
+  // A validator rejection arrives as `validationError`; reopen the field so the
+  // user can fix their answer instead of being stuck on a submitted state.
+  const locked = submitted && !validationError;
+
+  // Multi-line free-text gets a generous box (~`lines` rows), capped at 40% of
+  // screen height so it stays comfortable on small devices. Single-line fields
+  // keep the compact 52pt height.
+  const APPROX_ROW_HEIGHT = 26;
+  const minHeight = multiline
+    ? Math.min(Math.max(lines, 4) * APPROX_ROW_HEIGHT + t.spacing.md * 2, screenHeight * 0.4)
+    : 52;
+
+  const handleSubmit = useCallback(() => {
+    if (value.trim() && onSubmit && !locked) {
+      setSubmitted(true);
+      onSubmit(value.trim());
+    }
+  }, [value, onSubmit, locked]);
+
+  return (
+    <CardLayout
+      title={label}
+      subtitle={hint}
+      footer={
+        <Button
+          title={submitLabel}
+          onPress={handleSubmit}
+          variant="primary"
+          disabled={!value.trim() || locked}
+        />
+      }
+    >
+      <View style={{ gap: t.spacing.sm }}>
+        <TextInput
+          value={value}
+          onChangeText={setValue}
+          placeholder={placeholder ?? ""}
+          placeholderTextColor={t.colors.textMuted}
+          editable={!locked}
+          multiline={multiline}
+          numberOfLines={multiline ? lines : 1}
+          textAlignVertical={multiline ? "top" : "center"}
+          style={[
+            bodyStyle(t.fonts),
+            styles.input,
+            {
+              color: t.colors.text,
+              backgroundColor: t.colors.surface,
+              borderRadius: t.radius.md,
+              borderColor: validationError ? t.colors.error : t.colors.border,
+              padding: t.spacing.md,
+              minHeight,
+            },
+          ]}
+        />
+        {validationError ? (
+          <Text style={[captionStyle(t.fonts), { color: t.colors.error }]}>{validationError}</Text>
+        ) : null}
+      </View>
+    </CardLayout>
+  );
+};
+
+export const TextInputCard: WireAIComponent = {
+  name: "TextInputCard",
+  description:
+    "Use when the user needs to type a free-text answer: an open-ended goal, notes, feedback, a name, a destination, a search query. Multi-line by default (great for open-ended goals); set multiline:false for a short single-line field like a name. Use NumberStepperCard for numeric ranges with known bounds.",
+  component: React.memo(_TextInputCard) as WireAIComponent["component"],
+  propsSchema: schema,
+  defaultProps: { submitLabel: "Submit", multiline: true, lines: 6 },
+};
+
+const styles = StyleSheet.create({
+  input: { borderWidth: 1 },
+});

package/src/cards/index.ts

@@ -0,0 +1,23 @@
+/**
+ * onboardingComponents — the constrained set of themed cards the kit registers
+ * with the SDK. The backend's `allowed_components` must be a subset of these
+ * names so every card the agent asks for has a themed renderer.
+ */
+import type { WireAIComponent } from "wireai-rn";
+import { ChipSelectCard } from "./ChipSelectCard";
+import { TextInputCard } from "./TextInputCard";
+import { SelectionCard } from "./SelectionCard";
+import { StatusCard } from "./StatusCard";
+import { NumberStepperCard } from "./NumberStepperCard";
+import { InterstitialCard } from "./InterstitialCard";
+
+export { ChipSelectCard, TextInputCard, SelectionCard, StatusCard, NumberStepperCard, InterstitialCard };
+
+export const onboardingComponents: WireAIComponent[] = [
+  ChipSelectCard,
+  TextInputCard,
+  SelectionCard,
+  StatusCard,
+  NumberStepperCard,
+  InterstitialCard,
+];

package/src/coachmarks/CoachmarkOverlayHost.tsx

@@ -0,0 +1,44 @@
+import React from "react";
+
+import { useCoachmarkOverlay } from "./coachmarkOverlayStore";
+import { SpotlightOverlay } from "./SpotlightOverlay";
+
+export interface CoachmarkOverlayHostProps {
+  /** Ring/tooltip accent; defaults to the onboarding theme's `primary`. */
+  accentColor?: string;
+  /** Text/icon color on the accent surface; defaults to the theme's `onPrimary`. */
+  accentTextColor?: string;
+}
+
+/**
+ * Mounts once at the app root (rendered by CoachmarkProvider as a sibling of the
+ * app tree) so the blur + spotlight paint OVER the bottom tab bar — which
+ * react-navigation renders above screen components, out of reach of any
+ * screen-level overlay. Renders nothing until a step is active.
+ */
+const CoachmarkOverlayHostComponent: React.FC<CoachmarkOverlayHostProps> = ({
+  accentColor,
+  accentTextColor,
+}) => {
+  const active = useCoachmarkOverlay();
+
+  if (!active) return null;
+
+  return (
+    <SpotlightOverlay
+      message={active.message}
+      targetRect={active.targetRect}
+      gesture={active.gesture}
+      placement={active.placement}
+      onEngage={active.onEngage}
+      onDismiss={active.onDismiss}
+      accentColor={accentColor}
+      accentTextColor={accentTextColor}
+    />
+  );
+};
+
+export const CoachmarkOverlayHost = React.memo(CoachmarkOverlayHostComponent);
+CoachmarkOverlayHost.displayName = "CoachmarkOverlayHost";
+
+export default CoachmarkOverlayHost;