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

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

@@ -0,0 +1,331 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+
+// Stub the recursive ThemeBlock (default export) with a countable marker, the
+// same way theme-slot.test.tsx does — a region is only honest if the block it
+// hands over is the one that reaches the renderer.
+jest.mock('../../theme-block', () => ({
+  __esModule: true,
+  default: ({ block }: { block: { id: string } }) => (
+    <div data-testid="tb" data-id={block.id} />
+  )
+}));
+
+import { CustomBlockContext } from '../block-context';
+import type { CustomBlockContextValue } from '../block-context';
+import { REGION_NAME_PROPERTY } from '../section-types';
+import type { Block } from '../../theme-block';
+import { ThemeRegion } from '../theme-region';
+import { resetDevWarnCacheForTests } from '../../utils/dev-warn';
+
+/**
+ * A seeded region as the editor writes one: an ORDINARY block of a real type
+ * carrying the reserved name property. There is no wrapper node — the merchant
+ * opens this row and gets the `image`/`mini-basket` panel itself.
+ */
+const regionBlock = (name: string, over: Partial<Block> = {}): Block => ({
+  id: `region-${name}`,
+  type: 'image',
+  label: name,
+  value: '',
+  properties: { [REGION_NAME_PROPERTY]: name },
+  styles: {},
+  order: 0,
+  hidden: false,
+  ...over
+});
+
+const contextValue = ({
+  blocks,
+  isDesigner = false,
+  scope = 'section',
+  declaredRegionNames
+}: {
+  blocks?: Block[];
+  isDesigner?: boolean;
+  scope?: 'block' | 'section';
+  declaredRegionNames?: string[];
+} = {}): CustomBlockContextValue => {
+  const node = {
+    id: 'sec-1',
+    type:
+      scope === 'section' ? 'custom:acme:header' : 'custom:acme:promo-strip',
+    label: 'Header',
+    properties: {},
+    styles: {},
+    order: 0,
+    hidden: false,
+    blocks
+  };
+
+  // `node` is what the helpers read and `block` is the compatibility alias;
+  // they are the SAME object here, which is what a section host provides.
+  return {
+    node,
+    scope,
+    block: node as unknown as Block,
+    placeholderId: 'header',
+    sectionId: 'sec-1',
+    isDesigner,
+    currentBreakpoint: 'desktop',
+    ...(declaredRegionNames ? { declaredRegionNames } : {})
+  };
+};
+
+const renderRegion = (
+  value: CustomBlockContextValue | null,
+  region: React.ReactNode = <ThemeRegion name="search" />
+) =>
+  render(
+    value === null ? (
+      <>{region}</>
+    ) : (
+      <CustomBlockContext.Provider value={value}>
+        {region}
+      </CustomBlockContext.Provider>
+    )
+  );
+
+const markers = (container: HTMLElement) =>
+  Array.from(container.querySelectorAll('[data-testid="tb"]'));
+
+const bands = (container: HTMLElement) =>
+  Array.from(container.querySelectorAll('[data-theme-block-placeholder]'));
+
+beforeEach(() => {
+  resetDevWarnCacheForTests();
+});
+
+describe('ThemeRegion — the seeded block', () => {
+  it('renders it through ThemeBlock, where the JSX put the region', () => {
+    const { container } = renderRegion(
+      contextValue({ blocks: [regionBlock('search')] })
+    );
+
+    expect(markers(container).map((m) => m.getAttribute('data-id'))).toEqual([
+      'region-search'
+    ]);
+  });
+
+  it('places each declared region independently in one render', () => {
+    const { container } = renderRegion(
+      contextValue({
+        blocks: [regionBlock('search'), regionBlock('basket')],
+        declaredRegionNames: ['search', 'basket']
+      }),
+      <>
+        <ThemeRegion name="basket" />
+        <ThemeRegion name="search" />
+      </>
+    );
+
+    // The JSX owns the order, not the composition: `basket` is seeded second
+    // and rendered first, and no drag in the layer tree can change that.
+    expect(markers(container).map((m) => m.getAttribute('data-id'))).toEqual([
+      'region-basket',
+      'region-search'
+    ]);
+  });
+
+  it('never renders a merchant composed block for a region it does not carry', () => {
+    // The anti-slot-fallback invariant, from the component side. A section's
+    // direct children are the merchant's own blocks; a region that fell back
+    // to them would draw the entire section inside itself.
+    const { container } = renderRegion(
+      contextValue({
+        blocks: [
+          { ...regionBlock('search'), id: 'merchant-hero', properties: {} }
+        ],
+        isDesigner: true,
+        declaredRegionNames: ['search']
+      })
+    );
+
+    expect(markers(container)).toHaveLength(0);
+    expect(bands(container)).toHaveLength(1);
+  });
+});
+
+describe('ThemeRegion — a region the merchant deleted', () => {
+  it('draws a labelled band in the designer so the hole can be filled', () => {
+    const { container } = renderRegion(
+      contextValue({
+        blocks: [],
+        isDesigner: true,
+        declaredRegionNames: ['search']
+      }),
+      <ThemeRegion name="search" label="Store search" />
+    );
+
+    expect(bands(container)).toHaveLength(1);
+    expect(container.textContent).toContain('Store search');
+    expect(container.textContent).toContain('removed');
+  });
+
+  it('renders nothing at all on the live site', () => {
+    // Deleting a region is an ordinary composition edit and has to stay
+    // durable — a header whose store search was removed does not grow one back
+    // on the next load.
+    const { container } = renderRegion(
+      contextValue({ blocks: [], declaredRegionNames: ['search'] })
+    );
+
+    expect(container).toBeEmptyDOMElement();
+  });
+});
+
+describe('ThemeRegion — a hidden region block', () => {
+  it('renders nothing live and stays selectable in the designer', () => {
+    const blocks = [regionBlock('search', { hidden: true })];
+
+    const live = renderRegion(contextValue({ blocks }));
+    expect(live.container).toBeEmptyDOMElement();
+
+    // Emptiness is decided AFTER the child pipeline, not from the array
+    // length: the designer keeps hidden children mounted so the layer tree can
+    // still reach them, and both sides draw what they actually rendered.
+    const designer = renderRegion(contextValue({ blocks, isDesigner: true }));
+    expect(markers(designer.container)).toHaveLength(1);
+    expect(bands(designer.container)).toHaveLength(0);
+  });
+});
+
+describe('ThemeRegion — the same region placed twice', () => {
+  it('renders the seeded block once, not twice', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    const { container } = renderRegion(
+      contextValue({ blocks: [regionBlock('search')] }),
+      <>
+        <ThemeRegion name="search" />
+        <ThemeRegion name="search" />
+      </>
+    );
+
+    // Both resolve to the SAME block, so rendering both would answer one
+    // `data-block-id` with two wrappers and break selection on the canvas.
+    expect(markers(container)).toHaveLength(1);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('more than once')
+    );
+
+    warn.mockRestore();
+  });
+
+  it('explains itself on the designer canvas rather than going blank', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    const { container } = renderRegion(
+      contextValue({ blocks: [regionBlock('search')], isDesigner: true }),
+      <>
+        <ThemeRegion name="search" />
+        <ThemeRegion name="search" />
+      </>
+    );
+
+    expect(markers(container)).toHaveLength(1);
+    expect(bands(container)).toHaveLength(1);
+    expect(container.textContent).toContain('Duplicate region');
+
+    warn.mockRestore();
+  });
+});
+
+describe('ThemeRegion — placed where it cannot resolve', () => {
+  it('renders nothing outside a custom section and says so', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    const { container } = renderRegion(null);
+
+    expect(container).toBeEmptyDOMElement();
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('outside a custom section')
+    );
+
+    warn.mockRestore();
+  });
+
+  it('refuses a custom BLOCK with a designer band and nothing live', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    // A block's children are its slot nodes and its merchant content; a region
+    // resolved against them would either find nothing or match a child that
+    // happens to carry the reserved property.
+    const designer = renderRegion(
+      contextValue({
+        scope: 'block',
+        blocks: [regionBlock('search')],
+        isDesigner: true
+      })
+    );
+
+    expect(markers(designer.container)).toHaveLength(0);
+    expect(bands(designer.container)).toHaveLength(1);
+    expect(designer.container.textContent).toContain(
+      'only works inside a custom section'
+    );
+    // The message has to name the thing the developer actually wanted: a
+    // merchant-fillable opening inside a block is a slot.
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('<ThemeSlot />'));
+
+    const live = renderRegion(
+      contextValue({ scope: 'block', blocks: [regionBlock('search')] })
+    );
+
+    expect(live.container).toBeEmptyDOMElement();
+
+    warn.mockRestore();
+  });
+
+  it('refuses a name the editor could never have seeded', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    const { container } = renderRegion(
+      contextValue({ blocks: [regionBlock('search')] }),
+      <ThemeRegion name="Store Search" />
+    );
+
+    expect(container).toBeEmptyDOMElement();
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('"Store Search" is not valid')
+    );
+
+    warn.mockRestore();
+  });
+
+  it('warns on a name the section never declared, naming the ones it did', () => {
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    // A typo and a merchant deletion look identical on screen — both are an
+    // empty band. Only the declaration tells them apart, and a developer
+    // staring at the band has nothing else to go on.
+    renderRegion(
+      contextValue({
+        blocks: [regionBlock('search')],
+        declaredRegionNames: ['search', 'basket']
+      }),
+      <ThemeRegion name="baskett" />
+    );
+
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('places a region "baskett" it never declared')
+    );
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('Declared: search, basket')
+    );
+
+    warn.mockRestore();
+  });
+});

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

