@akinon/pz-theme 2.0.71-rc.0 → 2.0.72-beta.0

package/src/custom/block-host.tsx

@@ -0,0 +1,162 @@
+'use client';
+
+import React, { useEffect, useMemo } from 'react';
+import type { BlockRendererProps } from '../blocks/block-renderer-registry';
+import { DesignerPlaceholder } from '../blocks/product-block-utils';
+import { devWarn } from '../utils/dev-warn';
+import { CustomBlockContext } from './block-context';
+import type { CustomBlockContextValue } from './block-context';
+import { finishCollection, getCollectSink, isCollecting } from './collect';
+import type { CustomBlockDefinition } from './define';
+
+interface CustomBlockErrorBoundaryProps {
+  type: string;
+  label: string;
+  isDesigner: boolean;
+  children: React.ReactNode;
+}
+
+/**
+ * Per-BLOCK isolation, deliberately not the per-section one.
+ *
+ * `SectionErrorBoundary` already catches this throw, and its recovery is to
+ * render the whole section as null — a brand block with a typo would blank the
+ * header, the hero and everything else composed beside it. Catching one level
+ * lower keeps the blast radius at the block a developer actually wrote, and
+ * everything around it renders normally.
+ *
+ * Live renders nothing (an end user never sees a broken block). The designer
+ * gets a labelled box instead, because a block that silently disappears from
+ * the canvas reads as "the editor lost my block" rather than "this component
+ * threw" — and the merchant still needs something to select and delete.
+ */
+class CustomBlockErrorBoundary extends React.Component<
+  CustomBlockErrorBoundaryProps,
+  { hasError: boolean }
+> {
+  state = { hasError: false };
+
+  static getDerivedStateFromError(): { hasError: boolean } {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: unknown): void {
+    devWarn(
+      'customBlock',
+      `"${this.props.type}" threw while rendering and was skipped`,
+      error
+    );
+  }
+
+  render(): React.ReactNode {
+    if (!this.state.hasError) return this.props.children;
+
+    return this.props.isDesigner ? (
+      <DesignerPlaceholder
+        label={`${this.props.label} failed to render — see the browser console`}
+      />
+    ) : null;
+  }
+}
+
+/**
+ * Adapts a developer component to `BlockRendererProps`, which is the only
+ * shape `blockRendererRegistry` can hold.
+ *
+ * The host is what makes the authoring API ordinary React: it converts a
+ * renderer's positional props into the context the public helpers read, so a
+ * `<ThemeEditable>` nested arbitrarily deep resolves without the developer
+ * threading anything through their own tree.
+ *
+ * A COMPONENT THAT TAKES ITS IDENTITY AS PROPS, never a factory `register.ts`
+ * calls. This file carries `'use client'`, and it has to — `React.Component`
+ * and `createContext` are both `undefined` under the `react-server` condition,
+ * so the error boundary below would die at module evaluation in the RSC graph.
+ * That directive also makes every export here a client REFERENCE for anyone
+ * holding the server-side copy, and React makes such a reference THROW when it
+ * is called. Taking identity as props is what lets `bindHost` in `register.ts`
+ * only ever *reference* this component, inside `createElement`, which resolves
+ * from either graph — a factory would have to be called.
+ */
+export interface CustomBlockHostProps extends BlockRendererProps {
+  /** The `custom:<vendor>:<name>` this instance renders. */
+  type: string;
+  /** Picker label, reused by the error box below. */
+  label: string;
+  definition: CustomBlockDefinition;
+}
+
+export const CustomBlockHost = ({
+  type,
+  label,
+  definition,
+  block,
+  placeholderId,
+  sectionId,
+  isDesigner,
+  selectedBlockId,
+  currentBreakpoint = 'desktop'
+}: CustomBlockHostProps) => {
+  const BrandBlock = definition.component;
+
+  // Read during render, not in the effect: the sink has to be in the context
+  // BEFORE the developer component runs, because that is when
+  // `useThemeSetting`/`ThemeEditable` report themselves.
+  const collecting = isCollecting(type);
+
+  // Closing on commit rather than on the render call is what makes the
+  // StrictMode double render harmless — see `finishCollection`.
+  useEffect(() => {
+    finishCollection(type);
+  }, [type]);
+
+  // Read off the DEFINITION rather than the catalog descriptor: the descriptor's
+  // slot list grows as runtime collection discovers slots, and `ThemeSlot`
+  // resolves a bare `<ThemeSlot />` against this list. A list that grew mid
+  // render would resolve the bare slot onto whichever name happened to render
+  // first.
+  const declaredSlotNames = useMemo(
+    () => (definition.options.slots ?? []).map((slot) => slot.name ?? ''),
+    [definition]
+  );
+
+  const value = useMemo<CustomBlockContextValue>(
+    () => ({
+      block,
+      placeholderId,
+      sectionId,
+      isDesigner,
+      currentBreakpoint,
+      selectedBlockId,
+      declaredSlotNames,
+      collect: collecting ? getCollectSink(type) : undefined
+    }),
+    [
+      type,
+      block,
+      placeholderId,
+      sectionId,
+      isDesigner,
+      currentBreakpoint,
+      selectedBlockId,
+      declaredSlotNames,
+      collecting
+    ]
+  );
+
+  return (
+    <CustomBlockContext.Provider value={value}>
+      <CustomBlockErrorBoundary
+        type={type}
+        label={label}
+        isDesigner={isDesigner}
+      >
+        <BrandBlock />
+      </CustomBlockErrorBoundary>
+    </CustomBlockContext.Provider>
+  );
+};
+
+// Named for the React devtools tree: without this every custom block on the
+// page appears as the same anonymous arrow function.
+CustomBlockHost.displayName = 'CustomBlockHost';

