@akinon/pz-theme 2.0.94 → 2.0.95-beta.1

package/src/overlays/overlay-surface.tsx

@@ -478,6 +478,21 @@ export interface OverlaySurfaceProps extends OverlayGeometryInput {
   chromeCss?: string;
   /** Rendered inside the panel, above the authored content. */
   header?: React.ReactNode;
+  /**
+   * Drawn over the panel while the composition is still committing — see
+   * `overlay-loading.tsx` for why a large one needs it.
+   *
+   * A node rather than a flag because only the composed modal host has one:
+   * the panel block passes nothing, so its markup — pinned byte for byte by
+   * `panel-legacy-golden.json` — cannot move.
+   */
+  loading?: React.ReactNode;
+  /**
+   * Marks the dialog as still filling. The attribute is the accessible half of
+   * `loading`: a wordless spinner tells a screen reader nothing, `aria-busy`
+   * tells it exactly what is happening. Absent leaves no attribute at all.
+   */
+  panelBusy?: boolean;
   children: React.ReactNode;
   /**
    * Legacy marker attributes per node. Order matters: they are spread BEFORE
@@ -530,6 +545,8 @@ export const CentredModalSurface = ({
   topInset,
   chromeCss,
   header,
+  loading,
+  panelBusy,
   children,
   markers
 }: Omit<
@@ -565,6 +582,7 @@ export const CentredModalSurface = ({
       role="dialog"
       {...overlayProps}
       aria-label={ariaLabel}
+      {...(panelBusy ? { 'aria-busy': true as const } : null)}
       // The backdrop closes the modal; clicks on the panel itself must not
       // bubble up into that handler.
       onClick={(event) => event.stopPropagation()}
@@ -593,6 +611,7 @@ export const CentredModalSurface = ({
         <style dangerouslySetInnerHTML={{ __html: chromeCss }} />
       ) : null}
       {header}
+      {loading}
       {children}
     </div>
   </div>
@@ -626,6 +645,8 @@ export const LayeredOverlaySurface = ({
   topInset,
   chromeCss,
   header,
+  loading,
+  panelBusy,
   children,
   markers
 }: OverlaySurfaceProps) => {
@@ -652,6 +673,7 @@ export const LayeredOverlaySurface = ({
       role="dialog"
       {...overlayProps}
       aria-label={ariaLabel}
+      {...(panelBusy ? { 'aria-busy': true as const } : null)}
       // Focus target of last resort, for a panel whose every control the
       // designer turned off.
       tabIndex={-1}
@@ -685,6 +707,7 @@ export const LayeredOverlaySurface = ({
         <OverlaySheetHandle markerAttrs={markers?.handle} />
       )}
       {header}
+      {loading}
       {children}
     </div>
   );

package/src/overlays/overlay-tokens.ts

@@ -33,6 +33,18 @@ export const OVERLAY_WIDTH_UNITS: OverlayWidthUnit[] = ['px', '%', 'vw'];
 export const OVERLAY_BACKDROP_COLOR = '#000000';
 export const OVERLAY_BACKDROP_OPACITY = 50;
 
+/**
+ * How long a panel may be empty before its loading mark fades in, in ms, and
+ * the longest delay a designer may ask for.
+ *
+ * Here rather than beside the layer that animates it for the reason at the top
+ * of this file: the REGISTRY clamps the authored value, and the registry is
+ * parsed on the server. `overlay-loading.tsx` re-exports both so client
+ * callers keep one import path.
+ */
+export const OVERLAY_LOADING_DELAY = 150;
+export const OVERLAY_LOADING_DELAY_MAX = 2000;
+
 /**
  * How tall a sheet is, and what a designer is allowed to write for it.
  *

package/src/overlays/theme-modal-mount.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import React, { useEffect, useRef } from 'react';
+import React, { startTransition, useEffect, useRef, useState } from 'react';
 
 import { useOverlay } from '../hooks/use-overlay';
 import { useVisibilityContext } from '../hooks/use-visibility-context';
@@ -18,6 +18,8 @@ import {
   LayeredOverlaySurface,
   OverlayCloseButton
 } from './overlay-surface';
+import { OverlayLoadingLayer } from './overlay-loading';
+import { ModalHostIdProvider } from './modal-host-context';
 import { useEditorKnowsModal } from './use-editor-modals';
 import { useModalPreview } from './use-modal-preview';
 import { useOverlayBreakpoint } from './use-overlay-breakpoint';
@@ -134,6 +136,53 @@ const ThemeModalMount = ({
     isDesigner ? breakpoint : undefined
   );
 
+  /**
+   * Whether the composition is revealed in its own commit, with a loading
+   * layer under it until it lands.
+   *
+   * Never in the canvas: a designer composing a modal must see their blocks
+   * the instant they select it, and the editor's own render is not the commit
+   * this is about.
+   */
+  const showsLoading = chrome.showLoading !== false && !isEditing;
+  const [revealed, setRevealed] = useState(!showsLoading);
+
+  /**
+   * A TRANSITION, not a timer.
+   *
+   * The pause this covers is the commit itself: a composed modal's content
+   * ships with the page, so opening a large one — ninety blocks, a text block
+   * carrying half a megabyte of pasted markup — is one long synchronous render
+   * during which nothing at all can be scheduled, a `setTimeout` that would
+   * show a spinner least of all. Rendering the composition at transition
+   * priority splits it off the urgent commit that draws the panel, so the
+   * panel and the loading layer paint first and the browser is free in
+   * between.
+   *
+   * It costs the fast path one extra commit and nothing visible: the layer is
+   * invisible for its first `loadingDelay` ms, which a small composition has
+   * long since outrun. And because `act()` flushes transitions, a test that
+   * opens a modal still sees its content in the same tick.
+   *
+   * Reset on close so a reopen starts from the cheap commit again — the bus is
+   * module state, so a mount lives far longer than one open.
+   */
+  useEffect(() => {
+    if (!showsLoading) {
+      setRevealed(true);
+
+      return;
+    }
+
+    if (!opened) {
+      setRevealed(false);
+
+      return;
+    }
+
+    startTransition(() => setRevealed(true));
+  }, [opened, showsLoading]);
+
   /**
    * In the canvas the overlay is fully inert: it never steals focus into the
    * page the designer is styling, never freezes it, never claims `aria-modal`
@@ -148,8 +197,17 @@ const ThemeModalMount = ({
     // be a lie.
     modal: isCentred ? true : chrome.showBackdrop,
     lockScroll: chrome.lockScroll && (isCentred || chrome.showBackdrop),
-    closeOnEscape: chrome.closeOnEscape,
-    fallbackFocusRef: rootRef
+    closeOnEscape: chrome.closeOnEscape
+    /**
+     * No `fallbackFocusRef` on purpose. It used to point at `rootRef`, which
+     * cannot take focus (the div carries no `tabIndex={-1}`) and is detached
+     * by the time the hand-back runs anyway — `if (!opened) return null`
+     * removes it in the same commit that closes the modal. `useOverlay`
+     * verifies that focus actually landed, so the branch was dead; naming a
+     * target that cannot work only hides the real gap, which is a modal
+     * nobody clicked open (an auto-triggered popup) having no opener to hand
+     * focus back to.
+     */
   });
 
   if (!opened) return null;
