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

package/CHANGELOG.md

@@ -1,12 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.128-beta.0
+## 2.0.128
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd757]
-  - @akinon/next@2.0.128-beta.0
-  - @akinon/theme-contract@2.0.128-beta.0
+- 2bf278e: ZERO-5156: Add a shared event API for theme-composed sections and blocks
+  - @akinon/next@2.0.128
+  - @akinon/theme-contract@2.0.128
 
 ## 2.0.127
 

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.128-beta.0",
+  "version": "2.0.128",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.128-beta.0",
+    "@akinon/next": "2.0.128",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.128-beta.0",
+    "@akinon/theme-contract": "2.0.128",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "react-multi-carousel": "2.8.4",
@@ -21,7 +21,7 @@
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.128-beta.0",
+    "@akinon/next": "2.0.128",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/commerce-channel-frozen.test.ts

@@ -0,0 +1,118 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * The commerce channel is closed. New moments go through `emitThemeSignal`.
+ *
+ * Two emit paths now live side by side on purpose (ZERO-5156): the commerce
+ * events keep dispatching `pz:commerce` exactly as they always have, and every
+ * new interaction moment dispatches `pz:theme`. Nothing enforces that split at
+ * runtime — the older emitter is the one everyone has already seen, its name
+ * reads generic, and adding a seventeenth call to it is one copy-paste away.
+ *
+ * The consequence of getting it wrong is not local. The one bridge that exists
+ * in the fleet (gant_next) ends in an unconditional flat dataLayer push, so a
+ * UI moment named on the commerce channel starts writing bare events into a
+ * live GA4 property the day that brand bumps this package — with nothing
+ * failing anywhere in this repo.
+ *
+ * So the call sites are frozen here. Adding a genuinely new COMMERCE event is
+ * a deliberate act: update this map in the same change, and check the
+ * consuming brand bridge maps the action rather than flat-pushing it.
+ */
+
+const SRC_ROOT = path.resolve(__dirname, '..');
+
+/** file path relative to src -> number of `emitCommerceEvent(` calls. */
+const FROZEN_COMMERCE_CALL_SITES: Record<string, number> = {
+  'blocks/account-menu-block.tsx': 1,
+  'blocks/add-to-cart-block.tsx': 1,
+  'blocks/auth-form-block.tsx': 3,
+  'blocks/basket-items-block.tsx': 1,
+  'blocks/favorite-button-block.tsx': 1,
+  'blocks/favourites-grid-block.tsx': 3,
+  'blocks/group-block.tsx': 1,
+  'blocks/product-grid-block.tsx': 2,
+  'blocks/product-recommendations-block.tsx': 1,
+  'blocks/search-box-block.tsx': 1,
+  // One call, four page-scope actions behind it (view_item, view_cart,
+  // begin_checkout, purchase) — the action is a variable there.
+  'theme-placeholder-wrapper.tsx': 1
+};
+
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx']);
+
+/** The emitter's own module: the definition and its GA4 bridge live there. */
+const EXCLUDED_FILES = new Set(['utils/analytics.ts']);
+
+const collectSourceFiles = (directory: string, collected: string[] = []) => {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const full = path.join(directory, entry.name);
+
+    if (entry.isDirectory()) {
+      if (entry.name === '__tests__' || entry.name === 'node_modules') continue;
+      collectSourceFiles(full, collected);
+      continue;
+    }
+
+    if (!SOURCE_EXTENSIONS.has(path.extname(entry.name))) continue;
+    if (entry.name.endsWith('.test.ts') || entry.name.endsWith('.test.tsx')) {
+      continue;
+    }
+
+    collected.push(full);
+  }
+
+  return collected;
+};
+
+const countCommerceCalls = (): Record<string, number> => {
+  const counts: Record<string, number> = {};
+
+  for (const file of collectSourceFiles(SRC_ROOT)) {
+    const relative = path.relative(SRC_ROOT, file).split(path.sep).join('/');
+    if (EXCLUDED_FILES.has(relative)) continue;
+
+    const source = fs.readFileSync(file, 'utf8');
+    const matches = source.match(/emitCommerceEvent\s*\(/g);
+    if (matches) counts[relative] = matches.length;
+  }
+
+  return counts;
+};
+
+describe('commerce channel call sites', () => {
+  it('has not grown — new moments belong on emitThemeSignal', () => {
+    expect(countCommerceCalls()).toEqual(FROZEN_COMMERCE_CALL_SITES);
+  });
+
+  it('keeps the two channels distinct', () => {
+    const analytics = fs.readFileSync(
+      path.join(SRC_ROOT, 'utils/analytics.ts'),
+      'utf8'
+    );
+    const signal = fs.readFileSync(
+      path.join(SRC_ROOT, 'utils/theme-signal.ts'),
+      'utf8'
+    );
+
+    // The commerce bridge must never listen to the new channel: it flat-pushes
+    // anything it does not recognise as an ecommerce verb.
+    expect(analytics).not.toContain('pz:theme');
+    expect(analytics).not.toContain('theme-signal');
+    expect(signal).not.toContain("'pz:commerce'");
+  });
+
+  it('keeps the new emitter callable from a server graph', () => {
+    // Guarded properly by the import-walking boundary test; this is the cheap
+    // first line, because a directive added here is the single change that
+    // would break every brand build while the whole suite stays green.
+    const signal = fs.readFileSync(
+      path.join(SRC_ROOT, 'utils/theme-signal.ts'),
+      'utf8'
+    );
+
+    expect(signal).not.toMatch(/^\s*(['"])use client\1/);
+    expect(signal).not.toContain('server-only');
+  });
+});

package/src/custom/README-sections.md

@@ -296,6 +296,19 @@ the English storefront too. Run each one through `useLocalizeHref()` where
 you read it, or render it with `ThemeLink`. See "Links and the page's
 language" in [README.md](./README.md).
 
+## Reporting what happened
+
+Identical to a custom block, and documented in `README.md` under **Reporting
+what happened**: `useThemeSignal()` picks the section up from the context it
+already renders in, so `sectionId` and `sectionType` ride the payload with
+nothing to thread. `useThemeSignalOnce({ name: 'section.seen', key })` is the
+form a section usually wants — it reports the first time a key resolves and
+stays quiet on every re-render after it.
+
+Do not guard a report with `isDesigner`. The emitter is already silent while the
+editor is attached, browse mode included, and that prop goes false under **Use
+preview** while the editor is still open.
+
 ## Parts must live on YOUR markup
 
 Part rules are generated with an ownership guard that excludes anything inside a

package/src/custom/README.md

@@ -303,6 +303,85 @@ attached". The editor's **Use preview** toggle turns it off while the editor
 stays open, so the canvas behaves like the live site: whatever you held open
 closes and links navigate again.
 
+## Reporting what happened
+
+A custom unit can report a moment — a strip was seen, a lookbook was opened, a
+tab was changed — and the brand decides in its own repo what that moment means
+to GA4, Insider or its own service. The theme never names an analytics event and
+never pushes to a tag manager, which is why one renderer can serve brands whose
+schemas disagree.
+
+```tsx
+import { useThemeSignal } from '@akinon/pz-theme/src/custom';
+
+const LookbookStrip = () => {
+  // Identity comes from the context this unit already renders inside, so the
+  // placeholder, section and block ride the payload with no props to thread.
+  const signal = useThemeSignal();
+
+  return (
+    <button onClick={() => signal('custom.lookbook.opened', { look: 3 })}>
+      …
+    </button>
+  );
+};
+```
+
+For the "first time it becomes true" case — a section seen, a promo shown — use
+the latching form. A `null` key means "not ready yet" and reports nothing, which
+is what stops a unit reporting before the data it describes has resolved:
+
+```tsx
+useThemeSignalOnce({
+  name: 'section.seen',
+  key: inView ? lookbookId : null,
+  facts: { lookSlot: 'home-hero' }
+});
+```
+
+Outside React — a module-level bus, a delegated document listener — call the
+primitive directly:
+
+```ts
+import { emitThemeSignal } from '@akinon/pz-theme/src/custom';
+
+emitThemeSignal('modal.opened', { modalId: id }, { key: id, once: true });
+```
+
+The brand listens once, anywhere in its client tree, and maps:
+
+```tsx
+import { subscribeToThemeSignals } from '@akinon/pz-theme/src/custom';
+
+useEffect(
+  () =>
+    subscribeToThemeSignals((detail) => {
+      if (detail.name !== 'custom.lookbook.opened') return;
+      window.dataLayer.push({ event: 'lookbook_open', look: detail.look });
+    }),
+  []
+);
+```
+
+Four things the emitter does so a call site does not have to:
+
+- **It is silent while the editor is attached, browse mode included.** It reads
+  the editor handshake flag itself, so do NOT wrap a report in an `isDesigner`
+  check — that prop means "the editing affordances are on", goes false under
+  **Use preview**, and a report guarded on it reports a designer's clicks as a
+  shopper's.
+- **`{ key, once: true }` is the latch**, reset on client-side navigation. A
+  repeat inside the same page view is a no-op.
+- **A ceiling** — 24 per key, 200 per page view. An autoplaying carousel would
+  otherwise emit continuously, billed to whatever the brand forwards to.
+- **The payload is closed to flat scalars** and sanitized at emit. A product
+  object, a DOM node or shopper-typed text is dropped with a dev warning, which
+  is how the no-PII rule is enforced rather than reviewed.
+
+A brand's own moment must be namespaced `custom.<something>`, so it can never
+collide with a name this package adds later and a bridge can tell the two apart.
+The package's own names are listed in `THEME_SIGNAL_NAMES`.
+
 ## Styling parts
 
 The `field-<key>` parts come free from `ThemeEditable`. Everything else a block

package/src/custom/__tests__/custom-entry-exports.test.tsx

@@ -9,6 +9,8 @@ import * as blockContext from '../block-context';
 import * as overlay from '../../hooks/use-overlay';
 import * as themeLink from '../../components/theme-link';
 import * as localizeHrefHook from '../../hooks/use-localize-href';
+import * as themeSignal from '../../utils/theme-signal';
+import * as themeSignalHook from '../../hooks/use-theme-signal';
 import { resetCustomCollection } from '../collect';
 import { CustomSectionHost } from '../section-host';
 import type { Section } from '../../theme-section';
@@ -22,10 +24,15 @@ import {
   defineCustomSection,
   setChromeMode,
   useChromeMode,
+  emitThemeSignal,
+  subscribeToThemeSignals,
   ThemeLink,
+  THEME_SIGNAL_NAMES,
   useCustomBlockContext,
   useLocalizeHref,
-  useOverlay
+  useOverlay,
+  useThemeSignal,
+  useThemeSignalOnce
 } from '../index';
 import type {
   ChromeMode,
@@ -46,7 +53,7 @@ const section = (): Section =>
     order: 0,
     hidden: false,
     blocks: []
-  } as unknown as Section);
+  }) as unknown as Section;
 
 /** Reports what a developer's own code would read from the hook. */
 function EditorProbe() {
@@ -261,3 +268,30 @@ describe('the custom entry exports ZERO-5100 added', () => {
     expect(useLocalizeHref).toBe(localizeHrefHook.useLocalizeHref);
   });
 });
