@akinon/pz-theme 2.0.128-beta.0 → 2.0.128

package/src/utils/theme-signal.ts

@@ -0,0 +1,419 @@
+import { devWarn } from './dev-warn';
+
+/**
+ * Neutral interaction signals for theme-composed sections and blocks
+ * (ZERO-5156).
+ *
+ * The sibling of `analytics.ts`, for the moments that are not commerce: a
+ * section scrolling into view, a slide changing, a modal opening, a promo
+ * being dismissed. Same doctrine — the theme reports a FACT in a neutral
+ * vocabulary and never knows GA4, Insider or any tag manager exists; a brand
+ * maps the fact to its own schema in its own repo, and a brand that listens
+ * to nothing gets exactly zero behaviour change.
+ *
+ * Why a second channel rather than a new action on `pz:commerce`: the one
+ * bridge that exists in the fleet ends in an unconditional flat dataLayer
+ * push, reached today only by `search`. The first UI moment named on that
+ * channel would start writing bare events into a live GA4 property the day
+ * the brand bumps this package. `pz:theme` cannot reach that listener at all,
+ * and `attachGa4DataLayerBridge` listens on the commerce name and never sees
+ * this one.
+ *
+ * This module is the ONLY place that dispatches the new channel, so the three
+ * rules every moment needs live here once instead of in thirty call sites:
+ * silence while the theme editor is attached, a latch so a repeat is a no-op,
+ * and a ceiling so an autoplaying carousel cannot bill a brand for a thousand
+ * hits an hour.
+ *
+ * It carries no `'use client'` and imports only `./dev-warn`, which imports
+ * nothing. That is deliberate and pinned by a test: a module reachable from a
+ * server render must not pull a client reference in, and the emitter has to be
+ * callable from plain modules (the overlay bus, a delegated DOM listener) as
+ * well as from components.
+ */
+
+export const THEME_SIGNAL_EVENT_NAME = 'pz:theme';
+
+/**
+ * The moments this build can report.
+ *
+ * A closed union rather than `string`, for three reasons: a typo fails the
+ * build instead of producing a silent second event name in a brand's GA4
+ * property; the editor's capability announce can be derived from the frozen
+ * array below rather than maintained beside it; and a brand bridge can switch
+ * exhaustively.
+ *
+ * Dot-namespaced so a name can never collide with a GA4 reserved or
+ * recommended event (`share`, `video_start`, `select_promotion`). What a
+ * moment MEANS in analytics terms is the brand's decision, taken in its
+ * bridge or in its container — the theme only says what happened.
+ */
+export type KnownThemeSignalName =
+  | 'section.seen'
+  | 'slide.changed'
+  | 'slide.control'
+  | 'modal.opened'
+  | 'modal.closed'
+  | 'popup.triggered'
+  | 'popup.suppressed'
+  | 'panel.opened'
+  | 'drawer.opened'
+  | 'tab.changed'
+  | 'disclosure.toggled'
+  | 'nav.clicked'
+  | 'promo.rotated'
+  | 'promo.dismissed'
+  | 'promo.suppressed'
+  | 'coupon.applied'
+  | 'coupon.removed'
+  | 'sort.changed'
+  | 'filter.applied'
+  | 'filter.cleared'
+  | 'share.clicked'
+  | 'countdown.expired'
+  | 'video.played'
+  | 'video.paused';
+
+export const THEME_SIGNAL_NAMES: readonly KnownThemeSignalName[] = [
+  'section.seen',
+  'slide.changed',
+  'slide.control',
+  'modal.opened',
+  'modal.closed',
+  'popup.triggered',
+  'popup.suppressed',
+  'panel.opened',
+  'drawer.opened',
+  'tab.changed',
+  'disclosure.toggled',
+  'nav.clicked',
+  'promo.rotated',
+  'promo.dismissed',
+  'promo.suppressed',
+  'coupon.applied',
+  'coupon.removed',
+  'sort.changed',
+  'filter.applied',
+  'filter.cleared',
+  'share.clicked',
+  'countdown.expired',
+  'video.played',
+  'video.paused'
+];
+
+const KNOWN_NAMES = new Set<string>(THEME_SIGNAL_NAMES);
+
+/** The prefix a brand's own moment must carry. */
+export const CUSTOM_SIGNAL_PREFIX = 'custom.';
+
+/**
+ * A brand-authored moment, namespaced so it can never collide with a name this
+ * package adds later and a bridge can tell the two apart at a glance.
+ */
+export type CustomThemeSignalName = `${typeof CUSTOM_SIGNAL_PREFIX}${string}`;
+
+export type ThemeSignalName = KnownThemeSignalName | CustomThemeSignalName;
+
+/**
+ * What a fact may be.
+ *
+ * Closed to flat scalars on purpose — the one deliberate difference from
+ * `CommerceEventDetail`, which carries an open index signature and a product
+ * array because GA4 ecommerce demands one. Here there is no shape in which a
+ * basket line, a form state, a DOM node or a shopper's typed text can be
+ * attached "just for now", which is the no-PII rule expressed structurally
+ * rather than as a review convention. Non-scalars are dropped at emit, so a
+ * cast does not get one through either.
+ */
+export type ThemeSignalValue = string | number | boolean;
+
+/** Where the moment happened. Every field optional: omit, never fabricate. */
+export interface ThemeSignalIdentity {
+  placeholderId?: string;
+  sectionId?: string;
+  sectionType?: string;
+  blockId?: string;
+  blockType?: string;
+}
+
+/**
+ * What a caller passes. `null` and `undefined` members are dropped rather than
+ * sent, so a caller can spread an optional value without a conditional.
+ */
+export interface ThemeSignalFacts extends ThemeSignalIdentity {
+  [key: string]: ThemeSignalValue | null | undefined;
+}
+
+/** What rides on the event. `name`, never `action` — see `emitThemeSignal`. */
+export interface ThemeSignalDetail extends ThemeSignalIdentity {
+  name: ThemeSignalName;
+  [key: string]: ThemeSignalValue | undefined;
+}
+
+export interface ThemeSignalOptions {
+  /**
+   * An extra dimension on the tally, composited as `name:key`, so two sections
+   * count separately while one section counts once. The composite shape is the
+   * one the page-scope emitter already uses for its own latch.
+   */
+  key?: string;
+  /** Shorthand for `ceiling: 1` — the latch. */
+  once?: boolean;
+  /**
+   * How many times this composite key may fire before the counter resets.
+   * `Infinity` opts out. Defaults to `DEFAULT_SIGNAL_CEILING`.
+   */
+  ceiling?: number;
+}
+
+/**
+ * Per-key flood guard.
+ *
+ * A six-slide hero at the default autoplay speed changes slide every three
+ * seconds — around 1200 `slide.changed` an hour on a tab left open, each one
+ * billed to whatever the brand forwards to. Twenty-four is far above any
+ * honest reading of a single page view and far below a runaway.
+ */
+export const DEFAULT_SIGNAL_CEILING = 24;
+
+/**
+ * Total emits allowed before the counter resets, across every key.
+ *
+ * The per-key ceiling cannot catch a composition that is chatty in aggregate —
+ * forty tracked sections each emitting their legitimate once. This bounds the
+ * page as a whole.
+ */
+export const SIGNAL_BUDGET_PER_ROUTE = 200;
+
+/** Longest string a fact may carry before it is truncated. */
+const MAX_VALUE_LENGTH = 120;
+
+/** Most facts one detail may carry, identity included. */
+const MAX_FACT_COUNT = 24;
+
+/**
+ * The tally, and the route it belongs to.
+ *
+ * Reset when `location.pathname` changes, read at emit time — no router
+ * import, no navigation listener, nothing to unsubscribe. This is the module
+ * equivalent of the per-mount refs the page-scope emitter uses: a client-side
+ * visit to another page reports again, a re-render of the same page does not.
+ */
+let tally = new Map<string, number>();
+let tallyPathname: string | null = null;
+let spent = 0;
+
+const currentPathname = (): string =>
+  typeof window === 'undefined' ? '' : (window.location?.pathname ?? '');
+
+const rollTallyForRoute = (): void => {
+  const pathname = currentPathname();
+  if (pathname === tallyPathname) return;
+
+  tallyPathname = pathname;
+  tally = new Map();
+  spent = 0;
+};
+
+/**
+ * True while the theme editor is attached — edit mode AND browse mode.
+ *
+ * Reads `window.__themeEditorDesigner` inline, the flag set only after a
+ * trusted SET_THEME_EDITOR_COOKIE arrives through the origin-guarded bridge.
+ * Four modules in this package read it exactly this way rather than importing
+ * it, so that the module holding it does not drag a client graph behind it.
+ *
+ * THE RAW FLAG, never an `isDesigner` a caller passes in. A block receives
+ * `isDesigner && !isBrowseMode`, so the moment a designer switches to browse
+ * mode that prop goes false while the editor is still attached — which is why
+ * the block-level commerce emits currently report a designer's clicks as a
+ * shopper's. Reading the flag here means no signal added through this module
+ * can inherit that defect, and no call site has to remember the distinction.
+ *
+ * Exported so a caller can skip expensive preparation (attaching an observer,
+ * measuring) rather than build a payload that would be thrown away.
+ */
+export const isThemeSignalMuted = (): boolean =>
+  typeof window !== 'undefined' &&
+  (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner ===
+    true;
+
+const isKnownName = (name: string): boolean =>
+  KNOWN_NAMES.has(name) ||
+  (name.startsWith(CUSTOM_SIGNAL_PREFIX) &&
+    name.length > CUSTOM_SIGNAL_PREFIX.length);
+
+/**
+ * One fact, or nothing.
+ *
+ * Objects, arrays, functions and symbols are dropped rather than serialized:
+ * the payload contract is flat scalars, and the failure mode of "serialize it
+ * anyway" is a product object or a form state reaching a third-party tag.
+ */
+const sanitizeValue = (value: unknown): ThemeSignalValue | undefined => {
+  if (typeof value === 'string') {
+    const text = value.trim();
+    if (!text) return undefined;
+    return text.length > MAX_VALUE_LENGTH
+      ? text.slice(0, MAX_VALUE_LENGTH)
+      : text;
+  }
+
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : undefined;
+  }
+
+  if (typeof value === 'boolean') return value;
+
+  return undefined;
+};
+
+const sanitizeFacts = (
+  name: string,
+  facts: ThemeSignalFacts
+): Record<string, ThemeSignalValue> => {
+  const clean: Record<string, ThemeSignalValue> = Object.create(null);
+  let count = 0;
+
+  for (const [key, value] of Object.entries(facts)) {
+    // `name` is set by the emitter; a caller passing one would otherwise
+    // rename the moment from inside its own payload.
+    if (key === 'name') continue;
+    if (value === null || value === undefined) continue;
+
+    if (count >= MAX_FACT_COUNT) {
+      devWarn(
+        'themeSignal',
+        `"${name}" carries more than ${MAX_FACT_COUNT} facts; the rest are dropped`
+      );
+      break;
+    }
+
+    const scalar = sanitizeValue(value);
+    if (scalar === undefined) {
+      devWarn(
+        'themeSignal',
+        `"${name}" fact "${key}" is not a string, finite number or boolean; dropped`
+      );
+      continue;
+    }
+
+    clean[key] = scalar;
+    count += 1;
+  }
+
+  return clean;
+};
+
+/**
+ * Report one theme moment.
+ *
+ * Fire-and-forget by the same rule the commerce emitter follows: observability
+ * must never take a block down, so everything here is guarded and a failure is
+ * silent in production.
+ *
+ * The detail names the moment under `name`, not `action`. That is a deliberate
+ * difference from the commerce channel: a bridge accidentally pointed at the
+ * wrong channel reads `detail.action === undefined` and drops the frame,
+ * instead of pushing a nameless event into a live property.
+ *
+ * @returns whether it dispatched, so a caller can stop observing once a
+ *          one-shot moment has been reported.
+ */
+export const emitThemeSignal = (
+  name: ThemeSignalName,
+  facts: ThemeSignalFacts = {},
+  options: ThemeSignalOptions = {}
+): boolean => {
+  if (typeof window === 'undefined') return false;
+
+  // Before anything else: the editor canvas and browse mode report nothing.
+  if (isThemeSignalMuted()) return false;
+
+  try {
+    if (!isKnownName(name)) {
+      devWarn(
+        'themeSignal',
+        `unknown signal name "${name}"; add it to THEME_SIGNAL_NAMES or prefix it with "${CUSTOM_SIGNAL_PREFIX}"`
+      );
+      return false;
+    }
+
+    rollTallyForRoute();
+
+    if (spent >= SIGNAL_BUDGET_PER_ROUTE) return false;
+
+    const ceiling = options.once
+      ? 1
+      : (options.ceiling ?? DEFAULT_SIGNAL_CEILING);
+
+    if (ceiling !== Infinity) {
+      const tallyKey = options.key ? `${name}:${options.key}` : name;
+      const seen = tally.get(tallyKey) ?? 0;
+      if (seen >= ceiling) return false;
+      tally.set(tallyKey, seen + 1);
+    }
+
+    spent += 1;
+
+    window.dispatchEvent(
+      new CustomEvent<ThemeSignalDetail>(THEME_SIGNAL_EVENT_NAME, {
+        detail: { name, ...sanitizeFacts(name, facts) }
+      })
+    );
+
+    return true;
+  } catch {
+    // Never let a reporting failure surface as a storefront error.
+    return false;
+  }
+};
+
+export interface ThemeSignalListenerOptions {
+  /** Only these moments reach the listener. */
+  names?: readonly ThemeSignalName[];
+}
+
+/**
+ * Listen for theme moments.
+ *
+ * A typed wrapper over `addEventListener` so a brand does not hand-roll the
+ * CustomEvent cast, and so the event name lives in one place. Returns a detach
+ * function, which is what makes `useEffect(() => subscribeToThemeSignals(fn), [])`
+ * the whole integration on the brand side.
+ *
+ * No default GA4 bridge ships for this channel, on purpose: `add_to_cart` has
+ * an industry-standard mapping, "promo dismissed" does not, and shipping one
+ * would be this package choosing a brand's analytics schema.
+ */
+export const subscribeToThemeSignals = (
+  listener: (detail: ThemeSignalDetail) => void,
+  options: ThemeSignalListenerOptions = {}
+): (() => void) => {
+  if (typeof window === 'undefined') return () => {};
+
+  const wanted = options.names ? new Set<string>(options.names) : null;
+
+  const handler = (event: Event) => {
+    const detail = (event as CustomEvent<ThemeSignalDetail>).detail;
+    if (!detail?.name) return;
+    if (wanted && !wanted.has(detail.name)) return;
+
+    try {
+      listener(detail);
+    } catch {
+      // A brand callback that throws must not break the dispatch for others.
+    }
+  };
+
+  window.addEventListener(THEME_SIGNAL_EVENT_NAME, handler);
+
+  return () => window.removeEventListener(THEME_SIGNAL_EVENT_NAME, handler);
+};
+
+/** Test-only: forget the route tally, matching the overlay bus reset helper. */
+export const __resetThemeSignalsForTests = (): void => {
+  tally = new Map();
+  tallyPathname = null;
+  spent = 0;
+};