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

package/src/overlays/overlay-bus.ts

@@ -0,0 +1,214 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+import { devWarn } from '../utils/dev-warn';
+
+/**
+ * Which composed modals are open, for the whole page.
+ *
+ * A modal is opened by something that is not inside it — a header button, a
+ * footer link, a PDP badge, a timer. Those live in DIFFERENT React roots:
+ * every placeholder on the page mounts its own `ThemePlaceholderWrapper`, so
+ * header and body share no provider, no context and no state. Passing a
+ * callback down is not merely awkward there, it is impossible.
+ *
+ * Module state is the one channel that crosses those roots, which is exactly
+ * the reasoning `use-overlay.ts` already applies to its overlay stack — and the
+ * two are deliberately separate concerns. This module answers *which modals
+ * the page wants open*; `useOverlay` answers *what an open overlay does to the
+ * page* (focus, scroll, `aria-modal`, Escape). The modal surface subscribes
+ * here and hands the answer to `useOverlay`, so the stack, the focus trap and
+ * the scroll lock stay in one place for every overlay in the system.
+ *
+ *     // trigger, anywhere on the page
+ *     openModal('newsletter');
+ *
+ *     // the surface
+ *     const open = useModalOpen(modal.id);
+ *     const overlay = useOverlay({ open, onClose: () => closeModal(modal.id) });
+ */
+
+/**
+ * Open modal ids, oldest first. An id appears AT MOST ONCE, and that is the
+ * loop guard: a trigger inside modal A that points at A — or a chain A → B → A,
+ * which is the same bug one indirection further out — finds A already open and
+ * stops, instead of pushing forever.
+ */
+let openModalIds: string[] = [];
+
+/**
+ * A page cannot meaningfully stack this many dialogs, so passing it means
+ * something is opening modals in a loop the id guard cannot see (an effect that
+ * re-opens on every render, say). Refusing keeps the tab alive and names the
+ * modal that tipped it over.
+ */
+const MAX_OPEN_MODALS = 8;
+
+const listeners = new Set<() => void>();
+
+const notify = () => {
+  listeners.forEach((listener) => listener());
+};
+
+export const subscribeToModals = (listener: () => void): (() => void) => {
+  listeners.add(listener);
+
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+/**
+ * Mutations are refused outside the browser.
+ *
+ * Module state on a server is per PROCESS, not per request: one request opening
+ * a modal here would leave it open for the next visitor's render, on a server
+ * that serves everyone. Nothing legitimate calls these outside an event handler
+ * or an effect, so the guard costs nothing and closes a cross-request leak that
+ * would be very hard to see.
+ */
+const canMutate = () => typeof window !== 'undefined';
+
+/**
+ * Whether `<ThemeModals />` is mounted, so a trigger that reaches nothing can
+ * say why. The host is one line in the brand's root layout, and forgetting it
+ * otherwise looks exactly like a broken trigger.
+ */
+let mountedHosts = 0;
+
+export const registerModalHost = (): (() => void) => {
+  mountedHosts += 1;
+
+  /**
+   * The disposer releases ITS OWN registration and only once.
+   *
+   * A plain decrement would be called twice under React StrictMode, which
+   * double-invokes effect cleanups in development — the count would fall below
+   * the number of live hosts and every trigger would warn about a host that is
+   * mounted and working.
+   */
+  let released = false;
+
+  return () => {
+    if (released) return;
+
+    released = true;
+    mountedHosts = Math.max(0, mountedHosts - 1);
+  };
+};
+
+export const isModalHostMounted = (): boolean => mountedHosts > 0;
+
+export const getOpenModalIds = (): readonly string[] => openModalIds;
+
+export const isModalOpen = (id: string): boolean => openModalIds.includes(id);
+
+export const openModal = (id: string): void => {
+  if (!canMutate() || !id) return;
+
+  // Already open: the no-op IS the loop guard. See `openModalIds`.
+  if (openModalIds.includes(id)) return;
+
+  if (!isModalHostMounted()) {
+    devWarn(
+      'overlayBus',
+      `Nothing can show modal "${id}": <ThemeModals /> is not mounted. Add it once to the brand's root layout, next to the footer slot.`
+    );
+    // Still queued: the host may simply not have mounted yet this tick, and
+    // refusing would turn a race into a dead trigger.
+  }
+
+  if (openModalIds.length >= MAX_OPEN_MODALS) {
+    devWarn(
+      'overlayBus',
+      `Refusing to open modal "${id}": ${MAX_OPEN_MODALS} modals are already open, which means something is opening them in a loop`
+    );
+    return;
+  }
+
+  openModalIds = [...openModalIds, id];
+  notify();
+};
+
+export const closeModal = (id: string): void => {
+  if (!canMutate() || !openModalIds.includes(id)) return;
+
+  openModalIds = openModalIds.filter((openId) => openId !== id);
+  notify();
+};
+
+export const toggleModal = (id: string): void => {
+  if (isModalOpen(id)) {
+    closeModal(id);
+    return;
+  }
+
+  openModal(id);
+};
+
+/** Close the most recently opened modal — what a generic "close" control means. */
+export const closeTopModal = (): void => {
+  const top = openModalIds[openModalIds.length - 1];
+  if (top) closeModal(top);
+};
+
+export const closeAllModals = (): void => {
+  if (!canMutate() || openModalIds.length === 0) return;
+
+  openModalIds = [];
+  notify();
+};
+
+/**
+ * Nothing is open during SSR.
+ *
+ * This is the answer the server snapshot must give even if the module state
+ * somehow says otherwise: a modal opened during render would put a focus trap
+ * and an `aria-modal` claim into the serialized markup, and the client — which
+ * starts from an empty page-load state — would hydrate into a different tree.
+ * Auto-triggers therefore fire from an effect, never during render.
+ */
+const closedOnServer = () => false;
+
+/**
+ * Subscription for a caller with no modal to watch.
+ *
+ * `useBlockAction` runs on EVERY block on the page — hooks cannot be called
+ * conditionally — and almost none of them target a modal. Handing those the
+ * real subscribe would put a listener per block in the set and walk all of
+ * them on every open, so a page with hundreds of blocks would pay for a
+ * feature it is not using.
+ */
+const neverNotifies = () => () => undefined;
+
+const alwaysClosed = () => false;
+
+/** Pass an empty id for "nothing to watch" — it costs no subscription. */
+export const useModalOpen = (id: string): boolean =>
+  useSyncExternalStore(
+    id ? subscribeToModals : neverNotifies,
+    id ? () => openModalIds.includes(id) : alwaysClosed,
+    closedOnServer
+  );
+
+/**
+ * Stable empty array for the server snapshot: `useSyncExternalStore` compares
+ * snapshots by reference and a fresh `[]` on every call is an infinite loop.
+ * The live snapshot is safe for the same reason — `openModalIds` is replaced
+ * only when it actually changes, never mutated in place.
+ */
+const NO_OPEN_MODALS: readonly string[] = Object.freeze([]);
+
+export const useOpenModalIds = (): readonly string[] =>
+  useSyncExternalStore(
+    subscribeToModals,
+    getOpenModalIds,
+    () => NO_OPEN_MODALS
+  );
+
+/** Test-only: drop all state so cases cannot leak into each other. */
+export const __resetOverlayBusForTests = (): void => {
+  openModalIds = [];
+  listeners.clear();
+  mountedHosts = 0;
+};

package/src/overlays/overlay-surface.tsx

@@ -0,0 +1,386 @@
+'use client';
+
+import React from 'react';
+import { partAttrs } from '../utils';
+
+/**
+ * The overlay surface: how a panel arrives over the page, and what it looks
+ * like when it does.
+ *
+ * Extracted from `panel-block.tsx` so the composed modal host and the panel
+ * block draw the SAME thing. Two consumers of one visual language is exactly
+ * the situation that produced three incompatible focus traps before
+ * `use-overlay.ts` unified them, and geometry is the next thing that would
+ * have drifted: "what does a bottom sheet look like" must not have two
+ * answers.
+ *
+ * What lives here is the surface. What lives in `use-overlay.ts` is the page:
+ * focus, scroll lock, `aria-modal`, Escape. A consumer wires both.
+ *
+ * The data attributes are the caller's, because the panel block's published
+ * markup carries `data-size-guide-*` names that live storefronts style and
+ * `panel-legacy-golden.json` pins byte for byte. New callers pass their own.
+ */
+
+export type OverlayPresentation = 'modal' | 'drawer' | 'sheet' | 'anchored';
+
+export const OVERLAY_PRESENTATIONS: OverlayPresentation[] = [
+  'modal',
+  'drawer',
+  'sheet',
+  'anchored'
+];
+
+export const clampOverlayNumber = (
+  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));
+};
+
+/** The panel's own box, before geometry places it. */
+export const overlayPanelSurface: React.CSSProperties = {
+  overflow: 'auto',
+  padding: '24px',
+  background: '#ffffff',
+  color: '#111827',
+  textAlign: 'left',
+  outline: 'none'
+};
+
+export interface OverlayGeometryInput {
+  presentation: OverlayPresentation;
+  /** Drawer/anchored width and the centred modal's max width, in px. */
+  width: number;
+  panelSide?: string;
+  /** Sheet height as a percentage of the viewport. */
+  sheetHeight?: number;
+  anchorAlign?: 'start' | 'center' | 'end';
+  anchorOffset?: number;
+}
+
+/**
+ * Where the panel sits for a given presentation.
+ *
+ * Anchored is the odd one: it hangs off the block's own root rather than a
+ * fixed layer, because a dropdown has to travel with the trigger that opened
+ * it. Everything else lives on a layer over the page.
+ */
+export const resolveOverlayPanelGeometry = ({
+  presentation,
+  width,
+  panelSide = 'right',
+  sheetHeight = 60,
+  anchorAlign = 'start',
+  anchorOffset = 8
+}: OverlayGeometryInput): React.CSSProperties => {
+  if (presentation === 'drawer') {
+    return {
+      position: 'absolute',
+      top: 0,
+      bottom: 0,
+      [panelSide === 'left' ? 'left' : 'right']: 0,
+      width: `min(${width}px, 92vw)`,
+      boxShadow: '0 0 24px rgba(0, 0, 0, 0.2)'
+    };
+  }
+
+  if (presentation === 'sheet') {
+    return {
+      position: 'absolute',
+      left: 0,
+      right: 0,
+      bottom: 0,
+      width: '100%',
+      maxHeight: `${sheetHeight}vh`,
+      boxShadow: '0 -12px 32px rgba(0, 0, 0, 0.18)'
+    };
+  }
+
+  const anchorPlacement: React.CSSProperties =
+    anchorAlign === 'center'
+      ? { left: '50%', transform: 'translateX(-50%)' }
+      : anchorAlign === 'end'
+      ? { right: 0 }
+      : { left: 0 };
+
+  return {
+    position: 'absolute',
+    top: `calc(100% + ${anchorOffset}px)`,
+    zIndex: 1000,
+    width: `${width}px`,
+    maxWidth: '92vw',
+    maxHeight: '80vh',
+    borderRadius: '4px',
+    boxShadow: '0 12px 32px rgba(0, 0, 0, 0.18)',
+    ...anchorPlacement
+  };
+};
+
+export interface OverlayCloseButtonProps {
+  label: string;
+  onClick: () => void;
+  /** Legacy marker attribute, e.g. `{ 'data-size-guide-close': '' }`. */
+  markerAttrs?: Record<string, string>;
+}
+
+export const OverlayCloseButton = ({
+  label,
+  onClick,
+  markerAttrs
+}: OverlayCloseButtonProps) => (
+  <button
+    type="button"
+    {...markerAttrs}
+    {...partAttrs('close')}
+    aria-label={label}
+    onClick={onClick}
+    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>
+);
+
+/** The grab handle a bottom sheet draws above its content. */
+export const OverlaySheetHandle = ({
+  markerAttrs
+}: {
+  markerAttrs?: Record<string, string>;
+}) => (
+  <div
+    {...markerAttrs}
+    {...partAttrs('handle')}
+    style={{
+      width: '40px',
+      height: '4px',
+      margin: '0 auto 12px',
+      borderRadius: '999px',
+      background: '#d1d5db'
+    }}
+  />
+);
+
+/** Attributes `useOverlay` hands back for the element that IS the overlay. */
+export interface OverlayHandleProps {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ref: any;
+  'aria-modal': 'true' | undefined;
+}
+
+export interface OverlaySurfaceProps extends OverlayGeometryInput {
+  overlayProps: OverlayHandleProps;
+  ariaLabel: string;
+  showBackdrop: boolean;
+  closeOnOverlay: boolean;
+  onDismiss: () => void;
+  /** Rendered inside the panel, above the authored content. */
+  header?: React.ReactNode;
+  children: React.ReactNode;
+  /**
+   * Legacy marker attributes per node. Order matters: they are spread BEFORE
+   * the part attributes, which is where the panel block already put them and
+   * therefore where the golden expects them.
+   */
+  markers?: {
+    root?: Record<string, string>;
+    backdrop?: Record<string, string>;
+    backdropRoot?: Record<string, string>;
+    panel?: Record<string, string>;
+    handle?: Record<string, string>;
+  };
+}
+
+/**
+ * The centred modal, kept as ONE node that is both the fixed root and the
+ * backdrop.
+ *
+ * Refactoring it into the root + backdrop sibling pair the other
+ * presentations use would move markup live storefronts already style, for no
+ * gain — so it keeps its own branch, and `panel-legacy-golden.json` holds it
+ * there. It also deliberately does without the panel's `tabIndex={-1}`: adding
+ * it would move published markup, and the gap only shows in a composition with
+ * the close button off AND no focusable child.
+ */
+export const CentredModalSurface = ({
+  overlayProps,
+  ariaLabel,
+  closeOnOverlay,
+  onDismiss,
+  width,
+  header,
+  children,
+  markers
+}: Omit<
+  OverlaySurfaceProps,
+  'presentation' | 'showBackdrop' | 'panelSide' | 'sheetHeight'
+>) => (
+  <div
+    {...markers?.root}
+    {...partAttrs('overlay', { open: true })}
+    onClick={() => {
+      if (closeOnOverlay) onDismiss();
+    }}
+    style={{
+      position: 'fixed',
+      inset: 0,
+      zIndex: 1000,
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      padding: '16px',
+      background: 'rgba(0, 0, 0, 0.5)'
+    }}
+  >
+    <div
+      {...markers?.panel}
+      {...partAttrs('modal', { open: true })}
+      role="dialog"
+      {...overlayProps}
+      aria-label={ariaLabel}
+      // 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: `${width}px`,
+        maxHeight: '80vh',
+        overflow: 'auto',
+        padding: '24px',
+        borderRadius: '4px',
+        background: '#ffffff',
+        color: '#111827',
+        textAlign: 'left'
+      }}
+    >
+      {header}
+      {children}
+    </div>
+  </div>
+);
+
+/**
+ * Drawer, sheet and anchored: a panel plus an optional backdrop.
+ *
+ * With the backdrop off, the 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.
+ */
+export const LayeredOverlaySurface = ({
+  presentation,
+  overlayProps,
+  ariaLabel,
+  showBackdrop,
+  closeOnOverlay,
+  onDismiss,
+  width,
+  panelSide,
+  sheetHeight,
+  anchorAlign,
+  anchorOffset,
+  header,
+  children,
+  markers
+}: OverlaySurfaceProps) => {
+  const backdrop = showBackdrop ? (
+    <div
+      {...markers?.backdrop}
+      {...partAttrs('overlay', { open: true })}
+      onClick={() => {
+        if (closeOnOverlay) onDismiss();
+      }}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        background: 'rgba(0, 0, 0, 0.5)'
+      }}
+    />
+  ) : null;
+
+  const panel = (
+    <div
+      {...markers?.panel}
+      {...partAttrs('modal', { open: true })}
+      role="dialog"
+      {...overlayProps}
+      aria-label={ariaLabel}
+      // Focus target of last resort, for a panel whose every control the
+      // designer turned off.
+      tabIndex={-1}
+      onClick={(event) => event.stopPropagation()}
+      style={{
+        ...overlayPanelSurface,
+        ...resolveOverlayPanelGeometry({
+          presentation,
+          width,
+          panelSide,
+          sheetHeight,
+          anchorAlign,
+          anchorOffset
+        }),
+        pointerEvents: showBackdrop ? undefined : 'auto'
+      }}
+    >
+      {presentation === 'sheet' && (
+        <OverlaySheetHandle markerAttrs={markers?.handle} />
+      )}
+      {header}
+      {children}
+    </div>
+  );
+
+  if (presentation === 'anchored') {
+    return (
+      <>
+        {showBackdrop && (
+          <div
+            {...markers?.backdropRoot}
+            style={{ position: 'fixed', inset: 0, zIndex: 999 }}
+          >
+            {backdrop}
+          </div>
+        )}
+        {panel}
+      </>
+    );
+  }
+
+  return (
+    <div
+      {...markers?.root}
+      style={{
+        position: 'fixed',
+        inset: 0,
+        zIndex: 1000,
+        pointerEvents: showBackdrop ? undefined : 'none'
+      }}
+    >
+      {backdrop}
+      {panel}
+    </div>
+  );
+};