@akinon/pz-theme 2.0.162-rc.0 → 2.0.163-beta.0

package/src/custom/__tests__/use-theme-setting.test.tsx

@@ -367,100 +367,3 @@ describe('useThemeSetting — invalid declarations throw in development', () =>
     ).toThrow(/not one of the editor's control types/);
   });
 });
-
-describe('useThemeSetting — richtext', () => {
-  it('reads the breakpoint’s html and strips what the allowlist refuses', () => {
-    const { result } = renderHook(
-      () =>
-        useThemeSetting('body', {
-          type: 'richtext',
-          label: 'Body',
-          default: '<p>default</p>'
-        }),
-      {
-        wrapper: wrapperFor(
-          contextValue({
-            currentBreakpoint: 'mobile',
-            properties: {
-              body: {
-                desktop: '<p>desktop</p>',
-                mobile:
-                  '<p onclick="x()">mobile <script>x</script><b>bold</b></p>'
-              }
-            }
-          })
-        )
-      }
-    );
-
-    expect(result.current).toBe('<p>mobile <b>bold</b></p>');
-  });
-
-  it('sanitizes the authored default too', () => {
-    const { result } = renderHook(
-      () =>
-        useThemeSetting('body', {
-          type: 'richtext',
-          label: 'Body',
-          default: '<p><img src=x onerror=alert(1)>safe</p>'
-        }),
-      { wrapper: wrapperFor(contextValue()) }
-    );
-
-    expect(result.current).toBe('<p>safe</p>');
-  });
-
-  describe('written per language by the rich text control', () => {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const hooks = require('@akinon/next/hooks');
-    let localizationSpy: jest.SpyInstance;
-
-    const onPage = (locale: string) => {
-      const original = hooks.useLocalization;
-      localizationSpy = jest
-        .spyOn(hooks, 'useLocalization')
-        .mockImplementation(() => ({
-          ...original(),
-          locale,
-          defaultLocaleValue: 'tr',
-          locales: [{ value: 'tr' }, { value: 'en' }]
-        }));
-    };
-
-    afterEach(() => localizationSpy?.mockRestore());
-
-    const read = (body: unknown) =>
-      renderHook(
-        () =>
-          useThemeSetting('body', {
-            type: 'richtext',
-            label: 'Body',
-            default: '<p>default</p>'
-          }),
-        { wrapper: wrapperFor(contextValue({ properties: { body } })) }
-      ).result.current;
-
-    it('reads the page’s language out of the locale map and sanitizes it', () => {
-      onPage('tr');
-
-      expect(
-        read({
-          en: '<p>old</p>',
-          tr: '<p>sss <b>bold</b><script>x()</script></p>'
-        })
-      ).toBe('<p>sss <b>bold</b></p>');
-    });
-
-    it('falls back to the default language’s entry', () => {
-      onPage('en');
-
-      expect(read({ tr: '<p>türkçe</p>' })).toBe('<p>türkçe</p>');
-    });
-
-    it('still reads a breakpoint map written in the default language', () => {
-      onPage('tr');
-
-      expect(read({ desktop: '<p>desktop</p>' })).toBe('<p>desktop</p>');
-    });
-  });
-});

package/src/custom/collect.ts

@@ -42,7 +42,9 @@ import type { CustomSettingDescriptor, CustomSlotDescriptor } from './types';
  * through the one function below.
  */
 export type ThemeSettingChoice =
