@akinon/pz-theme 2.0.93-rc.0 → 2.0.94-beta.0

package/CHANGELOG.md

@@ -1,38 +1,27 @@
 # @akinon/pz-theme
 
-## 2.0.93-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea41430]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71d]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6c]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a631]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b]
-  - @akinon/next@2.0.93-rc.0
-  - @akinon/theme-contract@2.0.93-rc.0
+## 2.0.94-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.94-beta.0
+  - @akinon/theme-contract@2.0.94-beta.0
+
+## 2.0.93
+
+### Patch Changes
+
+- fc6b433f: ZERO-5000: Server-render carousel slides so sliders have height before hydration
+
+  Both carousel call sites rendered `<Carousel>` without `ssr`/`deviceType`, so the library returned no slides on the server and every slider shipped an empty track — zero height at first paint, full height once hydrated. On a storefront home page that meant the page opened on its second section and measured a CLS of 0.70.
+
+  Includes a behaviour change merchants can see: `slider-block`'s responsive map switched item counts at 768px while the block's own stylesheet, its `slidesToSlide` picker and the sibling posts slider all drew the line at 1024. It now draws it at 1024 too, so a slider between 768px and 1023px shows the mobile item count rather than the desktop one.
+
+  Also stops a video's native control bar appearing at first paint: `controls` and `poster` are stored per breakpoint and were being read raw, so controls were on for every video whatever the merchant chose and a poster they typed was silently dropped.
+
+  - @akinon/next@2.0.93
+  - @akinon/theme-contract@2.0.93
 
 ## 2.0.92
 

package/jest/setup.ts

