@wireai/activation 0.8.0 → 0.9.1

package/src/icons/expoIcons.ts

@@ -0,0 +1,165 @@
+/**
+ * expoIcons — resolve an `@expo/vector-icons` family, lazily and optionally.
+ *
+ * ── WHY THIS DOES NOT BREAK THE NO-NATIVE-DEPENDENCY POLICY ──────────────────────────────
+ *
+ * The policy (see `questionnaire/QuestionnaireGate.tsx`'s back-chevron note, `AnimatedSparkle`,
+ * `coachmarks/GestureHint`, `cards/StatusCard`'s Unicode STATUS_ICONS) says: no vector library
+ * is worth FORCING EVERY HOST INTO A NATIVE REBUILD. Read it precisely — what it forbids is
+ * forcing hosts, not the existence of an icon.
+ *
+ * `@expo/vector-icons` is an OPTIONAL peer:
+ *
+ *   • A host WITHOUT it installs the kit fine (optional peer → npm never fetches it) and renders
+ *     fine (icon → null, layout unchanged). To BUNDLE fine it must let Metro know the module is
+ *     allowed to be missing — see "OPTIONALITY IS A BUILD-TIME CONTRACT" below.
+ *   • A host WITH it gets real brand icons. Both live host apps already ship it
+ *     (`@expo/vector-icons ^15.0.3`), so neither needs a rebuild — which matters because
+ *     neither can be force-updated: both ship new store builds only and never OTA.
+ *   • A host that wants neither can override every name with its own artwork through the
+ *     `icons` registry, so the library is never on the critical path at all.
+ *
+ * ── THE SPECIFIER MUST BE A STRING LITERAL — THIS IS THE WHOLE BUG ───────────────────────
+ *
+ * DO NOT "restore" the old `const req = require; req(moduleName)` shape. It could never work,
+ * and it shipped broken in 0.8.0. What that shape actually did, proven in a real `expo export`
+ * bundle and in Expo SDK 55's runtime:
+ *
+ *   1. Metro collects dependencies STATICALLY, by matching a call whose callee is literally the
+ *      identifier `require` and whose argument is a STRING LITERAL. Aliasing `require` to a local
+ *      hid the call from the collector, so this module's dependencyMap was emitted EMPTY (`[]`)
+ *      and `@expo/vector-icons` was never put in the bundle at all.
+ *   2. At runtime the alias did NOT point at Node's `require`. Metro renames the free `require`
+ *      identifier to the module factory's require param, so `req` WAS `metroRequire`, whose
+ *      module registry is keyed by NUMERIC module ids. Handing it the string "@expo/vector-icons"
+ *      could never match a key, so it threw `Requiring unknown module "@expo/vector-icons"` —
+ *      even in a bundle that contained the module.
+ *   3. That throw never reached the `catch` below. Metro's own `guardedLoadModule` wraps the
+ *      load, catches the error FIRST, and routes it to `global.ErrorUtils.reportFatalError(e)`
+ *      instead of rethrowing (Expo SDK 55: `@expo/cli/build/metro-require/require.js:151-165`).
+ *      So the call returned `undefined` — icon silently null — AND logged a red fatal error. A
+ *      try/catch cannot guard a require that Metro never lets throw.
+ *
+ * A LITERAL `require("@expo/vector-icons")` is collected, is bundled, and resolves SYNCHRONOUSLY
+ * through the numeric dependencyMap — the same reason `reviews/storeReview.ts`'s literal
+ * `await import("expo-store-review")` has always worked. (The old comment here claimed the alias
+ * worked "exactly like expo-store-review". It was the opposite: storeReview's specifier is a
+ * literal, and that is precisely why it resolves and this one did not.)
+ *
+ * ── OPTIONALITY IS A BUILD-TIME CONTRACT, AND THE TRY/CATCH IS LOAD-BEARING ──────────────
+ *
+ * Metro has NO runtime resolution: every specifier is resolved when the bundle is built. It does
+ * have a real optional-dependency mechanism, and it needs BOTH halves of what is written below:
+ * a LITERAL specifier (so the dep is collected at all) AND the call inside a TRY/CATCH — that is
+ * literally how Metro marks a dependency `isOptional`. When the peer is absent, Metro then puts
+ * `null` in this module's dependencyMap and `metroRequire(null, "@expo/vector-icons")` throws
+ * "Cannot find module" from its own `moduleId === null` branch, BEFORE `guardedLoadModule` — so
+ * unlike the string-id path in the autopsy above, that throw really does land in the catch below.
+ * So do NOT "simplify" the try/catch away: it is what keeps the peer optional, not just tidy.
+ *
+ * That mechanism rides on the transformer's `allowOptionalDependencies`, which Expo enables by
+ * default but bare `metro-config` defaults to FALSE. For hosts in the second camp, the kit ships
+ * a safety net: `withWireOnboarding` (metro/index.js) installs a `resolveRequest` that maps an
+ * absent optional peer to an EMPTY module, landing on exactly the degradation path below (no
+ * families on the namespace → `undefined` → icon renders null).
+ */
+import type { WireIconFamily } from "./vocabulary";
+
+// Metro injects a module-scoped `require`; it is ABSENT in a pure-ESM runtime (the kit's own
+// tests run under `node --test` as ESM). Declared locally so this type-checks without ambient
+// Node types; the `typeof` guard keeps the reference ESM-safe.
+declare const require: ((id: string) => unknown) | undefined;
+
+/** A `require`-like resolver. Injectable in tests; production uses the guarded literal require. */
+export type OptionalRequire = (moduleName: string) => unknown;
+
+/**
+ * The minimal shape the kit uses from a vector-icons family. A COMPONENT TYPE, not a plain
+ * function: these are real React components (createIconSet output) and must be mounted via
+ * JSX/createElement, never invoked directly — calling one bypasses the reconciler and breaks
+ * the moment the family uses hooks or is a class.
+ */
+export type IconComponent = import("react").ComponentType<{
+  name: string;
+  size?: number;
+  color?: string;
+  allowFontScaling?: boolean;
+}>;
+
+/**
+ * The production resolver. The specifier is a LITERAL so Metro collects it (see the header); the
+ * `moduleName` parameter exists only to keep the `OptionalRequire` seam shape, so anything other
+ * than the one module this file owns resolves to undefined.
+ */
+const runtimeRequire: OptionalRequire = (moduleName) => {
+  if (moduleName !== "@expo/vector-icons") return undefined;
+  if (typeof require !== "function") return undefined;
+  try {
+    return require("@expo/vector-icons");
+  } catch {
+    return undefined;
+  }
+};
+
+/** Read a module's `default` (Expo modules are consumed as default exports) or the namespace. */
+const interop = (mod: unknown): Record<string, unknown> | undefined => {
+  if (!mod || typeof mod !== "object") return undefined;
+  const def = (mod as { default?: unknown }).default;
+  // `@expo/vector-icons` exposes the families as NAMED exports; prefer the namespace when it
+  // already carries them, and only fall back to `default` for a CJS-interop wrapper.
+  const ns = mod as Record<string, unknown>;
+  if (ns.MaterialCommunityIcons || ns.Ionicons) return ns;
+  if (def && typeof def === "object") return def as Record<string, unknown>;
+  return ns;
+};
+
+/**
+ * Narrow an unknown export to something mountable. A vector-icons family is either a function
+ * component or a class (`createIconSet` has returned both across versions), and React.memo /
+ * forwardRef wrappers are objects — so accept an object carrying a `$$typeof` too, and reject
+ * anything else rather than handing the reconciler a non-component.
+ */
+const asComponent = (value: unknown): IconComponent | undefined => {
+  if (typeof value === "function") return value as IconComponent;
+  if (value && typeof value === "object" && "$$typeof" in (value as object)) {
+    return value as IconComponent;
+  }
+  return undefined;
+};
+
+/**
+ * Module-level memo. `null` = "we looked and it is not there" (distinct from "not looked yet"),
+ * so an absent peer costs exactly one failed require per process, not one per rendered icon.
+ */
+let cached: Record<string, unknown> | null | undefined;
+
+/** Reset the memo. TEST-ONLY seam — production never calls it. */
+export const resetIconModuleCache = (): void => {
+  cached = undefined;
+};
+
+/**
+ * Resolve one icon family component, or undefined when the peer is absent/unresolvable.
+ * Never throws: an icon is decorative, so it must never be able to break a card.
+ *
+ * `requireModule` is injectable so tests can exercise BOTH the found and absent paths without
+ * installing the native peer (same convention as `detectAppVersion`).
+ */
+export const resolveIconFamily = (
+  family: WireIconFamily,
+  requireModule: OptionalRequire = runtimeRequire,
+): IconComponent | undefined => {
+  try {
+    if (cached === undefined || requireModule !== runtimeRequire) {
+      const resolved = interop(requireModule("@expo/vector-icons"));
+      // Don't poison the module memo from an injected test require.
+      if (requireModule === runtimeRequire) cached = resolved ?? null;
+      if (!resolved) return undefined;
+      return asComponent(resolved[family]);
+    }
+    if (cached === null) return undefined;
+    return asComponent(cached[family]);
+  } catch {
+    return undefined;
+  }
+};

