@wireai/activation 0.1.0

package/dist/coachmarks/index.d.ts

@@ -0,0 +1,352 @@
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+import { W as WireFeatures, a as WireFeaturesConfig } from '../types-CMuOexw0.js';
+import { C as CoachmarkStorage, a as CoachmarkStep, G as GestureKind, T as TargetRect, P as Placement } from '../types-GL_hQ0TN.js';
+import { View } from 'react-native';
+
+interface CoachmarkProviderProps {
+    /**
+     * SYNCHRONOUS gate storage (MMKV-friendly). Reads must not be async or a ring
+     * would flash before the "already seen" gate resolves. See CoachmarkStorage.
+     */
+    storage: CoachmarkStorage;
+    /**
+     * QA replay switch. When true, every seen-gate reads as unseen AND seen-writes
+     * are suppressed, so every tour + showcase replays on each mount. Flip ONE
+     * boolean to re-see the whole coachmark surface.
+     */
+    isTestingCoachmark?: boolean;
+    /** Ring + tooltip color for every tour. Defaults to the onboarding theme's `primary`. */
+    accentColor?: string;
+    /**
+     * Text/icon color on the accent surface (e.g. the tooltip's CTA label).
+     * Defaults to the onboarding theme's `onPrimary`.
+     */
+    accentTextColor?: string;
+    /**
+     * OPTIONAL feature-flag wiring. When `flags.coachmarks.enabled` is false, every tour + overlay
+     * request becomes a silent no-op (once-gates are NOT consumed, so re-enabling replays). Provide
+     * pre-resolved `features`, OR a `featuresConfig` (serverUrl + apiKey) to lazily fetch once, OR
+     * mount a `WireFeaturesProvider` above (context is read automatically). Omit all three and
+     * coachmarks stay on (fail-open) — zero behavior change for hosts that never adopt flags.
+     */
+    features?: WireFeatures;
+    /** Lazy-fetch config for the flags, used when `features` is absent and no provider is above. */
+    featuresConfig?: WireFeaturesConfig;
+    children: React__default.ReactNode;
+}
+/**
+ * Mount ONCE at the app root — wrap it around (or just inside) your
+ * NavigationContainer so the overlay host is a root-level sibling of the whole
+ * app tree. That placement is what lets a ring + blur paint ABOVE the bottom tab
+ * bar, which react-navigation renders over screen components.
+ *
+ * It feeds the sync storage + testing flag into the engine's module-level
+ * singletons so `useCoachmarkTour` / `useCoachmarkAnchor` work from anywhere in
+ * the tree without prop-drilling, then renders the overlay host as a sibling
+ * after `children` (the SpotlightOverlay self-positions absolute-fill at
+ * zIndex/elevation 9999).
+ *
+ * The singletons are set during render (not in an effect) so a child's mount
+ * effect — which runs BEFORE this parent's effects — already sees the storage
+ * when it reads its gate.
+ */
+declare const CoachmarkProvider: React__default.FC<CoachmarkProviderProps>;
+
+/**
+ * Makes any element ringable by a coachmark tour. Attach the returned ref to a
+ * plain RN View wrapping the target (use `collapsable={false}` so the native
+ * node survives for measurement):
+ *
+ *   const filterAnchor = useCoachmarkAnchor("filter_icon");
+ *   <View ref={filterAnchor} collapsable={false}>{button}</View>
+ *
+ * The app decides which ids exist and where they live; the kit measures them at
+ * step time via `measureInWindow` (never continuously). Pass `null` to keep the
+ * hook's position stable while registering nothing (e.g. a list item that is
+ * only an anchor at one index).
+ */
+declare const useCoachmarkAnchor: (id: string | null | undefined) => React.RefObject<View | null>;
+
+interface UseCoachmarkTourOptions {
+    /**
+     * Gate key for the whole tour. The kit reads/writes
+     * `wire_coachmark_<tourId>_seen` through the injected CoachmarkStorage so the
+     * app never owns the "seen" bookkeeping (the global testing flag bypasses it).
+     */
+    tourId: string;
+    /** Run at most once ever (persisted via the gate). Default true. */
+    showOnce?: boolean;
+    /**
+     * Domain gate — the tour only arms while this is true (e.g. hasPosts), and it
+     * also drives PAUSE/RESUME: if this flips false mid-tour (e.g. the user tab-
+     * switches and the screen loses focus without unmounting) the overlay is
+     * hidden but the tour's position is kept, and it resumes on the CURRENT step
+     * (re-resolving its anchor) when this returns true. See the hook JSDoc.
+     */
+    enabled: boolean;
+    /** Let passive value land before the first hint. */
+    startDelayMs?: number;
+    /** Fires once the tour finishes or is skipped (after the gate is written). */
+    onComplete?: () => void;
+    /**
+     * Fires once when a step first becomes visible. It is NOT re-fired when the
+     * SAME step resumes after a focus-loss pause (the last-shown step id is
+     * tracked in a ref and suppressed), so a tab-switch never inflates
+     * impressions. It fires again only when the tour advances to a new step.
+     */
+    onStepShown?: (id: string) => void;
+    onStepEngaged?: (id: string) => void;
+    onStepDismissed?: (id: string) => void;
+}
+/**
+ * Plays an ordered queue of coachmark steps on the current screen through the
+ * root SpotlightOverlay (mounted by CoachmarkProvider). Engaging a step (tap the
+ * ring/tooltip) advances and fires onStepEngaged. Tapping the backdrop advances
+ * to the NEXT step and fires onStepDismissed — a stray tap or a "not now" never
+ * kills the tour; only a backdrop tap on the LAST step ends it. Both terminal
+ * paths (engaging past the end, or dismissing the last step) write the seen gate
+ * once and call onComplete, so a finished tour never nags again.
+ *
+ * Gating lives IN the kit: the tour arms only when `enabled` AND (not `showOnce`
+ * OR the `tourId` gate is unseen).
+ *
+ * PAUSE/RESUME on focus loss: `enabled` is a live gate, not just an arm-once
+ * trigger. Once armed, if `enabled` goes false while the tour is in flight
+ * (started, not finished) — the classic case being a tab-switch that keeps the
+ * screen mounted — the drive effect hides the overlay so a stale rect can't
+ * float over the wrong screen, but KEEPS `activeIndex` and does NOT write the
+ * seen gate. When `enabled` returns true the effect re-runs (it's in the deps)
+ * and re-drives the SAME step, re-resolving its anchor so a moved/relaid-out
+ * target is picked up. `onStepShown` is suppressed on that resume (last-shown
+ * step id is tracked in a ref) so a pause/resume never double-counts a step.
+ *
+ * IMPORTANT: `steps` MUST be a stable (memoized) array. If a new array identity
+ * is passed on every render the drive effect re-runs and re-shows the current
+ * step (wasteful anchor re-resolves / overlay churn), and analytics can
+ * double-fire. Memoize it, or pass an inline module-level constant.
+ *
+ * Preserved engine invariants: step callbacks live in a ref (not effect deps),
+ * anchor resolution is cancellable, and finish is idempotent (only one overlay
+ * is ever active, the gate is written once).
+ */
+declare const useCoachmarkTour: (
+/** Ordered coachmark steps. MUST be stable/memoized — see the note above. */
+steps: CoachmarkStep[], { tourId, showOnce, enabled, startDelayMs, onComplete, onStepShown, onStepEngaged, onStepDismissed, }: UseCoachmarkTourOptions) => void;
+
+/**
+ * Module-level runtime for the coachmark engine: the injected sync storage, the
+ * global `isTestingCoachmark` flag, and the seen-gate helpers built on top.
+ *
+ * WHY module singletons (not just context): the tour hooks and the anchor
+ * registry are driven imperatively from anywhere in the tree (a screen deep
+ * under the navigator), while the storage + testing flag are configured once at
+ * the root by `CoachmarkProvider`. Singletons let a hook read the gate without
+ * every call site threading the storage through props. The provider is still the
+ * single writer — it calls `setCoachmarkStorage` / `setCoachmarkTesting` on mount.
+ */
+
+/**
+ * Set the coachmarks master switch (from the resolved feature flags). Default true (fail-open).
+ * Written by CoachmarkProvider; read imperatively by the tour arm + the overlay store.
+ */
+declare const setCoachmarksEnabled: (value: boolean) => void;
+/** Whether the coachmarks module is enabled. False → tours/overlays are silently skipped. */
+declare const areCoachmarksEnabled: () => boolean;
+/** Set (or clear) the injected sync gate storage. Called by CoachmarkProvider. */
+declare const setCoachmarkStorage: (storage: CoachmarkStorage | null) => void;
+/** The currently-injected gate storage, or null if no provider is mounted. */
+declare const getCoachmarkStorage: () => CoachmarkStorage | null;
+/**
+ * Toggle the global QA replay flag. When true, EVERY seen-gate reads as unseen
+ * and every seen-write is suppressed, so every tour + showcase replays on each
+ * mount. The app flips ONE boolean to QA the whole coachmark surface.
+ */
+declare const setCoachmarkTesting: (value: boolean) => void;
+/** Whether replay-everything QA mode is on. */
+declare const isCoachmarkTesting: () => boolean;
+/** Gate key for a tour: `wire_coachmark_<tourId>_seen`. */
+declare const coachmarkGateKey: (tourId: string) => string;
+/** Gate key for a feature showcase: `wire_showcase_<id>_seen`. */
+declare const showcaseGateKey: (showcaseId: string) => string;
+/**
+ * Read a seen gate. Testing mode ALWAYS reports unseen (so everything replays).
+ * A missing storage (no provider) also reports unseen — the safe default is to
+ * show the hint rather than silently swallow it. `storageOverride` /
+ * `testingOverride` let a self-contained component (e.g. FeatureShowcase) pass
+ * its own storage without relying on the provider singleton.
+ */
+declare const hasSeenGate: (key: string, storageOverride?: CoachmarkStorage | null, testingOverride?: boolean) => boolean;
+/**
+ * Mark a gate seen. Suppressed in testing mode (so replay never persists) and a
+ * no-op without storage. Best-effort — a throwing adapter never breaks the tour.
+ */
+declare const markSeenGate: (key: string, storageOverride?: CoachmarkStorage | null, testingOverride?: boolean) => void;
+
+/**
+ * selectTourSteps — the Phase-3 (AI intent-mapping) seam, stubbed today.
+ *
+ * The app declares a full catalog of coachmarks (its "feature map"). Near-term,
+ * the whole catalog plays in its declared order. LATER, the Wire server will
+ * emit an ordered `coachmarks: string[]` id list chosen by the user's captured
+ * intent (see the package spec §1e / §5), and the app passes it straight here as
+ * `selection`. This function is the ONE place that turns a selection into the
+ * live ordered step list — so turning AI on is a drop-in with zero app changes:
+ *
+ *   // Phase 1-2 (no AI): full catalog, declared order
+ *   const steps = selectTourSteps(catalog);
+ *
+ *   // Phase 3 (AI on): server-chosen subset, server order
+ *   const steps = selectTourSteps(catalog, plan.coachmarks);
+ *
+ * Contract:
+ *  - `selection` absent → returns the catalog unchanged (identity/declared order).
+ *  - `selection` present → returns only catalog entries whose `id` appears in
+ *    `selection`, ordered by `selection` (unknown ids are skipped; duplicates in
+ *    `selection` are ignored after the first match).
+ *
+ * NOTE: routing steps through a catalog + this selector is NOT required today.
+ * Declaring an inline, static (module-level or memoized) steps array and passing
+ * it straight to `useCoachmarkTour` is a perfectly fine consumer pattern. The
+ * catalog + selection route exists to make the app AI-selection-ready — flip to
+ * server-chosen ordering later with zero app changes — not as the baseline.
+ */
+declare const selectTourSteps: <T extends {
+    id: string;
+}>(catalog: T[], selection?: string[]) => T[];
+
+/**
+ * Abstract gesture pictogram shown beside a coachmark tooltip. Pure reanimated —
+ * every animation runs on the UI thread (shared values + worklets), never
+ * setState, so it costs nothing on the JS thread. Honors Reduce Motion by
+ * dropping the motion loop and rendering the glyph static.
+ *
+ * NO drawn-hand anatomy. Swipes render the standard two-finger swipe glyph: two
+ * rounded vertical capsules (an abstract index + middle finger, slightly
+ * different heights) with a short, fading motion track trailing behind them along
+ * the swipe axis. The whole glyph is rotated per direction (up/down/left/right)
+ * and the capsules slide along the axis, fading, in a UI-thread loop. Pinch/zoom
+ * reuse the two-capsule abstraction spreading apart. Tap / double-tap render a
+ * minimal pulsing tap-target (ring + dot).
+ *
+ * Every glyph is a self-drawn primitive built from Views/borders (no vector-icon
+ * dependency, like AnimatedSparkle). Pass `renderHand` — the glyph slot — to
+ * substitute your own node while keeping the tuned motion. (The name is kept for
+ * backward compatibility; despite it, the default is a glyph, not a drawn hand.)
+ *
+ * NOTE: the coachmark path (SpotlightOverlay) and the showcase path
+ * (FeatureShowcase) both SKIP this component for `tap` / `double_tap` — those
+ * steps show only the highlight ring + tooltip, no glyph. The tap visual here
+ * exists for direct / standalone use.
+ */
+interface GestureHintProps {
+    type: GestureKind;
+    /** Overall glyph size in px. */
+    size?: number;
+    /** Glyph color. Defaults to white (reads on the dark blur backdrop). */
+    color?: string;
+    /**
+     * Provide a custom glyph node in place of the default self-drawn primitive; it
+     * inherits the tuned motion (slide+fade for swipes, pulse for tap). Kept as
+     * `renderHand` for backward compatibility — despite the name it is just the
+     * glyph slot, no longer a drawn hand.
+     */
+    renderHand?: (props: {
+        size: number;
+        color: string;
+    }) => ReactNode;
+}
+declare const GestureHint: React__default.NamedExoticComponent<GestureHintProps>;
+
+interface SpotlightOverlayProps {
+    message: string;
+    /** Window-space rect of the element to highlight. Null → centered hint (e.g. a scroll gesture). */
+    targetRect?: TargetRect | null;
+    gesture?: GestureKind;
+    placement?: Placement;
+    /** Tapping the highlighted target or the pill — advance / act. */
+    onEngage: () => void;
+    /** Tapping the dimmed backdrop — advance to the next step (ends the tour only on the last step). */
+    onDismiss: () => void;
+    /** Ring + tooltip color. Defaults to the onboarding theme's `primary`. */
+    accentColor?: string;
+    /** Tooltip label color. Defaults to the theme's `onPrimary`. */
+    accentTextColor?: string;
+}
+declare const SpotlightOverlay: React__default.NamedExoticComponent<SpotlightOverlayProps>;
+
+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;
+}
+declare const CoachmarkOverlayHost: React__default.NamedExoticComponent<CoachmarkOverlayHostProps>;
+
+/**
+ * A tiny module-level store for the single active coachmark overlay. The host
+ * (CoachmarkOverlayHost, mounted once by CoachmarkProvider at the app root)
+ * subscribes and renders whatever is active; the tour controller drives it
+ * imperatively via show()/hide(). No React context is needed for the overlay
+ * itself — the host reaches the root so the ring can paint above the tab bar.
+ *
+ * Only ONE overlay is ever active (steps never stack), per the engine's
+ * one-overlay-at-a-time rule.
+ */
+interface CoachmarkOverlayState {
+    message: string;
+    targetRect: TargetRect | null;
+    gesture: GestureKind;
+    placement: Placement;
+    onEngage: () => void;
+    onDismiss: () => void;
+}
+declare const coachmarkOverlay: {
+    show(state: CoachmarkOverlayState): void;
+    hide(): void;
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): CoachmarkOverlayState | null;
+};
+/** Subscribe a component to the active overlay (or null). */
+declare const useCoachmarkOverlay: () => CoachmarkOverlayState | null;
+
+/**
+ * Maps a coachmark anchor id → a function that measures that element's current
+ * window rect. Elements register themselves on mount (via useCoachmarkAnchor)
+ * and the tour controller resolves an id to a rect at the moment a step fires.
+ *
+ * This is the "app declares WHERE" half of the engine: the kit owns the
+ * measuring/registry mechanics, each app decides which ids exist and pins them
+ * to its own components.
+ */
+type AnchorMeasurer = () => Promise<TargetRect | null>;
+/**
+ * NOTE: this registry is last-writer-wins — one measurer per id. An `anchorId`
+ * MUST be unique across screens that can be mounted simultaneously; if two live
+ * screens share an id, the second registration hides the first and unmount order
+ * decides who survives. Scope ids per screen (e.g. `feed.filter_icon`) when a
+ * component can appear in more than one mounted screen at once.
+ */
+declare const coachmarkAnchors: {
+    register(id: string, measurer: AnchorMeasurer): void;
+    /**
+     * Only clears the id when `measurer` is still the current registration, so a
+     * screen unmounting after a newer screen registered the same id does not wipe
+     * the live measurer. Omit `measurer` to force-delete regardless.
+     */
+    unregister(id: string, measurer?: AnchorMeasurer): void;
+    get(id: string): AnchorMeasurer | undefined;
+    /**
+     * Resolve an anchor to a rect, retrying briefly while the target lays out
+     * (e.g. the first feed post, or a screen just navigated to). Cancellable via
+     * `shouldCancel` so a superseded step abandons its retry loop immediately.
+     */
+    resolve(id: string, { retries, intervalMs, shouldCancel, }?: {
+        retries?: number;
+        intervalMs?: number;
+        /** Abort the retry loop early (e.g. the step was superseded). */
+        shouldCancel?: () => boolean;
+    }): Promise<TargetRect | null>;
+};
+
+export { type AnchorMeasurer, CoachmarkOverlayHost, type CoachmarkOverlayHostProps, type CoachmarkOverlayState, CoachmarkProvider, type CoachmarkProviderProps, CoachmarkStep, CoachmarkStorage, GestureHint, type GestureHintProps, GestureKind, Placement, SpotlightOverlay, type SpotlightOverlayProps, TargetRect, type UseCoachmarkTourOptions, areCoachmarksEnabled, coachmarkAnchors, coachmarkGateKey, coachmarkOverlay, getCoachmarkStorage, hasSeenGate, isCoachmarkTesting, markSeenGate, selectTourSteps, setCoachmarkStorage, setCoachmarkTesting, setCoachmarksEnabled, showcaseGateKey, useCoachmarkAnchor, useCoachmarkOverlay, useCoachmarkTour };