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

package/src/blocks/product-recommendations-block.tsx

@@ -11,7 +11,12 @@ import {
 } from '@akinon/next/data/client/product';
 import { useLocalization } from '@akinon/next/hooks';
 import { useOverlay } from '../hooks/use-overlay';
-import { useThemeSectionData } from '../theme-section-data-context';
+import {
+  ThemeSectionListProvider,
+  useThemeSectionData,
+  useThemeSectionList
+} from '../theme-section-data-context';
+import { useListImpression } from '../hooks/use-list-impression';
 import { getResponsiveValue, partAttrs } from '../utils';
 import {
   buildCommerceItem,
@@ -285,6 +290,7 @@ const ProductRecommendationsBlock = ({
 }: BlockRendererProps) => {
   const { locale, currency: localeCurrency } = useLocalization();
   const rootRef = useRef<HTMLDivElement>(null);
+  const sectionList = useThemeSectionList();
   const trackRef = useRef<HTMLDivElement>(null);
   // The ambient product: on a PDP this is what the shopper is looking at, and
   // it is both what gets recorded and what is excluded from its own strip.
@@ -863,6 +869,25 @@ const ProductRecommendationsBlock = ({
     ? favouriteCards
     : collectionProducts;
 
+  // The list this strip is (ZERO-5305): named after its title ("You may also
+  // like"), else the section's label; identified by the
+  // collection it shows, else the section.
+  const listIdentity = {
+    listId:
+      (!isRecentlyViewed && !isFavourites && !isSectionSource && collectionId) ||
+      sectionList?.listId ||
+      'product_recommendations',
+    listName: title || sectionList?.listName || 'Product Recommendations'
+  };
+
+  useListImpression({
+    ref: rootRef,
+    products: products as unknown as Record<string, unknown>[],
+    listId: listIdentity.listId,
+    listName: listIdentity.listName,
+    enabled: !isDesigner
+  });
+
   /**
    * The designer has no browsing history behind the canvas, so a recently
    * viewed strip would collapse to nothing and stop being selectable, sizeable
@@ -891,17 +916,24 @@ const ProductRecommendationsBlock = ({
 
   // A designer who marked a child as the card layout gets that layout repeated
   // per product; otherwise the built-in card renders unchanged.
+  // The strip's own list identity rides over its cards, so an authored card's
+  // click reports this strip — not the section around it — as its list.
   const customCards = hasItemTemplate(block, currentBreakpoint) ? (
-    <ItemTemplateList
-      block={block}
-      items={products as unknown as Record<string, unknown>[]}
-      placeholderId={placeholderId}
-      sectionId={sectionId}
-      isDesigner={isDesigner}
-      selectedBlockId={selectedBlockId}
-      currentBreakpoint={currentBreakpoint}
-      designerPlaceholderCount={4}
-    />
+    <ThemeSectionListProvider
+      listId={listIdentity.listId}
+      listName={listIdentity.listName}
+    >
+      <ItemTemplateList
+        block={block}
+        items={products as unknown as Record<string, unknown>[]}
+        placeholderId={placeholderId}
+        sectionId={sectionId}
+        isDesigner={isDesigner}
+        selectedBlockId={selectedBlockId}
+        currentBreakpoint={currentBreakpoint}
+        designerPlaceholderCount={4}
+      />
+    </ThemeSectionListProvider>
   ) : null;
 
   // An empty history is the normal state on a first visit, so the strip
@@ -1294,8 +1326,8 @@ const ProductRecommendationsBlock = ({
                     buildCommerceItem(
                       product as unknown as Record<string, unknown>,
                       {
-                        listId: 'product_recommendations',
-                        listName: 'Product Recommendations'
+                        ...listIdentity,
+                        index: products.indexOf(product)
                       }
                     )
                   ]

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]);
+};

package/src/hooks/use-section-seen.ts

@@ -60,14 +60,24 @@ const isFramed = (): boolean => {
 
 export interface UseSectionSeenOptions {
   ref: React.RefObject<HTMLElement>;
-  section: Pick<Section, 'id' | 'type' | 'order' | 'properties'>;
+  section: Pick<Section, 'id' | 'type' | 'order' | 'properties'> &
+    Partial<Pick<Section, 'label'>>;
   placeholderId: string;
+  /**
+   * How many products the section lists (its collection's rows), so a bridge
+   * can tell a product row from a banner (ZERO-5305). 0 or absent: none.
+   */
+  productCount?: number;
 }
 
+/** A label is a short display name; anything past this is not one. */
+const MAX_SECTION_LABEL = 120;
+
 export const useSectionSeen = ({
   ref,
   section,
-  placeholderId
+  placeholderId,
+  productCount = 0
 }: UseSectionSeenOptions): void => {
   const pathname = usePathname();
   const signal = useThemeSignal({
@@ -90,6 +100,12 @@ export const useSectionSeen = ({
   const reported = useRef<string | null>(null);
 
   const order = section.order;
+  // The name the merchant sees and renames in the editor's layer tree: what a
+  // report shows a section as (ZERO-5305 — a promotion is read by its name).
+  const label =
+    typeof section.label === 'string'
+      ? section.label.trim().slice(0, MAX_SECTION_LABEL)
+      : '';
   const { name, purpose, seenWhen, dwellMs, frequency } =
     normalizeSectionTracking(section.properties?.[SECTION_TRACKING_PROPERTY_KEY]);
 
@@ -146,6 +162,8 @@ export const useSectionSeen = ({
             // so a merchant label sent under that key would vanish without a
             // word. It also reads better beside `sectionId` and `sectionType`.
             ...(name ? { sectionName: name } : null),
+            ...(label ? { sectionLabel: label } : null),
+            ...(productCount > 0 ? { productCount } : null),
             ...(typeof order === 'number' && Number.isFinite(order)
               ? { order }
               : null)
@@ -185,6 +203,8 @@ export const useSectionSeen = ({
     order,
     signal,
     name,
+    label,
+    productCount,
     purpose,
     seenWhen,
     dwellMs,