@akinon/pz-theme 2.0.105-rc.0 → 2.0.106-beta.0

package/CHANGELOG.md

@@ -1,40 +1,20 @@
 # @akinon/pz-theme
 
-## 2.0.105-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 [b1111d7b1]
-- Updated dependencies [1595d45]
-- Updated dependencies [dca1281]
-  - @akinon/next@2.0.105-rc.0
-  - @akinon/theme-contract@2.0.105-rc.0
+## 2.0.106-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.106-beta.0
+  - @akinon/theme-contract@2.0.106-beta.0
+
+## 2.0.105
+
+### Patch Changes
+
+- 4b9dd654: ZERO-5077: Render the carousel SSR stylesheet and the theme's Google font links on the server so the first paint is correct
+  - @akinon/next@2.0.105
+  - @akinon/theme-contract@2.0.105
 
 ## 2.0.104
 

package/jest/react-18-style-text.ts

@@ -0,0 +1,66 @@
+/**
+ * `react/jsx-runtime`, except that a `<style>` element's text children are
+ * HTML-escaped the way React 18's server renderer escapes them.
+ *
+ * This package's tests run React 19, whose server renderer writes `<style>`
+ * text verbatim. React 18 — Next 14, which v1 brands serve with — runs every
+ * text child through `escapeTextForBrowser`, and since `<style>` is raw text
+ * the browser never decodes the entities: a quoted attribute selector arrives
+ * as `[data-x=&quot;id&quot;]` and the whole rule is dropped. Under plain
+ * React 19 a `<style>{css}</style>` regression passes every test.
+ *
+ * Pre-escaping the child here makes React 19's `renderToString` emit the bytes
+ * React 18 served. `dangerouslySetInnerHTML` is left untouched, exactly as
+ * React 18 leaves it. Only for server-render assertions: on the client this
+ * would put the entities into `textContent`.
+ *
+ * `jest.mock` is hoisted above imports, so the factory has to `require` it:
+ *
+ *   jest.mock('react/jsx-runtime', () =>
+ *     require('../../../jest/react-18-style-text').jsxRuntime
+ *   );
+ *
+ * It reaches the MODULES the test requires, not JSX written in the test file
+ * itself: TypeScript emits that file's runtime import above the hoisted
+ * `jest.mock`, so its own `<style>` elements still use the real runtime.
+ */
+
+// `requireActual`, or this module would receive the mock it is building.
+const actual = jest.requireActual('react/jsx-runtime');
+
+const ENTITIES: Record<string, string> = {
+  '"': '&quot;',
+  '&': '&amp;',
+  "'": '&#x27;',
+  '<': '&lt;',
+  '>': '&gt;'
+};
+
+/** React 18's `escapeTextForBrowser`, character for character. */
+export const escapeTextLikeReact18 = (text: string): string =>
+  text.replace(/["&'<>]/g, (character) => ENTITIES[character]);
+
+const escapeChild = (child: unknown): unknown =>
+  typeof child === 'string' ? escapeTextLikeReact18(child) : child;
+
+type JsxFactory = (type: unknown, props: any, ...rest: unknown[]) => unknown;
+
+const withReact18StyleText =
+  (factory: JsxFactory): JsxFactory =>
+  (type, props, ...rest) => {
+    if (type !== 'style' || !props || props.children == null) {
+      return factory(type, props, ...rest);
+    }
+
+    const children = Array.isArray(props.children)
+      ? props.children.map(escapeChild)
+      : escapeChild(props.children);
+
+    return factory(type, { ...props, children }, ...rest);
+  };
+
+export const jsxRuntime = {
+  ...actual,
+  jsx: withReact18StyleText(actual.jsx),
+  jsxs: withReact18StyleText(actual.jsxs)
+};

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

package/src/__tests__/google-fonts-server-render.test.tsx

@@ -0,0 +1,231 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+// The Node build, not the browser one: it is the path a storefront actually
+// server-renders through.
+import { renderToStaticMarkup } from 'react-dom/server.node';
+
+jest.mock('server-only', () => ({}), { virtual: true });
+
+const loadPlaceholderSections = jest.fn();
+jest.mock('../load-placeholder-sections', () => ({
+  loadPlaceholderSections: (slug: string) => loadPlaceholderSections(slug)
+}));
+
+import ThemePlaceholder from '../theme-placeholder';
+import ThemePlaceholderWrapper from '../theme-placeholder-wrapper';
+import { ThemeGoogleFontsLinks } from '../chrome/theme-google-fonts-links';
+import { buildGoogleFontStylesheetUrl } from '../utils/google-fonts';
+import type { Section } from '../theme-section';
+
+/**
+ * A composed homepage painted its text in the browser's default serif first
+ * and swapped the theme's Google fonts in seconds later: the served HTML linked
+ * none of their stylesheets, and the section CSS names the families with no
+ * fallback stack. Only client effects appended the links, after hydration.
+ *
+ * The placeholder now links them from its server render, and the client
+ * loaders must not add a second copy of anything the document already has.
+ */
+
+const node = (id: string, extra: Record<string, unknown>) => ({
+  id,
+  label: id,
+  order: 0,
+  hidden: false,
+  properties: {},
+  styles: {},
+  ...extra
+});
+
+const HOMEPAGE = [
+  node('hero', {
+    type: 'generic-section',
+    name: 'hero',
+    blocks: [
+      node('headline', {
+        type: 'text',
+        styles: { 'font-family': { desktop: 'Krona One', mobile: 'Krona One' } }
+      }),
+      node('copy-group', {
+        type: 'group',
+        blocks: [
+          node('copy', {
+            type: 'text',
+            styles: {
+              'font-family': { desktop: 'Playfair Display', tablet: 'Jost' }
+            }
+          })
+        ]
+      })
+    ]
+  })
+] as unknown as Section[];
+
+const SETTINGS = {
+  typography: [{ key: 'body', fontFamily: 'Plus Jakarta Sans' }],
+  customFonts: [
+    {
+      name: 'ZsaDisplay',
+      sources: [{ dataUrl: 'data:font/woff2;base64,AAAA', format: 'woff2' }]
+    }
+  ]
+};
+
+const FAMILIES = ['Plus Jakarta Sans', 'Krona One', 'Playfair Display', 'Jost'];
+
+const parse = (html: string) => {
+  const container = document.createElement('div');
+  container.innerHTML = html;
+  return container;
+};
+
+const stylesheetsFor = (root: ParentNode, family: string) =>
+  Array.from(root.querySelectorAll('link[rel="stylesheet"]')).filter(
+    (link) =>
+      link.getAttribute('href') === buildGoogleFontStylesheetUrl(family)
+  );
+
+describe('ThemeGoogleFontsLinks', () => {
+  it('links one stylesheet per family from the server render', () => {
+    const markup = parse(
+      renderToStaticMarkup(
+        <ThemeGoogleFontsLinks sections={HOMEPAGE} settings={SETTINGS} />
+      )
+    );
+
+    FAMILIES.forEach((family) => {
+      const links = stylesheetsFor(markup, family);
+
+      expect(links).toHaveLength(1);
+      expect(links[0].getAttribute('data-pz-google-font')).toBe('true');
+      expect(links[0].getAttribute('data-precedence')).toBe(
+        'pz-theme-google-fonts'
+      );
+      expect(links[0].id).toMatch(/^google-font-/);
+    });
+
+    expect(markup.querySelectorAll('link[rel="stylesheet"]')).toHaveLength(
+      FAMILIES.length
+    );
+  });
+
+  it('preconnects to both Google origins, the face files anonymously', () => {
+    const markup = parse(
+      renderToStaticMarkup(
+        <ThemeGoogleFontsLinks sections={HOMEPAGE} settings={SETTINGS} />
+      )
+    );
+
+    const css = markup.querySelector(
+      'link[rel="preconnect"][href="https://fonts.googleapis.com"]'
+    );
+    const files = markup.querySelector(
+      'link[rel="preconnect"][href="https://fonts.gstatic.com"]'
+    );
+
+    expect(css).not.toBeNull();
+    expect(css?.hasAttribute('crossorigin')).toBe(false);
+    expect(files).not.toBeNull();
+    // An empty attribute is the anonymous CORS state.
+    expect(['', 'anonymous']).toContain(files?.getAttribute('crossorigin'));
+  });
+
+  it('renders nothing when the composition uses no Google family', () => {
+    const sections = [
+      node('s', {
+        blocks: [
+          node('b', {
+            styles: {
+              'font-family': {
+                desktop: 'inherit',
+                mobile: "'ZsaDisplay', sans-serif"
+              }
+            }
+          })
+        ]
+      })
+    ] as unknown as Section[];
+    // The uploaded face and no typography variants: nothing left for Google.
+    const settings = { customFonts: SETTINGS.customFonts };
+
+    expect(
+      renderToStaticMarkup(
+        <ThemeGoogleFontsLinks sections={sections} settings={settings} />
+      )
+    ).toBe('');
+    expect(
+      renderToStaticMarkup(<ThemeGoogleFontsLinks sections={null} settings={null} />)
+    ).toBe('');
+  });
+});
+
+describe('ThemePlaceholder', () => {
+  beforeEach(() => {
+    loadPlaceholderSections.mockReset();
+    loadPlaceholderSections.mockResolvedValue({
+      sections: HOMEPAGE,
+      placeholderId: 'homepage',
+      dataSources: [],
+      themeSettings: SETTINGS
+    });
+  });
+
+  it('links the composition’s Google fonts, so text never paints in the fallback face first', async () => {
+    const element = await ThemePlaceholder({ slug: 'homepage' });
+    const markup = parse(renderToStaticMarkup(element as React.ReactElement));
+
+    FAMILIES.forEach((family) => {
+      expect(stylesheetsFor(markup, family)).toHaveLength(1);
+    });
+    expect(markup.querySelectorAll('link[data-pz-google-font]')).toHaveLength(
+      FAMILIES.length
+    );
+  });
+});
+
+describe('the client loaders stand down for the server links', () => {
+  afterEach(() => {
+    document.head.innerHTML = '';
+  });
+
+  const mountWrapper = () =>
+    render(
+      <ThemePlaceholderWrapper
+        slug="homepage"
+        initialSections={HOMEPAGE}
+        initialPlaceholderId="homepage"
+        isDesignMode={false}
+        initialThemeSettings={SETTINGS}
+      />
+    );
+
+  it('adds no second copy on hydration, even when the hoisted link lost its id', () => {
+    document.head.insertAdjacentHTML(
+      'beforeend',
+      renderToStaticMarkup(
+        <ThemeGoogleFontsLinks sections={HOMEPAGE} settings={SETTINGS} />
+      )
+    );
+    document.head
+      .querySelectorAll('link[data-pz-google-font]')
+      .forEach((link) => link.removeAttribute('id'));
+
+    const { unmount } = mountWrapper();
+
+    FAMILIES.forEach((family) => {
+      expect(stylesheetsFor(document, family)).toHaveLength(1);
+    });
+
+    unmount();
+  });
+
+  it('still loads the fonts from the client when nothing linked them', () => {
+    const { unmount } = mountWrapper();
+
+    FAMILIES.forEach((family) => {
+      expect(stylesheetsFor(document, family)).toHaveLength(1);
+    });
+
+    unmount();
+  });
+});

package/src/blocks/__tests__/carousel-ssr-style-text.test.tsx

@@ -0,0 +1,151 @@
+/**
+ * The carousel gate sheet reaches the document byte for byte.
+ *
+ * It used to be a text child, `<style>{css}</style>`. React 18's server
+ * renderer escapes text children and `<style>` is raw text, so the storefront
+ * served `[data-carousel-ssr=&quot;…&quot;] …&gt;.react-multi-carousel-track`,
+ * the browser dropped the invalid rule, and a full-width hero slider painted at
+ * 746px in a 1440px viewport until hydration.
+ *
+ * `carousel-ssr-render.test.tsx` could not see it: these tests run React 19,
+ * which writes `<style>` text verbatim. The mocked runtime puts React 18's
+ * escaping back (see `jest/react-18-style-text.ts`).
+ */
+import React from 'react';
+import { renderToString } from 'react-dom/server';
+
+jest.mock('react/jsx-runtime', () =>
+  require('../../../jest/react-18-style-text').jsxRuntime
+);
+
+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,
+  useCarouselSsr
+} from '../../utils/carousel-ssr';
+import { DESKTOP_MIN_WIDTH } from '../../utils/breakpoints';
+
+const slide = (id: string, type = 'video'): any => ({
+  id,
+  type,
+  label: id,
+  value: '',
+  properties: {},
+  styles: {},
+  order: 0,
+  hidden: false
+});
+
+/** Every `<style>` body in the server HTML — what the browser parses as CSS. */
+const servedSheets = (html: string): string[] =>
+  Array.from(
+    html.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/g),
+    (match) => match[1]
+  );
+
+const expectVerbatimGateSheet = (html: string) => {
+  const sheet = servedSheets(html).find((css) =>
+    css.includes(CAROUSEL_SSR_GATE_ATTRIBUTE)
+  );
+
+  expect(sheet).toBeDefined();
+  expect(sheet).toContain(`[${CAROUSEL_SSR_GATE_ATTRIBUTE}="`);
+  expect(sheet).toContain('>.react-multi-carousel-track');
+  expect(sheet).not.toContain('&quot;');
+  expect(sheet).not.toContain('&gt;');
+};
+
+describe('the harness serves <style> text the way React 18 did', () => {
+  it('escapes a text child, so a text-child sheet cannot pass below', () => {
+    // If the components ever stopped receiving the mocked runtime, every
+    // assertion in this file would pass against the old markup without saying
+    // so. Required here rather than written as JSX: this file's own JSX binds
+    // the runtime before the mock is registered, a component module does not.
+    const { jsx } = require('react/jsx-runtime');
+    expect(
+      renderToString(jsx('style', { children: '[data-x="a"]>b' }))
+    ).toBe('<style>[data-x=&quot;a&quot;]&gt;b</style>');
+  });
+});
+
+describe('the carousel gate sheet is served verbatim', () => {
+  it('from the hook itself', () => {
+    const HeroCarousel = () => {
+      const ssr = useCarouselSsr({
+        id: 'hero-video',
+        remountKey: 'hero-video',
+        responsive: {
+          desktop: {
+            breakpoint: { max: 4000, min: DESKTOP_MIN_WIDTH },
+            items: 1
+          },
+          mobile: {
+            breakpoint: { max: DESKTOP_MIN_WIDTH - 1, min: 0 },
+            items: 1
+          }
+        }
+      });
+      return <div {...ssr.gateProps}>{ssr.gateStyle}</div>;
+    };
+
+    expectVerbatimGateSheet(renderToString(<HeroCarousel />));
+  });
+
+  it('from the slider block holding a hero video', () => {
+    expectVerbatimGateSheet(
+      renderToString(
+        <SliderBlock
+          {...({
+            block: {
+              id: 'hero-video',
+              type: 'slider',
+              label: 'Hero',
+              value: '',
+              properties: { 'items-per-slide': { desktop: 1, mobile: 1 } },
+              styles: {},
+              order: 0,
+              hidden: false,
+              blocks: [slide('campaign-film')]
+            },
+            placeholderId: 'home',
+            sectionId: 'hero',
+            isDesigner: false
+          } as any)}
+        />
+      )
+    );
+  });
+
+  it('from the posts slider section', () => {
+    expectVerbatimGateSheet(
+      renderToString(
+        <PostsSliderSection
+          {...({
+            section: {
+              id: 'complete-the-look',
+              type: 'posts-slider',
+              label: 'Complete the look',
+              properties: {
+                'items-per-slide': { desktop: 4, tablet: 3, mobile: 2 }
+              },
+              styles: {},
+              blocks: ['coat', 'scarf', 'boots', 'bag', 'belt'].map((id) =>
+                slide(id, 'text')
+              )
+            },
+            placeholderId: 'home',
+            isDesigner: false
+          } as any)}
+        />
+      )
+    );
+  });
+});