@akinon/pz-theme 2.0.132 → 2.0.133-beta.0

package/CHANGELOG.md

@@ -1,9 +1,18 @@
 # @akinon/pz-theme
 
+## 2.0.133-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.133-beta.0
+  - @akinon/theme-contract@2.0.133-beta.0
+
 ## 2.0.132
 
 ### Patch Changes
 
+- d16b7c3: ZERO-5163: Report slide changes from the posts slider section
 - 6a296eb: ZERO-5161: resolve video clip and posters per storefront language
   - @akinon/next@2.0.132
   - @akinon/theme-contract@2.0.132

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.132",
+  "version": "2.0.133-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.132",
+    "@akinon/next": "2.0.133-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.132",
+    "@akinon/theme-contract": "2.0.133-beta.0",
     "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.132",
+    "@akinon/next": "2.0.133-beta.0",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/blocks/__tests__/slider-block-signals.test.tsx

@@ -22,7 +22,8 @@ jest.mock('../../theme-block', () => ({
   }
 }));
 
-import SliderBlock, { authoredSlideIndex } from '../slider-block';
+import SliderBlock from '../slider-block';
+import { authoredSlideIndex } from '../../utils/carousel-index';
 import {
   __resetThemeSignalsForTests,
   subscribeToThemeSignals,
@@ -362,6 +363,19 @@ describe('slider events (ZERO-5160)', () => {
       expect(received).toHaveLength(5);
     });
 
+    it('does not cap a slider the shopper is driving', () => {
+      // With autoplay off nothing can be changing the slide but the shopper —
+      // a drag or a keyboard arrow — so the timer's low ceiling must not
+      // apply, even though neither leaves an attribution note.
+      render(<SliderBlock {...props()} />);
+
+      for (let tick = 0; tick < 20; tick += 1) {
+        lastCarouselProps().beforeChange(tick % 6, { slidesToShow: 1 });
+      }
+
+      expect(received).toHaveLength(20);
+    });
+
     it('still reports a shopper control after the timer has used its budget', () => {
       // The two go on separate tally keys, so a carousel spinning below the
       // fold cannot silence the arrow the shopper actually pressed.

package/src/blocks/slider-block.tsx

@@ -15,6 +15,10 @@ import {
 } from '../utils';
 import { DESKTOP_MIN_WIDTH, isNarrowBreakpoint } from '../utils/breakpoints';
 import { useCarouselSsr } from '../utils/carousel-ssr';
+import {
+  authoredSlideIndex,
+  TIMER_SLIDE_CHANGE_CEILING
+} from '../utils/carousel-index';
 import { useThemeSignal } from '../hooks/use-theme-signal';
 import {
   CAROUSEL_MINIMUM_TOUCH_DRAG,
@@ -68,60 +72,6 @@ const clampNumber = (value: number, min: number, max: number) =>
  * render would unmount and remount all of them on each slide change — taking
  * the focus of a keyboard user who had just tabbed to one.
  */
-/**
- * How many unattributed slide changes one slider may report per page view.
- *
- * An autoplaying carousel changes slide every few seconds for as long as the
- * tab is open, and nothing in the callback says whether a change was the timer
- * or a shopper. Those go on their own tally key with this much lower ceiling,
- * so a carousel spinning below the fold can neither drown the arrow clicks of
- * the same slider nor eat the whole route's budget and silence every other
- * moment on the page.
- */
-const UNATTRIBUTED_SLIDE_CHANGE_CEILING = 5;
-
-/**
- * The authored slide ordinal behind the index the library reports.
- *
- * In infinite mode the carousel prepends and appends clones, so `beforeChange`
- * counts in clone space: a six-slide hero starts at 2 and climbs to 9 before
- * the library silently teleports back. Reporting that raw would give
- * `index: 9, total: 6` and would never mention slides 0 and 1 at all.
- *
- * This is the same mapping the library's own dots use to resolve which one is
- * active (`getOriginalIndexLookupTableByClones`), written out rather than
- * imported: the helper is not on the package's export surface, only its
- * internal deep path, and four lines of arithmetic is a smaller liability than
- * an import that a minor version can move.
- *
- * `slidesToShow` must be the MEASURED value off the callback's state — the
- * table branches on it, so the block's own breakpoint guess would silently
- * select a different table. Before mount the library reports 0, which cannot
- * resolve anything, so the change is not reported at all rather than guessed.
- */
-export const authoredSlideIndex = (
-  reportedIndex: number,
-  total: number,
-  slidesToShow: number
-): number | null => {
-  if (!Number.isFinite(reportedIndex) || total <= 0) return null;
-  if (slidesToShow <= 0) return null;
-
-  const span = 2 * slidesToShow;
-  let authored: number;
-
-  if (total > span) {
-    if (reportedIndex < span) authored = total - span + reportedIndex;
-    else if (reportedIndex < total + span) authored = reportedIndex - span;
-    else authored = reportedIndex - (total + span);
-  } else {
-    // Short lists are cloned by concatenation, so the table is a modulo.
-    authored = ((reportedIndex % total) + total) % total;
-  }
-
-  return authored >= 0 && authored < total ? authored : null;
-};
-
 const CustomDot = ({ index, active, onClick, onSelect }: any) => (
   <li
     className={clsx(
@@ -1048,11 +998,15 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
         ...(measuredInView > 0 ? { slidesInView: measuredInView } : null),
         ...(via ? { via } : null)
       },
-      via
+      // The low ceiling is for the autoplay timer, which reports no cause and
+      // never stops. With autoplay off an unattributed change is a drag or a
+      // keyboard arrow — a real shopper action, and capping those at five
+      // would lose most of them.
+      via || !useAutoPlay
         ? { key: block.id }
         : {
-            key: `${block.id}:unattributed`,
-            ceiling: UNATTRIBUTED_SLIDE_CHANGE_CEILING
+            key: `${block.id}:timer`,
+            ceiling: TIMER_SLIDE_CHANGE_CEILING
           }
     );
   };

package/src/sections/__tests__/posts-slider-edges.test.tsx

@@ -101,11 +101,18 @@ const slidePadding = (container: HTMLElement) =>
   );
 
 describe('a slider that has not opted in', () => {
-  it('is handed no edge props at all', () => {
+  it('is handed no edge transform, but is still reported on', () => {
     const { props } = renderSection();
 
+    // The transform is the lead-in's, and a slider that did not opt in must
+    // still be handed the identical prop object it was handed before.
     expect('additionalTransfrom' in props).toBe(false);
-    expect('beforeChange' in props).toBe(false);
+
+    // The change callback is no longer part of that opt-in (ZERO-5163): every
+    // posts slider reports its slide changes, and a lead-in requires a finite
+    // track, so hanging the report off it would leave every looping slider
+    // silent. The lead-in's own state write is still behind its condition.
+    expect(typeof props.beforeChange).toBe('function');
   });
 
   it('keeps the half-gap on both sides of every slide', () => {

package/src/sections/__tests__/posts-slider-signals.test.tsx

@@ -0,0 +1,200 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+
+/**
+ * What the posts slider reports when a slide changes (ZERO-5163).
+ *
+ * The sibling `slider` block got this first; this section draws the same
+ * carousel, and the one thing the two must not do is disagree about whether a
+ * slide change is worth reporting or what a slide index means.
+ *
+ * The library renders nothing under jsdom, so — as in the edges suite — the
+ * assertions go through the prop object it was handed.
+ */
+
+const carouselProps: Record<string, any>[] = [];
+
+let themeBlockRenders = 0;
+jest.mock('../../theme-block', () => ({
+  __esModule: true,
+  default: ({ block }: { block: { id: string } }) => {
+    themeBlockRenders += 1;
+    return <div data-testid="slide-content" data-id={block.id} />;
+  }
+}));
+
+jest.mock('react-multi-carousel', () => ({
+  __esModule: true,
+  default: (props: Record<string, any>) => {
+    carouselProps.push(props);
+    return <div data-testid="carousel">{props.children}</div>;
+  }
+}));
+
+import PostsSliderSection from '../posts-slider-section';
+import {
+  __resetThemeSignalsForTests,
+  subscribeToThemeSignals,
+  type ThemeSignalDetail
+} from '../../utils/theme-signal';
+
+declare global {
+  interface Window {
+    __themeEditorDesigner?: boolean;
+  }
+}
+
+const slide = (id: string) => ({
+  id,
+  type: 'group',
+  label: id,
+  properties: {},
+  styles: {},
+  order: 0,
+  blocks: []
+});
+
+const renderSection = (
+  properties: Record<string, unknown> = {},
+  slideCount = 6
+) => {
+  carouselProps.length = 0;
+  themeBlockRenders = 0;
+
+  const result = render(
+    <PostsSliderSection
+      {...({
+        section: {
+          id: 'sec',
+          type: 'flash-deals-slider',
+          label: 'sec',
+          properties: { 'items-per-slide': 1, ...properties },
+          styles: {},
+          blocks: Array.from({ length: slideCount }, (_unused, index) =>
+            slide(`s${index}`)
+          )
+        },
+        currentBreakpoint: 'desktop',
+        placeholderId: 'ph',
+        isDesigner: false
+      } as any)}
+    />
+  );
+
+  return { ...result, props: carouselProps[carouselProps.length - 1] };
+};
+
+describe('posts slider events (ZERO-5163)', () => {
+  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 a change with the section identity', () => {
+    const { props } = renderSection();
+
+    props.beforeChange(2, { slidesToShow: 1 });
+
+    expect(received).toEqual([
+      {
+        name: 'slide.changed',
+        placeholderId: 'ph',
+        sectionId: 'sec',
+        sectionType: 'flash-deals-slider',
+        index: 2,
+        total: 6,
+        slidesInView: 1
+      }
+    ]);
+  });
+
+  it('never claims to know what caused the change', () => {
+    // This section uses the library's own arrows and dots rather than
+    // components it owns, so nothing here could attribute a change honestly.
+    const { props } = renderSection();
+
+    props.beforeChange(1, { slidesToShow: 1 });
+    props.beforeChange(2, { slidesToShow: 1 });
+
+    expect(received.some((detail) => 'via' in detail)).toBe(false);
+  });
+
+  it('maps a clone index back to the slide the merchant authored', () => {
+    const { props } = renderSection({ infinite: true });
+
+    // Six slides one at a time: the library starts at 2, so its 3 is the
+    // second slide and its 7 is the last.
+    props.beforeChange(3, { slidesToShow: 1 });
+    props.beforeChange(7, { slidesToShow: 1 });
+
+    expect(received.map((detail) => detail.index)).toEqual([1, 5]);
+  });
+
+  it('reports nothing before the library has measured itself', () => {
+    const { props } = renderSection({ infinite: true });
+
+    props.beforeChange(3, { slidesToShow: 0 });
+
+    expect(received).toEqual([]);
+  });
+
+  it('omits slides in view rather than reporting zero', () => {
+    const { props } = renderSection();
+
+    props.beforeChange(1, { slidesToShow: 0 });
+
+    expect(received[0]).not.toHaveProperty('slidesInView');
+  });
+
+  it('does not re-render the cards on a change it was not asked to track', () => {
+    const { props } = renderSection();
+    const before = themeBlockRenders;
+
+    props.beforeChange(2, { slidesToShow: 1 });
+
+    expect(themeBlockRenders).toBe(before);
+  });
+
+  describe('volume', () => {
+    it('caps the autoplay timer', () => {
+      const { props } = renderSection({ autoplay: true });
+
+      for (let tick = 0; tick < 20; tick += 1) {
+        props.beforeChange(tick % 6, { slidesToShow: 1 });
+      }
+
+      expect(received).toHaveLength(5);
+    });
+
+    it('does not cap a slider the shopper is driving', () => {
+      // With autoplay off nothing can be reporting but the shopper — a drag
+      // or a keyboard arrow — so the low ceiling would lose most of them.
+      const { props } = renderSection();
+
+      for (let tick = 0; tick < 20; tick += 1) {
+        props.beforeChange(tick % 6, { slidesToShow: 1 });
+      }
+
+      expect(received).toHaveLength(20);
+    });
+  });
+
+  it('reports nothing while the theme editor is attached', () => {
+    window.__themeEditorDesigner = true;
+
+    const { props } = renderSection();
+    props.beforeChange(2, { slidesToShow: 1 });
+
+    expect(received).toEqual([]);
+  });
+});

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

@@ -22,6 +22,11 @@ import {
 } from '../utils';
 import { DESKTOP_MIN_WIDTH, TABLET_MIN_WIDTH } from '../utils/breakpoints';
 import { useCarouselSsr } from '../utils/carousel-ssr';
+import {
+  authoredSlideIndex,
+  TIMER_SLIDE_CHANGE_CEILING
+} from '../utils/carousel-index';
+import { useThemeSignal } from '../hooks/use-theme-signal';
 import {
   CAROUSEL_MINIMUM_TOUCH_DRAG,
   carouselDragStyle,
@@ -605,6 +610,44 @@ const PostsSliderSection: React.FC<PostsSliderSectionProps> = ({
   // there is no edge for a gap to belong to.
   const useLeadIn = leadIn > 0 && hasMultipleSlides && !useInfinite;
   const [slidePosition, setSlidePosition] = React.useState(0);
+
+  const signal = useThemeSignal({
+    placeholderId,
+    sectionId: section.id,
+    sectionType: section.type
+  });
+
+  /**
+   * One slide change, in authored terms (ZERO-5163).
+   *
+   * The same report the `slider` block sends, minus the cause: this section
+   * uses the library's own arrows and dots rather than components it owns, so
+   * there is nothing here that could attribute a change honestly. `total` is
+   * the expanded count — what the shopper can actually page through.
+   */
+  const reportSlideChange = (
+    reportedIndex: number,
+    state?: { slidesToShow?: number }
+  ) => {
+    const measuredInView = Number(state?.slidesToShow) || 0;
+    const index = useInfinite
+      ? authoredSlideIndex(reportedIndex, visibleCount, measuredInView)
+      : reportedIndex;
+
+    if (index === null || index === undefined) return;
+
+    signal(
+      'slide.changed',
+      {
+        index,
+        total: visibleCount,
+        ...(measuredInView > 0 ? { slidesInView: measuredInView } : null)
+      },
+      useAutoPlay
+        ? { key: `${section.id}:timer`, ceiling: TIMER_SLIDE_CHANGE_CEILING }
+        : { key: section.id }
+    );
+  };
   const lastPosition = Math.max(0, visibleCount - itemsPerView);
   const edgeOffset =
     leadInSide === 'left'
@@ -927,18 +970,29 @@ const PostsSliderSection: React.FC<PostsSliderSectionProps> = ({
           autoPlaySpeed={autoPlaySpeed}
           containerClass={`posts-slider-carousel ${carouselSsr.scopeClass}`}
           dotListClass="posts-slider-dots"
+          /*
+           * Reported on every posts slider, not only the ones with a lead-in:
+           * a lead-in requires a finite track, so hanging the report off it
+           * would leave every looping slider silent.
+           *
+           * The lead-in's own state write stays behind its condition. Calling
+           * it unconditionally would re-render this section and every card
+           * under it on each change, to move a transform nothing else reads.
+           */
+          beforeChange={(
+            nextSlide: number,
+            state: { slidesToShow?: number }
+          ) => {
+            if (useLeadIn) setSlidePosition(nextSlide);
+
+            reportSlideChange(nextSlide, state);
+          }}
           /*
            * Spread conditionally so a slider that has not opted in is handed
-           * the identical prop object it was handed before — there is no
-           * `additionalTransfrom: 0` for the library to reason about, and no
-           * `beforeChange` for it to call.
+           * the identical transform prop it was handed before — there is no
+           * `additionalTransfrom: 0` for the library to reason about.
            */
-          {...(useLeadIn
-            ? {
-                additionalTransfrom: edgeOffset,
-                beforeChange: (nextSlide: number) => setSlidePosition(nextSlide)
-              }
-            : {})}
+          {...(useLeadIn ? { additionalTransfrom: edgeOffset } : {})}
         >
           {expandedBlocks.map((block, index) => {
             const controlBlockId = block.__iteratorParentId || block.id;

package/src/utils/carousel-index.ts

@@ -0,0 +1,65 @@
+/**
+ * The authored slide ordinal behind the index react-multi-carousel reports.
+ *
+ * In infinite mode the carousel prepends and appends clones, so its change
+ * callback counts in clone space: a six-slide hero starts at 2 and climbs to 9
+ * before the library silently teleports back. Reported raw that reads
+ * `index: 9` against `total: 6`, and slides 0 and 1 are never mentioned at all.
+ *
+ * This is the same mapping the library's own dots use to resolve which one is
+ * active (`getOriginalIndexLookupTableByClones`), written out rather than
+ * imported: the helper is not on the package's export surface, only its
+ * internal deep path, and four lines of arithmetic is a smaller liability than
+ * an import a minor version can move.
+ *
+ * Its own module because two renderers draw the same carousel — the `slider`
+ * block and the posts slider section — and the one thing they must not do is
+ * disagree about what a slide index means.
+ *
+ * @param reportedIndex what the library said, in clone space
+ * @param total         the authored slide count, after any iterator expansion
+ * @param slidesToShow  the MEASURED value off the callback's state. The table
+ *                      branches on it, so a renderer's own breakpoint guess
+ *                      would silently select a different table. Before mount
+ *                      the library reports 0, which cannot resolve anything —
+ *                      hence null, so the caller reports nothing rather than
+ *                      guessing.
+ */
+export const authoredSlideIndex = (
+  reportedIndex: number,
+  total: number,
+  slidesToShow: number
+): number | null => {
+  if (!Number.isFinite(reportedIndex) || total <= 0) return null;
+  if (slidesToShow <= 0) return null;
+
+  const span = 2 * slidesToShow;
+  let authored: number;
+
+  if (total > span) {
+    if (reportedIndex < span) authored = total - span + reportedIndex;
+    else if (reportedIndex < total + span) authored = reportedIndex - span;
+    else authored = reportedIndex - (total + span);
+  } else {
+    // Short lists are cloned by concatenation, so the table is a modulo.
+    authored = ((reportedIndex % total) + total) % total;
+  }
+
+  return authored >= 0 && authored < total ? authored : null;
+};
+
+/**
+ * How many slide changes one carousel may report per page view when nothing
+ * attributed them to a shopper.
+ *
+ * An autoplaying carousel changes slide every few seconds for as long as the
+ * tab is open, and the library's callback carries no cause. Those go on their
+ * own tally key with this much lower ceiling, so a carousel spinning below the
+ * fold can neither drown out the controls of the same carousel nor eat the
+ * route budget every other moment on the page shares.
+ *
+ * It applies ONLY while a timer could be driving the carousel. With autoplay
+ * off, an unattributed change is a drag or a keyboard arrow — a real shopper
+ * action — and capping those at five would lose most of them.
+ */
+export const TIMER_SLIDE_CHANGE_CEILING = 5;