@akinon/pz-theme 2.0.78-rc.1 → 2.0.78

package/src/custom/__tests__/define-section.test.tsx

@@ -0,0 +1,481 @@
+import React from 'react';
+
+import blockRendererRegistry from '../../blocks/block-renderer-registry';
+import { resetCustomCatalog } from '../catalog';
+import { resetCustomCollection } from '../collect';
+import { defineCustomBlock } from '../define';
+import {
+  CUSTOM_SECTION_MARKER,
+  defineCustomSection,
+  isCustomSectionDefinition
+} from '../define-section';
+import { registerCustomBlocks, registerCustomSections } from '../register';
+import {
+  getCustomSectionDescriptor,
+  getCustomSectionTypes,
+  resetCustomSectionCatalog
+} from '../section-catalog';
+import {
+  getCustomSectionDefinition,
+  hasCustomSectionDefinition,
+  resetCustomSectionDefinitions
+} from '../section-definitions';
+import { CUSTOM_SECTION_LIMITS } from '../section-types';
+import { isCustomThemeType } from '../types';
+
+/**
+ * Neither registry has an `unregister` — a build registers once and a
+ * storefront never takes a type back. A test file registers dozens of times
+ * into that same module state, so it reaches the private Map directly, exactly
+ * as define.test.tsx does.
+ */
+const rendererMap = (): Map<string, unknown> =>
+  (blockRendererRegistry as unknown as { renderers: Map<string, unknown> })
+    .renderers;
+
+const clearCustomRenderers = (): void => {
+  const map = rendererMap();
+  Array.from(map.keys())
+    .filter(isCustomThemeType)
+    .forEach((type) => map.delete(type));
+};
+
+const Header = () => <header>header</header>;
+const ProductPage = () => <main>product</main>;
+
+const HEADER = 'custom:acme:header';
+
+const headerDescriptor = () => getCustomSectionDescriptor(HEADER);
+
+beforeEach(() => {
+  resetCustomCatalog();
+  resetCustomCollection();
+  resetCustomSectionCatalog();
+  resetCustomSectionDefinitions();
+  clearCustomRenderers();
+});
+
+describe('defineCustomSection', () => {
+  it('tags the wrapper with a string marker, not a Symbol', () => {
+    const definition = defineCustomSection(Header, { label: 'Header' });
+
+    // A brand can resolve two physical copies of pz-theme at once. A
+    // `Symbol()` per copy would make one copy read the other's definition as a
+    // bare component and silently drop every option declared here.
+    expect(definition.$$pzCustomSection).toBe(CUSTOM_SECTION_MARKER);
+    expect(typeof CUSTOM_SECTION_MARKER).toBe('string');
+    expect(isCustomSectionDefinition(definition)).toBe(true);
+    expect(isCustomSectionDefinition(Header)).toBe(false);
+  });
+
+  it('accepts a component wrapped in memo, which is ordinary React', () => {
+    const definition = defineCustomSection(
+      React.memo(Header) as unknown as typeof Header
+    );
+
+    expect(isCustomSectionDefinition(definition)).toBe(true);
+  });
+
+  it('throws on a value that could never render, naming what it received', () => {
+    expect(() =>
+      defineCustomSection(undefined as unknown as typeof Header)
+    ).toThrow(/expects a React component, received undefined/);
+  });
+
+  it('refuses a record entry that is not a component at all', () => {
+    // The shape a missing default export arrives in: `{ header: undefined }`
+    // from a barrel whose file exports nothing. Named at the record key,
+    // because that is the only identifier the developer can search for.
+    expect(() =>
+      registerCustomSections('acme', {
+        header: undefined as unknown as typeof Header
+      })
+    ).toThrow(/Custom section "header" is neither a React component/);
+  });
+});
+
+describe('registerCustomSections — the offered-implies-renderable invariant', () => {
+  it('puts every registered section in BOTH stores, and nothing else in either', () => {
+    registerCustomSections('acme', {
+      header: defineCustomSection(Header, { label: 'ZSA header' }),
+      // A bare component: someone will forget the wrapper, and a section with
+      // no declared options is a complete section.
+      'product-page': ProductPage
+    });
+
+    const expected = new Set([HEADER, 'custom:acme:product-page']);
+
+    expect(new Set(getCustomSectionTypes())).toEqual(expected);
+    expect(hasCustomSectionDefinition(HEADER)).toBe(true);
+    // A type in the catalog and not in the definitions is a section the editor
+    // offers and the storefront cannot draw; the reverse is one the merchant
+    // can never place. Both directions are checked.
+    getCustomSectionTypes().forEach((type) => {
+      expect(hasCustomSectionDefinition(type)).toBe(true);
+    });
+    expect(getCustomSectionDefinition('custom:acme:product-page')?.component).toBe(
+      ProductPage
+    );
+  });
+
+  it('registers a bare component under the record key, not the component name', () => {
+    // Minification renames `Header` to a single letter; the record key is the
+    // only source that survives a production build.
+    registerCustomSections('acme', { header: Header });
+
+    expect(headerDescriptor()?.name).toBe('header');
+    expect(headerDescriptor()?.label).toBe('header');
+  });
+});
+
+describe('registerCustomSections — one type namespace, two stores', () => {
+  it('refuses a type a custom BLOCK already claimed', () => {
+    // Blocks and sections share the `custom:<vendor>:<name>` grammar, so
+    // nothing downstream can tell them apart from the string alone: the editor
+    // resolves a section through its section catalog and a block through its
+    // block catalog, and a type in both resolves differently depending on
+    // which lookup ran.
+    registerCustomBlocks('acme', {
+      header: defineCustomBlock(Header, { label: 'Header block' })
+    });
+
+    expect(() => registerCustomSections('acme', { header: Header })).toThrow(
+      /already registered in this build, as a block or as a section/
+    );
+  });
+
+  it('refuses a type a custom SECTION already claimed, from the BLOCK door', () => {
+    // The other direction, and it was one-way for a while: the block door
+    // checked only the block stores, so a section registered first and a block
+    // of the same type second was silently accepted — leaving one type present
+    // in all four stores, resolving as whichever the caller happened to ask.
+    // A namespace guarded in one direction is not a namespace.
+    registerCustomSections('acme', { header: Header });
+
+    expect(() =>
+      registerCustomBlocks('acme', {
+        header: defineCustomBlock(Header, { label: 'Header block' })
+      })
+    ).toThrow(/already registered in this build, as a block or as a section/);
+  });
+
+  it('refuses a second registration of the same section type', () => {
+    registerCustomSections('acme', { header: Header });
+
+    expect(() =>
+      registerCustomSections('acme', { header: ProductPage })
+    ).toThrow(/already registered/);
+  });
+
+  it('leaves the first entry unregistered in both stores when a later one is invalid', () => {
+    // A half-registered barrel is worse than a rejected one: the Add Section
+    // band would offer a section the build can draw and hide one it cannot.
+    expect(() =>
+      registerCustomSections('acme', {
+        header: Header,
+        'product-page': defineCustomSection(ProductPage, {
+          regions: [{ name: 'Gallery', block: 'image' }]
+        })
+      })
+    ).toThrow(/"Gallery" is not valid/);
+
+    expect(getCustomSectionTypes()).toEqual([]);
+    expect(hasCustomSectionDefinition(HEADER)).toBe(false);
+  });
+});
+
+describe('registerCustomSections — naming', () => {
+  it('throws on a vendor that is not a valid segment', () => {
+    expect(() => registerCustomSections('Acme Inc', { header: Header })).toThrow(
+      /vendor "Acme Inc"/
+    );
+  });
+
+  it('throws on a section name that is not a valid segment', () => {
+    expect(() => registerCustomSections('acme', { Header_Bar: Header })).toThrow(
+      /"Header_Bar"/
+    );
+  });
+});
+
+describe('registerCustomSections — declared regions', () => {
+  it('carries the name, the block type and the seed through untouched', () => {
+    registerCustomSections('acme', {
+      header: defineCustomSection(Header, {
+        regions: [
+          { name: 'logo', label: 'Logo', block: 'image' },
+          {
+            name: 'basket',
+            block: 'mini-basket',
+            properties: { showCount: { desktop: true } },
+            styles: { 'margin-left': '16px' }
+          }
+        ]
+      })
+    });
+
+    // The name is what `<ThemeRegion name>` matches against the seeded block,
+    // and the seed is written straight into the composition, so both have to
+    // survive registration verbatim.
+    expect(headerDescriptor()?.regions).toEqual([
+      { name: 'logo', label: 'Logo', block: 'image' },
+      {
+        name: 'basket',
+        block: 'mini-basket',
+        properties: { showCount: { desktop: true } },
+        styles: { 'margin-left': '16px' }
+      }
+    ]);
+  });
+
+  it('throws on a name no seeded block could be matched by', () => {
+    expect(() =>
+      registerCustomSections('acme', {
+        header: defineCustomSection(Header, {
+          regions: [{ name: 'Store Search', block: 'search-box' }]
+        })
+      })
+    ).toThrow(/"Store Search" is not valid/);
+  });
+
+  it('throws naming a region declared twice', () => {
+    expect(() =>
+      registerCustomSections('acme', {
+        header: defineCustomSection(Header, {
+          regions: [
+            { name: 'logo', block: 'image' },
+            { name: 'logo', block: 'text' }
+          ]
+        })
+      })
+    ).toThrow(/declares the region "logo" twice/);
+  });
+
+  it('throws on a region with no block type — the merchant would see nothing to open', () => {
+    expect(() =>
+      registerCustomSections('acme', {
+        header: defineCustomSection(Header, {
+          regions: [{ name: 'logo', block: '' }]
+        })
+      })
+    ).toThrow(/with no block type/);
+  });
+
+  it.each(['properties', 'styles'])(
+    'throws on a %s seed that is not the shape the composition stores',
+    (field) => {
+      expect(() =>
+        registerCustomSections('acme', {
+          header: defineCustomSection(Header, {
+            regions: [
+              {
+                name: 'logo',
+                block: 'image',
+                [field]: ['margin-left', '16px']
+              } as never
+            ]
+          })
+        })
+      ).toThrow(/is not a plain object/);
+    }
+  );
+
+  it('throws when one name is declared as both a region and a slot', () => {
+    // Two rows with one name in the layer tree. The resolvers never collide —
+    // they read different properties — but the merchant has no way to tell
+    // which row is which.
+    expect(() =>
+      registerCustomSections('acme', {
+        header: defineCustomSection(Header, {
+          regions: [{ name: 'extras', block: 'image' }],
+          slots: [{ name: 'extras' }]
+        })
+      })
+    ).toThrow(/as both a region and a slot/);
+  });
+});
+
+describe('registerCustomSections — caps', () => {
+  const many = <T,>(count: number, build: (index: number) => T): T[] =>
+    Array.from({ length: count }, (_, index) => build(index));
+
+  it('refuses more regions than the editor would seed', () => {
+    expect(() =>
+      registerCustomSections('acme', {
+        header: defineCustomSection(Header, {
+          regions: many(CUSTOM_SECTION_LIMITS.regionsPerType + 1, (index) => ({
+            name: `r${index}`,
+            block: 'image'
+          }))
+        })
+      })
+    ).toThrow(/regions, over the 24 cap/);
+  });
+
+  it('refuses more slots than the announce should carry', () => {
+    expect(() =>
+      registerCustomSections('acme', {
+        header: defineCustomSection(Header, {
+          slots: many(CUSTOM_SECTION_LIMITS.slotsPerType + 1, (index) => ({
+            name: `s${index}`
+          }))
+        })
+      })
+    ).toThrow(/slots, over the 8 cap/);
+  });
+
+  it('refuses more settings than the panel should carry', () => {
+    expect(() =>
+      registerCustomSections('acme', {
+        header: defineCustomSection(Header, {
+          settings: many(
+            CUSTOM_SECTION_LIMITS.settingsPerType + 1,
+            (index) => ({ key: `k${index}`, type: 'text' as const })
+          )
+        })
+      })
+    ).toThrow(/settings, over the 24 cap/);
+  });
+
+  it('refuses more parts than the editor would build control groups for', () => {
+    expect(() =>
+      registerCustomSections('acme', {
+        header: defineCustomSection(Header, {
+          parts: many(CUSTOM_SECTION_LIMITS.partsPerType + 1, (index) =>
+            `p${index}`
+          )
+        })
+      })
+    ).toThrow(/parts, over the 32 cap/);
+  });
+
+  it('refuses a build declaring more sections than the announce should carry', () => {
+    const record: Record<string, typeof Header> = {};
+    many(CUSTOM_SECTION_LIMITS.sectionTypesPerBuild + 1, (index) => index).forEach(
+      (index) => {
+        record[`section-${index}`] = Header;
+      }
+    );
+
+    expect(() => registerCustomSections('acme', record)).toThrow(
+      /would declare 17 custom sections, over the 16 cap/
+    );
+    // Refused whole: the cap is enforced before anything is written, so the
+    // build does not end up with 16 of the 17 registered.
+    expect(getCustomSectionTypes()).toEqual([]);
+  });
+});
+
+describe('registerCustomSections — the descriptor on the wire', () => {
+  it('survives its own JSON round trip unchanged', () => {
+    registerCustomSections('acme', {
+      header: defineCustomSection(Header, {
+        label: 'ZSA header',
+        icon: 'layout',
+        group: 'Chrome',
+        settings: [
+          {
+            key: 'tone',
+            type: 'select',
+            label: 'Tone',
+            options: ['light', 'dark'],
+            defaultValue: 'light'
+          }
+        ],
+        regions: [{ name: 'logo', label: 'Logo', block: 'image' }],
+        slots: [{ name: 'extras', label: 'Extra header actions' }],
+        parts: { bar: { states: ['hover'] } },
+        styles: { 'padding-top': '12px' },
+        placeholders: ['header'],
+        lockRootTransforms: true
+      })
+    });
+
+    const descriptor = headerDescriptor();
+
+    expect(descriptor).toEqual(JSON.parse(JSON.stringify(descriptor)));
+  });
+
+  it('keeps the three section-only fields, which nothing else carries', () => {
+    registerCustomSections('acme', {
+      header: defineCustomSection(Header, {
+        styles: { 'padding-top': '12px' },
+        placeholders: ['header', 'header-mobile'],
+        lockRootTransforms: true
+      })
+    });
+
+    const descriptor = headerDescriptor();
+
+    // `lockRootTransforms` is the one that is not tidiness: rotate, scale,
+    // translate, filter and backdrop-filter each create a containing block for
+    // a `position: fixed` descendant, so one of them on the root collapses a
+    // fixed header into the root's own box — measured at 1247px becoming
+    // 600px. Losing this field in transit puts the trap back on the panel.
+    expect(descriptor?.lockRootTransforms).toBe(true);
+    expect(descriptor?.placeholders).toEqual(['header', 'header-mobile']);
+    expect(descriptor?.styles).toEqual({ 'padding-top': '12px' });
+  });
+
+  it('says hasChildren even for a section that declares neither region nor slot', () => {
+    // Unlike a block, which earns it by declaring a slot. A section always
+    // hosts children, and the editor reads the same field off its own registry
+    // entry — a false here makes the section undroppable.
+    registerCustomSections('acme', { header: Header });
+
+    expect(headerDescriptor()?.hasChildren).toBe(true);
+    expect(headerDescriptor()?.regions).toEqual([]);
+    expect(headerDescriptor()?.slots).toEqual([]);
+  });
+
+  it('omits an undeclared optional field rather than sending it undefined', () => {
+    registerCustomSections('acme', { header: Header });
+
+    // Through `unknown`: a descriptor is an interface with no index
+    // signature, and jest never type-checks this file — the only tsc that
+    // reaches it is the template app's, where the direct cast is an error.
+    const descriptor = headerDescriptor() as unknown as Record<
+      string,
+      unknown
+    >;
+
+    // `undefined` does not survive postMessage, and a descriptor carrying the
+    // key would diverge from its own round trip — which is what
+    // `assertSerializable` refuses.
+    expect('icon' in descriptor).toBe(false);
+    expect('placeholders' in descriptor).toBe(false);
+    expect('lockRootTransforms' in descriptor).toBe(false);
+  });
+
+  it('throws naming the path of a value JSON would drop', () => {
+    expect(() =>
+      registerCustomSections('acme', {
+        header: defineCustomSection(Header, {
+          regions: [
+            {
+              name: 'logo',
+              block: 'image',
+              // A function cannot cross postMessage; without the mechanical
+              // catch the editor would seed this region with no styles and
+              // nothing would report it.
+              styles: { 'margin-left': () => '16px' }
+            }
+          ]
+        })
+      })
+    ).toThrow(/does not survive JSON/);
+  });
+
+  it('joins the declared parts to the field-derived ones in one list', () => {
+    registerCustomSections('acme', {
+      header: defineCustomSection(Header, {
+        settings: [
+          { key: 'tagline', type: 'text', label: 'Tagline', editable: true }
+        ],
+        parts: ['bar', 'row']
+      })
+    });
+
+    expect(headerDescriptor()?.parts).toEqual(['field-tagline', 'bar', 'row']);
+  });
+});

