@akinon/pz-theme 2.0.65-rc.0 → 2.0.66-beta.0

package/src/overlays/__tests__/server-read-path-client-free.test.ts

@@ -0,0 +1,119 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * The server-side theme-config read path must not reach a `'use client'`
+ * module.
+ *
+ * A Server Component importing a VALUE from a client module does not get the
+ * value: React hands back a client reference. `OVERLAY_WIDTH_UNITS` arrived as
+ * a function, `allowed.includes(...)` threw inside the registry parser, and the
+ * reader's catch turned that into an entirely empty theme config on the
+ * storefront — no modals, no theme settings, no data sources — with nothing
+ * logged. A composed modal simply never opened, and the trigger looked broken.
+ *
+ * No runtime test can catch this: Jest resolves a `'use client'` module like
+ * any other, so the constants are real arrays under test and every assertion
+ * passes while the storefront is broken. The import graph is the only place
+ * the mistake is visible, so this walks it from source.
+ */
+
+const SRC_ROOT = path.resolve(__dirname, '../..');
+
+/** Entry points that are read during a server render. */
+const SERVER_ENTRY_POINTS = [
+  'chrome/theme-config-source.ts',
+  'overlays/modal-registry.ts'
+];
+
+const CANDIDATE_EXTENSIONS = ['.ts', '.tsx', '/index.ts', '/index.tsx'];
+
+const resolveImport = (fromFile: string, specifier: string): string | null => {
+  // Only relative imports are ours to police; a bare specifier is a package,
+  // and a package's own client boundaries are its business.
+  if (!specifier.startsWith('.')) return null;
+
+  const base = path.resolve(path.dirname(fromFile), specifier);
+
+  for (const extension of CANDIDATE_EXTENSIONS) {
+    const candidate = `${base}${extension}`;
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return candidate;
+    }
+  }
+
+  return null;
+};
+
+const IMPORT_PATTERN = /(?:from|import)\s*['"]([^'"]+)['"]/g;
+
+/**
+ * Type-only imports are erased at compile time, so they cannot carry a client
+ * reference and a server module may freely import a type from a client module.
+ */
+const isTypeOnlyImport = (source: string, index: number): boolean => {
+  const statementStart = source.lastIndexOf('import', index);
+  if (statementStart === -1) return false;
+
+  return /^import\s+type\b/.test(source.slice(statementStart, index));
+};
+
+const isClientModule = (source: string): boolean =>
+  /^\s*(['"])use client\1/.test(source);
+
+const collectReachableModules = (entryPoints: string[]): Map<string, string> => {
+  const visited = new Map<string, string>();
+  const queue = entryPoints.map((entry) => path.join(SRC_ROOT, entry));
+
+  while (queue.length > 0) {
+    const file = queue.shift() as string;
+    if (visited.has(file)) continue;
+
+    const source = fs.readFileSync(file, 'utf8');
+    visited.set(file, source);
+
+    for (const match of source.matchAll(IMPORT_PATTERN)) {
+      if (isTypeOnlyImport(source, match.index ?? 0)) continue;
+
+      const resolved = resolveImport(file, match[1]);
+      if (resolved) queue.push(resolved);
+    }
+  }
+
+  return visited;
+};
+
+describe('server-side theme-config read path', () => {
+  it('reaches no "use client" module', () => {
+    const reachable = collectReachableModules(SERVER_ENTRY_POINTS);
+
+    const clientModules = Array.from(reachable.entries())
+      .filter(([, source]) => isClientModule(source))
+      .map(([file]) => path.relative(SRC_ROOT, file));
+
+    expect(clientModules).toEqual([]);
+  });
+
+  it('sees the overlay tokens as real values, not client references', () => {
+    // Guards the specific shape of the original break: the parser calls
+    // `.includes` on this array and `.slice` on the colour.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const tokens = require('../overlay-tokens');
+
+    expect(Array.isArray(tokens.OVERLAY_WIDTH_UNITS)).toBe(true);
+    expect(typeof tokens.OVERLAY_BACKDROP_COLOR).toBe('string');
+    expect(typeof tokens.OVERLAY_BACKDROP_OPACITY).toBe('number');
+  });
+
+  it('keeps the tokens importable from the client surface too', () => {
+    // The re-export is what stops this fix from breaking every existing
+    // `from './overlay-surface'` import.
+    const surfaceSource = fs.readFileSync(
+      path.join(SRC_ROOT, 'overlays/overlay-surface.tsx'),
+      'utf8'
+    );
+
+    expect(surfaceSource).toMatch(/export\s*{[^}]*OVERLAY_WIDTH_UNITS/);
+    expect(surfaceSource).toMatch(/from '\.\/overlay-tokens'/);
+  });
+});

package/src/overlays/modal-registry.ts

@@ -1,12 +1,15 @@
 import { modalSlug } from '../chrome/placeholder-slugs';
 import { devWarn } from '../utils/dev-warn';
 import type { VisibilityRules } from '../utils/visibility-rules';
+// From `overlay-tokens`, NOT from `overlay-surface`: this module is parsed on
+// the server, and a value imported from a `'use client'` module arrives as a
+// client reference rather than the value itself.
 import {
   OVERLAY_BACKDROP_COLOR,
   OVERLAY_BACKDROP_OPACITY,
   OVERLAY_WIDTH_UNITS,
   type OverlayWidthUnit
-} from './overlay-surface';
+} from './overlay-tokens';
 
 /**
  * The modal registry: what modals this theme has, read off `theme-config`.

package/src/overlays/overlay-surface.tsx

@@ -2,6 +2,11 @@
 
 import React from 'react';
 import { partAttrs } from '../utils';
+import {
+  OVERLAY_BACKDROP_COLOR,
+  OVERLAY_BACKDROP_OPACITY
+} from './overlay-tokens';
+import type { OverlayPresentation, OverlayWidthUnit } from './overlay-tokens';
 
 /**
  * The overlay surface: how a panel arrives over the page, and what it looks
@@ -22,18 +27,18 @@ import { partAttrs } from '../utils';
  * `panel-legacy-golden.json` pins byte for byte. New callers pass their own.
  */
 
-export type OverlayPresentation = 'modal' | 'drawer' | 'sheet' | 'anchored';
-
-export const OVERLAY_PRESENTATIONS: OverlayPresentation[] = [
-  'modal',
-  'drawer',
-  'sheet',
-  'anchored'
-];
-
-export type OverlayWidthUnit = 'px' | '%' | 'vw';
-
-export const OVERLAY_WIDTH_UNITS: OverlayWidthUnit[] = ['px', '%', 'vw'];
+/**
+ * Re-exported from `overlay-tokens.ts`, which owns them so the server-side
+ * registry parser can import them without going through this client module.
+ * Client callers keep importing from here.
+ */
+export {
+  OVERLAY_PRESENTATIONS,
+  OVERLAY_WIDTH_UNITS,
+  OVERLAY_BACKDROP_COLOR,
+  OVERLAY_BACKDROP_OPACITY
+} from './overlay-tokens';
+export type { OverlayPresentation, OverlayWidthUnit } from './overlay-tokens';
 
 /**
  * The overlay width as CSS. Unit-less callers (the panel block, whose markup
@@ -58,10 +63,6 @@ export const clampOverlayNumber = (
   return Math.min(max, Math.max(min, numeric));
 };
 
-/** Backdrop paint defaults — what every published surface shipped with. */
-export const OVERLAY_BACKDROP_COLOR = '#000000';
-export const OVERLAY_BACKDROP_OPACITY = 50;
-
 const HEX_COLOR_PATTERN = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
 
 /**

package/src/overlays/overlay-tokens.ts

@@ -0,0 +1,34 @@
+/**
+ * The overlay vocabulary: presentations, width units and backdrop defaults.
+ *
+ * Deliberately NOT in `overlay-surface.tsx`, which is a `'use client'` module.
+ * `modal-registry.ts` normalises the registry on the SERVER — it is what
+ * `theme-config-source.ts` reads `theme_config` through — and a server module
+ * importing a value from a client module does not receive the value: React
+ * hands back a client reference, so `OVERLAY_WIDTH_UNITS` arrives as a
+ * function and `allowed.includes(...)` throws. That throw used to surface as
+ * an entirely EMPTY theme config on the storefront (no modals, no settings, no
+ * data sources), because the registry is parsed first and the reader's catch
+ * swallows the reason.
+ *
+ * So the shared vocabulary lives in a module both sides can import. Anything
+ * here must stay free of React and of client-only APIs; `overlay-surface.tsx`
+ * re-exports it so client callers keep their existing import path.
+ */
+
+export type OverlayPresentation = 'modal' | 'drawer' | 'sheet' | 'anchored';
+
+export const OVERLAY_PRESENTATIONS: OverlayPresentation[] = [
+  'modal',
+  'drawer',
+  'sheet',
+  'anchored'
+];
+
+export type OverlayWidthUnit = 'px' | '%' | 'vw';
+
+export const OVERLAY_WIDTH_UNITS: OverlayWidthUnit[] = ['px', '%', 'vw'];
+
+/** Backdrop paint defaults — what every published surface shipped with. */
+export const OVERLAY_BACKDROP_COLOR = '#000000';
+export const OVERLAY_BACKDROP_OPACITY = 50;