@akinon/pz-theme 2.0.42-beta.0 → 2.0.42

package/CHANGELOG.md

@@ -1,12 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.42-beta.0
+## 2.0.42
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd75]
-  - @akinon/next@2.0.42-beta.0
-  - @akinon/theme-contract@2.0.42-beta.0
+- 3521bb92: ZERO-4727: Add an empty-zone designer affordance for fallback-less chrome slots and a code-owned region explainer
+  - @akinon/next@2.0.42
+  - @akinon/theme-contract@2.0.42
 
 ## 2.0.41
 

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

package/src/__tests__/chrome-empty-zone.test.tsx

@@ -0,0 +1,147 @@
+import React from 'react';
+import { render, screen, fireEvent, act } from '@testing-library/react';
+
+import { ChromeFallback } from '../chrome/chrome-fallback';
+
+/**
+ * A slot without brand markup (the checkout zones) has no fallback to hover,
+ * so before the empty-zone mode an uncomposed one rendered as literally
+ * nothing in the designer — undiscoverable, unhoverable, no way in. These
+ * tests pin the band that fixes that, and pin that visitors never see it.
+ */
+
+const EDITOR_ORIGIN = 'http://localhost:5174';
+
+const pushTheme = (
+  sections: unknown[],
+  slug = 'checkout-top-body',
+  origin = EDITOR_ORIGIN
+) =>
+  act(() => {
+    fireEvent(
+      window,
+      new MessageEvent('message', {
+        origin,
+        data: {
+          type: 'UPDATE_THEME',
+          data: {
+            theme: {
+              placeholders: [{ slug, sections }]
+            }
+          }
+        }
+      })
+    );
+  });
+
+describe('ChromeFallback empty zone in the designer', () => {
+  beforeAll(() => {
+    Object.defineProperty(window, 'top', {
+      configurable: true,
+      value: { name: 'designer' }
+    });
+  });
+
+  it('draws a visible band with the affordance for an uncomposed zone', () => {
+    render(<ChromeFallback slug="checkout-top-body" emptyZone />);
+
+    // Visible without hover: a hover-only control on an empty area is the
+    // exact invisibility this mode exists to fix.
+    expect(
+      screen.getByText(/checkout-top-body area has no composition yet/i)
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', { name: /edit in theme editor/i })
+    ).toBeInTheDocument();
+  });
+
+  it('asks the editor to compose the zone when the affordance is used', () => {
+    const postMessage = jest.fn();
+    Object.defineProperty(window, 'parent', {
+      configurable: true,
+      value: { postMessage }
+    });
+
+    render(<ChromeFallback slug="checkout-summary-body" emptyZone />);
+
+    // A frame from the editor is what proves its origin to the bridge;
+    // without one there is no trusted target and the message is dropped.
+    pushTheme([], 'checkout-summary-body');
+
+    fireEvent.click(
+      screen.getByRole('button', { name: /edit in theme editor/i })
+    );
+
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    const [envelope, targetOrigin] = postMessage.mock.calls[0];
+    expect(envelope).toMatchObject({
+      type: 'REQUEST_CHROME_OVERRIDE',
+      data: { slug: 'checkout-summary-body' }
+    });
+    expect(envelope.protocolVersion).toBeGreaterThan(0);
+    expect(targetOrigin).toBe(EDITOR_ORIGIN);
+  });
+
+  it('withdraws once the zone is composed and returns when emptied again', () => {
+    render(<ChromeFallback slug="checkout-top-body" emptyZone />);
+
+    pushTheme([{ id: 'section-abc', type: 'custom' }]);
+    expect(
+      screen.queryByText(/has no composition yet/i)
+    ).not.toBeInTheDocument();
+
+    pushTheme([]);
+    expect(screen.getByText(/has no composition yet/i)).toBeInTheDocument();
+  });
+
+  it('starts hidden when the server rendered a composition and returns on removal', () => {
+    render(
+      <ChromeFallback slug="checkout-bottom-body" emptyZone initiallyOverridden />
+    );
+
+    expect(
+      screen.queryByText(/has no composition yet/i)
+    ).not.toBeInTheDocument();
+
+    pushTheme([], 'checkout-bottom-body');
+    expect(screen.getByText(/has no composition yet/i)).toBeInTheDocument();
+  });
+
+  it('ignores a theme pushed from an untrusted origin', () => {
+    render(<ChromeFallback slug="checkout-top-body" emptyZone />);
+
+    pushTheme(
+      [{ id: 'section-abc', type: 'custom' }],
+      'checkout-top-body',
+      'https://evil.example'
+    );
+
+    // An embedding page must not be able to toggle designer chrome.
+    expect(screen.getByText(/has no composition yet/i)).toBeInTheDocument();
+  });
+});
+
+describe('ChromeFallback empty zone on the live site', () => {
+  beforeAll(() => {
+    Object.defineProperty(window, 'top', {
+      configurable: true,
+      value: window
+    });
+  });
+
+  it('renders nothing for an uncomposed zone', () => {
+    const { container } = render(
+      <ChromeFallback slug="checkout-top-body" emptyZone />
+    );
+
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('renders nothing under a server-rendered composition', () => {
+    const { container } = render(
+      <ChromeFallback slug="checkout-top-body" emptyZone initiallyOverridden />
+    );
+
+    expect(container).toBeEmptyDOMElement();
+  });
+});

package/src/__tests__/code-owned-region.test.tsx

@@ -0,0 +1,90 @@
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+
+import { CodeOwnedRegion } from '../chrome/code-owned-region';
+
+/**
+ * The checkout flow offers no takeover affordance on purpose, but silence
+ * reads as breakage: a designer hovering it sees the same nothing a bug would
+ * produce. These tests pin the explainer that fills that gap — and pin that
+ * it never leaks to visitors and never blocks the flow it wraps.
+ */
+
+describe('CodeOwnedRegion in the designer', () => {
+  beforeAll(() => {
+    Object.defineProperty(window, 'top', {
+      configurable: true,
+      value: { name: 'designer' }
+    });
+  });
+
+  it('explains the region on hover and says where the composable zones are', () => {
+    render(
+      <CodeOwnedRegion label="checkout flow">
+        <div data-testid="flow">payment steps</div>
+      </CodeOwnedRegion>
+    );
+
+    expect(screen.queryByText(/code-owned/i)).not.toBeInTheDocument();
+
+    fireEvent.mouseEnter(screen.getByTestId('flow').parentElement!);
+
+    const note = screen.getByText(/checkout flow is code-owned/i);
+    expect(note).toBeInTheDocument();
+    expect(note.textContent).toMatch(/zones above and below/i);
+
+    fireEvent.mouseLeave(screen.getByTestId('flow').parentElement!);
+    expect(screen.queryByText(/code-owned/i)).not.toBeInTheDocument();
+  });
+
+  it('never intercepts the pointer, so the flow stays usable in the preview', () => {
+    render(
+      <CodeOwnedRegion label="checkout flow">
+        <div data-testid="flow">payment steps</div>
+      </CodeOwnedRegion>
+    );
+
+    fireEvent.mouseEnter(screen.getByTestId('flow').parentElement!);
+
+    const overlay = screen.getByText(/code-owned/i).parentElement!;
+    expect(overlay).toHaveStyle({ pointerEvents: 'none' });
+  });
+
+  it('keeps the children rendered and interactive underneath', () => {
+    const onClick = jest.fn();
+    render(
+      <CodeOwnedRegion label="checkout flow">
+        <button type="button" onClick={onClick}>
+          continue
+        </button>
+      </CodeOwnedRegion>
+    );
+
+    fireEvent.mouseEnter(screen.getByRole('button').parentElement!);
+    fireEvent.click(screen.getByRole('button', { name: /continue/i }));
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('CodeOwnedRegion on the live site', () => {
+  beforeAll(() => {
+    Object.defineProperty(window, 'top', {
+      configurable: true,
+      value: window
+    });
+  });
+
+  it('renders the children and no explainer, hovered or not', () => {
+    render(
+      <CodeOwnedRegion label="checkout flow">
+        <div data-testid="flow">payment steps</div>
+      </CodeOwnedRegion>
+    );
+
+    expect(screen.getByTestId('flow')).toBeInTheDocument();
+
+    fireEvent.mouseEnter(screen.getByTestId('flow').parentElement!);
+    expect(screen.queryByText(/code-owned/i)).not.toBeInTheDocument();
+  });
+});

package/src/chrome/chrome-fallback.tsx

@@ -18,10 +18,11 @@ export function ChromeFallback({
   slug,
   children,
   wrapperClassName,
-  initiallyOverridden = false
+  initiallyOverridden = false,
+  emptyZone = false
 }: {
   slug: string;
-  children: React.ReactNode;
+  children?: React.ReactNode;
   /**
    * Applied to the live-site wrapper only. The designer overlay below needs
    * a real positioned box for its scrim, so it deliberately ignores this.
@@ -34,6 +35,14 @@ export function ChromeFallback({
    * project markup has to come back.
    */
   initiallyOverridden?: boolean;
+  /**
+   * A slot with no brand markup (the checkout zones) has nothing to size the
+   * hover overlay, so an uncomposed one is invisible in the designer and the
+   * area cannot be discovered at all. This mode draws a slim dashed band with
+   * the affordance instead; visitors never see it — the live site renders
+   * nothing, exactly as before.
+   */
+  emptyZone?: boolean;
 }) {
   const [inDesigner, setInDesigner] = useState(false);
   const [isHovered, setIsHovered] = useState(false);
@@ -91,8 +100,9 @@ export function ChromeFallback({
 
   if (!inDesigner) {
     // Composed on the live site: the composition owns the area, the brand
-    // markup must never double-render under it.
-    if (initiallyOverridden) return null;
+    // markup must never double-render under it. An empty zone has nothing to
+    // show a visitor either way.
+    if (initiallyOverridden || emptyZone) return null;
 
     return (
       <div data-chrome-fallback={slug} className={wrapperClassName}>
@@ -107,6 +117,62 @@ export function ChromeFallback({
     postToEditor({ type: 'REQUEST_CHROME_OVERRIDE', data: { slug } });
   };
 
+  if (emptyZone) {
+    // Unlike the brand-markup overlay, the band and its button stay visible
+    // without hover: there is no markup to obscure, and a hover-only control
+    // on an otherwise empty area is exactly the invisibility this mode fixes.
+    return (
+      <div
+        data-chrome-fallback={slug}
+        data-chrome-empty-zone=""
+        onMouseEnter={() => setIsHovered(true)}
+        onMouseLeave={() => setIsHovered(false)}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          flexWrap: 'wrap',
+          gap: '12px',
+          minHeight: '56px',
+          padding: '10px 16px',
+          margin: '8px 0',
+          border: `2px dashed ${isHovered ? '#60a5fa' : '#cbd5e1'}`,
+          borderRadius: '6px',
+          background: isHovered
+            ? 'rgba(37, 99, 235, 0.08)'
+            : 'rgba(148, 163, 184, 0.08)',
+          transition: 'background 120ms ease, border-color 120ms ease'
+        }}
+      >
+        <span
+          style={{
+            color: '#64748b',
+            fontSize: '13px',
+            fontWeight: 500
+          }}
+        >
+          The {slug} area has no composition yet
+        </span>
+        <button
+          type="button"
+          onClick={requestOverride}
+          style={{
+            background: '#2563eb',
+            color: '#ffffff',
+            border: 'none',
+            borderRadius: '6px',
+            padding: '8px 14px',
+            fontSize: '13px',
+            fontWeight: 600,
+            cursor: 'pointer'
+          }}
+        >
+          Edit in theme editor
+        </button>
+      </div>
+    );
+  }
+
   return (
     <div
       data-chrome-fallback={slug}

package/src/chrome/chrome-slot.tsx

@@ -68,7 +68,10 @@ export default async function ChromeSlot({
         {/* The fallback ships hidden: on the live site it never renders, but
             in the designer it must be able to COME BACK when the last
             section is removed — without it in the tree, deleting a menu or
-            header composition would blank the area until a full reload. */}
+            header composition would blank the area until a full reload. The
+            same applies to a fallback-less zone: its designer band has to be
+            able to return, or removing the last section leaves the area
+            undiscoverable again. */}
         {fallback ? (
           <ChromeFallback
             slug={slug}
@@ -77,7 +80,9 @@ export default async function ChromeSlot({
           >
             {fallback}
           </ChromeFallback>
-        ) : null}
+        ) : (
+          <ChromeFallback slug={slug} emptyZone initiallyOverridden />
+        )}
         <ThemePlaceholder slug={slug} pageContext={pageContext} />
       </div>
     );
@@ -89,7 +94,12 @@ export default async function ChromeSlot({
         <ChromeFallback slug={slug} wrapperClassName={fallbackClassName}>
           {fallback}
         </ChromeFallback>
-      ) : null}
+      ) : (
+        // No brand markup to take over: an uncomposed zone would render as
+        // nothing at all, so the designer gets a visible band instead. The
+        // live site keeps rendering nothing.
+        <ChromeFallback slug={slug} emptyZone />
+      )}
       {/* Empty until the designer overrides this area from the editor */}
       <ThemePlaceholder slug={slug} pageContext={pageContext} />
     </div>

package/src/chrome/code-owned-region.tsx

@@ -0,0 +1,85 @@
+'use client';
+
+import React, { useEffect, useState } from 'react';
+
+/**
+ * Wraps markup that is deliberately NOT composable — the checkout flow being
+ * the canonical case. Without this, hovering the area in the designer gives
+ * no feedback at all, which reads as "broken" rather than "code-owned": every
+ * other region either offers the takeover affordance or an empty-zone band.
+ *
+ * On the live site the wrapper is inert (one attribute-carrying div, no
+ * styles beyond `position: relative`). In the designer, hover draws a neutral
+ * outline and a note explaining why there is no edit affordance here and
+ * where the composable zones are. The overlay never intercepts the pointer,
+ * so the wrapped flow stays fully usable in the preview.
+ */
+export function CodeOwnedRegion({
+  label,
+  children
+}: {
+  /** Human-readable region name, e.g. "checkout flow". */
+  label: string;
+  children: React.ReactNode;
+}) {
+  const [inDesigner, setInDesigner] = useState(false);
+  const [isHovered, setIsHovered] = useState(false);
+
+  useEffect(() => {
+    if (typeof window !== 'undefined' && window.self !== window.top) {
+      setInDesigner(true);
+    }
+  }, []);
+
+  return (
+    // The wrapper renders on the live site too: switching between a plain
+    // fragment and a wrapped tree at designer-detection time would remount
+    // the children — for the checkout flow that means refetching the whole
+    // checkout state right after hydration.
+    <div
+      data-code-owned={label}
+      style={{ position: 'relative' }}
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+    >
+      {children}
+
+      {inDesigner && isHovered && (
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            outline: '2px dashed #cbd5e1',
+            outlineOffset: '-2px',
+            // Never intercept the pointer: the region is explained, not locked.
+            pointerEvents: 'none',
+            display: 'flex',
+            alignItems: 'flex-start',
+            justifyContent: 'center',
+            zIndex: 30
+          }}
+        >
+          <span
+            style={{
+              // Sticky keeps the note readable while a tall region (the whole
+              // checkout flow) is scrolled under the pointer.
+              position: 'sticky',
+              top: '12px',
+              marginTop: '12px',
+              background: '#0f172a',
+              color: '#ffffff',
+              borderRadius: '9999px',
+              padding: '6px 14px',
+              fontSize: '12.5px',
+              fontWeight: 500,
+              boxShadow: '0 1px 3px rgba(0, 0, 0, 0.25)'
+            }}
+          >
+            The {label} is code-owned and cannot be composed — use the zones
+            above and below it
+          </span>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/index.ts

@@ -22,6 +22,7 @@ export type { Block } from './theme-block';
 
 export { default as ChromeSlot } from './chrome/chrome-slot';
 export { ChromeFallback } from './chrome/chrome-fallback';
+export { CodeOwnedRegion } from './chrome/code-owned-region';
 export { PreviewAuthStateReporter } from './chrome/preview-auth-state';
 export { LiveBasketPageContext } from './chrome/live-basket-page-context';
 export {