package/src/custom/__tests__/module-boundaries.test.ts

@@ -78,7 +78,9 @@ describe('src/custom module boundaries', () => {
       'block-context.ts',
       'block-host.tsx',
       'register.ts',
+      'section-host.tsx',
       'theme-editable.tsx',
+      'theme-region.tsx',
       'theme-slot.tsx',
       'use-theme-setting.ts'
     ]);

package/src/custom/__tests__/public-api.test.tsx

@@ -18,6 +18,8 @@ import blockRendererRegistry from '../../blocks/block-renderer-registry';
 import type { BlockRendererProps } from '../../blocks/block-renderer-registry';
 import { resetCustomCatalog } from '../catalog';
 import { resetCustomCollection } from '../collect';
+import { resetCustomSectionCatalog } from '../section-catalog';
+import { resetCustomSectionDefinitions } from '../section-definitions';
 
 // Through the barrel, never the individual modules. That is the point of this
 // file: the three pieces each have their own suite, and every one of them
@@ -25,15 +27,24 @@ import { resetCustomCollection } from '../collect';
 // still leave 86 green tests behind — while `@akinon/pz-theme/src/custom`, the
 // path a brand actually types, resolved to nothing.
 import {
+  CUSTOM_SECTION_LIMITS,
   CUSTOM_SLOT_BLOCK_TYPE,
   CUSTOM_TYPE_PREFIX,
   defineCustomBlock,
+  defineCustomSection,
+  findRegionChild,
   getCustomCatalog,
+  getCustomSectionCatalog,
   isCustomThemeType,
+  isRegionNode,
   partAttrs,
+  REGION_NAME_PROPERTY,
+  regionNodeName,
   registerCustomBlocks,
+  registerCustomSections,
   SLOT_NAME_PROPERTY,
   ThemeEditable,
+  ThemeRegion,
   ThemeSlot,
   useThemeSetting
 } from '../index';
