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

package/CHANGELOG.md

@@ -1,36 +1,16 @@
 # @akinon/pz-theme
 
-## 2.0.58-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.58-rc.0
-  - @akinon/theme-contract@2.0.58-rc.0
+## 2.0.58
+
+### Patch Changes
+
+- e11783b: ZERO-4790: Draw the modal being composed in the theme editor canvas, from the editor's live entry rather than the saved one — so a modal that has never been saved is visible, and chrome edits show up without a save and a reload
+- b992ca5: ZERO-4790: Read the theme editor's modal registry in the preview, so a trigger pointed at a modal that has not been saved yet actually opens it
+- 08f060d: ZERO-4790: Add composable modals — a global modal host, a block action vocabulary for triggering them, and auto-open with frequency capping
+- 7eb9396: ZERO-4790: Add the modal addressing foundation — modal slug family, overlay bus and theme_modals registry
+- Updated dependencies [08f060d]
+  - @akinon/theme-contract@2.0.58
+  - @akinon/next@2.0.58
 
 ## 2.0.57
 

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

package/src/blocks/button-block.tsx

@@ -9,6 +9,7 @@ import {
   getResponsiveValue,
   resolveThemeCssVariables
 } from '../utils';
+import { useBlockAction } from '../hooks/use-block-action';
 import { BlockRendererProps } from './block-renderer-registry';
 import { useThemeSettingsContext } from '../theme-settings-context';
 
