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

package/src/custom/README-sections.md

@@ -0,0 +1,289 @@
+# Custom sections
+
+A brand developer writes a whole **area** — a header, a footer, eventually a
+product detail page — in their own repo, names the children that go inside it,
+and hands each one to the merchant as an ordinary composed block. The section
+appears in the theme editor's Add Section band under **Brand sections**.
+
+Read [`README.md`](./README.md) first. Everything about `ThemeEditable`,
+`useThemeSetting`, `ThemeSlot`, `partAttrs` and the limits works identically
+inside a section; this file is only the difference.
+
+## When a section instead of a block
+
+A block, because it is dropped into a section the merchant created, gets the
+near-bare block-root panel and lives inside a wrapper the merchant can put a
+`transform` on — which traps a `position: fixed` descendant, measured once as a
+1247px header collapsing to 600px.
+
+A section root gets the geometry family (`position`, `display`, `height`,
+`max-height`, `z-index`, `grid-template-columns`) and Content Width, and there
+is no wrapper left to spring the trap.
+
+**Rule of thumb:** if the thing you are writing owns its own band on the page,
+write a section. If it is one element inside a band the merchant composed,
+write a block.
+
+## The shape
+
+```tsx
+'use client';
+
+import {
+  defineCustomSection,
+  partAttrs,
+  ThemeRegion,
+  ThemeSlot
+} from '@akinon/pz-theme/src/custom';
+
+function StoreHeader() {
+  return (
+    <header {...partAttrs('bar')}>
+      <div {...partAttrs('row')}>
+        <ThemeRegion name="logo" label="Logo" />
+
+        <nav {...partAttrs('actions')}>
+          <ThemeRegion name="search" label="Search" />
+          <ThemeRegion name="basket" label="Basket" />
+          <ThemeSlot name="extras" label="Extra header actions" />
+        </nav>
+      </div>
+    </header>
+  );
+}
+
+export default defineCustomSection(StoreHeader, {
+  label: 'Store header',
+  placeholders: ['header'],
+
+  regions: [
+    { name: 'logo', label: 'Logo', block: 'image', value: '/logo.svg' },
+    { name: 'search', label: 'Search', block: 'search-box' },
+    { name: 'basket', label: 'Basket', block: 'mini-basket' }
+  ],
+
+  slots: [{ name: 'extras', label: 'Extra header actions' }],
+
+  parts: ['bar', 'row', 'actions'],
+
+  styles: {
+    position: { desktop: 'fixed' },
+    inset: { desktop: '0 0 auto 0' },
+    'background-color': { desktop: 'transparent' },
+    ':scrolled/background-color': { desktop: '#000000' }
+  },
+
+  lockRootTransforms: true
+});
+```
+
+Then, from the **client root only**:
+
+```ts
+registerCustomSections('acme', { header: StoreHeader });
+```
+
+## `ThemeRegion` — the one genuinely new piece
+
+A region is a child you named, chose the type of, and placed. Declaring
+`{ name: 'search', block: 'search-box' }` is what buys the whole search-box
+panel: its settings, its shared controls, the 161 advanced CSS controls and its
+part groups. You write no descriptor for it.
+
+The merchant can style it, configure it, hide it and delete it. They **cannot**
+reorder it or insert beside it — your JSX owns the layout, and no drag in the
+layer tree changes where it renders.
+
+`properties`, `styles` and `value` on a region are a **seed**: what it looks
+like the moment the section is added. They are written once, at insert, and
+nothing re-applies them, so a merchant's edit is never quietly reverted.
+`value` is there for the block types that keep their content there rather than
+in `properties` — an `image` reads `block.value` for its src.
+
+**A deleted region draws a labelled band in the designer and nothing at all
+live.** That is not an error state: deleting is an ordinary composition edit and
+has to stay durable. Regions are seeded once, at insert; the editor lists every
+absent one under the section with an **Add back** control, so a deletion is
+reversible without being undone behind the merchant's back.
+
+**There is no unnamed region.** A bare `<ThemeSlot />` resolves to a block's
+single slot; a region has no such fallback, because a section's direct children
+are the merchant's own composed blocks and a nameless region would swallow all
+of them.
+
+## Region or slot
+
+| | Region | Slot |
+|---|---|---|
+| Who chooses the block type | you | the merchant |
+| Who chooses where it renders | you | you choose where the slot is |
+| How many blocks | exactly one | any number |
+| Merchant can reorder | no | yes, inside the slot |
+| Merchant can delete | yes, and it stays deleted (Add back restores it) | the row itself, no |
+
+## Commerce data
+
+Two different things want data and only one of them is yours.
+
+**The merchant's blocks resolve their own bindings, and you wire nothing.**
+Every block inside a region or a slot goes through the same pass a block under
+an ordinary section root goes through: `{{...}}` tokens in `dataBinding`, a bare
+`dataBinding` path, and an `isIterator` block repeating over the section's data
+source. That is the point — the merchant composed those blocks before you
+rewrote the area, and rewriting the area must not change what they say. It ran
+only on the generic path once, which meant a header moved into a custom section
+silently fell back to its authored text with nothing logged anywhere.
+
+Unlike the generic path, the pass is not gated on the section type: a
+`custom:acme:hero` root resolves bindings whenever there is anything to resolve
+against — a collection source, a static source, or the page's own commerce data.
+With no source at all the walk finds no root and returns the tree untouched, so
+the merchant's authored fallback stands.
+
+**Your own JSX reads the page instead.** The section component is code, so it
+asks directly rather than through a binding:
+
+```tsx
+import { useThemePageContext } from '@akinon/pz-theme/src/theme-page-context';
+
+const pageContext = useThemePageContext();
+```
+
+Import it from that deep path, not from `@akinon/pz-theme`. The package root
+re-exports `ThemePlaceholder`, which imports `server-only`, and that poisons the
+whole module for a client graph — a section file is a client module, so the root
+import fails the brand's build with "cannot be imported from a Client Component
+module". `@akinon/pz-theme/src/custom` does not re-export it either; the deep
+module is the one route.
+
+## Parts must live on YOUR markup
+
+Part rules are generated with an ownership guard that excludes anything inside a
+descendant `[data-block-id]`. Every region renders inside one. So a `data-part`
+stamped on markup a region's block renders is excluded from its own section's
+part rules, and the control the panel drew for it does nothing.
+
+Stamp parts on the elements the section itself draws — the bands **around** the
+regions.
+
+## The three page-level states
+
+Every other style state is a fact about an element and matches on it: `hover`,
+`selected`, `invalid`. Three are facts about the **page**, and they are the only
+way a composition learns something it cannot see from where it sits.
+
+| State | Means | Stamped on | By |
+|---|---|---|---|
+| `scrolled` | the page has moved under the chrome | the chrome slot, `data-scroll-state` | pz-theme (`chrome/scroll-state.tsx`) |
+| `overlay-open` | some overlay is open | `body`, `data-overlay-state` | pz-theme (`hooks/use-overlay.ts`) |
+| `docked` | the chrome sits **above** the page, not over it | `body`, `data-chrome-mode` | **you**, via `setChromeMode` |
+
+All three work as a root state on the section itself, `:<state>/<property>`, and
+as a part state, `<part>/<state>/<property>`.
+
+**The one rule: pz-theme owns the vocabulary, the brand owns the signal.** The
+attribute names, the tokens and the selectors that read them live here. Nothing
+in pz-theme can know which of your routes carry a hero, so nothing in pz-theme
+stamps `docked`. You do — and through `setChromeMode`, never by hand-writing the
+attribute, because a typo there raises no error and simply produces a header
+that never changes appearance.
+
+### The worked example: a header with two appearances
+
+This is what `docked` exists for. Over the home page's hero the header is
+transparent with light content; on every other route it sits above the page,
+solid, with dark content. Which one applies is a fact about the **route**, and a
+route is the one thing a composition cannot ask about. Before this, the choice
+was to keep the header in code and lose every merchant control, or compose it
+and lose the second appearance.
+
+```tsx
+'use client';
+
+const isHome = usePathname() === '/';
+
+useEffect(() => setChromeMode(isHome ? null : CHROME_MODE_DOCKED), [isHome]);
+```
+
+`setChromeMode` returns a cleanup, which is why it is returned straight from the
+effect. **Give the signal one owner.** The cleanup restores the value that call
+displaced — a snapshot, not a counted stack — so it unwinds correctly as one
+component mounts, re-stamps and unmounts, and does *not* compose if two
+components both stamp during a route transition.
+
+The section then styles all three appearances, and no descriptor changes:
+
+```ts
+styles: {
+  'background-color': { desktop: 'transparent' },
+  color: { desktop: '#ffffff' },
+
+  // Docked: above the page, solid, burgundy content.
+  ':docked/background-color': { desktop: '#ffffff' },
+  ':docked/color': { desktop: '#4a0e26' },
+
+  // Still transparent over the hero, but opaque once the page moves.
+  ':scrolled/background-color': { desktop: '#ffffff' },
+
+  // And opaque while the mega menu is open, which the menu cannot say itself.
+  ':overlay-open/background-color': { desktop: '#ffffff' }
+}
+```
+
+**Absent means overlay.** The attribute is not written until something writes
+it, so every composition published before `docked` existed renders exactly as it
+did.
+
+**`docked` outranks `scrolled` on purpose.** On an inner page both are true at
+once — a docked header is scrolled the moment the shopper moves — and both set
+the same property on the same band. The `docked` selector is qualified with
+`body`, which makes it (0,2,1) against `scrolled` at (0,2,0), so the mode wins
+on specificity rather than on whichever rule happened to be emitted last. That
+is the right answer and not an arbitrary one: `scrolled` describes how far the
+page has slid under a bar that floats over it, and once the bar is docked the
+question has no meaning. If you want a docked header to change on scroll as
+well, say so with a `docked` value that differs from the plain one.
+
+## `lockRootTransforms`
+
+Set it on any section whose design contains a `position: fixed` or `sticky`
+descendant. It removes `rotate`, `scale`, `translate`, `filter` and
+`backdrop-filter` from the section root's panel. Each of those creates a
+containing block for a fixed descendant, and a merchant has no way to know that.
+
+Remembering to set it is on you. It defaults to off because most sections do not
+contain a fixed child, and withholding controls a section could legitimately use
+is its own kind of lie.
+
+## `placeholders`
+
+`placeholders: ['header']` offers the section on the header placeholder and
+nowhere else. Omit it to offer it everywhere. A header section on the basket
+page is noise the merchant has to scroll past.
+
+## Limits
+
+Sixteen section types per build, twenty-four settings, twenty-four regions,
+eight slots and thirty-two parts per type, and a 256 KB **section** catalog
+measured separately from the block one.
+
+Sixteen rather than the blocks' forty because a section descriptor is the larger
+of the two — it carries a region list with seeded properties, styles and values —
+and a brand needs far fewer of them: sections are pages and chrome regions,
+blocks are the vocabulary inside them.
+
+## One type namespace
+
+`custom:acme:header` can be claimed by a block **or** a section, never both.
+Registration refuses either order with a message that says which one already
+holds it.
+
+## Failure behaviour
+
+A composition naming a section type this build does not register renders nothing
+on the live site and a labelled, selectable band in the designer — never the
+generic block loop, which would spill the seeded region blocks onto the page as
+loose top-level content in an order you never chose.
+
+A section component that throws is caught per-section: nothing live, a labelled
+card in the designer, and everything composed beside it renders normally.

