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

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

@@ -0,0 +1,179 @@
+'use client';
+
+import React, { useEffect, useRef } from 'react';
+
+import { useOverlay } from '../hooks/use-overlay';
+import { useVisibilityContext } from '../hooks/use-visibility-context';
+import { useBrowseMode } from '../browse-mode';
+import { evaluateVisibilityRules } from '../utils/visibility-rules';
+import { closeModal, useModalOpen } from './overlay-bus';
+import { ThemeModal } from './modal-registry';
+import {
+  CentredModalSurface,
+  LayeredOverlaySurface,
+  OverlayCloseButton
+} from './overlay-surface';
+import { useEditorKnowsModal } from './use-editor-modals';
+import { useModalPreview } from './use-modal-preview';
+import { useOverlayBreakpoint } from './use-overlay-breakpoint';
+import { useModalAutoTrigger } from './use-modal-auto-trigger';
+
+interface ThemeModalMountProps {
+  modal: ThemeModal;
+  /** The composition, already rendered on the server. */
+  children: React.ReactNode;
+  /**
+   * Where this mount's registry entry came from.
+   *
+   * A `saved` mount stands down while the editor is attached and knows this
+   * modal, because the editor's copy is the authority then — it carries chrome
+   * the designer is changing right now, and may describe a modal the backend
+   * has never heard of. `ModalPreviewHost` renders an `editor` mount in its
+   * place. Without the distinction the replacement would read "the editor owns
+   * this" about itself and both would stand down, leaving nothing.
+   */
+  origin?: 'saved' | 'editor';
+}
+
+const isDesignerWindow = () =>
+  typeof window !== 'undefined' &&
+  (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner === true;
+
+/**
+ * One composed modal: the bus decides whether it is open, `useOverlay` decides
+ * what being open costs the page, and `overlay-surface` draws it.
+ *
+ * The children arrive already rendered by the server and are mounted only
+ * while the modal is open. That is the whole reason the host can afford to
+ * declare every modal a theme has: a closed one costs the page nothing but the
+ * bytes of its markup, and never appears in the accessibility tree, in the tab
+ * order, or as duplicate content behind the page.
+ */
+const ThemeModalMount = ({
+  modal,
+  children,
+  origin = 'saved'
+}: ThemeModalMountProps) => {
+  const isOpen = useModalOpen(modal.id);
+  const breakpoint = useOverlayBreakpoint();
+  const rootRef = useRef<HTMLDivElement | null>(null);
+
+  /**
+   * Held open by the editor. This mount then stands down entirely and
+   * `ModalPreviewHost` draws the surface instead, from the live entry rather
+   * than from the saved one.
+   *
+   * Standing down is not an optimisation: both would render a
+   * `ThemePlaceholderWrapper` for the same slug, and two wrappers claiming one
+   * slug means the region registers twice and the editor sees the modal's
+   * contents doubled.
+   */
+  const isPreviewing = useModalPreview(modal.id);
+  const editorOwnsModal = useEditorKnowsModal(modal.id);
+  const isDesigner = isDesignerWindow();
+  const isBrowseMode = useBrowseMode();
+  const isEditing = isDesigner && !isBrowseMode;
+
+  const visibilityContext = useVisibilityContext(breakpoint, {
+    isDesigner: isEditing
+  });
+  const existsHere = evaluateVisibilityRules(
+    modal.visibilityRules,
+    visibilityContext
+  );
+
+  /**
+   * A modal that is not on this page must not be left open by a route change
+   * that carried it out of scope — the bus is module state and survives
+   * client-side navigation, so nothing else would close it and the shopper
+   * would be looking at an overlay belonging to a page they have left.
+   */
+  useEffect(() => {
+    if (!existsHere && isOpen) closeModal(modal.id);
+  }, [existsHere, isOpen, modal.id]);
+
+  useModalAutoTrigger({
+    modal,
+    enabled: existsHere && !isEditing,
+    visibilityContext
+  });
+
+  // Superseded by the editor's own copy of this modal. See `origin`.
+  const supersededByEditor = origin === 'saved' && editorOwnsModal;
+
+  const opened = !isPreviewing && !supersededByEditor && isOpen && existsHere;
+  const { chrome, presentation } = modal;
+  const isCentred = presentation === 'modal';
+
+  /**
+   * 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`
+   * and never answers Escape. The primitive does all of that off one flag.
+   */
+  const overlay = useOverlay<HTMLDivElement>({
+    open: opened,
+    onClose: () => closeModal(modal.id),
+    isDesigner: isEditing,
+    // A centred modal really does cover the page. The others make the claim
+    // only behind a backdrop, because with the page still clickable it would
+    // be a lie.
+    modal: isCentred ? true : chrome.showBackdrop,
+    lockScroll: chrome.lockScroll && (isCentred || chrome.showBackdrop),
+    closeOnEscape: chrome.closeOnEscape,
+    fallbackFocusRef: rootRef
+  });
+
+  if (!opened) return null;
+
+  const dismiss = () => closeModal(modal.id);
+
+  const header = chrome.showClose ? (
+    <OverlayCloseButton label={chrome.closeLabel} onClick={dismiss} />
+  ) : null;
+
+  const ariaLabel = chrome.ariaLabel || modal.name;
+
+  const surface = isCentred ? (
+    <CentredModalSurface
+      overlayProps={overlay.overlayProps}
+      ariaLabel={ariaLabel}
+      closeOnOverlay={chrome.closeOnBackdrop}
+      onDismiss={dismiss}
+      width={chrome.width}
+      header={header}
+    >
+      {children}
+    </CentredModalSurface>
+  ) : (
+    <LayeredOverlaySurface
+      presentation={presentation}
+      overlayProps={overlay.overlayProps}
+      ariaLabel={ariaLabel}
+      showBackdrop={chrome.showBackdrop}
+      closeOnOverlay={chrome.closeOnBackdrop}
+      onDismiss={dismiss}
+      width={chrome.width}
+      panelSide={chrome.panelSide}
+      sheetHeight={chrome.sheetHeight}
+      header={header}
+    >
+      {children}
+    </LayeredOverlaySurface>
+  );
+
+  return (
+    <div
+      ref={rootRef}
+      // The id a trigger's `aria-controls` points at. It exists only while the
+      // modal is mounted, which is why the trigger only claims the reference
+      // while the modal is open.
+      id={`theme-modal-${modal.id}`}
+      data-theme-modal={modal.id}
+      data-theme-modal-state="open"
+    >
+      {surface}
+    </div>
+  );
+};
+
+export default ThemeModalMount;

package/src/overlays/theme-modals.tsx

@@ -0,0 +1,82 @@
+import React from 'react';
+
+import ThemePlaceholder from '../theme-placeholder';
+import { getThemeConfig } from '../chrome/theme-config-source';
+import ThemeModalMount from './theme-modal-mount';
+import { ModalHostBeacon } from './modal-host-beacon';
+import ModalPreviewHost from './modal-preview-host';
+
+interface ThemeModalsProps {
+  /**
+   * Commerce data the composed blocks read, built with the same
+   * `chrome/page-context` helpers a ChromeSlot uses. A modal mounted in the
+   * root layout has no page of its own, so a brand that wants product-aware
+   * modals passes the context down from the page that has one.
+   */
+  pageContext?: Record<string, unknown> | null;
+}
+
+/**
+ * Every composed modal this theme has, mounted once for the page.
+ *
+ * Mount it in the brand's ROOT LAYOUT, next to the footer ChromeSlot:
+ *
+ *     <ThemeModals />
+ *
+ * It is an async server component, so — exactly like `ChromeSlot` — it cannot
+ * be used inside a client page. The layout is also the right home for a
+ * different reason: a modal is opened from the header as often as from the
+ * body, so it must outlive any one page's tree.
+ *
+ * Cost when a theme has no modals is a single object read from the
+ * `theme-config` widget that every page already fetches and memoizes, and this
+ * renders nothing at all.
+ */
+export default async function ThemeModals({
+  pageContext = null
+}: ThemeModalsProps) {
+  const { modals, dataSources, settings } = await getThemeConfig();
+
+  /**
+   * Every modal is fetched with the page, closed, and its content is mounted
+   * only when it opens.
+   *
+   * Route scoping is deliberately NOT applied here. `visibilityRules` read the
+   * pathname, the auth state and the breakpoint, and the layout this renders
+   * in has none of those reliably — deciding server-side would bake one page's
+   * answer into every page. The mount evaluates them client-side, exactly the
+   * way sections already do.
+   *
+   * The cost is therefore two widget reads per modal per page. That is fine
+   * for the handful of modals a theme actually has and would not be for
+   * twenty; when a theme gets there, the fix is server-side route scoping on
+   * the registry entry, not a client-side fetch that would have to reimplement
+   * the v1 schema fallback in `theme-placeholder.tsx`.
+   */
+  return (
+    <>
+      {/* Tells a trigger that the host exists, so an unmounted host is a
+          named warning instead of a button that does nothing. */}
+      <ModalHostBeacon />
+      {modals.map((modal) => (
+        <ThemeModalMount key={modal.id} modal={modal}>
+          <ThemePlaceholder slug={modal.slug} pageContext={pageContext} />
+        </ThemeModalMount>
+      ))}
+      {/*
+        Rendered even when the theme has no saved modals, which is precisely
+        when it matters most: the first modal a designer creates exists only in
+        the editor, and returning early on an empty registry would leave them
+        composing against a canvas that can never show it.
+
+        Costs a shopper nothing — it renders null unless the editor is holding
+        a modal open, and only the editor can ask.
+      */}
+      <ModalPreviewHost
+        dataSources={dataSources}
+        themeSettings={settings}
+        pageContext={pageContext}
+      />
+    </>
+  );
+}

package/src/overlays/use-editor-modals.ts

@@ -0,0 +1,109 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { parseEditorMessage } from '../editor-bridge';
+import { readThemeModals, ThemeModal } from './modal-registry';
+
+/**
+ * The modal registry as the EDITOR currently has it.
+ *
+ * The editor already sends its whole theme on `LOAD_THEME` and every
+ * `UPDATE_THEME`, modals included; this reads the field the preview used to
+ * throw away. Without it the registry could only ever come from
+ * `theme-config`, which made composed modals behave unlike everything else on
+ * the page: a section appears as you add it, but a modal did not exist until
+ * it was saved AND the preview was reloaded by hand — and a trigger pointed at
+ * one simply did nothing, with no way to tell a missing modal from a broken
+ * trigger.
+ *
+ * Module state, like the overlay bus and for the same reason: several mounts
+ * across different React roots must agree on one answer.
+ */
+let editorModals: ThemeModal[] = [];
+
+/**
+ * Serialized form of the registry. `UPDATE_THEME` arrives on every keystroke
+ * anywhere in the theme, and almost none of those touch a modal — comparing
+ * here keeps the whole modal layer from re-rendering at typing speed.
+ */
+let signature = '';
+
+const listeners = new Set<() => void>();
+
+const setEditorModals = (modals: ThemeModal[]) => {
+  const next = JSON.stringify(modals);
+  if (next === signature) return;
+
+  signature = next;
+  editorModals = modals;
+  listeners.forEach((listener) => listener());
+};
+
+let listening = false;
+
+const startListening = () => {
+  if (listening || typeof window === 'undefined') return;
+  listening = true;
+
+  window.addEventListener('message', (event: MessageEvent) => {
+    const message = parseEditorMessage(event);
+    if (!message) return;
+    if (message.type !== 'LOAD_THEME' && message.type !== 'UPDATE_THEME') {
+      return;
+    }
+
+    const theme = (message.data as { theme?: { modals?: unknown } } | undefined)
+      ?.theme;
+    if (!theme) return;
+
+    /**
+     * Read through the same normaliser the saved registry uses, so a modal
+     * cannot behave one way while being composed and another once published.
+     * A theme with no modals correctly yields an empty registry, which hands
+     * every modal back to the saved mounts.
+     */
+    setEditorModals(readThemeModals(theme.modals));
+  });
+};
+
+/** Stable empty registry: a fresh `[]` each render would loop the subscriber. */
+const NO_MODALS: ThemeModal[] = [];
+
+export const useEditorModals = (): ThemeModal[] => {
+  /**
+   * Empty on the server and on the first client render, so hydration matches;
+   * nothing can have arrived before the listener below is installed.
+   */
+  const [modals, setModals] = useState<ThemeModal[]>(NO_MODALS);
+
+  useEffect(() => {
+    startListening();
+
+    const listener = () => setModals(editorModals);
+    listeners.add(listener);
+    // A frame may have landed between render and this effect.
+    listener();
+
+    return () => {
+      listeners.delete(listener);
+    };
+  }, []);
+
+  return modals;
+};
+
+/**
+ * Whether the editor is attached AND knows this modal — in which case its copy
+ * supersedes whatever `theme-config` last saved.
+ */
+export const useEditorKnowsModal = (id: string): boolean =>
+  useEditorModals().some((modal) => modal.id === id);
+
+/** Test-only: drop the registry and the listener. */
+export const __resetEditorModalsForTests = (): void => {
+  editorModals = [];
+  signature = '';
+  listeners.clear();
+  listening = false;
+};

package/src/overlays/use-modal-auto-trigger.ts

@@ -0,0 +1,187 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+import { VisibilityRuleContext } from '../utils/visibility-rules';
+import { getOpenModalIds, openModal } from './overlay-bus';
+import { canAutoOpen, markAutoOpened } from './modal-frequency';
+import { ThemeModal } from './modal-registry';
+
+interface UseModalAutoTriggerOptions {
+  modal: ThemeModal;
+  /** False in the designer and wherever the modal does not belong. */
+  enabled: boolean;
+  visibilityContext: VisibilityRuleContext;
+}
+
+const DEFAULT_DELAY_MS = 3000;
+const DEFAULT_SCROLL_PERCENT = 50;
+const DEFAULT_IDLE_MS = 15000;
+
+/**
+ * Opens a modal without anyone clicking anything.
+ *
+ * Every branch below fires from an EFFECT, never during render. A modal opened
+ * while rendering would put a focus trap and an `aria-modal` claim into the
+ * server markup, and the client — which starts from an empty page-load state —
+ * would hydrate into a different tree. `overlay-bus.ts` backs this up by
+ * always reporting closed on the server, so a mistake here fails as a visible
+ * hydration warning rather than a subtly broken page.
+ */
+export const useModalAutoTrigger = ({
+  modal,
+  enabled,
+  visibilityContext
+}: UseModalAutoTriggerOptions): void => {
+  const trigger = modal.autoTrigger;
+
+  /**
+   * Auth state is 'loading' on the first client render and settles a beat
+   * later. A rule saying "guests only" would be unsatisfied at exactly the
+   * moment a page-load trigger fires, so the effect waits rather than deciding
+   * against information it does not have yet.
+   */
+  const authSettled = visibilityContext.authState !== 'loading';
+
+  // Read inside the handlers rather than captured, so a re-render does not
+  // rearm a timer that is already counting.
+  const stateRef = useRef({ modal, enabled, authSettled });
+  useEffect(() => {
+    stateRef.current = { modal, enabled, authSettled };
+  });
+
+  const armed = Boolean(trigger) && enabled && authSettled;
+  const event = trigger?.event;
+  const frequency = trigger?.frequency || 'once-per-session';
+
+  useEffect(() => {
+    if (!armed || !event || event === 'none') return undefined;
+    if (typeof window === 'undefined') return undefined;
+
+    let done = false;
+
+    const fire = () => {
+      if (done) return;
+
+      const current = stateRef.current;
+      if (!current.enabled) return;
+
+      /**
+       * Never interrupt. A shopper who opened the size guide, or is inside
+       * the mini basket, did not ask for a newsletter over the top of it —
+       * and stacking two dialogs also puts two focus traps on the page, which
+       * is the exact failure `use-overlay.ts` exists to prevent.
+       */
+      if (getOpenModalIds().length > 0) return;
+
+      if (!canAutoOpen(current.modal.id, frequency)) return;
+
+      done = true;
+      markAutoOpened(current.modal.id, frequency);
+      openModal(current.modal.id);
+    };
+
+    if (event === 'page-load') {
+      // Still a task rather than an inline call: firing inside the effect body
+      // on mount would open before the first paint has settled.
+      const id = window.setTimeout(fire, 0);
+
+      return () => window.clearTimeout(id);
+    }
+
+    if (event === 'delay') {
+      const id = window.setTimeout(
+        fire,
+        trigger?.delayMs ?? DEFAULT_DELAY_MS
+      );
+
+      return () => window.clearTimeout(id);
+    }
+
+    if (event === 'idle') {
+      const wait = trigger?.delayMs ?? DEFAULT_IDLE_MS;
+      let id = window.setTimeout(fire, wait);
+
+      const restart = () => {
+        window.clearTimeout(id);
+        id = window.setTimeout(fire, wait);
+      };
+
+      const events = ['pointerdown', 'keydown', 'scroll', 'pointermove'];
+      events.forEach((name) =>
+        window.addEventListener(name, restart, { passive: true })
+      );
+
+      return () => {
+        window.clearTimeout(id);
+        events.forEach((name) => window.removeEventListener(name, restart));
+      };
+    }
+
+    if (event === 'scroll-depth') {
+      const target = trigger?.scrollPercent ?? DEFAULT_SCROLL_PERCENT;
+
+      const check = () => {
+        const scrollable =
+          document.documentElement.scrollHeight - window.innerHeight;
+        // A page shorter than the viewport can never reach a depth, and
+        // dividing by zero would report Infinity and fire immediately.
+        if (scrollable <= 0) return;
+
+        const percent = (window.scrollY / scrollable) * 100;
+        if (percent >= target) fire();
+      };
+
+      window.addEventListener('scroll', check, { passive: true });
+      check();
+
+      return () => window.removeEventListener('scroll', check);
+    }
+
+    if (event === 'exit-intent') {
+      // Pointer leaving through the TOP of the viewport, which is the only
+      // direction that means "heading for the tab bar". A touch device has no
+      // such gesture and simply never fires this.
+      const handle = (nativeEvent: MouseEvent) => {
+        if (nativeEvent.clientY > 0) return;
+        if (nativeEvent.relatedTarget) return;
+
+        fire();
+      };
+
+      document.addEventListener('mouseout', handle);
+
+      return () => document.removeEventListener('mouseout', handle);
+    }
+
+    if (event === 'element-visible') {
+      const anchorId = trigger?.anchorId;
+      if (!anchorId || typeof IntersectionObserver === 'undefined') {
+        return undefined;
+      }
+
+      const element = document.getElementById(anchorId);
+      if (!element) return undefined;
+
+      const observer = new IntersectionObserver(
+        (entries) => {
+          if (entries.some((entry) => entry.isIntersecting)) fire();
+        },
+        { threshold: 0.1 }
+      );
+
+      observer.observe(element);
+
+      return () => observer.disconnect();
+    }
+
+    return undefined;
+  }, [
+    armed,
+    event,
+    frequency,
+    trigger?.delayMs,
+    trigger?.scrollPercent,
+    trigger?.anchorId
+  ]);
+};

package/src/overlays/use-modal-preview.ts

@@ -0,0 +1,127 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { parseEditorMessage } from '../editor-bridge';
+import { readThemeModal, ThemeModal } from './modal-registry';
+
+/**
+ * The modal the editor is holding open in the canvas, as the editor currently
+ * has it — not as the server last saved it.
+ *
+ * The whole entry travels, not just an id, and that is the point. A modal being
+ * composed may not exist on the server at all (it was created a moment ago and
+ * nothing has been saved), and one that does exist is being restyled: its
+ * presentation, width and dismissal switches change under the designer's hands.
+ * Holding open a server-rendered surface would mean every one of those edits
+ * needed a save and a reload before it could be seen, which is not an editing
+ * loop anyone would use.
+ *
+ * Module state rather than component state for the same reason the overlay bus
+ * is: several consumers must agree on ONE answer, or two surfaces cover the
+ * canvas at once.
+ *
+ * Deliberately NOT routed through the overlay bus. The bus is the shopper's
+ * page state; this is an editing mode. Keeping them apart is what lets the
+ * canvas hold a modal open with every dismissal inert while a real `openModal`
+ * on the same page still behaves like a real modal.
+ */
+let heldModal: ThemeModal | null = null;
+
+/**
+ * Serialized form of what is held, so a repeated frame does not re-render and
+ * a changed one always does. Comparing ids would miss chrome edits — the exact
+ * updates this channel exists to deliver.
+ */
+let heldSignature = '';
+
+const listeners = new Set<() => void>();
+
+const setHeldModal = (modal: ThemeModal | null) => {
+  const signature = modal ? JSON.stringify(modal) : '';
+  if (signature === heldSignature) return;
+
+  heldSignature = signature;
+  heldModal = modal;
+  listeners.forEach((listener) => listener());
+};
+
+let listening = false;
+
+/**
+ * One document listener for the whole page, installed on first use.
+ *
+ * Per-mount listeners would mean N handlers parsing every frame the editor
+ * sends, on a channel that already carries every style keystroke.
+ */
+const startListening = () => {
+  if (listening || typeof window === 'undefined') return;
+  listening = true;
+
+  window.addEventListener('message', (event: MessageEvent) => {
+    const message = parseEditorMessage(event);
+    if (!message) return;
+
+    if (message.type === 'PREVIEW_OPEN_MODAL') {
+      const data = message.data as
+        | { modalId?: string; modal?: unknown }
+        | undefined;
+
+      /**
+       * `modal` is what the editor sends. The `modalId`-only fallback keeps a
+       * mismatched pair of builds usable rather than silently dead: the canvas
+       * shows the surface with default chrome instead of nothing at all.
+       */
+      const modal =
+        readThemeModal(data?.modal) ??
+        (data?.modalId
+          ? readThemeModal({ id: data.modalId, name: data.modalId })
+          : null);
+
+      setHeldModal(modal);
+      return;
+    }
+
+    if (message.type === 'PREVIEW_CLOSE_MODAL') {
+      setHeldModal(null);
+    }
+  });
+};
+
+/** The modal the editor is holding open, or null. */
+export const useHeldModal = (): ThemeModal | null => {
+  /**
+   * Starts null on both sides. Nothing can have arrived before the first
+   * render — the listener is installed in the effect below — so the server and
+   * the first client render agree, and the effect picks up anything that lands
+   * between the two.
+   */
+  const [modal, setModal] = useState<ThemeModal | null>(null);
+
+  useEffect(() => {
+    startListening();
+
+    const listener = () => setModal(heldModal);
+    listeners.add(listener);
+    // The frame may have arrived between render and this effect.
+    listener();
+
+    return () => {
+      listeners.delete(listener);
+    };
+  }, []);
+
+  return modal;
+};
+
+/** True while the editor is holding THIS modal open in the canvas. */
+export const useModalPreview = (modalId: string): boolean =>
+  useHeldModal()?.id === modalId;
+
+/** Test-only: drop the listener registry and the held modal. */
+export const __resetModalPreviewForTests = (): void => {
+  heldModal = null;
+  heldSignature = '';
+  listeners.clear();
+  listening = false;
+};