package/src/icons/index.ts

@@ -0,0 +1,18 @@
+/**
+ * The icon module — a named semantic vocabulary the AI emits, resolved to real glyphs through
+ * an OPTIONAL peer, with a host override registry in front and a no-op behind. See
+ * `vocabulary.ts` for the contract and `expoIcons.ts` for why the optional peer honors the
+ * kit's no-forced-native-dependency policy rather than breaking it.
+ */
+export { WireIcon } from "./WireIcon";
+export type { WireIconProps } from "./WireIcon";
+export { IconRegistryProvider, useHostIcon } from "./IconRegistry";
+export type { WireIconRegistry, IconRegistryProviderProps } from "./IconRegistry";
+export {
+  WIRE_ICON_GLYPHS,
+  WIRE_ICON_NAMES,
+  lookupIconGlyph,
+} from "./vocabulary";
+export type { WireIconName, WireIconFamily, WireIconGlyph } from "./vocabulary";
+export { resolveIconFamily, resetIconModuleCache } from "./expoIcons";
+export type { OptionalRequire, IconComponent } from "./expoIcons";

package/src/icons/vocabulary.ts

@@ -0,0 +1,154 @@
+/**
+ * The Wire icon VOCABULARY — the stable, semantic contract between the AI and the kit.
+ *
+ * The model emits a plain semantic string (`"instagram"`, `"friend"`, `"wedding"`), never a
+ * raw icon-library glyph name. That indirection is the whole point:
+ *
+ *   • The model is never coupled to a library version. `@expo/vector-icons` renaming a glyph,
+ *     or a host swapping the library out for brand SVGs, changes THIS map — not the prompt,
+ *     not the server, and not a single stored answer.
+ *   • A host can override any name with its own artwork (see `IconRegistry`), so brand icons
+ *     need no kit change.
+ *   • An unknown name degrades to no icon (see `WireIcon`), which is why the vocabulary can
+ *     grow without a coordinated kit+server release.
+ *
+ * `WIRE_ICON_NAMES` is exported so the server/AI side can be taught the list verbatim — paste
+ * it into the prompt as the allowed `icon` values. Keep names SEMANTIC (what the option means)
+ * rather than visual (what the glyph looks like): the model reasons about meaning.
+ *
+ * Every glyph below was verified to exist in the `@expo/vector-icons` 15.0.3 glyphmaps that
+ * both live host apps already ship. MaterialCommunityIcons is the default family (the broadest
+ * single set); Ionicons covers the few brand logos MCI lacks (TikTok, Discord).
+ */
+
+/** The icon families this kit resolves out of `@expo/vector-icons`. Both are root exports. */
+export type WireIconFamily = "MaterialCommunityIcons" | "Ionicons";
+
+/** One vocabulary entry: the concrete glyph a semantic name resolves to. */
+export interface WireIconGlyph {
+  family: WireIconFamily;
+  /** The library's own glyph name — an INTERNAL detail. The AI never sees or emits this. */
+  name: string;
+}
+
+/**
+ * The semantic name → concrete glyph map. Grouped by the onboarding questions these actually
+ * serve: acquisition channels ("where did you hear about us"), intent/occasion ("what brings
+ * you here"), and a general-purpose set for everything else.
+ */
+export const WIRE_ICON_GLYPHS = {
+  // ── Acquisition channels ("where did you hear about us?") ──────────────────
+  instagram: { family: "MaterialCommunityIcons", name: "instagram" },
+  tiktok: { family: "Ionicons", name: "logo-tiktok" },
+  youtube: { family: "MaterialCommunityIcons", name: "youtube" },
+  facebook: { family: "MaterialCommunityIcons", name: "facebook" },
+  twitter: { family: "MaterialCommunityIcons", name: "twitter" },
+  reddit: { family: "MaterialCommunityIcons", name: "reddit" },
+  linkedin: { family: "MaterialCommunityIcons", name: "linkedin" },
+  discord: { family: "Ionicons", name: "logo-discord" },
+  whatsapp: { family: "MaterialCommunityIcons", name: "whatsapp" },
+  twitch: { family: "MaterialCommunityIcons", name: "twitch" },
+  snapchat: { family: "MaterialCommunityIcons", name: "snapchat" },
+  pinterest: { family: "MaterialCommunityIcons", name: "pinterest" },
+  google: { family: "MaterialCommunityIcons", name: "google" },
+  search: { family: "MaterialCommunityIcons", name: "magnify" },
+  friend: { family: "MaterialCommunityIcons", name: "account-heart" },
+  podcast: { family: "MaterialCommunityIcons", name: "podcast" },
+  blog: { family: "MaterialCommunityIcons", name: "post" },
+  newsletter: { family: "MaterialCommunityIcons", name: "email-outline" },
+  news: { family: "MaterialCommunityIcons", name: "newspaper" },
+  "app-store": { family: "MaterialCommunityIcons", name: "apple" },
+  ad: { family: "MaterialCommunityIcons", name: "bullhorn" },
+
+  // ── Intent / occasion ("what brings you here?") ────────────────────────────
+  wedding: { family: "MaterialCommunityIcons", name: "ring" },
+  birthday: { family: "MaterialCommunityIcons", name: "cake-variant" },
+  baby: { family: "MaterialCommunityIcons", name: "baby-carriage" },
+  travel: { family: "MaterialCommunityIcons", name: "airplane" },
+  work: { family: "MaterialCommunityIcons", name: "briefcase" },
+  celebration: { family: "MaterialCommunityIcons", name: "party-popper" },
+  store: { family: "MaterialCommunityIcons", name: "storefront" },
+  school: { family: "MaterialCommunityIcons", name: "school" },
+  team: { family: "MaterialCommunityIcons", name: "account-multiple" },
+  growth: { family: "MaterialCommunityIcons", name: "trending-up" },
+
+  // ── General purpose ────────────────────────────────────────────────────────
+  sparkle: { family: "MaterialCommunityIcons", name: "star-four-points" },
+  heart: { family: "MaterialCommunityIcons", name: "heart" },
+  star: { family: "MaterialCommunityIcons", name: "star" },
+  fire: { family: "MaterialCommunityIcons", name: "fire" },
+  target: { family: "MaterialCommunityIcons", name: "target" },
+  trophy: { family: "MaterialCommunityIcons", name: "trophy" },
+  rocket: { family: "MaterialCommunityIcons", name: "rocket-launch" },
+  clock: { family: "MaterialCommunityIcons", name: "clock-outline" },
+  calendar: { family: "MaterialCommunityIcons", name: "calendar-star" },
+  camera: { family: "MaterialCommunityIcons", name: "camera" },
+  image: { family: "MaterialCommunityIcons", name: "image" },
+  video: { family: "MaterialCommunityIcons", name: "video" },
+  mic: { family: "MaterialCommunityIcons", name: "microphone" },
+  music: { family: "MaterialCommunityIcons", name: "music" },
+  book: { family: "MaterialCommunityIcons", name: "book-open-variant" },
+  food: { family: "MaterialCommunityIcons", name: "silverware-fork-knife" },
+  coffee: { family: "MaterialCommunityIcons", name: "coffee" },
+  fitness: { family: "MaterialCommunityIcons", name: "dumbbell" },
+  health: { family: "MaterialCommunityIcons", name: "heart-pulse" },
+  meditation: { family: "MaterialCommunityIcons", name: "meditation" },
+  sleep: { family: "MaterialCommunityIcons", name: "sleep" },
+  brain: { family: "MaterialCommunityIcons", name: "brain" },
+  idea: { family: "MaterialCommunityIcons", name: "lightbulb-on" },
+  money: { family: "MaterialCommunityIcons", name: "cash" },
+  shopping: { family: "MaterialCommunityIcons", name: "cart" },
+  gift: { family: "MaterialCommunityIcons", name: "gift" },
+  home: { family: "MaterialCommunityIcons", name: "home" },
+  car: { family: "MaterialCommunityIcons", name: "car" },
+  pet: { family: "MaterialCommunityIcons", name: "paw" },
+  plant: { family: "MaterialCommunityIcons", name: "sprout" },
+  sun: { family: "MaterialCommunityIcons", name: "white-balance-sunny" },
+  moon: { family: "MaterialCommunityIcons", name: "weather-night" },
+  globe: { family: "MaterialCommunityIcons", name: "earth" },
+  "map-pin": { family: "MaterialCommunityIcons", name: "map-marker" },
+  compass: { family: "MaterialCommunityIcons", name: "compass" },
+  flag: { family: "MaterialCommunityIcons", name: "flag" },
+  bookmark: { family: "MaterialCommunityIcons", name: "bookmark" },
+  bell: { family: "MaterialCommunityIcons", name: "bell" },
+  mail: { family: "MaterialCommunityIcons", name: "email" },
+  phone: { family: "MaterialCommunityIcons", name: "phone" },
+  chat: { family: "MaterialCommunityIcons", name: "chat" },
+  user: { family: "MaterialCommunityIcons", name: "account" },
+  users: { family: "MaterialCommunityIcons", name: "account-group" },
+  settings: { family: "MaterialCommunityIcons", name: "cog" },
+  tools: { family: "MaterialCommunityIcons", name: "tools" },
+  puzzle: { family: "MaterialCommunityIcons", name: "puzzle" },
+  chart: { family: "MaterialCommunityIcons", name: "chart-line" },
+  shield: { family: "MaterialCommunityIcons", name: "shield-check" },
+  lock: { family: "MaterialCommunityIcons", name: "lock" },
+  cloud: { family: "MaterialCommunityIcons", name: "cloud" },
+  pencil: { family: "MaterialCommunityIcons", name: "pencil" },
+  check: { family: "MaterialCommunityIcons", name: "check-circle" },
+  plus: { family: "MaterialCommunityIcons", name: "plus-circle" },
+  question: { family: "MaterialCommunityIcons", name: "help-circle" },
+  other: { family: "MaterialCommunityIcons", name: "dots-horizontal-circle" },
+} as const satisfies Record<string, WireIconGlyph>;
+
+/** A name in the vocabulary. The card schemas accept any string and degrade — see `WireIcon`. */
+export type WireIconName = keyof typeof WIRE_ICON_GLYPHS;
+
+/**
+ * Every semantic name, as a plain array — the list to paste into the server/AI prompt as the
+ * allowed `icon` values. Sorted for a stable, diffable prompt.
+ */
+export const WIRE_ICON_NAMES: readonly string[] = Object.keys(WIRE_ICON_GLYPHS).sort();
+
+/**
+ * Look up a semantic name. Returns undefined for anything outside the vocabulary.
+ *
+ * The OWN-property check is load-bearing, not defensive noise: the name comes from an LLM, and
+ * a plain object lookup answers `"toString"` / `"constructor"` / `"valueOf"` with an inherited
+ * `Object.prototype` member. That would hand back a function where a `{family, name}` is
+ * expected — a non-glyph masquerading as one. Caught by the vocabulary canary.
+ */
+export const lookupIconGlyph = (name: string | undefined): WireIconGlyph | undefined => {
+  if (!name) return undefined;
+  if (!Object.prototype.hasOwnProperty.call(WIRE_ICON_GLYPHS, name)) return undefined;
+  return (WIRE_ICON_GLYPHS as Record<string, WireIconGlyph>)[name];
+};

package/src/index.ts

@@ -52,11 +52,31 @@ export {
   ChipSelectCard,
   TextInputCard,
   SelectionCard,
+  CardGridSelectCard,
   StatusCard,
   NumberStepperCard,
   InterstitialCard,
   onboardingComponents,
 } from "./cards";
+export type { CardOption } from "./cards";
+
+// ─── Icons (semantic vocabulary → optional @expo/vector-icons → nothing) ──────
+// WIRE_ICON_NAMES is the list to paste into the server/AI prompt as the allowed `icon` values.
+export {
+  WireIcon,
+  IconRegistryProvider,
+  useHostIcon,
+  WIRE_ICON_GLYPHS,
+  WIRE_ICON_NAMES,
+  lookupIconGlyph,
+} from "./icons";
+export type {
+  WireIconProps,
+  WireIconRegistry,
+  WireIconName,
+  WireIconFamily,
+  WireIconGlyph,
+} from "./icons";
 
 // ─── Flow internals (advanced) ────────────────────────────────────────────────
 export { OnboardingFlow } from "./OnboardingFlow";