@@ -171,6 +229,20 @@ const ThemeModalMount = ({
 
   const ariaLabel = chrome.ariaLabel || modal.name;
 
+  /**
+   * The layer, and the composition it stands in for. Both are absent once the
+   * composition has landed, so nothing is drawn over it and no attribute is
+   * left claiming the dialog is still filling.
+   */
+  const loading =
+    showsLoading && !revealed ? (
+      <OverlayLoadingLayer
+        label={chrome.loadingLabel}
+        delay={chrome.loadingDelay}
+      />
+    ) : null;
+  const body = revealed ? children : null;
+
   const surface = isCentred ? (
     <CentredModalSurface
       overlayProps={overlay.overlayProps}
@@ -186,8 +258,10 @@ const ThemeModalMount = ({
       topInset={chrome.topInset}
       chromeCss={chromeCss}
       header={header}
+      loading={loading}
+      panelBusy={Boolean(loading)}
     >
-      {children}
+      {body}
     </CentredModalSurface>
   ) : (
     <LayeredOverlaySurface
@@ -209,8 +283,10 @@ const ThemeModalMount = ({
       panelStretch={chrome.stretchContent}
       chromeCss={chromeCss}
       header={header}
+      loading={loading}
+      panelBusy={Boolean(loading)}
     >
-      {children}
+      {body}
     </LayeredOverlaySurface>
   );
 
@@ -224,7 +300,10 @@ const ThemeModalMount = ({
       data-theme-modal={modal.id}
       data-theme-modal-state="open"
     >
-      {surface}
+      {/* Tells the composition which modal it is inside, so a form that
+          finishes can close THIS one — see `modal-host-context.tsx`. Renders
+          no element, so the published markup is untouched. */}
+      <ModalHostIdProvider value={modal.id}>{surface}</ModalHostIdProvider>
     </div>
   );
 };

package/src/utils/visibility-rules.ts

@@ -532,6 +532,109 @@ export const evaluateVisibilityRules = (
 const isVisibilityRuleExempt = (node: Block | Section): boolean =>
   containsCheckoutOutlet(node);
 
+
+/**
+ * A per-breakpoint value, read the way the renderers read one.
+ *
+ * A local reader rather than `getResponsiveValue` from `../utils`: this module
+ * is pure and is walked on the server read path, and that barrel pulls in the
+ * React helpers.
+ */
+const readResponsive = (value: unknown, breakpoint?: string): unknown => {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return value;
+  }
+
+  const record = value as Record<string, unknown>;
+  const chain = [
+    breakpoint,
+    ...(breakpoint ? BREAKPOINT_FALLBACKS[breakpoint] ?? [] : []),
+    'desktop'
+  ];
+
+  for (const key of chain) {
+    if (key && record[key] !== undefined) return record[key];
+  }
+
+  return undefined;
+};
+
+/**
+ * Who a block's ACTION is for.
+ *
+ * Visibility already answers "who is this block for"; this answers the same
+ * question about the action wired onto it, which is not the same thing. The
+ * account button is the case that forced it: it renders its own link — to the
+ * account for a member, to the login page for a guest — while a designer wires
+ * "open the login drawer" onto the block itself. Both then fire on one click,
+ * so a signed-in shopper landed on their account page with the login drawer
+ * open over it.
+ *
+ * Resolved HERE, in the pass that already knows who the shopper is, rather
+ * than in `use-block-action`: that hook runs for every block on the page, and
+ * making it read the session would make a SessionProvider mandatory for the
+ * whole theme rather than for the placeholder wrapper that already has one.
+ */
+export const BLOCK_ACTION_AUDIENCES = ['all', 'guest', 'authenticated'] as const;
+
+export type BlockActionAudience = (typeof BLOCK_ACTION_AUDIENCES)[number];
+
+const MODAL_ACTION_TYPES = new Set([
+  'open-modal',
+  'close-modal',
+  'toggle-modal'
+]);
+
+/**
+ * The audience a block's action is scoped to.
+ *
+ * Absent means `all`, EXCEPT for an account button opening a modal: a member
+ * clicking their own account button never wants the login drawer, so the
+ * default there is `guest`. That is a behaviour change on published
+ * compositions, and a deliberate one — the alternative is the drawer covering
+ * the account page it just navigated to. A brand that really wants it for
+ * everyone says `all`.
+ */
+const resolveActionAudience = (
+  block: Block,
+  currentBreakpoint?: string
+): BlockActionAudience => {
+  const authored = String(
+    readResponsive(block.properties?.actionAudience, currentBreakpoint) ?? ''
+  ).trim();
+
+  if ((BLOCK_ACTION_AUDIENCES as readonly string[]).includes(authored)) {
+    return authored as BlockActionAudience;
+  }
+
+  const actionType = String(
+    readResponsive(block.properties?.actionType, currentBreakpoint) ?? ''
+  ).trim();
+
+  if (block.type === 'account-button' && MODAL_ACTION_TYPES.has(actionType)) {
+    return 'guest';
+  }
+
+  return 'all';
+};
+
+/**
+ * Whether the action runs for this shopper.
+ *
+ * `loading` counts as a guest: the session is unknown for the first client
+ * render, and withholding the login drawer through it would break the common
+ * case to fix the rare one.
+ */
+const actionRunsFor = (
+  audience: BlockActionAudience,
+  authState: unknown
+): boolean => {
+  if (audience === 'all') return true;
+  if (audience === 'authenticated') return authState === 'authenticated';
+
+  return authState !== 'authenticated';
+};
+
 const applyBlockVisibility = (
   block: Block,
   context: VisibilityRuleContext
@@ -541,8 +644,19 @@ const applyBlockVisibility = (
     isVisibilityRuleExempt(block) ||
     evaluateVisibilityRules(block.properties?.visibilityRules, context);
 
+  /**
+   * An action this shopper is not the audience for is REMOVED rather than
+   * ignored at click time, so the wrapper never claims `aria-haspopup="dialog"`
+   * for a dialog it will not open either.
+   */
+  const audience = resolveActionAudience(block, context.breakpoint);
+  const properties = actionRunsFor(audience, context.authState)
+    ? block.properties
+    : { ...(block.properties || {}), actionType: 'none' };
+
   return {
     ...block,
+    properties,
     hidden: Boolean(block.hidden) || !isVisibleByRules,
     blocks
   };