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

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,

package/src/sections/__tests__/posts-slider-select-item.test.tsx

@@ -0,0 +1,205 @@
+import React from 'react';
+import { act, render, screen } from '@testing-library/react';
+
+/**
+ * A deal card as it really is: one anchor to the product page, with a control
+ * a designer may drop inside it.
+ */
+jest.mock('../../theme-block', () => ({
+  __esModule: true,
+  default: ({ block }: { block: { id: string } }) => (
+    <a data-testid="card" data-id={block.id} href={`/product/${block.id}/`}>
+      <span data-testid="card-name">card</span>
+      <button type="button" data-testid="card-button">
+        add
+      </button>
+    </a>
+  )
+}));
+
+/** The real carousel renders an empty track at jsdom's zero width. */
+jest.mock('react-multi-carousel', () => ({
+  __esModule: true,
+  default: ({ children }: { children?: React.ReactNode }) => (
+    <div data-testid="carousel">{children}</div>
+  )
+}));
+
+import PostsSliderSection from '../posts-slider-section';
+import { ThemeSectionListProvider } from '../../theme-section-data-context';
+import { COMMERCE_EVENT_NAME } from '../../utils/analytics';
+
+declare global {
+  interface Window {
+    __themeEditorDesigner?: boolean;
+  }
+}
+
+/**
+ * A product slider's cards are a list (ZERO-5305): a click on one is a
+ * select_item naming the list it was picked from and its place in it, the
+ * identity the row's view_item_list carries — so the pick can follow the
+ * product to its page and into the basket.
+ */
+
+const product = (pk: number, name: string, price: number) => ({
+  pk,
+  base_code: `B${pk}`,
+  name,
+  price: String(price),
+  currency_type: 'try',
+  absolute_url: `/product/${pk}/`,
+  productimage_set: [{ image: `/img/${pk}.jpg` }],
+  active_price: { price, currency_type: 'TRY' }
+});
+
+const ITERATOR = {
+  id: 'iter',
+  label: 'Iterator',
+  isIterator: true,
+  order: 0,
+  properties: {},
+  styles: {},
+  blocks: [
+    {
+      id: 'card',
+      type: 'group',
+      label: 'Product Card 1',
+      properties: { tag: 'a' },
+      styles: {},
+      blocks: []
+    }
+  ]
+};
+
+const renderSlider = ({
+  type = 'flash-deals-slider',
+  properties = {},
+  isDesigner = false,
+  list = { listId: 'datasource-1', listName: 'Picks Slider' } as {
+    listId: string;
+    listName: string;
+  } | null
+} = {}) => {
+  const slider = (
+    <PostsSliderSection
+      {...({
+        section: {
+          id: 'sec',
+          type,
+          label: 'Picks Slider',
+          properties: { 'items-per-slide': 1, ...properties },
+          styles: {},
+          blocks: [ITERATOR],
+          dataSource: {
+            details: {
+              collection: {
+                products: [
+                  product(11, 'Blue Stool', 2790),
+                  product(22, 'Red Chair', 1490)
+                ]
+              }
+            }
+          }
+        },
+        currentBreakpoint: 'desktop',
+        placeholderId: 'ph',
+        isDesigner
+      } as any)}
+    />
+  );
+  return render(
+    list ? (
+      <ThemeSectionListProvider listId={list.listId} listName={list.listName}>
+        {slider}
+      </ThemeSectionListProvider>
+    ) : (
+      slider
+    )
+  );
+};
+
+const click = (element: Element) =>
+  act(() => {
+    element.dispatchEvent(
+      new MouseEvent('click', { bubbles: true, cancelable: true, button: 0 })
+    );
+  });
+
+describe('a product slider card click (ZERO-5305)', () => {
+  let received: Array<Record<string, any>>;
+  const onCommerce = (event: Event) =>
+    received.push((event as CustomEvent<Record<string, any>>).detail);
+
+  beforeEach(() => {
+    received = [];
+    delete window.__themeEditorDesigner;
+    window.addEventListener(COMMERCE_EVENT_NAME, onCommerce);
+  });
+
+  afterEach(() => {
+    window.removeEventListener(COMMERCE_EVENT_NAME, onCommerce);
+    delete window.__themeEditorDesigner;
+  });
+
+  const selects = () => received.filter((d) => d.action === 'select_item');
+
+  it('reports the pick with the list and the card’s place in it', () => {
+    renderSlider();
+
+    click(screen.getAllByTestId('card-name')[1]);
+
+    expect(selects()).toHaveLength(1);
+    expect(selects()[0].items).toEqual([
+      expect.objectContaining({
+        baseCode: 'B22',
+        name: 'Red Chair',
+        index: 1,
+        listId: 'datasource-1',
+        listName: 'Picks Slider'
+      })
+    ]);
+    expect(selects()[0].currency).toBe('try');
+  });
+
+  it('still reports the pick when the click opens the quick view', () => {
+    renderSlider({ properties: { 'show-quick-view': true } });
+
+    click(screen.getAllByTestId('card-name')[0]);
+
+    expect(selects()).toHaveLength(1);
+    expect(selects()[0].items[0]).toMatchObject({ baseCode: 'B11', index: 0 });
+    expect(
+      document.querySelector('[data-part="quick-view-panel"]')
+    ).not.toBeNull();
+  });
+
+  it('leaves a control inside the card to itself', () => {
+    renderSlider();
+
+    click(screen.getAllByTestId('card-button')[0]);
+
+    expect(selects()).toEqual([]);
+  });
+
+  it('reports the pick without a list outside one', () => {
+    renderSlider({ list: null });
+
+    click(screen.getAllByTestId('card-name')[0]);
+
+    expect(selects()[0].items[0]).toMatchObject({ baseCode: 'B11', index: 0 });
+    expect(selects()[0].items[0]).not.toHaveProperty('listId');
+    expect(selects()[0].items[0]).not.toHaveProperty('listName');
+  });
+
+  it('is silent for a slider of posts, and in the designer', () => {
+    renderSlider({ type: 'posts-slider' });
+    click(screen.getAllByTestId('card-name')[0]);
+    expect(selects()).toEqual([]);
+
+    window.__themeEditorDesigner = true;
+    renderSlider();
+    click(screen.getAllByTestId('card-name')[0]);
+    expect(selects()).toEqual([]);
+  });
+});