-  string | number | { label?: string; value: unknown };
+  | string
+  | number
+  | { label?: string; value: unknown };
 
 /**
  * Normalizes the shorthand into the `{label, value}` pairs the editor's select
@@ -78,8 +80,8 @@ export const normalizeSettingChoices = (
 
 /**
  * Why a control type is refused, named per type. "Unsupported" tells a
- * developer nothing actionable; each of these fails for its own reason and
- * each has a different way out.
+ * developer nothing actionable; each of these three fails for its own reason
+ * and each has a different way out.
  */
 const UNSUPPORTED_TYPE_REASON: Record<string, string> = {
   multiselect:
@@ -88,7 +90,10 @@ const UNSUPPORTED_TYPE_REASON: Record<string, string> = {
     'Use "select" and store one value until a per-type resolver exists',
   localetext:
     'the editor stores a localetext value as a locale map with no "desktop" key, so getResponsiveValue ' +
-    'falls back and the block would read its authored default forever. Use "text" and localize in the component'
+    'falls back and the block would read its authored default forever. Use "text" and localize in the component',
+  richtext:
+    'there is no safe renderer for it here — the sanitizer this repo owns parses by assigning to innerHTML ' +
+    'on a live element, and pz-theme renders on the server where there is no document at all. Use "text"'
 };
 
 /** The reason a setting key is refused, or null. Shared by the declared and the collected path. */

package/src/custom/property-types.ts

@@ -33,20 +33,19 @@ export type PropertyType = (typeof CUSTOM_PROPERTY_TYPES)[number];
  * The subset whose value provably survives the full round trip — panel write,
  * persistence, and resolution back into a prop.
  *
- * The two excluded members are excluded for reasons that were verified, not
- * guessed: `multiselect` and `localetext` are stored UNBUCKETED by the editor
- * (`theme-basic-properties.tsx:1547-1548` passes arrays and locale objects
- * through without the per-breakpoint wrapper). `getResponsiveValue` then
- * rejects an array with a devWarn and returns the fallback, and a locale
- * object has no `desktop` key so it does too. They can never deliver a
- * value until a per-type resolver exists.
+ * The three excluded members are excluded for reasons that were verified, not
+ * guessed:
  *
- * `richtext` is the one type with such a resolver. The editor's rich text
- * control writes per language (`{ tr: '<p>…</p>', en: … }`, unbucketed, like
- * `localetext`), so `useThemeSetting` reads the page's language out of the
- * map before the breakpoint read, then passes the html through
- * `sanitizeRichText`, a DOM-free allowlist, so a block can hand it to
- * `dangerouslySetInnerHTML` on the server as well as the client.
+ * - `multiselect` and `localetext` are stored UNBUCKETED by the editor
+ *   (`theme-basic-properties.tsx:1547-1548` passes arrays and locale objects
+ *   through without the per-breakpoint wrapper). `getResponsiveValue` then
+ *   rejects an array with a devWarn and returns the fallback, and a locale
+ *   object has no `desktop` key so it does too. They can never deliver a
+ *   value until a per-type resolver exists.
+ * - `richtext` has no safe renderer here. The allowlist sanitizer this repo
+ *   already owns parses by assigning to `innerHTML` on a live element, so the
+ *   sink is its first act — and pz-theme renders server-side, where there is
+ *   no `document` at all.
  *
  * Declaring one of these throws at define time rather than shipping a control
  * that silently shows the default forever.
@@ -60,11 +59,12 @@ export const SUPPORTED_PROPERTY_TYPES: readonly PropertyType[] = [
   'color',
   'image',
   'file',
-  'richtext',
   'typography',
   'icon'
 ];
 
-export const isSupportedPropertyType = (type: unknown): type is PropertyType =>
+export const isSupportedPropertyType = (
+  type: unknown
+): type is PropertyType =>
   typeof type === 'string' &&
   (SUPPORTED_PROPERTY_TYPES as readonly string[]).includes(type);

package/src/custom/use-theme-setting.ts

@@ -1,7 +1,6 @@
 'use client';
 
 import { getResponsiveValue } from '../utils';
-import { sanitizeRichText } from '../utils/sanitize-rich-text';
 import { devWarn } from '../utils/dev-warn';
 import {
   isLocalizedValue,
@@ -239,11 +238,6 @@ export function useThemeSetting<
 
   const defaults = splitDefault(declaration, valueLocale);
 
-  const finish = (value: unknown): TValue =>
-    (declaration.type === 'richtext'
-      ? sanitizeRichText(typeof value === 'string' ? value : '')
-      : value) as TValue;
-
   if (!context) {
     // A missing block context is never an error on its own: a developer
     // previewing the component in a storybook or a unit test should see the
@@ -260,7 +254,7 @@ export function useThemeSetting<
         `unreachable and the declared default is used instead. Render this ` +
         `component through a block registered with registerCustomBlocks().`
     );
-    return finish(defaults.page);
+    return defaults.page as TValue;
   }
 
   // Reported on every render rather than once from an effect: the collection
@@ -277,17 +271,7 @@ export function useThemeSetting<
   // attribute keys that were never declared. `node` rather than `block` so a
   // setting declared inside a custom SECTION reads the section's own
   // properties, which is where the editor writes it.
-  const authored = context.node.properties?.[key];
-
-  // The rich text control writes per language — `{ tr: '<p>…</p>', en: … }` —
-  // and the editor stores that map as it is, with no breakpoint key: the same
-  // shape that keeps `localetext` out (see `property-types.ts`). Read the
-  // page's language out of it first; what is left is a string or a breakpoint
-  // map, which the responsive read below already understands.
-  const stored =
-    declaration.type === 'richtext'
-      ? resolveLocalizedValue(authored, valueLocale)
-      : authored;
+  const stored = context.node.properties?.[key];
 
   // The sentinel again, for the same reason: handing `getResponsiveValue` an
   // undefined fallback would resolve an undeclared default to `''`, so a
@@ -296,15 +280,15 @@ export function useThemeSetting<
   const resolved = getResponsiveValue(stored, breakpoint, NOT_AUTHORED);
 
   if (resolved === NOT_AUTHORED) {
-    return finish(resolveAuthoredDefault(defaults.page, breakpoint));
+    return resolveAuthoredDefault(defaults.page, breakpoint) as TValue;
   }
 
   // The default-language text as the editor seeded it when the block was
   // placed, never changed since: still the author's copy, so it follows the
   // page's language. Anything the merchant typed is theirs and shows as typed.
   if (defaults.perLocale && resolved === defaults.base) {
-    return finish(defaults.page);
+    return defaults.page as TValue;
   }
 
-  return finish(resolved);
+  return resolved as TValue;
 }