package/src/custom/catalog.ts

@@ -0,0 +1,97 @@
+import { devWarn } from '../utils/dev-warn';
+import { CUSTOM_LIMITS } from './types';
+import type { CustomBlockDescriptor, CustomCatalog } from './types';
+
+/**
+ * The serializable half of every registered custom block, for the editor.
+ *
+ * Module state, one Map per bundle. That is the same shape `placeholderRegistry`
+ * uses and it inherits the same hazard: the client and server module graphs each
+ * get their own copy, and only the graph the brand barrel was imported into ever
+ * fills one. That is the CLIENT graph and only the client graph —
+ * `registerCustomBlocks` is client-only, so a brand imports its barrel from the
+ * client root and never from the server layout. Nothing is lost by that: the
+ * renderer registry `ThemeBlock` reads lives in the client graph too, and the
+ * announce in `placeholder-registry.ts` runs from the client.
+ *
+ * This file therefore stays free of a directive of its own:
+ * `placeholder-registry.ts` calls `getCustomCatalog` without one, and a
+ * `'use client'` here would turn that call into a client reference that throws
+ * on the server side.
+ */
+const catalog = new Map<string, CustomBlockDescriptor>();
+
+let vendor = '';
+
+export const setCatalogVendor = (next: string) => {
+  vendor = next;
+};
+
+export const getCatalogVendor = () => vendor;
+
+/**
+ * Adds a descriptor, refusing rather than overwriting.
+ *
+ * Last-wins would be silent: `blockRendererRegistry.register` is a bare
+ * `Map.set`, so two blocks claiming one type would leave the second rendering
+ * everywhere the first was placed, with no signal anywhere.
+ */
+export const addToCatalog = (descriptor: CustomBlockDescriptor) => {
+  if (catalog.has(descriptor.type)) {
+    throw new Error(
+      `[pz-theme] Custom block "${descriptor.type}" is defined twice in this build. ` +
+        `Type names must be unique — rename one of them.`
+    );
+  }
+
+  if (catalog.size >= CUSTOM_LIMITS.typesPerBuild) {
+    throw new Error(
+      `[pz-theme] This build declares more than ${CUSTOM_LIMITS.typesPerBuild} custom blocks. ` +
+        `The cap exists because the whole catalog is posted to the editor on every ` +
+        `placeholder announce; split the build or retire unused blocks.`
+    );
+  }
+
+  catalog.set(descriptor.type, descriptor);
+};
+
+export const getCustomBlockDescriptor = (
+  type: string
+): CustomBlockDescriptor | undefined => catalog.get(type);
+
+export const getCustomBlockTypes = (): string[] => Array.from(catalog.keys());
+
+/**
+ * The payload the storefront announces. Returns null when nothing is
+ * registered, so the announcer can omit the field entirely rather than posting
+ * an empty catalog every time a placeholder mounts.
+ */
+export const getCustomCatalog = (): CustomCatalog | null => {
+  if (catalog.size === 0) return null;
+
+  const payload: CustomCatalog = {
+    vendor,
+    blocks: Array.from(catalog.values())
+  };
+
+  // Measured here rather than trusted: a descriptor grows with every setting,
+  // slot and option list, and the editor drops the WHOLE frame's catalog when
+  // it arrives over-cap. Failing loudly at the source names the build that did
+  // it; failing at the receiver names nothing.
+  const bytes = JSON.stringify(payload).length;
+  if (bytes > CUSTOM_LIMITS.catalogBytes) {
+    devWarn(
+      'customCatalog',
+      `Catalog is ${bytes} bytes, over the ${CUSTOM_LIMITS.catalogBytes} byte cap. ` +
+        `The editor will reject it; reduce option lists or the number of blocks.`
+    );
+  }
+
+  return payload;
+};
+
+/** Test-only. Module state outlives a test file otherwise. */
+export const resetCustomCatalog = () => {
+  catalog.clear();
+  vendor = '';
+};

