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

package/src/overlays/overlay-surface.tsx

@@ -4,7 +4,10 @@ import React from 'react';
 import { partAttrs } from '../utils';
 import {
   OVERLAY_BACKDROP_COLOR,
-  OVERLAY_BACKDROP_OPACITY
+  OVERLAY_BACKDROP_OPACITY,
+  SHEET_HEIGHT_FALLBACK,
+  isSheetHeightLength,
+  resolveOverlayTopInset
 } from './overlay-tokens';
 import type { OverlayPresentation, OverlayWidthUnit } from './overlay-tokens';
 
@@ -101,6 +104,57 @@ export const resolveOverlayBackdrop = (
   return `rgba(${r}, ${g}, ${b}, ${alpha})`;
 };
 
+/**
+ * How a stretched panel hands its height down to the composition.
+ *
+ * The markup between the panel and the designer's blocks is fixed and ours:
+ * `<div data-placeholder>` then `<section data-section-id>` (whose content
+ * box is `display: contents`, so the section lays the block wrappers out
+ * directly). These rules make that fixed chain fill the panel; what happens
+ * INSIDE the section stays the designer's (a section set to Flex column with
+ * "space between" pins its last block to the drawer's bottom edge). The auth
+ * journey wrappers are carried along via `:has` so a flow's active step can
+ * fill the drawer without the designer hand-writing the chain.
+ *
+ * The chain has to be UNBROKEN, which is the whole difficulty: height is not
+ * inherited, it is passed down link by link, and one wrapper left at `auto`
+ * strands everything below it. That is why the composed forms are in the list
+ * too — an OTP form sits between the step and its phase, so a phase can only
+ * fill the drawer if the form does. A block that should NOT grow opts out with
+ * its own Flex control (`flex: 0 0 auto`), which outranks these rules.
+ */
+const AUTH_JOURNEY_PARTS = [
+  'data-auth-flow',
+  'data-auth-step',
+  'data-otp-phase',
+  'data-auth-form',
+  'data-register-form',
+  'data-otp-form',
+  'data-forgot-password'
+];
+
+const strandsOf = (attribute: string) => ({
+  /** The designer wrapper the generated stylesheet targets. */
+  wrapper: `[data-modal-stretch] [data-block-id]:has(>[${attribute}])`,
+  /** Our own element inside it. */
+  element: `[data-modal-stretch] [${attribute}]`
+});
+
+const PANEL_STRETCH_CSS = [
+  '[data-modal-stretch]>[data-placeholder]{flex:1 1 auto;min-height:0;display:flex;flex-direction:column}',
+  '[data-modal-stretch]>[data-placeholder]>section{flex:1 1 auto;min-height:0}',
+  `${AUTH_JOURNEY_PARTS.map((attribute) => strandsOf(attribute).wrapper).join(
+    ','
+  )}{flex:1 1 auto;min-height:0;display:flex;flex-direction:column}`,
+  `${AUTH_JOURNEY_PARTS.map((attribute) => strandsOf(attribute).element).join(
+    ','
+  )}{flex:1 1 auto;min-height:0}`
+].join('\n');
+
+export const PanelStretchStyles = () => (
+  <style dangerouslySetInnerHTML={{ __html: PANEL_STRETCH_CSS }} />
+);
+
 /** The panel's own box, before geometry places it. */
 export const overlayPanelSurface: React.CSSProperties = {
   overflow: 'auto',
@@ -118,12 +172,47 @@ export interface OverlayGeometryInput {
   /** Unit of `width`; px unless the composed modal's chrome says otherwise. */
   widthUnit?: OverlayWidthUnit;
   panelSide?: string;
-  /** Sheet height as a percentage of the viewport. */
-  sheetHeight?: number;
+  /**
+   * Sheet height. A number is vh (the historical form); a string is any CSS
+   * length, so `calc(100dvh - 172px)` can say "everything below the header".
+   */
+  sheetHeight?: number | string;
   anchorAlign?: 'start' | 'center' | 'end';
   anchorOffset?: number;
+  /**
+   * Whether the panel hands its height to the composition. Only the sheet
+   * reads it: a drawer is already full height and a centred dialog sizes
+   * itself in the surface rather than here.
+   */
+  panelStretch?: boolean;
 }
 
+/**
+ * A sheet's height, as a CSS length.
+ *
+ * A bare number is the historical form and means vh, which is what every
+ * published sheet carries. A string is taken as written, so a designer can say
+ * what a percentage cannot: `calc(100dvh - 172px)` is "everything below the
+ * header", and `fit-content` is "as tall as the composition needs".
+ *
+ * Rejected values fall back to the historical 60vh rather than reaching the
+ * browser: a declaration the browser drops would leave the panel with no height
+ * at all, and one carrying a brace or a semicolon would not be a length.
+ */
+export const resolveSheetHeight = (
+  value: number | string | undefined
+): string => {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return `${value}vh`;
+  }
+
+  if (typeof value === 'string' && isSheetHeightLength(value)) {
+    return value.trim();
+  }
+
+  return `${SHEET_HEIGHT_FALLBACK}vh`;
+};
+
 /**
  * Where the panel sits for a given presentation.
  *
@@ -136,9 +225,10 @@ export const resolveOverlayPanelGeometry = ({
   width,
   widthUnit = 'px',
   panelSide = 'right',
-  sheetHeight = 60,
+  sheetHeight = 60 as number | string,
   anchorAlign = 'start',
-  anchorOffset = 8
+  anchorOffset = 8,
+  panelStretch = false
 }: OverlayGeometryInput): React.CSSProperties => {
   if (presentation === 'drawer') {
     return {
@@ -158,7 +248,17 @@ export const resolveOverlayPanelGeometry = ({
       right: 0,
       bottom: 0,
       width: '100%',
-      maxHeight: `${sheetHeight}vh`,
+      /**
+       * A stretched sheet is TOLD its height rather than merely capped at it.
+       * `maxHeight` alone leaves the panel as tall as its content, so the flex
+       * column stretch turns on with no free space to hand out and a CTA given
+       * `margin-top: auto` does not move — which reads as the setting doing
+       * nothing. Unstretched, the cap stays the whole rule: a short sheet
+       * should still hug its content.
+       */
+      ...(panelStretch
+        ? { height: resolveSheetHeight(sheetHeight) }
+        : { maxHeight: resolveSheetHeight(sheetHeight) }),
       boxShadow: '0 -12px 32px rgba(0, 0, 0, 0.18)'
     };
   }
