@akinon/pz-theme 2.0.60-rc.0 → 2.0.60

package/CHANGELOG.md

@@ -1,36 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.60-rc.0
-
-### Patch Changes
-
-- 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 [804d2bd6]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a63]
-- Updated dependencies [e18836b20]
-  - @akinon/next@2.0.60-rc.0
-  - @akinon/theme-contract@2.0.60-rc.0
+## 2.0.60
+
+### Patch Changes
+
+- 29b039a: ZERO-4809: Publish an overlay-open page state and close the panel in the canvas
+  - @akinon/next@2.0.60
+  - @akinon/theme-contract@2.0.60
 
 ## 2.0.59
 

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.60-rc.0",
+  "version": "2.0.60",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.60-rc.0",
+    "@akinon/next": "2.0.60",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.60-rc.0",
+    "@akinon/theme-contract": "2.0.60",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.60-rc.0",
+    "@akinon/next": "2.0.60",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/blocks/__tests__/panel-block.test.tsx

@@ -90,6 +90,12 @@ describe('the legacy size-guide markup, byte for byte', () => {
   // generalised. Every one of these is markup a live storefront is already
   // styling, so nothing here may move: the centred modal keeps its combined
   // root/backdrop node, its attribute order and its missing `tabIndex`.
+  //
+  // `legacy-designer` is the exception, and only because no storefront ever
+  // renders it — `isDesigner` is false everywhere outside the editor canvas.
+  // It was re-captured when the canvas stopped rendering a closed panel's
+  // children inline: that copy pushed the composition around the panel out of
+  // place, and "Hold open in canvas" is the control that shows it open.
   const CASES: Array<[string, Record<string, unknown>, boolean, boolean]> = [
     ['legacy-closed', {}, false, false],
     ['legacy-open', {}, false, true],
@@ -341,3 +347,43 @@ describe('an empty panel', () => {
     expect(placeholder?.textContent).not.toMatch(/size/i);
   });
 });
+
+describe('what the canvas shows while the panel is closed', () => {
+  it('renders the trigger only, so the composition around it keeps its layout', () => {
+    // The defect: a panel dropped into a header rendered its whole menu inline,
+    // under the trigger, and shoved the logo and the icons out of place — while
+    // the author was editing exactly that header. It also showed something no
+    // shopper ever sees.
+    const { container } = renderPanel({}, { isDesigner: true });
+
+    expect(container.querySelector('[data-size-guide-trigger]')).toBeTruthy();
+    expect(container.querySelector('[data-id="child-1"]')).toBeNull();
+    expect(
+      container.querySelector('[data-size-guide]')?.getAttribute(
+        'data-size-guide-state'
+      )
+    ).toBe('closed');
+  });
+
+  it('shows the open panel once it is held open, children and all', () => {
+    // "Hold open in canvas" is the control that answers "let me see it open",
+    // and it draws the real overlay rather than an inline copy of it.
+    const { container } = renderPanel(
+      {},
+      { isDesigner: true, styles: { forceOpen: { desktop: true } } }
+    );
+
+    expect(container.querySelector('[data-id="child-1"]')).toBeTruthy();
+    expect(container.querySelector('[data-part="modal"]')).toBeTruthy();
+  });
+
+  it('keeps the empty-state hint, which has no composition to disturb', () => {
+    // Without it a panel just added from the block list looks like nothing
+    // happened; with no children there is nothing to push out of place.
+    const { container } = renderPanel({}, { isDesigner: true, blocks: [] });
+
+    expect(container.textContent).toContain(
+      'Panel (drop the blocks it opens here)'
+    );
+  });
+});

package/src/blocks/__tests__/panel-legacy-golden.json

@@ -3,5 +3,5 @@
   "legacy-open": "<div data-size-guide=\"\" data-size-guide-state=\"open\"><button type=\"button\" data-size-guide-trigger=\"\" data-part=\"trigger\" aria-haspopup=\"dialog\" aria-expanded=\"true\" style=\"display: inline-flex; align-items: center; gap: 6px; padding: 0px; margin: 0px; background: transparent; text-decoration: underline; cursor: pointer;\" data-state=\"open\">Size guide</button><div data-size-guide-overlay=\"\" data-part=\"overlay\" data-state=\"open\" style=\"position: fixed; inset: 0; z-index: 1000; display: flex; align-items: center; justify-content: center; padding: 16px; background: rgba(0, 0, 0, 0.5);\"><div data-size-guide-content=\"\" data-size-guide-mode=\"modal\" data-part=\"modal\" data-state=\"open\" role=\"dialog\" aria-modal=\"true\" aria-label=\"Size guide\" style=\"position: relative; width: 100%; max-width: 640px; max-height: 80vh; overflow: auto; padding: 24px; border-radius: 4px; background: rgb(255, 255, 255); color: rgb(17, 24, 39); text-align: left;\"><button type=\"button\" data-size-guide-close=\"\" data-part=\"close\" aria-label=\"Close\" style=\"position: absolute; top: 12px; right: 12px; background: transparent; cursor: pointer; padding: 0px;\"><svg width=\"18\" height=\"18\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.6\" stroke-linecap=\"round\"><path d=\"M6 6l12 12M18 6L6 18\"></path></svg></button><div data-testid=\"tb\" data-id=\"child-1\"></div></div></div></div>",
   "legacy-open-titled": "<div data-size-guide=\"\" data-size-guide-state=\"open\"><button type=\"button\" data-size-guide-trigger=\"\" data-part=\"trigger\" aria-haspopup=\"dialog\" aria-expanded=\"true\" style=\"display: inline-flex; align-items: center; gap: 6px; padding: 0px; margin: 0px; background: transparent; text-decoration: underline; cursor: pointer;\" data-state=\"open\">Size guide</button><div data-size-guide-overlay=\"\" data-part=\"overlay\" data-state=\"open\" style=\"position: fixed; inset: 0; z-index: 1000; display: flex; align-items: center; justify-content: center; padding: 16px; background: rgba(0, 0, 0, 0.5);\"><div data-size-guide-content=\"\" data-size-guide-mode=\"modal\" data-part=\"modal\" data-state=\"open\" role=\"dialog\" aria-modal=\"true\" aria-label=\"Size chart\" style=\"position: relative; width: 100%; max-width: 900px; max-height: 80vh; overflow: auto; padding: 24px; border-radius: 4px; background: rgb(255, 255, 255); color: rgb(17, 24, 39); text-align: left;\"><button type=\"button\" data-size-guide-close=\"\" data-part=\"close\" aria-label=\"Close\" style=\"position: absolute; top: 12px; right: 12px; background: transparent; cursor: pointer; padding: 0px;\"><svg width=\"18\" height=\"18\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.6\" stroke-linecap=\"round\"><path d=\"M6 6l12 12M18 6L6 18\"></path></svg></button><div data-size-guide-title=\"\" data-part=\"title\" style=\"margin-bottom: 12px; font-weight: 600;\">Size chart</div><div data-testid=\"tb\" data-id=\"child-1\"></div></div></div></div>",
   "legacy-open-noclose": "<div data-size-guide=\"\" data-size-guide-state=\"open\"><button type=\"button\" data-size-guide-trigger=\"\" data-part=\"trigger\" aria-haspopup=\"dialog\" aria-expanded=\"true\" style=\"display: inline-flex; align-items: center; gap: 6px; padding: 0px; margin: 0px; background: transparent; text-decoration: underline; cursor: pointer;\" data-state=\"open\">Size guide</button><div data-size-guide-overlay=\"\" data-part=\"overlay\" data-state=\"open\" style=\"position: fixed; inset: 0; z-index: 1000; display: flex; align-items: center; justify-content: center; padding: 16px; background: rgba(0, 0, 0, 0.5);\"><div data-size-guide-content=\"\" data-size-guide-mode=\"modal\" data-part=\"modal\" data-state=\"open\" role=\"dialog\" aria-modal=\"true\" aria-label=\"Size guide\" style=\"position: relative; width: 100%; max-width: 640px; max-height: 80vh; overflow: auto; padding: 24px; border-radius: 4px; background: rgb(255, 255, 255); color: rgb(17, 24, 39); text-align: left;\"><div data-testid=\"tb\" data-id=\"child-1\"></div></div></div></div>",
-  "legacy-designer": "<div data-size-guide=\"\" data-size-guide-state=\"inline\"><button type=\"button\" data-size-guide-trigger=\"\" data-part=\"trigger\" aria-haspopup=\"dialog\" aria-expanded=\"false\" style=\"display: inline-flex; align-items: center; gap: 6px; padding: 0px; margin: 0px; background: transparent; text-decoration: underline; cursor: pointer;\">Size guide</button><div data-size-guide-content=\"\" data-size-guide-mode=\"inline\" data-part=\"modal\" style=\"margin-top: 8px; padding: 12px; border: 1px dashed #cbd5e1; border-radius: 4px;\"><div data-testid=\"tb\" data-id=\"child-1\"></div></div></div>"
+  "legacy-designer": "<div data-size-guide=\"\" data-size-guide-state=\"closed\"><button type=\"button\" data-size-guide-trigger=\"\" data-part=\"trigger\" aria-haspopup=\"dialog\" aria-expanded=\"false\" style=\"display: inline-flex; align-items: center; gap: 6px; padding: 0px; margin: 0px; background: transparent; text-decoration: underline; cursor: pointer;\">Size guide</button></div>"
 }

