@akinon/pz-theme 2.0.163-rc.0 → 2.0.164-beta.0

package/src/custom/property-types.ts

@@ -33,20 +33,19 @@ export type PropertyType = (typeof CUSTOM_PROPERTY_TYPES)[number];
  * The subset whose value provably survives the full round trip — panel write,
  * persistence, and resolution back into a prop.
  *
- * The two excluded members are excluded for reasons that were verified, not
- * guessed: `multiselect` and `localetext` are stored UNBUCKETED by the editor
- * (`theme-basic-properties.tsx:1547-1548` passes arrays and locale objects
- * through without the per-breakpoint wrapper). `getResponsiveValue` then
- * rejects an array with a devWarn and returns the fallback, and a locale
- * object has no `desktop` key so it does too. They can never deliver a
- * value until a per-type resolver exists.
+ * The three excluded members are excluded for reasons that were verified, not
+ * guessed:
  *
- * `richtext` is the one type with such a resolver. The editor's rich text
- * control writes per language (`{ tr: '<p>…</p>', en: … }`, unbucketed, like
- * `localetext`), so `useThemeSetting` reads the page's language out of the
- * map before the breakpoint read, then passes the html through
- * `sanitizeRichText`, a DOM-free allowlist, so a block can hand it to
- * `dangerouslySetInnerHTML` on the server as well as the client.
+ * - `multiselect` and `localetext` are stored UNBUCKETED by the editor
+ *   (`theme-basic-properties.tsx:1547-1548` passes arrays and locale objects
+ *   through without the per-breakpoint wrapper). `getResponsiveValue` then
+ *   rejects an array with a devWarn and returns the fallback, and a locale
+ *   object has no `desktop` key so it does too. They can never deliver a
+ *   value until a per-type resolver exists.
+ * - `richtext` has no safe renderer here. The allowlist sanitizer this repo
+ *   already owns parses by assigning to `innerHTML` on a live element, so the
+ *   sink is its first act — and pz-theme renders server-side, where there is
+ *   no `document` at all.
  *
  * Declaring one of these throws at define time rather than shipping a control
  * that silently shows the default forever.
@@ -60,11 +59,12 @@ export const SUPPORTED_PROPERTY_TYPES: readonly PropertyType[] = [
   'color',
   'image',
   'file',
-  'richtext',
   'typography',
   'icon'
 ];
 
-export const isSupportedPropertyType = (type: unknown): type is PropertyType =>
+export const isSupportedPropertyType = (
+  type: unknown
+): type is PropertyType =>
   typeof type === 'string' &&
   (SUPPORTED_PROPERTY_TYPES as readonly string[]).includes(type);

package/src/custom/use-theme-setting.ts

@@ -1,7 +1,6 @@
 'use client';
 
 import { getResponsiveValue } from '../utils';
-import { sanitizeRichText } from '../utils/sanitize-rich-text';
 import { devWarn } from '../utils/dev-warn';
 import {
   isLocalizedValue,
@@ -239,11 +238,6 @@ export function useThemeSetting<
 
   const defaults = splitDefault(declaration, valueLocale);
 
-  const finish = (value: unknown): TValue =>
-    (declaration.type === 'richtext'
-      ? sanitizeRichText(typeof value === 'string' ? value : '')
-      : value) as TValue;
-
   if (!context) {
     // A missing block context is never an error on its own: a developer
     // previewing the component in a storybook or a unit test should see the
@@ -260,7 +254,7 @@ export function useThemeSetting<
         `unreachable and the declared default is used instead. Render this ` +
         `component through a block registered with registerCustomBlocks().`
     );
-    return finish(defaults.page);
+    return defaults.page as TValue;
   }
 
   // Reported on every render rather than once from an effect: the collection
@@ -277,17 +271,7 @@ export function useThemeSetting<
   // attribute keys that were never declared. `node` rather than `block` so a
   // setting declared inside a custom SECTION reads the section's own
   // properties, which is where the editor writes it.
-  const authored = context.node.properties?.[key];
-
-  // The rich text control writes per language — `{ tr: '<p>…</p>', en: … }` —
-  // and the editor stores that map as it is, with no breakpoint key: the same
-  // shape that keeps `localetext` out (see `property-types.ts`). Read the
-  // page's language out of it first; what is left is a string or a breakpoint
-  // map, which the responsive read below already understands.
-  const stored =
-    declaration.type === 'richtext'
-      ? resolveLocalizedValue(authored, valueLocale)
-      : authored;
+  const stored = context.node.properties?.[key];
 
   // The sentinel again, for the same reason: handing `getResponsiveValue` an
   // undefined fallback would resolve an undeclared default to `''`, so a
