@akinon/pz-theme 2.0.157-rc.13 → 2.0.158-beta.0

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/theme-placeholder-wrapper.tsx

@@ -1166,9 +1166,6 @@ 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/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;
+};

package/src/__tests__/row-scope.test.tsx

@@ -1,118 +0,0 @@
-import React from 'react';
-import { render, screen } from '@testing-library/react';
-import { ItemTemplateList } from '../blocks/item-template';
-import { useThemeProduct } from '../blocks/product-block-utils';
-import { useThemeRowScope } from '../blocks/row-scope';
-import blockRendererRegistry from '../blocks/block-renderer-registry';
-import { resetCustomCatalog } from '../custom/catalog';
-import { resetCustomCollection } from '../custom/collect';
-import { isCustomThemeType, registerCustomBlocks } from '../custom';
-import type { Block } from '../theme-block';
-
-const READER = 'custom:acme:row-reader';
-
-function RowReader() {
-  const scope = useThemeRowScope();
-  const product = useThemeProduct();
-
-  return (
-    <span
-      data-testid="reader"
-      data-list={scope?.listType ?? ''}
-      data-index={scope?.index ?? ''}
-      data-number={String(scope?.row.number ?? '')}
-      data-product={String(product?.pk ?? '')}
-    />
-  );
-}
-
-const template = (): Block =>
-  ({
-    id: 'tpl',
-    type: 'group',
-    label: 'Row',
-    order: 0,
-    hidden: false,
-    value: '',
-    properties: { role: { desktop: 'item-template' } },
-    styles: {},
-    blocks: [
-      {
-        id: 'tpl-reader',
-        type: READER,
-        label: 'Reader',
-        order: 0,
-        hidden: false,
-        value: '',
-        properties: {},
-        styles: {},
-        blocks: []
-      }
-    ]
-  } as Block);
-
-const list = (type: string): Block =>
-  ({
-    id: 'list',
-    type,
-    label: 'List',
-    order: 0,
-    hidden: false,
-    value: '',
-    properties: {},
-    styles: {},
-    blocks: [template()]
-  } as Block);
-
-const renderRows = (type: string, items: Record<string, unknown>[]) =>
-  render(
-    <ItemTemplateList
-      block={list(type)}
-      items={items}
-      placeholderId="p1"
-      sectionId="s1"
-    />
-  );
-
-beforeAll(() => {
-  registerCustomBlocks('acme', { 'row-reader': RowReader });
-});
-
-afterAll(() => {
-  const map = (
-    blockRendererRegistry as unknown as { renderers: Map<string, unknown> }
-  ).renderers;
-  Array.from(map.keys())
-    .filter(isCustomThemeType)
-    .forEach((key) => map.delete(key));
-  resetCustomCatalog();
-  resetCustomCollection();
-});
-
-describe('the row scope', () => {
-  it('hands every repeated row to the blocks inside it, on any list', () => {
-    renderRows('order-list', [{ number: 'ORD-1' }, { number: 'ORD-2' }]);
-
-    const readers = screen.getAllByTestId('reader');
-    expect(readers).toHaveLength(2);
-    expect(readers[0]).toHaveAttribute('data-list', 'order-list');
-    expect(readers[0]).toHaveAttribute('data-index', '0');
-    expect(readers[0]).toHaveAttribute('data-number', 'ORD-1');
-    expect(readers[1]).toHaveAttribute('data-number', 'ORD-2');
-    expect(readers[0]).toHaveAttribute('data-product', '');
-  });
-
-  it('keeps the product scope on product lists next to the row scope', () => {
-    renderRows('product-grid', [{ pk: 7, name: 'Sneaker' }]);
-
-    const reader = screen.getByTestId('reader');
-    expect(reader).toHaveAttribute('data-list', 'product-grid');
-    expect(reader).toHaveAttribute('data-product', '7');
-  });
-
-  it('is closed outside a repeated row', () => {
-    render(<RowReader />);
-
-    expect(screen.getByTestId('reader')).toHaveAttribute('data-list', '');
-  });
-});

package/src/blocks/__tests__/order-line-actions.test.tsx

@@ -1,54 +0,0 @@
-import React from 'react';
-import {
-  registerOrderLineActions,
-  renderOrderLineActions
-} from '../order-line-actions';
-
-const context = {
-  order: { id: 7, number: '20920397829', created_date: '2026-10-01' },
-  line: {
-    key: '1',
-    name: 'Product',
-    image: '',
-    href: '',
-    price: '100',
-    total: 100,
-    quantity: 1,
-    item: { id: 1, status: { value: '550', label: 'Delivered' } }
-  },
-  isDesigner: false
-};
-
-describe('order line actions registry', () => {
-  it('renders nothing until a brand registers', () => {
-    expect(renderOrderLineActions(context)).toBeNull();
-  });
-
-  it('hands the line and order to the registered renderer', () => {
-    const renderer = jest.fn(() => <span>action</span>);
-    const unregister = registerOrderLineActions(renderer);
-
-    expect(renderOrderLineActions(context)).toEqual(<span>action</span>);
-    expect(renderer).toHaveBeenCalledWith(context);
-
-    unregister();
-    expect(renderOrderLineActions(context)).toBeNull();
-  });
-
-  it('swallows a throwing renderer so a brand bug cannot break the line', () => {
-    const unregister = registerOrderLineActions(() => {
-      throw new Error('boom');
-    });
-
-    expect(renderOrderLineActions(context)).toBeNull();
-    unregister();
-  });
-
-  it('only forgets the renderer it was asked to forget', () => {
-    const first = registerOrderLineActions(() => 'first');
-    registerOrderLineActions(() => 'second');
-
-    first();
-    expect(renderOrderLineActions(context)).toBe('second');
-  });
-});