@akinon/pz-theme 2.0.64-rc.0 → 2.0.65-beta.0

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

@@ -82,9 +82,12 @@ describe('readThemeConfig', () => {
             showClose: true,
             closeLabel: 'Close',
             showBackdrop: true,
+            backdropColor: '#000000',
+            backdropOpacity: 50,
             closeOnBackdrop: true,
             closeOnEscape: true,
             width: 640,
+            widthUnit: 'px',
             panelSide: 'right',
             sheetHeight: 60,
             lockScroll: true

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

@@ -122,6 +122,42 @@ describe('the modal a designer is composing', () => {
     expect(screen.getByRole('dialog').style.maxWidth).toBe('420px');
   });
 
+  it('follows a width unit edit — a relative modal tracks the viewport', () => {
+    render(<ModalPreviewHost />);
+
+    hold(mkModal({ chrome: { width: 80, widthUnit: '%' } }));
+    expect(screen.getByRole('dialog').style.maxWidth).toBe('80%');
+
+    hold(mkModal({ chrome: { width: 90, widthUnit: 'vw' } }));
+    expect(screen.getByRole('dialog').style.maxWidth).toBe('90vw');
+  });
+
+  it('follows a backdrop edit, and defaults to the historical dimming', () => {
+    render(<ModalPreviewHost />);
+
+    // The centred surface's root IS the backdrop.
+    hold(mkModal());
+    const backdropOf = () =>
+      (
+        document.querySelector(
+          '[data-theme-modal] [data-part="overlay"]'
+        ) as HTMLElement
+      ).style.background;
+
+    expect(backdropOf()).toBe('rgba(0, 0, 0, 0.5)');
+
+    hold(
+      mkModal({
+        chrome: { backdropColor: '#1a2b3c', backdropOpacity: 80 }
+      })
+    );
+    expect(backdropOf()).toBe('rgba(26, 43, 60, 0.8)');
+
+    // Fully see-through is a legitimate choice, not a missing value.
+    hold(mkModal({ chrome: { backdropOpacity: 0 } }));
+    expect(backdropOf()).toBe('rgba(0, 0, 0, 0)');
+  });
+
   it('follows a presentation edit without a save or a reload', () => {
     render(<ModalPreviewHost />);
 

package/src/overlays/__tests__/modal-registry.test.ts

@@ -50,9 +50,12 @@ describe('readThemeModals', () => {
           showClose: true,
           closeLabel: 'Close',
           showBackdrop: true,
+          backdropColor: '#000000',
+          backdropOpacity: 50,
           closeOnBackdrop: true,
           closeOnEscape: true,
           width: 640,
+          widthUnit: 'px',
           panelSide: 'right',
           sheetHeight: 60,
           lockScroll: true
@@ -105,6 +108,40 @@ describe('readThemeModals', () => {
       expect(chromeOf({ sheetHeight: 300 }).sheetHeight).toBe(100);
     });
 
+    it('normalizes the backdrop paint, refusing junk colors', () => {
+      // Entries saved before backdrop settings existed keep today's paint.
+      expect(chromeOf({}).backdropColor).toBe('#000000');
+      expect(chromeOf({}).backdropOpacity).toBe(50);
+
+      expect(chromeOf({ backdropColor: '#1a2b3c' }).backdropColor).toBe(
+        '#1a2b3c'
+      );
+      expect(chromeOf({ backdropColor: '#fff' }).backdropColor).toBe('#fff');
+      // A dropped declaration would silently undim the page — junk falls back.
+      expect(chromeOf({ backdropColor: 'dark' }).backdropColor).toBe('#000000');
+      expect(
+        chromeOf({ backdropColor: 'url(javascript:1)' }).backdropColor
+      ).toBe('#000000');
+
+      expect(chromeOf({ backdropOpacity: 0 }).backdropOpacity).toBe(0);
+      expect(chromeOf({ backdropOpacity: 350 }).backdropOpacity).toBe(100);
+      expect(chromeOf({ backdropOpacity: 'dim' }).backdropOpacity).toBe(50);
+    });
+
+    it('reads a width unit, clamping relative widths to the viewport scale', () => {
+      // Entries saved before units existed carry none — they stay px.
+      expect(chromeOf({}).widthUnit).toBe('px');
+      expect(chromeOf({ widthUnit: 'em' }).widthUnit).toBe('px');
+
+      expect(chromeOf({ width: 80, widthUnit: '%' }).width).toBe(80);
+      expect(chromeOf({ width: 80, widthUnit: '%' }).widthUnit).toBe('%');
+      // Relative units live on a 10–100 scale; a px-scale value snaps into it
+      // instead of producing a 640vw overlay.
+      expect(chromeOf({ width: 640, widthUnit: 'vw' }).width).toBe(100);
+      expect(chromeOf({ width: 3, widthUnit: '%' }).width).toBe(10);
+      expect(chromeOf({ widthUnit: '%' }).width).toBe(80);
+    });
+
     it('refuses an unknown panel side', () => {
       expect(chromeOf({ panelSide: 'top' }).panelSide).toBe('right');
       expect(chromeOf({ panelSide: 'left' }).panelSide).toBe('left');

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

@@ -121,6 +121,9 @@ export const ModalPreviewHost = ({
         closeOnOverlay={false}
         onDismiss={noop}
         width={chrome.width}
+        widthUnit={chrome.widthUnit}
+        backdropColor={chrome.backdropColor}
+        backdropOpacity={chrome.backdropOpacity}
         header={header}
       >
         {composition(modal.slug)}
@@ -134,6 +137,9 @@ export const ModalPreviewHost = ({
         closeOnOverlay={false}
         onDismiss={noop}
         width={chrome.width}
+        widthUnit={chrome.widthUnit}
+        backdropColor={chrome.backdropColor}
+        backdropOpacity={chrome.backdropOpacity}
         panelSide={chrome.panelSide}
         sheetHeight={chrome.sheetHeight}
         header={header}

package/src/overlays/modal-registry.ts

@@ -1,6 +1,12 @@
 import { modalSlug } from '../chrome/placeholder-slugs';
 import { devWarn } from '../utils/dev-warn';
 import type { VisibilityRules } from '../utils/visibility-rules';
+import {
+  OVERLAY_BACKDROP_COLOR,
+  OVERLAY_BACKDROP_OPACITY,
+  OVERLAY_WIDTH_UNITS,
+  type OverlayWidthUnit
+} from './overlay-surface';
 
 /**
  * The modal registry: what modals this theme has, read off `theme-config`.
@@ -65,10 +71,19 @@ export interface ModalChrome {
   showClose: boolean;
   closeLabel: string;
   showBackdrop: boolean;
+  /** Backdrop paint. `#rrggbb` plus a 0–100 opacity; 0 is fully see-through. */
+  backdropColor: string;
+  backdropOpacity: number;
   closeOnBackdrop: boolean;
   closeOnEscape: boolean;
-  /** Drawer/anchored width, and the centred modal's max width, in px. */
+  /** Drawer/anchored width, and the centred modal's max width, in `widthUnit`. */
   width: number;
+  /**
+   * Unit of `width`. Relative units (`%`, `vw`) let a modal follow the
+   * viewport — a fixed pixel count cannot express "80% of the screen".
+   * Absent on entries saved before units existed, which reads as px.
+   */
+  widthUnit: OverlayWidthUnit;
   panelSide: 'left' | 'right';
   /** Sheet height as a percentage of the viewport. */
   sheetHeight: number;
@@ -146,6 +161,18 @@ const readAutoTrigger = (value: unknown): ModalAutoTrigger | undefined => {
   };
 };
 
+const HEX_COLOR_PATTERN = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+/**
+ * A junk color falls back instead of passing through: the surface would hand
+ * the browser an invalid declaration, the declaration would be dropped, and
+ * the page behind the modal would silently lose its dimming.
+ */
+const asHexColor = (value: unknown, fallback: string): string =>
+  typeof value === 'string' && HEX_COLOR_PATTERN.test(value.trim())
+    ? value.trim()
+    : fallback;
+
 const asToggle = (value: unknown, fallback: boolean): boolean =>
   typeof value === 'boolean' ? value : fallback;
 
@@ -170,6 +197,11 @@ const readChrome = (value: unknown, name: string): ModalChrome => {
   const showClose = asToggle(raw.showClose, true);
   const closeOnBackdrop = asToggle(raw.closeOnBackdrop, true);
   const closeOnEscape = asToggle(raw.closeOnEscape, true);
+  const widthUnit = asOption<OverlayWidthUnit>(
+    raw.widthUnit,
+    OVERLAY_WIDTH_UNITS,
+    'px'
+  );
 
   return {
     ariaLabel: asString(raw.ariaLabel) || name,
@@ -183,9 +215,22 @@ const readChrome = (value: unknown, name: string): ModalChrome => {
     showClose: showClose || (!closeOnBackdrop && !closeOnEscape),
     closeLabel: asString(raw.closeLabel) || 'Close',
     showBackdrop: asToggle(raw.showBackdrop, true),
+    backdropColor: asHexColor(raw.backdropColor, OVERLAY_BACKDROP_COLOR),
+    backdropOpacity: asClamped(
+      raw.backdropOpacity,
+      OVERLAY_BACKDROP_OPACITY,
+      0,
+      100
+    ),
     closeOnBackdrop,
     closeOnEscape,
-    width: asClamped(raw.width, 640, 240, 1600),
+    // px keeps its historical clamp; the relative units live on a 10–100
+    // scale of the viewport — 8000vw is not a width, it is a typo.
+    width:
+      widthUnit === 'px'
+        ? asClamped(raw.width, 640, 240, 1600)
+        : 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)

package/src/overlays/overlay-surface.tsx

@@ -31,6 +31,21 @@ export const OVERLAY_PRESENTATIONS: OverlayPresentation[] = [
   'anchored'
 ];
 
+export type OverlayWidthUnit = 'px' | '%' | 'vw';
+
+export const OVERLAY_WIDTH_UNITS: OverlayWidthUnit[] = ['px', '%', 'vw'];
+
+/**
+ * The overlay width as CSS. Unit-less callers (the panel block, whose markup
+ * `panel-legacy-golden.json` pins byte for byte) stay in px and keep emitting
+ * the exact strings they always did; a composed modal may carry `%` or `vw`
+ * so its surface can follow the viewport instead of a fixed pixel count.
+ */
+export const resolveOverlayWidth = (
+  width: number,
+  widthUnit: OverlayWidthUnit = 'px'
+): string => `${width}${widthUnit}`;
+
 export const clampOverlayNumber = (
   value: unknown,
   fallback: number,
@@ -43,6 +58,48 @@ export const clampOverlayNumber = (
   return Math.min(max, Math.max(min, numeric));
 };
 
+/** Backdrop paint defaults — what every published surface shipped with. */
+export const OVERLAY_BACKDROP_COLOR = '#000000';
+export const OVERLAY_BACKDROP_OPACITY = 50;
+
+const HEX_COLOR_PATTERN = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+/**
+ * The backdrop as CSS. The defaults reproduce the historical paint byte for
+ * byte — `rgba(0, 0, 0, 0.5)` — which the panel block's golden markup pins,
+ * so a surface given no backdrop settings cannot drift. Junk color falls
+ * back to black rather than to an invalid declaration the browser drops,
+ * which would leave the page behind the modal fully undimmed.
+ */
+export const resolveOverlayBackdrop = (
+  color?: string,
+  opacity?: number
+): string => {
+  const hex = HEX_COLOR_PATTERN.test(color || '')
+    ? (color as string)
+    : OVERLAY_BACKDROP_COLOR;
+  const digits = hex.slice(1);
+  const full =
+    digits.length === 3
+      ? digits
+          .split('')
+          .map((digit) => digit + digit)
+          .join('')
+      : digits;
+
+  const numericOpacity = Number(opacity);
+  const clampedOpacity = Number.isFinite(numericOpacity)
+    ? Math.min(100, Math.max(0, numericOpacity))
+    : OVERLAY_BACKDROP_OPACITY;
+
+  const r = parseInt(full.slice(0, 2), 16);
+  const g = parseInt(full.slice(2, 4), 16);
+  const b = parseInt(full.slice(4, 6), 16);
+  const alpha = Number((clampedOpacity / 100).toFixed(2));
+
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+};
+
 /** The panel's own box, before geometry places it. */
 export const overlayPanelSurface: React.CSSProperties = {
   overflow: 'auto',
@@ -55,8 +112,10 @@ export const overlayPanelSurface: React.CSSProperties = {
 
 export interface OverlayGeometryInput {
   presentation: OverlayPresentation;
-  /** Drawer/anchored width and the centred modal's max width, in px. */
+  /** Drawer/anchored width and the centred modal's max width, in `widthUnit`. */
   width: number;
+  /** 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;
@@ -74,6 +133,7 @@ export interface OverlayGeometryInput {
 export const resolveOverlayPanelGeometry = ({
   presentation,
   width,
+  widthUnit = 'px',
   panelSide = 'right',
   sheetHeight = 60,
   anchorAlign = 'start',
@@ -85,7 +145,7 @@ export const resolveOverlayPanelGeometry = ({
       top: 0,
       bottom: 0,
       [panelSide === 'left' ? 'left' : 'right']: 0,
-      width: `min(${width}px, 92vw)`,
+      width: `min(${resolveOverlayWidth(width, widthUnit)}, 92vw)`,
       boxShadow: '0 0 24px rgba(0, 0, 0, 0.2)'
     };
   }
@@ -113,7 +173,7 @@ export const resolveOverlayPanelGeometry = ({
     position: 'absolute',
     top: `calc(100% + ${anchorOffset}px)`,
     zIndex: 1000,
-    width: `${width}px`,
+    width: resolveOverlayWidth(width, widthUnit),
     maxWidth: '92vw',
     maxHeight: '80vh',
     borderRadius: '4px',
@@ -195,6 +255,9 @@ export interface OverlaySurfaceProps extends OverlayGeometryInput {
   overlayProps: OverlayHandleProps;
   ariaLabel: string;
   showBackdrop: boolean;
+  /** Backdrop paint; absent means the historical rgba(0, 0, 0, 0.5). */
+  backdropColor?: string;
+  backdropOpacity?: number;
   closeOnOverlay: boolean;
   onDismiss: () => void;
   /** Rendered inside the panel, above the authored content. */
@@ -231,6 +294,9 @@ export const CentredModalSurface = ({
   closeOnOverlay,
   onDismiss,
   width,
+  widthUnit,
+  backdropColor,
+  backdropOpacity,
   header,
   children,
   markers
@@ -252,7 +318,7 @@ export const CentredModalSurface = ({
       alignItems: 'center',
       justifyContent: 'center',
       padding: '16px',
-      background: 'rgba(0, 0, 0, 0.5)'
+      background: resolveOverlayBackdrop(backdropColor, backdropOpacity)
     }}
   >
     <div
@@ -267,7 +333,7 @@ export const CentredModalSurface = ({
       style={{
         position: 'relative',
         width: '100%',
-        maxWidth: `${width}px`,
+        maxWidth: resolveOverlayWidth(width, widthUnit),
         maxHeight: '80vh',
         overflow: 'auto',
         padding: '24px',
@@ -295,9 +361,12 @@ export const LayeredOverlaySurface = ({
   overlayProps,
   ariaLabel,
   showBackdrop,
+  backdropColor,
+  backdropOpacity,
   closeOnOverlay,
   onDismiss,
   width,
+  widthUnit,
   panelSide,
   sheetHeight,
   anchorAlign,
@@ -316,7 +385,7 @@ export const LayeredOverlaySurface = ({
       style={{
         position: 'absolute',
         inset: 0,
-        background: 'rgba(0, 0, 0, 0.5)'
+        background: resolveOverlayBackdrop(backdropColor, backdropOpacity)
       }}
     />
   ) : null;
@@ -337,6 +406,7 @@ export const LayeredOverlaySurface = ({
         ...resolveOverlayPanelGeometry({
           presentation,
           width,
+          widthUnit,
           panelSide,
           sheetHeight,
           anchorAlign,

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

@@ -140,6 +140,9 @@ const ThemeModalMount = ({
       closeOnOverlay={chrome.closeOnBackdrop}
       onDismiss={dismiss}
       width={chrome.width}
+      widthUnit={chrome.widthUnit}
+      backdropColor={chrome.backdropColor}
+      backdropOpacity={chrome.backdropOpacity}
       header={header}
     >
       {children}
@@ -153,6 +156,9 @@ const ThemeModalMount = ({
       closeOnOverlay={chrome.closeOnBackdrop}
       onDismiss={dismiss}
       width={chrome.width}
+      widthUnit={chrome.widthUnit}
+      backdropColor={chrome.backdropColor}
+      backdropOpacity={chrome.backdropOpacity}
       panelSide={chrome.panelSide}
       sheetHeight={chrome.sheetHeight}
       header={header}