@@ -17,6 +17,56 @@ if (!window.matchMedia) {
 
 window.scrollTo = (() => {}) as typeof window.scrollTo;
 
+// `react-dom/server` builds a MessageChannel at module scope, and jsdom has
+// none — importing it in a jsdom suite throws before a single test runs. Node's
+// own MessageChannel is not the answer: its ports keep the event loop alive, so
+// jest hangs after the last test instead of exiting.
+//
+// `renderToString` is synchronous and never waits on this channel; it only
+// needs the constructor to exist. So the shim delivers through a macrotask and
+// holds nothing. Needed by any test that asserts what a component emits on the
+// SERVER, which is the only way to catch a component that renders nothing until
+// it hydrates.
+class ShimMessagePort {
+  onmessage: ((event: { data: unknown }) => void) | null = null;
+  peer: ShimMessagePort | null = null;
+
+  postMessage(data: unknown) {
+    const peer = this.peer;
+    if (!peer) return;
+    setTimeout(() => peer.onmessage?.({ data }), 0);
+  }
+
+  start() {}
+  close() {}
+  addEventListener() {}
+  removeEventListener() {}
+}
+
+class ShimMessageChannel {
+  port1 = new ShimMessagePort();
+  port2 = new ShimMessagePort();
+
+  constructor() {
+    this.port1.peer = this.port2;
+    this.port2.peer = this.port1;
+  }
+}
+
+const globals = globalThis as unknown as Record<string, unknown>;
+if (typeof globals.MessageChannel === 'undefined') {
+  globals.MessageChannel = ShimMessageChannel;
+}
+
+// The other half of the same gap: the server renderer encodes its output, and
+// jsdom exposes no TextEncoder/TextDecoder. Node's are the real implementations
+// and hold nothing open.
+if (typeof globals.TextEncoder === 'undefined') {
+  const { TextEncoder, TextDecoder } = require('util');
+  globals.TextEncoder = TextEncoder;
+  globals.TextDecoder = TextDecoder;
+}
+
 class NoopObserver {
   observe() {}
   unobserve() {}

package/package.json

@@ -1,26 +1,27 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.93-rc.0",
+  "version": "2.0.94-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.93-rc.0",
+    "@akinon/next": "2.0.94-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.93-rc.0",
+    "@akinon/theme-contract": "2.0.94-beta.0",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
+    "react-multi-carousel": "2.8.4",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.93-rc.0",
+    "@akinon/next": "2.0.94-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__/carousel-ssr-render.test.tsx

@@ -0,0 +1,387 @@
+/**
+ * Slides that exist before hydration — asserted on the markup, with the REAL
+ * carousel library.
+ *
+ * Every other slider test in this package mocks `react-multi-carousel` away,
+ * which is right for testing what this package decides and useless for testing
+ * what the library emits. The bug being pinned here lived entirely inside the
+ * library: without `ssr`/`deviceType` its `CarouselItems` returns `null` on the
+ * server, so the track shipped empty, every slider band was 0px at first paint
+ * and the page opened on its second section. A test that stubbed the library
+ * would have gone on passing throughout.
+ *
+ * So: no carousel mock. Only `ThemeBlock` is stubbed, because what a slide
+ * CONTAINS is another file's subject and pulling the real one in would drag the
+ * whole renderer into a test about `<li>` elements.
+ *
+ * Note the jsdom caveat that makes these assertions possible at all: jsdom
+ * reports `offsetWidth: 0`, so `domFullyLoaded` is never true here and the
+ * library stays on its SSR path for the whole test. The gate this package owns
+ * is independent of that — it is React state, and it drops on its own effect,
+ * which is what "the gate is gone after mount" below actually measures.
+ */
+import React from 'react';
+import { act, render } from '@testing-library/react';
+import { renderToString } from 'react-dom/server';
+import { hydrateRoot } from 'react-dom/client';
+
+jest.mock('../../theme-block', () => ({
+  __esModule: true,
+  default: ({ block }: { block: { id: string } }) => (
+    <div data-testid="slide-content" data-id={block.id} />
+  )
+}));
+
+import SliderBlock from '../slider-block';
+import PostsSliderSection from '../../sections/posts-slider-section';
+import {
+  CAROUSEL_SSR_GATE_ATTRIBUTE,
+  CAROUSEL_SSR_SCOPE_PREFIX,
+  useCarouselSsr
+} from '../../utils/carousel-ssr';
+import { DESKTOP_MIN_WIDTH } from '../../utils/breakpoints';
+
+const slide = (id: string): any => ({
+  id,
+  type: 'text',
+  label: id,
+  value: '',
+  properties: {},
+  styles: {},
+  order: 0,
+  hidden: false
+});
+
+const sliderProps = (
+  properties: Record<string, unknown> = {},
+  over: Record<string, unknown> = {}
+) =>
+  ({
+    block: {
+      id: 'featured-brands',
+      type: 'slider',
+      label: 'slider',
+      value: '',
+      properties,
+      styles: {},
+      order: 0,
+      hidden: false,
+      blocks: ['a', 'b', 'c', 'd', 'e', 'f'].map(slide)
+    },
+    placeholderId: 'home',
+    sectionId: 'sec',
+    isDesigner: false,
+    ...over
+  } as any);
+
+const postsProps = (over: Record<string, unknown> = {}) =>
+  ({
+    section: {
+      id: 'complete-the-look',
+      type: 'posts-slider',
+      label: 'strip',
+      properties: { 'items-per-slide': { desktop: 4, tablet: 3, mobile: 2 } },
+      styles: {},
+      blocks: ['p', 'q', 'r', 's', 't'].map(slide)
+    },
+    placeholderId: 'home',
+    isDesigner: false,
+    ...over
+  } as any);
+
+/** The server's markup, parsed so it can be queried the way a browser would. */
+const serverDom = (element: React.ReactElement): HTMLElement => {
+  const host = document.createElement('div');
+  host.innerHTML = renderToString(element);
+  return host;
+};
+
+const slides = (root: ParentNode) =>
+  root.querySelectorAll('ul.react-multi-carousel-track > li');
+
+describe('the server emits an <li> per slide — it emitted none', () => {
+  it('does so for the slider block', () => {
+    expect(slides(serverDom(<SliderBlock {...sliderProps()} />))).toHaveLength(
+      6
+    );
+  });
+
+  it('does so for the posts slider section', () => {
+    expect(
+      slides(serverDom(<PostsSliderSection {...postsProps()} />))
+    ).toHaveLength(5);
+  });
+
+  it('sizes each of them, rather than leaving the track to collapse', () => {
+    const dom = serverDom(<SliderBlock {...sliderProps()} />);
+    // Four per view is the block's default, so the library's own SSR basis.
+    slides(dom).forEach((item) => {
+      expect((item as HTMLElement).style.flex).toBe('1 0 25.0%');
+    });
+  });
+});
+
+describe('the style, the gate and the element the selector targets', () => {
+  /**
+   * The point of resolving the selector against the real markup rather than
+   * comparing two strings: a rule can be emitted perfectly and still match
+   * nothing, and nothing about the output says so.
+   */
+  const assertSheetReachesItsTrack = (dom: HTMLElement) => {
+    const sheet = dom.querySelector('style');
+    expect(sheet).not.toBeNull();
+
+    const selector = (sheet as HTMLStyleElement).textContent!.split('{')[0];
+    expect(selector).toContain(`[${CAROUSEL_SSR_GATE_ATTRIBUTE}=`);
+
+    const matched = dom.querySelector(selector);
+    expect(matched).not.toBeNull();
+    expect(matched).toBe(dom.querySelector('ul.react-multi-carousel-track'));
+    expect((matched as HTMLElement).className).toContain(
+      'react-multi-carousel-track'
+    );
+  };
+
+  it('resolves to the real track in the slider block', () => {
+    assertSheetReachesItsTrack(serverDom(<SliderBlock {...sliderProps()} />));
+  });
+
+  it('resolves to the real track in the posts slider section', () => {
+    assertSheetReachesItsTrack(
+      serverDom(<PostsSliderSection {...postsProps()} />)
+    );
+  });
+
+  it('carries the gate on an ancestor and the scope on the carousel itself', () => {
+    const dom = serverDom(<SliderBlock {...sliderProps()} />);
+
+    const gated = dom.querySelector(
+      `[${CAROUSEL_SSR_GATE_ATTRIBUTE}="featured-brands"]`
+    );
+    const scoped = dom.querySelector(
+      `.${CAROUSEL_SSR_SCOPE_PREFIX}featured-brands`
+    );
+
+    expect(gated).not.toBeNull();
+    expect(scoped).not.toBeNull();
+    expect(gated!.contains(scoped!)).toBe(true);
+    expect(scoped!.className).toContain('react-multi-carousel-list');
+  });
+
+  it('keeps the scope class on the carousel, not the gate', () => {
+    // The scope is what stops a slider nested in another slider's slide being
+    // restyled by its parent's item count, so it must not vanish with the gate.
+    const dom = serverDom(<PostsSliderSection {...postsProps()} />);
+    const scoped = dom.querySelector(
+      `.${CAROUSEL_SSR_SCOPE_PREFIX}complete-the-look`
+    );
+    expect(scoped!.className).toContain('posts-slider-carousel');
+  });
+});
+
+describe('the client agrees with the server, then lets go', () => {
+  const hydrationErrors = (element: React.ReactElement) => {
+    const html = renderToString(element);
+    const host = document.createElement('div');
+    host.innerHTML = html;
+    document.body.appendChild(host);
+
+    const seen: string[] = [];
+    const spy = jest
+      .spyOn(console, 'error')
+      .mockImplementation((...args: unknown[]) => {
+        seen.push(args.map(String).join(' '));
+      });
+
+    let root: ReturnType<typeof hydrateRoot>;
+    act(() => {
+      root = hydrateRoot(host, element);
+    });
+
+    spy.mockRestore();
+    return {
+      host,
+      mismatches: seen.filter((message) =>
+        /hydrat|did not match/i.test(message)
+      ),
+      unmount: () => act(() => root.unmount())
+    };
+  };
+
+  it('hydrates the slider block with no mismatch', () => {
+    const { mismatches, unmount } = hydrationErrors(
+      <SliderBlock {...sliderProps()} />
+    );
+    expect(mismatches).toEqual([]);
+    unmount();
+  });
+
+  it('hydrates the posts slider section with no mismatch', () => {
+    const { mismatches, unmount } = hydrationErrors(
+      <PostsSliderSection {...postsProps()} />
+    );
+    expect(mismatches).toEqual([]);
+    unmount();
+  });
+
+  it('drops the gate and its stylesheet once mounted', () => {
+    const { host, unmount } = hydrationErrors(
+      <SliderBlock {...sliderProps()} />
+    );
+
+    expect(host.querySelector(`[${CAROUSEL_SSR_GATE_ATTRIBUTE}]`)).toBeNull();
+    expect(host.querySelector('style')).toBeNull();
+    // The scope class is not part of the gate and stays.
+    expect(
+      host.querySelector(`.${CAROUSEL_SSR_SCOPE_PREFIX}featured-brands`)
+    ).not.toBeNull();
+
+    unmount();
+  });
+
+  it('brings the gate back when the carousel remounts', () => {
+    /**
+     * `posts-slider-section` puts `currentBreakpoint` in its carousel key, so
+     * switching device in the editor REMOUNTS the library — back to
+     * `domLoaded: false`, back on the SSR path — and the gated sheet has to
+     * come back with it or the canvas paints desktop-basis slides for a frame.
+     *
+     * Asserted on the hook rather than on the DOM because the window being
+     * pinned is one RENDER long: `rerender` wraps the update in `act`, which
+     * flushes the effect that closes the gate before any query could see it
+     * open. So the renders themselves are recorded. Both call sites hand the
+     * hook the same `carouselKey` const they hand `<Carousel key>`, which is
+     * what makes this lifecycle theirs.
+     */
+    const gatedPerRender: boolean[] = [];
+    const responsive = {
+      desktop: { breakpoint: { max: 3000, min: DESKTOP_MIN_WIDTH }, items: 4 }
+    };
+
+    const Probe = ({ remountKey }: { remountKey: string }) => {
+      const ssr = useCarouselSsr({ id: 'strip', remountKey, responsive });
+      gatedPerRender.push(ssr.gateStyle !== null);
+      return null;
+    };
+
+    const { rerender } = render(<Probe remountKey="4-4-desktop" />);
+    expect(gatedPerRender).toEqual([true, false]);
+
+    rerender(<Probe remountKey="4-4-mobile" />);
+    expect(gatedPerRender).toEqual([true, false, true, false]);
+
+    // A re-render that does not change the key does not reopen it.
+    rerender(<Probe remountKey="4-4-mobile" />);
+    expect(gatedPerRender).toEqual([true, false, true, false, false]);
+  });
+});
+
+describe('deviceType is a constant, never the currentBreakpoint prop', () => {
+  /**
+   * Asserted through the width the library writes on each slide rather than
+   * through the prop, because the prop is only the mechanism. The block's
+   * default is 4 items on desktop and 1 on mobile; if `currentBreakpoint` were
+   * handed to `deviceType`, a mobile render would size its slides 100.0% and a
+   * desktop one 25.0%, and the two would disagree across hydration.
+   */
+  it.each(['desktop', 'tablet', 'mobile'])(
+    'sizes slides from the desktop band at currentBreakpoint=%s',
+    (breakpoint) => {
+      const dom = serverDom(
+        <SliderBlock {...sliderProps({}, { currentBreakpoint: breakpoint })} />
+      );
+      expect(slides(dom).length).toBe(6);
+      slides(dom).forEach((item) => {
+        expect((item as HTMLElement).style.flex).toBe('1 0 25.0%');
+      });
+    }
+  );
+
+  it('survives a breakpoint the responsive map has no band for', () => {
+    /**
+     * `slider-block`'s map has `desktop` and `mobile` and nothing else. With
+     * `currentBreakpoint` passed as `deviceType`, a slide peek sends the
+     * library into `getPartialVisibilityGutter`, which reads
+     * `responsive['tablet'].paritialVisibilityGutter` with no null check and
+     * throws — a blank section, in the editor, on a tablet.
+     */
+    expect(() =>
+      serverDom(
+        <SliderBlock
+          {...sliderProps(
+            { 'slide-peek': { desktop: 40, mobile: 24 } },
+            { currentBreakpoint: 'tablet' }
+          )}
+        />
+      )
+    ).not.toThrow();
+  });
+
+  /**
+   * THE OTHER CALL SITE, and the one a maintainer is likelier to "fix": its
+   * `<Carousel key>` already carries `currentBreakpoint`, so handing the same
+   * prop to `deviceType` looks like tidying. Its map has three bands with
+   * distinct counts, so the desktop basis is the only one that can be right on
+   * the server whatever the client thinks it is looking at.
+   */
+  it.each(['desktop', 'tablet', 'mobile'])(
+    'sizes the posts strip from the desktop band at currentBreakpoint=%s',
+    (breakpoint) => {
+      const dom = serverDom(
+        <PostsSliderSection
+          {...postsProps({ currentBreakpoint: breakpoint })}
+        />
+      );
+      expect(slides(dom).length).toBe(5);
+      slides(dom).forEach((item) => {
+        expect((item as HTMLElement).style.flex).toBe('1 0 25.0%');
+      });
+    }
+  );
+});
+
+describe('a carousel with no id stays off the SSR path', () => {
+  /**
+   * The width rule is scoped by the id, so without one it cannot be written —
+   * and opting into the library's SSR path WITHOUT that rule is worse than not
+   * opting in at all: the track is a flex item with an indefinite width, so
+   * the percentage basis collapses the strip. Two id-less sliders sharing a
+   * literal fallback would additionally restyle each other's slides with the
+   * wrong item count. Rendering nothing is the honest failure.
+   */
+  it('emits no slides, no gate attribute and no stylesheet', () => {
+    const withId = sliderProps();
+    const withoutId = {
+      ...withId,
+      // The same block in every other respect — six slides included — so a
+      // zero here can only come from the missing id.
+      block: { ...withId.block, id: '' }
+    };
+
+    expect(slides(serverDom(<SliderBlock {...withId} />)).length).toBe(6);
+
+    const dom = serverDom(<SliderBlock {...(withoutId as any)} />);
+
+    expect(slides(dom).length).toBe(0);
+    expect(dom.querySelector('[data-carousel-ssr]')).toBeNull();
+    expect(dom.querySelector('style')).toBeNull();
+  });
+});
+
+describe('the gated sheet switches where the responsive map switches', () => {
+  it('hands the 768-1023 band the mobile item count, not the desktop one', () => {
+    // The map used to say `desktop: { min: 768 }` while every other reader of
+    // this block drew the line at 1024. A sheet written against the old number
+    // would have applied the mobile count from 768 up while the mounted library
+    // applied the desktop count from 768 up — visible resize at hydration.
+    const sheet = serverDom(
+      <SliderBlock
+        {...sliderProps({ 'items-per-slide': { desktop: 4, mobile: 2 } })}
+      />
+    ).querySelector('style')!.textContent!;
+
+    expect(sheet).toContain(`@media (max-width:${DESKTOP_MIN_WIDTH - 1}px)`);
+    expect(sheet).toContain('flex:1 0 50.0% !important;');
+    expect(sheet).not.toContain('max-width:767px');
+  });
+});

package/src/blocks/__tests__/video-block.test.tsx

@@ -448,3 +448,92 @@ describe('VideoBlock', () => {
     });
   });
 });