package/src/sections/__tests__/section-wrapper-list.test.tsx

@@ -0,0 +1,148 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+
+import SectionWrapper from '../section-wrapper';
+import type { Section } from '../../theme-section';
+import { useThemeSectionList } from '../../theme-section-data-context';
+import { useSectionSeen } from '../../hooks/use-section-seen';
+import { useListImpression } from '../../hooks/use-list-impression';
+
+/**
+ * A section drawn through `SectionWrapper` — a product slider, a developer's
+ * custom section — is reported as the generic branch reports its own
+ * (ZERO-5305): seen with its product count, so a product row is never taken
+ * for a banner; listed under its list identity as one view_item_list; and its
+ * cards told which list they are in. The two hooks are the wrapper's whole
+ * contract with the reports, so they are recorded here rather than driven.
+ */
+
+jest.mock('../../components/action-toolbar', () => ({
+  __esModule: true,
+  default: () => null
+}));
+
+jest.mock('../../hooks/use-section-seen', () => ({
+  useSectionSeen: jest.fn()
+}));
+
+jest.mock('../../hooks/use-list-impression', () => ({
+  useListImpression: jest.fn()
+}));
+
+const seen = useSectionSeen as jest.Mock;
+const impression = useListImpression as jest.Mock;
+
+const section = {
+  id: 'sec-1',
+  type: 'flash-deals-slider',
+  name: 'sec-1',
+  label: 'Picks Slider',
+  properties: {},
+  styles: {},
+  blocks: [],
+  order: 2,
+  hidden: false
+} as unknown as Section;
+
+const ROWS = [
+  { pk: 1, base_code: 'B1', name: 'Polo' },
+  { pk: 2, base_code: 'B2', name: 'Shirt' }
+];
+
+const ListReader = () => {
+  const list = useThemeSectionList();
+  return (
+    <span data-testid="list">
+      {list ? `${list.listId}|${list.listName}` : 'none'}
+    </span>
+  );
+};
+
+const lastCall = (mock: jest.Mock) =>
+  mock.mock.calls[mock.mock.calls.length - 1][0];
+
+describe('SectionWrapper list reporting (ZERO-5305)', () => {
+  beforeEach(() => {
+    seen.mockClear();
+    impression.mockClear();
+  });
+
+  it('reports the section seen with its product count', () => {
+    render(
+      <SectionWrapper section={section} placeholderId="ph" productCount={2}>
+        <span />
+      </SectionWrapper>
+    );
+
+    expect(lastCall(seen)).toMatchObject({
+      section,
+      placeholderId: 'ph',
+      productCount: 2
+    });
+  });
+
+  it('lists its rows under its list identity, from its own element', () => {
+    const { container } = render(
+      <SectionWrapper
+        section={section}
+        placeholderId="ph"
+        listProducts={ROWS}
+        listId="datasource-7"
+        listName="Picks Slider"
+      >
+        <span />
+      </SectionWrapper>
+    );
+
+    const call = lastCall(impression);
+    expect(call).toMatchObject({
+      products: ROWS,
+      listId: 'datasource-7',
+      listName: 'Picks Slider',
+      enabled: true
+    });
+    expect(call.ref.current).toBe(
+      container.querySelector('[data-section-id="sec-1"]')
+    );
+  });
+
+  it('tells its cards which list they are in', () => {
+    render(
+      <SectionWrapper
+        section={section}
+        placeholderId="ph"
+        listId="datasource-7"
+        listName="Picks Slider"
+      >
+        <ListReader />
+      </SectionWrapper>
+    );
+
+    expect(screen.getByTestId('list')).toHaveTextContent(
+      'datasource-7|Picks Slider'
+    );
+  });
+
+  it('lists nothing when handed nothing, and nothing in the designer', () => {
+    render(
+      <SectionWrapper section={section} placeholderId="ph">
+        <span />
+      </SectionWrapper>
+    );
+    expect(lastCall(impression)).toMatchObject({ products: null, listId: '' });
+
+    render(
+      <SectionWrapper
+        section={section}
+        placeholderId="ph"
+        isDesigner
+        listProducts={ROWS}
+        listId="datasource-7"
+        listName="Picks Slider"
+      >
+        <span />
+      </SectionWrapper>
+    );
+    expect(lastCall(impression)).toMatchObject({ enabled: false });
+  });
+});