package/src/custom/README.md

@@ -9,6 +9,13 @@ with ordinary editor content.
 Nothing here is a schema kept alongside the component. The declaration *is* the
 usage.
 
+**Writing a whole area rather than one element inside it?** See
+[`README-sections.md`](./README-sections.md). A custom *section* owns its own
+band on the page: it gets the section root panel (geometry and content width),
+and it names the children that go inside it rather than opening a hole. A custom
+*block* is the right shape for one element the merchant drops into a band they
+composed.
+
 ## The shape
 
 A "Complete the look" row for a product page — the merchant retypes its

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

@@ -0,0 +1,327 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+
+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 { isCustomThemeType } from '../types';
+
+/**
+ * THE MERCHANT'S DATA HAS TO SURVIVE THE REWRITE.
+ *
+ * A brand takes a header the merchant already composed — bound text, a repeat
+ * over the catalogue — and rewrites the area as a developer-authored section so
+ * the JSX can own the layout. The blocks do not change: the same tree moves
+ * from under a generic section root to under a `custom:acme:hero` one.
+ *
+ * It used to lose every binding in the move. The custom branch of
+ * `ThemeSection` returned before `resolveIteratorsRecursively` and
+ * `resolveBlockBindings` ran, so `ThemeRegion`/`ThemeSlot` handed
+ * `renderComposedChildren` raw blocks and `ThemeBlock` resolves nothing: the
+ * text fell back to its authored value and the repeat drew one empty row. No
+ * console output in the designer, none on the storefront, and nothing in the
+ * diff to review — the section markup was the only thing that changed.
+ *
+ * EVERY CASE IS ASSERTED AS AN EQUALITY BETWEEN THE TWO RENDERS, never against
+ * a literal. A literal expectation ("1,299.90 TL") pins today's formatter and
+ * says nothing about the two paths agreeing; if the fixture or the formatting
+ * moves, an equality test still asks the only question that matters — does the
+ * custom root render what the generic root renders. The second case below —
+ * "proves that equality is over resolved data" — is what stops that equality
+ * passing because both sides are equally broken.
+ */
+
+const CUSTOM_TYPE = 'custom:acme:hero';
+
+/**
+ * `custom` is the type a merchant-composed section actually carries, so this is
+ * the real before-state of the rewrite, not a synthetic control. It is also the
+ * one type the generic path resolves bindings for unconditionally
+ * (`shouldApplyGenericBindings`), which is exactly why a `custom:acme:hero`
+ * root cannot reuse that predicate: it is not the string `custom`.
+ */
+const GENERIC_TYPE = 'custom';
+
+const CATALOGUE = [
+  { name: 'Spring Sneaker', colour: 'sand' },
+  { name: 'Trail Runner', colour: 'moss' },
+  { name: 'City Loafer', colour: 'ink' }
+];
+
+/** Fewer rows than the catalogue holds, so the slice is visibly doing something. */
+const ITERATOR_COUNT = 2;
+
+/** A collection source, which is the case `shouldApplyGenericBindings` gates on. */
+const DATA_SOURCE = {
+  type: 'collection',
+  details: { collection: { data: CATALOGUE } }
+};
+
+/**
+ * The blocks, authored once and rendered under both roots byte for byte.
+ *
+ * `properties.regionName` is what a section's `<ThemeRegion>` resolves against
+ * and is an ordinary unread property everywhere else, so one array serves both
+ * fixtures and the ONLY difference between the two renders is `section.type`.
+ */
+const authoredBlocks = () => [
+  {
+    // (a) A `{{...}}` token inside literal text.
+    id: 'block-headline',
+    type: 'text',
+    label: 'Headline',
+    value: 'Authored headline fallback',
+    properties: {
+      regionName: 'headline',
+      dataBinding: 'Featured: {{ products[0].name }}'
+    },
+    styles: {},
+    order: 0,
+    hidden: false
+  },
+  {
+    // (b) A bare `properties.dataBinding` path.
+    id: 'block-lead',
+    type: 'text',
+    label: 'Lead',
+    value: 'Authored lead fallback',
+    properties: { regionName: 'lead', dataBinding: 'products[1].name' },
+    styles: {},
+    order: 1,
+    hidden: false
+  },
+  {
+    // (c) A repeat over the section's data source, one bound row template.
+    id: 'block-list',
+    type: 'group',
+    label: 'Catalogue',
+    isIterator: true,
+    iteratorDataPath: 'products',
+    properties: {
+      regionName: 'list',
+      useIteratorCount: true,
+      iteratorCount: ITERATOR_COUNT
+    },
+    styles: {},
+    order: 2,
+    hidden: false,
+    blocks: [
+      {
+        id: 'block-row',
+        type: 'text',
+        label: 'Row',
+        value: 'Authored row fallback',
+        properties: { dataBinding: 'item.name' },
+        styles: {},
+        order: 0,
+        hidden: false
+      }
+    ]
+  }
+];
+
+const sectionOfType = (type: string): Section =>
+  ({
+    id: `section-${type}`,
+    type,
+    name: 'Store hero',
+    label: 'Store hero',
+    properties: {},
+    styles: {},
+    order: 0,
+    hidden: false,
+    dataSource: DATA_SOURCE,
+    blocks: authoredBlocks()
+  } as unknown as Section);
+
+/** Places one region per authored block, in the order they were authored. */
+function AcmeHero() {
+  return (
+    <div>
+      <div data-testid="headline-area">
+        <ThemeRegion name="headline" />
+      </div>
+      <div data-testid="lead-area">
+        <ThemeRegion name="lead" />
+      </div>
+      <div data-testid="list-area">
+        <ThemeRegion name="list" />
+      </div>
+    </div>
+  );
+}
+
+const registerHero = () =>
+  registerCustomSections('acme', {
+    hero: defineCustomSection(AcmeHero, {
+      label: 'Store hero',
+      regions: [
+        { name: 'headline', label: 'Headline', block: 'text' },
+        { name: 'lead', label: 'Lead', block: 'text' },
+        { name: 'list', label: 'Catalogue', block: 'group' }
+      ]
+    })
+  });
+
+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 renderSection = (section: Section) =>
+  render(
+    <ThemeSettingsProvider value={null}>
+      <ThemeSection
+        section={section}
+        placeholderId="header"
+        currentBreakpoint="desktop"
+        isDesigner={false}
+      />
+    </ThemeSettingsProvider>
+  );
+
+/**
+ * Collapsed whitespace, because the two roots wrap the same blocks in different
+ * markup and a comparison that counted the gaps between elements would be
+ * asserting the JSX rather than the data.
+ */
+const renderedText = (section: Section): string =>
+  (renderSection(section).container.textContent ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+/** Direct `[data-block-id]` children — the top-level blocks the root rendered. */
+const topLevelBlockIds = (parent: Element | null): string[] =>
+  Array.from(parent?.children ?? [])
+    .filter((child) => child.hasAttribute('data-block-id'))
+    .map((child) => child.getAttribute('data-block-id') ?? '');
+
+describe('merchant bindings inside a developer-authored section', () => {
+  beforeEach(() => {
+    resetCustomCatalog();
+    resetCustomCollection();
+    resetCustomSectionCatalog();
+    resetCustomSectionDefinitions();
+    clearCustomRenderers();
+  });
+
+  it('renders the same text as the generic root the blocks came from', () => {
+    registerHero();
+
+    const generic = renderedText(sectionOfType(GENERIC_TYPE));
+    const custom = renderedText(sectionOfType(CUSTOM_TYPE));
+
+    // The whole regression in one line: rewriting the area as a section must
+    // change where the blocks render, never what they say.
+    expect(custom).toBe(generic);
+  });
+
+  it('proves that equality is over resolved data, not two dead renders', () => {
+    registerHero();
+
+    // Without this the assertion above would pass just as happily if both
+    // roots printed the authored fallbacks, which is the state this file
+    // exists to forbid.
+    const custom = renderedText(sectionOfType(CUSTOM_TYPE));
+
+    expect(custom).toContain(`Featured: ${CATALOGUE[0].name}`);
+    expect(custom).toContain(CATALOGUE[1].name);
+    expect(custom).not.toContain('Authored');
+  });
+
+  it.each([
+    ['a {{...}} token', 'headline-area', `Featured: ${CATALOGUE[0].name}`],
+    ['a properties.dataBinding path', 'lead-area', CATALOGUE[1].name],
+    [
+      'an isIterator block over the data source',
+      'list-area',
+      // Two rows, `iteratorCount` of them, spelled from the fixture so the
+      // case keeps its meaning if the catalogue changes. Concatenated with no
+      // separator because adjacent rows put no whitespace between themselves.
+      CATALOGUE.slice(0, ITERATOR_COUNT)
+        .map((product) => product.name)
+        .join('')
+    ]
+  ])('resolves %s in the region that places it', (_case, area, expected) => {
+    registerHero();
+    renderSection(sectionOfType(CUSTOM_TYPE));
+
+    // Region by region rather than on the whole section, so a binding that
+    // resolved into the WRONG region cannot pass on the concatenated text.
+    const text = (screen.getByTestId(area).textContent ?? '')
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    expect(text).toBe(expected);
+  });
+
+  it('leaves the top-level block count untouched when a repeat expands', () => {
+    registerHero();
+
+    // THE INVARIANT `findRegionChild` DEPENDS ON. It matches by property over
+    // `section.blocks`, so a resolution pass that spliced a repeat's rows in as
+    // siblings would leave every later region resolving against a shifted list.
+    // `buildIteratorBlock` expands INSIDE the iterator block, and the custom
+    // branch maps one resolved block per authored block — this is what pins
+    // both halves of that.
+    const { container } = renderSection(sectionOfType(GENERIC_TYPE));
+
+    expect(
+      topLevelBlockIds(container.querySelector('[data-section-content]'))
+    ).toEqual(['block-headline', 'block-lead', 'block-list']);
+  });
+
+  it('still resolves each region to its own block after resolution', () => {
+    registerHero();
+    renderSection(sectionOfType(CUSTOM_TYPE));
+
+    // One block per region, still the block that carries that region's name —
+    // the repeat sitting between them expanded without displacing anything.
+    expect(topLevelBlockIds(screen.getByTestId('headline-area'))).toEqual([
+      'block-headline'
+    ]);
+    expect(topLevelBlockIds(screen.getByTestId('lead-area'))).toEqual([
+      'block-lead'
+    ]);
+    expect(topLevelBlockIds(screen.getByTestId('list-area'))).toEqual([
+      'block-list'
+    ]);
+  });
+
+  it('keeps the authored value when there is nothing to bind against', () => {
+    registerHero();
+
+    // The unconditional binding pass must not invent a value: with no data
+    // source and no page context `resolveBlockBindings` finds no binding root
+    // and returns the tree unchanged, exactly as the generic path does.
+    const withoutData = sectionOfType(CUSTOM_TYPE);
+    delete (withoutData as unknown as Record<string, unknown>).dataSource;
+
+    const custom = renderedText(withoutData);
+    const generic = renderedText(
+      (() => {
+        const genericWithoutData = sectionOfType(GENERIC_TYPE);
+        delete (genericWithoutData as unknown as Record<string, unknown>)
+          .dataSource;
+        return genericWithoutData;
+      })()
+    );
+
+    expect(custom).toBe(generic);
+    expect(custom).toContain('Authored headline fallback');
+  });
+});