+
+describe('the custom entry exports ZERO-5156 added', () => {
+  // A custom unit reports moments through the same barrel it imports
+  // everything else from; the package root is unreachable from a client
+  // module, so the reporting API has to be here too.
+  it('re-exports the emitter and its hooks rather than second copies', () => {
+    expect(emitThemeSignal).toBe(themeSignal.emitThemeSignal);
+    expect(subscribeToThemeSignals).toBe(themeSignal.subscribeToThemeSignals);
+    expect(THEME_SIGNAL_NAMES).toBe(themeSignal.THEME_SIGNAL_NAMES);
+    expect(useThemeSignal).toBe(themeSignalHook.useThemeSignal);
+    expect(useThemeSignalOnce).toBe(themeSignalHook.useThemeSignalOnce);
+  });
+
+  it('documents the reporting API where a brand developer will look', () => {
+    // The README is the brand-facing doc for this entry, and the one trap
+    // that costs a brand real data — do not guard a report with `isDesigner` —
+    // only exists in prose.
+    const readme = fs.readFileSync(
+      path.join(__dirname, '..', 'README.md'),
+      'utf8'
+    );
+
+    expect(readme).toContain('useThemeSignal');
+    expect(readme).toContain('subscribeToThemeSignals');
+    expect(readme).toContain('custom.');
+  });
+});

