@akinon/pz-theme 2.0.111-rc.0 → 2.0.111

package/CHANGELOG.md

@@ -1,40 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.111-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.111-rc.0
-  - @akinon/theme-contract@2.0.111-rc.0
+## 2.0.111
+
+### Patch Changes
+
+- 6f73835: ZERO-5085: Let theme editor images differ per locale
+  - @akinon/next@2.0.111
+  - @akinon/theme-contract@2.0.111
 
 ## 2.0.110
 

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

package/src/blocks/__tests__/image-block-locale.test.tsx

@@ -0,0 +1,232 @@
+import React from 'react';
+import { renderToString } from 'react-dom/server';
+import { render } from '@testing-library/react';
+
+// Per-test localization: the shared mapper mock is fixed to `en-us`, and these
+// cases need to switch the language the page is showing.
+let localizationValue: Record<string, unknown> = {};
+jest.mock('@akinon/next/hooks', () => ({
+  __esModule: true,
+  useLocalization: () => localizationValue
+}));
+
+import ImageBlock from '../image-block';
+import {
+  isLocalizedValue,
+  resolveLocalizedValue
+} from '../../utils/localized-value';
+import type { BlockRendererProps } from '../block-renderer-registry';
+
+const TR = 'https://example.com/tr.jpg';
+const EN = 'https://example.com/en.jpg';
+
+const setLocalization = (
+  locale: string,
+  locales: string[] = ['tr', 'en'],
+  defaultLocaleValue = 'tr'
+) => {
+  localizationValue = {
+    locale,
+    locales: locales.map((value) => ({ value, label: value.toUpperCase() })),
+    defaultLocaleValue
+  };
+};
+
+const element = (
+  block: Record<string, unknown>,
+  extra: Partial<BlockRendererProps> = {}
+) => (
+  <ImageBlock
+    {...({
+      block: { id: 'img', type: 'image', ...block }
+    } as unknown as BlockRendererProps)}
+    {...extra}
+  />
+);
+
+const srcOf = (
+  block: Record<string, unknown>,
+  extra: Partial<BlockRendererProps> = {}
+) =>
+  render(element(block, extra))
+    .container.querySelector('img')
+    ?.getAttribute('src') ?? null;
+
+const markupOf = (
+  block: Record<string, unknown>,
+  extra: Partial<BlockRendererProps> = {}
+) => render(element(block, extra)).container.innerHTML;
+
+beforeEach(() => setLocalization('tr'));
+
+describe('isLocalizedValue', () => {
+  const locales = ['tr', 'en'];
+
+  it('is true only when a key is one of the known locales', () => {
+    expect(isLocalizedValue({ tr: TR, en: EN }, locales)).toBe(true);
+    expect(isLocalizedValue({ en: EN }, locales)).toBe(true);
+  });
+
+  it('never reads the existing image shapes as localized', () => {
+    expect(isLocalizedValue(TR, locales)).toBe(false);
+    expect(isLocalizedValue({ url: TR }, locales)).toBe(false);
+    expect(
+      isLocalizedValue({ desktop: TR, mobile: EN, tablet: EN }, locales)
+    ).toBe(false);
+    expect(isLocalizedValue([TR, EN], locales)).toBe(false);
+    expect(isLocalizedValue(null, locales)).toBe(false);
+  });
+
+  it('does not guess from key shape: locale-looking keys need to be known', () => {
+    expect(isLocalizedValue({ tr: TR, en: EN }, ['tr-tr', 'en-us'])).toBe(
+      false
+    );
+    expect(isLocalizedValue({ tr: TR, en: EN }, [])).toBe(false);
+  });
+});
+
+describe('resolveLocalizedValue', () => {
+  const ctx = {
+    locale: 'en',
+    defaultLocale: 'tr',
+    locales: ['tr', 'en', 'de']
+  };
+
+  it('picks the current locale, then the default, then the first entry', () => {
+    expect(resolveLocalizedValue({ tr: TR, en: EN }, ctx)).toBe(EN);
+    expect(resolveLocalizedValue({ tr: TR }, ctx)).toBe(TR);
+    expect(resolveLocalizedValue({ de: 'de.jpg' }, ctx)).toBe('de.jpg');
+    expect(resolveLocalizedValue({ tr: TR, en: '' }, ctx)).toBe(TR);
+  });
+
+  it('returns a non-localized value as the same reference', () => {
+    const breakpoints = { desktop: TR, mobile: EN };
+    const picker = { url: TR };
+
+    expect(resolveLocalizedValue(TR, ctx)).toBe(TR);
+    expect(resolveLocalizedValue(breakpoints, ctx)).toBe(breakpoints);
+    expect(resolveLocalizedValue(picker, ctx)).toBe(picker);
+  });
+});
+
+describe('ImageBlock - per-locale sources', () => {
+  it('renders the image of the language being shown', () => {
+    setLocalization('en');
+    expect(srcOf({ value: { tr: TR, en: EN } })).toBe(EN);
+
+    setLocalization('tr');
+    expect(srcOf({ value: { tr: TR, en: EN } })).toBe(TR);
+  });
+
+  it('falls back to the default locale, then to the first entry', () => {
+    setLocalization('en', ['tr', 'en', 'de'], 'tr');
+    expect(srcOf({ value: { de: 'https://example.com/de.jpg', tr: TR } })).toBe(
+      TR
+    );
+
+    setLocalization('en', ['tr', 'en', 'de'], 'tr');
+    expect(srcOf({ value: { de: 'https://example.com/de.jpg' } })).toBe(
+      'https://example.com/de.jpg'
+    );
+  });
+
+  it('unwraps { url } and breakpoint maps inside a locale entry', () => {
+    setLocalization('en');
+    expect(srcOf({ value: { tr: { url: TR }, en: { url: EN } } })).toBe(EN);
+
+    const value = {
+      tr: { desktop: TR, mobile: 'https://example.com/tr-m.jpg' },
+      en: { desktop: EN, mobile: 'https://example.com/en-m.jpg' }
+    };
+    expect(srcOf({ value })).toBe(EN);
+    expect(srcOf({ value }, { currentBreakpoint: 'mobile' })).toBe(
+      'https://example.com/en-m.jpg'
+    );
+  });
+
+  it('localizes the phone override on the storefront <picture>', () => {
+    setLocalization('en');
+    const { container } = render(
+      element({
+        value: { tr: TR, en: EN },
+        properties: {
+          imageMobile: {
+            tr: 'https://example.com/tr-phone.jpg',
+            en: 'https://example.com/en-phone.jpg'
+          }
+        }
+      })
+    );
+
+    expect(container.querySelector('img')?.getAttribute('src')).toBe(EN);
+    expect(container.querySelector('source')?.getAttribute('srcset')).toBe(
+      'https://example.com/en-phone.jpg'
+    );
+  });
+
+  it('localizes the phone override on the canvas', () => {
+    setLocalization('tr');
+    expect(
+      srcOf(
+        {
+          value: { tr: TR, en: EN },
+          properties: {
+            imageMobile: {
+              tr: 'https://example.com/tr-phone.jpg',
+              en: 'https://example.com/en-phone.jpg'
+            }
+          }
+        },
+        { isDesigner: true, currentBreakpoint: 'mobile' }
+      )
+    ).toBe('https://example.com/tr-phone.jpg');
+  });
+
+  it('resolves the locale in the server render', () => {
+    setLocalization('en');
+    const html = renderToString(element({ value: { tr: TR, en: EN } }));
+
+    expect(html).toContain(`src="${EN}"`);
+    expect(html).not.toContain(TR);
+  });
+
+  describe('non-localized values render exactly as before', () => {
+    // An empty locale list is the pre-feature renderer: nothing can be
+    // localized, so every value goes straight to the old unwrap.
+    const before = (
+      block: Record<string, unknown>,
+      extra: Partial<BlockRendererProps> = {}
+    ) => {
+      setLocalization('tr', []);
+      const html = markupOf(block, extra);
+      setLocalization('tr');
+      return html;
+    };
+
+    const cases: Array<[string, Record<string, unknown>]> = [
+      ['a URL string', { value: TR }],
+      ['a { url } value', { value: { url: TR } }],
+      [
+        'a breakpoint map',
+        { value: { desktop: TR, mobile: 'https://example.com/m.jpg' } }
+      ],
+      [
+        'a phone override',
+        { value: TR, properties: { imageMobile: 'https://example.com/m.jpg' } }
+      ],
+      // Locale-looking keys that are not the storefront's locales stay on
+      // the old path (which takes the first string it finds).
+      ['unknown locale-looking keys', { value: { de: TR, fr: EN } }]
+    ];
+
+    it.each(cases)('%s', (_label, block) => {
+      for (const extra of [
+        {},
+        { currentBreakpoint: 'mobile' },
+        { isDesigner: true, currentBreakpoint: 'mobile' }
+      ] as Array<Partial<BlockRendererProps>>) {
+        expect(markupOf(block, extra)).toBe(before(block, extra));
+      }
+    });
+  });
+});