package/src/blocks/panel-block.tsx

@@ -272,29 +272,43 @@ const PanelBlock = ({
   ) : null;
 
   if (isDesigner && !forcedOpen) {
+    /**
+     * Closed in the canvas, exactly as it is on the storefront.
+     *
+     * The children used to render INLINE here, in flow under the trigger, so
+     * they stayed selectable without a click the author cannot perform inside
+     * the preview iframe. That predates the force-open toggle, and once the
+     * toggle existed the inline copy became the worse of the two: it is why a
+     * panel sitting in a header shoves the logo and the icons out of place
+     * while that header is being composed, and what the author sees there is
+     * not what a shopper gets.
+     *
+     * "Hold open in canvas" is the answer to seeing it open, and it draws the
+     * REAL overlay — right geometry, dressable backdrop. With the panel closed
+     * the layer tree still reaches every child.
+     *
+     * The empty state is the one thing that stays: a panel just added from the
+     * block list would otherwise look like nothing happened, and an empty
+     * panel has no content to push anything out of place.
+     */
     return (
-      <div data-size-guide="" data-size-guide-state="inline">
+      <div data-size-guide="" data-size-guide-state="closed">
         {trigger}
-        <div
-          data-size-guide-content=""
-          data-size-guide-mode="inline"
-          // The same part as the storefront panel: the author has to see the
-          // panel styling they just typed, and the panel never opens here.
-          {...partAttrs('modal')}
-          style={{
-            marginTop: '8px',
-            padding: '12px',
-            border: '1px dashed #cbd5e1',
-            borderRadius: '4px'
-          }}
-        >
-          {titleNode}
-          {childBlocks.length > 0 ? (
-            renderChildren()
-          ) : (
+        {childBlocks.length === 0 ? (
+          <div
+            data-size-guide-content=""
+            data-size-guide-mode="empty"
+            {...partAttrs('modal')}
+            style={{
+              marginTop: '8px',
+              padding: '12px',
+              border: '1px dashed #cbd5e1',
+              borderRadius: '4px'
+            }}
+          >
             <DesignerPlaceholder label="Panel (drop the blocks it opens here)" />
-          )}
-        </div>
+          </div>
+        ) : null}
       </div>
     );
   }

package/src/hooks/__tests__/use-overlay.test.tsx

@@ -157,6 +157,7 @@ function Page({ a, b }: PageProps) {
 describe('useOverlay', () => {
   afterEach(() => {
     document.body.style.overflow = '';
+    document.body.removeAttribute('data-overlay-state');
   });
 
   it('reproduces the loop the per-block traps have: two document-level traps pull focus at each other forever', () => {
@@ -487,6 +488,31 @@ describe('useOverlay', () => {
     expect(closeA).not.toHaveBeenCalled();
   });
 
+  it('publishes an overlay-open state on the body, and withdraws it only when the last overlay closes', () => {
+    // The styling hook a composition needs and cannot derive: a header that
+    // has to repaint while its own menu panel is open is not inside that
+    // panel, so no part state on the panel can reach it. `data-overlay-state`
+    // is the page saying so, in the same shape as the chrome slot's
+    // `data-scroll-state`.
+    const { rerender } = render(<Page a={{ open: false }} b={{ open: false }} />);
+    expect(document.body.hasAttribute('data-overlay-state')).toBe(false);
+
+    rerender(<Page a={{ open: true }} b={{ open: false }} />);
+    expect(document.body.getAttribute('data-overlay-state')).toBe('open');
+
+    // Two open, then one closes: the page is still held, so the attribute has
+    // to stay — the scroll lock learned this the hard way and the attribute is
+    // driven off the same stack for the same reason.
+    rerender(<Page a={{ open: true }} b={{ open: true }} />);
+    expect(document.body.getAttribute('data-overlay-state')).toBe('open');
+
+    rerender(<Page a={{ open: true }} b={{ open: false }} />);
+    expect(document.body.getAttribute('data-overlay-state')).toBe('open');
+
+    rerender(<Page a={{ open: false }} b={{ open: false }} />);
+    expect(document.body.hasAttribute('data-overlay-state')).toBe(false);
+  });
+
   it('does not touch the document while rendering on the server', () => {
     const addEventListener = jest.spyOn(document, 'addEventListener');
     document.body.style.overflow = 'auto';

package/src/hooks/use-overlay.ts

@@ -51,7 +51,37 @@ import { useEffect, useId, useMemo, useRef, useSyncExternalStore } from 'react';
 const overlayStack: string[] = [];
 const stackListeners = new Set<() => void>();
 
+/**
+ * The attribute a composition styles against while any overlay holds the page.
+ *
+ * Same shape and same reason as `data-scroll-state` on the chrome slot: a fact
+ * about the PAGE that an element cannot learn about itself. The header that
+ * turns opaque while its own menu panel is open is the case that forced it —
+ * the header is not inside the panel, so no part state on the panel can reach
+ * it, and the alternative was every block growing its own listener.
+ *
+ * It goes on `body` rather than on the chrome slot because an overlay can be
+ * opened from anywhere — a page body, a footer, another overlay — and
+ * everything that might want to react is a descendant of `body`.
+ */
+export const OVERLAY_STATE_ATTRIBUTE = 'data-overlay-state';
+export const OVERLAY_STYLE_STATE = 'open';
+
+const syncOverlayStateAttribute = () => {
+  if (typeof document === 'undefined') return;
+
+  // Driven off the stack rather than off each open/close call: two overlays
+  // closing in either order must leave exactly one attribute state behind, and
+  // the stack is already the thing that knows whether anything is left.
+  if (overlayStack.length > 0) {
+    document.body.setAttribute(OVERLAY_STATE_ATTRIBUTE, OVERLAY_STYLE_STATE);
+  } else {
+    document.body.removeAttribute(OVERLAY_STATE_ATTRIBUTE);
+  }
+};
+
 const notifyStack = () => {
+  syncOverlayStateAttribute();
   stackListeners.forEach((listener) => listener());
 };
 

package/src/utils/__tests__/scrolled-state-styles.test.ts

@@ -204,3 +204,54 @@ describe('checkout safety', () => {
     ).toEqual({ ':scrolled/background-color': '#ffffff' });
   });
 });
+
+describe('the overlay-open state', () => {
+  const OPEN = '[data-overlay-state~="open"]';
+
+  it('conditions a part on the page, exactly as scrolled does', () => {
+    const [selector] = buildPartSelectors('[data-block-id="blk-1"]', {
+      part: 'trigger',
+      state: 'overlay-open',
+      styles: {}
+    });
+
+    expect(selector).toBe(
+      `${OPEN} [data-block-id="blk-1"] [data-part="trigger"]` +
+        ':not(:where([data-block-id="blk-1"] [data-block-id] *))'
+    );
+  });
+
+  it('repaints a whole header band while a panel is open', () => {
+    // The case it exists for: the header is not inside the panel, so the panel
+    // cannot style it, and the alternative was a second copy of the logo and
+    // the icons authored inside the panel.
+    const css = generateThemeCSS([
+      section('sec-1', {}, [
+        block('bar', {
+          'background-color': 'transparent',
+          ':overlay-open/background-color': '#ffffff'
+        })
+      ])
+    ]);
+
+    expect(css).toContain(
+      `${OPEN} [data-block-id="bar"] {
+  background-color: rgba(255, 255, 255, 1);
+}`
+    );
+  });
+
+  it('matches nothing while every overlay is closed', () => {
+    const [selector] = buildPartSelectors('[data-block-id="blk-1"]', {
+      part: 'trigger',
+      state: 'overlay-open',
+      styles: {}
+    });
+
+    document.body.removeAttribute('data-overlay-state');
+    document.body.innerHTML =
+      '<div data-block-id="blk-1"><button data-part="trigger"></button></div>';
+
+    expect(document.querySelectorAll(selector)).toHaveLength(0);
+  });
+});

package/src/utils/part-styles.ts

@@ -69,13 +69,19 @@ const STATE_SELECTORS: Record<string, string[]> = {
   available: ['[data-state~="available"]'],
   unavailable: ['[data-state~="unavailable"]'],
   unknown: ['[data-state~="unknown"]'],
-  // The odd one out: every state above is a fact about the ELEMENT and matches
-  // on the element itself. This one is a fact about the PAGE — the chrome slot
-  // carries `data-scroll-state` (see chrome/scroll-state.tsx) — so it is
-  // matched through an ancestor and no renderer has to stamp anything for it to
+  // The odd ones out: every state above is a fact about the ELEMENT and matches
+  // on the element itself. These two are facts about the PAGE — the chrome slot
+  // carries `data-scroll-state` (see chrome/scroll-state.tsx) and `body` carries
+  // `data-overlay-state` (see hooks/use-overlay.ts) — so they are matched
+  // through an ancestor and no renderer has to stamp anything for them to
   // apply. That is what lets a header become opaque on scroll, which nothing in
   // a composition could previously say.
-  scrolled: ['[data-scroll-state~="scrolled"] &']
+  scrolled: ['[data-scroll-state~="scrolled"] &'],
+  // The same trick for the other half of that header: transparent over the
+  // hero, opaque while its menu panel is open. The panel cannot express it —
+  // the header is not inside the panel — and the header cannot know it without
+  // the page saying so.
+  'overlay-open': ['[data-overlay-state~="open"] &']
 };
 
 export const PART_STYLE_STATES = Object.keys(STATE_SELECTORS);