package/src/custom/index.ts

@@ -183,6 +183,44 @@ export type { CustomBlockContextValue } from './block-context';
 export { useOverlay } from '../hooks/use-overlay';
 export type { OverlayHandle, UseOverlayOptions } from '../hooks/use-overlay';
 
+/**
+ * Reporting a moment (ZERO-5156).
+ *
+ * A custom section or block reports what happened — a strip was seen, a
+ * lookbook was opened — and the brand decides in its own repo what that means
+ * to GA4, Insider or its own service. The theme never names an analytics
+ * event and never pushes to a tag manager.
+ *
+ * A brand's own moment is namespaced: `custom.lookbook.opened`. The hook
+ * resolves placeholder, section and block identity from the context a custom
+ * unit already renders inside, so nothing has to be threaded through.
+ *
+ * Both are inert while the theme editor is attached, browse mode included —
+ * the emitter reads the editor handshake flag itself, so a custom unit must
+ * NOT add its own `isDesigner` check around a report.
+ */
+export {
+  emitThemeSignal,
+  isThemeSignalMuted,
+  subscribeToThemeSignals,
+  CUSTOM_SIGNAL_PREFIX,
+  THEME_SIGNAL_EVENT_NAME,
+  THEME_SIGNAL_NAMES
+} from '../utils/theme-signal';
+export type {
+  ThemeSignalDetail,
+  ThemeSignalFacts,
+  ThemeSignalIdentity,
+  ThemeSignalName,
+  ThemeSignalOptions,
+  ThemeSignalValue
+} from '../utils/theme-signal';
+export { useThemeSignal, useThemeSignalOnce } from '../hooks/use-theme-signal';
+export type {
+  ThemeSignalEmit,
+  UseThemeSignalOnceOptions
+} from '../hooks/use-theme-signal';
+
 // What the editor bridge announces. Exported here rather than kept internal
 // because a brand that mounts its own announce path needs the same payload the
 // package would have sent, not a second construction of it.