package/src/sections/posts-slider-section.tsx

@@ -53,6 +53,12 @@ import {
   resolveSliderRowProduct
 } from '../blocks/item-template-utils';
 import type { ThemeProduct } from '../blocks/product-block-utils';
+import { useThemeSectionList } from '../theme-section-data-context';
+import {
+  buildCommerceItem,
+  emitCommerceEvent,
+  readItemsCurrency
+} from '../utils/analytics';
 
 import { postToEditor } from '../editor-bridge';
 import { PreviewToEditorMessageType } from '@akinon/theme-contract';
@@ -391,7 +397,9 @@ const PostsSliderSection: React.FC<PostsSliderSectionProps> = ({
         // products AND the data source actually returned one for this index.
         // `products[index] || {}` above makes every clone truthy, so quick
         // view cannot gate on the clone — it gates on this.
-        __qvProduct: resolveSliderRowProduct(section?.type, products[index])
+        __qvProduct: resolveSliderRowProduct(section?.type, products[index]),
+        // Its place in the list, for the position a card click reports.
+        __qvIndex: index
       };
     });
   });
@@ -708,6 +716,8 @@ const PostsSliderSection: React.FC<PostsSliderSectionProps> = ({
   );
   const quickViewOpenerRef = React.useRef<HTMLElement | null>(null);
   const bandRef = React.useRef<HTMLDivElement | null>(null);
+  // The list these slides are, as `SectionWrapper` publishes it (ZERO-5305).
+  const sectionList = useThemeSectionList();
 
   const showQuickView =
     getResponsiveValue(
@@ -1092,10 +1102,60 @@ const PostsSliderSection: React.FC<PostsSliderSectionProps> = ({
                   }
                 : null;
 
+            /**
+             * GA4 select_item (ZERO-5305): a click on a product slide's link
+             * is a pick from this list, reported with the list and the card's
+             * place in it — the identity the row's view_item_list carries.
+             * Runs ahead of the quick view, which may stop the click; a
+             * control dropped into the card owns its own click, and a slide
+             * with no product row (a post, an empty designer pad) is silent.
+             */
+            const reportSelectItem =
+              !isDesigner && block.__qvProduct
+                ? (event: React.MouseEvent<HTMLDivElement>) => {
+                    const target = event.target as HTMLElement | null;
+                    if (!target?.closest?.('a[href]')) return;
+                    if (target.closest(INNER_CONTROL_SELECTOR)) return;
+
+                    const product = block.__qvProduct as Record<
+                      string,
+                      unknown
+                    >;
+                    const item = buildCommerceItem(product, {
+                      ...(typeof block.__qvIndex === 'number'
+                        ? { index: block.__qvIndex }
+                        : null),
+                      ...(sectionList?.listId
+                        ? { listId: sectionList.listId }
+                        : null),
+                      ...(sectionList?.listName
+                        ? { listName: sectionList.listName }
+                        : null)
+                    });
+                    if (!item) return;
+                    emitCommerceEvent('select_item', {
+                      currency: readItemsCurrency(product),
+                      items: [item]
+                    });
+                  }
+                : null;
+
+            const slideClickHandlers =
+              reportSelectItem || quickViewHandlers
+                ? {
+                    onClickCapture: (
+                      event: React.MouseEvent<HTMLDivElement>
+                    ) => {
+                      reportSelectItem?.(event);
+                      quickViewHandlers?.onClickCapture(event);
+                    }
+                  }
+                : null;
+
             return (
               <div
                 key={block.id}
-                {...quickViewHandlers}
+                {...slideClickHandlers}
                 style={
                   flushEdges
                     ? {

package/src/sections/section-wrapper.tsx

@@ -10,6 +10,8 @@ import { SECTION_CONTENT_ATTRIBUTE } from '../utils/section-content-width';
 import { isTrustedEditorEvent, postToEditor } from '../editor-bridge';
 import { resolveSectionPartName } from '../hooks/use-designer-features';
 import { useSectionSeen } from '../hooks/use-section-seen';
+import { useListImpression } from '../hooks/use-list-impression';
+import { ThemeSectionListProvider } from '../theme-section-data-context';
 
 
 interface SectionWrapperProps {
@@ -24,6 +26,17 @@ interface SectionWrapperProps {
   onToggleVisibility?: () => void;
   onDelete?: () => void;
   onRename?: (newLabel: string) => void;
+  /**
+   * The list this section's product rows are (ZERO-5305), worked out by
+   * `ThemeSection` as for its generic branch: a product slider renders
+   * through this wrapper, and its rows are a list as a carousel's are.
+   * `listProducts` is null when nothing here reports an impression (no
+   * collection, or a grid inside that reports its own).
+   */
+  productCount?: number;
+  listProducts?: ReadonlyArray<Record<string, unknown>> | null;
+  listId?: string;
+  listName?: string;
   children: React.ReactNode;
 }
 
@@ -39,6 +52,10 @@ export default function SectionWrapper({
   onToggleVisibility,
   onDelete,
   onRename,
+  productCount,
+  listProducts = null,
+  listId = '',
+  listName = '',
   children
 }: SectionWrapperProps) {
   const readSectionString = (value: unknown): string => {
@@ -70,7 +87,18 @@ export default function SectionWrapper({
   // the emitter reads the editor handshake flag itself, so there is no
   // `isDesigner` check here — that prop goes false in browse mode while the
   // editor is still attached.
-  useSectionSeen({ ref: sectionRef, section, placeholderId });
+  useSectionSeen({ ref: sectionRef, section, placeholderId, productCount });
+
+  // The section's product rows, reported as one view_item_list when it comes
+  // into view — the generic branch's own call never runs for a section drawn
+  // here, its ref being left unattached.
+  useListImpression({
+    ref: sectionRef,
+    products: listProducts,
+    listId,
+    listName,
+    enabled: !isDesigner
+  });
 
   // Custom-renderer sections render through this wrapper instead of the
   // default <section> in theme-section, so the editor's SCROLL_TO_SECTION
@@ -193,7 +221,9 @@ export default function SectionWrapper({
         {...{ [SECTION_CONTENT_ATTRIBUTE]: '' }}
         className={isDesigner ? 'relative z-10' : 'relative'}
       >
-        {children}
+        <ThemeSectionListProvider listId={listId} listName={listName}>
+          {children}
+        </ThemeSectionListProvider>
       </div>
     </section>
   );

package/src/theme-block.tsx

@@ -62,6 +62,11 @@ export interface Block {
    * product scope the row's favourite / add-to-basket resolve against.
    */
   itemScopeProduct?: ThemeProduct | null;
+  /**
+   * The row's place in its list (0-based), beside `itemScopeProduct`: the
+   * position a product card's click reports (ZERO-5305). Never authored.
+   */
+  itemScopeIndex?: number;
   iteratorDataPath?: string;
   /**
    * Written by the property-switch pass (utils/property-switches.ts), never
@@ -247,6 +252,7 @@ export default function ThemeBlock({
       product={
         block.itemScopeProduct ?? (isDesigner ? DESIGNER_SAMPLE_PRODUCT : null)
       }
+      index={block.itemScopeIndex}
     >
       {rendered}
     </ThemeItemScopeProvider>

package/src/theme-placeholder-wrapper.tsx

@@ -1166,9 +1166,6 @@ export default function ThemePlaceholderWrapper({
           Tells the editor which languages this storefront has and follows its
           language switch. Every placeholder renders one; they share a single
           listener and a single announcement (see editor-locale-bridge.tsx).
-          A child of this wrapper on purpose: its effect, and so its frame,
-          runs before the effect below that posts IFRAME_READY, and the editor
-          counts on hearing the languages before the ready report.
         */}
           <EditorLocaleBridge />
           {themeBackgroundCSS && (

package/src/theme-section-data-context.tsx

@@ -30,3 +30,36 @@ export const ThemeSectionDataProvider = ({
 };
 
 export const useThemeSectionData = () => useContext(ThemeSectionDataContext);
+
+/**
+ * The list a section's product rows are, for the commerce facts a row reports
+ * (ZERO-5305): a click on a card in a "New Arrivals" carousel names that
+ * carousel as the list, not the product's own catalogue group. The id is the
+ * section's data source (the collection), else the section; the name is the
+ * section's label — what the merchant calls it in the editor's layer tree.
+ */
+export interface ThemeSectionListValue {
+  listId: string;
+  listName: string;
+}
+
+const ThemeSectionListContext = createContext<ThemeSectionListValue | null>(
+  null
+);
+
+export const ThemeSectionListProvider = ({
+  listId,
+  listName,
+  children
+}: PropsWithChildren<ThemeSectionListValue>) => {
+  const value = useMemo(() => ({ listId, listName }), [listId, listName]);
+
+  return (
+    <ThemeSectionListContext.Provider value={value}>
+      {children}
+    </ThemeSectionListContext.Provider>
+  );
+};
+
+/** The enclosing section's list identity; null outside a section. */
+export const useThemeSectionList = () => useContext(ThemeSectionListContext);