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

package/CHANGELOG.md

@@ -1,52 +1,17 @@
 # @akinon/pz-theme
 
-## 2.0.78-rc.2
+## 2.0.78
 
 ### Patch Changes
 
-- Updated dependencies [86187b1c]
-  - @akinon/next@2.0.78-rc.2
-  - @akinon/theme-contract@2.0.78-rc.2
+- 18d2b061: ZERO-4880: Developer-authored custom sections
 
-## 2.0.78-rc.1
+  A brand writes a whole area — a header, a footer — as one section and places its children in JSX with `<ThemeRegion name="search" />`. Each region is seeded as a real composition block of a declared type, so the merchant gets that block's own panel, its shared controls and its part groups with no descriptor written by hand. The section root gets the section root panel, and `lockRootTransforms` keeps the five properties that trap a fixed descendant off it.
 
-### Patch Changes
-
-- @akinon/next@2.0.78-rc.1
-- @akinon/theme-contract@2.0.78-rc.1
-
-## 2.0.78-rc.0
-
-### Patch Changes
+  New: `defineCustomSection`, `registerCustomSections`, `ThemeRegion`, and the section catalog, which rides the existing `PLACEHOLDERS_AVAILABLE` frame as a sibling field with its own byte budget. The CSS generator now treats a `custom:` section as owning its own content box while still resolving its max-width token, which a brand component cannot do for itself.
 
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea4143]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6c]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a631]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b]
-  - @akinon/next@2.0.78-rc.0
-  - @akinon/theme-contract@2.0.78-rc.0
+  - @akinon/next@2.0.78
+  - @akinon/theme-contract@2.0.78
 
 ## 2.0.77
 

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.78-rc.2",
+  "version": "2.0.78",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.78-rc.2",
+    "@akinon/next": "2.0.78",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.78-rc.2",
+    "@akinon/theme-contract": "2.0.78",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.78-rc.2",
+    "@akinon/next": "2.0.78",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/custom-catalog-announce.test.ts

@@ -46,6 +46,7 @@ const load = (): Loaded => {
 };
 
 const Promo = () => null;
+const Header = () => null;
 
 describe('PLACEHOLDERS_AVAILABLE announce', () => {
   const postMessage = jest.fn();
@@ -124,6 +125,75 @@ describe('PLACEHOLDERS_AVAILABLE announce', () => {
     ]);
   });
 
