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

package/src/hooks/use-theme-signal.ts

@@ -0,0 +1,144 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+
+import { useCustomBlockContext } from '../custom/block-context';
+import {
+  emitThemeSignal,
+  isThemeSignalMuted,
+  type ThemeSignalFacts,
+  type ThemeSignalIdentity,
+  type ThemeSignalName,
+  type ThemeSignalOptions
+} from '../utils/theme-signal';
+
+/**
+ * The React half of the theme signal API (ZERO-5156).
+ *
+ * `emitThemeSignal` is the primitive and is callable from anywhere, including
+ * the plain modules a third of these moments fire from — the overlay bus, the
+ * modal frequency rules, a delegated document listener. This hook exists for
+ * the one thing a plain function cannot do: resolve WHERE the moment happened.
+ * Section and block identity is carried by React context, so a brand's custom
+ * section gets it for free instead of threading four props to reach the line
+ * that reports.
+ */
+
+export type ThemeSignalEmit = (
+  name: ThemeSignalName,
+  facts?: ThemeSignalFacts,
+  options?: ThemeSignalOptions
+) => boolean;
+
+/**
+ * Resolve identity field by field: an explicit value wins, then the custom
+ * unit's context, then the field is omitted.
+ *
+ * Omitted, never fabricated — no `'unknown'`, no empty string. A bridge
+ * grouping by section must be able to tell absent from wrong, and an invented
+ * value is indistinguishable from a real one once it is in a report.
+ */
+const resolveIdentity = (
+  explicit: ThemeSignalIdentity | undefined,
+  context: ReturnType<typeof useCustomBlockContext>
+): ThemeSignalIdentity => {
+  const identity: ThemeSignalIdentity = {};
+
+  const placeholderId = explicit?.placeholderId ?? context?.placeholderId;
+  const sectionId = explicit?.sectionId ?? context?.sectionId;
+  const blockId =
+    explicit?.blockId ??
+    (context?.scope === 'block' ? context?.node?.id : undefined);
+  const blockType =
+    explicit?.blockType ??
+    (context?.scope === 'block' ? context?.node?.type : undefined);
+  const sectionType =
+    explicit?.sectionType ??
+    (context?.scope === 'section' ? context?.node?.type : undefined);
+
+  if (placeholderId) identity.placeholderId = placeholderId;
+  if (sectionId) identity.sectionId = sectionId;
+  if (sectionType) identity.sectionType = sectionType;
+  if (blockId) identity.blockId = blockId;
+  if (blockType) identity.blockType = blockType;
+
+  return identity;
+};
+
+/**
+ * An emit bound to this unit's identity.
+ *
+ * A built-in renderer passes what its props already carry; a brand's custom
+ * block or section passes nothing and is identified by the context it renders
+ * inside. The returned function is stable across renders, so it can sit in a
+ * dependency array without rebuilding the effect that uses it.
+ */
+export const useThemeSignal = (
+  identity?: ThemeSignalIdentity
+): ThemeSignalEmit => {
+  const context = useCustomBlockContext();
+
+  // Kept in a ref so the returned callback can stay stable while still
+  // reading the latest identity: a block moved between sections in the editor
+  // keeps the same component instance.
+  const identityRef = useRef<ThemeSignalIdentity>({});
+  identityRef.current = resolveIdentity(identity, context);
+
+  return useCallback(
+    (name, facts = {}, options = {}) =>
+      emitThemeSignal(name, { ...identityRef.current, ...facts }, options),
+    []
+  );
+};
+
+export interface UseThemeSignalOnceOptions {
+  name: ThemeSignalName;
+  /**
+   * What makes this occurrence distinct. A null or undefined key means "not
+   * ready yet" and reports nothing — the shape that stops a section from
+   * reporting before the data it describes has resolved.
+   */
+  key: string | number | null | undefined;
+  /** Report only once this turns true. Defaults to true. */
+  when?: boolean;
+  facts?: ThemeSignalFacts;
+  identity?: ThemeSignalIdentity;
+}
+
+/**
+ * The "report it the first time it becomes true" case: a section seen, a promo
+ * shown, a countdown finished.
+ *
+ * Latched on a ref, deliberately PER MOUNT rather than per route, exactly as
+ * the page-scope commerce emitter latches its own events: a client-side visit
+ * mounts a fresh unit and must report again, while re-renders of the same
+ * mount — a breakpoint change, context identity churn — must not. The module's
+ * route tally still applies on top, so neither guard can be forgotten.
+ */
+export const useThemeSignalOnce = ({
+  name,
+  key,
+  when = true,
+  facts,
+  identity
+}: UseThemeSignalOnceOptions): void => {
+  const signal = useThemeSignal(identity);
+  const reported = useRef<string | null>(null);
+
+  // Read through a ref so a fresh object literal on every render does not
+  // re-run the effect; the facts that matter are fixed by the key.
+  const factsRef = useRef<ThemeSignalFacts | undefined>(facts);
+  factsRef.current = facts;
+
+  useEffect(() => {
+    if (!when) return;
+    if (key === null || key === undefined) return;
+    if (isThemeSignalMuted()) return;
+
+    const latchKey = String(key);
+    if (reported.current === latchKey) return;
+    reported.current = latchKey;
+
+    signal(name, factsRef.current ?? {}, { key: latchKey, once: true });
+  }, [name, key, when, signal]);
+};

