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

package/src/custom/__tests__/region-node-wire.test.tsx

@@ -0,0 +1,302 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+
+// The recursive renderer, stubbed with a countable marker so a region's block
+// is assertable without dragging every block renderer into the assertion. The
+// same stand-in `slot-node-wire.test.tsx` uses, for the same reason.
+jest.mock('../../theme-block', () => ({
+  __esModule: true,
+  default: ({ block }: { block: { id: string } }) => (
+    <div data-testid="region-child" data-id={block.id} />
+  )
+}));
+
+import blockRendererRegistry from '../../blocks/block-renderer-registry';
+import ThemeSection from '../../theme-section';
+import type { Section } from '../../theme-section';
+import { ThemeSettingsProvider } from '../../theme-settings-context';
+import { resetCustomCatalog } from '../catalog';
+import { resetCustomCollection } from '../collect';
+import { defineCustomSection } from '../define-section';
+import { registerCustomSections } from '../register';
+import { resetCustomSectionCatalog } from '../section-catalog';
+import { resetCustomSectionDefinitions } from '../section-definitions';
+import { ThemeRegion } from '../theme-region';
+import { ThemeSlot } from '../theme-slot';
+import { isCustomThemeType } from '../types';
+
+/**
+ * THE OTHER HALF OF THE CROSS-REPO SEAM, for sections.
+ *
+ * The catalog travels one way — this repo describes the section and the editor
+ * reads it. Region blocks travel the OTHER way: the editor seeds them into the
+ * composition and this repo reads them back. Nothing in this package's own
+ * tests could notice if the two sides disagreed about the seeded shape, because
+ * every other region test here builds its composition from this repo's own
+ * constants.
+ *
+ * `EDITOR_COMPOSITION` below is therefore read as DATA. It is the shape the
+ * editor's section insert writes for a section whose descriptor declares the
+ * three regions and the one slot the component below places: an ORDINARY block
+ * of the declared type per region, carrying `properties.regionName`, plus a
+ * `custom-slot` node for the slot. A region is NOT a wrapper node, and that
+ * asymmetry with slots is the whole design — the merchant opens the row and
+ * gets the `image`/`search-box`/`mini-basket` panel itself.
+ *
+ * TO REGENERATE, in `pz-dynamic-widget`: ingest a section catalog through
+ * `parseCustomSectionCatalogPayload` + `setCustomSectionCatalog`, add a section
+ * of that type so the insert reducer seeds its regions from
+ * `getCustomSectionRegions(type)`, and log `section.blocks`. The ids are the
+ * only values that differ per run.
+ *
+ * Written WITHOUT this repo's own constants. `REGION_NAME_PROPERTY` is exported
+ * precisely so the editor can mirror it, and a fixture spelled through that
+ * export would follow a rename here and stay green while the editor went on
+ * seeding the old spelling — which is the one failure this file exists to
+ * catch.
+ */
+const EDITOR_COMPOSITION = {
+  id: 'section-header',
+  type: 'custom:zsazsazsu:header',
+  name: 'ZSA ZSA ZSU Header',
+  label: 'ZSA ZSA ZSU Header',
+  properties: {},
+  styles: {},
+  order: 0,
+  hidden: false,
+  blocks: [
+    {
+      id: 'block-h3n1a',
+      type: 'image',
+      label: 'Logo',
+      properties: { regionName: 'logo' },
+      styles: {},
+      order: 0,
+      hidden: false
+    },
+    {
+      id: 'block-k92rd',
+      type: 'search-box',
+      label: 'Store search',
+      properties: { regionName: 'search' },
+      styles: {},
+      order: 1,
+      hidden: false
+    },
+    {
+      id: 'block-p47xv',
+      type: 'mini-basket',
+      label: 'Basket',
+      properties: { regionName: 'basket' },
+      styles: {},
+      order: 2,
+      hidden: false
+    },
+    {
+      id: 'block-t6qz0',
+      type: 'custom-slot',
+      label: 'Extra header actions',
+      properties: { slotName: 'extras' },
+      styles: {},
+      order: 3,
+      hidden: false,
+      blocks: [
+        {
+          id: 'extras-child',
+          type: 'text',
+          label: 'Text',
+          properties: {},
+          styles: {},
+          order: 0,
+          hidden: false
+        }
+      ]
+    }
+  ]
+} as unknown as Section;
+
+const TYPE = 'custom:zsazsazsu:header';
+
+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));
+};
+
+/** Places its three regions and its one slot exactly as the descriptor declares them. */
+function ZsaHeader() {
+  return (
+    <header>
+      <div data-testid="logo-area">
+        <ThemeRegion name="logo" />
+      </div>
+      <div data-testid="search-area">
+        <ThemeRegion name="search" label="Store search" />
+      </div>
+      <div data-testid="basket-area">
+        <ThemeRegion name="basket" />
+      </div>
+      <div data-testid="extras-area">
+        <ThemeSlot name="extras" label="Extra header actions" />
+      </div>
+    </header>
+  );
+}
+
+const registerHeader = () =>
+  registerCustomSections('zsazsazsu', {
+    header: defineCustomSection(ZsaHeader, {
+      label: 'ZSA ZSA ZSU Header',
+      regions: [
+        { name: 'logo', label: 'Logo', block: 'image' },
+        { name: 'search', label: 'Store search', block: 'search-box' },
+        { name: 'basket', label: 'Basket', block: 'mini-basket' }
+      ],
+      slots: [{ name: 'extras', label: 'Extra header actions' }],
+      lockRootTransforms: true
+    })
+  });
+
+const renderComposition = (section: Section, isDesigner = false) =>
+  render(
+    <ThemeSettingsProvider value={null}>
+      <ThemeSection
+        section={section}
+        placeholderId="header"
+        currentBreakpoint="desktop"
+        isDesigner={isDesigner}
+      />
+    </ThemeSettingsProvider>
+  );
+
+const childIdsIn = (areaTestId: string): string[] =>
+  Array.from(
+    screen
+      .getByTestId(areaTestId)
+      .querySelectorAll('[data-testid="region-child"]')
+  ).map((element) => element.getAttribute('data-id') ?? '');
+
+/** A deep copy, so one test's edit cannot reach the next one's fixture. */
+const composition = (): Section =>
+  JSON.parse(JSON.stringify(EDITOR_COMPOSITION)) as Section;
+
+describe('the region blocks the editor actually seeds', () => {
+  beforeEach(() => {
+    resetCustomCatalog();
+    resetCustomCollection();
+    resetCustomSectionCatalog();
+    resetCustomSectionDefinitions();
+    clearCustomRenderers();
+  });
+
+  it('each render into the ThemeRegion that names them, and no other', () => {
+    registerHeader();
+    renderComposition(composition());
+
+    // Three regions placed independently, from three ordinary blocks in one
+    // section, in the order the JSX chose rather than the order they are
+    // seeded in — the layer tree cannot move any of them.
+    expect(childIdsIn('logo-area')).toEqual(['block-h3n1a']);
+    expect(childIdsIn('search-area')).toEqual(['block-k92rd']);
+    expect(childIdsIn('basket-area')).toEqual(['block-p47xv']);
+  });
+
+  it('keep the slot in the same section resolving against its own node', () => {
+    registerHeader();
+    renderComposition(composition());
+
+    // Two grammars in one section: regions matched on `regionName` on an
+    // ordinary block, slots matched on `slotName` on a `custom-slot` wrapper.
+    // Crossing them would put the slot's wrapper into a region, or a region's
+    // block into the slot.
+    expect(childIdsIn('extras-area')).toEqual(['extras-child']);
+  });
+
+  it('are matched on the property the editor writes, not on the label', () => {
+    registerHeader();
+
+    // `RENAME_BLOCK` is the one field of a seeded region a merchant can change
+    // from the layer tree. If the name rode on the label, this rename would
+    // silently detach the block from its `<ThemeRegion name="search" />` and
+    // nothing would say why the area went empty.
+    const renamed = composition();
+    (renamed.blocks as Array<{ label: string }>)[1].label = 'Find a store';
+
+    renderComposition(renamed);
+
+    expect(childIdsIn('search-area')).toEqual(['block-k92rd']);
+  });
+
+  it('leave a region the merchant deleted empty rather than wrong', () => {
+    registerHeader();
+
+    // Deleting a region is an ordinary composition edit and stays durable:
+    // nothing re-seeds it on the next load. The other two are unaffected.
+    const withoutSearch = composition();
+    withoutSearch.blocks = withoutSearch.blocks.filter(
+      (block) => block.id !== 'block-k92rd'
+    );
+
+    renderComposition(withoutSearch);
+
+    expect(childIdsIn('search-area')).toEqual([]);
+    expect(childIdsIn('logo-area')).toEqual(['block-h3n1a']);
+    expect(childIdsIn('basket-area')).toEqual(['block-p47xv']);
+  });
+
+  it('never adopt a block the merchant added to the section itself', () => {
+    registerHeader();
+
+    // THE ANTI-SLOT-FALLBACK INVARIANT ON REAL DATA. `resolveSlotChildren` has
+    // a legacy branch that reads a block's direct children as its unnamed
+    // slot's content, and nothing like it can exist for regions: a section's
+    // direct children are the merchant's own blocks, so a region falling back
+    // to them would draw a loose banner inside the logo area — or, with the
+    // region deleted, draw it three times over.
+    const withStray = composition();
+    withStray.blocks = [
+      ...withStray.blocks.filter((block) => block.id !== 'block-k92rd'),
+      {
+        id: 'merchant-banner',
+        type: 'text',
+        label: 'Free shipping',
+        properties: {},
+        styles: {},
+        order: 4,
+        hidden: false
+      } as unknown as Section['blocks'][number]
+    ];
+
+    renderComposition(withStray);
+
+    expect(childIdsIn('search-area')).toEqual([]);
+    expect(childIdsIn('logo-area')).toEqual(['block-h3n1a']);
+    expect(childIdsIn('basket-area')).toEqual(['block-p47xv']);
+    expect(childIdsIn('extras-area')).toEqual(['extras-child']);
+  });
+
+  it('are never spilled onto the page by a build that cannot draw the section', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    // The composition holds a section whose barrel was not imported — a stale
+    // published widget, or a client root that lost the import. The generic
+    // block loop must NOT take over: it would spill the seeded regions onto
+    // the page as loose top-level content, in an order the developer never
+    // chose.
+    const { container } = renderComposition(composition());
+
+    expect(container).toBeEmptyDOMElement();
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining(`No renderer registered for custom section type: "${TYPE}"`)
+    );
+
+    warn.mockRestore();
+  });
+});