@@ -167,8 +267,8 @@ export const resolveOverlayPanelGeometry = ({
     anchorAlign === 'center'
       ? { left: '50%', transform: 'translateX(-50%)' }
       : anchorAlign === 'end'
-      ? { right: 0 }
-      : { left: 0 };
+        ? { right: 0 }
+        : { left: 0 };
 
   return {
     position: 'absolute',
@@ -186,13 +286,56 @@ export const resolveOverlayPanelGeometry = ({
 export interface OverlayCloseButtonProps {
   label: string;
   onClick: () => void;
+  /**
+   * Where the button sits inside the panel, and how big its glyph is.
+   *
+   * The button is positioned against the PANEL while a title row authored in
+   * the composition flows with its own padding, so the two never line up by
+   * accident. Absent keeps the historical 12 / 12 / 18 every published modal
+   * renders with.
+   */
+  top?: number | string;
+  right?: number | string;
+  size?: number | string;
+  /**
+   * Lift the button above the panel's authored content.
+   *
+   * A composed modal fills its panel with the designer's blocks, and a
+   * full-width one — a title row, a banner — paints OVER this button: it comes
+   * later in the DOM and the button, positioned but unlayered, loses. The click
+   * then lands on the heading and the ✕ does nothing at all, which is how this
+   * was found.
+   *
+   * A flag rather than always-on because the legacy size-guide panel renders
+   * the same button and its markup is pinned byte for byte by
+   * `panel-legacy-golden.json` — live storefronts style it. Only the composed
+   * hosts ask.
+   */
+  elevate?: boolean;
   /** Legacy marker attribute, e.g. `{ 'data-size-guide-close': '' }`. */
   markerAttrs?: Record<string, string>;
 }
 
+/** px unless the author wrote a length. */
+const asCssLength = (
+  value: number | string | undefined,
+  fallback: string
+): string => {
+  if (typeof value === 'number' && Number.isFinite(value)) return `${value}px`;
+  if (typeof value === 'string' && isSheetHeightLength(value)) {
+    return value.trim();
+  }
+
+  return fallback;
+};
+
 export const OverlayCloseButton = ({
   label,
   onClick,
+  top,
+  right,
+  size,
+  elevate,
   markerAttrs
 }: OverlayCloseButtonProps) => (
   <button
@@ -203,18 +346,31 @@ export const OverlayCloseButton = ({
     onClick={onClick}
     style={{
       position: 'absolute',
-      top: '12px',
-      right: '12px',
+      top: asCssLength(top, '12px'),
+      right: asCssLength(right, '12px'),
       border: 'none',
       background: 'transparent',
       color: 'inherit',
       cursor: 'pointer',
-      padding: 0
+      /**
+       * Untouched unless a size is asked for, and that is not fussiness: this
+       * button is the legacy size-guide panel's too, whose markup is pinned
+       * byte for byte by `panel-legacy-golden.json` because live storefronts
+       * style it. A hit area is worth having — the padding is what a thumb aims
+       * at, and the negative margin keeps the glyph where the offsets put it —
+       * but only a modal that asked for a size gets them.
+       */
+      ...(size === undefined
+        ? { padding: 0 }
+        : { padding: '8px', margin: '-8px', lineHeight: 0 }),
+      // Only has to beat static content, which is what the composition's
+      // blocks are; the panel's own layer sits at 1000 above the page.
+      ...(elevate ? { zIndex: 2 } : null)
     }}
   >
     <svg
-      width="18"
-      height="18"
+      width={size === undefined ? '18' : asCssLength(size, '18px')}
+      height={size === undefined ? '18' : asCssLength(size, '18px')}
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
@@ -261,6 +417,29 @@ export interface OverlaySurfaceProps extends OverlayGeometryInput {
   backdropOpacity?: number;
   closeOnOverlay: boolean;
   onDismiss: () => void;
+  /**
+   * The panel's inner padding in px; absent means the historical 24. Owned by
+   * the composed modal's chrome — the panel block keeps its fixed surface.
+   */
+  panelPadding?: number;
+  /**
+   * Stretch the composed content to the panel's full height (see
+   * `ModalChrome.stretchContent`). The panel becomes a flex column and the
+   * scoped rules below walk the stretch through the placeholder markup.
+   */
+  panelStretch?: boolean;
+  /**
+   * The sheet's grab bar. Absent reads as shown, which is what every published
+   * sheet has — a composition with its own header turns it off so the bar does
+   * not read as a stray line above the title.
+   */
+  showSheetHandle?: boolean;
+  /**
+   * How far down the whole overlay layer starts, so a sticky site header is
+   * neither covered nor dimmed. Absent means the layer covers the viewport,
+   * which is what every published modal does.
+   */
+  topInset?: number | string;
   /** Rendered inside the panel, above the authored content. */
   header?: React.ReactNode;
   children: React.ReactNode;
@@ -278,6 +457,18 @@ export interface OverlaySurfaceProps extends OverlayGeometryInput {
   };
 }
 
+/**
+ * The `top` a layer takes when the design keeps the site header clear, as a
+ * style object so both surfaces spread it the same way.
+ */
+const topInsetStyle = (
+  value: number | string | undefined
+): React.CSSProperties | null => {
+  const resolved = resolveOverlayTopInset(value);
+
+  return resolved ? { top: resolved } : null;
+};
+
 /**
  * The centred modal, kept as ONE node that is both the fixed root and the
  * backdrop.
@@ -298,6 +489,9 @@ export const CentredModalSurface = ({
   widthUnit,
   backdropColor,
   backdropOpacity,
+  panelPadding,
+  panelStretch,
+  topInset,
   header,
   children,
   markers
@@ -314,6 +508,11 @@ export const CentredModalSurface = ({
     style={{
       position: 'fixed',
       inset: 0,
+      // Same rule as the layered surface: this node IS the backdrop, so the
+      // inset is what keeps a sticky header visible and clickable. The dialog
+      // then centres in what is left, which is where a designer who asked for
+      // the header to stay clear expects it.
+      ...topInsetStyle(topInset),
       zIndex: 1000,
       display: 'flex',
       alignItems: 'center',
@@ -325,6 +524,7 @@ export const CentredModalSurface = ({
     <div
       {...markers?.panel}
       {...partAttrs('modal', { open: true })}
+      {...(panelStretch ? { 'data-modal-stretch': '' } : null)}
       role="dialog"
       {...overlayProps}
       aria-label={ariaLabel}
@@ -337,13 +537,21 @@ export const CentredModalSurface = ({
         maxWidth: resolveOverlayWidth(width, widthUnit),
         maxHeight: '80vh',
         overflow: 'auto',
-        padding: '24px',
+        padding: `${panelPadding ?? 24}px`,
         borderRadius: '4px',
         background: '#ffffff',
         color: '#111827',
-        textAlign: 'left'
+        textAlign: 'left',
+        ...(panelStretch
+          ? {
+              display: 'flex',
+              flexDirection: 'column' as const,
+              height: '80vh'
+            }
+          : null)
       }}
     >
+      {panelStretch && <PanelStretchStyles />}
       {header}
       {children}
     </div>
@@ -372,6 +580,10 @@ export const LayeredOverlaySurface = ({
   sheetHeight,
   anchorAlign,
   anchorOffset,
+  panelPadding,
+  panelStretch,
+  showSheetHandle,
+  topInset,
   header,
   children,
   markers
@@ -395,6 +607,7 @@ export const LayeredOverlaySurface = ({
     <div
       {...markers?.panel}
       {...partAttrs('modal', { open: true })}
+      {...(panelStretch ? { 'data-modal-stretch': '' } : null)}
       role="dialog"
       {...overlayProps}
       aria-label={ariaLabel}
@@ -404,6 +617,9 @@ export const LayeredOverlaySurface = ({
       onClick={(event) => event.stopPropagation()}
       style={{
         ...overlayPanelSurface,
+        ...(panelPadding !== undefined
+          ? { padding: `${panelPadding}px` }
+          : null),
         ...resolveOverlayPanelGeometry({
           presentation,
           width,
@@ -411,12 +627,17 @@ export const LayeredOverlaySurface = ({
           panelSide,
           sheetHeight,
           anchorAlign,
-          anchorOffset
+          anchorOffset,
+          panelStretch
         }),
-        pointerEvents: showBackdrop ? undefined : 'auto'
+        pointerEvents: showBackdrop ? undefined : 'auto',
+        ...(panelStretch
+          ? { display: 'flex', flexDirection: 'column' as const }
+          : null)
       }}
     >
-      {presentation === 'sheet' && (
+      {panelStretch && <PanelStretchStyles />}
+      {presentation === 'sheet' && showSheetHandle !== false && (
         <OverlaySheetHandle markerAttrs={markers?.handle} />
       )}
       {header}
@@ -430,7 +651,12 @@ export const LayeredOverlaySurface = ({
         {showBackdrop && (
           <div
             {...markers?.backdropRoot}
-            style={{ position: 'fixed', inset: 0, zIndex: 999 }}
+            style={{
+              position: 'fixed',
+              inset: 0,
+              ...topInsetStyle(topInset),
+              zIndex: 999
+            }}
           >
             {backdrop}
           </div>
@@ -446,6 +672,10 @@ export const LayeredOverlaySurface = ({
       style={{
         position: 'fixed',
         inset: 0,
+        // The inset is on the LAYER, not the panel: the backdrop lives here
+        // too, and a panel-only offset would leave the header dimmed and
+        // unclickable — which is exactly what the design does not do.
+        ...topInsetStyle(topInset),
         zIndex: 1000,
         pointerEvents: showBackdrop ? undefined : 'none'
       }}

package/src/overlays/overlay-tokens.ts

@@ -32,3 +32,97 @@ export const OVERLAY_WIDTH_UNITS: OverlayWidthUnit[] = ['px', '%', 'vw'];
 /** Backdrop paint defaults — what every published surface shipped with. */
 export const OVERLAY_BACKDROP_COLOR = '#000000';
 export const OVERLAY_BACKDROP_OPACITY = 50;
+
+/**
+ * How tall a sheet is, and what a designer is allowed to write for it.
+ *
+ * A number is a percentage of the viewport — the historical form every
+ * published sheet carries. A string is a 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".
+ *
+ * Lives here rather than beside the surface that applies it because the
+ * REGISTRY validates it, and the registry is parsed on the server — see the
+ * note at the top of this file for what importing a client module there costs.
+ */
+const SHEET_HEIGHT_KEYWORDS = new Set([
+  'auto',
+  'fit-content',
+  'min-content',
+  'max-content',
+  'stretch'
+]);
+
+/** Units a viewport-sized panel is plausibly measured in. */
+const SHEET_HEIGHT_UNIT =
+  '(px|%|vh|dvh|svh|lvh|vw|dvw|svw|lvw|rem|em|ch|ex|cm|mm|in|pt|pc|q)';
+
+const SHEET_HEIGHT_LENGTH = new RegExp(
+  `^-?\\d*\\.?\\d+${SHEET_HEIGHT_UNIT}$`,
+  'i'
+);
+
+const SHEET_HEIGHT_FUNCTION = /^(calc|min|max|clamp)\(.+\)$/i;
+
+/**
+ * Whether a string is a height the browser will accept.
+ *
+ * Strict on purpose: an earlier, looser check let `tall` through as a "length",
+ * and a declaration the browser drops leaves the panel with NO height — a sheet
+ * collapsed to its content with the composition spilling out of it. A function
+ * is checked for length-ish contents rather than parsed: nothing here may carry
+ * a brace, a semicolon, a `url()` or a `var()`, which are how a value stops
+ * being a measurement.
+ */
+export const isSheetHeightLength = (value: string): boolean => {
+  const trimmed = value.trim();
+
+  if (!trimmed || trimmed.length > 120) return false;
+  if (/[;{}]|url|expression/i.test(trimmed)) return false;
+  if (SHEET_HEIGHT_KEYWORDS.has(trimmed.toLowerCase())) return true;
+  if (SHEET_HEIGHT_LENGTH.test(trimmed)) return true;
+  // `var(--header-height)` and `env(safe-area-inset-top)`: a designer who
+  // knows the measure only as a variable has no other way to say it, and a
+  // custom property cannot break out of a declaration.
+  if (/^(var|env)\(--?[a-z0-9-]+(,[^;{}]*)?\)$/i.test(trimmed)) return true;
+
+  if (SHEET_HEIGHT_FUNCTION.test(trimmed)) {
+    // Inside a function only arithmetic, numbers, units, variables and nesting.
+    const body = trimmed.replace(/^(calc|min|max|clamp)\(/i, '').slice(0, -1);
+    return (
+      /^[0-9a-z\s().,%+*/_-]+$/i.test(body) &&
+      // A number or a variable has to appear, or this is words in parentheses.
+      (/\d/.test(body) || /var\(|env\(/i.test(body))
+    );
+  }
+
+  return false;
+};
+
+/**
+ * How far down the overlay layer starts.
+ *
+ * A bottom sheet in a design does not ride over the site header: the header
+ * stays visible AND clickable, and the dimming begins below it. That cannot be
+ * expressed as a panel height — the backdrop covers the header either way — so
+ * it is an inset on the layer itself, which the backdrop and the panel share.
+ *
+ * Same vocabulary as a sheet height: a number is px (the unit a header is
+ * measured in), a string is any length this module accepts.
+ */
+export const resolveOverlayTopInset = (
+  value: number | string | undefined
+): string | undefined => {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    return `${value}px`;
+  }
+
+  if (typeof value === 'string' && isSheetHeightLength(value)) {
+    return value.trim();
+  }
+
+  return undefined;
+};
+
+/** The default every sheet had before its height could be written out. */
+export const SHEET_HEIGHT_FALLBACK = 60;

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

@@ -7,7 +7,11 @@ 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 {
+  ThemeModal,
+  resolveModalChrome,
+  resolveModalPresentation
+} from './modal-registry';
 import {
   CentredModalSurface,
   LayeredOverlaySurface,
@@ -37,7 +41,8 @@ interface ThemeModalMountProps {
 
 const isDesignerWindow = () =>
   typeof window !== 'undefined' &&
-  (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner === true;
+  (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner ===
+    true;
 
 /**
  * One composed modal: the bus decides whether it is open, `useOverlay` decides
@@ -102,7 +107,18 @@ const ThemeModalMount = ({
   const supersededByEditor = origin === 'saved' && editorOwnsModal;
 
   const opened = !isPreviewing && !supersededByEditor && isOpen && existsHere;
-  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);
+  /**
+   * Resolved, not read: a modal is often a centred dialog on a desktop and a
+   * bottom sheet on a phone, and the shape decides the geometry, the backdrop
+   * and the sheet handle — so it has to be settled before any of them.
+   */
+  const presentation = resolveModalPresentation(modal, breakpoint);
   const isCentred = presentation === 'modal';
 
   /**
@@ -128,7 +144,14 @@ const ThemeModalMount = ({
   const dismiss = () => closeModal(modal.id);
 
   const header = chrome.showClose ? (
-    <OverlayCloseButton label={chrome.closeLabel} onClick={dismiss} />
+    <OverlayCloseButton
+      label={chrome.closeLabel}
+      onClick={dismiss}
+      top={chrome.closeTop}
+      right={chrome.closeRight}
+      size={chrome.closeSize}
+      elevate
+    />
   ) : null;
 
   const ariaLabel = chrome.ariaLabel || modal.name;
@@ -143,6 +166,9 @@ const ThemeModalMount = ({
       widthUnit={chrome.widthUnit}
       backdropColor={chrome.backdropColor}
       backdropOpacity={chrome.backdropOpacity}
+      panelPadding={chrome.padding}
+      panelStretch={chrome.stretchContent}
+      topInset={chrome.topInset}
       header={header}
     >
       {children}
@@ -161,6 +187,10 @@ const ThemeModalMount = ({
       backdropOpacity={chrome.backdropOpacity}
       panelSide={chrome.panelSide}
       sheetHeight={chrome.sheetHeight}
+      showSheetHandle={chrome.showSheetHandle}
+      topInset={chrome.topInset}
+      panelPadding={chrome.padding}
+      panelStretch={chrome.stretchContent}
       header={header}
     >
       {children}

package/src/theme-block.tsx

@@ -46,6 +46,12 @@ export interface Block {
   blocks?: Block[]; // Optional - only group blocks have nested blocks
   isIterator?: boolean;
   iteratorDataPath?: string;
+  /**
+   * Properties this clone resolved for itself from its row. One generated rule
+   * serves every clone, so these are the values that have to be inlined on the
+   * element — see `collectRowBoundStyleKeys` in utils/iterator-utils.ts.
+   */
+  rowStyleKeys?: string[];
 }
 
 interface ThemeBlockProps {