@akinon/pz-theme 2.0.83-rc.0 → 2.0.84-beta.0

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

@@ -12,6 +12,8 @@ import {
 import ThemeModalMount from './theme-modal-mount';
 import { useEditorModals } from './use-editor-modals';
 import { useHeldModal } from './use-modal-preview';
+import { resolveModalChrome, resolveModalPresentation } from './modal-registry';
+import { useOverlayBreakpoint } from './use-overlay-breakpoint';
 
 interface ModalPreviewHostProps {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -63,6 +65,9 @@ export const ModalPreviewHost = ({
 }: ModalPreviewHostProps) => {
   const modal = useHeldModal();
   const editorModals = useEditorModals();
+  // Above the early return below: a hook that runs on some renders and not
+  // others is the one thing React cannot survive.
+  const breakpoint = useOverlayBreakpoint();
 
   const composition = (slug: string) => (
     <ThemePlaceholderWrapper
@@ -101,14 +106,33 @@ export const ModalPreviewHost = ({
 
   if (!modal) return triggerable;
 
-  const { chrome, presentation } = modal;
+  /**
+   * Resolved, not read: a sheet's height and the weight of its backdrop are
+   * answered per device, so the values have to be settled for THIS breakpoint
+   * before any of them reaches a style.
+   */
+  const chrome = resolveModalChrome(modal, breakpoint);
+  /**
+   * The canvas has to show the shape the chosen device will get: a designer who
+   * switches the editor to mobile and still sees a centred dialog has no way to
+   * lay out the sheet they just asked for. The hook reads the editor's forced
+   * breakpoint inside the iframe, so this follows the viewport buttons.
+   */
+  const presentation = resolveModalPresentation(modal, breakpoint);
 
   // 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} />
+    <OverlayCloseButton
+      label={chrome.closeLabel}
+      onClick={noop}
+      top={chrome.closeTop}
+      right={chrome.closeRight}
+      size={chrome.closeSize}
+      elevate
+    />
   ) : null;
 
   const ariaLabel = chrome.ariaLabel || modal.name;
@@ -124,6 +148,12 @@ export const ModalPreviewHost = ({
         widthUnit={chrome.widthUnit}
         backdropColor={chrome.backdropColor}
         backdropOpacity={chrome.backdropOpacity}
+        // The canvas preview has to show what the storefront will: this host is
+        // where "I set the padding to 0 and nothing happened" came from the
+        // first time, because only the real mount was passing them through.
+        panelPadding={chrome.padding}
+        panelStretch={chrome.stretchContent}
+        topInset={chrome.topInset}
         header={header}
       >
         {composition(modal.slug)}
@@ -140,8 +170,15 @@ export const ModalPreviewHost = ({
         widthUnit={chrome.widthUnit}
         backdropColor={chrome.backdropColor}
         backdropOpacity={chrome.backdropOpacity}
+        // The canvas preview has to show what the storefront will: this host is
+        // where "I set the padding to 0 and nothing happened" came from the
+        // first time, because only the real mount was passing them through.
+        panelPadding={chrome.padding}
+        panelStretch={chrome.stretchContent}
         panelSide={chrome.panelSide}
         sheetHeight={chrome.sheetHeight}
+        showSheetHandle={chrome.showSheetHandle}
+        topInset={chrome.topInset}
         header={header}
       >
         {composition(modal.slug)}

package/src/overlays/modal-registry.ts

@@ -8,6 +8,8 @@ import {
   OVERLAY_BACKDROP_COLOR,
   OVERLAY_BACKDROP_OPACITY,
   OVERLAY_WIDTH_UNITS,
+  SHEET_HEIGHT_FALLBACK,
+  isSheetHeightLength,
   type OverlayWidthUnit
 } from './overlay-tokens';
 
@@ -88,9 +90,72 @@ export interface ModalChrome {
    */
   widthUnit: OverlayWidthUnit;
   panelSide: 'left' | 'right';
-  /** Sheet height as a percentage of the viewport. */
-  sheetHeight: number;
+  /**
+   * Sheet height. A number is a percentage of the viewport (the historical
+   * form); a string is any CSS length, which is the only way to say what a
+   * percentage cannot — `calc(100dvh - 172px)` is "everything below the
+   * header", `fit-content` is "as tall as the composition needs".
+   */
+  sheetHeight: number | string;
   lockScroll: boolean;
+  /**
+   * The panel's inner padding in px. Optional because every modal saved before
+   * this existed has no value, and those must keep rendering with the 24 the
+   * surfaces have always applied.
+   */
+  padding?: number;
+  /**
+   * How far down the overlay starts, so a sticky site header is neither covered
+   * nor dimmed — the design's bottom sheet does not ride over the header. A
+   * number is px (the unit a header is measured in); a string is any length,
+   * including `var(--header-height)`. Absent means the overlay covers the
+   * viewport, which is what every modal published so far does.
+   */
+  topInset?: number | string;
+  /**
+   * Where the built-in close button sits inside the panel, and how big it is.
+   *
+   * The button is chrome: it is positioned against the PANEL, while a title row
+   * authored in the composition flows with its own padding. The two are in
+   * different coordinate systems, so they never line up by accident — and part
+   * styles cannot reach chrome (a part rule hangs off a `[data-block-id]`,
+   * which chrome has none of). These are the way to align them. Absent keeps
+   * the historical 12px / 12px / 18px every published modal renders with.
+   */
+  closeTop?: number | string;
+  closeRight?: number | string;
+  closeSize?: number | string;
+  /**
+   * The grab bar a sheet draws at its top centre. Absent reads as ON, because
+   * every sheet published so far has one and removing it silently would move
+   * their markup. A composition with its own header does not want it: the bar
+   * then reads as a stray line above the title.
+   */
+  showSheetHandle?: boolean;
+  /**
+   * Hands the panel's full height down to the composition, so a drawer can pin
+   * its CTA to the bottom edge instead of leaving it under the last field. Off
+   * by default and optional for the same backward-compatibility reason as
+   * `padding` — see `PANEL_STRETCH_CSS` in overlay-surface.tsx for the chain it
+   * turns on.
+   */
+  stretchContent?: boolean;
+}
+
+/**
+ * The chrome fields that may be answered again for a narrower breakpoint.
+ * Absent means "whatever the wider breakpoint said" — never a copied value, so
+ * a later change to the desktop answer still reaches the phone.
+ */
+export interface ModalChromeOverrides {
+  sheetHeight?: number | string;
+  topInset?: number | string;
+  /** A title row is padded differently per device, so these follow it. */
+  closeTop?: number | string;
+  closeRight?: number | string;
+  closeSize?: number | string;
+  backdropColor?: string;
+  backdropOpacity?: number;
 }
 
 export interface ThemeModal {
@@ -101,7 +166,34 @@ export interface ThemeModal {
   /** `modal-<id>`, the widget slug the composition is saved under. */
   slug: string;
   presentation: ModalPresentation;
+  /**
+   * The presentation to use at a narrower breakpoint, when it differs.
+   *
+   * A centred modal is the wrong shape on a phone: the pattern every storefront
+   * reaches for there is a bottom sheet that fills the screen, with the CTA on
+   * its bottom edge. That is not a variant of the desktop dialog — it is a
+   * different presentation — and one scalar could not express both.
+   *
+   * A breakpoint left out follows the desktop choice, so every modal saved
+   * before this existed presents exactly as it did.
+   */
+  presentationByBreakpoint?: Partial<
+    Record<'tablet' | 'mobile', ModalPresentation>
+  >;
   chrome: ModalChrome;
+  /**
+   * Chrome values that differ at a narrower breakpoint.
+   *
+   * Only the settings whose right answer genuinely changes with the device: a
+   * sheet that should cover 92% of a phone is not the same measure as the 60%
+   * it gets on a desktop, and a backdrop dark enough behind a small sheet is
+   * too heavy behind a centred dialog. Everything else stays single-valued,
+   * because a control that can differ per device is a control a designer has
+   * to check three times.
+   */
+  chromeByBreakpoint?: Partial<
+    Record<'tablet' | 'mobile', ModalChromeOverrides>
+  >;
   autoTrigger?: ModalAutoTrigger;
   /**
    * Where this modal EXISTS — the same rule object sections and blocks already
@@ -191,6 +283,238 @@ const asClamped = (
   return Math.min(max, Math.max(min, numeric));
 };
 
+/**
+ * Like `asClamped`, but absence survives.
+ *
+ * A setting whose default lives in the renderer (the panel's historical 24px
+ * padding) must come out of here as `undefined` when it was never authored —
+ * defaulting it in the parser would make every modal saved before the control
+ * existed claim a value it never had.
+ */
+const asOptionalClamped = (
+  value: unknown,
+  min: number,
+  max: number
+): number | undefined => {
+  if (value === undefined || value === null || value === '') return undefined;
+
+  const numeric = Math.round(Number(value));
+  if (!Number.isFinite(numeric)) return undefined;
+
+  return Math.min(max, Math.max(min, numeric));
+};
+
+/**
+ * Reads the per-breakpoint presentation overrides.
+ *
+ * Absence is preserved rather than filled with the desktop value: an override
+ * that merely repeats the desktop choice would be indistinguishable from one a
+ * designer set deliberately, and the resolver below is the single place that
+ * decides what an absent breakpoint means.
+ */
+const readPresentationByBreakpoint = (
+  value: unknown
+): ThemeModal['presentationByBreakpoint'] => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const raw = value as Record<string, unknown>;
+  const overrides: Partial<Record<'tablet' | 'mobile', ModalPresentation>> = {};
+
+  (['tablet', 'mobile'] as const).forEach((breakpoint) => {
+    const candidate = raw[breakpoint];
+    if (
+      typeof candidate === 'string' &&
+      MODAL_PRESENTATIONS.includes(candidate as ModalPresentation)
+    ) {
+      overrides[breakpoint] = candidate as ModalPresentation;
+    }
+  });
+
+  return Object.keys(overrides).length > 0 ? overrides : undefined;
+};
+
+/**
+ * Reads the per-breakpoint chrome overrides.
+ *
+ * Each field goes through the same validation as its base counterpart — a junk
+ * colour or an out-of-range height must not become an override the base value
+ * could never have been. A breakpoint whose every field was rejected comes back
+ * absent rather than as an empty object nobody chose.
+ */
+const readChromeByBreakpoint = (
+  value: unknown
+): ThemeModal['chromeByBreakpoint'] => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const raw = value as Record<string, unknown>;
+  const overrides: Partial<Record<'tablet' | 'mobile', ModalChromeOverrides>> =
+    {};
+
+  (['tablet', 'mobile'] as const).forEach((breakpoint) => {
+    const entry = raw[breakpoint];
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return;
+
+    const fields = entry as Record<string, unknown>;
+    const next: ModalChromeOverrides = {};
+
+    if (
+      fields.sheetHeight !== undefined &&
+      fields.sheetHeight !== null &&
+      fields.sheetHeight !== ''
+    ) {
+      // Sentinel-free: an override that fails validation is dropped rather
+      // than falling back to 60, which would be an answer nobody gave.
+      const sheetHeight = asSheetHeight(fields.sheetHeight, '');
+      if (sheetHeight !== '') next.sheetHeight = sheetHeight;
+    }
+
+    if (
+      typeof fields.backdropColor === 'string' &&
+      HEX_COLOR_PATTERN.test(fields.backdropColor.trim())
+    ) {
+      next.backdropColor = fields.backdropColor.trim();
+    }
+
+    const backdropOpacity = asOptionalClamped(fields.backdropOpacity, 0, 100);
+    if (backdropOpacity !== undefined) next.backdropOpacity = backdropOpacity;
+
+    // A header is a different height on a phone, so this belongs per breakpoint.
+    const topInset = asChromeLength(fields.topInset);
+    if (topInset !== undefined) next.topInset = topInset;
+
+    (
+      [
+        ['closeTop', 200],
+        ['closeRight', 200],
+        ['closeSize', 64]
+      ] as const
+    ).forEach(([field, max]) => {
+      const measure = asChromeLength(fields[field], max);
+      if (measure !== undefined) next[field] = measure;
+    });
+
+    if (Object.keys(next).length > 0) overrides[breakpoint] = next;
+  });
+
+  return Object.keys(overrides).length > 0 ? overrides : undefined;
+};
+
+/**
+ * The chrome to render at one breakpoint.
+ *
+ * Overrides fall UP the chain exactly as the presentation does: a phone takes
+ * its own answer, then the tablet's, then the desktop's. Returns the SAME
+ * object when nothing overrides, so a modal without overrides is not merely
+ * equal but identical — no new object per render.
+ */
+export const resolveModalChrome = (
+  modal: Pick<ThemeModal, 'chrome' | 'chromeByBreakpoint'>,
+  breakpoint?: string
+): ModalChrome => {
+  const overrides = modal.chromeByBreakpoint;
+  if (!overrides) return modal.chrome;
+
+  // Widest first: each layer overwrites what the wider one said.
+  const chain: (ModalChromeOverrides | undefined)[] = [];
+  if (breakpoint === 'tablet' || breakpoint === 'mobile') {
+    chain.push(overrides.tablet);
+  }
+  if (breakpoint === 'mobile') {
+    chain.push(overrides.mobile);
+  }
+
+  const applied = chain.filter(Boolean) as ModalChromeOverrides[];
+  if (applied.length === 0) return modal.chrome;
+
+  return applied.reduce<ModalChrome>(
+    (chrome, layer) => ({ ...chrome, ...layer }),
+    modal.chrome
+  );
+};
+
+/**
+ * The presentation to render at one breakpoint.
+ *
+ * Narrower breakpoints fall UP the chain rather than to the desktop value: a
+ * modal told to be a sheet on tablet should stay a sheet on a phone, which is
+ * the narrower device, unless the phone was given its own answer. Anything
+ * else would have a designer set two controls to say one thing.
+ */
+export const resolveModalPresentation = (
+  modal: Pick<ThemeModal, 'presentation' | 'presentationByBreakpoint'>,
+  breakpoint?: string
+): ModalPresentation => {
+  const overrides = modal.presentationByBreakpoint;
+  if (!overrides) return modal.presentation;
+
+  if (breakpoint === 'mobile') {
+    return overrides.mobile ?? overrides.tablet ?? modal.presentation;
+  }
+
+  if (breakpoint === 'tablet') {
+    return overrides.tablet ?? modal.presentation;
+  }
+
+  return modal.presentation;
+};
+
+/**
+ * A sheet height, as a number of viewport percent or as a CSS length.
+ *
+ * The number keeps its historical clamp — 4000 is not a height. A string is
+ * kept only if it reads as a length: the surface resolves it, and a value
+ * carrying a brace or a semicolon would not be one. Junk falls back rather
+ * than passing through, so the panel is never left with no height at all.
+ */
+const asSheetHeight = (
+  value: unknown,
+  fallback: number | string
+): number | string => {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    // A plain numeric string is the number, not a length: an editor input hands
+    // back "80", and `80` alone is not valid CSS.
+    if (/^\d+(\.\d+)?$/.test(trimmed)) {
+      return asClamped(trimmed, SHEET_HEIGHT_FALLBACK, 20, 100);
+    }
+
+    return isSheetHeightLength(trimmed) ? trimmed : fallback;
+  }
+
+  const numeric = Math.round(Number(value));
+  if (!Number.isFinite(numeric)) return fallback;
+
+  return Math.min(100, Math.max(20, numeric));
+};
+
+/**
+ * A measurement in px or as a written length. Absent stays absent: a value of
+ * `0` and no value at all render differently — only the second says "the
+ * designer never asked for this", which is what lets the renderer keep its own
+ * default.
+ */
+const asChromeLength = (
+  value: unknown,
+  max = 600
+): number | string | undefined => {
+  if (value === undefined || value === null || value === '') return undefined;
+
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (/^\d+(\.\d+)?$/.test(trimmed)) {
+      return asOptionalClamped(trimmed, 0, max);
+    }
+
+    return isSheetHeightLength(trimmed) ? trimmed : undefined;
+  }
+
+  return asOptionalClamped(value, 0, max);
+};
+
 const readChrome = (value: unknown, name: string): ModalChrome => {
   const raw =
     value && typeof value === 'object' && !Array.isArray(value)
@@ -235,8 +559,20 @@ const readChrome = (value: unknown, name: string): ModalChrome => {
         : asClamped(raw.width, 80, 10, 100),
     widthUnit,
     panelSide: raw.panelSide === 'left' ? 'left' : 'right',
-    sheetHeight: asClamped(raw.sheetHeight, 60, 20, 100),
-    lockScroll: asToggle(raw.lockScroll, true)
+    sheetHeight: asSheetHeight(raw.sheetHeight, 60),
+    lockScroll: asToggle(raw.lockScroll, true),
+    // Read, not defaulted: 0 is a real answer ("no padding at all"), which is
+    // why absence has to stay distinguishable from it. The upper bound is a
+    // typo guard — 2400 is not a padding.
+    padding: asOptionalClamped(raw.padding, 0, 200),
+    // Absent reads as on: every sheet published before this toggle has a bar.
+    showSheetHandle: asToggle(raw.showSheetHandle, true),
+    topInset: asChromeLength(raw.topInset),
+    closeTop: asChromeLength(raw.closeTop, 200),
+    closeRight: asChromeLength(raw.closeRight, 200),
+    // A tap target below ~24px is hard to hit and above ~64px is not an icon.
+    closeSize: asChromeLength(raw.closeSize, 64),
+    stretchContent: asToggle(raw.stretchContent, false)
   };
 };
 
@@ -275,6 +611,10 @@ export const readThemeModal = (value: unknown): ThemeModal | null => {
     name,
     slug,
     presentation: asOption(raw.presentation, MODAL_PRESENTATIONS, 'modal'),
+    presentationByBreakpoint: readPresentationByBreakpoint(
+      raw.presentationByBreakpoint
+    ),
+    chromeByBreakpoint: readChromeByBreakpoint(raw.chromeByBreakpoint),
     chrome: readChrome(raw.chrome, name),
     autoTrigger: readAutoTrigger(raw.autoTrigger),
     visibilityRules: