@akinon/pz-theme 2.0.157 → 2.0.158-rc.14

package/src/custom/property-types.ts

@@ -33,19 +33,20 @@ 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 three excluded members are excluded for reasons that were verified, not
- * guessed:
+ * 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.
  *
- * - `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.
+ * `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.
  *
  * Declaring one of these throws at define time rather than shipping a control
  * that silently shows the default forever.
@@ -59,12 +60,11 @@ 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,6 +1,7 @@
 'use client';
 
 import { getResponsiveValue } from '../utils';
+import { sanitizeRichText } from '../utils/sanitize-rich-text';
 import { devWarn } from '../utils/dev-warn';
 import {
   isLocalizedValue,
@@ -238,6 +239,11 @@ 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
@@ -254,7 +260,7 @@ export function useThemeSetting<
         `unreachable and the declared default is used instead. Render this ` +
         `component through a block registered with registerCustomBlocks().`
     );
-    return defaults.page as TValue;
+    return finish(defaults.page);
   }
 
   // Reported on every render rather than once from an effect: the collection
@@ -271,7 +277,17 @@ 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 stored = context.node.properties?.[key];
+  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;
 
   // The sentinel again, for the same reason: handing `getResponsiveValue` an
   // undefined fallback would resolve an undeclared default to `''`, so a
@@ -280,15 +296,15 @@ export function useThemeSetting<
   const resolved = getResponsiveValue(stored, breakpoint, NOT_AUTHORED);
 
   if (resolved === NOT_AUTHORED) {
-    return resolveAuthoredDefault(defaults.page, breakpoint) as TValue;
+    return finish(resolveAuthoredDefault(defaults.page, breakpoint));
   }
 
   // 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 defaults.page as TValue;
+    return finish(defaults.page);
   }
 
-  return resolved as TValue;
+  return finish(resolved);
 }

package/src/editor-locale-bridge.tsx

@@ -4,14 +4,28 @@ 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 }`); 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
+ * `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
  * 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
@@ -54,6 +68,7 @@ export interface EditorLocaleOption {
 interface LocaleState {
   locale: string;
   locales: EditorLocaleOption[];
+  defaultLocale?: string;
   setLocale: (locale: string) => void;
 }
 
@@ -86,15 +101,22 @@ const toEditorLocales = (locales: unknown): EditorLocaleOption[] =>
           : entry.value
     }));
 
-const announcementKey = (locale: string, locales: EditorLocaleOption[]) =>
-  JSON.stringify([locale, locales]);
+const announcementKey = ({
+  locale,
+  locales,
+  defaultLocale
+}: Omit<LocaleState, 'setLocale'>) =>
+  JSON.stringify([locale, locales, defaultLocale ?? null]);
 
-const announce = ({ locale, locales }: LocaleState) => {
-  const key = announcementKey(locale, locales);
+const announce = ({ locale, locales, defaultLocale }: LocaleState) => {
+  const key = announcementKey({ locale, locales, defaultLocale });
   if (key === lastAnnounced) return;
   lastAnnounced = key;
 
-  postToEditor({ type: 'LOCALE_UPDATE', data: { locale, locales } });
+  postToEditor({
+    type: 'LOCALE_UPDATE',
+    data: { locale, locales, defaultLocale }
+  });
 };
 
 const handleEditorMessage = (event: MessageEvent) => {
@@ -115,7 +137,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(requested, current.locales);
+  lastAnnounced = announcementKey({ ...current, locale: requested });
   current.setLocale(requested);
 };
 
@@ -126,6 +148,7 @@ const handleEditorMessage = (event: MessageEvent) => {
  */
 export function EditorLocaleBridge(): null {
   const { locale, locales, setLocale } = useLocalization();
+  const { defaultLocale } = useValueLocale();
 
   useEffect(() => {
     if (!isFramed()) return;
@@ -147,9 +170,14 @@ export function EditorLocaleBridge(): null {
   useEffect(() => {
     if (!isFramed() || !locale) return;
 
-    current = { locale, locales: toEditorLocales(locales), setLocale };
+    current = {
+      locale,
+      locales: toEditorLocales(locales),
+      defaultLocale,
+      setLocale
+    };
     announce(current);
-  }, [locale, locales, setLocale]);
+  }, [locale, locales, defaultLocale, setLocale]);
 
   return null;
 }

package/src/theme-placeholder-wrapper.tsx

@@ -1166,6 +1166,9 @@ export default function ThemePlaceholderWrapper({
           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).
+          A child of this wrapper on purpose: its effect, and so its frame,
+          runs before the effect below that posts IFRAME_READY, and the editor
+          counts on hearing the languages before the ready report.
         */}
           <EditorLocaleBridge />
           {themeBackgroundCSS && (

package/src/utils/__tests__/order-action-rules.test.tsx

@@ -0,0 +1,96 @@
+import React from 'react';
+import { act, render, screen } from '@testing-library/react';
+
+import {
+  __resetOrderActionRulesForTests,
+  allowsLineReturn,
+  allowsOrderCancel,
+  registerOrderActionRules,
+  useOrderActionRules
+} from '../order-action-rules';
+
+/**
+ * The brand's say over the order actions a storefront offers (ZERO-5302):
+ * asked only about what commerce already allows; with no rule, commerce's
+ * flags decide.
+ */
+
+const line = (status: string) => ({ id: 1, status: { value: status } });
+const order = { id: 7, number: 'O-7' };
+
+afterEach(() => __resetOrderActionRulesForTests());
+
+describe('order action rules', () => {
+  it('leaves the decision to commerce when no brand registered rules', () => {
+    expect(allowsLineReturn({}, line('500'), order)).toBe(true);
+    expect(allowsOrderCancel({}, order)).toBe(true);
+  });
+
+  it('lets a brand narrow returns and cancellations', () => {
+    const rules = {
+      returnLine: (item: { status?: { value?: string } | null }) =>
+        item.status?.value === '550',
+      cancelOrder: () => false
+    };
+
+    expect(allowsLineReturn(rules, line('550'), order)).toBe(true);
+    expect(allowsLineReturn(rules, line('500'), order)).toBe(false);
+    expect(allowsOrderCancel(rules, order)).toBe(false);
+  });
+
+  it('gives a rule that throws no say', () => {
+    const rules = {
+      returnLine: () => {
+        throw new Error('brand bug');
+      },
+      cancelOrder: () => {
+        throw new Error('brand bug');
+      }
+    };
+
+    expect(allowsLineReturn(rules, line('550'), order)).toBe(true);
+    expect(allowsOrderCancel(rules, order)).toBe(true);
+  });
+
+  it('renders a reader again when the rules are registered or dropped', () => {
+    const Reader = () => {
+      const rules = useOrderActionRules();
+      return (
+        <span data-testid="reader">
+          {allowsLineReturn(rules, line('500'), order) ? 'offers' : 'withholds'}
+        </span>
+      );
+    };
+    render(<Reader />);
+    expect(screen.getByTestId('reader')).toHaveTextContent('offers');
+
+    let unregister = () => {};
+    act(() => {
+      unregister = registerOrderActionRules({ returnLine: () => false });
+    });
+    expect(screen.getByTestId('reader')).toHaveTextContent('withholds');
+
+    act(() => unregister());
+    expect(screen.getByTestId('reader')).toHaveTextContent('offers');
+  });
+
+  it('keeps rules registered later when an older registration unregisters', () => {
+    const first = registerOrderActionRules({ returnLine: () => false });
+    const second = { returnLine: () => true };
+    registerOrderActionRules(second);
+
+    first();
+
+    expect(allowsLineReturn(second, line('500'), order)).toBe(true);
+    const Reader = () => {
+      const rules = useOrderActionRules();
+      return (
+        <span data-testid="current">
+          {rules === second ? 'second' : 'other'}
+        </span>
+      );
+    };
+    render(<Reader />);
+    expect(screen.getByTestId('current')).toHaveTextContent('second');
+  });
+});

package/src/utils/__tests__/sanitize-rich-text.test.ts

@@ -0,0 +1,80 @@
+import { sanitizeRichText } from '../sanitize-rich-text';
+
+describe('sanitizeRichText', () => {
+  it('keeps the markup the editor writes', () => {
+    const html =
+      '<p>Sipariş <b>verirseniz</b> <i>yarın</i> <u>kapınızda</u></p><ul><li>bir</li></ul><h2>Başlık</h2><br>';
+
+    expect(sanitizeRichText(html)).toBe(
+      '<p>Sipariş <b>verirseniz</b> <i>yarın</i> <u>kapınızda</u></p><ul><li>bir</li></ul><h2>Başlık</h2><br />'
+    );
+  });
+
+  it('drops scripts, event handlers and unknown tags but keeps their text', () => {
+    const html =
+      '<p onclick="x()">a<script>alert(1)</script><custom>b</custom><img src=x onerror=alert(1)></p>';
+
+    expect(sanitizeRichText(html)).toBe('<p>ab</p>');
+  });
+
+  it('keeps only safe links and forces rel on new-tab links', () => {
+    expect(
+      sanitizeRichText(
+        '<a href="javascript:alert(1)">x</a><a href="https://gant.com" target="_blank">y</a><a href="/sss">z</a>'
+      )
+    ).toBe(
+      '<a>x</a><a href="https://gant.com" target="_blank" rel="noopener noreferrer">y</a><a href="/sss">z</a>'
+    );
+  });
+
+  it('keeps only the colour and emphasis styles', () => {
+    expect(
+      sanitizeRichText(
+        '<span style="color: #9a2320; position: fixed; background: url(x)">a</span>'
+      )
+    ).toBe('<span style="color: #9a2320">a</span>');
+  });
+
+  it('leaves text, entities and placeholders untouched', () => {
+    expect(sanitizeRichText('{{countdown}} &amp; {{add_day|4}}')).toBe(
+      '{{countdown}} &amp; {{add_day|4}}'
+    );
+    expect(sanitizeRichText('')).toBe('');
+  });
+
+  it('reads tag names the way the browser does, so no element slips through as text', () => {
+    expect(
+      sanitizeRichText(
+        '<x_y onmouseover=alert(1) style=position:fixed;inset:0>a</x_y>'
+      )
+    ).toBe('a');
+    expect(sanitizeRichText('<svg/onload=alert(1)>b')).toBe('b');
+  });
+
+  it('never lets an unfinished tag run into the markup that follows', () => {
+    expect(sanitizeRichText('<img src=x onerror=alert(1)')).toBe(
+      '&lt;img src=x onerror=alert(1)'
+    );
+    expect(sanitizeRichText('<p>a</p><b')).toBe('<p>a</p>&lt;b');
+  });
+
+  it('escapes every < that does not become a kept tag', () => {
+    expect(sanitizeRichText('a < b <3 c')).toBe('a &lt; b &lt;3 c');
+    expect(sanitizeRichText('<!DOCTYPE html><?xml version="1.0"?>x')).toBe(
+      '&lt;!DOCTYPE html>&lt;?xml version="1.0"?>x'
+    );
+    expect(sanitizeRichText('</>')).toBe('&lt;/>');
+  });
+
+  it('reads a quoted attribute value holding > as part of the tag', () => {
+    expect(sanitizeRichText('<a href="/x" title="a>b">t</a>')).toBe(
+      '<a href="/x">t</a>'
+    );
+  });
+
+  it('drops an unterminated comment or script to the end', () => {
+    expect(sanitizeRichText('a<!-- b')).toBe('a');
+    expect(sanitizeRichText('<!-->x')).toBe('x');
+    expect(sanitizeRichText('a<script>alert(1)')).toBe('a');
+  });
+});

package/src/utils/order-action-rules.ts

@@ -0,0 +1,115 @@
+import { useSyncExternalStore } from 'react';
+
+/**
+ * Brand hook for the order actions a storefront offers (ZERO-5302).
+ *
+ * Commerce says what it allows: a line it will take back is flagged
+ * `is_refundable`, an order it will cancel `is_cancellable`. Whether the
+ * storefront offers that return or that cancellation is a brand decision on
+ * top — from which statuses, for how long after the order, whether the action
+ * is switched on at all — so the order blocks never learn it. A brand
+ * registers its rules from its own code (the pattern of the search-term
+ * transform), and the blocks ask them only about what commerce already
+ * allows. No registration, or a rule left out, and commerce's flags decide.
+ * A rule that throws has no say: a brand bug must not take the page down.
+ *
+ * Rules may be registered again when what they depend on arrives (a brand
+ * reading its settings from a widget, say); every block reading them through
+ * `useOrderActionRules` renders again.
+ */
+
+export interface OrderActionLine {
+  id?: number | string;
+  status?: { value?: string; label?: string } | null;
+  created_date?: string | null;
+  is_refundable?: boolean;
+  is_cancellable?: boolean;
+  [key: string]: unknown;
+}
+
+export interface OrderActionOrder {
+  id?: number | string;
+  number?: string;
+  created_date?: string | null;
+  status?: { value?: string; label?: string } | null;
+  [key: string]: unknown;
+}
+
+export interface OrderActionRules {
+  /**
+   * Whether a return may start from this line. Asked only about a line
+   * commerce flags refundable and that has no request open on it.
+   */
+  returnLine?: (line: OrderActionLine, order: OrderActionOrder) => boolean;
+  /**
+   * Whether the order may be cancelled from the storefront. Asked only about
+   * an order commerce flags cancellable.
+   */
+  cancelOrder?: (order: OrderActionOrder) => boolean;
+}
+
+const NO_RULES: OrderActionRules = {};
+
+let current: OrderActionRules = NO_RULES;
+const listeners = new Set<() => void>();
+
+const notify = () => listeners.forEach((listener) => listener());
+
+/** Register the brand's rules. Returns an unregister function. */
+export const registerOrderActionRules = (
+  rules: OrderActionRules
+): (() => void) => {
+  current = rules;
+  notify();
+  return () => {
+    if (current !== rules) return;
+    current = NO_RULES;
+    notify();
+  };
+};
+
+const subscribe = (listener: () => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+const getSnapshot = () => current;
+const getServerSnapshot = () => NO_RULES;
+
+/** The rules in force; the caller renders again when they are replaced. */
+export const useOrderActionRules = (): OrderActionRules =>
+  useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+/** Whether the brand lets a return start from a line commerce allows. */
+export const allowsLineReturn = (
+  rules: OrderActionRules,
+  line: OrderActionLine,
+  order: OrderActionOrder
+): boolean => {
+  if (!rules.returnLine) return true;
+  try {
+    return rules.returnLine(line, order) !== false;
+  } catch {
+    return true;
+  }
+};
+
+/** Whether the brand lets an order commerce allows be cancelled. */
+export const allowsOrderCancel = (
+  rules: OrderActionRules,
+  order: OrderActionOrder
+): boolean => {
+  if (!rules.cancelOrder) return true;
+  try {
+    return rules.cancelOrder(order) !== false;
+  } catch {
+    return true;
+  }
+};
+
+/** Test-only: drop the registered rules between cases. */
+export const __resetOrderActionRulesForTests = (): void => {
+  current = NO_RULES;
+};