package/src/custom/__tests__/region-nodes.test.ts

@@ -0,0 +1,161 @@
+import type { Block } from '../../theme-block';
+import { findRegionChild, isRegionNode, regionNodeName } from '../region-nodes';
+import { REGION_NAME_PROPERTY } from '../section-types';
+import { CUSTOM_SLOT_BLOCK_TYPE, SLOT_NAME_PROPERTY } from '../types';
+
+const block = (over: Partial<Block> = {}): Block => ({
+  id: 'b1',
+  type: 'text',
+  label: 'b1',
+  properties: {},
+  styles: {},
+  order: 0,
+  hidden: false,
+  ...over
+});
+
+/**
+ * A seeded region exactly as the editor writes one: an ORDINARY block of a real
+ * type — an `image`, a `search-box` — carrying the reserved name property. It
+ * is not a wrapper node, which is the whole point: the merchant opens it and
+ * gets that block type's own panel.
+ */
+const regionBlock = (name: string, over: Partial<Block> = {}): Block =>
+  block({
+    id: `region-${name}`,
+    type: 'image',
+    label: name,
+    properties: { [REGION_NAME_PROPERTY]: name },
+    ...over
+  });
+
+describe('regionNodeName', () => {
+  it('reads the bare string the editor stamps', () => {
+    expect(regionNodeName(regionBlock('search'))).toBe('search');
+  });
+
+  it('reads a per-breakpoint bucket as well', () => {
+    // Every other value in `block.properties` is per-breakpoint and the panel
+    // re-buckets whatever it is handed. A bare-string-only reader would detach
+    // every region in every published composition the day anything routed this
+    // key through a property control.
+    expect(
+      regionNodeName(
+        block({ properties: { [REGION_NAME_PROPERTY]: { desktop: 'search' } } })
+      )
+    ).toBe('search');
+  });
+
+  it('reads the desktop entry and not merely the first one in the bucket', () => {
+    // The bucket has no ordering guarantee across a JSON round trip, so a
+    // reader taking `Object.values(raw)[0]` would resolve a different region
+    // depending on how the composition happened to be serialized.
+    expect(
+      regionNodeName(
+        block({
+          properties: { [REGION_NAME_PROPERTY]: { mobile: 'search' } }
+        })
+      )
+    ).toBe('');
+  });
+
+  it('is empty for an ordinary composed block', () => {
+    expect(regionNodeName(block())).toBe('');
+    expect(regionNodeName(block({ properties: undefined }))).toBe('');
+  });
+});
+
+describe('isRegionNode', () => {
+  it('recognises a block carrying the name and nothing else', () => {
+    expect(isRegionNode(regionBlock('search'))).toBe(true);
+    expect(isRegionNode(block({ type: 'image' }))).toBe(false);
+  });
+
+  it('does not mistake a slot node for a region', () => {
+    // The two grammars sit side by side in one composition — a custom section
+    // may declare both — and they are matched on different properties. A
+    // reader that crossed them would hand a slot's node to `<ThemeRegion>`,
+    // which renders the wrapper instead of the merchant's blocks.
+    expect(
+      isRegionNode(
+        block({
+          type: CUSTOM_SLOT_BLOCK_TYPE,
+          properties: { [SLOT_NAME_PROPERTY]: 'extras' }
+        })
+      )
+    ).toBe(false);
+  });
+});
+
+describe('findRegionChild', () => {
+  const search = regionBlock('search');
+  const basket = regionBlock('basket');
+
+  it('returns the child seeded for that name and no other', () => {
+    const section = { blocks: [search, basket] };
+
+    expect(findRegionChild(section, 'search')).toBe(search);
+    expect(findRegionChild(section, 'basket')).toBe(basket);
+  });
+
+  it('matches on the property the editor writes, not on the label', () => {
+    // `RENAME_BLOCK` is the one field of a seeded region a merchant can change
+    // from the layer tree. If the name rode on the label, renaming the row
+    // would detach the region from its `<ThemeRegion name="search" />` and the
+    // area would go empty with nothing anywhere to say why.
+    const renamed = regionBlock('search', { label: 'Store finder' });
+
+    expect(findRegionChild({ blocks: [renamed] }, 'search')).toBe(renamed);
+  });
+
+  it('returns null for a name nothing carries', () => {
+    // Not an error: deleting a region is an ordinary composition edit and has
+    // to stay durable. The caller decides what to draw, and only the designer
+    // draws anything.
+    expect(findRegionChild({ blocks: [search] }, 'basket')).toBeNull();
+  });
+
+  it('NEVER falls back to the section ordinary children — there is no unnamed region', () => {
+    // THE ANTI-SLOT-FALLBACK INVARIANT, and the single highest-risk seam in the
+    // feature. `resolveSlotChildren` has a legacy branch that reads a block's
+    // direct children as the content of its unnamed slot, and this resolver is
+    // one refactor away from growing the same branch. It must not: a section's
+    // direct children are the merchant's OWN composed blocks, so a bare or
+    // unmatched region falling back to them would swallow the whole section
+    // and render it inside whatever `<ThemeRegion>` asked first.
+    const composed = { blocks: [block({ id: 'merchant-hero' })] };
+
+    expect(findRegionChild(composed, 'search')).toBeNull();
+    expect(findRegionChild(composed, '')).toBeNull();
+    // Even with a real region beside them, the merchant's own blocks are never
+    // the answer to a name that was not seeded.
+    expect(findRegionChild({ blocks: [search, ...composed.blocks] }, 'logo'))
+      .toBeNull();
+  });
+
+  it('answers nothing for the empty name even when a child carries one', () => {
+    // A section declaring no regions still has children. An empty name is the
+    // shape a developer's `<ThemeRegion name={undefined as string} />` reaches
+    // here as, and resolving it onto the first region would place the wrong
+    // block in the wrong part of the markup.
+    expect(findRegionChild({ blocks: [search] }, '')).toBeNull();
+  });
+
+  it('takes the first match when a region row was duplicated', () => {
+    // Reachable only by duplicating a region row in the layer tree. Rendering
+    // both would put two `data-block-id` wrappers under one `<ThemeRegion>`,
+    // and the second is unreachable from the JSX either way.
+    const duplicate = regionBlock('search', { id: 'region-search-copy' });
+
+    expect(findRegionChild({ blocks: [search, duplicate] }, 'search')).toBe(
+      search
+    );
+  });
+
+  it('survives a container with no children at all', () => {
+    expect(findRegionChild({ blocks: [] }, 'search')).toBeNull();
+    expect(findRegionChild({}, 'search')).toBeNull();
+    expect(findRegionChild(null, 'search')).toBeNull();
+    expect(findRegionChild(undefined, 'search')).toBeNull();
+  });
+});

