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

package/CHANGELOG.md

@@ -1,12 +1,15 @@
 # @akinon/pz-theme
 
-## 2.0.71-beta.0
+## 2.0.71
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd757]
-  - @akinon/next@2.0.71-beta.0
-  - @akinon/theme-contract@2.0.71-beta.0
+- 4f3f143: ZERO-4852: Add the custom block authoring API (defineCustomBlock, registerCustomBlocks, ThemeEditable, ThemeSlot, useThemeSetting)
+- c84da01: ZERO-4852: Refuse a custom block's slot accepts/max at declare time, and keep runtime part collection under the catalog cap
+- 3e1306b: ZERO-4852: Announce the custom block catalog to the theme editor on the placeholder frame
+- c84da01: ZERO-4852: Let a custom block open several named slots and declare its own styling parts with states
+  - @akinon/next@2.0.71
+  - @akinon/theme-contract@2.0.71
 
 ## 2.0.70
 

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.71-beta.0",
+  "version": "2.0.71",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.71-beta.0",
+    "@akinon/next": "2.0.71",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.71-beta.0",
+    "@akinon/theme-contract": "2.0.71",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.71-beta.0",
+    "@akinon/next": "2.0.71",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/custom-catalog-announce.test.ts

@@ -0,0 +1,276 @@
+/**
+ * What the storefront announces to the editor, and what it refuses to.
+ *
+ * `getCustomCatalog()` had no caller: a brand could register a custom block
+ * and the editor could never learn the type existed. The announce is the only
+ * channel, and it is shared with the placeholder slugs — which is what makes
+ * the gating interesting. Three answers have to hold at once:
+ *
+ *   - no placeholders, no frame (the editor's subscriber reloads the theme
+ *     against whatever slugs a frame carries, so an empty one is destructive)
+ *   - no proven designer, no catalog (a storefront is framed in production by
+ *     payment providers, and the catalog is brand IP)
+ *   - every frame carries the catalog whole, so the receiver can replace
+ */
+
+const EDITOR_ORIGIN = 'http://editor.example';
+
+type Registry = typeof import('../placeholder-registry');
+type Register = typeof import('../custom/register');
+
+interface Loaded {
+  registry: Registry;
+  register: Register;
+}
+
+let loadedModules: Loaded[] = [];
+
+/**
+ * A fresh copy of both modules, sharing one isolated graph.
+ *
+ * The registry, the catalog and the renderer registry are all module state,
+ * and `registerCustomBlocks` refuses to register a type twice — so a second
+ * test reusing the first one's modules would throw rather than start clean.
+ * Every copy is remembered so teardown can undo its window listener.
+ */
+const load = (): Loaded => {
+  let loaded: Loaded;
+  jest.isolateModules(() => {
+    loaded = {
+      registry: require('../placeholder-registry'),
+      register: require('../custom/register')
+    };
+  });
+  loadedModules.push(loaded!);
+  return loaded!;
+};
+
+const Promo = () => null;
+
+describe('PLACEHOLDERS_AVAILABLE announce', () => {
+  const postMessage = jest.fn();
+
+  const frames = () =>
+    postMessage.mock.calls.map(([message]) => message.data ?? {});
+
+  beforeAll(() => {
+    // Framed: `postToEditor` drops everything when window.self === window.top.
+    Object.defineProperty(window, 'top', {
+      configurable: true,
+      value: { name: 'designer' }
+    });
+    Object.defineProperty(window, 'parent', {
+      configurable: true,
+      value: { postMessage }
+    });
+    Object.defineProperty(document, 'referrer', {
+      configurable: true,
+      value: `${EDITOR_ORIGIN}/builder`
+    });
+  });
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+    postMessage.mockClear();
+    process.env.NEXT_PUBLIC_THEME_EDITOR_ORIGINS = EDITOR_ORIGIN;
+  });
+
+  afterEach(() => {
+    // Every copy attached its designer listener to the ONE jsdom window, and
+    // each copy still holds its own placeholder set — so without this the next
+    // test announces for all of its predecessors too.
+    loadedModules.forEach(({ registry }) =>
+      registry.__resetPlaceholderRegistryForTests()
+    );
+    loadedModules = [];
+    jest.useRealTimers();
+    delete process.env.NEXT_PUBLIC_THEME_EDITOR_ORIGINS;
+    delete (window as { __themeEditorDesigner?: boolean })
+      .__themeEditorDesigner;
+  });
+
+  it('posts nothing when a build registers blocks but mounts no placeholder', () => {
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+    const { register } = load();
+
+    register.registerCustomBlocks('acme', { 'promo-strip': Promo });
+    jest.advanceTimersByTime(500);
+
+    // The re-arm alone must never produce a frame: the editor's subscriber
+    // clears its cache and swaps the active placeholder set the moment one
+    // arrives, and this one would carry no slugs at all.
+    expect(postMessage).not.toHaveBeenCalled();
+  });
+
+  it('carries placeholders and the catalog in one frame', () => {
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+    const { registry, register } = load();
+
+    registry.registerPlaceholder('header');
+    // Re-arms the placeholder debounce rather than starting a second timer.
+    register.registerCustomBlocks('acme', {
+      'promo-strip': Promo
+    });
+    jest.advanceTimersByTime(100);
+
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    const [payload] = frames();
+    expect(payload.placeholders).toEqual(['header']);
+    expect(payload.customBlocks.vendor).toBe('acme');
+    expect(payload.customBlocks.blocks.map((block) => block.type)).toEqual([
+      'custom:acme:promo-strip'
+    ]);
+  });
+
+  it('omits the catalog key when the build registers no custom block', () => {
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+    const { registry } = load();
+
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+
+    const [payload] = frames();
+    expect(payload.placeholders).toEqual(['header']);
+    // Absent, not empty — a build with no custom blocks has to be
+    // indistinguishable from one whose catalog is not this frame's business.
+    expect('customBlocks' in payload).toBe(false);
+  });
+
+  it('withholds the catalog from a frame that has not proven it is the editor', () => {
+    const { registry, register } = load();
+
+    register.registerCustomBlocks('acme', { 'promo-strip': Promo });
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+
+    // Being framed is not the designer flag. Payment providers frame live
+    // storefronts; the slugs are route names and still go out, but every block
+    // name, setting key and option list this build ships does not.
+    const [payload] = frames();
+    expect(payload.placeholders).toEqual(['header']);
+    expect('customBlocks' in payload).toBe(false);
+  });
+
+  it('re-announces the catalog once the editor proves itself', () => {
+    const { registry, register } = load();
+
+    register.registerCustomBlocks('acme', { 'promo-strip': Promo });
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+    expect('customBlocks' in frames()[0]).toBe(false);
+
+    // The designer flag arrives in the editor's reply to IFRAME_READY — a
+    // postMessage round trip that is not guaranteed to land inside the 100ms
+    // debounce. Without the re-announce the catalog would be lost for the life
+    // of the document on exactly the loads where the handshake was slow.
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        origin: EDITOR_ORIGIN,
+        source: window.parent as Window,
+        data: { type: 'SET_THEME_EDITOR_COOKIE', data: true }
+      })
+    );
+    jest.advanceTimersByTime(100);
+
+    expect(postMessage).toHaveBeenCalledTimes(2);
+    // The vendor and the type the barrel actually produced, not merely one
+    // block: this second frame is the whole of what the editor ever learns
+    // about this build, and "the block is in the picker" is the only claim a
+    // human checks.
+    expect(frames()[1].customBlocks.vendor).toBe('acme');
+    expect(frames()[1].customBlocks.blocks.map((block) => block.type)).toEqual([
+      'custom:acme:promo-strip'
+    ]);
+  });
+
+  it('settles the announce/cookie handshake instead of ping-ponging', () => {
+    const { registry, register } = load();
+
+    register.registerCustomBlocks('acme', { 'promo-strip': Promo });
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+
+    // The editor answers EVERY announce with this cookie, not just the first
+    // (theme-iframe-service.ts sends it from the same handler that ingests the
+    // catalog). An unlatched re-arm would therefore loop for the life of the
+    // document, and every lap costs the editor a full theme reload —
+    // loadThemeForPlaceholders clears the widget cache and refetches every
+    // widget on each announce it receives.
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+
+    for (let lap = 0; lap < 5; lap += 1) {
+      window.dispatchEvent(
+        new MessageEvent('message', {
+          origin: EDITOR_ORIGIN,
+          source: window.parent as Window,
+          data: { type: 'SET_THEME_EDITOR_COOKIE', data: true }
+        })
+      );
+      jest.advanceTimersByTime(100);
+    }
+
+    // One frame to say which placeholders mounted, one to hand over the
+    // catalog the first could not carry, and then quiet.
+    expect(postMessage).toHaveBeenCalledTimes(2);
+    expect(frames()[1].customBlocks.blocks).toHaveLength(1);
+  });
+
+  it('does not spend a second frame when the build has no custom block', () => {
+    const { registry } = load();
+
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        origin: EDITOR_ORIGIN,
+        source: window.parent as Window,
+        data: { type: 'SET_THEME_EDITOR_COOKIE', data: true }
+      })
+    );
+    jest.advanceTimersByTime(100);
+
+    // Every brand shipping today registers no custom block. The re-announce
+    // exists to deliver a catalog; with none to deliver it must cost them
+    // nothing at all, or this feature would add a theme reload to every
+    // preview load in the fleet.
+    expect(postMessage).toHaveBeenCalledTimes(1);
+  });
+
+  it('sends the whole catalog every time, so a re-announce replaces', () => {
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+    const { registry, register } = load();
+
+    register.registerCustomBlocks('acme', { 'promo-strip': Promo });
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+
+    // A second barrel, then a second announce — as an in-iframe route change
+    // produces when its placeholders remount.
+    register.registerCustomBlocks('acme', { 'promo-banner': Promo });
+    registry.registerPlaceholder('footer');
+    jest.advanceTimersByTime(100);
+
+    const [first, second] = frames();
+    expect(first.customBlocks.blocks.map((block) => block.type)).toEqual([
+      'custom:acme:promo-strip'
+    ]);
+    // The full snapshot, not the delta. The receiver replaces what it holds;
+    // if this frame carried only the new block, replacing would drop the
+    // first one and the editor would offer a type it can no longer describe.
+    expect(second.customBlocks.blocks.map((block) => block.type)).toEqual([
+      'custom:acme:promo-strip',
+      'custom:acme:promo-banner'
+    ]);
+    expect(second.placeholders).toEqual(['header', 'footer']);
+  });
+});

