@wireai/activation 0.14.1 → 0.14.3

package/src/showcase/FeatureShowcase.tsx

@@ -1,8 +1,8 @@
-import Onboarding, {
-  type OnboardingColors,
-  type OnboardingFonts,
-  type OnboardingProps,
-  type OnboardingStep,
+import type {
+  OnboardingColors,
+  OnboardingFonts,
+  OnboardingProps,
+  OnboardingStep,
 } from "@blazejkustra/react-native-onboarding";
 import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { type ImageSourcePropType, StyleSheet, View } from "react-native";
@@ -12,6 +12,7 @@ import { hasSeenGate, markSeenGate, showcaseGateKey } from "../coachmarks/runtim
 import { useResolvedFeatures } from "../features/WireFeaturesProvider";
 import { useOnboardingTheme } from "../theme/ThemeContext";
 import type { OnboardingTheme } from "../theme/types";
+import { resolveShowcaseOnboarding } from "./blazejOnboarding";
 import { showcaseColorsFromTheme, showcasePanelBackground } from "./showcaseColors";
 import type { FeatureShowcaseProps } from "./types";
 
@@ -47,6 +48,13 @@ const mergeThemeOver = (
  *
  * When the gate says "seen", it renders nothing and calls `onDone` from an
  * effect (never during render).
+ *
+ * The underlying package is an OPTIONAL peer, resolved through the guarded lazy
+ * require in `blazejOnboarding.ts` rather than a static import, so the showcase
+ * subpath builds on a host that never installed it. Absent, this takes the SAME
+ * path as the kill switch — render null, call `onDone`, write no gate — so the
+ * host's flow always advances and the showcase still plays once if the peer is
+ * added later.
  */
 const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
   config,
@@ -71,14 +79,20 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
   const flags = useResolvedFeatures({ flags: features, config: featuresConfig });
   const disabled = !flags.showcase.enabled;
 
+  // The optional pager peer. Resolved once, on first render, instead of at module scope — so
+  // merely importing this file (and thus the showcase subpath) never needs it. Absent → treated
+  // exactly like the kill switch below: no render, no gate write, `onDone` from the effect.
+  const Onboarding = useMemo(() => resolveShowcaseOnboarding(), []);
+
   const gateKey = showcaseGateKey(config.id);
   const seen = useMemo(
     () => hasSeenGate(gateKey, storage, isTesting),
     [gateKey, storage, isTesting],
   );
-  // Either already-seen OR feature-disabled short-circuits the showcase. Only the seen path is a
-  // gate write (in `finish`); the disabled path never persists, so it replays when re-enabled.
-  const skip = seen || disabled;
+  // Already-seen, feature-disabled OR the peer missing short-circuits the showcase. Only the seen
+  // path is a gate write (in `finish`); the other two never persist, so the showcase replays once
+  // the feature is re-enabled or the peer is installed.
+  const skip = seen || disabled || !Onboarding;
 
   const doneRef = useRef(false);
   const finish = useCallback(() => {
@@ -177,7 +191,9 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
     [t],
   );
 
-  if (skip) return null;
+  // `!Onboarding` is already folded into `skip`; it is repeated here so the narrowing is explicit
+  // to the reader and to the compiler at the JSX below.
+  if (skip || !Onboarding) return null;
 
   const activeGesture = config.slides[activeIndex]?.gesture;
   // Same rule as the coachmark path: tap / double-tap slides show no glyph.

package/src/showcase/blazejOnboarding.ts

@@ -0,0 +1,136 @@
+/**
+ * blazejOnboarding — resolve `@blazejkustra/react-native-onboarding`, lazily and optionally.
+ *
+ * ── WHY THIS DOES NOT BREAK THE NO-NATIVE-DEPENDENCY POLICY ──────────────────────────────
+ *
+ * `@blazejkustra/react-native-onboarding` is an OPTIONAL peer of the showcase subpath — it is the
+ * slide pager `FeatureShowcase` wraps. Before this file, `FeatureShowcase.tsx` imported its default
+ * export at module scope, and `showcase/index.ts` re-exports the component with no wildcard escape,
+ * so importing ANYTHING from `@wireai/activation/showcase` (even `selectShowcaseSlides`) dragged
+ * the peer in, and a host that skipped the "optional" peer hit a Metro resolution failure. This
+ * resolver removes that static edge. Same class and same shape as the 0.14.2 `expo-blur` fix
+ * (`coachmarks/expoBlur.ts`), whose header carries the reasoning in full.
+ *
+ * The TYPES stay statically imported on purpose: a type-only import is erased by every toolchain
+ * (babel, esbuild and sucrase all drop it), so it creates no runtime edge and no bundle dependency,
+ * and `showcaseColors.ts` already relies on exactly that.
+ *
+ * ── THE SPECIFIER MUST BE A STRING LITERAL, INSIDE A TRY/CATCH ───────────────────────────
+ *
+ * Metro collects dependencies statically and matches only a call whose callee is literally the
+ * identifier `require` and whose argument is literally a string; the try/catch around it is what
+ * marks the dependency `isOptional`. Both halves are load-bearing — see `icons/expoIcons.ts` for
+ * the full autopsy of the 0.8.0 shape that aliased the callee and was collected nowhere.
+ *
+ * ── THE DEGRADE ─────────────────────────────────────────────────────────────────────────
+ *
+ * Absent → `FeatureShowcase` renders null and calls `onDone` from an effect, which is the SAME path
+ * the feature kill switch already takes. The host's flow always advances (a showcase that cannot
+ * render must never strand the user on a blank screen), and the seen-gate is deliberately NOT
+ * written, so installing the peer later still plays the showcase once.
+ */
+import type { ComponentType } from "react";
+
+import type { OnboardingProps } from "@blazejkustra/react-native-onboarding";
+
+// 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 pager component `FeatureShowcase` wraps. */
+export type OnboardingComponent = ComponentType<OnboardingProps>;
+
+const MODULE_NAME = "@blazejkustra/react-native-onboarding";
+
+/**
+ * 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 !== MODULE_NAME) return undefined;
+  if (typeof require !== "function") return undefined;
+  try {
+    return require("@blazejkustra/react-native-onboarding");
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * TEST-ONLY seam. `FeatureShowcase`'s public props are frozen, so it cannot take a `requireModule`
+ * the way `WireIcon` does — this lets a component render exercise the PRESENT path without the peer
+ * installed. Production never sets it; `runtimeRequire` is the only resolver.
+ */
+let testRequire: OptionalRequire | undefined;
+export const __setShowcaseOnboardingRequireForTests = (fn: OptionalRequire | undefined): void => {
+  testRequire = fn;
+  cached = undefined;
+};
+
+/**
+ * Read the component off the module. The package ships it as a DEFAULT export; a CJS build may put
+ * the component directly on `module.exports` instead, so both shapes are accepted.
+ */
+const interop = (mod: unknown): unknown => {
+  if (typeof mod === "function") return mod;
+  if (!mod || typeof mod !== "object") return undefined;
+  const ns = mod as Record<string, unknown>;
+  if (ns.default) return ns.default;
+  // `module.exports = forwardRef(...)`: the component IS the namespace, and it is an object rather
+  // than a function, so it would slip past the check above.
+  if ("$$typeof" in ns) return ns;
+  return undefined;
+};
+
+/**
+ * Narrow an unknown export to something mountable: a real component (function or class) or a
+ * React.memo / forwardRef wrapper (an object carrying `$$typeof`). Reject anything else rather than
+ * handing the reconciler a non-component.
+ */
+const asComponent = (value: unknown): OnboardingComponent | undefined => {
+  if (typeof value === "function") return value as OnboardingComponent;
+  if (value && typeof value === "object" && "$$typeof" in (value as object)) {
+    return value as OnboardingComponent;
+  }
+  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 showcase mount.
+ */
+let cached: OnboardingComponent | null | undefined;
+
+/** Reset the memo. TEST-ONLY seam — production never calls it. */
+export const resetShowcaseOnboardingCache = (): void => {
+  cached = undefined;
+};
+
+/**
+ * Resolve the pager component, or undefined when the peer is absent/unresolvable. Never throws: an
+ * absent showcase must advance the host's flow, never break it.
+ *
+ * `requireModule` is injectable so tests can exercise BOTH the found and absent paths without
+ * installing the peer (same convention as `resolveBlurView` / `resolveIconFamily`).
+ */
+export const resolveShowcaseOnboarding = (
+  requireModule: OptionalRequire = testRequire ?? runtimeRequire,
+): OnboardingComponent | undefined => {
+  try {
+    if (cached === undefined || requireModule !== runtimeRequire) {
+      const component = asComponent(interop(requireModule(MODULE_NAME)));
+      // Don't poison the module memo from an injected test require.
+      if (requireModule === runtimeRequire) cached = component ?? null;
+      return component;
+    }
+    if (cached === null) return undefined;
+    return cached;
+  } catch {
+    return undefined;
+  }
+};

package/src/showcase/index.ts

@@ -2,10 +2,14 @@
  * @wireai/activation/showcase — the pre-onboarding feature showcase ("app intro").
  *
  * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-
- * free: importing this pulls in the optional peer
- * `@blazejkustra/react-native-onboarding` (and, transitively via GestureHint,
- * `react-native-reanimated`). The app supplies a declarative ShowcaseConfig; the
- * kit bakes in the Wire theme + optional per-slide gesture hand and gates once.
+ * free. Importing this pulls in NO native peer (0.14.3): the pager
+ * `@blazejkustra/react-native-onboarding` is reached through the guarded lazy
+ * require in `blazejOnboarding.ts`, and the transitive edge through GestureHint
+ * to `react-native-reanimated` is guarded the same way in `coachmarks/reanimated.ts`.
+ * Without the pager the showcase renders null and calls `onDone` so the host's
+ * flow advances; without reanimated the gesture glyph renders static. The app
+ * supplies a declarative ShowcaseConfig; the kit bakes in the Wire theme +
+ * optional per-slide gesture hand and gates once.
  *
  *   import { FeatureShowcase, selectShowcaseSlides } from "@wireai/activation/showcase";
  */