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

package/src/overlays/modal-dom-bridge.ts

@@ -0,0 +1,104 @@
+'use client';
+
+import {
+  closeModal,
+  closeTopModal,
+  openModal,
+  toggleModal
+} from './overlay-bus';
+
+/**
+ * Two ways in for markup React does not own.
+ *
+ * The block dictionary is not the only thing on a composed page. The `embed`
+ * block renders authored HTML, a brand still owns part of its own chrome, and
+ * an agency drops a snippet into a campaign banner. None of those can call a
+ * hook, and without a way in they simply cannot open a modal — which pushes
+ * people back to writing their own overlay, the outcome this whole system
+ * exists to avoid.
+ *
+ *     <button data-pz-modal-open="newsletter">Sign up</button>
+ *     <button data-pz-modal-close="newsletter">No thanks</button>
+ *
+ *     window.pzTheme.openModal('newsletter');
+ *
+ * The listener is delegated from the document, so markup injected at any time
+ * works with no registration step.
+ */
+
+const ATTRIBUTES = [
+  ['data-pz-modal-open', openModal],
+  ['data-pz-modal-close', closeModal],
+  ['data-pz-modal-toggle', toggleModal]
+] as const;
+
+const handleDocumentClick = (event: MouseEvent) => {
+  const start = event.target as Element | null;
+  if (!start || typeof start.closest !== 'function') return;
+
+  for (const [attribute, action] of ATTRIBUTES) {
+    const trigger = start.closest(`[${attribute}]`);
+    if (!trigger) continue;
+
+    const id = trigger.getAttribute(attribute);
+    if (!id) continue;
+
+    // A trigger inside an <a> or a <form> must not also navigate or submit.
+    event.preventDefault();
+    action(id);
+
+    return;
+  }
+
+  if (start.closest('[data-pz-modal-close-top]')) {
+    event.preventDefault();
+    closeTopModal();
+  }
+};
+
+export interface PzThemeWindowApi {
+  openModal: typeof openModal;
+  closeModal: typeof closeModal;
+  toggleModal: typeof toggleModal;
+  closeTopModal: typeof closeTopModal;
+}
+
+declare global {
+  interface Window {
+    pzTheme?: PzThemeWindowApi;
+  }
+}
+
+let installed = false;
+
+/**
+ * Install both entry points. Idempotent, because the modal host mounts it and
+ * a page could legitimately mount more than one host during a transition.
+ */
+export const installModalDomBridge = (): (() => void) => {
+  if (typeof window === 'undefined' || installed) return () => undefined;
+
+  installed = true;
+  document.addEventListener('click', handleDocumentClick);
+
+  window.pzTheme = {
+    ...(window.pzTheme || {}),
+    openModal,
+    closeModal,
+    toggleModal,
+    closeTopModal
+  };
+
+  return () => {
+    installed = false;
+    document.removeEventListener('click', handleDocumentClick);
+  };
+};
+
+/** Test-only: forget that the bridge was installed. */
+export const __resetModalDomBridgeForTests = (): void => {
+  if (typeof document !== 'undefined') {
+    document.removeEventListener('click', handleDocumentClick);
+  }
+  installed = false;
+};

package/src/overlays/modal-frequency.ts

@@ -0,0 +1,104 @@
+import { ModalFrequency } from './modal-registry';
+
+/**
+ * How often an auto-opening modal may show itself.
+ *
+ * This is the difference between a welcome popup and a reason to leave the
+ * site. Nothing else in the theme system needs persistent per-visitor state,
+ * so it lives here rather than growing a general store.
+ *
+ * `once-per-session` uses sessionStorage (cleared with the tab, which is what
+ * a "visit" means to a shopper); the day and forever caps use localStorage.
+ * Both are wrapped: Safari in private mode throws on write, and an exception
+ * here would take the whole page down for a marketing banner.
+ */
+
+const STORAGE_PREFIX = 'pz-theme:modal-seen:';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const storageFor = (frequency: ModalFrequency): Storage | null => {
+  if (typeof window === 'undefined') return null;
+
+  try {
+    return frequency === 'once-per-session'
+      ? window.sessionStorage
+      : window.localStorage;
+  } catch {
+    // Storage disabled entirely (some privacy modes, some embedded webviews).
+    return null;
+  }
+};
+
+const keyFor = (modalId: string) => `${STORAGE_PREFIX}${modalId}`;
+
+/**
+ * Whether the cap still allows this modal to open.
+ *
+ * Fails OPEN when storage is unavailable: a shopper whose browser refuses
+ * storage should still see the newsletter offer once, and the alternative —
+ * suppressing it forever — is a silent regression nobody would trace back to
+ * a privacy setting.
+ */
+export const canAutoOpen = (
+  modalId: string,
+  frequency: ModalFrequency
+): boolean => {
+  if (frequency === 'always') return true;
+
+  const storage = storageFor(frequency);
+  if (!storage) return true;
+
+  let raw: string | null = null;
+  try {
+    raw = storage.getItem(keyFor(modalId));
+  } catch {
+    return true;
+  }
+
+  if (!raw) return true;
+  if (frequency === 'once-per-session' || frequency === 'once-ever') {
+    return false;
+  }
+
+  // once-per-day: a stamp we cannot read is treated as "never shown" rather
+  // than as "shown forever", so a corrupted value self-heals on the next view.
+  const shownAt = Number(raw);
+  if (!Number.isFinite(shownAt)) return true;
+
+  return Date.now() - shownAt >= DAY_MS;
+};
+
+/** Record that the modal auto-opened. Never throws. */
+export const markAutoOpened = (
+  modalId: string,
+  frequency: ModalFrequency
+): void => {
+  if (frequency === 'always') return;
+
+  const storage = storageFor(frequency);
+  if (!storage) return;
+
+  try {
+    storage.setItem(keyFor(modalId), String(Date.now()));
+  } catch {
+    // Quota or private mode. The modal simply shows again next time, which is
+    // the harmless end of the two possible failures.
+  }
+};
+
+/** Test-only helper, and what an editor "reset this modal" control would call. */
+export const clearAutoOpenRecord = (modalId: string): void => {
+  if (typeof window === 'undefined') return;
+
+  [
+    () => window.sessionStorage.removeItem(keyFor(modalId)),
+    () => window.localStorage.removeItem(keyFor(modalId))
+  ].forEach((remove) => {
+    try {
+      remove();
+    } catch {
+      // Nothing to clear if storage is unavailable.
+    }
+  });
+};

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

@@ -0,0 +1,35 @@
+'use client';
+
+import { useEffect } from 'react';
+
+import { installModalDomBridge } from './modal-dom-bridge';
+import { registerModalHost } from './overlay-bus';
+
+/**
+ * Announces that `<ThemeModals />` is on the page.
+ *
+ * The host has to be mounted by the brand, in its root layout — one line, but
+ * one line sixteen brands each have to add. Without this, forgetting it
+ * produces the worst possible symptom: a trigger the designer configured
+ * correctly, in a theme that saved correctly, that does nothing at all when
+ * clicked, with no error anywhere to suggest why.
+ *
+ * With it, `openModal` can say the actual sentence.
+ */
+export const ModalHostBeacon = () => {
+  useEffect(() => {
+    const unregister = registerModalHost();
+    // The `data-pz-modal-open` / `window.pzTheme` entry points live with the
+    // host: they can only work when there is something to open.
+    const uninstall = installModalDomBridge();
+
+    return () => {
+      unregister();
+      uninstall();
+    };
+  }, []);
+
+  return null;
+};
+
+export default ModalHostBeacon;

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

@@ -0,0 +1,159 @@
+'use client';
+
+import React from 'react';
+
+import ThemePlaceholderWrapper from '../theme-placeholder-wrapper';
+import {
+  CentredModalSurface,
+  LayeredOverlaySurface,
+  OverlayCloseButton,
+  OverlayHandleProps
+} from './overlay-surface';
+import ThemeModalMount from './theme-modal-mount';
+import { useEditorModals } from './use-editor-modals';
+import { useHeldModal } from './use-modal-preview';
+
+interface ModalPreviewHostProps {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  dataSources?: any[];
+  themeSettings?: Record<string, unknown> | null;
+  pageContext?: Record<string, unknown> | null;
+}
+
+/**
+ * Nothing to grab and nothing to claim.
+ *
+ * The canvas is a workspace, not a shopper's viewport: no focus trap into the
+ * page being styled, no `aria-modal` hiding the rest of the document from the
+ * accessibility tree, no scroll lock, no Escape. Passing inert props rather
+ * than calling `useOverlay` with a flag says that plainly — this surface never
+ * takes anything over.
+ */
+const INERT_OVERLAY: OverlayHandleProps = {
+  ref: undefined,
+  'aria-modal': undefined
+};
+
+/**
+ * The modal a designer is composing, drawn in the canvas.
+ *
+ * This is the ONLY renderer for an editor-held modal, and it draws from the
+ * entry the editor pushes rather than from `theme-config`. That single choice
+ * is what makes the three cases behave the same:
+ *
+ *   - a modal created seconds ago that the server has never heard of,
+ *   - a saved modal whose chrome is being changed right now,
+ *   - a saved modal being filled with blocks.
+ *
+ * All three need a surface on screen before anything is saved. A
+ * server-rendered surface could only ever manage the third, and only after a
+ * save and a reload.
+ *
+ * The composition inside comes from an ordinary `ThemePlaceholderWrapper`, the
+ * same one every other editable region on the page uses, so the modal's
+ * interior registers itself, accepts drops and answers selection with no
+ * special case anywhere in the editor. It starts empty on purpose: on
+ * `LOAD_THEME`/`UPDATE_THEME` the wrapper replaces its sections wholesale from
+ * the editor's copy, which is the authority while editing.
+ */
+export const ModalPreviewHost = ({
+  dataSources,
+  themeSettings = null,
+  pageContext = null
+}: ModalPreviewHostProps) => {
+  const modal = useHeldModal();
+  const editorModals = useEditorModals();
+
+  const composition = (slug: string) => (
+    <ThemePlaceholderWrapper
+      slug={slug}
+      initialSections={[]}
+      initialPlaceholderId={slug}
+      isDesignMode={false}
+      dataSources={dataSources}
+      initialThemeSettings={themeSettings}
+      initialPageContext={pageContext}
+    />
+  );
+
+  /**
+   * Every modal the editor knows, mounted the ordinary way.
+   *
+   * This is what lets a TRIGGER work while composing. The saved mounts can
+   * only offer modals the backend has stored, so pressing a trigger in browse
+   * mode did nothing at all for a modal created minutes ago — and nothing
+   * distinguished that from a broken trigger. These mounts answer the overlay
+   * bus exactly as the saved ones do, so an unsaved modal opens, dismisses and
+   * traps focus like a real one.
+   *
+   * The one the editor is holding open stands itself down here and is drawn
+   * below instead, as an inert editing surface.
+   */
+  const triggerable = (
+    <>
+      {editorModals.map((entry) => (
+        <ThemeModalMount key={entry.id} modal={entry} origin="editor">
+          {composition(entry.slug)}
+        </ThemeModalMount>
+      ))}
+    </>
+  );
+
+  if (!modal) return triggerable;
+
+  const { chrome, presentation } = modal;
+
+  // Every dismissal is inert: the designer has to be able to click the close
+  // button and the backdrop they are colouring without the surface vanishing.
+  const noop = () => undefined;
+
+  const header = chrome.showClose ? (
+    <OverlayCloseButton label={chrome.closeLabel} onClick={noop} />
+  ) : null;
+
+  const ariaLabel = chrome.ariaLabel || modal.name;
+
+  const surface =
+    presentation === 'modal' ? (
+      <CentredModalSurface
+        overlayProps={INERT_OVERLAY}
+        ariaLabel={ariaLabel}
+        closeOnOverlay={false}
+        onDismiss={noop}
+        width={chrome.width}
+        header={header}
+      >
+        {composition(modal.slug)}
+      </CentredModalSurface>
+    ) : (
+      <LayeredOverlaySurface
+        presentation={presentation}
+        overlayProps={INERT_OVERLAY}
+        ariaLabel={ariaLabel}
+        showBackdrop={chrome.showBackdrop}
+        closeOnOverlay={false}
+        onDismiss={noop}
+        width={chrome.width}
+        panelSide={chrome.panelSide}
+        sheetHeight={chrome.sheetHeight}
+        header={header}
+      >
+        {composition(modal.slug)}
+      </LayeredOverlaySurface>
+    );
+
+  return (
+    <>
+      {triggerable}
+      <div
+        id={`theme-modal-${modal.id}`}
+        data-theme-modal={modal.id}
+        data-theme-modal-state="preview"
+      >
+        {surface}
+      </div>
+    </>
+  );
+};
+
+export default ModalPreviewHost;

package/src/overlays/modal-registry.ts

