@akinon/pz-theme 2.0.78-rc.2 → 2.0.79-beta.0

package/src/hooks/use-designer-features.tsx

@@ -52,6 +52,47 @@ export function postBlockSelection({
   });
 }
 
+/**
+ * The SECTION's own part under a click, or undefined.
+ *
+ * The section twin of the block resolution inside `handleClick` below, and it
+ * lives in this file for a reason a test enforces: `checkout-hosted-parts.test.ts`
+ * refuses a `[data-part]` query anywhere in pz-theme outside the three
+ * designer-only modules, because those attributes are a STYLING contract and
+ * nothing on the live path may branch on them. This module is one of the three.
+ * Section-wrapper is not — it renders on the storefront too — so the query
+ * belongs here and the wrapper calls it from inside its own designer gate.
+ *
+ * TWO GUARDS, and the second is the one that matters.
+ *
+ * The walk stops at the section: a `data-part` above it belongs to something
+ * else entirely.
+ *
+ * And a part inside a composed CHILD is not the section's to report. The
+ * generated rule for a section part carries an ownership guard —
+ * `:not(:where(<scope> [data-block-id] *))` — so opening a panel for a part
+ * inside a block would offer controls whose CSS can never match, which is the
+ * "it saves and nothing moves" failure this whole feature is written against.
+ * The check is deliberately `parentElement?.closest(...)`, i.e. STRICTLY
+ * between: the CSS guard uses a descendant combinator, so an element carrying
+ * both `data-block-id` and `data-part` is still matched by the section's rule
+ * and is legitimately reportable.
+ */
+export function resolveSectionPartName(
+  target: Element | null,
+  sectionElement: Element
+): string | undefined {
+  const partElement = target?.closest('[data-part]');
+  if (!partElement || !sectionElement.contains(partElement)) return undefined;
+
+  const enclosingBlock = partElement.parentElement?.closest('[data-block-id]');
+  if (enclosingBlock && sectionElement.contains(enclosingBlock)) {
+    return undefined;
+  }
+
+  return partElement.getAttribute('data-part') || undefined;
+}
+
 export function useDesignerFeatures({
   blockId,
   placeholderId,

package/src/index.ts

@@ -36,6 +36,12 @@ export {
   SCROLL_STATE_THRESHOLD,
   SCROLL_STYLE_STATE
 } from './chrome/scroll-state';
+export {
+  CHROME_MODE_ATTRIBUTE,
+  CHROME_MODE_DOCKED,
+  setChromeMode
+} from './chrome/chrome-mode';
+export type { ChromeMode } from './chrome/chrome-mode';
 export { PreviewAuthStateReporter } from './chrome/preview-auth-state';
 export { LiveBasketPageContext } from './chrome/live-basket-page-context';
 export { LiveWishlistPageContext } from './chrome/live-wishlist-page-context';
@@ -171,17 +177,26 @@ export type { CheckoutPieceKey } from './chrome/checkout-pieces';
 // mirror the grammar rather than re-deriving it.
 export {
   defineCustomBlock,
+  defineCustomSection,
   registerCustomBlocks,
+  registerCustomSections,
   ThemeEditable,
+  ThemeRegion,
   ThemeSlot,
   useThemeSetting,
   getCustomCatalog,
+  getCustomSectionCatalog,
   isCustomThemeType,
   CUSTOM_TYPE_PREFIX,
   CUSTOM_SLOT_BLOCK_TYPE,
   SLOT_NAME_PROPERTY,
   isSlotNode,
-  slotNodeName
+  slotNodeName,
+  REGION_NAME_PROPERTY,
+  CUSTOM_SECTION_LIMITS,
+  findRegionChild,
+  isRegionNode,
+  regionNodeName
 } from './custom';
 export type {
   CustomBlockComponent,
@@ -192,6 +207,14 @@ export type {
   CustomCatalog,
   CustomPartDeclaration,
   CustomPartsDeclaration,
+  CustomRegionDeclaration,
+  CustomRegionDescriptor,
+  CustomSectionCatalog,
+  CustomSectionComponent,
+  CustomSectionDefinition,
+  CustomSectionDescriptor,
+  CustomSectionInput,
+  CustomSectionOptions,
   CustomSettingDeclaration,
   CustomSettingDescriptor,
   CustomSettingOption,
@@ -200,6 +223,7 @@ export type {
   EditableKind,
   PropertyType,
   ThemeEditableProps,
+  ThemeRegionProps,
   ThemeSettingChoice,
   ThemeSettingOptions,
   ThemeSlotProps

package/src/placeholder-registry.ts

@@ -1,4 +1,6 @@
-import { getCustomCatalog } from './custom/catalog';
+import { getCatalogVendor, getCustomCatalog } from './custom/catalog';
+import { getCustomSectionCatalog } from './custom/section-catalog';
+import type { CustomSectionCatalog } from './custom/section-types';
 import type { CustomCatalog } from './custom/types';
 import { isTrustedEditorEvent, postToEditor } from './editor-bridge';
 
@@ -33,6 +35,23 @@ interface PlaceholdersAvailablePayload {
    * nothing can render.
    */
   customBlocks?: CustomCatalog;
+  /**
+   * The section catalog, on the same terms as `customBlocks` and as a SIBLING
+   * of it rather than a key inside it.
+   *
+   * Nesting would have been cheaper here and much more expensive everywhere
+   * else: the editor validates `customBlocks` element by element and drops the
+   * WHOLE value on an unexpected shape, so an editor build older than this
+   * change would answer a catalog carrying sections by emptying the brand's
+   * block palette. A sibling key is simply ignored by an older receiver, and a
+   * new field on an existing message needs no `@akinon/theme-contract` publish
+   * — `parseThemeMessage` validates the envelope, not the payload.
+   *
+   * A sibling also means a separate byte budget on both sides, which is what
+   * keeps one oversized section descriptor from taking the block palette down
+   * with it.
+   */
+  customSections?: CustomSectionCatalog;
 }
 
 const isFramed = (): boolean =>
@@ -81,6 +100,9 @@ const flush = () => {
     // must be indistinguishable from one whose catalog simply is not this
     // frame's business.
     if (customBlocks) data.customBlocks = customBlocks;
+
+    const customSections = getCustomSectionCatalog(getCatalogVendor());
+    if (customSections) data.customSections = customSections;
   }
 
   postToEditor({
@@ -126,10 +148,17 @@ const handleEditorMessage = (event: MessageEvent) => {
   if (designerReannounceSpent) return;
   designerReannounceSpent = true;
 
-  // A build that registers no custom block has nothing to add to a frame it
-  // has already sent, so it stays at exactly one announce — the behaviour
-  // every brand shipping no custom block had before any of this existed.
-  if (!getCustomCatalog()) return;
+  // A build that registers nothing developer-authored has nothing to add to a
+  // frame it has already sent, so it stays at exactly one announce — the
+  // behaviour every brand shipping neither had before any of this existed.
+  //
+  // BOTH catalogs, not just the block one: a brand that ships only custom
+  // sections would otherwise never get its second frame, and its section band
+  // would be empty on exactly the loads where the cookie handshake lost the
+  // 100ms debounce — intermittently, and invisibly.
+  if (!getCustomCatalog() && !getCustomSectionCatalog(getCatalogVendor())) {
+    return;
+  }
 
   // Re-arm rather than flush: the flag itself is set by the placeholder
   // client's own listener, and listener order across modules is not ours to

package/src/sections/__tests__/custom-renderer-section-types.test.ts

@@ -68,3 +68,32 @@ describe('hasCustomSectionRenderer', () => {
     ).toBe(true);
   });
 });
+
+describe('hasCustomSectionRenderer — a developer-authored section', () => {
+  it('is true for a brand section type, decided by grammar alone', () => {
+    // No registry is consulted, and none can be: `registerCustomSections` is
+    // client-only, so the SERVER copy of any registry is permanently empty
+    // while this module is read by the server-side CSS generator. The same
+    // generator then runs again on the client, which would emit a DIFFERENT
+    // stylesheet for the same page — with the client `<style>` winning by
+    // source order. The grammar is identical in both.
+    expect(hasCustomSectionRenderer(section({ type: 'custom:acme:hero' }))).toBe(
+      true
+    );
+    expect(
+      hasCustomSectionRenderer(section({ type: 'custom:zsazsazsu:header' }))
+    ).toBe(true);
+  });
+
+  it('is false for every string that merely looks like one', () => {
+    // A half-typed or mis-cased type must fall back to the generic loop rather
+    // than being handed a box nothing draws: `ownsContentBox` decides where the
+    // child-layout keys land, so a wrong answer here silently re-lays-out the
+    // section.
+    ['custom:', 'custom:acme', 'custom:acme:', 'Custom:Acme:Hero'].forEach(
+      (type) => {
+        expect(hasCustomSectionRenderer(section({ type }))).toBe(false);
+      }
+    );
+  });
+});

package/src/sections/__tests__/section-part-selection.test.tsx

@@ -0,0 +1,277 @@
+import React from 'react';
+import { fireEvent, render } from '@testing-library/react';
+
+import SectionWrapper from '../section-wrapper';
+import ThemeSection from '../../theme-section';
+import type { Section } from '../../theme-section';
+import { ThemeSettingsProvider } from '../../theme-settings-context';
+import { postToEditor } from '../../editor-bridge';
+
+// `isTrustedEditorEvent` rides along because the wrapper's SCROLL_TO_SECTION
+// listener imports it from the same module this mock replaces.
+jest.mock('../../editor-bridge', () => ({
+  postToEditor: jest.fn(),
+  isTrustedEditorEvent: jest.fn(() => false)
+}));
+
+jest.mock('../../components/action-toolbar', () => ({
+  __esModule: true,
+  default: () => <div data-testid="action-toolbar" />
+}));
+
+// The recursive block renderer, stubbed so a composed child is one assertable
+// node instead of the whole block registry.
+jest.mock('../../theme-block', () => ({
+  __esModule: true,
+  default: ({ block }: { block: { id: string } }) => (
+    <div data-block-id={block.id} data-testid="composed-block">
+      <span data-part="title" data-testid="block-part">
+        block title
+      </span>
+    </div>
+  )
+}));
+
+const postToEditorMock = postToEditor as jest.Mock;
+
+/**
+ * A CLICK ON A SECTION'S OWN BAND MUST OPEN THAT BAND'S PANEL.
+ *
+ * The editor has always been able to receive it — `theme-iframe-service`
+ * destructures `partName` off SELECT_SECTION and the properties panel opens
+ * the part panel — but no pz-theme sender ever put the field on the message.
+ * A developer-authored header therefore advertised six bands (`bar`,
+ * `topRow`, `logoArea`, `leftActions`, `actions`, `navRow`) and a click on any
+ * of them selected the section ROOT, leaving the merchant to guess which of
+ * the six names was the band under the cursor. The identical click inside a
+ * BLOCK already opened its part panel.
+ *
+ * Three properties are locked here, each a real failure mode:
+ *
+ * - BOUNDED WALK: resolution stops at the section. A `[data-part]` above it
+ *   belongs to something else.
+ * - BLOCK PARTS ARE NOT SECTION PARTS: the generated section part rule carries
+ *   `:not(:where(<section> [data-block-id] *))` (buildOwnershipGuard in
+ *   utils/part-styles.ts), so naming a part from inside a composed child would
+ *   open a panel whose every control writes CSS that can never match.
+ * - OMITTED, NOT EMPTY: with no part, an ordinary section click posts a
+ *   payload byte-identical to the one sent before this existed.
+ */
+
+const makeSection = (overrides: Partial<Section> = {}): Section => ({
+  id: 'sec-1',
+  type: 'generic-section',
+  name: 'name',
+  label: 'My Section',
+  properties: {},
+  styles: {},
+  blocks: [],
+  order: 0,
+  hidden: false,
+  ...overrides
+});
+
+const lastSelectSectionPayload = () => {
+  const call = [...postToEditorMock.mock.calls]
+    .reverse()
+    .find(([message]) => message?.type === 'SELECT_SECTION');
+
+  return call?.[0]?.data as Record<string, unknown> | undefined;
+};
+
+beforeEach(() => {
+  postToEditorMock.mockClear();
+});
+
+describe('SectionWrapper — part resolution on a section click', () => {
+  const renderWrapper = (children: React.ReactNode) =>
+    render(
+      <SectionWrapper
+        section={makeSection()}
+        placeholderId="header"
+        isDesigner
+        onSelect={jest.fn()}
+      >
+        {children}
+      </SectionWrapper>
+    );
+
+  it('reports the part-stamped band the click landed on', () => {
+    const { getByTestId } = renderWrapper(
+      <header data-part="bar">
+        <div data-part="topRow" data-testid="top-row">
+          <span>ZSA</span>
+        </div>
+      </header>
+    );
+
+    fireEvent.click(getByTestId('top-row'));
+
+    expect(lastSelectSectionPayload()).toEqual({
+      placeholderId: 'header',
+      sectionId: 'sec-1',
+      partName: 'topRow'
+    });
+  });
+
+  it('reports the NEAREST band, not the outermost one', () => {
+    const { getByTestId } = renderWrapper(
+      <header data-part="bar">
+        <div data-part="topRow">
+          <div data-part="logoArea">
+            <span data-testid="logo-text">ZSA</span>
+          </div>
+        </div>
+      </header>
+    );
+
+    fireEvent.click(getByTestId('logo-text'));
+
+    expect(lastSelectSectionPayload()?.partName).toBe('logoArea');
+  });
+
+  it('omits the partName KEY entirely on a bare section click', () => {
+    const { container } = renderWrapper(<span>plain content</span>);
+
+    fireEvent.click(container.querySelector('[data-section-id]') as Element);
+
+    const payload = lastSelectSectionPayload();
+    // Not `toBeUndefined()`: the key must be ABSENT, so the frame stays
+    // byte-identical to what an ordinary section click always posted.
+    expect(payload).toEqual({ placeholderId: 'header', sectionId: 'sec-1' });
+    expect(payload && 'partName' in payload).toBe(false);
+  });
+
+  it('omits partName for a part inside a nested block', () => {
+    const { getByTestId } = renderWrapper(
+      <div data-part="actions">
+        <div data-block-id="blk-1">
+          <span data-part="title" data-testid="nested-part">
+            Basket
+          </span>
+        </div>
+      </div>
+    );
+
+    fireEvent.click(getByTestId('nested-part'));
+
+    const payload = lastSelectSectionPayload();
+    expect(payload && 'partName' in payload).toBe(false);
+    // And it must not fall back to the enclosing band either: the click was
+    // not on `actions`, so answering with it would style the wrong element.
+    expect(payload).toEqual({ placeholderId: 'header', sectionId: 'sec-1' });
+  });
+
+  it('omits partName for unstamped markup inside a nested block', () => {
+    // The case the guard exists for: a block renders markup its own click
+    // handler does not cover, so the click reaches the section handler.
+    const { getByTestId } = renderWrapper(
+      <div data-part="actions">
+        <div data-block-id="blk-1">
+          <span data-part="row">
+            <em data-testid="deep-node">x</em>
+          </span>
+        </div>
+      </div>
+    );
+
+    fireEvent.click(getByTestId('deep-node'));
+
+    expect(lastSelectSectionPayload()).toEqual({
+      placeholderId: 'header',
+      sectionId: 'sec-1'
+    });
+  });
+
+  it('still reports a part stamped on a block ROOT, matching the CSS guard', () => {
+    // `buildOwnershipGuard` excludes `<section> [data-block-id] *` —
+    // DESCENDANTS of a block, not the block element itself. An element
+    // carrying both attributes is still matched by the section part rule, so
+    // reporting it opens a panel whose writes do apply.
+    const { getByTestId } = renderWrapper(
+      <div data-block-id="blk-1" data-part="bar" data-testid="block-root" />
+    );
+
+    fireEvent.click(getByTestId('block-root'));
+
+    expect(lastSelectSectionPayload()?.partName).toBe('bar');
+  });
+
+  it('omits partName for an empty data-part value', () => {
+    const { getByTestId } = renderWrapper(
+      <div data-part="" data-testid="blank-part" />
+    );
+
+    fireEvent.click(getByTestId('blank-part'));
+
+    expect(lastSelectSectionPayload()).toEqual({
+      placeholderId: 'header',
+      sectionId: 'sec-1'
+    });
+  });
+
+  it('posts nothing at all when not in designer mode', () => {
+    const { getByTestId } = render(
+      <SectionWrapper section={makeSection()} placeholderId="header">
+        <div data-part="topRow" data-testid="top-row" />
+      </SectionWrapper>
+    );
+
+    fireEvent.click(getByTestId('top-row'));
+
+    expect(postToEditorMock).not.toHaveBeenCalled();
+  });
+});
+
+describe('ThemeSection generic path — same resolution on its own section', () => {
+  const renderGeneric = (section: Section) =>
+    render(
+      <ThemeSettingsProvider value={null}>
+        <ThemeSection
+          section={section}
+          placeholderId="home"
+          currentBreakpoint="desktop"
+          isDesigner
+          onSelect={jest.fn()}
+        />
+      </ThemeSettingsProvider>
+    );
+
+  it('omits the partName key on a bare section click', () => {
+    const { container } = renderGeneric(makeSection({ id: 'gen-1' }));
+
+    fireEvent.click(
+      container.querySelector('[data-section-id="gen-1"]') as Element
+    );
+
+    expect(lastSelectSectionPayload()).toEqual({
+      placeholderId: 'home',
+      sectionId: 'gen-1'
+    });
+  });
+
+  it('omits partName for a part inside one of its composed blocks', () => {
+    const { getByTestId } = renderGeneric(
+      makeSection({
+        id: 'gen-2',
+        blocks: [
+          {
+            id: 'blk-1',
+            type: 'text',
+            label: 'Text',
+            value: '',
+            properties: {},
+            styles: {},
+            order: 0,
+            hidden: false
+          }
+        ] as unknown as Section['blocks']
+      })
+    );
+
+    fireEvent.click(getByTestId('block-part'));
+
+    const payload = lastSelectSectionPayload();
+    expect(payload && 'partName' in payload).toBe(false);
+  });
+});

package/src/sections/custom-renderer-section-types.ts

@@ -1,3 +1,5 @@
+import { isCustomThemeType } from '../custom/types';
+
 /**
  * The section types that render through their own component instead of the
  * generic block loop, as plain data.
@@ -47,5 +49,22 @@ export const hasCustomSectionRenderer = (section: {
 }): boolean => {
   if (section.blocks?.some((block) => block.type === 'tab')) return true;
 
+  // A developer-authored section draws its own box, exactly as a registered
+  // renderer does, so its child-layout keys belong on the band rather than
+  // being moved onto the content wrapper.
+  //
+  // ANSWERED BY GRAMMAR, NEVER BY LOOKUP. Registration is client-only and this
+  // module is read by the SERVER-side CSS generator, so the server copy of any
+  // registry is permanently empty — and the same generator runs again on the
+  // client, which would then emit a DIFFERENT stylesheet for the same page,
+  // with the client's `<style>` winning by source order. The grammar is
+  // identical in both.
+  //
+  // Imported from `../custom/types`, NEVER from `../custom`: the barrel
+  // re-exports `register.ts`, which carries 'use client' and drags ~99 block
+  // modules into whatever graph imports it. `types.ts` is directive-free and
+  // its only import is a type.
+  if (isCustomThemeType(section.type)) return true;
+
   return CUSTOM_RENDERER_SECTION_TYPES.includes(section.type ?? '');
 };

package/src/sections/section-wrapper.tsx

@@ -8,6 +8,9 @@ import { Section } from '../theme-section';
 import { SECTION_CONTENT_ATTRIBUTE } from '../utils/section-content-width';
 
 import { isTrustedEditorEvent, postToEditor } from '../editor-bridge';
+import { resolveSectionPartName } from '../hooks/use-designer-features';
+
+
 interface SectionWrapperProps {
   section: Section;
   placeholderId: string;
@@ -90,12 +93,20 @@ export default function SectionWrapper({
       e.stopPropagation();
       onSelect(section.id);
 
+      const partName = resolveSectionPartName(
+        e.target as Element | null,
+        e.currentTarget as Element
+      );
+
       if (window.parent) {
         postToEditor({
           type: 'SELECT_SECTION',
           data: {
             placeholderId,
-            sectionId: section.id
+            sectionId: section.id,
+            // Omitted rather than sent empty, so an ordinary section click
+            // posts exactly the payload it always has.
+            ...(partName ? { partName } : {})
           }
         });
       }