package/src/overlays/__tests__/server-read-path-client-free.test.ts

@@ -23,7 +23,11 @@ const SRC_ROOT = path.resolve(__dirname, '../..');
 /** Entry points that are read during a server render. */
 const SERVER_ENTRY_POINTS = [
   'chrome/theme-config-source.ts',
-  'overlays/modal-registry.ts'
+  'overlays/modal-registry.ts',
+  // The theme signal emitter is called from plain modules as well as from
+  // components, so it must stay reachable without dragging a client reference
+  // behind it — `browse-mode.ts` and any hook are one convenient import away.
+  'utils/theme-signal.ts'
 ];
 
 const CANDIDATE_EXTENSIONS = ['.ts', '.tsx', '/index.ts', '/index.tsx'];
@@ -61,7 +65,9 @@ const isTypeOnlyImport = (source: string, index: number): boolean => {
 const isClientModule = (source: string): boolean =>
   /^\s*(['"])use client\1/.test(source);
 
-const collectReachableModules = (entryPoints: string[]): Map<string, string> => {
+const collectReachableModules = (
+  entryPoints: string[]
+): Map<string, string> => {
   const visited = new Map<string, string>();
   const queue = entryPoints.map((entry) => path.join(SRC_ROOT, entry));
 

package/src/utils/__tests__/theme-signal.test.ts

@@ -0,0 +1,284 @@
+import {
+  __resetThemeSignalsForTests,
+  CUSTOM_SIGNAL_PREFIX,
+  DEFAULT_SIGNAL_CEILING,
+  emitThemeSignal,
+  isThemeSignalMuted,
+  SIGNAL_BUDGET_PER_ROUTE,
+  subscribeToThemeSignals,
+  THEME_SIGNAL_EVENT_NAME,
+  THEME_SIGNAL_NAMES,
+  type ThemeSignalDetail,
+  type ThemeSignalName
+} from '../theme-signal';
+import {
+  attachGa4DataLayerBridge,
+  COMMERCE_EVENT_NAME,
+  emitCommerceEvent
+} from '../analytics';
+import { resetDevWarnCacheForTests } from '../dev-warn';
+
+declare global {
+  interface Window {
+    __themeEditorDesigner?: boolean;
+    // Must match the augmentation in ../analytics, and the core package's.
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    dataLayer?: Object[];
+  }
+}
+
+const setPathname = (pathname: string) => {
+  window.history.replaceState({}, '', pathname);
+};
+
+describe('theme signals (ZERO-5156)', () => {
+  let received: ThemeSignalDetail[];
+  let detach: () => void;
+
+  beforeEach(() => {
+    received = [];
+    detach = subscribeToThemeSignals((detail) => received.push(detail));
+    __resetThemeSignalsForTests();
+    resetDevWarnCacheForTests();
+    delete window.__themeEditorDesigner;
+    setPathname('/');
+  });
+
+  afterEach(() => {
+    detach();
+    delete window.__themeEditorDesigner;
+  });
+
+  it('reports the moment under `name`, never `action`', () => {
+    emitThemeSignal('modal.opened', { modalId: 'size-guide' });
+
+    expect(received).toEqual([{ name: 'modal.opened', modalId: 'size-guide' }]);
+    // A bridge pointed at the wrong channel reads `action` and drops the
+    // frame rather than pushing a nameless event.
+    expect(received[0]).not.toHaveProperty('action');
+  });
+
+  it('is silent while the theme editor is attached, browse mode included', () => {
+    // The raw handshake flag, which stays true in browse mode — the exact
+    // state in which the block-level commerce emits currently report a
+    // designer's clicks as a shopper's.
+    window.__themeEditorDesigner = true;
+
+    expect(isThemeSignalMuted()).toBe(true);
+    expect(emitThemeSignal('slide.changed', { index: 2 })).toBe(false);
+    expect(received).toEqual([]);
+  });
+
+  it('reports on a storefront that is framed but has no editor attached', () => {
+    // Being inside an iframe is not evidence of the editor: a production
+    // storefront is legitimately framed by payment providers and marketplace
+    // previews, so framing is deliberately not part of the gate.
+    window.__themeEditorDesigner = false;
+
+    expect(
+      emitThemeSignal('section.seen', { sectionId: 'section-h3k9q' })
+    ).toBe(true);
+    expect(received).toHaveLength(1);
+  });
+
+  it('drops facts that are not flat scalars', () => {
+    emitThemeSignal('filter.applied', {
+      facetKey: 'color',
+      // Nothing may carry a product, a node or a form state onto the wire.
+      product: { pk: 42 } as never,
+      items: [1, 2] as never,
+      ratio: Number.NaN,
+      on: true
+    });
+
+    expect(received).toEqual([
+      { name: 'filter.applied', facetKey: 'color', on: true }
+    ]);
+  });
+
+  it('drops null and undefined facts instead of sending them', () => {
+    emitThemeSignal('nav.clicked', {
+      itemKey: 'women',
+      level: 1,
+      label: undefined,
+      url: null
+    });
+
+    expect(received).toEqual([
+      { name: 'nav.clicked', itemKey: 'women', level: 1 }
+    ]);
+  });
+
+  it('truncates a long string rather than refusing the moment', () => {
+    emitThemeSignal('share.clicked', { method: 'x'.repeat(200) });
+
+    expect(String(received[0].method)).toHaveLength(120);
+  });
+
+  it('cannot be renamed from inside its own payload', () => {
+    emitThemeSignal('promo.dismissed', {
+      name: 'purchase'
+    } as never);
+
+    expect(received[0].name).toBe('promo.dismissed');
+  });
+
+  it('refuses a name that is neither known nor brand-prefixed', () => {
+    expect(emitThemeSignal('slide_changed' as ThemeSignalName)).toBe(false);
+    expect(received).toEqual([]);
+  });
+
+  it('accepts a brand-authored name behind the reserved prefix', () => {
+    expect(
+      emitThemeSignal(`${CUSTOM_SIGNAL_PREFIX}lookbook.opened`, { look: 3 })
+    ).toBe(true);
+    expect(received[0].name).toBe('custom.lookbook.opened');
+  });
+
+  it('exports one frozen name list, so the vocabulary is pinnable', () => {
+    expect(new Set(THEME_SIGNAL_NAMES).size).toBe(THEME_SIGNAL_NAMES.length);
+    // Dot-namespaced, so no name can collide with a GA4 reserved or
+    // recommended event such as `share` or `video_start`.
+    for (const name of THEME_SIGNAL_NAMES) {
+      expect(name).toMatch(/^[a-z]+\.[a-z]+$/);
+    }
+  });
+
+  describe('latch and ceiling', () => {
+    it('reports a once-keyed moment a single time', () => {
+      const facts = { sectionId: 'section-h3k9q' };
+
+      expect(
+        emitThemeSignal('section.seen', facts, { key: 'hero', once: true })
+      ).toBe(true);
+      expect(
+        emitThemeSignal('section.seen', facts, { key: 'hero', once: true })
+      ).toBe(false);
+
+      expect(received).toHaveLength(1);
+    });
+
+    it('latches each key separately', () => {
+      emitThemeSignal('section.seen', {}, { key: 'hero', once: true });
+      emitThemeSignal('section.seen', {}, { key: 'footer-strip', once: true });
+
+      expect(received).toHaveLength(2);
+    });
+
+    it('stops a repeating moment at the default ceiling', () => {
+      for (let index = 0; index < DEFAULT_SIGNAL_CEILING + 5; index += 1) {
+        emitThemeSignal('slide.changed', { index }, { key: 'hero' });
+      }
+
+      expect(received).toHaveLength(DEFAULT_SIGNAL_CEILING);
+    });
+
+    it('lets a caller opt out of the ceiling explicitly', () => {
+      for (let index = 0; index < DEFAULT_SIGNAL_CEILING + 5; index += 1) {
+        emitThemeSignal(
+          'slide.changed',
+          { index },
+          { key: 'hero', ceiling: Infinity }
+        );
+      }
+
+      expect(received).toHaveLength(DEFAULT_SIGNAL_CEILING + 5);
+    });
+
+    it('starts counting again after a client-side navigation', () => {
+      emitThemeSignal('section.seen', {}, { key: 'hero', once: true });
+      expect(received).toHaveLength(1);
+
+      setPathname('/kadin');
+      emitThemeSignal('section.seen', {}, { key: 'hero', once: true });
+
+      // A fresh page must report again; a re-render of the same page must not.
+      expect(received).toHaveLength(2);
+    });
+
+    it('bounds the whole page, not just each key', () => {
+      for (let index = 0; index < SIGNAL_BUDGET_PER_ROUTE + 10; index += 1) {
+        emitThemeSignal(
+          'section.seen',
+          {},
+          { key: `section-${index}`, once: true }
+        );
+      }
+
+      expect(received).toHaveLength(SIGNAL_BUDGET_PER_ROUTE);
+    });
+  });
+
+  describe('channel separation', () => {
+    it('does not reach a listener on the commerce channel', () => {
+      const commerce: unknown[] = [];
+      const onCommerce = (event: Event) =>
+        commerce.push((event as CustomEvent).detail);
+      window.addEventListener(COMMERCE_EVENT_NAME, onCommerce);
+
+      emitThemeSignal('modal.opened', { modalId: 'newsletter' });
+
+      window.removeEventListener(COMMERCE_EVENT_NAME, onCommerce);
+      expect(commerce).toEqual([]);
+    });
+
+    it('leaves the GA4 commerce bridge untouched', () => {
+      // The bridge ends in an unconditional flat push, so a UI moment reaching
+      // it would write junk events into a live property.
+      window.dataLayer = [];
+      const detachBridge = attachGa4DataLayerBridge();
+
+      emitThemeSignal('promo.dismissed', { messageIndex: 1 });
+
+      expect(window.dataLayer).toEqual([]);
+
+      // The commerce channel still works, so the bridge itself is alive.
+      emitCommerceEvent('search', { searchTerm: 'elbise' });
+      expect(window.dataLayer).toHaveLength(1);
+
+      detachBridge();
+      delete window.dataLayer;
+    });
+  });
+
+  describe('subscription', () => {
+    it('filters to the moments a listener asked for', () => {
+      const wanted: ThemeSignalDetail[] = [];
+      const stop = subscribeToThemeSignals((detail) => wanted.push(detail), {
+        names: ['modal.opened']
+      });
+
+      emitThemeSignal('modal.opened', { modalId: 'a' });
+      emitThemeSignal('tab.changed', { index: 1 });
+
+      stop();
+      expect(wanted.map((detail) => detail.name)).toEqual(['modal.opened']);
+    });
+
+    it('survives a listener that throws', () => {
+      const stop = subscribeToThemeSignals(() => {
+        throw new Error('brand bridge is broken');
+      });
+
+      expect(() => emitThemeSignal('tab.changed', { index: 2 })).not.toThrow();
+      // The healthy listener registered in beforeEach still received it.
+      expect(received).toHaveLength(1);
+
+      stop();
+    });
+
+    it('stops delivering once detached', () => {
+      const seen: ThemeSignalDetail[] = [];
+      const stop = subscribeToThemeSignals((detail) => seen.push(detail));
+
+      stop();
+      emitThemeSignal('drawer.opened', {});
+
+      expect(seen).toEqual([]);
+    });
+  });
+
+  it('uses the documented event name', () => {
+    expect(THEME_SIGNAL_EVENT_NAME).toBe('pz:theme');
+  });
+});