@@ -55,8 +55,8 @@ const contextValue = ({
   isDesigner?: boolean;
   slotSink?: (descriptor: CustomSlotDescriptor) => void;
   declaredSlotNames?: string[];
-} = {}): CustomBlockContextValue => ({
-  block: {
+} = {}): CustomBlockContextValue => {
+  const block = {
     id: 'b1',
     type: 'custom:acme:promo-strip',
     label: 'Promo strip',
@@ -65,14 +65,22 @@ const contextValue = ({
     order: 0,
     hidden: false,
     blocks
-  },
-  placeholderId: 'p',
-  sectionId: 's',
-  isDesigner,
-  currentBreakpoint: 'desktop',
-  ...(declaredSlotNames ? { declaredSlotNames } : {}),
-  ...(slotSink ? { collect: { setting: jest.fn(), slot: slotSink } } : {})
-});
+  };
+
+  // `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: 'p',
+    sectionId: 's',
+    isDesigner,
+    currentBreakpoint: 'desktop',
+    ...(declaredSlotNames ? { declaredSlotNames } : {}),
+    ...(slotSink ? { collect: { setting: jest.fn(), slot: slotSink } } : {})
+  };
+};
 
 const renderSlot = (
   value: CustomBlockContextValue | null,

package/src/custom/__tests__/use-theme-setting.test.tsx

@@ -17,8 +17,8 @@ const contextValue = ({
   properties?: Record<string, unknown>;
   currentBreakpoint?: string;
   sink?: SettingSink;
-} = {}): CustomBlockContextValue => ({
-  block: {
+} = {}): CustomBlockContextValue => {
+  const block = {
     id: 'b1',
     type: 'custom:acme:promo-strip',
     label: 'Promo strip',
@@ -26,13 +26,21 @@ const contextValue = ({
     styles: {},
     order: 0,
     hidden: false
-  },
-  placeholderId: 'p',
-  sectionId: 's',
-  isDesigner: false,
-  currentBreakpoint,
-  ...(sink ? { collect: { setting: sink, slot: jest.fn() } } : {})
-});
+  };
+
+  // `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: 'p',
+    sectionId: 's',
+    isDesigner: false,
+    currentBreakpoint,
+    ...(sink ? { collect: { setting: sink, slot: jest.fn() } } : {})
+  };
+};
 
 const wrapperFor = (value: CustomBlockContextValue | null) => {
   const Wrapper = ({ children }: { children: React.ReactNode }) =>

package/src/custom/block-context.ts

@@ -2,13 +2,25 @@
 
 import { createContext, useContext } from 'react';
 import type { Block } from '../theme-block';
+import type { Section } from '../theme-section';
 import type {
   CustomSettingDescriptor,
   CustomSlotDescriptor
 } from './types';
 
 /**
- * What `ThemeEditable`, `useThemeSetting` and `ThemeSlot` read.
+ * The composition node a custom unit renders from.
+ *
+ * A `Block` for a custom block, the `Section` itself for a custom section. The
+ * two shapes agree on everything the authoring helpers read — `properties` for
+ * settings and fields, `blocks` for slots and regions — which is why one
+ * context serves both instead of a second one that would have to be threaded
+ * through `ThemeSlot`, `ThemeEditable` and `useThemeSetting` in parallel.
+ */
+export type CustomNode = Block | Section;
+
+/**
+ * What `ThemeEditable`, `useThemeSetting`, `ThemeSlot` and `ThemeRegion` read.
  *
  * A context rather than props, because the whole point of the authoring model
  * is that a developer writes ordinary JSX. Threading `block`/`breakpoint`
@@ -16,6 +28,31 @@ import type {
  * down would be the tax this API exists to remove.
  */
 export interface CustomBlockContextValue {
+  /**
+   * The node this unit renders. READ THIS, not `block` below.
+   *
+   * For a custom block it is the block; for a custom section it is the section,
+   * whose `properties` hold the section's settings and whose `blocks` hold the
+   * seeded regions.
+   */
+  node: CustomNode;
+  /**
+   * Which kind of unit is rendering.
+   *
+   * `ThemeRegion` refuses to render outside a section, because a region resolves
+   * against `section.blocks` — inside a block it would either find nothing or,
+   * worse, match a child that happens to carry the reserved property.
+   */
+  scope: 'block' | 'section';
+  /**
+   * The same object as `node`, kept because brand code already reads it.
+   *
+   * A `Section` satisfies `Block` structurally (it carries every required
+   * field), so this stays type-correct for a section host too. New code should
+   * read `node`: the name is honest there, and a reader that reaches for a
+   * Block-only field like `value` or `isIterator` is then visibly wrong instead
+   * of quietly undefined.
+   */
   block: Block;
   placeholderId: string;
   sectionId: string;
@@ -23,9 +60,9 @@ export interface CustomBlockContextValue {
   currentBreakpoint: string;
   selectedBlockId?: string | null;
   /**
-   * The slot names `defineCustomBlock` DECLARED, in declaration order, so a
-   * bare `<ThemeSlot />` can resolve to the block's single slot whatever it is
-   * called.
+   * The slot names `defineCustomBlock`/`defineCustomSection` DECLARED, in
+   * declaration order, so a bare `<ThemeSlot />` can resolve to the unit's
+   * single slot whatever it is called.
    *
    * From the definition and not from the catalog descriptor, which is the
    * whole reason it is threaded here. The descriptor's `slots` array is
@@ -36,7 +73,13 @@ export interface CustomBlockContextValue {
    */
   declaredSlotNames?: readonly string[];
   /**
-   * Runtime collection sink. Present only while the block is rendering inside
+   * The region names the section DECLARED. `ThemeRegion` uses it for one thing
+   * only: telling a merchant's deletion (ordinary, durable, silent) apart from
+   * a developer typo (a name nothing was ever seeded for, worth a warning).
+   */
+  declaredRegionNames?: readonly string[];
+  /**
+   * Runtime collection sink. Present only while the unit is rendering inside
    * a host that is collecting — see `collect.ts`. The build-time extractor is
    * the authoritative source of the descriptor; this is the fallback that
    * makes the API work before the extractor exists, and the cross-check that
@@ -52,12 +95,12 @@ export const CustomBlockContext =
   createContext<CustomBlockContextValue | null>(null);
 
 /**
- * Returns null outside a custom block rather than throwing.
+ * Returns null outside a custom block or section rather than throwing.
  *
- * The three public components have to say something useful when a developer
- * uses them in the wrong place — a plain React tree, a built-in block, a unit
- * test. Each handles the null itself with a named message; a bare throw here
- * would surface as a stack trace pointing at this file rather than at the
+ * The public components have to say something useful when a developer uses
+ * them in the wrong place — a plain React tree, a built-in block, a unit test.
+ * Each handles the null itself with a named message; a bare throw here would
+ * surface as a stack trace pointing at this file rather than at the
  * `<ThemeEditable>` the developer actually mis-placed.
  */
 export const useCustomBlockContext = (): CustomBlockContextValue | null =>

package/src/custom/block-host.tsx

@@ -29,8 +29,15 @@ interface CustomBlockErrorBoundaryProps {
  * 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.
+ *
+ * Exported because `section-host.tsx` uses the SAME boundary rather than a
+ * second copy. A section host has no lower level to fall back to, so the
+ * boundary buys it a labelled designer card rather than blast-radius reduction
+ * — but a diverged copy would be a second place for the live/designer split to
+ * be got wrong, and getting it wrong live means shipping a broken card to
+ * shoppers.
  */
-class CustomBlockErrorBoundary extends React.Component<
+export class CustomBlockErrorBoundary extends React.Component<
   CustomBlockErrorBoundaryProps,
   { hasError: boolean }
 > {
@@ -122,6 +129,11 @@ export const CustomBlockHost = ({
 
   const value = useMemo<CustomBlockContextValue>(
     () => ({
+      // `node` and `block` are the same object here. The pair exists so a
+      // section host can fill `node` with the section while brand code that
+      // already reads `block` keeps working — see `block-context.ts`.
+      node: block,
+      scope: 'block',
       block,
       placeholderId,
       sectionId,

package/src/custom/collect.ts

@@ -1,5 +1,6 @@
 import { devWarn } from '../utils/dev-warn';
 import { getCustomBlockDescriptor } from './catalog';
+import { getCustomSectionDescriptor } from './section-catalog';
 import { fieldPartName } from './editable-tags';
 import { slotNameError } from './slot-nodes';
 import {
@@ -141,6 +142,19 @@ export interface CustomCollectSink {
   slot: (descriptor: CustomSlotDescriptor) => void;
 }
 
+/**
+ * What a sink writes into. Both `CustomBlockDescriptor` and
+ * `CustomSectionDescriptor` satisfy it, which is what lets one sink serve
+ * either — declared structurally rather than as a union so a third descriptor
+ * shape would not have to be added here as well.
+ */
+interface CollectTarget {
+  settings: CustomSettingDescriptor[];
+  slots: CustomSlotDescriptor[];
+  parts: string[];
+  hasChildren: boolean;
+}
+
 const sinks = new Map<string, CustomCollectSink>();
 const finished = new Set<string>();
 
@@ -187,15 +201,22 @@ export const getCollectSink = (type: string): CustomCollectSink => {
   const existing = sinks.get(type);
   if (existing) return existing;
 
-  const targetDescriptor = () => {
-    const descriptor = getCustomBlockDescriptor(type);
+  // Blocks and sections share one type namespace — registration refuses a type
+  // already claimed by either — so one lookup order is unambiguous and a sink
+  // can serve both. The shapes agree on everything this file writes: settings,
+  // slots and parts. `hasChildren` is on both too, so the slot sink needs no
+  // branch of its own.
+  const targetDescriptor = (): CollectTarget | undefined => {
+    const descriptor: CollectTarget | undefined =
+      getCustomBlockDescriptor(type) ?? getCustomSectionDescriptor(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.`
+          `It registered into a different module copy than the one rendering it: check that the ` +
+          `barrel calling registerCustomBlocks()/registerCustomSections() is imported from the ` +
+          `CLIENT ROOT, and clear .next — webpack keeps serving the old copy of a changed package.`
       );
     }
     return descriptor;