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

package/CHANGELOG.md

@@ -1,40 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.114-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.114-rc.0
-  - @akinon/theme-contract@2.0.114-rc.0
+## 2.0.114
+
+### Patch Changes
+
+- cfde270: Read a block value the commerce api returns wrapped, so a per-locale image renders on the storefront
+  - @akinon/next@2.0.114
+  - @akinon/theme-contract@2.0.114
 
 ## 2.0.113
 

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

package/src/__tests__/wrapped-attribute-values.test.ts

@@ -0,0 +1,153 @@
+/**
+ * A BLOCK VALUE ARRIVES WRAPPED, AND THE WRAPPER HID THE JSON.
+ *
+ * The commerce API answers a widget read with every attribute as
+ * `{ value, kwargs }` -- never a bare string. The loader's `getBlockValue`
+ * parsed only the bare-string form, so in production the branch that ran
+ * handed `.value` over verbatim and a block whose value is a JSON document
+ * received the SERIALISED text.
+ *
+ * That is what made a per-locale image (ZERO-5085) render "No image uploaded"
+ * in every language: the editor writes `{"tr":"…","en":"…"}` as one attribute
+ * string, the renderer saw a 120-character "URL" starting with `{`, could not
+ * normalise it, and drew the placeholder. Text blocks never showed it because
+ * `text-block.tsx` parses the string itself.
+ *
+ * The guard these tests pin down is as load-bearing as the parse: only an
+ * object or array literal is parsed. A numeric text value like "2026" has
+ * always reached blocks as a string, and the text block returns '' for a
+ * number -- so parsing every string would have deleted that copy instead.
+ */
+jest.mock('server-only', () => ({}), { virtual: true });
+
+const getWidgetData = jest.fn();
+const getWidgetSchemaData = jest.fn();
+const getCollectionWidgetData = jest.fn();
+const getPreviewSnapshot = jest.fn(async () => null as unknown);
+
+jest.mock('@akinon/next/data/server', () => ({
+  getWidgetData: (...args: unknown[]) => getWidgetData(...args),
+  getWidgetSchemaData: (...args: unknown[]) => getWidgetSchemaData(...args),
+  getCollectionWidgetData: (...args: unknown[]) =>
+    getCollectionWidgetData(...args),
+  getPreviewSnapshot: (...args: unknown[]) =>
+    (getPreviewSnapshot as (...a: unknown[]) => unknown)(...args)
+}));
+
+jest.mock(
+  '@akinon/next/utils/app-fetch',
+  () => ({ __esModule: true, default: jest.fn() }),
+  { virtual: true }
+);
+
+jest.mock(
+  '@akinon/next/utils/server-variables',
+  () => ({ ServerVariables: { locale: 'tr', currency: 'try' } }),
+  { virtual: true }
+);
+
+import { loadPlaceholderSections } from '../load-placeholder-sections';
+
+const SLOT = 'theme-homepage-body';
+const SECTION = 'section-pt5vg';
+const BLOCK = 'block-yby44';
+
+/** The two images the editor uploaded, one per language. */
+const TR_IMAGE =
+  'https://cdn.example.com/cms/2026/09/21/f1e4bc11-aeb8-4252-96c9-093ffd72208e.jpg';
+const EN_IMAGE =
+  'https://cdn.example.com/cms/2026/09/21/b1fd2ad9-1461-4ac9-8016-270d369ef97b.jpg';
+
+/** Exactly how the commerce API returns an attribute: wrapped, never bare. */
+const wrapped = (value: unknown) => ({ value, kwargs: {} });
+
+const loadBlockValue = async (attribute: unknown) => {
+  getWidgetData.mockImplementation(async ({ slug }: { slug: string }) => {
+    if (slug === SLOT) {
+      return {
+        slug: SLOT,
+        attributes: {
+          theme_editor_placeholder: wrapped(
+            JSON.stringify([{ section_slug: SECTION, order: 0 }])
+          )
+        }
+      };
+    }
+    if (slug === SECTION) {
+      return { slug: SECTION, attributes: { [BLOCK]: attribute } };
+    }
+    return null;
+  });
+
+  getWidgetSchemaData.mockResolvedValue({
+    schema: {
+      [SECTION]: {
+        metadata: {
+          name: 'Hero',
+          blocks: [{ id: BLOCK, type: 'image', label: 'Background Image' }]
+        }
+      }
+    }
+  });
+
+  const loaded = await loadPlaceholderSections(SLOT);
+  return loaded?.sections[0]?.blocks[0]?.value;
+};
+
+beforeEach(() => {
+  getWidgetData.mockReset();
+  getWidgetSchemaData.mockReset().mockResolvedValue(null);
+  getCollectionWidgetData.mockReset().mockResolvedValue(null);
+  getPreviewSnapshot.mockReset().mockResolvedValue(null);
+});
+
+describe('a wrapped block attribute', () => {
+  it('parses a per-locale image map back into an object', async () => {
+    const value = await loadBlockValue(
+      wrapped(JSON.stringify({ tr: TR_IMAGE, en: EN_IMAGE }))
+    );
+
+    expect(value).toEqual({ tr: TR_IMAGE, en: EN_IMAGE });
+  });
+
+  it('parses an array value', async () => {
+    const value = await loadBlockValue(
+      wrapped(JSON.stringify([{ url: TR_IMAGE }]))
+    );
+
+    expect(value).toEqual([{ url: TR_IMAGE }]);
+  });
+
+  it('leaves a plain url alone', async () => {
+    expect(await loadBlockValue(wrapped(TR_IMAGE))).toBe(TR_IMAGE);
+  });
+
+  it('leaves a numeric value as the string every block has received', async () => {
+    expect(await loadBlockValue(wrapped('2026'))).toBe('2026');
+  });
+
+  it('leaves copy that merely mentions a brace alone', async () => {
+    expect(await loadBlockValue(wrapped('Use {code} at checkout'))).toBe(
+      'Use {code} at checkout'
+    );
+  });
+
+  it('keeps the raw string when a json-looking value is malformed', async () => {
+    expect(await loadBlockValue(wrapped('{"tr":'))).toBe('{"tr":');
+  });
+
+  it('still reads a bare-string attribute', async () => {
+    // The shape fixtures and older answers use; it must keep working.
+    const value = await loadBlockValue(
+      JSON.stringify({ tr: TR_IMAGE, en: EN_IMAGE })
+    );
+
+    expect(value).toEqual({ tr: TR_IMAGE, en: EN_IMAGE });
+  });
+
+  it('reads a value the api already sent as an object', async () => {
+    const value = await loadBlockValue(wrapped({ tr: TR_IMAGE }));
+
+    expect(value).toEqual({ tr: TR_IMAGE });
+  });
+});

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