@@ -296,15 +280,15 @@ export function useThemeSetting<
   const resolved = getResponsiveValue(stored, breakpoint, NOT_AUTHORED);
 
   if (resolved === NOT_AUTHORED) {
-    return finish(resolveAuthoredDefault(defaults.page, breakpoint));
+    return resolveAuthoredDefault(defaults.page, breakpoint) as TValue;
   }
 
   // The default-language text as the editor seeded it when the block was
   // placed, never changed since: still the author's copy, so it follows the
   // page's language. Anything the merchant typed is theirs and shows as typed.
   if (defaults.perLocale && resolved === defaults.base) {
-    return finish(defaults.page);
+    return defaults.page as TValue;
   }
 
-  return finish(resolved);
+  return resolved as TValue;
 }

package/src/editor-locale-bridge.tsx

@@ -4,28 +4,14 @@ import { useEffect } from 'react';
 import { useLocalization } from '@akinon/next/hooks';
 
 import { isTrustedEditorEvent, postToEditor } from './editor-bridge';
-import { useValueLocale } from './utils/localized-value';
 
 /**
  * The storefront half of the editor's Language dropdown.
  *
  * The editor starts that dropdown with English only and fills it from the
- * `LOCALE_UPDATE` frame the preview posts (`{ locale, locales, defaultLocale }`);
- * when the merchant picks another language it posts `LOCALE_UPDATE` back and
- * expects the preview to follow.
- *
- * The frame carries the storefront's default language as well. The editor's
- * per-language text controls store a plain string in that language and a map
- * in every other, so an editor that never heard it assumed English and gave
- * every Turkish-default store a stray `en` key (ZERO-5296).
- *
- * It is posted BEFORE the document reports ready (`IFRAME_READY`): the bridge
- * is a child of the placeholder wrapper, whose own effect posts that frame,
- * and React runs a child's effects first. The editor relies on the order — it
- * holds every per-language write until the preview is ready, and takes
- * "ready without languages" to mean a storefront that will never send them.
- *
- * For a long time the only code answering either direction
+ * `LOCALE_UPDATE` frame the preview posts (`{ locale, locales }`); when the
+ * merchant picks another language it posts `LOCALE_UPDATE` back and expects the
+ * preview to follow. For a long time the only code answering either direction
  * was the app-template's `LanguageSelect` — brand code. A brand whose header no
  * longer renders that component (a header composed through ChromeSlot, a
  * custom header section, a project older than the template) left the editor
@@ -68,7 +54,6 @@ export interface EditorLocaleOption {
 interface LocaleState {
   locale: string;
   locales: EditorLocaleOption[];
-  defaultLocale?: string;
   setLocale: (locale: string) => void;
 }
 
@@ -101,22 +86,15 @@ const toEditorLocales = (locales: unknown): EditorLocaleOption[] =>
           : entry.value
     }));
 
-const announcementKey = ({
-  locale,
-  locales,
-  defaultLocale
-}: Omit<LocaleState, 'setLocale'>) =>
-  JSON.stringify([locale, locales, defaultLocale ?? null]);
+const announcementKey = (locale: string, locales: EditorLocaleOption[]) =>
+  JSON.stringify([locale, locales]);
 
-const announce = ({ locale, locales, defaultLocale }: LocaleState) => {
-  const key = announcementKey({ locale, locales, defaultLocale });
+const announce = ({ locale, locales }: LocaleState) => {
+  const key = announcementKey(locale, locales);
   if (key === lastAnnounced) return;
   lastAnnounced = key;
 
-  postToEditor({
-    type: 'LOCALE_UPDATE',
-    data: { locale, locales, defaultLocale }
-  });
+  postToEditor({ type: 'LOCALE_UPDATE', data: { locale, locales } });
 };
 
 const handleEditorMessage = (event: MessageEvent) => {
@@ -137,7 +115,7 @@ const handleEditorMessage = (event: MessageEvent) => {
 
   // The editor is already showing `requested`. Recording it as announced keeps
   // the switch from being echoed back when the new locale reaches the page.
-  lastAnnounced = announcementKey({ ...current, locale: requested });
+  lastAnnounced = announcementKey(requested, current.locales);
   current.setLocale(requested);
 };
 
@@ -148,7 +126,6 @@ const handleEditorMessage = (event: MessageEvent) => {
  */
 export function EditorLocaleBridge(): null {
   const { locale, locales, setLocale } = useLocalization();
-  const { defaultLocale } = useValueLocale();
 
   useEffect(() => {
     if (!isFramed()) return;
@@ -170,14 +147,9 @@ export function EditorLocaleBridge(): null {
   useEffect(() => {
     if (!isFramed() || !locale) return;
 
-    current = {
-      locale,
-      locales: toEditorLocales(locales),
-      defaultLocale,
-      setLocale
-    };
+    current = { locale, locales: toEditorLocales(locales), setLocale };
     announce(current);
-  }, [locale, locales, defaultLocale, setLocale]);
+  }, [locale, locales, setLocale]);
 
   return null;
 }

package/src/hooks/__tests__/use-list-impression.test.tsx

@@ -0,0 +1,228 @@
+import React, { useRef } from 'react';
+import { act, render } from '@testing-library/react';
+
+let pathname = '/';
+jest.mock('next/navigation', () => ({
+  usePathname: () => pathname
+}));
+
+import {
+  LIST_IMPRESSION_DWELL_MS,
+  useListImpression
+} from '../use-list-impression';
+import { COMMERCE_EVENT_NAME } from '../../utils/analytics';
+
+declare global {
+  interface Window {
+    __themeEditorDesigner?: boolean;
+  }
+}
+
+/**
+ * A product row that is not a listing grid — a collection carousel, a
+ * recommendations strip — reports its products as one view_item_list, named
+ * and identified as the list it is (ZERO-5305).
+ *
+ * The package's jsdom setup fills IntersectionObserver with a no-op, so every
+ * case is driven through this recording stand-in (as use-section-seen does).
+ */
+class RecordingObserver {
+  static instances: RecordingObserver[] = [];
+
+  callback: IntersectionObserverCallback;
+  options: IntersectionObserverInit | undefined;
+  observed: Element[] = [];
+  disconnected = false;
+
+  constructor(
+    callback: IntersectionObserverCallback,
+    options?: IntersectionObserverInit
+  ) {
+    this.callback = callback;
+    this.options = options;
+    RecordingObserver.instances.push(this);
+  }
+
+  observe(node: Element) {
+    this.observed.push(node);
+  }
+
+  unobserve() {}
+
+  disconnect() {
+    this.disconnected = true;
+  }
+
+  takeRecords() {
+    return [];
+  }
+
+  cross(isIntersecting: boolean) {
+    act(() => {
+      this.callback(
+        [
+          {
+            isIntersecting,
+            intersectionRatio: isIntersecting ? 1 : 0,
+            target: this.observed[0]
+          } as unknown as IntersectionObserverEntry
+        ],
+        this as unknown as IntersectionObserver
+      );
+    });
+  }
+}
+
+const latest = () =>
+  RecordingObserver.instances[RecordingObserver.instances.length - 1];
+
+const PRODUCTS = [
+  { pk: 1, base_code: 'B1', name: 'Polo', price: '1499' },
+  { pk: 2, base_code: 'B2', name: 'Shirt', price: '2499' }
+];
+
+const Row = ({
+  products = PRODUCTS,
+  enabled = true,
+  refreshKey,
+  currency
+}: {
+  products?: Record<string, unknown>[] | null;
+  enabled?: boolean;
+  refreshKey?: string;
+  currency?: string;
+}) => {
+  const ref = useRef<HTMLDivElement>(null);
+  useListImpression({
+    ref,
+    products,
+    listId: 'collection-12',
+    listName: 'New Arrivals',
+    enabled,
+    refreshKey,
+    currency
+  });
+  return <div ref={ref} />;
+};
+
+const tick = (ms: number) =>
+  act(() => {
+    jest.advanceTimersByTime(ms);
+  });
+
+describe('useListImpression (ZERO-5305)', () => {
+  let received: Array<Record<string, unknown>>;
+  let originalObserver: unknown;
+  const onCommerce = (event: Event) =>
+    received.push((event as CustomEvent<Record<string, unknown>>).detail);
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+    pathname = '/';
+    received = [];
+    delete window.__themeEditorDesigner;
+    window.addEventListener(COMMERCE_EVENT_NAME, onCommerce);
+    RecordingObserver.instances = [];
+    originalObserver = (window as unknown as Record<string, unknown>)
+      .IntersectionObserver;
+    (window as unknown as Record<string, unknown>).IntersectionObserver =
+      RecordingObserver;
+  });
+
+  afterEach(() => {
+    window.removeEventListener(COMMERCE_EVENT_NAME, onCommerce);
+    (window as unknown as Record<string, unknown>).IntersectionObserver =
+      originalObserver;
+    delete window.__themeEditorDesigner;
+    jest.useRealTimers();
+  });
+
+  it('reports the row as one list once it has been on screen for the dwell', () => {
+    render(<Row />);
+
+    latest().cross(true);
+    expect(received).toEqual([]);
+    tick(LIST_IMPRESSION_DWELL_MS);
+
+    expect(received).toHaveLength(1);
+    expect(received[0]).toMatchObject({ action: 'view_item_list' });
+    expect(received[0].items).toEqual([
+      expect.objectContaining({
+        baseCode: 'B1',
+        index: 0,
+        listId: 'collection-12',
+        listName: 'New Arrivals'
+      }),
+      expect.objectContaining({
+        baseCode: 'B2',
+        index: 1,
+        listId: 'collection-12',
+        listName: 'New Arrivals'
+      })
+    ]);
+  });
+
+  it('reports once per route, however often the row comes back into view', () => {
+    render(<Row />);
+
+    latest().cross(true);
+    tick(LIST_IMPRESSION_DWELL_MS);
+    latest().cross(false);
+    latest().cross(true);
+    tick(LIST_IMPRESSION_DWELL_MS);
+
+    expect(received).toHaveLength(1);
+  });
+
+  it('reports nothing for a glance shorter than the dwell', () => {
+    render(<Row />);
+
+    latest().cross(true);
+    tick(LIST_IMPRESSION_DWELL_MS - 100);
+    latest().cross(false);
+    tick(LIST_IMPRESSION_DWELL_MS);
+
+    expect(received).toEqual([]);
+  });
+
+  it('watches nothing while there is nothing to list, or while disabled', () => {
+    render(<Row products={[]} />);
+    render(<Row products={null} />);
+    render(<Row enabled={false} />);
+
+    expect(RecordingObserver.instances).toHaveLength(0);
+  });
+
+  it('reports again when a list keyed by its content changes', () => {
+    const { rerender } = render(<Row refreshKey="1,2" />);
+    latest().cross(true);
+    tick(LIST_IMPRESSION_DWELL_MS);
+
+    rerender(<Row products={[PRODUCTS[1]]} refreshKey="2" />);
+    latest().cross(true);
+    tick(LIST_IMPRESSION_DWELL_MS);
+
+    expect(received).toHaveLength(2);
+    expect(received[1].items).toEqual([
+      expect.objectContaining({ baseCode: 'B2', index: 0 })
+    ]);
+  });
+
+  it('carries the currency the caller knows', () => {
+    render(<Row currency="try" />);
+    latest().cross(true);
+    tick(LIST_IMPRESSION_DWELL_MS);
+
+    expect(received[0]).toMatchObject({ currency: 'try' });
+  });
+
+  it('reports nothing inside the editor', () => {
+    window.__themeEditorDesigner = true;
+    render(<Row />);
+
+    latest().cross(true);
+    tick(LIST_IMPRESSION_DWELL_MS);
+
+    expect(received).toEqual([]);
+  });
+});

