@akinon/pz-theme 2.0.109-rc.0 → 2.0.110-beta.0

package/CHANGELOG.md

@@ -1,40 +1,20 @@
 # @akinon/pz-theme
 
-## 2.0.109-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c2]
-- 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.109-rc.0
-  - @akinon/theme-contract@2.0.109-rc.0
+## 2.0.110-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.110-beta.0
+  - @akinon/theme-contract@2.0.110-beta.0
+
+## 2.0.109
+
+### Patch Changes
+
+- 55ab88c: ZERO-5083: Keep the theme editor's Language dropdown in sync from pz-theme, so brands whose header no longer renders the template LanguageSelect show their real languages and follow the editor's language switch
+  - @akinon/next@2.0.109
+  - @akinon/theme-contract@2.0.109
 
 ## 2.0.108
 

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.109-rc.0",
+  "version": "2.0.110-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.109-rc.0",
+    "@akinon/next": "2.0.110-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.109-rc.0",
+    "@akinon/theme-contract": "2.0.110-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.109-rc.0",
+    "@akinon/next": "2.0.110-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__/editor-locale-bridge.test.tsx

@@ -0,0 +1,272 @@
+import React from 'react';
+import { act, fireEvent, render } from '@testing-library/react';
+
+import { __resetEditorBridgeForTests } from '../editor-bridge';
+import {
+  __resetEditorLocaleBridgeForTests,
+  EditorLocaleBridge
+} from '../editor-locale-bridge';
+import ThemePlaceholderWrapper from '../theme-placeholder-wrapper';
+
+/**
+ * The editor's Language dropdown is filled by the preview, and the preview has
+ * to follow the dropdown back. That used to be the app-template's
+ * LanguageSelect's job, so a brand whose header no longer rendered it left the
+ * editor on a hard-coded English. The bridge now rides on every placeholder,
+ * and a page has several of them, so "once per page" is the property that
+ * matters most here, next to the two it must never break: no traffic outside
+ * the editor, and no switch ordered by anyone but the editor.
+ */
+
+const EDITOR_ORIGIN = 'http://localhost:5174';
+
+const SETTINGS_LOCALES = [
+  { value: 'en', label: 'English', apiValue: 'en-us', rtl: false },
+  { value: 'tr', label: 'Türkçe', apiValue: 'tr-tr', rtl: false }
+];
+
+const mockLocalization = {
+  locale: 'tr',
+  locales: SETTINGS_LOCALES as Array<Record<string, unknown>>,
+  setLocale: jest.fn()
+};
+
+jest.mock('@akinon/next/hooks', () => ({
+  __esModule: true,
+  useLocalization: () => ({
+    t: (path: string) => path,
+    currency: 'TRY',
+    currencies: ['TRY'],
+    setCurrency: () => {},
+    ...mockLocalization
+  })
+}));
+
+const originalParent = window.parent;
+const originalTop = window.top;
+
+const postMessage = jest.fn();
+
+const frameDocument = () => {
+  Object.defineProperty(window, 'top', {
+    configurable: true,
+    value: { name: 'designer' }
+  });
+  Object.defineProperty(window, 'parent', {
+    configurable: true,
+    value: { postMessage }
+  });
+  // Before the editor has spoken, the bridge finds it through the referrer.
+  Object.defineProperty(document, 'referrer', {
+    configurable: true,
+    value: `${EDITOR_ORIGIN}/builder`
+  });
+};
+
+const unframeDocument = () => {
+  Object.defineProperty(window, 'top', {
+    configurable: true,
+    value: originalTop
+  });
+  Object.defineProperty(window, 'parent', {
+    configurable: true,
+    value: originalParent
+  });
+};
+
+const localeFrames = () =>
+  postMessage.mock.calls
+    .map(([message]) => message)
+    .filter((message) => message?.type === 'LOCALE_UPDATE');
+
+const editorSwitch = (locale: string, origin = EDITOR_ORIGIN) =>
+  act(() => {
+    fireEvent(
+      window,
+      new MessageEvent('message', {
+        origin,
+        data: { type: 'LOCALE_UPDATE', data: { locale, locales: [] } }
+      })
+    );
+  });
+
+const placeholder = (slug: string) => (
+  <ThemePlaceholderWrapper
+    key={slug}
+    slug={slug}
+    initialSections={[]}
+    initialPlaceholderId={slug}
+    isDesignMode={false}
+  />
+);
+
+beforeEach(() => {
+  __resetEditorBridgeForTests();
+  __resetEditorLocaleBridgeForTests();
+  postMessage.mockClear();
+  mockLocalization.locale = 'tr';
+  mockLocalization.locales = SETTINGS_LOCALES;
+  mockLocalization.setLocale = jest.fn();
+  delete (window as { __iframeReadySent?: boolean }).__iframeReadySent;
+});
+
+describe('inside the editor', () => {
+  beforeEach(frameDocument);
+  afterAll(unframeDocument);
+
+  it('announces the languages once per page, however many placeholders mount', () => {
+    render(
+      <>
+        {placeholder('header')}
+        {placeholder('home-body')}
+        {placeholder('footer')}
+      </>
+    );
+
+    expect(localeFrames()).toHaveLength(1);
+  });
+
+  it("posts the brand's locales in the editor's shape", () => {
+    mockLocalization.locales = [
+      ...SETTINGS_LOCALES,
+      // No label in the settings: the dropdown shows the code, not a blank.
+      { value: 'de', apiValue: 'de-de' }
+    ];
+
+    render(placeholder('header'));
+
+    expect(localeFrames()).toEqual([
+      expect.objectContaining({
+        type: 'LOCALE_UPDATE',
+        data: {
+          locale: 'tr',
+          locales: [
+            { value: 'en', label: 'English' },
+            { value: 'tr', label: 'Türkçe' },
+            { value: 'de', label: 'de' }
+          ]
+        }
+      })
+    ]);
+    const [, targetOrigin] = postMessage.mock.calls.find(
+      ([message]) => message?.type === 'LOCALE_UPDATE'
+    );
+    expect(targetOrigin).toBe(EDITOR_ORIGIN);
+  });
+
+  it("follows the editor's switch exactly once, with several placeholders mounted", () => {
+    render(
+      <>
+        {placeholder('header')}
+        {placeholder('home-body')}
+        {placeholder('footer')}
+      </>
+    );
+
+    editorSwitch('en');
+
+    expect(mockLocalization.setLocale).toHaveBeenCalledTimes(1);
+    expect(mockLocalization.setLocale).toHaveBeenCalledWith('en');
+  });
+
+  it('does not echo the switch back to the editor', () => {
+    const view = render(<EditorLocaleBridge />);
+    postMessage.mockClear();
+
+    editorSwitch('en');
+
+    // The locale reaches the page (a same-document switch; the cores reload,
+    // which starts a fresh document and a fresh announcement anyway).
+    mockLocalization.locale = 'en';
+    view.rerender(<EditorLocaleBridge />);
+
+    expect(localeFrames()).toHaveLength(0);
+  });
+
+  it('tells the editor when the storefront changes language on its own', () => {
+    const view = render(<EditorLocaleBridge />);
+    postMessage.mockClear();
+
+    mockLocalization.locale = 'en';
+    view.rerender(<EditorLocaleBridge />);
+
+    expect(localeFrames()).toEqual([
+      expect.objectContaining({
+        data: expect.objectContaining({ locale: 'en' })
+      })
+    ]);
+  });
+
+  it('ignores a switch from an untrusted origin', () => {
+    render(<EditorLocaleBridge />);
+
+    editorSwitch('en', 'https://evil.example');
+
+    expect(mockLocalization.setLocale).not.toHaveBeenCalled();
+  });
+
+  it('ignores the current locale and one the storefront does not have', () => {
+    render(<EditorLocaleBridge />);
+
+    editorSwitch('tr');
+    editorSwitch('fr');
+
+    expect(mockLocalization.setLocale).not.toHaveBeenCalled();
+  });
+
+  it('keeps listening while any placeholder is left, and stops with the last', () => {
+    const body = render(<EditorLocaleBridge />);
+    const header = render(<EditorLocaleBridge />);
+
+    // A client-side navigation unmounts the page body; the layout's header
+    // slot stays, and has to keep answering the editor.
+    body.unmount();
+    editorSwitch('en');
+    expect(mockLocalization.setLocale).toHaveBeenCalledTimes(1);
+
+    header.unmount();
+    editorSwitch('en');
+    expect(mockLocalization.setLocale).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('outside the editor', () => {
+  beforeEach(unframeDocument);
+
+  it('posts nothing and follows nobody', () => {
+    const parentPost = jest.spyOn(window, 'postMessage');
+
+    render(
+      <>
+        {placeholder('header')}
+        {placeholder('footer')}
+      </>
+    );
+    editorSwitch('en');
+
+    expect(parentPost).not.toHaveBeenCalled();
+    expect(postMessage).not.toHaveBeenCalled();
+    expect(mockLocalization.setLocale).not.toHaveBeenCalled();
+
+    parentPost.mockRestore();
+  });
+
+  it('does not even listen', () => {
+    // Bare bridges, not wrappers: the wrapper keeps a message listener of its
+    // own, and this is about the bridge adding nothing to a live storefront.
+    const addListener = jest.spyOn(window, 'addEventListener');
+
+    render(
+      <>
+        <EditorLocaleBridge />
+        <EditorLocaleBridge />
+      </>
+    );
+
+    expect(
+      addListener.mock.calls.filter(([type]) => type === 'message')
+    ).toHaveLength(0);
+
+    addListener.mockRestore();
+  });
+});

package/src/editor-locale-bridge.tsx

@@ -0,0 +1,165 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useLocalization } from '@akinon/next/hooks';
+
+import { isTrustedEditorEvent, postToEditor } from './editor-bridge';
+
+/**
+ * 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 }`); 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
+ * stuck on English with nothing to switch.
+ *
+ * So the bridge lives here, next to the other editor plumbing, and every
+ * placeholder mounts it. A page carries several placeholders (header and
+ * footer slots, the page body, every theme modal), and they come and go
+ * independently on client-side navigation, so the page-wide parts are kept at
+ * module level instead of per mount:
+ *
+ * - ONE `message` listener, attached by the first mounted bridge and removed
+ *   with the last. A "first mount owns it" flag would go quiet as soon as that
+ *   mount left (the page body unmounts on every navigation, the layout's header
+ *   slot stays), so the listener is reference counted instead.
+ * - ONE announcement per state. Every mount reports the same localization
+ *   (they all read one provider), and an identical frame is only posted once,
+ *   however many placeholders mount at the same moment.
+ *
+ * Outside the editor it does nothing observable: nothing is attached or posted
+ * unless the storefront is framed, and `postToEditor` / `isTrustedEditorEvent`
+ * keep the traffic to trusted editor origins.
+ *
+ * Brands built from the app-template may still carry their own copy of this
+ * bridge. Their frames repeat ours, which the editor absorbs. Their listener
+ * also calls `setLocale` for the same switch, in the same event dispatch; on
+ * both the v1 and v2 cores `setLocale` assigns `location.href` from the
+ * unchanged current location, so the two calls target the same URL and the
+ * later assignment replaces the pending one before anything commits: one page
+ * load, one history entry. The template's own header already mounts its
+ * `LanguageSelect` twice (band and mobile menu), so this is how every template
+ * brand has always switched. Nothing needs to be deduplicated across the two.
+ */
+
+export interface EditorLocaleOption {
+  value: string;
+  label: string;
+}
+
+interface LocaleState {
+  locale: string;
+  locales: EditorLocaleOption[];
+  setLocale: (locale: string) => void;
+}
+
+let mountedBridges = 0;
+// The localization the page is showing, as last reported by any mounted bridge.
+// Every mount reads the same provider, so whichever wrote last is right.
+let current: LocaleState | null = null;
+// The state the editor already knows about, so it is never told twice.
+let lastAnnounced: string | null = null;
+
+const isFramed = () =>
+  typeof window !== 'undefined' && window.parent !== window;
+
+/**
+ * The editor's dropdown shape. Settings locales carry more (`apiValue`,
+ * `rtl`), and none of it is the editor's business. A locale without a label
+ * falls back to its code rather than showing up as an empty option.
+ */
+const toEditorLocales = (locales: unknown): EditorLocaleOption[] =>
+  (Array.isArray(locales) ? locales : [])
+    .filter(
+      (entry): entry is { value: string; label?: unknown } =>
+        !!entry && typeof entry.value === 'string' && entry.value !== ''
+    )
+    .map((entry) => ({
+      value: entry.value,
+      label:
+        typeof entry.label === 'string' && entry.label
+          ? entry.label
+          : entry.value
+    }));
+
+const announcementKey = (locale: string, locales: EditorLocaleOption[]) =>
+  JSON.stringify([locale, locales]);
+
+const announce = ({ locale, locales }: LocaleState) => {
+  const key = announcementKey(locale, locales);
+  if (key === lastAnnounced) return;
+  lastAnnounced = key;
+
+  postToEditor({ type: 'LOCALE_UPDATE', data: { locale, locales } });
+};
+
+const handleEditorMessage = (event: MessageEvent) => {
+  if (!isTrustedEditorEvent(event)) return;
+  if (event.data?.type !== 'LOCALE_UPDATE') return;
+
+  const requested = event.data?.data?.locale;
+  if (!current || typeof requested !== 'string' || !requested) return;
+  if (requested === current.locale) return;
+  // A stale editor list (it starts with a hard-coded English) must not send
+  // the storefront to a locale it does not have.
+  if (
+    current.locales.length > 0 &&
+    !current.locales.some((option) => option.value === requested)
+  ) {
+    return;
+  }
+
+  // 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(requested, current.locales);
+  current.setLocale(requested);
+};
+
+/**
+ * Headless: reports the storefront's languages to the editor and follows the
+ * editor's language switch. Rendered by every ThemePlaceholderWrapper; see the
+ * module comment for why several of them still add up to one bridge.
+ */
+export function EditorLocaleBridge(): null {
+  const { locale, locales, setLocale } = useLocalization();
+
+  useEffect(() => {
+    if (!isFramed()) return;
+
+    mountedBridges += 1;
+    if (mountedBridges === 1) {
+      window.addEventListener('message', handleEditorMessage);
+    }
+
+    return () => {
+      mountedBridges -= 1;
+      if (mountedBridges === 0) {
+        window.removeEventListener('message', handleEditorMessage);
+        current = null;
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!isFramed() || !locale) return;
+
+    current = { locale, locales: toEditorLocales(locales), setLocale };
+    announce(current);
+  }, [locale, locales, setLocale]);
+
+  return null;
+}
+
+/** Test-only: reset module state between cases. */
+export function __resetEditorLocaleBridgeForTests(): void {
+  if (typeof window !== 'undefined') {
+    window.removeEventListener('message', handleEditorMessage);
+  }
+  mountedBridges = 0;
+  current = null;
+  lastAnnounced = null;
+}

package/src/theme-placeholder-wrapper.tsx

@@ -30,6 +30,7 @@ import { isPublishWindowVisible } from './utils/publish-window';
 import { buildClientRequestUrl } from '@akinon/next/utils';
 import { PreviewToEditorMessageType } from '@akinon/theme-contract';
 import { parseEditorMessage, postToEditor } from './editor-bridge';
+import { EditorLocaleBridge } from './editor-locale-bridge';
 import { useBrowseMode } from './browse-mode';
 import { neutralizeStyleTagBreakout } from './utils/css-safety';
 import { buildCustomFontFaceCss } from './utils/custom-fonts';
@@ -983,6 +984,12 @@ export default function ThemePlaceholderWrapper({
         state when the designer comes back, so the panel and the canvas agree.
       */}
         <PartStatePreview isDesigner={isEditing} />
+        {/*
+        Tells the editor which languages this storefront has and follows its
+        language switch. Every placeholder renders one; they share a single
+        listener and a single announcement (see editor-locale-bridge.tsx).
+      */}
+        <EditorLocaleBridge />
         {themeBackgroundCSS && (
           <style dangerouslySetInnerHTML={{ __html: themeBackgroundCSS }} />
         )}