@@ -230,3 +230,62 @@ describe('ImageBlock - per-locale sources', () => {
     });
   });
 });
+
+/**
+ * THE SERIALISED FORM IS WHAT A STOREFRONT ACTUALLY HOLDS.
+ *
+ * A per-locale value is stored as one JSON string in a widget attribute. The
+ * loader parses it now, but not every reader can (the text block has always
+ * parsed it inline), so the resolver accepts either form. Without this, an
+ * unparsed map reached `pickImageSource` as a 120-character "URL" and the
+ * block drew "No image uploaded" in every language.
+ */
+describe('a locale map that arrived as a json string', () => {
+  const ctx = { locale: 'en', defaultLocale: 'tr', locales: ['tr', 'en'] };
+
+  it('resolves per locale', () => {
+    const serialized = JSON.stringify({ tr: TR, en: EN });
+
+    expect(resolveLocalizedValue(serialized, ctx)).toBe(EN);
+    expect(resolveLocalizedValue(serialized, { ...ctx, locale: 'tr' })).toBe(
+      TR
+    );
+  });
+
+  it('parses a non-localized object too, so the usual unwrap still runs', () => {
+    expect(resolveLocalizedValue(JSON.stringify({ url: TR }), ctx)).toEqual({
+      url: TR
+    });
+  });
+
+  it('leaves a plain string as the same reference', () => {
+    const copy = 'Use {code} at checkout';
+
+    expect(resolveLocalizedValue(TR, ctx)).toBe(TR);
+    expect(resolveLocalizedValue(copy, ctx)).toBe(copy);
+    expect(resolveLocalizedValue('{"tr":', ctx)).toBe('{"tr":');
+  });
+
+  it('renders the language being shown', () => {
+    const value = JSON.stringify({ tr: TR, en: EN });
+
+    setLocalization('en');
+    expect(srcOf({ value })).toBe(EN);
+
+    setLocalization('tr');
+    expect(srcOf({ value })).toBe(TR);
+  });
+
+  it('renders a serialized phone override', () => {
+    setLocalization('en');
+    expect(
+      srcOf(
+        {
+          value: TR,
+          properties: { imageMobile: JSON.stringify({ tr: TR, en: EN }) }
+        },
+        { isDesigner: true, currentBreakpoint: 'mobile' }
+      )
+    ).toBe(EN);
+  });
+});

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

