@akinon/pz-theme 2.0.107-rc.0 → 2.0.108-beta.0

package/CHANGELOG.md

@@ -1,40 +1,20 @@
 # @akinon/pz-theme
 
-## 2.0.107-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea41430]
-- 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 [e9598c71d]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6c]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a631]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b1]
-- Updated dependencies [1595d458]
-- Updated dependencies [dca12811]
-  - @akinon/next@2.0.107-rc.0
-  - @akinon/theme-contract@2.0.107-rc.0
+## 2.0.108-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.108-beta.0
+  - @akinon/theme-contract@2.0.108-beta.0
+
+## 2.0.107
+
+### Patch Changes
+
+- da5a550: ZERO-5048: Export useCustomBlockContext, useOverlay and chrome mode helpers from the custom entry and add reference examples
+  - @akinon/next@2.0.107
+  - @akinon/theme-contract@2.0.107
 
 ## 2.0.106
 

package/package.json

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

package/readme.md

@@ -21,3 +21,7 @@ export default async function Page() {
   return <ThemePlaceholder slug="homepage-body" />;
 }
 ```
+
+### Custom sections and blocks
+
+Developer-authored sections and blocks are written against `@akinon/pz-theme/src/custom` — see [`src/custom/README.md`](./src/custom/README.md) and [`src/custom/README-sections.md`](./src/custom/README-sections.md). Reference examples live in `examples/header/` at the root of the pz-next repository; they are not shipped in the npm package.

package/src/custom/README-sections.md

@@ -9,6 +9,11 @@ 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.
 
+For complete, commented sections to read alongside this file, see
+`examples/header/` at the root of the pz-next repository: one header written at
+six levels, from basic to advanced, each building on the previous one. They are
+reference only — not shipped in the npm package and never imported by an app.
+
 ## When a section instead of a block
 
 A block, because it is dropped into a section the merchant created, gets the
@@ -80,9 +85,17 @@ export default defineCustomSection(StoreHeader, {
 Then, from the **client root only**:
 
 ```ts
+import { registerCustomSections } from '@akinon/pz-theme/src/custom';
+import StoreHeader from './store-header';
+
 registerCustomSections('acme', { header: StoreHeader });
 ```
 
+Register the **default export** — the `defineCustomSection` result — not the
+plain `StoreHeader` function. A plain component is accepted, but it registers
+with no options at all, so its regions, slots, placeholders, seeded styles and
+`lockRootTransforms` are silently dropped.
+
 ## `ThemeRegion` — the one genuinely new piece
 
 A region is a child you named, chose the type of, and placed. Declaring
@@ -310,11 +323,26 @@ and lose the second appearance.
 ```tsx
 'use client';
 
-const isHome = usePathname() === '/';
+import { usePathname } from 'next/navigation';
+import { useEffect } from 'react';
+import {
+  CHROME_MODE_DOCKED,
+  setChromeMode
+} from '@akinon/pz-theme/src/custom';
+
+function StoreHeader() {
+  const isHome = usePathname() === '/';
+
+  useEffect(() => setChromeMode(isHome ? null : CHROME_MODE_DOCKED), [isHome]);
 
-useEffect(() => setChromeMode(isHome ? null : CHROME_MODE_DOCKED), [isHome]);
+  // ...the header markup
+}
 ```
 
+Import both from `@akinon/pz-theme/src/custom`, like the rest of the section
+API. The package root exports them too, but it pulls in `server-only`, so a
+client header cannot import them from there.
+
 `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

package/src/custom/README.md

@@ -16,6 +16,11 @@ 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.
 
+**Want a complete, commented example?** See `examples/header/` at the root of
+the pz-next repository: one header written at six levels, from basic to
+advanced, each building on the previous one. They are reference only — not
+shipped in the npm package and never imported by an app.
+
 ## The shape
 
 A "Complete the look" row for a product page — the merchant retypes its
@@ -205,6 +210,22 @@ region nothing could ever go in) and a `max` that is not a positive whole number
 would otherwise empty a brand's entire palette, with the only explanation in a
 repo the developer is not working in.
 