package/src/hooks/__tests__/use-theme-signal.test.tsx

@@ -0,0 +1,241 @@
+import React from 'react';
+import { renderHook } from '@testing-library/react';
+
+import {
+  CustomBlockContext,
+  type CustomBlockContextValue
+} from '../../custom/block-context';
+import {
+  __resetThemeSignalsForTests,
+  subscribeToThemeSignals,
+  type ThemeSignalDetail
+} from '../../utils/theme-signal';
+import { useThemeSignal, useThemeSignalOnce } from '../use-theme-signal';
+
+declare global {
+  interface Window {
+    __themeEditorDesigner?: boolean;
+  }
+}
+
+const customBlockContext = (
+  overrides: Partial<CustomBlockContextValue> = {}
+): CustomBlockContextValue =>
+  ({
+    node: { id: 'block-d4k1z', type: 'promo-strip' },
+    scope: 'block',
+    block: { id: 'block-d4k1z', type: 'promo-strip' },
+    placeholderId: 'theme-homepage-body',
+    sectionId: 'section-h3k9q',
+    isDesigner: false,
+    currentBreakpoint: 'desktop',
+    ...overrides
+  }) as CustomBlockContextValue;
+
+const wrapperFor = (value: CustomBlockContextValue) => {
+  const Wrapper = ({ children }: { children: React.ReactNode }) => (
+    <CustomBlockContext.Provider value={value}>
+      {children}
+    </CustomBlockContext.Provider>
+  );
+
+  return Wrapper;
+};
+
+describe('useThemeSignal (ZERO-5156)', () => {
+  let received: ThemeSignalDetail[];
+  let detach: () => void;
+
+  beforeEach(() => {
+    received = [];
+    detach = subscribeToThemeSignals((detail) => received.push(detail));
+    __resetThemeSignalsForTests();
+    delete window.__themeEditorDesigner;
+  });
+
+  afterEach(() => {
+    detach();
+    delete window.__themeEditorDesigner;
+  });
+
+  it('carries the identity a renderer passes explicitly', () => {
+    const { result } = renderHook(() =>
+      useThemeSignal({
+        placeholderId: 'theme-homepage-body',
+        sectionId: 'section-h3k9q',
+        blockId: 'block-w2m4t',
+        blockType: 'slider'
+      })
+    );
+
+    result.current('slide.changed', { index: 1, total: 3 });
+
+    expect(received).toEqual([
+      {
+        name: 'slide.changed',
+        placeholderId: 'theme-homepage-body',
+        sectionId: 'section-h3k9q',
+        blockId: 'block-w2m4t',
+        blockType: 'slider',
+        index: 1,
+        total: 3
+      }
+    ]);
+  });
+
+  it('reads identity from the custom unit it renders inside', () => {
+    const { result } = renderHook(() => useThemeSignal(), {
+      wrapper: wrapperFor(customBlockContext())
+    });
+
+    result.current('custom.promo.shown');
+
+    expect(received[0]).toMatchObject({
+      placeholderId: 'theme-homepage-body',
+      sectionId: 'section-h3k9q',
+      blockId: 'block-d4k1z',
+      blockType: 'promo-strip'
+    });
+  });
+
+  it('reports a custom section under sectionType, not blockType', () => {
+    const { result } = renderHook(() => useThemeSignal(), {
+      wrapper: wrapperFor(
+        customBlockContext({
+          scope: 'section',
+          node: { id: 'section-h3k9q', type: 'custom.store-header' } as never
+        })
+      )
+    });
+
+    result.current('custom.header.pinned');
+
+    expect(received[0].sectionType).toBe('custom.store-header');
+    expect(received[0]).not.toHaveProperty('blockId');
+  });
+
+  it('omits identity it does not have rather than inventing it', () => {
+    const { result } = renderHook(() => useThemeSignal());
+
+    result.current('modal.opened', { modalId: 'size-guide' });
+
+    expect(received).toEqual([{ name: 'modal.opened', modalId: 'size-guide' }]);
+  });
+
+  it('lets a caller override one inherited field without losing the rest', () => {
+    const { result } = renderHook(() => useThemeSignal(), {
+      wrapper: wrapperFor(customBlockContext())
+    });
+
+    result.current('nav.clicked', { blockId: 'block-inner', itemKey: 'women' });
+
+    expect(received[0]).toMatchObject({
+      sectionId: 'section-h3k9q',
+      blockId: 'block-inner',
+      itemKey: 'women'
+    });
+  });
+
+  it('returns a stable callback across re-renders', () => {
+    const { result, rerender } = renderHook(
+      ({ id }: { id: string }) => useThemeSignal({ sectionId: id }),
+      { initialProps: { id: 'section-a' } }
+    );
+
+    const first = result.current;
+    rerender({ id: 'section-b' });
+
+    expect(result.current).toBe(first);
+    // Stable, but not stale: the identity it sends is the current one.
+    result.current('section.seen');
+    expect(received[0].sectionId).toBe('section-b');
+  });
+});
+
+describe('useThemeSignalOnce (ZERO-5156)', () => {
+  let received: ThemeSignalDetail[];
+  let detach: () => void;
+
+  beforeEach(() => {
+    received = [];
+    detach = subscribeToThemeSignals((detail) => received.push(detail));
+    __resetThemeSignalsForTests();
+    delete window.__themeEditorDesigner;
+  });
+
+  afterEach(() => {
+    detach();
+    delete window.__themeEditorDesigner;
+  });
+
+  it('reports the first time the condition becomes true', () => {
+    const { rerender } = renderHook(
+      ({ when }: { when: boolean }) =>
+        useThemeSignalOnce({
+          name: 'section.seen',
+          key: 'hero',
+          when,
+          identity: { sectionId: 'section-h3k9q' }
+        }),
+      { initialProps: { when: false } }
+    );
+
+    expect(received).toEqual([]);
+
+    rerender({ when: true });
+    rerender({ when: true });
+
+    expect(received).toEqual([
+      { name: 'section.seen', sectionId: 'section-h3k9q' }
+    ]);
+  });
+
+  it('waits for a key rather than reporting an unresolved moment', () => {
+    const { rerender } = renderHook(
+      ({ key }: { key: string | null }) =>
+        useThemeSignalOnce({ name: 'section.seen', key }),
+      { initialProps: { key: null as string | null } }
+    );
+
+    expect(received).toEqual([]);
+
+    rerender({ key: 'hero' });
+    expect(received).toHaveLength(1);
+  });
+
+  it('reports again when the key changes', () => {
+    const { rerender } = renderHook(
+      ({ key }: { key: string }) =>
+        useThemeSignalOnce({ name: 'slide.changed', key }),
+      { initialProps: { key: 'slide-1' } }
+    );
+
+    rerender({ key: 'slide-2' });
+
+    expect(received).toHaveLength(2);
+  });
+
+  it('reports again on a fresh mount, the way a client-side visit does', () => {
+    const render = () =>
+      renderHook(() =>
+        useThemeSignalOnce({ name: 'section.seen', key: 'hero' })
+      );
+
+    const first = render();
+    first.unmount();
+    // The module tally is per route; a new visit to the same page mounts a
+    // fresh unit, which is exactly the case the page-scope emitter refires on.
+    __resetThemeSignalsForTests();
+    render();
+
+    expect(received).toHaveLength(2);
+  });
+
+  it('stays silent while the editor is attached', () => {
+    window.__themeEditorDesigner = true;
+
+    renderHook(() => useThemeSignalOnce({ name: 'section.seen', key: 'hero' }));
+
+    expect(received).toEqual([]);
+  });
+});