package/src/hooks/__tests__/use-section-seen.test.tsx

@@ -88,18 +88,26 @@ const DEFAULT_SECTION = { id: 'sec_hero', type: 'custom', order: 2 };
 
 const Section = ({
   placeholderId = 'home-body',
-  section = DEFAULT_SECTION
+  section = DEFAULT_SECTION,
+  productCount
 }: {
   placeholderId?: string;
   section?: {
     id: string;
     type: string;
     order?: number;
+    label?: string;
     properties?: Record<string, unknown>;
   };
+  productCount?: number;
 }) => {
   const ref = useRef<HTMLDivElement>(null);
-  useSectionSeen({ ref, section: section as never, placeholderId });
+  useSectionSeen({
+    ref,
+    section: section as never,
+    placeholderId,
+    productCount
+  });
 
   return <div ref={ref} data-testid="section" />;
 };
@@ -315,6 +323,51 @@ describe('section.seen (ZERO-5164)', () => {
     });
   });
 
+  describe('what the section is (ZERO-5305)', () => {
+    it('carries the label the merchant sees in the layer tree', () => {
+      render(
+        <Section
+          section={{ ...DEFAULT_SECTION, label: '  Summer Sale Hero  ' }}
+        />
+      );
+
+      latest().cross(true);
+      tick(SECTION_SEEN_DWELL_MS);
+
+      expect(received[0]).toMatchObject({ sectionLabel: 'Summer Sale Hero' });
+    });
+
+    it('caps a label at a display name’s length', () => {
+      render(
+        <Section section={{ ...DEFAULT_SECTION, label: 'x'.repeat(500) }} />
+      );
+
+      latest().cross(true);
+      tick(SECTION_SEEN_DWELL_MS);
+
+      expect(String(received[0].sectionLabel)).toHaveLength(120);
+    });
+
+    it('says how many products the section lists, so a bridge can tell a row from a banner', () => {
+      render(<Section productCount={8} />);
+
+      latest().cross(true);
+      tick(SECTION_SEEN_DWELL_MS);
+
+      expect(received[0]).toMatchObject({ productCount: 8 });
+    });
+
+    it('carries neither for an unlabelled section without products', () => {
+      render(<Section productCount={0} />);
+
+      latest().cross(true);
+      tick(SECTION_SEEN_DWELL_MS);
+
+      expect(received[0]).not.toHaveProperty('sectionLabel');
+      expect(received[0]).not.toHaveProperty('productCount');
+    });
+  });
+
   describe('what the merchant authored (ZERO-5222)', () => {
     const tracked = (viewTracking: Record<string, unknown>) => ({
       id: 'sec_hero',

package/src/hooks/use-list-impression.ts

@@ -0,0 +1,116 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { usePathname } from 'next/navigation';
+
+import { buildCommerceItem, emitCommerceEvent } from '../utils/analytics';
+
+/**
+ * GA4 `view_item_list` for a product row that is not a listing grid (a
+ * collection carousel, a recommendations strip), ZERO-5305.
+ *
+ * The listing grid and the favourites grid already report their own
+ * impressions; a carousel built from a collection, or the recommendations a
+ * block fetches for itself, reported none, so a click on one of their cards
+ * (`select_item`) had no impression to belong to. Every list reports as the
+ * list it is: its name (the carousel's) and its id.
+ *
+ * Once per route, when a quarter of the row has been on screen for half a
+ * second — the products in the row's markup are its list, as a listing page's
+ * products are, whether or not a slide has scrolled each card into view yet.
+ * A row that is never on screen (laid out with `display: none`, say) never
+ * reports. Silent inside the editor (emitCommerceEvent checks), and silent
+ * with nothing to list.
+ */
+
+export const LIST_IMPRESSION_DWELL_MS = 500;
+
+const SEEN: IntersectionObserverInit = { threshold: 0.25 };
+
+export interface UseListImpressionOptions {
+  ref: React.RefObject<HTMLElement>;
+  products: ReadonlyArray<Record<string, unknown>> | null | undefined;
+  listId: string;
+  listName: string;
+  /** False while the row has nothing real to list (loading, the designer). */
+  enabled?: boolean;
+  /**
+   * The list's content, for a list that reports again when it changes (the
+   * favourites grid after a removal); left out, once per route.
+   */
+  refreshKey?: string;
+  /** The list's currency, when the caller knows it. */
+  currency?: string;
+}
+
+export const useListImpression = ({
+  ref,
+  products,
+  listId,
+  listName,
+  enabled = true,
+  refreshKey = '',
+  currency
+}: UseListImpressionOptions): void => {
+  const pathname = usePathname();
+  const reportedFor = useRef<string | null>(null);
+
+  // The latest values, read when the observer fires rather than captured:
+  // the row's products arrive after the element mounts.
+  const latest = useRef({ products, listId, listName, currency });
+  latest.current = { products, listId, listName, currency };
+
+  const count = products?.length ?? 0;
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node || !enabled || count === 0) return;
+    if (typeof IntersectionObserver === 'undefined') return;
+
+    const latchKey = `${pathname}:${listId}:${refreshKey}`;
+    if (reportedFor.current === latchKey) return;
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    const observer = new IntersectionObserver((entries) => {
+      const entry = entries[entries.length - 1];
+      if (!entry) return;
+
+      if (!entry.isIntersecting) {
+        if (timer !== undefined) clearTimeout(timer);
+        timer = undefined;
+        return;
+      }
+
+      if (timer !== undefined) return;
+      timer = setTimeout(() => {
+        timer = undefined;
+        if (reportedFor.current === latchKey) return;
+
+        const current = latest.current;
+        const items = (current.products ?? []).map((product, index) =>
+          buildCommerceItem(product, {
+            index,
+            listId: current.listId,
+            listName: current.listName
+          })
+        );
+        if (items.every((item) => item === null)) return;
+
+        reportedFor.current = latchKey;
+        observer.disconnect();
+        emitCommerceEvent('view_item_list', {
+          ...(current.currency ? { currency: current.currency } : null),
+          items
+        });
+      }, LIST_IMPRESSION_DWELL_MS);
+    }, SEEN);
+
+    observer.observe(node);
+
+    return () => {
+      if (timer !== undefined) clearTimeout(timer);
+      observer.disconnect();
+    };
+  }, [ref, enabled, count, pathname, listId, refreshKey]);
+};