@qoretechnologies/reqraft 0.10.56 → 0.10.57-pr.127.g0edd18d

package/src/tracking/react/Experiment.stories.tsx

@@ -0,0 +1,174 @@
+import { ReqoreControlGroup, ReqoreP, ReqorePanel, ReqoreTag, ReqoreTagGroup } from '@qoretechnologies/reqore';
+import { StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { expect, within } from 'storybook/test';
+import { StoryMeta } from '../../types';
+import { KEYS, type IExperimentDefinition } from '../core/types';
+import { createMemoryTracker, type IMemoryTrackerOptions } from '../testing';
+import { Experiment } from './Experiment';
+import { useExperiment } from './hooks';
+import { TrackingProvider } from './TrackingProvider';
+
+const KEY = 'signup-cta';
+
+const RUNNING: IExperimentDefinition = {
+  key: KEY,
+  status: 'running',
+  variants: [
+    { key: 'a', weight: 0.5, control: true },
+    { key: 'b', weight: 0.5 },
+  ],
+  traffic: 1,
+  trigger: null,
+};
+
+/** `createMemoryTracker`'s clock starts here; the cached definitions are fresh for it. */
+const CLOCK = Date.UTC(2026, 8, 29, 10, 0, 0);
+
+/**
+ * The definitions as the tracker caches them after a fetch, so the first render already
+ * has them (a real app gets the same from its cache on every visit after the first).
+ */
+const cached = (experiments: IExperimentDefinition[]) => ({
+  [KEYS.experimentsCache]: JSON.stringify({ at: CLOCK, property: 'test', experiments }),
+});
+
+/** A visitor id whose GrowthBook hash for `signup-cta` lands in version B at 50/50. */
+const VISITOR_IN_B = 'visitor-3';
+
+const Version = ({ letter, label }: { letter: string; label: string }) => (
+  <ReqorePanel label={`Version ${letter}`} flat>
+    <ReqoreP>{label}</ReqoreP>
+  </ReqorePanel>
+);
+
+const VARIANTS = {
+  a: <Version letter='A' label='The control: what every visitor sees without the experiment.' />,
+  b: <Version letter='B' label='The challenger: shown only to visitors assigned to it.' />,
+};
+
+/** Shows why this visitor sees what they see (the same assignment `<Experiment>` uses). */
+const Reason = () => {
+  const { variant, assignment } = useExperiment(KEY, { variants: ['a', 'b'] });
+  return (
+    <ReqoreTagGroup>
+      <ReqoreTag labelKey='Shown' label={variant.toUpperCase()} />
+      <ReqoreTag labelKey='Reason' label={assignment.reason} />
+      <ReqoreTag labelKey='Counts for the test' label={assignment.enrolled ? 'yes' : 'no'} />
+    </ReqoreTagGroup>
+  );
+};
+
+const Demo = ({ tracking }: { tracking?: IMemoryTrackerOptions }) => {
+  const [memory] = useState(() => (tracking ? createMemoryTracker(tracking) : null));
+  return (
+    <TrackingProvider tracker={memory?.tracker ?? null} location='/'>
+      <ReqoreControlGroup vertical fluid>
+        <Reason />
+        <Experiment id={KEY} variants={VARIANTS} />
+      </ReqoreControlGroup>
+    </TrackingProvider>
+  );
+};
+
+const meta = {
+  title: 'Tracking/Experiment',
+  component: Demo,
+} as StoryMeta<typeof Demo>;
+
+export default meta;
+export type Story = StoryObj<typeof meta>;
+
+const expectShown = async (canvasElement: HTMLElement, variant: string, reason: string) => {
+  const canvas = within(canvasElement);
+  await expect(await canvas.findByText(`Version ${variant.toUpperCase()}`)).toBeInTheDocument();
+  const wrapper = canvasElement.querySelector(`[data-experiment="${KEY}"]`) as HTMLElement;
+  await expect(wrapper.dataset.variant).toBe(variant);
+  await expect(wrapper.dataset.experimentReason).toBe(reason);
+  await expect(canvas.getByText(reason)).toBeInTheDocument();
+};
+
+export const ControlWithoutTracker: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders an experiment with no tracker behind it (as before the visitor answered the consent prompt). Shows version A, the control, with the reason `no-consent`.',
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    await expectShown(canvasElement, 'a', 'no-consent');
+  },
+};
+
+export const AssignedVariant: Story = {
+  args: {
+    tracking: { consent: 'granted', vid: VISITOR_IN_B, seed: cached([RUNNING]) },
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a running 50/50 experiment for a visitor who allowed tracking and whose id hashes into version B. Shows version B, reason `assigned`, counted for the test.',
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    await expectShown(canvasElement, 'b', 'assigned');
+    await expect(within(canvasElement).getByText('yes')).toBeInTheDocument();
+  },
+};
+
+export const NotEnrolled: Story = {
+  args: {
+    tracking: { consent: 'granted', vid: VISITOR_IN_B, seed: cached([{ ...RUNNING, traffic: 0 }]) },
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a running experiment with a traffic share of 0 for a visitor who allowed tracking. Shows version A, reason `not-enrolled`, not counted for the test.',
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    await expectShown(canvasElement, 'a', 'not-enrolled');
+  },
+};
+
+export const PreviewLink: Story = {
+  args: {
+    tracking: { page: { search: `?qa_variant=${KEY}:b` }, seed: cached([RUNNING]) },
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the experiment opened through a `?qa_variant=signup-cta:b` preview link, without consent. Shows version B with the reason `preview`, never counted.',
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    await expectShown(canvasElement, 'b', 'preview');
+  },
+};
+
+export const ConcludedWinner: Story = {
+  args: {
+    tracking: {
+      seed: cached([{ key: KEY, status: 'concluded', winner: 'b' } as IExperimentDefinition]),
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders an experiment that ended with version B as the winner, for a visitor who never answered the consent prompt. Shows version B to everybody, reason `concluded`.',
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    await expectShown(canvasElement, 'b', 'concluded');
+  },
+};

package/src/tracking/react/Experiment.tsx

@@ -0,0 +1,44 @@
+import type { ReactNode } from 'react';
+import { useExperiment } from './hooks';
+
+export interface IExperimentProps {
+  /** The experiment key, as in the admin API (`signup-cta`). */
+  id: string;
+  /** One element per variant key; the control's key must be among them. */
+  variants: Record<string, ReactNode>;
+  /** The control's key (default `a`). */
+  control?: string;
+  /** Trigger section (`data-track-section` id) when the definition names none. */
+  trigger?: string;
+}
+
+/**
+ * Renders the visitor's variant: `<Experiment id="signup-cta" variants={{ a: <A />, b: <B /> }} />`.
+ * Without consent, without a running definition, or outside the traffic share it
+ * renders the control and logs nothing. An ended (concluded) experiment renders its winner
+ * for everybody. An in-app switch (`experiments.setEditorOverride`) shows one version per
+ * experiment (never logged); a `?qa_variant=signup-cta:b` link previews one for QA.
+ *
+ * DOM: a `display: contents` wrapper with `data-experiment`, `data-variant` (shown),
+ * `data-variants` (every key, comma-separated) and `data-experiment-reason`.
+ */
+export const Experiment = ({ id, variants, control = 'a', trigger }: IExperimentProps) => {
+  const keys = Object.keys(variants);
+  const { variant, assignment } = useExperiment(id, { control, trigger, variants: keys });
+  const shown = variants[variant] !== undefined ? variant : control;
+  // DOM markers, so an editor overlay can find every experiment on the page. `display: contents`
+  // gives the wrapper no box, so the page lays out exactly as without it.
+  return (
+    <div
+      style={CONTENTS}
+      data-experiment={id}
+      data-variant={shown}
+      data-variants={keys.join(',')}
+      data-experiment-reason={assignment.reason}
+    >
+      {variants[shown] ?? null}
+    </div>
+  );
+};
+
+const CONTENTS = { display: 'contents' } as const;

package/src/tracking/react/TrackingProvider.tsx

@@ -0,0 +1,56 @@
+import { createContext, useContext, useLayoutEffect, useMemo, useRef, type ReactNode, type MutableRefObject } from 'react';
+import type { IAttached } from '../browser/attach';
+import type { Tracker } from '../core/tracker';
+
+interface ITrackingContext {
+  tracker: Tracker | null;
+  /** The page wiring; set before any child's passive effect runs. */
+  attached: MutableRefObject<IAttached | null>;
+}
+
+const TrackingContext = createContext<ITrackingContext>({ tracker: null, attached: { current: null } });
+
+export interface ITrackingProviderProps {
+  tracker: Tracker | null;
+  /** Attaches the tracker to the page (listeners, observers); omitted in stories and tests. */
+  attach?: () => IAttached;
+  /** The current route (`pathname + search`): each change is a new page view. */
+  location: string;
+  children: ReactNode;
+}
+
+/**
+ * Mount once, at the app shell. Without a provider (or with `tracker={null}`)
+ * everything still renders: consent reads `unknown`, experiments serve the control.
+ */
+export const TrackingProvider = ({ tracker, attach, location, children }: ITrackingProviderProps) => {
+  const attached = useRef<IAttached | null>(null);
+
+  // Layout effects: every layout effect runs before any passive effect, so the
+  // tracker is attached and started before a child's `useExperiment` effect.
+  useLayoutEffect(() => {
+    if (!tracker) return undefined;
+    try {
+      attached.current = attach?.() ?? null;
+      tracker.start();
+    } catch {
+      /* never into the page */
+    }
+    return () => {
+      attached.current?.detach();
+      attached.current = null;
+    };
+  }, [tracker, attach]);
+
+  useLayoutEffect(() => {
+    tracker?.pageview();
+  }, [tracker, location]);
+
+  const value = useMemo(() => ({ tracker, attached }), [tracker]);
+  return <TrackingContext.Provider value={value}>{children}</TrackingContext.Provider>;
+};
+
+export const useTrackingContext = () => useContext(TrackingContext);
+
+/** The tracker, or null outside a provider. Call `goal`, `custom`, `record` on it. */
+export const useTracker = () => useContext(TrackingContext).tracker;

package/src/tracking/react/hooks.ts

@@ -0,0 +1,106 @@
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import type { IAssignment } from '../core/experiments';
+import { Observable } from '../core/observable';
+import type { TConsentState } from '../core/types';
+import { useTrackingContext } from './TrackingProvider';
+
+const noopSubscribe = () => () => undefined;
+
+/** The visitor's consent and the two answers. `unknown` outside a provider. */
+export const useConsent = () => {
+  const { tracker } = useTrackingContext();
+  const state = useSyncExternalStore<TConsentState>(
+    tracker ? tracker.consent.state.subscribe : noopSubscribe,
+    () => (tracker ? tracker.consent.get() : 'unknown'),
+    () => 'unknown',
+  );
+  const grant = useCallback(() => tracker?.grant(), [tracker]);
+  const deny = useCallback(() => tracker?.deny(), [tracker]);
+  return { state, grant, deny, available: !!tracker };
+};
+
+/** Whether the app asked to reopen its consent prompt (a "Cookie settings" link). */
+export const consentPanel = new Observable<boolean>(false);
+export const openConsentSettings = () => consentPanel.set(true);
+export const closeConsentSettings = () => consentPanel.set(false);
+export const useConsentPanelOpen = () => useSyncExternalStore(consentPanel.subscribe, consentPanel.get, consentPanel.get);
+
+export interface IUseExperimentOptions {
+  /** The control's key (default `a`): served whenever the visitor is not assigned. */
+  control?: string;
+  /** Variant keys this code can render; an assignment outside it falls back to the control. */
+  variants?: string[];
+  /** Trigger section when the experiment definition names none. */
+  trigger?: string;
+}
+
+export interface IUseExperiment {
+  variant: string;
+  assignment: IAssignment;
+  /** Put on the element whose being seen counts as exposure, when there is no trigger section. */
+  triggerRef: (el: Element | null) => void;
+}
+
+/**
+ * The variant this visitor sees. Decided once when the component mounts and kept
+ * for the page view (no flicker when definitions or consent arrive later: the
+ * next page view picks them up). Two exceptions, both for an editor: the in-app
+ * version switch (`setEditorOverride`) applies at once, and `experiments.refresh()`
+ * (after a winner is accepted or a version removed) decides again. Logs the exposure once per page view when the
+ * trigger is seen, and only for enrolled visitors (never for a preview or a winner).
+ */
+export const useExperiment = (key: string, options: IUseExperimentOptions = {}): IUseExperiment => {
+  const { tracker, attached } = useTrackingContext();
+  const control = options.control ?? 'a';
+  const known = options.variants;
+  const decide = useCallback((): IAssignment => {
+    const a: IAssignment = tracker
+      ? tracker.decide(key, control)
+      : { key, variant: control, enrolled: false, reason: 'no-consent', trigger: null };
+    return known && !known.includes(a.variant) ? { ...a, variant: control, enrolled: false } : a;
+    // `known` is the variant keys of the call site: constant for its lifetime.
+  }, [tracker, key, control]);
+  const [mounted] = useState<IAssignment>(decide);
+  const store = tracker?.experiments;
+  const revision = useSyncExternalStore(store ? store.revision.subscribe : noopSubscribe, () => store?.revision.get() ?? 0, () => 0);
+  const editorVariant = useSyncExternalStore(
+    store ? store.editorOverrides.subscribe : noopSubscribe,
+    () => store?.editorOverrideOf(key),
+    () => undefined,
+  );
+  // Windows of the same app (an editor and its preview frame) share the switch through localStorage.
+  useEffect(() => {
+    if (!store || typeof window === 'undefined') return undefined;
+    const onStorage = () => store.reloadEditorOverrides();
+    window.addEventListener('storage', onStorage);
+    return () => window.removeEventListener('storage', onStorage);
+  }, [store]);
+  // Same object while no switch or refresh changed it, so the exposure watch is not re-created.
+  const [mountedSwitch] = useState(editorVariant);
+  const assignment = useMemo(
+    () => (revision === 0 && editorVariant === mountedSwitch ? mounted : decide()),
+    [revision, editorVariant, mountedSwitch, mounted, decide],
+  );
+  const element = useRef<Element | null>(null);
+  const triggerRef = useCallback((el: Element | null) => {
+    element.current = el;
+  }, []);
+
+  useEffect(() => {
+    if (!tracker || !assignment.enrolled) return undefined;
+    let trigger = assignment.trigger ?? options.trigger ?? null;
+    let unobserve: (() => void) | undefined;
+    if (!trigger && element.current && attached.current) {
+      trigger = `experiment:${key}`;
+      unobserve = attached.current.observeElement(element.current, trigger);
+    }
+    const unwatch = tracker.watchExposure({ ...assignment, trigger });
+    return () => {
+      unwatch();
+      unobserve?.();
+    };
+    // A new assignment only comes from a switch or a refresh; options.trigger is a constant at the call site.
+  }, [tracker, assignment]);
+
+  return { variant: assignment.variant, assignment, triggerRef };
+};

package/src/tracking/react/index.ts

@@ -0,0 +1,13 @@
+export { TrackingProvider, useTracker, useTrackingContext } from './TrackingProvider';
+export { Experiment } from './Experiment';
+export {
+  closeConsentSettings,
+  consentPanel,
+  openConsentSettings,
+  useConsent,
+  useConsentPanelOpen,
+  useExperiment,
+} from './hooks';
+export type { IUseExperiment, IUseExperimentOptions } from './hooks';
+export type { ITrackingProviderProps } from './TrackingProvider';
+export type { IExperimentProps } from './Experiment';

package/src/tracking/testing.ts

@@ -0,0 +1,108 @@
+import { memoryStorage, type IStorage } from './core/storage';
+import { Tracker, type IPageInfo } from './core/tracker';
+import { resolveConfig, storageKeys, type IBatch, type IExperimentDefinition, type ITrackingConfig, type TStorageKeys } from './core/types';
+
+/**
+ * A tracker with no browser behind it: memory storage, a fake clock and timers you
+ * drive, a transport that records batches. For unit tests and Storybook stories.
+ * Defaults: property `test`, the default storage prefix (`qa.`), page `https://example.com/`.
+ */
+export interface IMemoryTracker {
+  tracker: Tracker;
+  /** Batches handed to the transport, parsed. */
+  sent: { batch: IBatch; mode: 'fetch' | 'beacon' }[];
+  local: IStorage;
+  session: IStorage;
+  /** The storage keys under the config's prefix. */
+  keys: TStorageKeys;
+  page: IPageInfo;
+  /** Moves the clock forward and runs every timer that is due. */
+  advance: (ms: number) => Promise<void>;
+  now: () => number;
+  /** Makes the next transport calls fail (network down). */
+  setOffline: (offline: boolean) => void;
+}
+
+export interface IMemoryTrackerOptions {
+  /** Any config field; `property`, `endpoint` and `experimentsEndpoint` have test defaults. */
+  config?: Partial<ITrackingConfig>;
+  consent?: 'granted' | 'denied';
+  /** The running-experiments answer: a list, a function (read on every load), or 'fail' (no endpoint). */
+  experiments?: IExperimentDefinition[] | (() => unknown[]) | 'fail';
+  page?: Partial<IPageInfo>;
+  vid?: string;
+  start?: number;
+  /** localStorage contents before the tracker starts (applied last). */
+  seed?: Record<string, string>;
+}
+
+export const createMemoryTracker = (options: IMemoryTrackerOptions = {}): IMemoryTracker => {
+  let clock = options.start ?? Date.UTC(2026, 8, 29, 10, 0, 0);
+  let offline = false;
+  const timers = new Map<number, { at: number; fn: () => void }>();
+  let nextTimer = 1;
+  const local = memoryStorage();
+  const session = memoryStorage();
+  const config = resolveConfig({
+    property: 'test',
+    endpoint: '/collect',
+    experimentsEndpoint: '/experiments',
+    ...options.config,
+  });
+  const keys = storageKeys(config.storagePrefix);
+  if (options.consent) {
+    local.set(keys.consent, options.consent);
+    local.set(keys.consentVersion, String(config.consentVersion));
+  }
+  if (options.vid) local.set(keys.vid, options.vid);
+  Object.entries(options.seed ?? {}).forEach(([k, v]) => local.set(k, v));
+  const page: IPageInfo = {
+    origin: 'https://example.com',
+    path: '/',
+    search: '',
+    title: 'Example',
+    referrer: '',
+    lang: 'en-US',
+    viewport: [1440, 900],
+    device: 'desktop',
+    ...options.page,
+  };
+  const sent: IMemoryTracker['sent'] = [];
+  const tracker = new Tracker(config, {
+    local,
+    session,
+    now: () => clock,
+    setTimer: (fn, ms) => {
+      const id = nextTimer++;
+      timers.set(id, { at: clock + ms, fn });
+      return id;
+    },
+    clearTimer: (h) => void timers.delete(h as number),
+    page: () => page,
+    transport: {
+      send: async (body, mode) => {
+        if (offline) return false;
+        sent.push({ batch: JSON.parse(body) as IBatch, mode });
+        return true;
+      },
+    },
+    fetchJson: async () => {
+      if (!options.experiments || options.experiments === 'fail') throw new Error('no experiments endpoint');
+      return { experiments: typeof options.experiments === 'function' ? options.experiments() : options.experiments };
+    },
+  });
+  const advance = async (ms: number) => {
+    const until = clock + ms;
+    for (;;) {
+      const due = Array.from(timers.entries()).filter(([, t]) => t.at <= until).sort((a, b) => a[1].at - b[1].at)[0];
+      if (!due) break;
+      timers.delete(due[0]);
+      clock = Math.max(clock, due[1].at);
+      due[1].fn();
+      await Promise.resolve();
+    }
+    clock = until;
+    await new Promise((r) => setTimeout(r, 0));
+  };
+  return { tracker, sent, local, session, keys, page, advance, now: () => clock, setOffline: (o) => (offline = o) };
+};