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

package/src/utils/__tests__/google-fonts.test.ts

@@ -0,0 +1,276 @@
+import {
+  buildGoogleFontLinkId,
+  buildGoogleFontStylesheetUrl,
+  collectGoogleFontFamilies,
+  loadGoogleFontStylesheet,
+  resolveGoogleFontFamily
+} from '../google-fonts';
+
+/**
+ * The one definition of "which Google stylesheet does this font need", shared
+ * by the server links and the client loaders. The server links only prevent
+ * the fallback-face flash if the client loaders recognise them, so the href
+ * format is pinned to what the loaders built before.
+ */
+
+// The URL and id the loaders built inline before the shared module existed,
+// copied verbatim so a change to the format fails here.
+const legacyUrl = (fontFamily: string, fontWeight?: string) => {
+  const cleanFontFamily = fontFamily.replace(/['"]/g, '').trim();
+  const weights = fontWeight || '100;300;400;500;600;700;800;900';
+  const fontParam = `${cleanFontFamily.replace(/\s+/g, '+')}:wght@${weights}`;
+  return `https://fonts.googleapis.com/css2?family=${fontParam}&display=swap`;
+};
+
+const legacyId = (fontFamily: string) =>
+  `google-font-${fontFamily
+    .replace(/['"]/g, '')
+    .trim()
+    .replace(/\s+/g, '-')
+    .toLowerCase()}`;
+
+describe('google font URL and id builders', () => {
+  it.each(['Krona One', 'Playfair Display', 'Jost', "'Plus Jakarta Sans'"])(
+    'match the previous inline format for %s',
+    (family) => {
+      expect(buildGoogleFontStylesheetUrl(family)).toBe(legacyUrl(family));
+      expect(buildGoogleFontLinkId(family)).toBe(legacyId(family));
+    }
+  );
+
+  it('keeps the requested weights, and the default when none are given', () => {
+    expect(buildGoogleFontStylesheetUrl('Jost', '400;700')).toBe(
+      legacyUrl('Jost', '400;700')
+    );
+    expect(buildGoogleFontStylesheetUrl('Jost', '')).toBe(legacyUrl('Jost'));
+  });
+
+  it('spells the exact href a browser cache already holds', () => {
+    expect(buildGoogleFontStylesheetUrl('Plus Jakarta Sans')).toBe(
+      'https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@100;300;400;500;600;700;800;900&display=swap'
+    );
+    expect(buildGoogleFontLinkId('Plus Jakarta Sans')).toBe(
+      'google-font-plus-jakarta-sans'
+    );
+  });
+});
+
+describe('resolveGoogleFontFamily', () => {
+  it('returns the cleaned family', () => {
+    expect(resolveGoogleFontFamily('"Krona One"')).toBe('Krona One');
+  });
+
+  it('takes the painting family of a stack instead of sending the whole stack to Google', () => {
+    expect(resolveGoogleFontFamily('Roboto, sans-serif')).toBe('Roboto');
+    expect(resolveGoogleFontFamily("'Open Sans', Arial, sans-serif")).toBe(
+      'Open Sans'
+    );
+  });
+
+  it.each([
+    ['inherit', 'inherit'],
+    ['an empty value', ''],
+    ['a system font', 'Arial'],
+    ['a system font stack', 'Times New Roman, serif'],
+    ['a generic family', 'sans-serif'],
+    ['a custom property', 'var(--theme-heading-font)'],
+    ['a custom property with a fallback', 'var(--x, Jost)'],
+    ['a row binding', '{{item.font}}'],
+    ['a value that would alter the query string', 'Jost&display=block'],
+    ['a non-string', 42]
+  ])('skips %s', (_label, value) => {
+    expect(resolveGoogleFontFamily(value)).toBeNull();
+  });
+
+  it('skips names served some other way, case-insensitively', () => {
+    expect(
+      resolveGoogleFontFamily('ZsaDisplay', new Set(['zsadisplay']))
+    ).toBeNull();
+  });
+});
+
+describe('collectGoogleFontFamilies', () => {
+  const block = (styles: Record<string, unknown>, blocks?: unknown[]) => ({
+    id: 'b',
+    type: 'text',
+    styles,
+    blocks
+  });
+
+  it('walks sections, blocks and nested blocks', () => {
+    const sections = [
+      {
+        styles: { 'font-family': { desktop: 'Jost' } },
+        blocks: [
+          block({ 'font-family': { desktop: 'Krona One' } }, [
+            block({}, [block({ 'font-family': { mobile: 'Playfair Display' } })])
+          ])
+        ]
+      }
+    ];
+
+    expect(collectGoogleFontFamilies(sections)).toEqual([
+      'Jost',
+      'Krona One',
+      'Playfair Display'
+    ]);
+  });
+
+  it('reads every breakpoint key present, not only desktop and mobile', () => {
+    const sections = [
+      {
+        blocks: [
+          block({
+            'font-family': {
+              desktop: 'Krona One',
+              tablet: 'Jost',
+              mobile: 'Playfair Display'
+            }
+          })
+        ]
+      }
+    ];
+
+    expect(collectGoogleFontFamilies(sections)).toEqual([
+      'Krona One',
+      'Jost',
+      'Playfair Display'
+    ]);
+  });
+
+  it('reads scalar values, camelCase keys and part or state keys', () => {
+    const sections = [
+      {
+        blocks: [
+          block({
+            fontFamily: 'Jost',
+            'title/font-family': { desktop: 'Krona One' },
+            'title/hover/font-family': { desktop: 'Playfair Display' },
+            ':scrolled/font-family': { desktop: 'Plus Jakarta Sans' },
+            color: { desktop: 'Lato' }
+          })
+        ]
+      }
+    ];
+
+    expect(collectGoogleFontFamilies(sections)).toEqual([
+      'Jost',
+      'Krona One',
+      'Playfair Display',
+      'Plus Jakarta Sans'
+    ]);
+  });
+
+  it('lists each family once', () => {
+    const sections = [
+      {
+        blocks: [
+          block({ 'font-family': { desktop: 'Jost', mobile: "'Jost'" } }),
+          block({ 'font-family': { desktop: 'Jost, sans-serif' } })
+        ]
+      },
+      { blocks: [block({ 'font-family': { desktop: 'Jost' } })] }
+    ];
+
+    expect(collectGoogleFontFamilies(sections)).toEqual(['Jost']);
+  });
+
+  it('skips inherit, system fonts, custom properties and uploaded faces', () => {
+    const sections = [
+      {
+        blocks: [
+          block({
+            'font-family': {
+              desktop: 'inherit',
+              tablet: 'Arial, sans-serif',
+              mobile: 'var(--brand-font)'
+            }
+          }),
+          block({ 'font-family': { desktop: "'ZsaDisplay', sans-serif" } }),
+          block({ 'font-family': { desktop: 'Krona One' } })
+        ]
+      }
+    ];
+    const settings = {
+      customFonts: [{ name: 'ZsaDisplay', sources: [] }]
+    };
+
+    expect(collectGoogleFontFamilies(sections, settings)).toEqual(['Krona One']);
+  });
+
+  it('includes the typography variants of the theme settings', () => {
+    const settings = {
+      typography: [
+        { key: 'heading', fontFamily: 'Playfair Display' },
+        { key: 'body', fontFamily: 'Plus Jakarta Sans' },
+        { key: 'caption', fontFamily: 'inherit' },
+        { key: 'label' }
+      ]
+    };
+
+    expect(collectGoogleFontFamilies([], settings)).toEqual([
+      'Playfair Display',
+      'Plus Jakarta Sans'
+    ]);
+  });
+
+  it('has nothing to collect from nothing', () => {
+    expect(collectGoogleFontFamilies(null, null)).toEqual([]);
+    expect(
+      collectGoogleFontFamilies([{ styles: null, blocks: null }], {})
+    ).toEqual([]);
+  });
+});
+
+describe('loadGoogleFontStylesheet', () => {
+  const stylesheets = (href: string) =>
+    Array.from(document.querySelectorAll('link[rel="stylesheet"]')).filter(
+      (link) => link.getAttribute('href') === href
+    );
+
+  afterEach(() => {
+    document.head.innerHTML = '';
+  });
+
+  it('appends the stylesheet once, with the shared id and href', () => {
+    loadGoogleFontStylesheet('Krona One');
+    loadGoogleFontStylesheet('Krona One');
+
+    const links = stylesheets(buildGoogleFontStylesheetUrl('Krona One'));
+    expect(links).toHaveLength(1);
+    expect(links[0].id).toBe('google-font-krona-one');
+  });
+
+  it('does not append a duplicate when the document links the same href without the id', () => {
+    // What the server render can leave behind: React hoists the link as a
+    // resource, and the id is not guaranteed to survive.
+    const serverLink = document.createElement('link');
+    serverLink.setAttribute('rel', 'stylesheet');
+    serverLink.setAttribute('href', buildGoogleFontStylesheetUrl('Krona One'));
+    document.head.appendChild(serverLink);
+
+    loadGoogleFontStylesheet('Krona One');
+
+    expect(stylesheets(buildGoogleFontStylesheetUrl('Krona One'))).toHaveLength(
+      1
+    );
+  });
+
+  it('stands down for an element that already carries the id', () => {
+    const earlier = document.createElement('link');
+    earlier.id = 'google-font-krona-one';
+    document.head.appendChild(earlier);
+
+    loadGoogleFontStylesheet('Krona One');
+
+    expect(document.querySelectorAll('link')).toHaveLength(1);
+  });
+
+  it('appends nothing for a value with nothing to fetch', () => {
+    loadGoogleFontStylesheet('inherit');
+    loadGoogleFontStylesheet('Arial, sans-serif');
+    loadGoogleFontStylesheet('var(--brand-font)');
+
+    expect(document.querySelectorAll('link')).toHaveLength(0);
+  });
+});

package/src/utils/carousel-ssr.tsx

@@ -268,8 +268,25 @@ export const useCarouselSsr = (options: {
     carouselProps: { ssr: true, deviceType: CAROUSEL_SSR_DEVICE_TYPE },
     gateProps: gated ? { [CAROUSEL_SSR_GATE_ATTRIBUTE]: scopeId } : {},
     scopeClass: `${CAROUSEL_SSR_SCOPE_PREFIX}${scopeId}`,
+    /*
+     * `dangerouslySetInnerHTML`, never a text child. React 18's server renderer
+     * (Next 14) HTML-escapes text children, and `<style>` is raw text the
+     * browser does not decode: the selector reached the page as
+     * `[data-carousel-ssr=&quot;…&quot;] …&gt;.react-multi-carousel-track`,
+     * was dropped as invalid, and the track painted at about half the viewport
+     * until the library measured at mount — the collapse the header describes.
+     *
+     * Verbatim is safe here: the sheet is built only from `carouselSsrScopeId`
+     * output (`[a-zA-Z0-9_-]`) and numeric band values, so it cannot contain a
+     * `</style` breakout. The client's first render passes the same string, so
+     * hydration compares equal.
+     */
     gateStyle: gated ? (
-      <style>{buildCarouselSsrCss(scopeId, responsive)}</style>
+      <style
+        dangerouslySetInnerHTML={{
+          __html: buildCarouselSsrCss(scopeId, responsive)
+        }}
+      />
     ) : null
   };
 };

package/src/utils/css-safety.ts

@@ -7,6 +7,14 @@
  * lets the following markup execute in the visitor's browser (stored XSS via
  * editor-controlled style values). Legitimate CSS never contains the literal
  * `</style`, so neutralizing it is safe for real themes.
+ *
+ * Why `dangerouslySetInnerHTML` and never a text child (`<style>{css}</style>`):
+ * React 18's server renderer — Next 14, which v1 brands run — HTML-escapes text
+ * children, and because `<style>` is raw text the browser never decodes them.
+ * `[data-x="id"] a>b` arrives as `[data-x=&quot;id&quot;] a&gt;b`, the selector
+ * is invalid, and the whole rule is dropped from first paint. React 19 writes
+ * `<style>` text verbatim, which is why this package's own React 19 tests could
+ * not see it; `jest/react-18-style-text.ts` puts the old escaping back for tests.
  */
 
 /**

package/src/utils/google-fonts.ts

@@ -0,0 +1,254 @@
+import { hasBindingToken } from './iterator-utils';
+
+/**
+ * Google Fonts, spelled once for every render that loads them.
+ *
+ * A composition names a Google family in its styles (`font-family: Krona One`)
+ * and the generated section CSS prints it with no fallback stack. The
+ * stylesheet declaring that face used to be appended only by client effects,
+ * so until hydration ran the browser painted those words in its default serif
+ * and swapped the real face in seconds later. The placeholder now links the
+ * same stylesheets from its server render (chrome/theme-google-fonts-links.tsx)
+ * and the client loaders stand down for whatever the document already links.
+ *
+ * That stand-down only works if both sides build the href and the id the same
+ * way, which is why the builders live here and nowhere else.
+ */
+
+export const GOOGLE_FONTS_CSS_ORIGIN = 'https://fonts.googleapis.com';
+
+/** Where the face files themselves come from. */
+export const GOOGLE_FONTS_FILES_ORIGIN = 'https://fonts.gstatic.com';
+
+/** Every weight — what the loaders have always requested. */
+export const GOOGLE_FONT_DEFAULT_WEIGHTS = '100;300;400;500;600;700;800;900';
+
+/** Installed on the shopper's machine; never requested from Google. */
+export const SYSTEM_FONT_FAMILIES = [
+  'Arial',
+  'Helvetica',
+  'Times New Roman',
+  'Georgia',
+  'Courier New',
+  'Verdana'
+];
+
+const SYSTEM_FONT_KEYS = new Set(
+  SYSTEM_FONT_FAMILIES.map((family) => family.toLowerCase())
+);
+
+/** CSS-wide keywords and generic families: valid values, never a download. */
+const NON_FAMILY_KEYWORDS = new Set([
+  'inherit',
+  'initial',
+  'unset',
+  'revert',
+  'revert-layer',
+  'serif',
+  'sans-serif',
+  'monospace',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'ui-serif',
+  'ui-sans-serif',
+  'ui-monospace',
+  'ui-rounded',
+  'emoji',
+  'math',
+  'fangsong',
+  '-apple-system',
+  'blinkmacsystemfont'
+]);
+
+/**
+ * The family is interpolated into a query string as-is, so anything beyond
+ * letters, digits, spaces and `._-` would change the request rather than name
+ * a font. Google's own family names never need more.
+ */
+const FAMILY_NAME_PATTERN = /^[\p{L}\p{N}][\p{L}\p{N} ._-]*$/u;
+
+/** Quotes and surrounding space removed — the spelling the loaders have always used. */
+export const cleanFontFamilyName = (fontFamily: string): string =>
+  fontFamily.replace(/['"]/g, '').trim();
+
+/**
+ * Byte for byte the URL the client loaders built inline before this module
+ * existed, so links already in a document and in the browser cache still match.
+ */
+export const buildGoogleFontStylesheetUrl = (
+  fontFamily: string,
+  weights?: string
+): string =>
+  `${GOOGLE_FONTS_CSS_ORIGIN}/css2?family=${cleanFontFamilyName(
+    fontFamily
+  ).replace(/\s+/g, '+')}:wght@${
+    weights || GOOGLE_FONT_DEFAULT_WEIGHTS
+  }&display=swap`;
+
+export const buildGoogleFontLinkId = (fontFamily: string): string =>
+  `google-font-${cleanFontFamilyName(fontFamily)
+    .replace(/\s+/g, '-')
+    .toLowerCase()}`;
+
+/**
+ * The family a `font-family` value would fetch from Google, or `null` when it
+ * names nothing to fetch.
+ *
+ * Only the first family of a stack is taken: it is the one that paints, and
+ * the editor's font select writes stacks (`Roboto, sans-serif`) that used to be
+ * sent to Google whole and came back as a 400.
+ *
+ * `excluded` holds lower-cased names served some other way — the theme's
+ * uploaded faces.
+ */
+export const resolveGoogleFontFamily = (
+  value: unknown,
+  excluded?: ReadonlySet<string>
+): string | null => {
+  if (typeof value !== 'string') return null;
+
+  // A custom property resolves elsewhere and a row binding per clone; neither
+  // names a family this render can know.
+  if (/var\(/i.test(value) || hasBindingToken(value)) return null;
+
+  const family = cleanFontFamilyName(value.split(',')[0] ?? '');
+  if (!family) return null;
+
+  const key = family.toLowerCase();
+  if (
+    NON_FAMILY_KEYWORDS.has(key) ||
+    SYSTEM_FONT_KEYS.has(key) ||
+    excluded?.has(key) ||
+    !FAMILY_NAME_PATTERN.test(family)
+  ) {
+    return null;
+  }
+
+  return family;
+};
+
+type FontStyleNode = {
+  styles?: unknown;
+  blocks?: unknown;
+};
+
+const FONT_FAMILY_PROPERTIES = new Set(['font-family', 'fontFamily']);
+
+/**
+ * Every authored `font-family` value in a style map: each breakpoint key that
+ * is present (tablet included, not just desktop/mobile), and the same property
+ * on a part or state (`title/font-family`, `:scrolled/font-family`), since the
+ * CSS generator emits all of them.
+ */
+const readFontFamilyValues = (styles: unknown): unknown[] => {
+  if (!styles || typeof styles !== 'object' || Array.isArray(styles)) {
+    return [];
+  }
+
+  const values: unknown[] = [];
+
+  Object.entries(styles as Record<string, unknown>).forEach(([key, entry]) => {
+    const property = key.slice(key.lastIndexOf('/') + 1);
+    if (!FONT_FAMILY_PROPERTIES.has(property)) return;
+
+    if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+      values.push(...Object.values(entry as Record<string, unknown>));
+    } else {
+      values.push(entry);
+    }
+  });
+
+  return values;
+};
+
+/**
+ * The unique Google families a composition uses: every section and block (at
+ * any depth) style, plus the theme's typography variants. Uploaded faces are
+ * left out — `ThemeFontsLink` serves those.
+ *
+ * Deduplicated by link id, the key both the server links and the client
+ * loaders deduplicate on; the first spelling seen wins.
+ */
+export const collectGoogleFontFamilies = (
+  sections: ReadonlyArray<FontStyleNode> | null | undefined,
+  settings?: Record<string, unknown> | null
+): string[] => {
+  const uploaded = new Set<string>();
+  const customFonts = settings?.customFonts;
+
+  if (Array.isArray(customFonts)) {
+    customFonts.forEach((font) => {
+      const name = (font as { name?: unknown })?.name;
+      if (typeof name === 'string' && name.trim()) {
+        uploaded.add(cleanFontFamilyName(name).toLowerCase());
+      }
+    });
+  }
+
+  const families = new Map<string, string>();
+
+  const add = (value: unknown) => {
+    const family = resolveGoogleFontFamily(value, uploaded);
+    if (!family) return;
+
+    const id = buildGoogleFontLinkId(family);
+    if (!families.has(id)) families.set(id, family);
+  };
+
+  const typography = settings?.typography;
+  if (Array.isArray(typography)) {
+    typography.forEach((variant) =>
+      add((variant as { fontFamily?: unknown })?.fontFamily)
+    );
+  }
+
+  const walk = (nodes: unknown) => {
+    if (!Array.isArray(nodes)) return;
+
+    nodes.forEach((node) => {
+      if (!node || typeof node !== 'object') return;
+
+      readFontFamilyValues((node as FontStyleNode).styles).forEach(add);
+      walk((node as FontStyleNode).blocks);
+    });
+  };
+
+  walk(sections);
+
+  return Array.from(families.values());
+};
+
+const documentLinksStylesheet = (href: string): boolean =>
+  Array.from(document.querySelectorAll('link[rel="stylesheet"]')).some(
+    (link) => link.getAttribute('href') === href
+  );
+
+/**
+ * Appends a family's stylesheet from the client — the editor picking a font
+ * mid-session, or a block whose value changes after mount — unless the
+ * document already links it.
+ */
+export const loadGoogleFontStylesheet = (
+  fontFamily: string,
+  fontWeight?: string
+): void => {
+  if (typeof document === 'undefined') return;
+
+  const family = resolveGoogleFontFamily(fontFamily);
+  if (!family) return;
+
+  const id = buildGoogleFontLinkId(family);
+  const href = buildGoogleFontStylesheetUrl(family, fontWeight);
+
+  // The id marks an earlier client call. The href is what the server render
+  // leaves behind: React hoists that link as a resource, and nothing promises
+  // the id survives, so checking the id alone would load the face twice.
+  if (document.getElementById(id) || documentLinksStylesheet(href)) return;
+
+  const link = document.createElement('link');
+  link.id = id;
+  link.href = href;
+  link.rel = 'stylesheet';
+  document.head.appendChild(link);
+};