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

package/src/overlays/modal-preview-host.tsx

@@ -10,6 +10,7 @@ import {
   OverlayCloseButton,
   OverlayHandleProps
 } from './overlay-surface';
+import { ModalHostIdProvider } from './modal-host-context';
 import ThemeModalMount from './theme-modal-mount';
 import { useEditorModals } from './use-editor-modals';
 import { useHeldModal } from './use-modal-preview';
@@ -167,7 +168,9 @@ export const ModalPreviewHost = ({
         chromeCss={chromeCss}
         header={header}
       >
-        {composition(modal.slug)}
+        <ModalHostIdProvider value={modal.id}>
+          {composition(modal.slug)}
+        </ModalHostIdProvider>
       </CentredModalSurface>
     ) : (
       <LayeredOverlaySurface
@@ -193,7 +196,9 @@ export const ModalPreviewHost = ({
         chromeCss={chromeCss}
         header={header}
       >
-        {composition(modal.slug)}
+        <ModalHostIdProvider value={modal.id}>
+          {composition(modal.slug)}
+        </ModalHostIdProvider>
       </LayeredOverlaySurface>
     );
 

package/src/overlays/modal-registry.ts

@@ -7,6 +7,7 @@ import type { VisibilityRules } from '../utils/visibility-rules';
 import {
   OVERLAY_BACKDROP_COLOR,
   OVERLAY_BACKDROP_OPACITY,
+  OVERLAY_LOADING_DELAY_MAX,
   OVERLAY_WIDTH_UNITS,
   SHEET_HEIGHT_FALLBACK,
   isSheetHeightLength,
@@ -152,6 +153,30 @@ export interface ModalChrome {
    */
   closeText?: string;
   closeTextSide?: 'before' | 'after';
+  /**
+   * Whether the panel shows a loading mark while its composition is still
+   * committing. Absent reads as ON, which cannot change how a published modal
+   * looks: the layer is invisible for its first `loadingDelay` ms, and a
+   * composition that commits in the same frame — every small one — has
+   * revealed itself long before that. What it buys is the large ones, where
+   * the panel's white surface is on screen for a beat with nothing in it.
+   *
+   * Off restores the single commit: the composition renders with the panel and
+   * nothing is drawn over it.
+   */
+  showLoading?: boolean;
+  /**
+   * How long the panel may be empty before the mark fades in, in ms. Absent
+   * means the historical-safe 150 — see `OVERLAY_LOADING_DELAY`.
+   */
+  loadingDelay?: number;
+  /**
+   * Words beside the mark. Absence-preserving for the same reason as
+   * `closeText`, and for one more: this package has no dictionary, so a
+   * default would be an English string on every storefront. Authored text is
+   * the only text.
+   */
+  loadingLabel?: string;
 }
 
 /**
@@ -602,7 +627,19 @@ const readChrome = (value: unknown, name: string): ModalChrome => {
     // a close text must not come out of here claiming an empty one, and the
     // side only means something once the text exists.
     closeText: asString(raw.closeText) || undefined,
-    closeTextSide: raw.closeTextSide === 'before' ? 'before' : undefined
+    closeTextSide: raw.closeTextSide === 'before' ? 'before' : undefined,
+    // Absent reads as on: the layer is invisible until the delay has passed,
+    // so turning it on for every published modal changes nothing a shopper
+    // sees except on the modals that were already keeping them waiting.
+    showLoading: asToggle(raw.showLoading, true),
+    // Read, not defaulted, on the same grounds as `padding`: 0 is a real
+    // answer ("show it at once"), so absence has to stay distinguishable.
+    loadingDelay: asOptionalClamped(
+      raw.loadingDelay,
+      0,
+      OVERLAY_LOADING_DELAY_MAX
+    ),
+    loadingLabel: asString(raw.loadingLabel) || undefined
   };
 };
 

package/src/overlays/overlay-loading.tsx

@@ -0,0 +1,144 @@
+'use client';
+
+import React from 'react';
+import { partAttrs } from '../utils';
+import { OVERLAY_LOADING_DELAY } from './overlay-tokens';
+
+/**
+ * What a modal shows while its composition is still arriving.
+ *
+ * The gap this exists for is not a fetch — a composed modal's content ships
+ * with the page, in the layout's payload — it is the COMMIT. Opening a drawer
+ * mounts the whole composition at once, and a large one (ninety blocks, a
+ * text block carrying half a megabyte of pasted markup) takes long enough
+ * that the panel's own white surface is on screen well before anything is in
+ * it. A shopper reads that as a broken drawer, which is why the host reveals
+ * the composition in a transition and puts this underneath in the meantime:
+ * the panel and this layer are the cheap commit, and they paint immediately.
+ *
+ * Two consequences follow from "the main thread is busy" and both shape the
+ * implementation:
+ *
+ *  - The reveal is a CSS animation, not a timer. A `setTimeout` scheduled to
+ *    show a spinner cannot fire while the thread it lives on is committing
+ *    the very tree it is waiting for.
+ *  - The layer carries no shopper-facing copy of its own. pz-theme has no
+ *    dictionary — it renders authored text — so an invented "Loading…" would
+ *    be an untranslatable English string on every storefront. The dialog
+ *    carries `aria-busy` instead, and a designer who wants words authors them.
+ */
+
+/**
+ * Re-exported from `overlay-tokens.ts`, which owns them so the server-side
+ * registry can clamp the authored delay without importing this client module.
+ *
+ * `OVERLAY_LOADING_DELAY` is long enough that a composition which commits in
+ * the same frame — the common case, and the one this must not disturb — never
+ * flashes a spinner, and short enough that it is not itself the pause it
+ * exists to explain.
+ */
+export {
+  OVERLAY_LOADING_DELAY,
+  OVERLAY_LOADING_DELAY_MAX
+} from './overlay-tokens';
+
+/** How long the layer takes to fade in once the delay has passed. */
+const OVERLAY_LOADING_FADE = 120;
+
+/**
+ * The reveal and the spin. Keyframes cannot be written inline, and the
+ * `prefers-reduced-motion` answer cannot either — a shopper who asked for
+ * less motion still gets the affordance, just still.
+ *
+ * Scoped through the layer's own part attribute rather than emitted bare, so
+ * a page with two overlays up does not have two authors for one selector.
+ */
+const OVERLAY_LOADING_CSS = [
+  '@keyframes pz-overlay-loading-in{from{opacity:0}to{opacity:1}}',
+  '@keyframes pz-overlay-loading-spin{from{transform:rotate(0)}to{transform:rotate(360deg)}}',
+  '@media (prefers-reduced-motion: reduce){' +
+    '[data-part="loading"] [data-part="loading-mark"]{animation:none}}'
+].join('');
+
+export interface OverlayLoadingLayerProps {
+  /**
+   * Visible text beside the mark, if the designer authored one. Absent means
+   * the mark alone — see the note on copy above.
+   */
+  label?: string;
+  /** ms before the layer fades in. See `OVERLAY_LOADING_DELAY`. */
+  delay?: number;
+}
+
+/**
+ * The layer itself: a mark centred in the panel, invisible for its first
+ * `delay` ms.
+ *
+ * In FLOW, not absolutely positioned, and that is deliberate: the panel is
+ * `overflow: auto`, so `inset: 0` would anchor to the scrollable content box
+ * and scroll away rather than stay centred — and a stretched panel is a flex
+ * column, where an out-of-flow child leaves the column with nothing to size.
+ * In flow, `flex: 1 1 auto` fills a stretched drawer and `min-height` gives a
+ * centred dialog something to be while it is empty. Nothing is drawn over the
+ * composition either way: the host renders one or the other, never both.
+ *
+ * Inert regardless, because the panel underneath is already listening for
+ * clicks it must keep receiving.
+ */
+export const OverlayLoadingLayer = ({
+  label,
+  delay = OVERLAY_LOADING_DELAY
+}: OverlayLoadingLayerProps) => (
+  <div
+    {...partAttrs('loading')}
+    /**
+     * Hidden from assistive tech when it is a bare spinner: the dialog's own
+     * `aria-busy` is the fact a screen reader needs, and a wordless status
+     * region announced the instant a drawer opens talks over the dialog's
+     * name. Authored text is real content and stays readable.
+     */
+    aria-hidden={label ? undefined : true}
+    style={{
+      display: 'flex',
+      // Fills a stretched panel, and is ignored by one that is not a flex
+      // column — where the min-height is what keeps the mark off the top edge.
+      flex: '1 1 auto',
+      minHeight: '160px',
+      flexDirection: 'column',
+      alignItems: 'center',
+      justifyContent: 'center',
+      gap: '12px',
+      pointerEvents: 'none',
+      opacity: 0,
+      animation:
+        `pz-overlay-loading-in ${OVERLAY_LOADING_FADE}ms linear ` +
+        `${delay}ms forwards`
+    }}
+  >
+    <style dangerouslySetInnerHTML={{ __html: OVERLAY_LOADING_CSS }} />
+    <span
+      {...partAttrs('loading-mark')}
+      style={{
+        width: '24px',
+        height: '24px',
+        borderRadius: '999px',
+        // `currentColor` so the mark inherits the panel's text colour: a
+        // designer who darkened the panel does not also have to restyle this.
+        border: '2px solid currentColor',
+        borderTopColor: 'transparent',
+        opacity: 0.45,
+        animation: 'pz-overlay-loading-spin 700ms linear infinite'
+      }}
+    />
+    {label ? (
+      <span
+        {...partAttrs('loading-text')}
+        style={{ fontSize: '13px', opacity: 0.7 }}
+      >
+        {label}
+      </span>
+    ) : null}
+  </div>
+);
+
+export default OverlayLoadingLayer;

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
   };