+
+/**
+ * The editor stores every video property PER BREAKPOINT — `{ desktop: false }`,
+ * not `false`. Two of the reads here compared that object against a scalar and
+ * so could never see the merchant's answer.
+ *
+ * It went unnoticed because nothing painted a video before hydration. With the
+ * slides now server-rendered (ZERO-5000), a cold load paints a full-width
+ * native control bar under the header on a video the merchant switched controls
+ * off for.
+ */
+describe('properties the editor stores per breakpoint', () => {
+  const renderVideo = (properties: any, currentBreakpoint = 'desktop') =>
+    render(
+      <VideoBlock
+        block={
+          { value: 'https://cdn.example.com/lookbook.mp4', properties } as any
+        }
+        placeholderId="p1"
+        sectionId="s1"
+        isDesigner={false}
+        currentBreakpoint={currentBreakpoint}
+      />
+    ).container.querySelector('video') as HTMLVideoElement;
+
+  it('reads controls off the breakpoint, not off the object', () => {
+    // `properties.controls !== false` was true here: an object is not `false`.
+    expect(renderVideo({ controls: { desktop: false } }).controls).toBe(false);
+  });
+
+  it('still defaults controls on when the merchant set nothing', () => {
+    expect(renderVideo({}).controls).toBe(true);
+    expect(renderVideo({ controls: { desktop: true } }).controls).toBe(true);
+  });
+
+  it('lets a merchant hide controls on the phone and keep them on desktop', () => {
+    const authored = { controls: { desktop: true, mobile: false } };
+    expect(renderVideo(authored, 'desktop').controls).toBe(true);
+    expect(renderVideo(authored, 'mobile').controls).toBe(false);
+  });
+
+  it('keeps honouring a plain boolean, which is what older JSON holds', () => {
+    expect(renderVideo({ controls: false }).controls).toBe(false);
+    expect(renderVideo({ controls: true }).controls).toBe(true);
+  });
+
+  it('reaches a poster the merchant typed, instead of dropping it', () => {
+    // `typeof properties.poster === 'string'` is false for the object the
+    // editor writes, so the poster was stored, shown in the panel and lost.
+    const poster = renderVideo({
+      poster: { desktop: 'https://cdn.example.com/cover.jpg' }
+    }).poster;
+    expect(poster).toContain('cover.jpg');
+  });
+
+  it('falls back to the desktop poster on a breakpoint that authored none', () => {
+    expect(
+      renderVideo(
+        { poster: { desktop: 'https://cdn.example.com/cover.jpg' } },
+        'mobile'
+      ).poster
+    ).toContain('cover.jpg');
+  });
+
+  it('sets no poster when there is none, rather than an empty one', () => {
+    expect(renderVideo({}).getAttribute('poster')).toBeNull();
+    expect(
+      renderVideo({ poster: { desktop: '' } }).getAttribute('poster')
+    ).toBeNull();
+  });
+
+  it('leaves autoplay, loop and muted exactly as they behave today', () => {
+    /**
+     * Their stored value is an object too, and an object is truthy — so the
+     * bug is what makes them true. Reading them correctly would switch
+     * autoplay and loop OFF on every composition already published, which is a
+     * separate decision. This locks the current behaviour so the change cannot
+     * arrive by accident alongside the two above.
+     */
+    const video = renderVideo({
+      autoplay: { desktop: false },
+      loop: { desktop: false },
+      muted: { desktop: false }
+    });
+
+    expect(video.autoplay).toBe(true);
+    expect(video.loop).toBe(true);
+  });
+});