package/src/custom/__tests__/theme-editable.test.tsx

@@ -8,8 +8,8 @@ import { resetDevWarnCacheForTests } from '../../utils/dev-warn';
 
 const contextValue = (
   over: Partial<CustomBlockContextValue> = {}
-): CustomBlockContextValue => ({
-  block: {
+): CustomBlockContextValue => {
+  const block = {
     id: 'b1',
     type: 'custom:acme:promo-strip',
     label: 'Promo strip',
@@ -17,13 +17,21 @@ const contextValue = (
     styles: {},
     order: 0,
     hidden: false
-  },
-  placeholderId: 'header',
-  sectionId: 's1',
-  isDesigner: false,
-  currentBreakpoint: 'desktop',
-  ...over
-});
+  };
+
+  // `node` is what the helpers read and `block` is the compatibility alias;
+  // they are the SAME object here, which is what a block host provides.
+  return {
+    node: block,
+    scope: 'block',
+    block,
+    placeholderId: 'header',
+    sectionId: 's1',
+    isDesigner: false,
+    currentBreakpoint: 'desktop',
+    ...over
+  };
+};
 
 /** Renders inside a custom block whose properties are the merchant's values. */
 const renderInBlock = (
@@ -35,7 +43,11 @@ const renderInBlock = (
   const { properties, ...rest } = over;
   const value = contextValue(rest);
 
-  if (properties) value.block = { ...value.block, properties };
+  if (properties) {
+    const next = { ...value.block, properties };
+    value.block = next;
+    value.node = next;
+  }
 
   return render(
     <CustomBlockContext.Provider value={value}>