@@ -0,0 +1,289 @@
+import { modalSlug } from '../chrome/placeholder-slugs';
+import { devWarn } from '../utils/dev-warn';
+import type { VisibilityRules } from '../utils/visibility-rules';
+
+/**
+ * The modal registry: what modals this theme has, read off `theme-config`.
+ *
+ * A modal's CONTENT is an ordinary composition saved under its own slug, so
+ * nothing about the block tree lives here. This is only the index — the part
+ * the page needs before it can decide which modals to fetch at all.
+ */
+
+export type ModalPresentation = 'modal' | 'drawer' | 'sheet';
+
+export const MODAL_PRESENTATIONS: ModalPresentation[] = [
+  'modal',
+  'drawer',
+  'sheet'
+];
+
+export type ModalAutoTriggerEvent =
+  | 'none'
+  | 'page-load'
+  | 'delay'
+  | 'scroll-depth'
+  | 'exit-intent'
+  | 'idle'
+  | 'element-visible';
+
+/**
+ * How often an auto-triggered modal may show itself. Without this a "welcome"
+ * popup reappears on every navigation, which is the single most common way
+ * this feature gets switched back off after launch.
+ */
+export type ModalFrequency =
+  | 'always'
+  | 'once-per-session'
+  | 'once-per-day'
+  | 'once-ever';
+
+export interface ModalAutoTrigger {
+  event: ModalAutoTriggerEvent;
+  /** `delay` and `idle`, in milliseconds. */
+  delayMs?: number;
+  /** `scroll-depth`, as a percentage of scrollable height. */
+  scrollPercent?: number;
+  /** `element-visible`, an authored `htmlId` elsewhere on the page. */
+  anchorId?: string;
+  frequency: ModalFrequency;
+}
+
+/**
+ * The frame around the authored content: what the surface does, not what is
+ * in it. Kept on the registry rather than inside the composition because the
+ * host needs it before it renders anything, and because a designer changing
+ * "close on backdrop" should not be editing a block.
+ */
+export interface ModalChrome {
+  /**
+   * The dialog's accessible name. Defaults to the modal's own name — a dialog
+   * with no name is announced as just "dialog", which tells a screen reader
+   * user nothing about what just took over their page.
+   */
+  ariaLabel?: string;
+  showClose: boolean;
+  closeLabel: string;
+  showBackdrop: boolean;
+  closeOnBackdrop: boolean;
+  closeOnEscape: boolean;
+  /** Drawer/anchored width, and the centred modal's max width, in px. */
+  width: number;
+  panelSide: 'left' | 'right';
+  /** Sheet height as a percentage of the viewport. */
+  sheetHeight: number;
+  lockScroll: boolean;
+}
+
+export interface ThemeModal {
+  /** Generated, stable, and what every trigger points at. Never the name. */
+  id: string;
+  /** Designer-facing label. Free to change without touching saved content. */
+  name: string;
+  /** `modal-<id>`, the widget slug the composition is saved under. */
+  slug: string;
+  presentation: ModalPresentation;
+  chrome: ModalChrome;
+  autoTrigger?: ModalAutoTrigger;
+  /**
+   * Where this modal EXISTS — the same rule object sections and blocks already
+   * use, so route, auth state, locale, currency, breakpoint and page-data
+   * conditions all work with no second condition language to learn or maintain.
+   */
+  visibilityRules?: VisibilityRules;
+}
+
+const asString = (value: unknown): string =>
+  typeof value === 'string' ? value.trim() : '';
+
+const asOption = <T extends string>(
+  value: unknown,
+  allowed: readonly T[],
+  fallback: T
+): T => (allowed.includes(value as T) ? (value as T) : fallback);
+
+const asPositiveNumber = (value: unknown): number | undefined => {
+  const numeric = Number(value);
+
+  return Number.isFinite(numeric) && numeric >= 0 ? numeric : undefined;
+};
+
+const AUTO_TRIGGER_EVENTS: ModalAutoTriggerEvent[] = [
+  'none',
+  'page-load',
+  'delay',
+  'scroll-depth',
+  'exit-intent',
+  'idle',
+  'element-visible'
+];
+
+const FREQUENCIES: ModalFrequency[] = [
+  'always',
+  'once-per-session',
+  'once-per-day',
+  'once-ever'
+];
+
+const readAutoTrigger = (value: unknown): ModalAutoTrigger | undefined => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const raw = value as Record<string, unknown>;
+  const event = asOption(raw.event, AUTO_TRIGGER_EVENTS, 'none');
+
+  if (event === 'none') return undefined;
+
+  return {
+    event,
+    delayMs: asPositiveNumber(raw.delayMs),
+    scrollPercent: asPositiveNumber(raw.scrollPercent),
+    anchorId: asString(raw.anchorId) || undefined,
+    // Defaults to the safe end: an auto-opening modal that has not been told
+    // how often it may appear should not appear on every page view.
+    frequency: asOption(raw.frequency, FREQUENCIES, 'once-per-session')
+  };
+};
+
+const asToggle = (value: unknown, fallback: boolean): boolean =>
+  typeof value === 'boolean' ? value : fallback;
+
+const asClamped = (
+  value: unknown,
+  fallback: number,
+  min: number,
+  max: number
+): number => {
+  const numeric = Math.round(Number(value));
+  if (!Number.isFinite(numeric)) return fallback;
+
+  return Math.min(max, Math.max(min, numeric));
+};
+
+const readChrome = (value: unknown, name: string): ModalChrome => {
+  const raw =
+    value && typeof value === 'object' && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : {};
+
+  const showClose = asToggle(raw.showClose, true);
+  const closeOnBackdrop = asToggle(raw.closeOnBackdrop, true);
+  const closeOnEscape = asToggle(raw.closeOnEscape, true);
+
+  return {
+    ariaLabel: asString(raw.ariaLabel) || name,
+    /**
+     * Forced back on when nothing else could dismiss the modal. A shopper
+     * sealed inside an overlay has lost the page, and this is the one setting
+     * combination where honouring every switch as authored produces exactly
+     * that — so the close button comes back rather than the designer finding
+     * out from a support ticket.
+     */
+    showClose: showClose || (!closeOnBackdrop && !closeOnEscape),
+    closeLabel: asString(raw.closeLabel) || 'Close',
+    showBackdrop: asToggle(raw.showBackdrop, true),
+    closeOnBackdrop,
+    closeOnEscape,
+    width: asClamped(raw.width, 640, 240, 1600),
+    panelSide: raw.panelSide === 'left' ? 'left' : 'right',
+    sheetHeight: asClamped(raw.sheetHeight, 60, 20, 100),
+    lockScroll: asToggle(raw.lockScroll, true)
+  };
+};
+
+/**
+ * Normalise ONE registry entry.
+ *
+ * Exported because the editor pushes a live entry over postMessage while a
+ * designer is composing a modal, and that entry has to survive exactly the
+ * same defaulting and rejection as one read off `theme-config` — otherwise the
+ * canvas would render a modal the published page never could.
+ */
+export const readThemeModal = (value: unknown): ThemeModal | null => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+
+  const raw = value as Record<string, unknown>;
+  const id = asString(raw.id);
+  const slug = modalSlug(id);
+
+  // An id this slug family cannot address has no composition to fetch, so the
+  // entry is dropped rather than rendered as an empty overlay a trigger can
+  // "open" to nothing. Named, because it means the editor wrote a bad id.
+  if (!slug) {
+    if (id) {
+      devWarn(
+        'modalRegistry',
+        `Modal id "${id}" is not addressable (expected lowercase letters, digits and hyphens); the modal is ignored`
+      );
+    }
+    return null;
+  }
+
+  const name = asString(raw.name) || id;
+
+  return {
+    id,
+    name,
+    slug,
+    presentation: asOption(raw.presentation, MODAL_PRESENTATIONS, 'modal'),
+    chrome: readChrome(raw.chrome, name),
+    autoTrigger: readAutoTrigger(raw.autoTrigger),
+    visibilityRules:
+      raw.visibilityRules && typeof raw.visibilityRules === 'object'
+        ? (raw.visibilityRules as VisibilityRules)
+        : undefined
+  };
+};
+
+/**
+ * Parse the `theme_modals` attribute into the registry.
+ *
+ * Accepts the array itself or the JSON string the editor writes, matching how
+ * every other `theme_*` attribute is read. Malformed entries are dropped one by
+ * one: one bad modal must not cost the page the rest of them.
+ *
+ * Duplicate ids collapse to the first, because two entries claiming one id
+ * claim one slug, and letting both through would mean two surfaces racing to
+ * render the same composition.
+ */
+export const readThemeModals = (value: unknown): ThemeModal[] => {
+  let parsed: unknown = value;
+
+  if (typeof parsed === 'string') {
+    if (!parsed.trim()) return [];
+
+    try {
+      parsed = JSON.parse(parsed);
+    } catch {
+      devWarn(
+        'modalRegistry',
+        'theme_modals is not valid JSON; the theme renders with no modals'
+      );
+      return [];
+    }
+  }
+
+  if (!Array.isArray(parsed)) return [];
+
+  const seen = new Set<string>();
+  const modals: ThemeModal[] = [];
+
+  parsed.forEach((entry) => {
+    const modal = readThemeModal(entry);
+    if (!modal) return;
+
+    if (seen.has(modal.id)) {
+      devWarn(
+        'modalRegistry',
+        `Duplicate modal id "${modal.id}"; only the first entry is used`
+      );
+      return;
+    }
+
+    seen.add(modal.id);
+    modals.push(modal);
+  });
+
+  return modals;
+};