+## Detecting the editor canvas
+
+`useCustomBlockContext()` returns the context the block or section renders in,
+or `null` outside one. Its `isDesigner` is what to branch on when the canvas
+needs something the live site must not do — keep a menu open so the merchant
+can style it, or stop a link from navigating on click.
+
+```ts
+const isDesigner = useCustomBlockContext()?.isDesigner ?? false;
+```
+
+`isDesigner` means "the editing affordances are on", not "the editor is
+attached". The editor's **Use preview** toggle turns it off while the editor
+stays open, so the canvas behaves like the live site: whatever you held open
+closes and links navigate again.
+
 ## Styling parts
 
 The `field-<key>` parts come free from `ThemeEditable`. Everything else a block

package/src/custom/__tests__/custom-entry-exports.test.tsx

@@ -0,0 +1,200 @@
+import fs from 'fs';
+import path from 'path';
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+
+import * as chromeMode from '../../chrome/chrome-mode';
+import * as blockContext from '../block-context';
+import * as overlay from '../../hooks/use-overlay';
+import { resetCustomCollection } from '../collect';
+import { CustomSectionHost } from '../section-host';
+import type { Section } from '../../theme-section';
+
+// Through the barrel, the path a brand's custom header actually types. The
+// package root exports the chrome mode helpers too, but it pulls in
+// `server-only`, so a client module cannot reach them there.
+import {
+  CHROME_MODE_DOCKED,
+  defineCustomSection,
+  setChromeMode,
+  useCustomBlockContext,
+  useOverlay
+} from '../index';
+import type {
+  ChromeMode,
+  CustomBlockContextValue,
+  OverlayHandle,
+  UseOverlayOptions
+} from '../index';
+
+const HEADER = 'custom:brand:store-header';
+
+const section = (): Section =>
+  ({
+    id: 'section-header',
+    type: HEADER,
+    label: 'Store header',
+    properties: {},
+    styles: {},
+    order: 0,
+    hidden: false,
+    blocks: []
+  } as unknown as Section);
+
+/** Reports what a developer's own code would read from the hook. */
+function EditorProbe() {
+  const context: CustomBlockContextValue | null = useCustomBlockContext();
+
+  return (
+    <div
+      data-testid="probe"
+      data-inside={context ? 'yes' : 'no'}
+      data-designer={String(context?.isDesigner ?? 'none')}
+      data-scope={context?.scope ?? 'none'}
+    />
+  );
+}
+
+const StoreHeader = defineCustomSection(EditorProbe, {
+  label: 'Store header'
+});
+
+const renderHost = (isDesigner: boolean) =>
+  render(
+    <CustomSectionHost
+      type={HEADER}
+      label="Store header"
+      definition={StoreHeader}
+      section={section()}
+      placeholderId="header"
+      isDesigner={isDesigner}
+    />
+  );
+
+const probe = () => screen.getByTestId('probe');
+
+describe('the custom entry exports ZERO-5048 added', () => {
+  it('re-exports the same bindings rather than second copies', () => {
+    expect(useCustomBlockContext).toBe(blockContext.useCustomBlockContext);
+    expect(setChromeMode).toBe(chromeMode.setChromeMode);
+    expect(CHROME_MODE_DOCKED).toBe(chromeMode.CHROME_MODE_DOCKED);
+    expect(CHROME_MODE_DOCKED).toBe('docked');
+    expect(useOverlay).toBe(overlay.useOverlay);
+  });
+
+  it('keeps use-overlay.ts client-safe: a client directive and react as its only import', () => {
+    const source = fs.readFileSync(
+      path.resolve(__dirname, '../../hooks/use-overlay.ts'),
+      'utf8'
+    );
+    const imports = source.match(/^import[\s\S]*?from\s+['"]([^'"]+)['"]/gm);
+
+    expect(source.trimStart()).toMatch(/^['"]use client['"]/);
+    expect(source).not.toMatch(/server-only/);
+    expect(imports).toHaveLength(1);
+    expect(imports?.[0]).toMatch(/from 'react'$/);
+  });
+
+  it('keeps chrome-mode.ts free of imports and directives, so the barrel stays client-safe', () => {
+    const source = fs.readFileSync(
+      path.resolve(__dirname, '../../chrome/chrome-mode.ts'),
+      'utf8'
+    );
+
+    expect(source).not.toMatch(/^import\s/m);
+    expect(source).not.toMatch(/server-only/);
+    expect(source.trimStart()).not.toMatch(/^['"]use (client|server)['"]/);
+  });
+});
+
+describe('useCustomBlockContext', () => {
+  beforeEach(() => {
+    resetCustomCollection();
+  });
+
+  it('returns null outside a custom block or section instead of throwing', () => {
+    render(<EditorProbe />);
+
+    expect(probe().getAttribute('data-inside')).toBe('no');
+  });
+
+  it('reports isDesigner true on the editing canvas', () => {
+    renderHost(true);
+
+    expect(probe().getAttribute('data-inside')).toBe('yes');
+    expect(probe().getAttribute('data-scope')).toBe('section');
+    expect(probe().getAttribute('data-designer')).toBe('true');
+  });
+
+  it('reports isDesigner false when the section receives the preview flag', () => {
+    renderHost(false);
+
+    expect(probe().getAttribute('data-designer')).toBe('false');
+  });
+
+  it('receives isDesigner with preview (browse mode) already folded in', () => {
+    // The documented promise: "Use preview" turns isDesigner off for the
+    // section. The host passes through what the placeholder hands it, and the
+    // placeholder hands sections `isDesigner && !isBrowseMode`, never the raw
+    // "editor attached" flag.
+    const wrapper = fs.readFileSync(
+      path.resolve(__dirname, '../../theme-placeholder-wrapper.tsx'),
+      'utf8'
+    );
+
+    expect(wrapper).toMatch(/const isEditing = isDesigner && !isBrowseMode;/);
+    expect(wrapper).toMatch(/<ThemeSection[\s\S]*?isDesigner=\{isEditing\}/);
+  });
+});
+
+describe('setChromeMode from the custom entry', () => {
+  afterEach(() => {
+    document.body.removeAttribute('data-chrome-mode');
+  });
+
+  it('stamps the docked mode on body and restores it on cleanup', () => {
+    const mode: ChromeMode = CHROME_MODE_DOCKED;
+    const cleanup = setChromeMode(mode);
+
+    expect(document.body.getAttribute('data-chrome-mode')).toBe('docked');
+
+    cleanup();
+
+    expect(document.body.hasAttribute('data-chrome-mode')).toBe(false);
+  });
+});
+
+describe('useOverlay from the custom entry', () => {
+  /** A panel written the way a custom block writes one. */
+  function Panel(props: Omit<UseOverlayOptions, 'modal'>) {
+    const handle: OverlayHandle<HTMLDivElement> = useOverlay<HTMLDivElement>({
+      ...props,
+      modal: false
+    });
+
+    return props.open ? (
+      <div {...handle.overlayProps} role="dialog" aria-label="Menu" />
+    ) : null;
+  }
+
+  afterEach(() => {
+    document.body.removeAttribute('data-overlay-state');
+  });
+
+  it('sets the overlay-open page state on body while open, and clears it on close', () => {
+    const { rerender } = render(<Panel open />);
+
+    expect(document.body.getAttribute('data-overlay-state')).toBe('open');
+
+    rerender(<Panel open={false} />);
+
+    expect(document.body.hasAttribute('data-overlay-state')).toBe(false);
+  });
+
+  it('stays inert on the editor canvas', () => {
+    render(<Panel open isDesigner />);
+
+    expect(document.body.hasAttribute('data-overlay-state')).toBe(false);
+    expect(screen.getByRole('dialog').hasAttribute('aria-modal')).toBe(false);
+  });
+});

package/src/custom/index.ts

@@ -29,7 +29,9 @@
  *   export default defineCustomBlock(PromoStrip);
  *
  *   // blocks/index.ts — imported from the CLIENT ROOT only
- *   registerCustomBlocks('acme', { 'promo-strip': PromoStrip });
+ *   import { registerCustomBlocks } from '@akinon/pz-theme/src/custom';
+ *   import PromoStrip from './promo-strip';
+ *   registerCustomBlocks('brand', { 'promo-strip': PromoStrip });
  *
  * The block NAME lives in that record, never in `Component.name`: every
  * production build minifies the function name, so a block authored as
@@ -71,11 +73,11 @@ export { registerCustomBlocks, registerCustomSections } from './register';
  *
  * The shape a brand writes:
  *
- *   // views/header/zzz-header.tsx
+ *   // views/header/store-header.tsx
  *   import { defineCustomSection, ThemeRegion, ThemeSlot, partAttrs }
  *     from '@akinon/pz-theme/src/custom';
  *
- *   function ZsaHeader() {
+ *   function StoreHeader() {
  *     return (
  *       <header {...partAttrs('bar')}>
  *         <ThemeRegion name="logo" />
@@ -85,8 +87,8 @@ export { registerCustomBlocks, registerCustomSections } from './register';
  *     );
  *   }
  *
- *   export default defineCustomSection(ZsaHeader, {
- *     label: 'ZSA ZSA ZSU Header',
+ *   export default defineCustomSection(StoreHeader, {
+ *     label: 'Store header',
  *     regions: [
  *       { name: 'logo', label: 'Logo', block: 'image' },
  *       { name: 'basket', label: 'Basket', block: 'mini-basket' }
@@ -96,7 +98,9 @@ export { registerCustomBlocks, registerCustomSections } from './register';
  *   });
  *
  *   // views/header/index.ts — imported from the CLIENT ROOT only
- *   registerCustomSections('zsazsazsu', { header: ZsaHeader });
+ *   import { registerCustomSections } from '@akinon/pz-theme/src/custom';
+ *   import StoreHeader from './store-header';
+ *   registerCustomSections('brand', { header: StoreHeader });
  *
  * A REGION AND A SLOT ARE DIFFERENT PROMISES. A region is a child the developer
  * named, chose the type of and PLACED; the merchant styles it, configures it,
@@ -129,6 +133,36 @@ export type {
   ThemeSettingOptions
 } from './use-theme-setting';
 
+/**
+ * The context every custom unit renders inside, for the one question the
+ * components above cannot answer for a developer: is this the editor canvas?
+ *
+ * `isDesigner` is true only while the editing affordances are on. The editor's
+ * "Use preview" toggle (browse mode) turns it OFF for the section although the
+ * editor is still attached — `theme-placeholder-wrapper.tsx` hands sections
+ * `isDesigner && !isBrowseMode` — so anything kept open for styling closes and
+ * links navigate, exactly as on the live site.
+ *
+ * Returns null outside a custom block or section, never throws.
+ */
+export { useCustomBlockContext } from './block-context';
+export type { CustomBlockContextValue } from './block-context';
+
+/**
+ * The overlay behaviour pz-theme's own drawers and menus use, for a custom
+ * block that opens a panel: Escape to close, an optional scroll lock and
+ * focus handling, and the `overlay-open` page state on `body` while it is
+ * open, which a header section can style with `:overlay-open/<property>`.
+ *
+ * Pass the block's `isDesigner`: on the editor canvas the hook is inert (no
+ * focus move, no scroll lock, no page state). `modal: false` leaves the page
+ * usable, so a trigger outside the panel can still close it.
+ * `hooks/use-overlay.ts` is 'use client' and imports only react, so it is
+ * safe to re-export here.
+ */
+export { useOverlay } from '../hooks/use-overlay';
+export type { OverlayHandle, UseOverlayOptions } from '../hooks/use-overlay';
+
 // What the editor bridge announces. Exported here rather than kept internal
 // because a brand that mounts its own announce path needs the same payload the
 // package would have sent, not a second construction of it.
@@ -185,3 +219,14 @@ export { findRegionChild, isRegionNode, regionNodeName } from './region-nodes';
  * `data-part="…"`, which `sanitizePartName` then has no chance to normalize.
  */
 export { partAttrs } from '../utils/part-styles';
+
+/**
+ * The chrome mode writer, re-exported so a custom header section can declare
+ * its docked appearance from this module. The package root exports the same
+ * symbols but pulls in `server-only`, which a client module cannot import.
+ * `chrome/chrome-mode.ts` has no imports and no directive, and `setChromeMode`
+ * is a no-op without a `document`, so it is safe on either graph. Call it from
+ * an effect and return the cleanup it hands back.
+ */
+export { CHROME_MODE_DOCKED, setChromeMode } from '../chrome/chrome-mode';
+export type { ChromeMode } from '../chrome/chrome-mode';