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

package/src/chrome/placeholder-slugs.ts

@@ -79,6 +79,47 @@ export type PlaceholderSlug =
 /** Custom pages created from the editor resolve to `page-<slug>` */
 export const customPageSlug = (slug: string) => `page-${slug}`;
 
+/**
+ * Modals created from the editor resolve to `modal-<id>`.
+ *
+ * A modal is the one composable surface with no route behind it: the designer
+ * creates it, names it, and opens it from anywhere. So its slug is derived from
+ * a GENERATED id rather than from the name — renaming "Newsletter" to "Sign up"
+ * must not orphan the composition saved under it — and never from a path,
+ * because a modal has none.
+ */
+export const MODAL_SLUG_PREFIX = 'modal-';
+
+/**
+ * Ids this slug family accepts. Deliberately a REFUSAL rather than the
+ * sanitising the path-derived helper above does.
+ *
+ * Sanitising maps several inputs onto one output, and for a content key that is
+ * not a tidy-up, it is a collision: two modals whose ids differ only by a
+ * character the cleaner strips would share one slug and silently overwrite each
+ * other's composition — the exact failure the table at the top of this file
+ * exists to prevent. The ids are ours (the editor generates them), so anything
+ * failing this pattern is a bug upstream and is better refused loudly than
+ * rewritten quietly.
+ */
+const MODAL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+/** `null` for an id this family cannot address — callers skip that modal. */
+export const modalSlug = (id: string): string | null =>
+  MODAL_ID_PATTERN.test(id) ? `${MODAL_SLUG_PREFIX}${id}` : null;
+
+export const isModalSlug = (slug: string): boolean =>
+  typeof slug === 'string' && slug.startsWith(MODAL_SLUG_PREFIX);
+
+/** The inverse of `modalSlug`, for turning a placeholder back into a modal id. */
+export const modalIdFromSlug = (slug: string): string | null => {
+  if (!isModalSlug(slug)) return null;
+
+  const id = slug.slice(MODAL_SLUG_PREFIX.length);
+
+  return MODAL_ID_PATTERN.test(id) ? id : null;
+};
+
 /**
  * Slug for a brand page that has no canonical placeholder — every bespoke
  * content route (about us, campaigns, returns policy…) gets one derived from

package/src/chrome/theme-config-source.ts

@@ -1,6 +1,8 @@
 import * as React from 'react';
 import { getWidgetData } from '@akinon/next/data/server';
 
+import { readThemeModals, ThemeModal } from '../overlays/modal-registry';
+
 /**
  * The `theme-config` widget, read and parsed once per request.
  *
@@ -15,6 +17,12 @@ export interface ThemeConfig {
   settings: Record<string, unknown> | null;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   dataSources: any[];
+  /**
+   * The modals this theme defines. Read here rather than by the modal host so
+   * it costs nothing: the host would otherwise be a third reader of a widget
+   * every page already fetches once.
+   */
+  modals: ThemeModal[];
 }
 
 type ThemeConfigWidget = {
@@ -34,11 +42,17 @@ const unwrapAttribute = (raw: unknown): unknown => {
 };
 
 export const readThemeConfig = (data: ThemeConfigWidget): ThemeConfig => {
-  const config: ThemeConfig = { settings: null, dataSources: [] };
+  const config: ThemeConfig = { settings: null, dataSources: [], modals: [] };
   const attributes = data?.attributes;
 
   if (!attributes) return config;
 
+  if (attributes.theme_modals) {
+    // `readThemeModals` already survives a malformed blob one entry at a time,
+    // so it needs no try/catch of its own here.
+    config.modals = readThemeModals(unwrapAttribute(attributes.theme_modals));
+  }
+
   if (attributes.theme_dataSources) {
     try {
       const resolved = unwrapAttribute(attributes.theme_dataSources);
@@ -76,12 +90,13 @@ const load = async (): Promise<ThemeConfig> => {
     const data = await getWidgetData<{
       theme_settings?: unknown;
       theme_dataSources?: unknown;
+      theme_modals?: unknown;
     }>({ slug: 'theme-config' });
 
     return readThemeConfig(data as ThemeConfigWidget);
   } catch {
     // A brand with no published theme still renders: no settings, no sources.
-    return { settings: null, dataSources: [] };
+    return { settings: null, dataSources: [], modals: [] };
   }
 };
 

package/src/components/with-designer-features.tsx

@@ -5,6 +5,10 @@ import React, { useEffect, useRef } from 'react';
 import { getResponsiveValue } from '../utils';
 import DesignerOverlay from './designer-overlay';
 import { useDesignerFeatures } from '../hooks/use-designer-features';
+import {
+  NATIVELY_INTERACTIVE_BLOCK_TYPES,
+  useBlockAction
+} from '../hooks/use-block-action';
 
 import { isTrustedEditorEvent } from '../editor-bridge';
 interface WithDesignerFeaturesProps {
@@ -77,6 +81,42 @@ export function WithDesignerFeatures({
     return () => window.removeEventListener('message', handleMessage);
   }, [actionBlockId, isDesigner]);
 
+  /**
+   * An authored action makes ANY block a trigger.
+   *
+   * It is wired here rather than in each renderer because the design decides
+   * what the trigger is — an image, an icon, a whole card — and enumerating
+   * those in advance is exactly what cannot be done. The wrapper is also the
+   * only element in the chain that already exists, so a block that becomes
+   * clickable gains no extra box and its layout does not move.
+   *
+   * `button` and `link` are excluded: they render a real `<button>`/`<a>` and
+   * wire the action onto it themselves. Handling it here too would nest a
+   * control inside a control, which is both invalid and double-fires.
+   */
+  const action = useBlockAction(block, { currentBreakpoint, isDesigner });
+  const ownsAction =
+    action.isActive && !NATIVELY_INTERACTIVE_BLOCK_TYPES.has(block.type);
+
+  const handleRootClick = (event: React.MouseEvent<HTMLDivElement>) => {
+    handleClick(event);
+
+    if (ownsAction) action.onClick?.(event);
+  };
+
+  /**
+   * Keyboard parity for the role this element just claimed. A div announced as
+   * a button that only answers the mouse is worse than an unannounced div: it
+   * promises an affordance to a keyboard user and then withholds it.
+   */
+  const handleRootKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    if (!ownsAction) return;
+    if (event.key !== 'Enter' && event.key !== ' ') return;
+    // Space would scroll the page underneath the modal it just opened.
+    event.preventDefault();
+    action.onClick?.(event as unknown as React.MouseEvent<HTMLElement>);
+  };
+
   const isButtonBlock = block.type === 'button';
 
   const buttonDisplay = isButtonBlock
@@ -95,7 +135,10 @@ export function WithDesignerFeatures({
   // but visually hide them.
   const mergedStyle: React.CSSProperties = {
     ...(style || {}),
-    ...(isDesigner && block.hidden ? { display: 'none' } : null)
+    ...(isDesigner && block.hidden ? { display: 'none' } : null),
+    // Only on the live site: the canvas already shows a pointer for selection,
+    // and a trigger there selects rather than fires.
+    ...(ownsAction && !isDesigner ? { cursor: 'pointer' } : null)
   };
 
   return (
@@ -109,7 +152,11 @@ export function WithDesignerFeatures({
         block.type === 'tab' && 'h-full'
       )}
       style={mergedStyle}
-      onClick={handleClick}
+      onClick={handleRootClick}
+      onKeyDown={ownsAction ? handleRootKeyDown : undefined}
+      role={ownsAction ? 'button' : undefined}
+      tabIndex={ownsAction ? 0 : undefined}
+      {...(ownsAction ? action.ariaProps : null)}
     >
       {isDesigner && (
         <DesignerOverlay

package/src/hooks/use-block-action.ts

@@ -0,0 +1,209 @@
+'use client';
+
+import React, { useCallback } from 'react';
+
+import { getResponsiveValue } from '../utils';
+import {
+  closeModal,
+  closeTopModal,
+  openModal,
+  toggleModal,
+  useModalOpen
+} from '../overlays/overlay-bus';
+
+/**
+ * What a block does when it is clicked.
+ *
+ * Until now the answer was hardcoded per block: `button` and `link` followed a
+ * `url` and nothing else could be clicked at all. A modal has to be openable
+ * from an image, an icon, a group — from whatever the design says the trigger
+ * is — so the behaviour becomes a property instead of a block type.
+ *
+ * Backward compatibility is the point of `'none'` being the absent value and
+ * `'link'` being what a url-carrying block already did: a composition
+ * published before this existed carries no `actionType` and behaves exactly as
+ * it did.
+ */
+
+export type BlockActionType =
+  | 'none'
+  | 'link'
+  | 'open-modal'
+  | 'close-modal'
+  | 'toggle-modal'
+  | 'close-top-modal'
+  | 'scroll-to';
+
+export const BLOCK_ACTION_TYPES: BlockActionType[] = [
+  'none',
+  'link',
+  'open-modal',
+  'close-modal',
+  'toggle-modal',
+  'close-top-modal',
+  'scroll-to'
+];
+
+const MODAL_ACTIONS: BlockActionType[] = [
+  'open-modal',
+  'close-modal',
+  'toggle-modal'
+];
+
+/**
+ * Blocks that render a real `<button>` or `<a>` and therefore wire the action
+ * onto that element themselves.
+ *
+ * The generic path in `WithDesignerFeatures` must skip them: a wrapper
+ * claiming `role="button"` around a real button nests one control inside
+ * another, which is invalid markup, announces twice, and fires the action
+ * twice on one click.
+ */
+export const NATIVELY_INTERACTIVE_BLOCK_TYPES: ReadonlySet<string> = new Set([
+  'button',
+  'link'
+]);
+
+export interface BlockActionSource {
+  properties?: Record<string, unknown> | null;
+}
+
+export interface BlockAction {
+  type: BlockActionType;
+  target: string;
+}
+
+export const resolveBlockAction = (
+  block: BlockActionSource,
+  currentBreakpoint = 'desktop'
+): BlockAction => {
+  const rawType = getResponsiveValue(
+    block.properties?.actionType,
+    currentBreakpoint,
+    'none'
+  );
+  const type = BLOCK_ACTION_TYPES.includes(rawType as BlockActionType)
+    ? (rawType as BlockActionType)
+    : 'none';
+
+  const target = String(
+    getResponsiveValue(block.properties?.actionTarget, currentBreakpoint, '') ??
+      ''
+  ).trim();
+
+  return { type, target };
+};
+
+/** True for an action this hook handles itself, i.e. not navigation. */
+export const isInteractiveAction = (type: BlockActionType): boolean =>
+  type !== 'none' && type !== 'link';
+
+export interface UseBlockActionResult {
+  /** Whether this block has an action that this hook performs. */
+  isActive: boolean;
+  /** Attach to the clickable element. `undefined` when there is no action. */
+  onClick?: (event: React.MouseEvent<HTMLElement>) => void;
+  /**
+   * Spread onto the same element. Announces a dialog trigger as one, which is
+   * what turns a styled div into something a screen reader user can act on
+   * deliberately rather than discover by accident.
+   */
+  ariaProps: {
+    'aria-haspopup'?: 'dialog';
+    'aria-expanded'?: boolean;
+    'aria-controls'?: string;
+  };
+}
+
+const scrollToAnchor = (target: string) => {
+  if (!target) return;
+
+  // Accepts `#reviews` and `reviews` alike: the designer typed one of them and
+  // does not care which, and `htmlId` is stored without the hash.
+  const id = target.startsWith('#') ? target.slice(1) : target;
+  const element = document.getElementById(id);
+
+  element?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+};
+
+/**
+ * Wire a block's authored action to the overlay bus.
+ *
+ * Inert in the designer: clicking a trigger in the canvas should select the
+ * block for editing, not open the modal over the workspace. The canvas has its
+ * own way to preview a modal (`use-modal-preview.ts`).
+ */
+export const useBlockAction = (
+  block: BlockActionSource,
+  {
+    currentBreakpoint = 'desktop',
+    isDesigner = false
+  }: { currentBreakpoint?: string; isDesigner?: boolean } = {}
+): UseBlockActionResult => {
+  const { type, target } = resolveBlockAction(block, currentBreakpoint);
+
+  // Subscribed unconditionally — a hook cannot be called on a branch — but an
+  // empty id never matches an open modal, so a block with no action pays only
+  // for the subscription.
+  const isTargetOpen = useModalOpen(
+    MODAL_ACTIONS.includes(type) ? target : ''
+  );
+
+  const handleClick = useCallback(
+    (event: React.MouseEvent<HTMLElement>) => {
+      if (isDesigner) return;
+
+      switch (type) {
+        case 'open-modal':
+          // A trigger that also navigates would race its own modal.
+          event.preventDefault();
+          openModal(target);
+          break;
+        case 'close-modal':
+          event.preventDefault();
+          closeModal(target);
+          break;
+        case 'toggle-modal':
+          event.preventDefault();
+          toggleModal(target);
+          break;
+        case 'close-top-modal':
+          event.preventDefault();
+          closeTopModal();
+          break;
+        case 'scroll-to':
+          event.preventDefault();
+          scrollToAnchor(target);
+          break;
+        default:
+          break;
+      }
+    },
+    [isDesigner, type, target]
+  );
+
+  const isActive = isInteractiveAction(type) && (type === 'close-top-modal' || Boolean(target));
+
+  if (!isActive) {
+    return { isActive: false, ariaProps: {} };
+  }
+
+  const opensDialog = type === 'open-modal' || type === 'toggle-modal';
+
+  return {
+    isActive: true,
+    onClick: handleClick,
+    ariaProps: opensDialog
+      ? {
+          'aria-haspopup': 'dialog',
+          'aria-expanded': isTargetOpen,
+          // Points at the mount wrapper, which carries `data-theme-modal` and
+          // is present only while the modal is open — so the reference is
+          // honest rather than pointing at markup that is not there.
+          'aria-controls': isTargetOpen ? `theme-modal-${target}` : undefined
+        }
+      : {}
+  };
+};
+
+export default useBlockAction;

package/src/index.ts

@@ -61,10 +61,60 @@ export {
 export {
   PLACEHOLDER_SLUGS,
   customPageSlug,
-  customPageSlugFromPath
+  customPageSlugFromPath,
+  MODAL_SLUG_PREFIX,
+  modalSlug,
+  isModalSlug,
+  modalIdFromSlug
 } from './chrome/placeholder-slugs';
 export type { PlaceholderSlug } from './chrome/placeholder-slugs';
 
+export {
+  openModal,
+  closeModal,
+  toggleModal,
+  closeTopModal,
+  closeAllModals,
+  isModalOpen,
+  getOpenModalIds,
+  subscribeToModals,
+  registerModalHost,
+  isModalHostMounted,
+  useModalOpen,
+  useOpenModalIds
+} from './overlays/overlay-bus';
+
+export {
+  readThemeModals,
+  MODAL_PRESENTATIONS
+} from './overlays/modal-registry';
+export type {
+  ThemeModal,
+  ModalChrome,
+  ModalPresentation,
+  ModalAutoTrigger,
+  ModalAutoTriggerEvent,
+  ModalFrequency
+} from './overlays/modal-registry';
+
+export { default as ThemeModals } from './overlays/theme-modals';
+export { default as ThemeModalMount } from './overlays/theme-modal-mount';
+
+export {
+  CentredModalSurface,
+  LayeredOverlaySurface,
+  OverlayCloseButton,
+  OVERLAY_PRESENTATIONS,
+  resolveOverlayPanelGeometry
+} from './overlays/overlay-surface';
+export type { OverlayPresentation } from './overlays/overlay-surface';
+
+export {
+  canAutoOpen,
+  markAutoOpened,
+  clearAutoOpenRecord
+} from './overlays/modal-frequency';
+
 export {
   resolveBodySlug,
   resolveBodySlugFromUrl,