package/src/blocks/image-block.tsx

@@ -13,6 +13,11 @@ import {
   PHONE_ONLY_MEDIA_CONDITION,
   TABLET_ONLY_MEDIA_CONDITION
 } from '../utils/breakpoints';
+import {
+  type ValueLocale,
+  resolveLocalizedValue,
+  useValueLocale
+} from '../utils/localized-value';
 import { BlockRendererProps } from './block-renderer-registry';
 
 const pickImageSource = (value: unknown, currentBreakpoint: string): string => {
@@ -82,8 +87,15 @@ const isValidImageSource = (src: string): boolean => {
  * save path flattens an `image` block's `value` to a single string anyway, so a
  * per-breakpoint map could never survive a round trip there.
  */
-const resolveOverride = (value: unknown, currentBreakpoint: string): string => {
-  const raw = pickImageSource(value, currentBreakpoint);
+const resolveOverride = (
+  value: unknown,
+  currentBreakpoint: string,
+  valueLocale: ValueLocale
+): string => {
+  const raw = pickImageSource(
+    resolveLocalizedValue(value, valueLocale),
+    currentBreakpoint
+  );
   const url = normalizeImageSource(raw);
   return isValidImageSource(url) ? url : '';
 };
@@ -137,8 +149,20 @@ const ImageBlock = ({
   isDesigner = false,
   currentBreakpoint = 'desktop'
 }: BlockRendererProps) => {
+  /*
+   * Every source (the main value and both overrides) may be a per-locale map.
+   * The language is picked first and the result goes through the unwrap below
+   * unchanged, so a locale entry can itself be a URL, `{ url }` or a
+   * breakpoint map, and a value that is not localized is read as it always
+   * was.
+   */
+  const valueLocale = useValueLocale();
+
   const imageValue = useMemo(() => {
-    const rawUrl = pickImageSource(block.value, currentBreakpoint);
+    const rawUrl = pickImageSource(
+      resolveLocalizedValue(block.value, valueLocale),
+      currentBreakpoint
+    );
     const url = normalizeImageSource(rawUrl);
     const alt = String(block.properties?.alt || '');
 
@@ -146,17 +170,19 @@ const ImageBlock = ({
       url: isValidImageSource(url) ? url : '',
       alt
     };
-  }, [block.value, block.properties?.alt, currentBreakpoint]);
+  }, [block.value, block.properties?.alt, currentBreakpoint, valueLocale]);
 
   const { url: desktopSrc, alt } = imageValue;
 
   const imageTablet = resolveOverride(
     block.properties?.imageTablet,
-    currentBreakpoint
+    currentBreakpoint,
+    valueLocale
   );
   const imageMobile = resolveOverride(
     block.properties?.imageMobile,
-    currentBreakpoint
+    currentBreakpoint,
+    valueLocale
   );
 
   const pictureSources = useMemo(

package/src/sections/countdown-campaign-banner-section.tsx

@@ -12,6 +12,10 @@ import {
   getResponsiveValue,
   resolveThemeCssVariables
 } from '../utils';
+import {
+  resolveLocalizedValue,
+  useValueLocale
+} from '../utils/localized-value';
 import { Section } from '../theme-section';
 
 import { postToEditor } from '../editor-bridge';
@@ -179,6 +183,7 @@ const CountdownCampaignBannerSection: React.FC<
   selectedBlockId = null
 }) => {
   const themeSettings = useThemeSettingsContext();
+  const valueLocale = useValueLocale();
 
   const sortedBlocks = [...(section.blocks || [])]
     .sort((a, b) => (a.order || 0) - (b.order || 0))
@@ -272,10 +277,13 @@ const CountdownCampaignBannerSection: React.FC<
   );
   const backgroundImageSrc = useMemo(() => {
     if (!backgroundBlock) return '';
-    const raw = pickImageSource(backgroundBlock.value, currentBreakpoint);
+    const raw = pickImageSource(
+      resolveLocalizedValue(backgroundBlock.value, valueLocale),
+      currentBreakpoint
+    );
     const normalized = normalizeImageSource(raw);
     return hasValidImageSource(normalized) ? normalized : '';
-  }, [backgroundBlock, currentBreakpoint]);
+  }, [backgroundBlock, currentBreakpoint, valueLocale]);
 
   const overlayColor = resolveThemeCssVariables(
     String(

package/src/sections/coupon-banner-section.tsx

@@ -14,6 +14,10 @@ import {
   resolveThemeCssVariables
 } from '../utils';
 import { isNarrowBreakpoint } from '../utils/breakpoints';
+import {
+  resolveLocalizedValue,
+  useValueLocale
+} from '../utils/localized-value';
 import { Section } from '../theme-section';
 
 import { postToEditor } from '../editor-bridge';
@@ -198,6 +202,7 @@ const CouponBannerSection: React.FC<CouponBannerSectionProps> = ({
   selectedBlockId = null
 }) => {
   const themeSettings = useThemeSettingsContext();
+  const valueLocale = useValueLocale();
 
   const sortedBlocks = [...(section.blocks || [])]
     .sort((a, b) => (a.order || 0) - (b.order || 0))
@@ -349,10 +354,13 @@ const CouponBannerSection: React.FC<CouponBannerSectionProps> = ({
 
   const backgroundImageSrc = useMemo(() => {
     if (!backgroundBlock) return '';
-    const raw = pickImageSource(backgroundBlock.value, currentBreakpoint);
+    const raw = pickImageSource(
+      resolveLocalizedValue(backgroundBlock.value, valueLocale),
+      currentBreakpoint
+    );
     const normalized = normalizeImageSource(raw);
     return hasValidImageSource(normalized) ? normalized : '';
-  }, [backgroundBlock, currentBreakpoint]);
+  }, [backgroundBlock, currentBreakpoint, valueLocale]);
   const hasBackgroundImage = Boolean(backgroundBlock && backgroundImageSrc);
 
   const overlayColor = resolveThemeCssVariables(

package/src/utils/localized-value.ts

@@ -0,0 +1,94 @@
+import { useMemo } from 'react';
+import { useLocalization } from '@akinon/next/hooks';
+
+/**
+ * The language a value is read in, plus the storefront's own locale codes.
+ *
+ * `locales` is the list a key has to appear in for a value to count as
+ * per-locale at all (see `isLocalizedValue`), so it comes from the storefront's
+ * settings rather than from anything the value itself looks like.
+ */
+export interface ValueLocale {
+  locale?: string;
+  defaultLocale?: string;
+  locales: readonly string[];
+}
+
+const hasEntry = (entry: unknown): boolean =>
+  entry !== undefined && entry !== null && entry !== '';
+
+/**
+ * Whether `value` is a per-locale map such as `{ tr: '…', en: '…' }`.
+ *
+ * Only a key that is one of the storefront's locale codes makes it one. The
+ * key's shape is never enough: a breakpoint map (`{ desktop, mobile }`) and the
+ * picker's `{ url }` are objects too, and guessing from "looks like a language
+ * code" would read either of them as a locale map and blank a published image.
+ * With no locales known (no localization provider above the block) nothing is
+ * localized, so the value renders exactly as it did before locales existed.
+ */
+export const isLocalizedValue = (
+  value: unknown,
+  locales: readonly string[]
+): value is Record<string, unknown> =>
+  typeof value === 'object' &&
+  value !== null &&
+  !Array.isArray(value) &&
+  locales.length > 0 &&
+  Object.keys(value).some((key) => locales.includes(key));
+
+/**
+ * Picks the entry for the language being shown, before any other unwrap.
+ *
+ * Current locale, then the default locale, then the first entry — so a
+ * language the merchant has not given its own image shows the default one
+ * instead of nothing. The entry is returned as authored (a URL string, a
+ * breakpoint map or `{ url }`), because the caller's existing unwrap already
+ * knows every one of those shapes.
+ *
+ * A value that is not localized is returned as the same reference, which is
+ * what keeps every block published before this existed rendering byte for
+ * byte as it did.
+ */
+export const resolveLocalizedValue = (
+  value: unknown,
+  { locale, defaultLocale, locales }: ValueLocale
+): unknown => {
+  if (!isLocalizedValue(value, locales)) return value;
+
+  if (locale && hasEntry(value[locale])) return value[locale];
+  if (defaultLocale && hasEntry(value[defaultLocale])) {
+    return value[defaultLocale];
+  }
+
+  return Object.values(value).find(hasEntry);
+};
+
+/**
+ * The storefront's `ValueLocale`, read from the same provider the text block
+ * reads, so it resolves identically in the server render and after hydration.
+ *
+ * Only `locale`, `locales` and `defaultLocaleValue` are read: all three exist
+ * on the v1 core's `useLocalization` as well.
+ */
+export const useValueLocale = (): ValueLocale => {
+  const { locale, locales, defaultLocaleValue } = useLocalization();
+
+  const codes = useMemo(
+    () =>
+      (Array.isArray(locales) ? locales : [])
+        .map((entry) => (entry as { value?: unknown } | null)?.value)
+        .filter(
+          (value): value is string => typeof value === 'string' && value !== ''
+        ),
+    [locales]
+  );
+
+  const defaultLocale =
+    defaultLocaleValue || process.env.NEXT_PUBLIC_DEFAULT_LOCALE;
+
+  return useMemo(
+    () => ({ locale, defaultLocale, locales: codes }),
+    [locale, defaultLocale, codes]
+  );
+};