package/src/custom/collect.ts

@@ -0,0 +1,342 @@
+import { devWarn } from '../utils/dev-warn';
+import { getCustomBlockDescriptor } from './catalog';
+import { fieldPartName } from './editable-tags';
+import { slotNameError } from './slot-nodes';
+import {
+  SUPPORTED_PROPERTY_TYPES,
+  isSupportedPropertyType
+} from './property-types';
+import {
+  CUSTOM_LIMITS,
+  RESERVED_SETTING_KEYS,
+  SETTING_KEY_PATTERN,
+  materializeDefault
+} from './types';
+import type { CustomSettingDescriptor, CustomSlotDescriptor } from './types';
+
+/**
+ * Runtime collection — the fallback that makes the authoring API work before
+ * the build-time extractor exists, and the cross-check that catches a stale
+ * generated descriptor after it does.
+ *
+ * A developer who declares nothing still gets a usable block: the first render
+ * of each type reports the `useThemeSetting` keys and the `ThemeSlot` it
+ * actually used, and those land in the catalog the editor receives. What
+ * runtime collection can never do is describe a block the merchant has not
+ * placed yet — nothing renders, so nothing is collected. That is the whole
+ * reason `defineCustomBlock` takes declarations too.
+ *
+ * The validators live in THIS file rather than beside the throwing versions in
+ * `register.ts` because both paths must apply the identical gate, and this is
+ * the only one of the four files with no inbound edge from the others
+ * (`register` -> `block-host` -> `collect`). Putting them in `register.ts`
+ * would close that chain into a cycle.
+ */
+
+/**
+ * The short form a developer actually writes: `options: ['light','dark']`.
+ *
+ * The object member's `label` is optional because `CustomSettingDeclaration`
+ * (define.tsx) accepts a label-less option too, and both doors normalize
+ * through the one function below.
+ */
+export type ThemeSettingChoice =
+  | string
+  | number
+  | { label?: string; value: unknown };
+
+/**
+ * Normalizes the shorthand into the `{label, value}` pairs the editor's select
+ * control expects.
+ *
+ * THE ONE COPY OF THIS RULE. `registerCustomBlocks` takes the same option list
+ * from `defineCustomBlock` and calls this rather than carrying its own; a
+ * second copy drifted immediately — the declared path filled a missing `label`
+ * from the value while the hook path left it unset, so `[{ value: 'light' }]`
+ * drew a captionless control through one door and a captioned one through the
+ * other.
+ *
+ * It lives HERE and not beside `useThemeSetting`, which is where it reads more
+ * naturally, for the boundary reason `buildSetting` in `register.ts` records
+ * beside its `options` field: `use-theme-setting.ts` carries `'use client'` and
+ * this file deliberately carries no directive. Keeping the shared normalizer in
+ * the directive-free tier of this folder — the tier `catalog.ts` sits in, the
+ * one `placeholder-registry.ts` reaches without a directive of its own — leaves
+ * it callable from either module graph. Moving it into the hook's module would
+ * drag a client boundary along with it, for nothing.
+ */
+export const normalizeSettingChoices = (
+  choices: ReadonlyArray<ThemeSettingChoice> | undefined
+): Array<{ label: string; value: unknown }> | undefined => {
+  if (!choices) return undefined;
+
+  return choices.map((choice) =>
+    typeof choice === 'object' && choice !== null
+      ? { label: String(choice.label ?? choice.value), value: choice.value }
+      : { label: String(choice), value: choice }
+  );
+};
+
+/**
+ * Why a control type is refused, named per type. "Unsupported" tells a
+ * developer nothing actionable; each of these three fails for its own reason
+ * and each has a different way out.
+ */
+const UNSUPPORTED_TYPE_REASON: Record<string, string> = {
+  multiselect:
+    'the editor stores a multiselect value as a bare array, and getResponsiveValue rejects arrays ' +
+    '(dev-warns and returns the fallback), so the block would read its authored default forever. ' +
+    'Use "select" and store one value until a per-type resolver exists',
+  localetext:
+    'the editor stores a localetext value as a locale map with no "desktop" key, so getResponsiveValue ' +
+    'falls back and the block would read its authored default forever. Use "text" and localize in the component',
+  richtext:
+    'there is no safe renderer for it here — the sanitizer this repo owns parses by assigning to innerHTML ' +
+    'on a live element, and pz-theme renders on the server where there is no document at all. Use "text"'
+};
+
+/** The reason a setting key is refused, or null. Shared by the declared and the collected path. */
+export const settingKeyError = (key: unknown): string | null => {
+  if (typeof key !== 'string' || !SETTING_KEY_PATTERN.test(key)) {
+    return (
+      `key ${JSON.stringify(
+        key
+      )} is not a valid setting key. Use a camelCase name starting with a ` +
+      `lowercase letter (max 32 characters) — the key becomes both an object key in block.properties ` +
+      `and the "${fieldPartName(
+        '<key>'
+      )}" part name, so both grammars have to accept it`
+    );
+  }
+
+  if (RESERVED_SETTING_KEYS.includes(key)) {
+    return (
+      `key "${key}" is reserved. The editor's property panel already treats it specially, so the field ` +
+      `would inherit behaviour it never asked for (a bespoke editor, a url() wrapper, or removal from ` +
+      `the Content tab). Rename it`
+    );
+  }
+
+  return null;
+};
+
+/** The reason a control type is refused, or null. */
+export const settingTypeError = (type: unknown): string | null => {
+  if (isSupportedPropertyType(type)) return null;
+
+  const named = typeof type === 'string' ? type : String(type);
+  const reason = UNSUPPORTED_TYPE_REASON[named];
+
+  if (reason)
+    return `control type "${named}" cannot deliver a value: ${reason}`;
+
+  return (
+    `control type "${named}" is not one of the editor's control types. ` +
+    `Supported: ${SUPPORTED_PROPERTY_TYPES.join(', ')}`
+  );
+};
+
+export interface CustomCollectSink {
+  setting: (descriptor: CustomSettingDescriptor) => void;
+  slot: (descriptor: CustomSlotDescriptor) => void;
+}
+
+const sinks = new Map<string, CustomCollectSink>();
+const finished = new Set<string>();
+
+export const isCollecting = (type: string): boolean => !finished.has(type);
+
+/**
+ * Closed after the first COMMITTED render of a type, never on the first render
+ * call: React may render a component twice before committing (StrictMode, a
+ * discarded concurrent attempt), and closing on the first call would drop
+ * everything the surviving render reported.
+ */
+export const finishCollection = (type: string): void => {
+  finished.add(type);
+};
+
+const disagreement = (
+  declared: CustomSettingDescriptor,
+  collected: CustomSettingDescriptor
+): string | null => {
+  if (declared.type !== collected.type) {
+    return `type "${declared.type}" vs "${collected.type}"`;
+  }
+
+  const collectedDefault = materializeDefault(collected.defaultValue);
+  if (
+    JSON.stringify(declared.defaultValue) !== JSON.stringify(collectedDefault)
+  ) {
+    return `default ${JSON.stringify(
+      declared.defaultValue
+    )} vs ${JSON.stringify(collectedDefault)}`;
+  }
+
+  return null;
+};
+
+/**
+ * One stable sink per type.
+ *
+ * Stable identity matters because the sink sits inside the context value the
+ * host memoizes: a fresh object per render would invalidate that memo on every
+ * render of every custom block on the page.
+ */
+export const getCollectSink = (type: string): CustomCollectSink => {
+  const existing = sinks.get(type);
+  if (existing) return existing;
+
+  const targetDescriptor = () => {
+    const descriptor = getCustomBlockDescriptor(type);
+    if (!descriptor) {
+      devWarn(
+        'customBlock',
+        `"${type}" rendered with no catalog descriptor, so nothing it uses can be collected. ` +
+          `The block registered into a different module copy than the one rendering it: check that the ` +
+          `barrel calling registerCustomBlocks() is imported from the CLIENT ROOT, and clear .next — ` +
+          `webpack keeps serving the old copy of a changed package.`
+      );
+    }
+    return descriptor;
+  };
+
+  const sink: CustomCollectSink = {
+    setting: (collected) => {
+      if (finished.has(type)) return;
+
+      const descriptor = targetDescriptor();
+      if (!descriptor) return;
+
+      const keyError = settingKeyError(collected.key);
+      const typeError = keyError ? null : settingTypeError(collected.type);
+      if (keyError || typeError) {
+        devWarn(
+          'customBlock',
+          `"${type}" used a setting the editor cannot offer: ${
+            keyError ?? typeError
+          }`
+        );
+        return;
+      }
+
+      const declared = descriptor.settings.find(
+        (setting) => setting.key === collected.key
+      );
+
+      if (declared) {
+        // The declaration always wins: it is what the editor already has and
+        // what the build-time extractor will regenerate. A mismatch means the
+        // declaration no longer describes the component — the stale-descriptor
+        // signal this cross-check exists to raise.
+        const conflict = disagreement(declared, collected);
+        if (conflict) {
+          devWarn(
+            'customBlock',
+            `"${type}" setting "${collected.key}" disagrees with its declaration (${conflict}). ` +
+              `The declaration wins; update defineCustomBlock() so the picker matches the component.`
+          );
+        }
+        return;
+      }
+
+      if (descriptor.settings.length >= CUSTOM_LIMITS.settingsPerType) {
+        devWarn(
+          'customBlock',
+          `"${type}" uses more than ${CUSTOM_LIMITS.settingsPerType} settings; "${collected.key}" was ` +
+            `dropped. Split the block — the whole catalog is posted to the editor on every placeholder announce.`
+        );
+        return;
+      }
+
+      descriptor.settings.push({
+        ...collected,
+        label: collected.label || collected.key,
+        defaultValue: materializeDefault(collected.defaultValue)
+      });
+
+      // The part name comes from the render path's own helper rather than a
+      // second copy of the same interpolation: `ThemeEditable` stamps the
+      // element with `partAttrs(fieldPartName(name))`, and a part the catalog
+      // advertises but the DOM never carries is a control the editor offers
+      // and nothing answers.
+      const part = fieldPartName(collected.key);
+
+      if (!collected.editable || descriptor.parts.includes(part)) return;
+
+      // The one place a descriptor can grow past the parts cap AFTER
+      // registration checked it. `register.ts` counts the declared parts and
+      // the declared fields together, but an undeclared `ThemeEditable`
+      // discovered at render time adds one more — and the cap is the editor's,
+      // which drops the WHOLE catalog above it. Losing this field's part group
+      // costs one control; letting it through would cost the brand every block
+      // in the palette.
+      if (descriptor.parts.length >= CUSTOM_LIMITS.partsPerType) {
+        devWarn(
+          'customBlock',
+          `"${type}" advertises more than ${CUSTOM_LIMITS.partsPerType} parts; the "${part}" part was ` +
+            `dropped, so "${collected.key}" has a control in the Content tab but no styling group. ` +
+            `Declare fewer parts in defineCustomBlock() — the editor refuses a catalog over the cap outright.`
+        );
+        return;
+      }
+
+      descriptor.parts.push(part);
+    },
+
+    slot: (collected) => {
+      if (finished.has(type)) return;
+
+      const descriptor = targetDescriptor();
+      if (!descriptor) return;
+
+      const name = collected.name ?? '';
+
+      const nameError = slotNameError(name);
+      if (nameError) {
+        devWarn(
+          'customBlock',
+          `"${type}" rendered a slot the editor cannot offer: ${nameError}`
+        );
+        return;
+      }
+
+      // Idempotent by name, and it has to be: this runs on every render until
+      // the first commit, so a repeat under one name is a re-render, never a
+      // second slot. Counting instead would cry wolf on the StrictMode double
+      // render — and it would be counting the wrong thing anyway, because a
+      // genuine duplicate never reaches this sink: `theme-slot.tsx` claims each
+      // NAME once per context value and the losers return without reporting.
+      // register.ts refuses the declared form of the same mistake, where the
+      // count is unambiguous.
+      if (descriptor.slots.some((slot) => slot.name === name)) {
+        descriptor.hasChildren = true;
+        return;
+      }
+
+      if (descriptor.slots.length >= CUSTOM_LIMITS.slotsPerType) {
+        devWarn(
+          'customBlock',
+          `"${type}" opens more than ${CUSTOM_LIMITS.slotsPerType} slots; "${name}" was dropped. ` +
+            `Split the block — the whole catalog is posted to the editor on every placeholder announce.`
+        );
+        return;
+      }
+
+      descriptor.slots.push({
+        name,
+        ...(collected.label !== undefined ? { label: collected.label } : {})
+      });
+      descriptor.hasChildren = true;
+    }
+  };
+
+  sinks.set(type, sink);
+  return sink;
+};
+
+/** Test-only. Module state outlives a test file otherwise. */
+export const resetCustomCollection = (): void => {
+  sinks.clear();
+  finished.clear();
+};