+  it('carries the section catalog as a SIBLING field, not inside the block one', () => {
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+    const { registry, register } = load();
+
+    registry.registerPlaceholder('header');
+    register.registerCustomSections('zsazsazsu', { header: Header });
+    jest.advanceTimersByTime(100);
+
+    const [payload] = frames();
+    expect(payload.customSections.vendor).toBe('zsazsazsu');
+    expect(
+      payload.customSections.sections.map((entry) => entry.type)
+    ).toEqual(['custom:zsazsazsu:header']);
+    // Beside `customBlocks` and never nested inside it: the editor validates
+    // the block catalog element by element and drops the whole thing on an
+    // unexpected shape, so a `sections` key inside it would make every block in
+    // a build vanish from the palette of any editor older than this change.
+    // A build that ships only sections therefore posts no block field at all.
+    expect('customBlocks' in payload).toBe(false);
+  });
+
+  it('carries both catalogs in one frame when a build ships both', () => {
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+    const { registry, register } = load();
+
+    registry.registerPlaceholder('header');
+    register.registerCustomBlocks('acme', { 'promo-strip': Promo });
+    register.registerCustomSections('acme', { header: Header });
+    jest.advanceTimersByTime(100);
+
+    // One frame, two payloads. Each announce replaces what the editor holds,
+    // so a build shipping both must never have to send them in two frames.
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    const [payload] = frames();
+    expect(payload.customBlocks.blocks).toHaveLength(1);
+    expect(payload.customSections.sections).toHaveLength(1);
+  });
+
+  it('gives a section-only build its second frame after a slow handshake', () => {
+    const { registry, register } = load();
+
+    register.registerCustomSections('zsazsazsu', { header: Header });
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+    expect('customSections' in frames()[0]).toBe(false);
+
+    // The re-announce latch has to consult BOTH catalogs. Checking only the
+    // block one would leave a brand that ships nothing but sections with an
+    // empty section band on exactly the loads where the cookie handshake lost
+    // the 100ms debounce — intermittently, and invisibly.
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        origin: EDITOR_ORIGIN,
+        source: window.parent as Window,
+        data: { type: 'SET_THEME_EDITOR_COOKIE', data: true }
+      })
+    );
+    jest.advanceTimersByTime(100);
+
+    expect(postMessage).toHaveBeenCalledTimes(2);
+    expect(
+      frames()[1].customSections.sections.map((entry) => entry.type)
+    ).toEqual(['custom:zsazsazsu:header']);
+  });
+
   it('omits the catalog key when the build registers no custom block', () => {
     (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
       true;
@@ -134,6 +204,9 @@ describe('PLACEHOLDERS_AVAILABLE announce', () => {
 
     const [payload] = frames();
     expect(payload.placeholders).toEqual(['header']);
+    // Neither field, for a build that registers neither. The section payload
+    // is omitted on exactly the same terms as the block one.
+    expect('customSections' in payload).toBe(false);
     // Absent, not empty — a build with no custom blocks has to be
     // indistinguishable from one whose catalog is not this frame's business.
     expect('customBlocks' in payload).toBe(false);

package/src/chrome/__tests__/chrome-mode.test.ts

@@ -0,0 +1,174 @@
+import {
+  CHROME_MODE_ATTRIBUTE,
+  CHROME_MODE_DOCKED,
+  setChromeMode
+} from '../chrome-mode';
+
+/**
+ * The writer for the `docked` style state.
+ *
+ * pz-theme owns the vocabulary — the attribute name, the token and the selector
+ * that reads them (utils/part-styles.ts). The BRAND owns the signal, because
+ * only the brand knows which of its routes carry a hero. This function is the
+ * seam between the two, and the reason it exists at all is that the alternative
+ * is every brand hand-typing `data-chrome-mode` into `document.body`: a typo
+ * there produces no error, just a header that never changes appearance.
+ *
+ * Two behaviours carry real weight and are pinned hardest below.
+ *
+ * IT WRITES TO `body`, NOT THE SLOT. That is not a stylistic difference from
+ * `data-scroll-state`. It is what earns the selector its specificity bump over
+ * `scrolled` (both match on an inner page), and it is what lets a hero written
+ * to sit under a transparent bar answer to the mode even though it is nowhere
+ * near the chrome.
+ *
+ * ITS CLEANUP RESTORES RATHER THAN CLEARS — a SNAPSHOT, not a stack. Each
+ * cleanup replays the value its own call displaced, which unwinds correctly
+ * when calls nest (mount, re-stamp, unmount) and does NOT compose when two
+ * owners overlap. Both halves are pinned below, the second as a
+ * characterisation test, because the constraint it implies — one owner for the
+ * signal — is invisible in the signature and its symptom only appears while
+ * navigating.
+ */
+
+const mode = () => document.body.getAttribute(CHROME_MODE_ATTRIBUTE);
+
+afterEach(() => {
+  document.body.removeAttribute(CHROME_MODE_ATTRIBUTE);
+});
+
+describe('stamping', () => {
+  it('writes the docked token onto body', () => {
+    setChromeMode(CHROME_MODE_DOCKED);
+
+    expect(mode()).toBe('docked');
+  });
+
+  it('writes to body rather than to the chrome slot', () => {
+    // The selector is `body[data-chrome-mode~="docked"] &`. Stamping the slot
+    // instead would match nothing at all, silently.
+    document.body.innerHTML = '<div data-chrome-slot="header"></div>';
+
+    setChromeMode(CHROME_MODE_DOCKED);
+
+    expect(mode()).toBe('docked');
+    expect(
+      document
+        .querySelector('[data-chrome-slot="header"]')
+        ?.getAttribute(CHROME_MODE_ATTRIBUTE)
+    ).toBeNull();
+
+    document.body.innerHTML = '';
+  });
+
+  it('leaves nothing behind when cleared with null, so overlay is the default', () => {
+    setChromeMode(CHROME_MODE_DOCKED);
+    setChromeMode(null);
+
+    // Absent, not `data-chrome-mode=""`: the token match `~="docked"` would
+    // fail on an empty value either way, but an empty attribute is a puzzle in
+    // devtools for anyone debugging why a header looks wrong.
+    expect(mode()).toBeNull();
+    expect(document.body.hasAttribute(CHROME_MODE_ATTRIBUTE)).toBe(false);
+  });
+
+  it('is idempotent', () => {
+    setChromeMode(CHROME_MODE_DOCKED);
+    setChromeMode(CHROME_MODE_DOCKED);
+    setChromeMode(CHROME_MODE_DOCKED);
+
+    expect(mode()).toBe('docked');
+  });
+});
+
+describe('the cleanup', () => {
+  it('restores the value that was there before, not a blank', () => {
+    const restoreFirst = setChromeMode(CHROME_MODE_DOCKED);
+    const restoreSecond = setChromeMode(null);
+
+    expect(mode()).toBeNull();
+
+    restoreSecond();
+
+    expect(mode()).toBe('docked');
+
+    restoreFirst();
+
+    expect(mode()).toBeNull();
+  });
+
+  it('unwinds correctly when cleanups nest, which is the mount/unmount case', () => {
+    // One owner mounting, re-stamping, and unmounting: cleanups run last-in
+    // first-out, and each finds exactly the value its own call displaced.
+    const restoreOuter = setChromeMode(CHROME_MODE_DOCKED);
+    const restoreInner = setChromeMode(null);
+
+    restoreInner();
+    expect(mode()).toBe('docked');
+
+    restoreOuter();
+    expect(mode()).toBeNull();
+  });
+
+  it('restores its OWN snapshot, so the signal must have a single owner', () => {
+    // A characterisation test, not an endorsement. Each cleanup replays the
+    // value observed at ITS call, so cleanups running out of order do not
+    // compose: here the outgoing caller's cleanup wipes a mode the incoming
+    // caller set after it.
+    //
+    // That is fine for the way this is meant to be used — one brand header
+    // owning the signal and re-stamping as the route changes — and it is the
+    // reason that constraint is not optional. Two components both stamping
+    // during a route transition can land here, and the symptom is a transparent
+    // bar over an inner page's content: reachable only by navigating, so no
+    // component test would show it.
+    //
+    // If a second owner ever becomes real, this needs a counted stack rather
+    // than a snapshot, and this test is where that decision should be recorded.
+    const restoreOutgoing = setChromeMode(null);
+    setChromeMode(CHROME_MODE_DOCKED);
+
+    restoreOutgoing();
+
+    expect(mode()).toBeNull();
+  });
+
+  it('can be called more than once without drifting', () => {
+    const restore = setChromeMode(CHROME_MODE_DOCKED);
+
+    restore();
+    restore();
+
+    expect(mode()).toBeNull();
+  });
+});
+
+describe('on the server', () => {
+  it('is a safe no-op and still returns a callable cleanup', () => {
+    // The chrome mode is stamped from a brand's header, which renders on the
+    // server first. Touching `document` there would throw during SSR and take
+    // the whole page down, so the guard is not a nicety.
+    const descriptor = Object.getOwnPropertyDescriptor(globalThis, 'document');
+
+    Object.defineProperty(globalThis, 'document', {
+      value: undefined,
+      configurable: true
+    });
+
+    try {
+      expect(typeof document).toBe('undefined');
+
+      const restore = setChromeMode(CHROME_MODE_DOCKED);
+
+      expect(typeof restore).toBe('function');
+      // The caller runs this in a cleanup it never guards itself.
+      expect(() => restore()).not.toThrow();
+    } finally {
+      if (descriptor) {
+        Object.defineProperty(globalThis, 'document', descriptor);
+      }
+    }
+
+    expect(typeof document).toBe('object');
+  });
+});

package/src/chrome/chrome-mode.ts

@@ -0,0 +1,61 @@
+/**
+ * Whether the chrome sits OVER the page or in the flow above it.
+ *
+ * The third page-level style state, beside `scrolled` (chrome/scroll-state.tsx)
+ * and `overlay-open` (hooks/use-overlay.ts). All three exist for the same
+ * reason: a composition cannot see the page it is on, so the page has to say.
+ *
+ * WHAT IT IS FOR. Almost every storefront header has two appearances — over the
+ * home page's hero it is transparent with light content, and on a product or
+ * category page it sits above the body, solid, with dark content. Which one
+ * applies is a fact about the ROUTE, and a route is the one thing a composition
+ * has no way to ask about. Before this, a brand had to choose: keep the header
+ * in code and lose every merchant control, or compose it and lose the second
+ * appearance.
+ *
+ * WHO STAMPS IT. The brand, from its own header, exactly as the mega menu
+ * stamps `data-overlay-state`. pz-theme supplies the vocabulary and the
+ * selector; only the brand knows which of its routes carry a hero. `setChromeMode`
+ * below is the one writer, so no brand hand-types the attribute.
+ *
+ * DEFAULT IS OVERLAY, and that is deliberate: the attribute is absent until
+ * something declares otherwise, so every composition that existed before this
+ * state renders exactly as it did.
+ */
+
+/** The attribute the renderer's `docked` selector matches on. */
+export const CHROME_MODE_ATTRIBUTE = 'data-chrome-mode';
+
+/** The style-state name this signal answers to (see utils/part-styles.ts). */
+export const CHROME_MODE_DOCKED = 'docked';
+
+export type ChromeMode = 'docked' | null;
+
+/**
+ * Stamps or clears the mode on `<body>`.
+ *
+ * The BODY rather than the chrome slot, unlike `data-scroll-state`, and the
+ * difference is load-bearing in two ways. It is what lets the state outrank
+ * `scrolled` on specificity — see the selector in `utils/part-styles.ts` — and
+ * it is what lets a block anywhere on the page answer to it, not only one
+ * inside the chrome: a docked header changes the space the page starts in, and
+ * a hero that was written to sit under a transparent bar needs to know.
+ *
+ * Idempotent, and a no-op on the server. Returns a cleanup that restores what
+ * was there before, so two headers on one page (a route transition rendering
+ * both) cannot leave the attribute stuck.
+ */
+export const setChromeMode = (mode: ChromeMode): (() => void) => {
+  if (typeof document === 'undefined') return () => undefined;
+
+  const { body } = document;
+  const previous = body.getAttribute(CHROME_MODE_ATTRIBUTE);
+
+  if (mode === null) body.removeAttribute(CHROME_MODE_ATTRIBUTE);
+  else body.setAttribute(CHROME_MODE_ATTRIBUTE, mode);
+
+  return () => {
+    if (previous === null) body.removeAttribute(CHROME_MODE_ATTRIBUTE);
+    else body.setAttribute(CHROME_MODE_ATTRIBUTE, previous);
+  };
+};