package/src/editor-locale-bridge.tsx

@@ -4,28 +4,14 @@ import { useEffect } from 'react';
 import { useLocalization } from '@akinon/next/hooks';
 
 import { isTrustedEditorEvent, postToEditor } from './editor-bridge';
-import { useValueLocale } from './utils/localized-value';
 
 /**
  * The storefront half of the editor's Language dropdown.
  *
  * The editor starts that dropdown with English only and fills it from the
- * `LOCALE_UPDATE` frame the preview posts (`{ locale, locales, defaultLocale }`);
- * when the merchant picks another language it posts `LOCALE_UPDATE` back and
- * expects the preview to follow.
- *
- * The frame carries the storefront's default language as well. The editor's
- * per-language text controls store a plain string in that language and a map
- * in every other, so an editor that never heard it assumed English and gave
- * every Turkish-default store a stray `en` key (ZERO-5296).
- *
- * It is posted BEFORE the document reports ready (`IFRAME_READY`): the bridge
- * is a child of the placeholder wrapper, whose own effect posts that frame,
- * and React runs a child's effects first. The editor relies on the order — it
- * holds every per-language write until the preview is ready, and takes
- * "ready without languages" to mean a storefront that will never send them.
- *
- * For a long time the only code answering either direction
+ * `LOCALE_UPDATE` frame the preview posts (`{ locale, locales }`); when the
+ * merchant picks another language it posts `LOCALE_UPDATE` back and expects the
+ * preview to follow. For a long time the only code answering either direction
  * was the app-template's `LanguageSelect` — brand code. A brand whose header no
  * longer renders that component (a header composed through ChromeSlot, a
  * custom header section, a project older than the template) left the editor
@@ -68,7 +54,6 @@ export interface EditorLocaleOption {
 interface LocaleState {
   locale: string;
   locales: EditorLocaleOption[];
-  defaultLocale?: string;
   setLocale: (locale: string) => void;
 }
 
@@ -101,22 +86,15 @@ const toEditorLocales = (locales: unknown): EditorLocaleOption[] =>
           : entry.value
     }));
 
-const announcementKey = ({
-  locale,
-  locales,
-  defaultLocale
-}: Omit<LocaleState, 'setLocale'>) =>
-  JSON.stringify([locale, locales, defaultLocale ?? null]);
+const announcementKey = (locale: string, locales: EditorLocaleOption[]) =>
+  JSON.stringify([locale, locales]);
 
-const announce = ({ locale, locales, defaultLocale }: LocaleState) => {
-  const key = announcementKey({ locale, locales, defaultLocale });
+const announce = ({ locale, locales }: LocaleState) => {
+  const key = announcementKey(locale, locales);
   if (key === lastAnnounced) return;
   lastAnnounced = key;
 
-  postToEditor({
-    type: 'LOCALE_UPDATE',
-    data: { locale, locales, defaultLocale }
-  });
+  postToEditor({ type: 'LOCALE_UPDATE', data: { locale, locales } });
 };
 
 const handleEditorMessage = (event: MessageEvent) => {
@@ -137,7 +115,7 @@ const handleEditorMessage = (event: MessageEvent) => {
 
   // The editor is already showing `requested`. Recording it as announced keeps
   // the switch from being echoed back when the new locale reaches the page.
-  lastAnnounced = announcementKey({ ...current, locale: requested });
+  lastAnnounced = announcementKey(requested, current.locales);
   current.setLocale(requested);
 };
 
@@ -148,7 +126,6 @@ const handleEditorMessage = (event: MessageEvent) => {
  */
 export function EditorLocaleBridge(): null {
   const { locale, locales, setLocale } = useLocalization();
-  const { defaultLocale } = useValueLocale();
 
   useEffect(() => {
     if (!isFramed()) return;
@@ -170,14 +147,9 @@ export function EditorLocaleBridge(): null {
   useEffect(() => {
     if (!isFramed() || !locale) return;
 
-    current = {
-      locale,
-      locales: toEditorLocales(locales),
-      defaultLocale,
-      setLocale
-    };
+    current = { locale, locales: toEditorLocales(locales), setLocale };
     announce(current);
-  }, [locale, locales, defaultLocale, setLocale]);
+  }, [locale, locales, setLocale]);
 
   return null;
 }

package/src/load-placeholder-sections.ts

@@ -13,6 +13,7 @@ import {
   PreviewSnapshot
 } from './chrome/preview-snapshot-source';
 import { getThemeConfig, ThemeConfig } from './chrome/theme-config-source';
+import { withRegionDataSources } from './region/region-source'; // ZERO-5391
 import { readCustomBreakpoints } from './utils/breakpoints';
 // One acceptance rule for this loader and the designer canvas's client fetch
 // (utils/live-rows.ts), so the two cannot take different answers.
@@ -295,6 +296,11 @@ export async function loadPlaceholderSections(
       );
     }
 