@@ -187,6 +198,8 @@ afterEach(() => {
   clearCustomRenderers();
   resetCustomCatalog();
   resetCustomCollection();
+  resetCustomSectionCatalog();
+  resetCustomSectionDefinitions();
 });
 
 describe('the documented barrel', () => {
@@ -361,6 +374,116 @@ describe('the advertised parts and the rendered DOM', () => {
   });
 });
 
+/**
+ * The SECTION half of the same barrel. A brand writing a header imports
+ * `defineCustomSection`, `ThemeRegion` and `registerCustomSections` from this
+ * one path, and every one of them is a name the root re-exports by hand — a
+ * renamed symbol compiles here and fails at the brand.
+ */
+describe('the section authoring surface', () => {
+  const HEADER = 'custom:acme:header';
+
+  /** The barrel's own documented example, unaltered. */
+  function ZsaHeader() {
+    return (
+      <header {...partAttrs('bar')}>
+        <ThemeRegion name="logo" />
+        <ThemeRegion name="basket" />
+        <ThemeSlot name="extras" label="Extra header actions" />
+      </header>
+    );
+  }
+
+  const registerHeader = () =>
+    registerCustomSections('acme', {
+      header: defineCustomSection(ZsaHeader, {
+        label: 'ZSA ZSA ZSU Header',
+        regions: [
+          { name: 'logo', label: 'Logo', block: 'image' },
+          { name: 'basket', label: 'Basket', block: 'mini-basket' }
+        ],
+        slots: [{ name: 'extras', label: 'Extra header actions' }],
+        parts: ['bar'],
+        placeholders: ['header'],
+        lockRootTransforms: true
+      })
+    });
+
+  it('describes a registered section through the same barrel that registered it', () => {
+    registerHeader();
+
+    const catalog = getCustomSectionCatalog('acme');
+    const descriptor = catalog?.sections.find(
+      (entry) => entry.type === HEADER
+    );
+
+    expect(catalog?.vendor).toBe('acme');
+    // A region is a child the developer NAMED, chose the type of and PLACED —
+    // so the block type is part of the description, and it is what buys the
+    // merchant that block's own panel.
+    expect(descriptor?.regions).toEqual([
+      { name: 'logo', label: 'Logo', block: 'image' },
+      { name: 'basket', label: 'Basket', block: 'mini-basket' }
+    ]);
+    expect(descriptor?.slots.map((slot) => slot.name)).toEqual(['extras']);
+    expect(descriptor?.parts).toEqual(['bar']);
+    expect(descriptor?.placeholders).toEqual(['header']);
+    expect(descriptor?.lockRootTransforms).toBe(true);
+    expect(descriptor?.hasChildren).toBe(true);
+  });
+
+  it('rides beside the block catalog rather than inside it', () => {
+    registerCustomSections('acme', { header: ZsaHeader });
+
+    // Two payloads, two byte budgets. The editor validates the BLOCK catalog
+    // element by element and drops the whole thing on an unexpected shape, so
+    // nesting sections inside it would make every block in a build vanish from
+    // the palette of any editor older than this change.
+    expect(getCustomSectionCatalog('acme')?.sections).toHaveLength(1);
+    expect(getCustomCatalog()?.blocks.map((block) => block.type)).toEqual(
+      expect.arrayContaining([PROMO])
+    );
+    expect(
+      getCustomCatalog()?.blocks.some((block) => block.type === HEADER)
+    ).toBe(false);
+  });
+
+  it('reads a seeded region back through the grammar it exports', () => {
+    // The editor mirrors `REGION_NAME_PROPERTY` and seeds the block; this
+    // package reads it back. Both sides are exported from here so the mirror
+    // can be diffed against one constant instead of a literal re-typed
+    // slightly wrong.
+    const seeded = {
+      id: 'block-h3n1a',
+      type: 'image',
+      label: 'Logo',
+      properties: { [REGION_NAME_PROPERTY]: 'logo' },
+      styles: {},
+      order: 0,
+      hidden: false
+    };
+
+    expect(REGION_NAME_PROPERTY).toBe('regionName');
+    expect(regionNodeName(seeded)).toBe('logo');
+    expect(isRegionNode(seeded)).toBe(true);
+    expect(findRegionChild({ blocks: [seeded] }, 'logo')).toBe(seeded);
+  });
+
+  it('publishes the section caps the editor mirrors as literals', () => {
+    // Every one is mirrored independently on the far side, and the receiver's
+    // answer to an over-cap catalog is to drop all of it — so a number moving
+    // on one side alone empties a brand's whole section band.
+    expect(CUSTOM_SECTION_LIMITS).toEqual({
+      sectionTypesPerBuild: 16,
+      settingsPerType: 24,
+      regionsPerType: 24,
+      slotsPerType: 8,
+      partsPerType: 32,
+      catalogBytes: 256 * 1024
+    });
+  });
+});
+
 describe('the curated package root', () => {
   /**
    * Parsed from source rather than imported, exactly as