package/src/blocks/group-block.tsx

@@ -2,10 +2,7 @@ import React from 'react';
 import NextLink from 'next/link';
 import { getResponsiveValue } from '../utils';
 import { BlockRendererProps } from './block-renderer-registry';
-import ThemeBlock from '../theme-block';
-
-import { postToEditor } from '../editor-bridge';
-import { PreviewToEditorMessageType } from '@akinon/theme-contract';
+import { renderComposedChildren } from './render-composed-children';
 
 /**
  * Composed anchors to the storefront's own routes navigate client-side. A
@@ -68,59 +65,14 @@ const GroupBlock = ({
     );
   }
 
-  const renderedChildren = block.blocks
-        .filter((childBlock) => (isDesigner ? true : !childBlock.hidden))
-        .sort((a, b) => (a.order || 0) - (b.order || 0))
-        .map((childBlock, index) => {
-          const createActionHandler =
-            (actionType: PreviewToEditorMessageType) => () => {
-              if (window.parent) {
-                postToEditor({
-                  type: actionType,
-                  data: {
-                    placeholderId,
-                    sectionId,
-                    blockId: childBlock.id
-                  }
-                });
-              }
-            };
-
-          const handleRename = (newLabel: string) => {
-            if (window.parent) {
-              postToEditor({
-                type: 'RENAME_BLOCK',
-                data: {
-                  placeholderId,
-                  sectionId,
-                  blockId: childBlock.id,
-                  label: newLabel
-                }
-              });
-            }
-          };
-
-          return (
-            <ThemeBlock
-              key={childBlock.id || `block-${index}`}
-              block={childBlock}
-              placeholderId={placeholderId}
-              sectionId={sectionId}
-              isDesigner={isDesigner}
-              isSelected={selectedBlockId === childBlock.id}
-              selectedBlockId={selectedBlockId}
-              currentBreakpoint={currentBreakpoint}
-              onMoveUp={createActionHandler('MOVE_BLOCK_UP')}
-              onMoveDown={createActionHandler('MOVE_BLOCK_DOWN')}
-              onDuplicate={createActionHandler('DUPLICATE_BLOCK')}
-              onToggleVisibility={createActionHandler(
-                'TOGGLE_BLOCK_VISIBILITY'
-              )}
-              onDelete={createActionHandler('DELETE_BLOCK')}
-              onRename={handleRename}
-            />
-          );
-        });
+  const renderedChildren = renderComposedChildren({
+    blocks: block.blocks,
+    placeholderId,
+    sectionId,
+    isDesigner,
+    selectedBlockId,
+    currentBreakpoint
+  });
 
   if (useRouterLink) {
     return (

package/src/blocks/render-composed-children.tsx

@@ -0,0 +1,104 @@
+import React from 'react';
+import { PreviewToEditorMessageType } from '@akinon/theme-contract';
+import ThemeBlock, { Block } from '../theme-block';
+import { postToEditor } from '../editor-bridge';
+
+export interface ComposedChildrenOptions {
+  /** A container's `block.blocks`. Absent and empty are the same thing here. */
+  blocks?: Block[];
+  placeholderId: string;
+  sectionId: string;
+  isDesigner: boolean;
+  selectedBlockId?: string | null;
+  currentBreakpoint?: string;
+}
+
+/**
+ * Renders the children of any container block: visibility filter, order sort,
+ * and the six editor action callbacks every child needs to be movable,
+ * duplicable, hideable, deletable and renamable on the canvas.
+ *
+ * Extracted because the callbacks are the expensive half. `tabs-section.tsx`
+ * hand-writes this same block of `postToEditor` closures twice — once at line
+ * 225 for its non-tab children and again at line 363 for the tab strip — and
+ * every copy is a place a new message field has to be remembered. A container
+ * that reimplemented them would be the third copy, and copies drift: a child
+ * whose `onRename` was forgotten simply refuses to rename on the canvas, with
+ * nothing logged anywhere.
+ *
+ * A plain function rather than a component on purpose. A `<ComposedChildren>`
+ * wrapper would insert a fiber between the container and its children, and
+ * the container's own element (GroupBlock's `<Tag className="contents">`) is
+ * frequently `display: contents` precisely so the children inherit the
+ * grandparent's grid — an extra layer there is not free. Returning the array
+ * keeps the rendered tree byte-identical to hand-writing the loop inline.
+ */
+export const renderComposedChildren = ({
+  blocks,
+  placeholderId,
+  sectionId,
+  isDesigner,
+  selectedBlockId,
+  currentBreakpoint
+}: ComposedChildrenOptions): React.ReactElement[] => {
+  if (!blocks || blocks.length === 0) return [];
+
+  return (
+    blocks
+      // The designer keeps hidden children mounted so they stay selectable in
+      // the layer tree; the storefront must never ship them.
+      .filter((childBlock) => (isDesigner ? true : !childBlock.hidden))
+      .sort((a, b) => (a.order || 0) - (b.order || 0))
+      .map((childBlock, index) => {
+        const createActionHandler =
+          (actionType: PreviewToEditorMessageType) => () => {
+            if (window.parent) {
+              postToEditor({
+                type: actionType,
+                data: {
+                  placeholderId,
+                  sectionId,
+                  blockId: childBlock.id
+                }
+              });
+            }
+          };
+
+        // Not foldable into `createActionHandler`: rename is the one action
+        // that carries a payload beyond the block identity, so its handler
+        // takes an argument the others have no way to supply.
+        const handleRename = (newLabel: string) => {
+          if (window.parent) {
+            postToEditor({
+              type: 'RENAME_BLOCK',
+              data: {
+                placeholderId,
+                sectionId,
+                blockId: childBlock.id,
+                label: newLabel
+              }
+            });
+          }
+        };
+
+        return (
+          <ThemeBlock
+            key={childBlock.id || `block-${index}`}
+            block={childBlock}
+            placeholderId={placeholderId}
+            sectionId={sectionId}
+            isDesigner={isDesigner}
+            isSelected={selectedBlockId === childBlock.id}
+            selectedBlockId={selectedBlockId}
+            currentBreakpoint={currentBreakpoint}
+            onMoveUp={createActionHandler('MOVE_BLOCK_UP')}
+            onMoveDown={createActionHandler('MOVE_BLOCK_DOWN')}
+            onDuplicate={createActionHandler('DUPLICATE_BLOCK')}
+            onToggleVisibility={createActionHandler('TOGGLE_BLOCK_VISIBILITY')}
+            onDelete={createActionHandler('DELETE_BLOCK')}
+            onRename={handleRename}
+          />
+        );
+      })
+  );
+};