+    // ZERO-5391: a region copy carries the data-source records its sections
+    // reference, so they resolve even while the shared theme-config is still
+    // cached without them; any other widget keeps theme-config's list.
+    const effectiveDataSources = withRegionDataSources(dataSources, data);
+
     const sections: Section[] = [];
 
     if (data?.attributes?.theme_editor_placeholder) {
@@ -460,7 +466,7 @@ export async function loadPlaceholderSections(
 
           const dataSourceWithData = await resolveSectionDataSource(
             dataSourceId,
-            dataSources,
+            effectiveDataSources, // ZERO-5391
             sectionSlug,
             sectionData
           );
@@ -504,8 +510,12 @@ export async function loadPlaceholderSections(
 
     return {
       sections,
-      placeholderId: data?.slug?.toString() || slug,
-      dataSources,
+      // ZERO-5391: always the canonical slug. A region copy
+      // (`<slug>-region-<cc>`) or a draft-mode per-widget preview copy answers
+      // under its own slug, while the editor and every frame address
+      // placeholders canonically.
+      placeholderId: slug,
+      dataSources: effectiveDataSources, // ZERO-5391
       themeSettings,
       customBreakpoints
     };

package/src/placeholder-registry.ts

@@ -13,6 +13,15 @@ import {
   STATE_PIN_CAPABILITIES,
   type StatePinCapability
 } from './state-pin-capabilities';
+// ZERO-5391: the per-country content handshake.
+import {
+  CONTENT_CAPABILITIES,
+  type ContentCapability
+} from './content-capabilities';
+import {
+  defaultLocaleForEditor,
+  localeUrlStrategyForEditor
+} from './region/editor-handshake';
 import type { CustomSectionCatalog } from './custom/section-types';
 import type { CustomPageCatalog } from './custom/page-types';
 import type { CustomCatalog } from './custom/types';
@@ -119,6 +128,32 @@ interface PlaceholdersAvailablePayload {
    * without the field would put it back to reporting nothing.
    */
   signalCapabilities?: readonly SignalCapability[];
+
+  // ZERO-5391: the three fields below are the per-country content handshake.
+  /**
+   * Which content THIS build can serve differently by audience (see
+   * `content-capabilities.ts`). The editor offers its country picker only to
+   * a storefront that lists `region-content`.
+   *
+   * Same terms as `actionCapabilities` above and on every frame for the same
+   * reason: the editor replaces what it holds with each frame, so a frame
+   * without the field would hide the picker again halfway through a session.
+   */
+  contentCapabilities?: readonly ContentCapability[];
+  /**
+   * `settings.localization.localeUrlStrategy`, 'hide-default-locale' when
+   * unset (see `region/editor-handshake.ts`). The editor moves its canvas
+   * between countries by switching the preview's locale, which under
+   * 'subdomain' would mean another origin. Every frame, on the same terms.
+   */
+  localeUrlStrategy?: string;
+  /**
+   * `settings.localization.defaultLocaleValue`: the locale the hide-*
+   * strategies serve without a path prefix, which the editor needs to link a
+   * country's page and to choose the locale a country switch lands on. Every
+   * frame, on the same terms.
+   */
+  defaultLocale?: string;
 }
 
 const isFramed = (): boolean =>
@@ -163,7 +198,13 @@ const flush = () => {
     // Outside the designer gate for the same reason, and for one more: the
     // panel it gates is the merchant's, so a slow handshake must not be the
     // difference between a section being trackable and not.
-    signalCapabilities: SIGNAL_CAPABILITIES
+    signalCapabilities: SIGNAL_CAPABILITIES,
+    // ZERO-5391: outside the designer gate for the same reasons. A fact about
+    // this theme version and two public locale settings: what decides whether
+    // the editor offers per-country content, and how it switches countries.
+    contentCapabilities: CONTENT_CAPABILITIES,
+    localeUrlStrategy: localeUrlStrategyForEditor(),
+    defaultLocale: defaultLocaleForEditor()
   };
 
   // Omitted entirely when nothing is registered: a build with no brand pages

package/src/region/__tests__/editor-handshake.test.ts

@@ -0,0 +1,144 @@
+/**
+ * ZERO-5391 — the locale settings the storefront hands the editor on
+ * PLACEHOLDERS_AVAILABLE, read from the brand's `settings` module.
+ *
+ * `settings` resolves to `jest/__mocks__/settings.js` unless a test swaps it.
+ * Each swap loads a fresh copy of the module under test, and `afterEach`
+ * removes the swap so the next test sees the shared stub again.
+ */
+
+// Type-only, so the module under test is still loaded fresh per test below;
+// it also keeps this file a module rather than a global script.
+import type * as HandshakeModule from '../editor-handshake';
+
+type Handshake = typeof HandshakeModule;
+
+const load = (settingsModule?: unknown): Handshake => {
+  let loaded: Handshake | undefined;
+  jest.isolateModules(() => {
+    if (settingsModule !== undefined) {
+      jest.doMock('settings', () => settingsModule);
+    }
+    loaded = require('../editor-handshake');
+  });
+  return loaded!;
+};
+
+describe('editor handshake settings', () => {
+  afterEach(() => {
+    jest.dontMock('settings');
+  });
+
+  it('reads the storefront settings the jest stub carries', () => {
+    const handshake = load();
+
+    expect(handshake.localeUrlStrategyForEditor()).toBe('hide-default-locale');
+    expect(handshake.defaultLocaleForEditor()).toBe('en-us');
+  });
+
+  it('passes the configured strategy and default locale through', () => {
+    // The brand's settings.js is CommonJS, so its default import is the
+    // module object itself.
+    const handshake = load({
+      localization: { localeUrlStrategy: 'subdomain', defaultLocaleValue: 'tr' }
+    });
+
+    expect(handshake.localeUrlStrategyForEditor()).toBe('subdomain');
+    expect(handshake.defaultLocaleForEditor()).toBe('tr');
+  });
+
+  it('reads an ES-module settings default export the same way', () => {
+    const handshake = load({
+      __esModule: true,
+      default: {
+        localization: {
+          localeUrlStrategy: 'show-all-locales',
+          defaultLocaleValue: 'en-ae'
+        }
+      }
+    });
+
+    expect(handshake.localeUrlStrategyForEditor()).toBe('show-all-locales');
+    expect(handshake.defaultLocaleForEditor()).toBe('en-ae');
+  });
+
+  it.each([
+    ['empty settings', {}],
+    ['no localization values', { localization: {} }],
+    ['a null localization', { localization: null }],
+    ['an undefined default export', { __esModule: true, default: undefined }]
+  ])('falls back to the defaults for %s', (_label, settingsModule) => {
+    const handshake = load(settingsModule);
+
+    // 'hide-default-locale' is what the core's locale middleware routes by
+    // when the strategy is unset, so the editor is told what really happens.
+    expect(handshake.localeUrlStrategyForEditor()).toBe('hide-default-locale');
+    expect(handshake.defaultLocaleForEditor()).toBe('');
+  });
+
+  it('treats an empty or non-string strategy as unset', () => {
+    expect(
+      load({
+        localization: { localeUrlStrategy: '' }
+      }).localeUrlStrategyForEditor()
+    ).toBe('hide-default-locale');
+    expect(
+      load({
+        localization: { localeUrlStrategy: 42 }
+      }).localeUrlStrategyForEditor()
+    ).toBe('hide-default-locale');
+  });
+
+  it('sends the default locale only when it is a string', () => {
+    expect(
+      load({
+        localization: { defaultLocaleValue: ['en'] }
+      }).defaultLocaleForEditor()
+    ).toBe('');
+    expect(
+      load({
+        localization: { defaultLocaleValue: '' }
+      }).defaultLocaleForEditor()
+    ).toBe('');
+  });
+
+  it('answers the defaults instead of throwing when the settings read throws', () => {
+    // The announce these values ride is the frame every editor load waits
+    // for; a settings read must never be able to take it down.
+    const handshake = load({
+      get localization() {
+        throw new Error('settings are not readable');
+      }
+    });
+
+    expect(handshake.localeUrlStrategyForEditor()).toBe('hide-default-locale');
+    expect(handshake.defaultLocaleForEditor()).toBe('');
+  });
+
+  it('reads nothing at module scope and the current settings on every call', () => {
+    const settingsModule = {
+      localization: {
+        localeUrlStrategy: 'hide-all-locales',
+        defaultLocaleValue: 'en'
+      }
+    };
+    const read = jest.fn(() => settingsModule.localization);
+    const handshake = load({
+      get localization() {
+        return read();
+      }
+    });
+
+    expect(read).not.toHaveBeenCalled();
+    expect(handshake.localeUrlStrategyForEditor()).toBe('hide-all-locales');
+
+    settingsModule.localization = {
+      localeUrlStrategy: 'show-all-locales',
+      defaultLocaleValue: 'tr'
+    };
+
+    expect(handshake.localeUrlStrategyForEditor()).toBe('show-all-locales');
+    expect(handshake.defaultLocaleForEditor()).toBe('tr');
+    expect(read).toHaveBeenCalledTimes(3);
+  });
+});