@@ -18,6 +19,7 @@ const ButtonBlock = ({
   isDesigner = false
 }: BlockRendererProps) => {
   const themeSettings = useThemeSettingsContext();
+  const action = useBlockAction(block, { currentBreakpoint, isDesigner });
   const { locale } = useLocalization();
   const [emailSubscription] = useEmailSubscriptionMutation();
   const [feedbackModal, setFeedbackModal] = useState({
@@ -386,6 +388,20 @@ const ButtonBlock = ({
       return;
     }
 
+    /**
+     * An authored action wins over the href.
+     *
+     * A button that both opens a modal and navigates would race itself, so the
+     * action calls `preventDefault` and this returns rather than falling
+     * through into the newsletter submit path below. With no action authored
+     * the hook is inert and everything published before this existed behaves
+     * exactly as it did.
+     */
+    if (action.isActive) {
+      action.onClick?.(e);
+      return;
+    }
+
     if (tag === 'button' && buttonType === 'submit') {
       e.preventDefault();
     }
@@ -566,7 +582,12 @@ const ButtonBlock = ({
   if (tag === 'button') {
     return (
       <>
-        <button type={buttonType} style={finalStyles} onClick={handleClick}>
+        <button
+          type={buttonType}
+          style={finalStyles}
+          onClick={handleClick}
+          {...action.ariaProps}
+        >
           {content}
         </button>
         {feedbackModalElement}
@@ -582,6 +603,7 @@ const ButtonBlock = ({
         rel={target === '_blank' ? 'noopener noreferrer' : undefined}
         style={finalStyles}
         onClick={handleClick}
+        {...action.ariaProps}
       >
         {content}
       </a>

package/src/blocks/link-block.tsx

@@ -6,6 +6,7 @@ import { useLocalization } from '@akinon/next/hooks';
 import { LocaleUrlStrategy } from '@akinon/next/localization';
 import { urlLocaleMatcherRegex, urlSchemes } from '@akinon/next/utils';
 import { getResponsiveValue } from '../utils';
+import { useBlockAction } from '../hooks/use-block-action';
 import { BlockRendererProps } from './block-renderer-registry';
 import ThemeBlock from '../theme-block';
 
@@ -20,6 +21,22 @@ const LinkBlock = ({
   isDesigner = false
 }: BlockRendererProps) => {
   const { locale, defaultLocaleValue, localeUrlStrategy } = useLocalization();
+  const action = useBlockAction(block, { currentBreakpoint, isDesigner });
+
+  /**
+   * An authored action replaces the navigation rather than joining it: a link
+   * that both opens a modal and follows its href would race itself. With no
+   * action authored this is exactly the designer-only preventDefault the link
+   * always had.
+   */
+  const handleClick = (event: React.MouseEvent<HTMLElement>) => {
+    if (isDesigner) {
+      event.preventDefault();
+      return;
+    }
+
+    if (action.isActive) action.onClick?.(event);
+  };
 
   const href = block.properties?.href
     ? String(getResponsiveValue(block.properties.href, currentBreakpoint, '#'))
@@ -136,11 +153,8 @@ const LinkBlock = ({
         target={isDesigner ? undefined : target}
         rel={isDesigner ? undefined : rel}
         style={inlineStyles}
-        onClick={(e) => {
-          if (isDesigner) {
-            e.preventDefault();
-          }
-        }}
+        onClick={handleClick}
+        {...action.ariaProps}
       >
         <div style={{ padding: '20px', color: '#6b7280' }}>
           Empty link block
@@ -155,11 +169,8 @@ const LinkBlock = ({
       target={isDesigner ? undefined : target}
       rel={isDesigner ? undefined : rel}
       style={inlineStyles}
-      onClick={(e) => {
-        if (isDesigner) {
-          e.preventDefault();
-        }
-      }}
+      onClick={handleClick}
+      {...action.ariaProps}
     >
       {block.blocks
         .filter((childBlock) => (isDesigner ? true : !childBlock.hidden))

package/src/blocks/panel-block.tsx

@@ -8,24 +8,21 @@ import {
   resolveOption
 } from '../utils';
 import { useOverlay } from '../hooks/use-overlay';
+import {
+  CentredModalSurface,
+  LayeredOverlaySurface,
+  OverlayCloseButton,
+  OverlayPresentation,
+  OVERLAY_PRESENTATIONS,
+  clampOverlayNumber as clampNumber
+} from '../overlays/overlay-surface';
 import ThemeBlock from '../theme-block';
 import { BlockRendererProps } from './block-renderer-registry';
 import { DesignerPlaceholder, readToggle } from './product-block-utils';
 
-const clampNumber = (
-  value: unknown,
-  fallback: number,
-  min: number,
-  max: number
-) => {
-  const numeric = Math.round(Number(value));
-  if (!Number.isFinite(numeric)) return fallback;
-  return Math.min(max, Math.max(min, numeric));
-};
-
-type Presentation = 'modal' | 'drawer' | 'sheet' | 'anchored';
+type Presentation = OverlayPresentation;
 
-const PRESENTATIONS: Presentation[] = ['modal', 'drawer', 'sheet', 'anchored'];
+const PRESENTATIONS = OVERLAY_PRESENTATIONS;
 
 /**
  * Generic overlay surface: a trigger that opens a panel the author fills.
@@ -303,245 +300,78 @@ const PanelBlock = ({
   }
 
   const closeButton = showClose ? (
-    <button
-      type="button"
-      data-size-guide-close=""
-      {...partAttrs('close')}
-      aria-label={closeLabel}
+    <OverlayCloseButton
+      label={closeLabel}
       onClick={dismiss}
-      style={{
-        position: 'absolute',
-        top: '12px',
-        right: '12px',
-        border: 'none',
-        background: 'transparent',
-        color: 'inherit',
-        cursor: 'pointer',
-        padding: 0
-      }}
-    >
-      <svg
-        width="18"
-        height="18"
-        viewBox="0 0 24 24"
-        fill="none"
-        stroke="currentColor"
-        strokeWidth="1.6"
-        strokeLinecap="round"
-      >
-        <path d="M6 6l12 12M18 6L6 18" />
-      </svg>
-    </button>
+      markerAttrs={{ 'data-size-guide-close': '' }}
+    />
   ) : null;
 
   /**
-   * The centred modal keeps the shape it published with: ONE node that is both
-   * the fixed root and the backdrop, carrying `data-part="overlay"`, with the
-   * panel centred inside it by flex. Refactoring it into the root + backdrop
-   * sibling pair the other presentations use would move markup live
-   * storefronts already style, for no gain — so the new modes get their own
-   * branch instead. `panel-legacy-golden.json` is what holds this to it.
+   * Both branches come from `overlays/overlay-surface.tsx`, so this block and
+   * the composed modal host draw the same surface. The legacy
+   * `data-size-guide-*` / `data-panel-*` markers stay this block's own: live
+   * storefronts style them and `panel-legacy-golden.json` pins them byte for
+   * byte, which is also what proves the extraction moved nothing.
    */
+  const header = (
+    <>
+      {closeButton}
+      {titleNode}
+    </>
+  );
+
   const modalOverlay = (
-    <div
-      data-size-guide-overlay=""
-      {...partAttrs('overlay', { open: true })}
-      onClick={() => {
-        if (closeOnOverlay) dismiss();
-      }}
-      style={{
-        position: 'fixed',
-        inset: 0,
-        zIndex: 1000,
-        display: 'flex',
-        alignItems: 'center',
-        justifyContent: 'center',
-        padding: '16px',
-        background: 'rgba(0, 0, 0, 0.5)'
+    <CentredModalSurface
+      overlayProps={overlay.overlayProps}
+      ariaLabel={modalTitle || triggerLabel}
+      closeOnOverlay={closeOnOverlay}
+      onDismiss={dismiss}
+      width={modalWidth}
+      anchorAlign={anchorAlign}
+      anchorOffset={anchorOffset}
+      header={header}
+      markers={{
+        root: { 'data-size-guide-overlay': '' },
+        panel: {
+          'data-size-guide-content': '',
+          'data-size-guide-mode': 'modal'
+        }
       }}
     >
-      <div
-        data-size-guide-content=""
-        data-size-guide-mode="modal"
-        {...partAttrs('modal', { open: true })}
-        role="dialog"
-        // Carries the panel ref and the `aria-modal` claim, which is now
-        // made only while this really is the dialog on top. Spread after
-        // `role` so the attribute order stays exactly where it was.
-        //
-        // The primitive asks a panel to carry `tabIndex={-1}` as its focus
-        // target of last resort; this one cannot be given it without
-        // moving markup a published storefront already renders. The gap
-        // only shows in a composition with the close button off AND no
-        // focusable child, where focus simply stays put — the same place
-        // it stayed before the migration.
-        {...overlay.overlayProps}
-        aria-label={modalTitle || triggerLabel}
-        // The backdrop closes the modal; clicks on the panel itself must
-        // not bubble up into that handler.
-        onClick={(event) => event.stopPropagation()}
-        style={{
-          position: 'relative',
-          width: '100%',
-          maxWidth: `${modalWidth}px`,
-          maxHeight: '80vh',
-          overflow: 'auto',
-          padding: '24px',
-          borderRadius: '4px',
-          background: '#ffffff',
-          color: '#111827',
-          textAlign: 'left'
-        }}
-      >
-        {closeButton}
-        {titleNode}
-        {renderChildren()}
-      </div>
-    </div>
+      {renderChildren()}
+    </CentredModalSurface>
   );
 
-  const backdrop = showBackdrop ? (
-    <div
-      data-panel-backdrop=""
-      {...partAttrs('overlay', { open: true })}
-      onClick={() => {
-        if (closeOnOverlay) dismiss();
-      }}
-      style={{
-        position: 'absolute',
-        inset: 0,
-        background: 'rgba(0, 0, 0, 0.5)'
-      }}
-    />
-  ) : null;
-
-  const panelSurface: React.CSSProperties = {
-    overflow: 'auto',
-    padding: '24px',
-    background: '#ffffff',
-    color: '#111827',
-    textAlign: 'left',
-    outline: 'none'
-  };
-
-  const anchorPlacement: React.CSSProperties =
-    anchorAlign === 'center'
-      ? { left: '50%', transform: 'translateX(-50%)' }
-      : anchorAlign === 'end'
-      ? { right: 0 }
-      : { left: 0 };
-
-  const panelGeometry: React.CSSProperties =
-    presentation === 'drawer'
-      ? {
-          position: 'absolute',
-          top: 0,
-          bottom: 0,
-          [panelSide === 'left' ? 'left' : 'right']: 0,
-          width: `min(${modalWidth}px, 92vw)`,
-          boxShadow: '0 0 24px rgba(0, 0, 0, 0.2)'
-        }
-      : presentation === 'sheet'
-      ? {
-          position: 'absolute',
-          left: 0,
-          right: 0,
-          bottom: 0,
-          width: '100%',
-          maxHeight: `${sheetHeight}vh`,
-          boxShadow: '0 -12px 32px rgba(0, 0, 0, 0.18)'
-        }
-      : {
-          // Anchored hangs off the block root rather than a fixed layer, so it
-          // travels with the trigger the way a dropdown must.
-          position: 'absolute',
-          top: `calc(100% + ${anchorOffset}px)`,
-          zIndex: 1000,
-          width: `${modalWidth}px`,
-          maxWidth: '92vw',
-          maxHeight: '80vh',
-          borderRadius: '4px',
-          boxShadow: '0 12px 32px rgba(0, 0, 0, 0.18)',
-          ...anchorPlacement
-        };
-
-  const panel = (
-    <div
-      data-size-guide-content=""
-      data-panel-presentation={presentation}
-      {...partAttrs('modal', { open: true })}
-      role="dialog"
-      // Spread after `role` for the same attribute-order reason the modal
-      // branch documents.
-      {...overlay.overlayProps}
-      aria-label={modalTitle || triggerLabel}
-      // Focus target of last resort, for a panel whose every control the
-      // designer turned off. The centred modal deliberately does without it:
-      // adding it there would move published markup.
-      tabIndex={-1}
-      onClick={(event) => event.stopPropagation()}
-      style={{
-        ...panelSurface,
-        ...panelGeometry,
-        // Turn events back on for the panel itself when the see-through root
-        // below is letting them pass.
-        pointerEvents: showBackdrop ? undefined : 'auto'
+  const layeredOverlay = (
+    <LayeredOverlaySurface
+      presentation={presentation}
+      overlayProps={overlay.overlayProps}
+      ariaLabel={modalTitle || triggerLabel}
+      showBackdrop={showBackdrop}
+      closeOnOverlay={closeOnOverlay}
+      onDismiss={dismiss}
+      width={modalWidth}
+      panelSide={panelSide}
+      sheetHeight={sheetHeight}
+      anchorAlign={anchorAlign}
+      anchorOffset={anchorOffset}
+      header={header}
+      markers={{
+        root: { 'data-panel-root': '' },
+        backdrop: { 'data-panel-backdrop': '' },
+        backdropRoot: { 'data-panel-backdrop-root': '' },
+        panel: {
+          'data-size-guide-content': '',
+          'data-panel-presentation': presentation
+        },
+        handle: { 'data-panel-handle': '' }
       }}
     >
-      {presentation === 'sheet' && (
-        <div
-          data-panel-handle=""
-          {...partAttrs('handle')}
-          style={{
-            width: '40px',
-            height: '4px',
-            margin: '0 auto 12px',
-            borderRadius: '999px',
-            background: '#d1d5db'
-          }}
-        />
-      )}
-      {closeButton}
-      {titleNode}
       {renderChildren()}
-    </div>
+    </LayeredOverlaySurface>
   );
 
-  /**
-   * Drawer and sheet live on a fixed layer over the page; anchored lives in
-   * the block's own flow so it travels with the trigger. With the backdrop off
-   * that fixed layer would still be an invisible sheet of glass over the whole
-   * viewport, so events pass through it and the panel turns them back on for
-   * itself.
-   */
-  const layeredOverlay =
-    presentation === 'anchored' ? (
-      <>
-        {showBackdrop && (
-          <div
-            data-panel-backdrop-root=""
-            style={{ position: 'fixed', inset: 0, zIndex: 999 }}
-          >
-            {backdrop}
-          </div>
-        )}
-        {panel}
-      </>
-    ) : (
-      <div
-        data-panel-root=""
-        style={{
-          position: 'fixed',
-          inset: 0,
-          zIndex: 1000,
-          pointerEvents: showBackdrop ? undefined : 'none'
-        }}
-      >
-        {backdrop}
-        {panel}
-      </div>
-    );
-
   return (
     <div
       data-size-guide=""

package/src/chrome/__tests__/theme-config-source.test.ts

@@ -24,7 +24,8 @@ describe('readThemeConfig', () => {
       })
     ).toEqual({
       settings: { mainMenuSticky: true },
-      dataSources: [{ id: 'ds-1' }]
+      dataSources: [{ id: 'ds-1' }],
+      modals: []
     });
   });
 
@@ -38,7 +39,8 @@ describe('readThemeConfig', () => {
       })
     ).toEqual({
       settings: { mainMenuSticky: true },
-      dataSources: [{ id: 'ds-1' }]
+      dataSources: [{ id: 'ds-1' }],
+      modals: []
     });
   });
 
@@ -52,7 +54,45 @@ describe('readThemeConfig', () => {
       })
     ).toEqual({
       settings: { mainMenuSticky: false },
-      dataSources: [{ id: 'ds-1' }]
+      dataSources: [{ id: 'ds-1' }],
+      modals: []
+    });
+  });
+
+  it('reads the modal registry alongside the rest', () => {
+    expect(
+      readThemeConfig({
+        attributes: {
+          theme_modals: JSON.stringify([
+            { id: 'newsletter', name: 'Newsletter', presentation: 'drawer' }
+          ])
+        }
+      })
+    ).toEqual({
+      settings: null,
+      dataSources: [],
+      modals: [
+        {
+          id: 'newsletter',
+          name: 'Newsletter',
+          slug: 'modal-newsletter',
+          presentation: 'drawer',
+          chrome: {
+            ariaLabel: 'Newsletter',
+            showClose: true,
+            closeLabel: 'Close',
+            showBackdrop: true,
+            closeOnBackdrop: true,
+            closeOnEscape: true,
+            width: 640,
+            panelSide: 'right',
+            sheetHeight: 60,
+            lockScroll: true
+          },
+          autoTrigger: undefined,
+          visibilityRules: undefined
+        }
+      ]
     });
   });
 
@@ -66,16 +106,21 @@ describe('readThemeConfig', () => {
           theme_dataSources: JSON.stringify([{ id: 'ds-1' }])
         }
       })
-    ).toEqual({ settings: null, dataSources: [{ id: 'ds-1' }] });
+    ).toEqual({ settings: null, dataSources: [{ id: 'ds-1' }], modals: [] });
 
     error.mockRestore();
   });
 
   it('answers empty for a brand with no theme at all', () => {
-    expect(readThemeConfig(null)).toEqual({ settings: null, dataSources: [] });
+    expect(readThemeConfig(null)).toEqual({
+      settings: null,
+      dataSources: [],
+      modals: []
+    });
     expect(readThemeConfig({ attributes: {} })).toEqual({
       settings: null,
-      dataSources: []
+      dataSources: [],
+      modals: []
     });
   });
 });
@@ -90,7 +135,8 @@ describe('getThemeConfig', () => {
 
     await expect(getThemeConfig()).resolves.toEqual({
       settings: null,
-      dataSources: []
+      dataSources: [],
+      modals: []
     });
   });
 });

package/src/chrome/placeholder-slugs.ts

@@ -79,6 +79,47 @@ export type PlaceholderSlug =
 /** Custom pages created from the editor resolve to `page-<slug>` */
 export const customPageSlug = (slug: string) => `page-${slug}`;
 
+/**
+ * Modals created from the editor resolve to `modal-<id>`.
+ *
+ * A modal is the one composable surface with no route behind it: the designer
+ * creates it, names it, and opens it from anywhere. So its slug is derived from
+ * a GENERATED id rather than from the name — renaming "Newsletter" to "Sign up"
+ * must not orphan the composition saved under it — and never from a path,
+ * because a modal has none.
+ */
+export const MODAL_SLUG_PREFIX = 'modal-';
+
+/**
+ * Ids this slug family accepts. Deliberately a REFUSAL rather than the
+ * sanitising the path-derived helper above does.
+ *
+ * Sanitising maps several inputs onto one output, and for a content key that is
+ * not a tidy-up, it is a collision: two modals whose ids differ only by a
+ * character the cleaner strips would share one slug and silently overwrite each
+ * other's composition — the exact failure the table at the top of this file
+ * exists to prevent. The ids are ours (the editor generates them), so anything
+ * failing this pattern is a bug upstream and is better refused loudly than
+ * rewritten quietly.
+ */
+const MODAL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+/** `null` for an id this family cannot address — callers skip that modal. */
+export const modalSlug = (id: string): string | null =>
+  MODAL_ID_PATTERN.test(id) ? `${MODAL_SLUG_PREFIX}${id}` : null;
+
+export const isModalSlug = (slug: string): boolean =>
+  typeof slug === 'string' && slug.startsWith(MODAL_SLUG_PREFIX);
+
+/** The inverse of `modalSlug`, for turning a placeholder back into a modal id. */
+export const modalIdFromSlug = (slug: string): string | null => {
+  if (!isModalSlug(slug)) return null;
+
+  const id = slug.slice(MODAL_SLUG_PREFIX.length);
+
+  return MODAL_ID_PATTERN.test(id) ? id : null;
+};
+
 /**
  * Slug for a brand page that has no canonical placeholder — every bespoke
  * content route (about us, campaigns, returns policy…) gets one derived from