@probat/react 0.4.1 → 0.4.2

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React$1, { ReactNode } from 'react';
 
 interface ProbatProviderProps {
     /** Your end-user's ID. When provided, used as the distinct_id for variant
@@ -12,7 +12,7 @@ interface ProbatProviderProps {
      * e.g. { "cta-copy-test": "ai_v1" }
      */
     bootstrap?: Record<string, string>;
-    children: React.ReactNode;
+    children: React$1.ReactNode;
 }
 
 /**
@@ -34,7 +34,7 @@ interface ProbatProviderProps {
  * }
  * ```
  */
-declare function ProbatProviderClient(props: ProbatProviderProps): React.FunctionComponentElement<ProbatProviderProps>;
+declare function ProbatProviderClient(props: ProbatProviderProps): React$1.FunctionComponentElement<ProbatProviderProps>;
 
 interface ExperimentTrackOptions {
     /** Auto-track impressions (default true) */
@@ -50,9 +50,9 @@ interface ExperimentProps {
     /** Experiment key / identifier */
     id: string;
     /** Control variant ReactNode */
-    control: React.ReactNode;
+    control: React$1.ReactNode;
     /** Named variant ReactNodes, keyed by variant key (e.g. { ai_v1: <MyVariant /> }) */
-    variants: Record<string, React.ReactNode>;
+    variants: Record<string, React$1.ReactNode>;
     /** Tracking configuration */
     track?: ExperimentTrackOptions;
     /** Stable instance id when multiple instances of the same experiment exist on a page */
@@ -62,7 +62,73 @@ interface ExperimentProps {
     /** Log decisions + events to console */
     debug?: boolean;
 }
-declare function Experiment({ id, control, variants, track, componentInstanceId, fallback, debug, }: ExperimentProps): React.JSX.Element;
+declare function Experiment({ id, control, variants, track, componentInstanceId, fallback, debug, }: ExperimentProps): React$1.JSX.Element;
+
+interface UseTrackOptions {
+    /** Experiment identifier */
+    experimentId: string;
+    /** The variant key to attach to events */
+    variantKey: string;
+    /** Stable instance id when multiple instances of the same experiment exist on a page */
+    componentInstanceId?: string;
+    /** Auto-track impressions (default true) */
+    impression?: boolean;
+    /** Auto-track clicks (default true) */
+    click?: boolean;
+    /** Custom impression event name (default "$experiment_exposure") */
+    impressionEventName?: string;
+    /** Custom click event name (default "$experiment_click") */
+    clickEventName?: string;
+    /** Log events to console */
+    debug?: boolean;
+}
+/**
+ * Attaches impression and click tracking to a DOM element via a ref.
+ * Completely independent of variant assignment — pass the variantKey explicitly.
+ *
+ * @example
+ * ```tsx
+ * const trackRef = useTrack({ experimentId: "pricing", variantKey: "ai_v1" });
+ * return <div ref={trackRef}>...</div>;
+ * ```
+ */
+declare function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement | null>;
+
+interface TrackProps extends UseTrackOptions {
+    children: React$1.ReactNode;
+}
+/**
+ * Wrapper component that attaches impression and click tracking to its children.
+ * Alternative to the `useTrack` hook when you prefer a component over a ref.
+ *
+ * @example
+ * ```tsx
+ * <Track experimentId="pricing" variantKey="ai_v1">
+ *   <PricingCard />
+ * </Track>
+ * ```
+ */
+declare function Track({ children, ...trackOptions }: TrackProps): React$1.JSX.Element;
+
+interface UseExperimentOptions {
+    /** Behavior when assignment fetch fails: "control" (default) renders control, "suspend" throws */
+    fallback?: "control" | "suspend";
+    /** Log decisions to console */
+    debug?: boolean;
+}
+interface UseExperimentReturn {
+    /** The resolved variant key (e.g. "control", "ai_v1") */
+    variantKey: string;
+    /** Whether the assignment has been resolved (bootstrap, cache, or fetch) */
+    resolved: boolean;
+}
+/**
+ * Resolves the variant assignment for an experiment.
+ * No tracking — use `useTrack` or `<Track>` to observe impressions/clicks.
+ *
+ * Priority: bootstrap > localStorage cache > fetchDecision.
+ */
+declare function useExperiment(id: string, options?: UseExperimentOptions): UseExperimentReturn;
 
 interface UseProbatMetricsReturn {
     /**
@@ -102,4 +168,30 @@ declare function fetchDecision(host: string, experimentId: string, distinctId: s
  */
 declare function sendMetric(host: string, event: string, properties: Record<string, unknown>): void;
 
-export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, ProbatProviderClient, type ProbatProviderProps, type UseProbatMetricsReturn, fetchDecision, sendMetric, useProbatMetrics };
+/**
+ * Factory that creates a typed context + hook pair for passing a variantKey
+ * between components in different files without prop-drilling.
+ *
+ * @example
+ * ```tsx
+ * // experiment-context.ts
+ * export const { ExperimentProvider, useVariantKey } = createExperimentContext("pricing-test");
+ *
+ * // Parent.tsx
+ * const { variantKey } = useExperiment("pricing-test");
+ * <ExperimentProvider value={variantKey}><Child /></ExperimentProvider>
+ *
+ * // Child.tsx (different file)
+ * const variantKey = useVariantKey();
+ * const trackRef = useTrack({ experimentId: "pricing-test", variantKey });
+ * ```
+ */
+declare function createExperimentContext(experimentId: string): {
+    ExperimentProvider: ({ value, children, }: {
+        value: string;
+        children: ReactNode;
+    }) => React$1.FunctionComponentElement<React$1.ProviderProps<string | null>>;
+    useVariantKey: () => string;
+};
+
+export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, ProbatProviderClient, type ProbatProviderProps, Track, type TrackProps, type UseExperimentOptions, type UseExperimentReturn, type UseProbatMetricsReturn, type UseTrackOptions, createExperimentContext, fetchDecision, sendMetric, useExperiment, useProbatMetrics, useTrack };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React$1, { ReactNode } from 'react';
 
 interface ProbatProviderProps {
     /** Your end-user's ID. When provided, used as the distinct_id for variant
@@ -12,7 +12,7 @@ interface ProbatProviderProps {
      * e.g. { "cta-copy-test": "ai_v1" }
      */
     bootstrap?: Record<string, string>;
-    children: React.ReactNode;
+    children: React$1.ReactNode;
 }
 
 /**
@@ -34,7 +34,7 @@ interface ProbatProviderProps {
  * }
  * ```
  */
-declare function ProbatProviderClient(props: ProbatProviderProps): React.FunctionComponentElement<ProbatProviderProps>;
+declare function ProbatProviderClient(props: ProbatProviderProps): React$1.FunctionComponentElement<ProbatProviderProps>;
 
 interface ExperimentTrackOptions {
     /** Auto-track impressions (default true) */
@@ -50,9 +50,9 @@ interface ExperimentProps {
     /** Experiment key / identifier */
     id: string;
     /** Control variant ReactNode */
-    control: React.ReactNode;
+    control: React$1.ReactNode;
     /** Named variant ReactNodes, keyed by variant key (e.g. { ai_v1: <MyVariant /> }) */
-    variants: Record<string, React.ReactNode>;
+    variants: Record<string, React$1.ReactNode>;
     /** Tracking configuration */
     track?: ExperimentTrackOptions;
     /** Stable instance id when multiple instances of the same experiment exist on a page */
@@ -62,7 +62,73 @@ interface ExperimentProps {
     /** Log decisions + events to console */
     debug?: boolean;
 }
-declare function Experiment({ id, control, variants, track, componentInstanceId, fallback, debug, }: ExperimentProps): React.JSX.Element;
+declare function Experiment({ id, control, variants, track, componentInstanceId, fallback, debug, }: ExperimentProps): React$1.JSX.Element;
+
+interface UseTrackOptions {
+    /** Experiment identifier */
+    experimentId: string;
+    /** The variant key to attach to events */
+    variantKey: string;
+    /** Stable instance id when multiple instances of the same experiment exist on a page */
+    componentInstanceId?: string;
+    /** Auto-track impressions (default true) */
+    impression?: boolean;
+    /** Auto-track clicks (default true) */
+    click?: boolean;
+    /** Custom impression event name (default "$experiment_exposure") */
+    impressionEventName?: string;
+    /** Custom click event name (default "$experiment_click") */
+    clickEventName?: string;
+    /** Log events to console */
+    debug?: boolean;
+}
+/**
+ * Attaches impression and click tracking to a DOM element via a ref.
+ * Completely independent of variant assignment — pass the variantKey explicitly.
+ *
+ * @example
+ * ```tsx
+ * const trackRef = useTrack({ experimentId: "pricing", variantKey: "ai_v1" });
+ * return <div ref={trackRef}>...</div>;
+ * ```
+ */
+declare function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement | null>;
+
+interface TrackProps extends UseTrackOptions {
+    children: React$1.ReactNode;
+}
+/**
+ * Wrapper component that attaches impression and click tracking to its children.
+ * Alternative to the `useTrack` hook when you prefer a component over a ref.
+ *
+ * @example
+ * ```tsx
+ * <Track experimentId="pricing" variantKey="ai_v1">
+ *   <PricingCard />
+ * </Track>
+ * ```
+ */
+declare function Track({ children, ...trackOptions }: TrackProps): React$1.JSX.Element;
+
+interface UseExperimentOptions {
+    /** Behavior when assignment fetch fails: "control" (default) renders control, "suspend" throws */
+    fallback?: "control" | "suspend";
+    /** Log decisions to console */
+    debug?: boolean;
+}
+interface UseExperimentReturn {
+    /** The resolved variant key (e.g. "control", "ai_v1") */
+    variantKey: string;
+    /** Whether the assignment has been resolved (bootstrap, cache, or fetch) */
+    resolved: boolean;
+}
+/**
+ * Resolves the variant assignment for an experiment.
+ * No tracking — use `useTrack` or `<Track>` to observe impressions/clicks.
+ *
+ * Priority: bootstrap > localStorage cache > fetchDecision.
+ */
+declare function useExperiment(id: string, options?: UseExperimentOptions): UseExperimentReturn;
 
 interface UseProbatMetricsReturn {
     /**
@@ -102,4 +168,30 @@ declare function fetchDecision(host: string, experimentId: string, distinctId: s
  */
 declare function sendMetric(host: string, event: string, properties: Record<string, unknown>): void;
 
-export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, ProbatProviderClient, type ProbatProviderProps, type UseProbatMetricsReturn, fetchDecision, sendMetric, useProbatMetrics };
+/**
+ * Factory that creates a typed context + hook pair for passing a variantKey
+ * between components in different files without prop-drilling.
+ *
+ * @example
+ * ```tsx
+ * // experiment-context.ts
+ * export const { ExperimentProvider, useVariantKey } = createExperimentContext("pricing-test");
+ *
+ * // Parent.tsx
+ * const { variantKey } = useExperiment("pricing-test");
+ * <ExperimentProvider value={variantKey}><Child /></ExperimentProvider>
+ *
+ * // Child.tsx (different file)
+ * const variantKey = useVariantKey();
+ * const trackRef = useTrack({ experimentId: "pricing-test", variantKey });
+ * ```
+ */
+declare function createExperimentContext(experimentId: string): {
+    ExperimentProvider: ({ value, children, }: {
+        value: string;
+        children: ReactNode;
+    }) => React$1.FunctionComponentElement<React$1.ProviderProps<string | null>>;
+    useVariantKey: () => string;
+};
+
+export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, ProbatProviderClient, type ProbatProviderProps, Track, type TrackProps, type UseExperimentOptions, type UseExperimentReturn, type UseProbatMetricsReturn, type UseTrackOptions, createExperimentContext, fetchDecision, sendMetric, useExperiment, useProbatMetrics, useTrack };

package/dist/index.js

@@ -204,6 +204,75 @@ function buildMeta(el, isPrimary) {
   return meta;
 }
 
+// src/hooks/useExperiment.ts
+var ASSIGNMENT_PREFIX = "probat:assignment:";
+function readAssignment(id) {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = localStorage.getItem(ASSIGNMENT_PREFIX + id);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    return parsed.variantKey ?? null;
+  } catch {
+    return null;
+  }
+}
+function writeAssignment(id, variantKey) {
+  if (typeof window === "undefined") return;
+  try {
+    const entry = { variantKey, ts: Date.now() };
+    localStorage.setItem(ASSIGNMENT_PREFIX + id, JSON.stringify(entry));
+  } catch {
+  }
+}
+function useExperiment(id, options = {}) {
+  const { fallback = "control", debug = false } = options;
+  const { host, bootstrap, customerId } = useProbatContext();
+  const [variantKey, setVariantKey] = React3.useState(() => {
+    if (bootstrap[id]) return bootstrap[id];
+    return "control";
+  });
+  const [resolved, setResolved] = React3.useState(() => {
+    return !!bootstrap[id];
+  });
+  React3.useEffect(() => {
+    if (bootstrap[id] || readAssignment(id)) {
+      const key = bootstrap[id] ?? readAssignment(id) ?? "control";
+      setVariantKey(key);
+      setResolved(true);
+      return;
+    }
+    let cancelled = false;
+    (async () => {
+      try {
+        const distinctId = customerId ?? getDistinctId();
+        const key = await fetchDecision(host, id, distinctId);
+        if (cancelled) return;
+        setVariantKey(key);
+        writeAssignment(id, key);
+      } catch (err) {
+        if (cancelled) return;
+        if (debug) {
+          console.error(`[probat] fetchDecision failed for "${id}":`, err);
+        }
+        if (fallback === "suspend") throw err;
+        setVariantKey("control");
+      } finally {
+        if (!cancelled) setResolved(true);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [id, host]);
+  React3.useEffect(() => {
+    if (debug && resolved) {
+      console.log(`[probat] Experiment "${id}" -> variant "${variantKey}"`);
+    }
+  }, [debug, id, variantKey, resolved]);
+  return { variantKey, resolved };
+}
+
 // src/utils/dedupeStorage.ts
 var PREFIX = "probat:seen:";
 var memorySet = /* @__PURE__ */ new Set();
@@ -291,113 +360,37 @@ function useStableInstanceIdFallback(experimentId) {
 }
 var useStableInstanceId = typeof React3__default.default.useId === "function" ? useStableInstanceIdV18 : useStableInstanceIdFallback;
 
-// src/components/Experiment.tsx
-var ASSIGNMENT_PREFIX = "probat:assignment:";
-function readAssignment(id) {
-  if (typeof window === "undefined") return null;
-  try {
-    const raw = localStorage.getItem(ASSIGNMENT_PREFIX + id);
-    if (!raw) return null;
-    const parsed = JSON.parse(raw);
-    return parsed.variantKey ?? null;
-  } catch {
-    return null;
-  }
-}
-function writeAssignment(id, variantKey) {
-  if (typeof window === "undefined") return;
-  try {
-    const entry = { variantKey, ts: Date.now() };
-    localStorage.setItem(ASSIGNMENT_PREFIX + id, JSON.stringify(entry));
-  } catch {
-  }
-}
-function Experiment({
-  id,
-  control,
-  variants,
-  track,
-  componentInstanceId,
-  fallback = "control",
-  debug = false
-}) {
-  const { host, bootstrap, customerId } = useProbatContext();
-  const autoInstanceId = useStableInstanceId(id);
+// src/hooks/useTrack.ts
+function useTrack(options) {
+  const {
+    experimentId,
+    variantKey,
+    componentInstanceId,
+    impression: trackImpression = true,
+    click: trackClick = true,
+    impressionEventName = "$experiment_exposure",
+    clickEventName = "$experiment_click",
+    debug = false
+  } = options;
+  const { host, customerId } = useProbatContext();
+  const autoInstanceId = useStableInstanceId(experimentId);
   const instanceId = componentInstanceId ?? autoInstanceId;
-  const trackImpression = track?.impression !== false;
-  const trackClick = track?.primaryClick !== false;
-  const impressionEvent = track?.impressionEventName ?? "$experiment_exposure";
-  const clickEvent = track?.clickEventName ?? "$experiment_click";
-  const [variantKey, setVariantKey] = React3.useState(() => {
-    if (bootstrap[id]) return bootstrap[id];
-    return "control";
-  });
-  const [resolved, setResolved] = React3.useState(() => {
-    return !!bootstrap[id];
-  });
-  React3.useEffect(() => {
-    if (bootstrap[id] || readAssignment(id)) {
-      const key = bootstrap[id] ?? readAssignment(id) ?? "control";
-      setVariantKey(key);
-      setResolved(true);
-      return;
-    }
-    let cancelled = false;
-    (async () => {
-      try {
-        const distinctId = customerId ?? getDistinctId();
-        const key = await fetchDecision(host, id, distinctId);
-        if (cancelled) return;
-        if (key !== "control" && !(key in variants)) {
-          if (debug) {
-            console.warn(
-              `[probat] Unknown variant "${key}" for experiment "${id}", falling back to control`
-            );
-          }
-          setVariantKey("control");
-        } else {
-          setVariantKey(key);
-          writeAssignment(id, key);
-        }
-      } catch (err) {
-        if (cancelled) return;
-        if (debug) {
-          console.error(`[probat] fetchDecision failed for "${id}":`, err);
-        }
-        if (fallback === "suspend") throw err;
-        setVariantKey("control");
-      } finally {
-        if (!cancelled) setResolved(true);
-      }
-    })();
-    return () => {
-      cancelled = true;
-    };
-  }, [id, host]);
-  React3.useEffect(() => {
-    if (debug && resolved) {
-      console.log(`[probat] Experiment "${id}" \u2192 variant "${variantKey}"`, {
-        instanceId,
-        pageKey: getPageKey()
-      });
-    }
-  }, [debug, id, variantKey, resolved, instanceId]);
+  const containerRef = React3.useRef(null);
+  const impressionSent = React3.useRef(false);
   const eventProps = React3.useMemo(
     () => ({
-      experiment_id: id,
+      experiment_id: experimentId,
       variant_key: variantKey,
       component_instance_id: instanceId,
       ...customerId ? { distinct_id: customerId } : {}
     }),
-    [id, variantKey, instanceId, customerId]
+    [experimentId, variantKey, instanceId, customerId]
   );
-  const containerRef = React3.useRef(null);
-  const impressionSent = React3.useRef(false);
   React3.useEffect(() => {
-    if (!trackImpression || !resolved) return;
+    if (!trackImpression) return;
     impressionSent.current = false;
     const pageKey = getPageKey();
-    const dedupeKey = makeDedupeKey(id, variantKey, instanceId, pageKey);
+    const dedupeKey = makeDedupeKey(experimentId, variantKey, instanceId, pageKey);
     if (hasSeen(dedupeKey)) {
       impressionSent.current = true;
       return;
@@ -408,8 +401,8 @@ function Experiment({
       if (!impressionSent.current) {
         impressionSent.current = true;
         markSeen(dedupeKey);
-        sendMetric(host, impressionEvent, eventProps);
-        if (debug) console.log(`[probat] Impression sent (no IO) for "${id}"`);
+        sendMetric(host, impressionEventName, eventProps);
+        if (debug) console.log(`[probat] Impression sent (no IO) for "${experimentId}"`);
       }
       return;
     }
@@ -422,8 +415,8 @@ function Experiment({
             if (impressionSent.current) return;
             impressionSent.current = true;
             markSeen(dedupeKey);
-            sendMetric(host, impressionEvent, eventProps);
-            if (debug) console.log(`[probat] Impression sent for "${id}"`);
+            sendMetric(host, impressionEventName, eventProps);
+            if (debug) console.log(`[probat] Impression sent for "${experimentId}"`);
             observer.disconnect();
           }, 250);
         } else if (timer) {
@@ -440,12 +433,11 @@ function Experiment({
     };
   }, [
     trackImpression,
-    resolved,
-    id,
+    experimentId,
     variantKey,
     instanceId,
     host,
-    impressionEvent,
+    impressionEventName,
     eventProps,
     debug
   ]);
@@ -454,22 +446,59 @@ function Experiment({
       if (!trackClick) return;
       const meta = extractClickMeta(e.target);
       if (!meta) return;
-      sendMetric(host, clickEvent, {
+      sendMetric(host, clickEventName, {
         ...eventProps,
         ...meta
       });
       if (debug) {
-        console.log(`[probat] Click tracked for "${id}"`, meta);
+        console.log(`[probat] Click tracked for "${experimentId}"`, meta);
       }
     },
-    [trackClick, host, clickEvent, eventProps, id, debug]
+    [trackClick, host, clickEventName, eventProps, experimentId, debug]
   );
+  React3.useEffect(() => {
+    const el = containerRef.current;
+    if (!el || !trackClick) return;
+    el.addEventListener("click", handleClick);
+    return () => {
+      el.removeEventListener("click", handleClick);
+    };
+  }, [handleClick, trackClick]);
+  return containerRef;
+}
+
+// src/components/Experiment.tsx
+function Experiment({
+  id,
+  control,
+  variants,
+  track,
+  componentInstanceId,
+  fallback = "control",
+  debug = false
+}) {
+  const { variantKey: rawKey, resolved } = useExperiment(id, { fallback, debug });
+  const variantKey = rawKey === "control" || rawKey in variants ? rawKey : "control";
+  if (debug && rawKey !== variantKey) {
+    console.warn(
+      `[probat] Unknown variant "${rawKey}" for experiment "${id}", falling back to control`
+    );
+  }
+  const trackRef = useTrack({
+    experimentId: id,
+    variantKey,
+    componentInstanceId,
+    impression: resolved ? track?.impression !== false : false,
+    click: track?.primaryClick !== false,
+    impressionEventName: track?.impressionEventName,
+    clickEventName: track?.clickEventName,
+    debug
+  });
   const content = variantKey === "control" || !(variantKey in variants) ? control : variants[variantKey];
   return /* @__PURE__ */ React3__default.default.createElement(
     "div",
     {
-      ref: containerRef,
-      onClick: handleClick,
+      ref: trackRef,
       "data-probat-experiment": id,
       "data-probat-variant": variantKey,
       style: {
@@ -483,6 +512,19 @@ function Experiment({
     content
   );
 }
+function Track({ children, ...trackOptions }) {
+  const trackRef = useTrack(trackOptions);
+  return /* @__PURE__ */ React3__default.default.createElement(
+    "div",
+    {
+      ref: trackRef,
+      "data-probat-track": trackOptions.experimentId,
+      "data-probat-variant": trackOptions.variantKey,
+      style: { display: "contents" }
+    },
+    children
+  );
+}
 function useProbatMetrics() {
   const { host, customerId } = useProbatContext();
   const capture = React3.useCallback(
@@ -496,11 +538,34 @@ function useProbatMetrics() {
   );
   return { capture };
 }
+function createExperimentContext(experimentId) {
+  const Ctx = React3.createContext(null);
+  function ExperimentProvider({
+    value,
+    children
+  }) {
+    return React3__default.default.createElement(Ctx.Provider, { value }, children);
+  }
+  function useVariantKey() {
+    const v = React3.useContext(Ctx);
+    if (v === null) {
+      throw new Error(
+        `useVariantKey() must be used inside <ExperimentProvider> for "${experimentId}"`
+      );
+    }
+    return v;
+  }
+  return { ExperimentProvider, useVariantKey };
+}
 
 exports.Experiment = Experiment;
 exports.ProbatProviderClient = ProbatProviderClient;
+exports.Track = Track;
+exports.createExperimentContext = createExperimentContext;
 exports.fetchDecision = fetchDecision;
 exports.sendMetric = sendMetric;
+exports.useExperiment = useExperiment;
 exports.useProbatMetrics = useProbatMetrics;
+exports.useTrack = useTrack;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map