@@ -80,14 +80,31 @@ describe('ImageBlock - pickImageSource', () => {
     );
   });
 
-  it('SURPRISE: a plain { foo: url } object never reaches the first-string scan', () => {
-    // getResponsiveValue returns its '' string fallback (no desktop/breakpoint
-    // key), pickImageSource returns '' before scanning values -> placeholder.
+  it('scans a plain { foo: url } object for a usable source', () => {
+    // No breakpoint key answers, so getResponsiveValue returns the sentinel
+    // rather than a '' string, and the scan below it runs. This is what keeps
+    // an unrecognised map shape — a per-locale value whose codes the
+    // storefront does not know, say — showing its picture instead of the
+    // placeholder.
     const { container } = renderBlock({
       id: 'b5',
       value: { foo: 'https://example.com/first.jpg' }
     });
 
+    expect(getImg(container)?.getAttribute('src')).toBe(
+      'https://example.com/first.jpg'
+    );
+  });
+
+  it('keeps a breakpoint that was authored empty empty', () => {
+    // The opposite case, and the reason the fallback is a sentinel and not
+    // simply "any empty result": the desktop value exists and is blank, so it
+    // must NOT inherit the phone image through the scan.
+    const { container } = renderBlock({
+      id: 'b6',
+      value: { desktop: '', mobile: 'https://example.com/mobile.jpg' }
+    });
+
     expect(getImg(container)).toBeNull();
     expect(screen.getByText('No image uploaded')).toBeInTheDocument();
   });

package/src/blocks/image-block.tsx

@@ -20,6 +20,9 @@ import {
 } from '../utils/localized-value';
 import { BlockRendererProps } from './block-renderer-registry';
 
+/** "No breakpoint answered", which '' cannot express (see `pickImageSource`). */
+const NO_RESPONSIVE_VALUE = Symbol('no-responsive-value');
+
 const pickImageSource = (value: unknown, currentBreakpoint: string): string => {
   if (typeof value === 'string') {
     return value.trim();
@@ -32,7 +35,24 @@ const pickImageSource = (value: unknown, currentBreakpoint: string): string => {
       return objectValue.url.trim();
     }
 
-    const responsiveValue = getResponsiveValue(value, currentBreakpoint, '');
+    /*
+     * The fallback is a SENTINEL, not '', so "nothing was authored for any
+     * breakpoint" stays distinguishable from "this breakpoint was authored
+     * empty".
+     *
+     * With '' as the fallback, an object that is not a breakpoint map at all
+     * resolved to '' — a string — and returned it, which made the
+     * first-string-value pass below dead code. Any map shape this renderer did
+     * not recognise therefore drew "No image uploaded" rather than the picture
+     * it was holding. An explicitly emptied breakpoint still returns its own
+     * '' through the branch above, so a cleared desktop image does NOT silently
+     * inherit the phone one.
+     */
+    const responsiveValue = getResponsiveValue(
+      value,
+      currentBreakpoint,
+      NO_RESPONSIVE_VALUE
+    );
     if (typeof responsiveValue === 'string') {
       return responsiveValue.trim();
     }

package/src/load-placeholder-sections.ts

@@ -34,7 +34,7 @@ type ServerDataFn = (<T>(args: never) => Promise<T | null>) | undefined;
 const optionalServerFn = (name: string): ServerDataFn =>
   (serverData as unknown as Record<string, ServerDataFn>)[name];
 
-const directFetch = async <T,>(url: string): Promise<T | null> => {
+const directFetch = async <T>(url: string): Promise<T | null> => {
   try {
     const result = await appFetch<T>({
       url,
@@ -47,7 +47,7 @@ const directFetch = async <T,>(url: string): Promise<T | null> => {
   }
 };
 
-const getCollectionWidgetData = async <T,>(args: {
+const getCollectionWidgetData = async <T>(args: {
   slug: string;
 }): Promise<T | null> => {
   const fn = optionalServerFn('getCollectionWidgetData');
@@ -56,7 +56,7 @@ const getCollectionWidgetData = async <T,>(args: {
   return directFetch<T>(`/product_collection_widgets/${args.slug}/`);
 };
 
-const getWidgetSchemaData = async <T,>(args: {
+const getWidgetSchemaData = async <T>(args: {
   widgetSlug: string;
 }): Promise<T | null> => {
   const fn = optionalServerFn('getWidgetSchemaData');
@@ -264,7 +264,13 @@ export async function loadPlaceholderSections(
     // asking the same question to decide whether it is pinned, reads it once.
     const { dataSources, settings: themeSettings } = await getThemeConfig();
 
-    let data: { slug?: string; attributes?: { theme_editor_placeholder?: unknown; [key: string]: unknown } } | null = null;
+    let data: {
+      slug?: string;
+      attributes?: {
+        theme_editor_placeholder?: unknown;
+        [key: string]: unknown;
+      };
+    } | null = null;
     try {
       // Shared with ChromeSlot's composed/uncomposed decision — see
       // getPlaceholderWidget for why the two must read one fetch.
@@ -363,7 +369,44 @@ export async function loadPlaceholderSections(
                 return attrData;
               }
             } else if (typeof attrData === 'object' && 'value' in attrData) {
-              return attrData.value;
+              /*
+               * THE WRAPPED FORM IS THE ONE PRODUCTION TAKES, SO IT HAS TO
+               * PARSE TOO.
+               *
+               * The commerce API returns every widget attribute as
+               * `{ value, kwargs }`, so the bare-string branch above only ever
+               * runs against a hand-built fixture — every real storefront read
+               * lands here. Returning `.value` verbatim handed the block the
+               * SERIALISED value, which is why a per-locale image
+               * (`{"tr":"…","en":"…"}`, ZERO-5085) rendered "No image
+               * uploaded" in every language: the renderer saw one long string
+               * where a map was expected. A text block never showed it because
+               * text-block.tsx parses the string itself.
+               *
+               * Only an object or array literal is parsed, NOT every string the
+               * branch above would parse: a numeric text value like "2026" must
+               * stay the string every block has always received, or a plain
+               * JSON.parse would turn it into a number and the text block —
+               * which returns '' for a non-string, non-object value — would
+               * drop it.
+               */
+              const wrapped = attrData.value;
+              if (typeof wrapped !== 'string') return wrapped;
+
+              const trimmed = wrapped.trim();
+              if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
+                return wrapped;
+              }
+
+              try {
+                return JSON.parse(trimmed);
+              } catch {
+                devWarn(
+                  'ThemePlaceholder',
+                  `Block "${blockId}" value looks like JSON but failed to parse; using the raw string`
+                );
+                return wrapped;
+              }
             }
             return attrData;
           };

package/src/utils/localized-value.ts

@@ -37,6 +37,37 @@ export const isLocalizedValue = (
   locales.length > 0 &&
   Object.keys(value).some((key) => locales.includes(key));
 
+/**
+ * The value as an object when it arrived SERIALISED.
+ *
+ * A per-locale value is stored as one JSON string in a widget attribute, and
+ * not every reader hands it over parsed — the text block has always parsed it
+ * itself (`text-block.tsx`), and a caller that reads an attribute directly
+ * cannot. Parsing here means every consumer of a localized value behaves the
+ * same whichever form reaches it.
+ *
+ * Only an object literal is parsed, and only the parse result is used: a URL
+ * never starts with `{`, so a plain value is returned as the same reference and
+ * renders byte for byte as it did.
+ */
+const parseSerializedValue = (value: unknown): unknown => {
+  if (typeof value !== 'string') return value;
+
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('{')) return value;
+
+  try {
+    const parsed = JSON.parse(trimmed);
+    return typeof parsed === 'object' &&
+      parsed !== null &&
+      !Array.isArray(parsed)
+      ? parsed
+      : value;
+  } catch {
+    return value;
+  }
+};
+
 /**
  * Picks the entry for the language being shown, before any other unwrap.
  *
@@ -46,14 +77,17 @@ export const isLocalizedValue = (
  * 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.
+ * The value itself may arrive as the JSON string it is stored as; see
+ * `parseSerializedValue`. 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,
+  rawValue: unknown,
   { locale, defaultLocale, locales }: ValueLocale
 ): unknown => {
+  const value = parseSerializedValue(rawValue);
+
   if (!isLocalizedValue(value, locales)) return value;
 
   if (locale && hasEntry(value[locale])) return value[locale];