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

package/src/blocks/text-block.tsx

@@ -1,39 +1,11 @@
 'use client';
 
 import { useLocalization } from '@akinon/next/hooks';
-import React from 'react';
+import React, { useMemo } from 'react';
 import { BlockRendererProps } from './block-renderer-registry';
-import { getCSSStyles } from '../utils';
+import { getInnerRootInlineStyles, partAttrs } from '../utils';
 import { useThemeSettingsContext } from '../theme-settings-context';
 
-/**
- * The block's box geometry, which this div must not wear.
- *
- * Everything else in a text block's style map has to be applied here, and not
- * because the stylesheet forgot it: a bound value (`{{item.badgeColor}}`) is
- * deliberately stripped from the shared `[data-block-id]` rule, because every
- * row of an iterator shares that id and a rule cannot hold a different colour
- * per row. Inline is the only place a per-row value can land.
- *
- * Margin and padding are the exception. They describe the block's box, the
- * stylesheet already puts them on the `[data-block-id]` wrapper this div renders
- * inside, and a box inside a box means they compound — a designer setting 29px
- * under a heading got 29 on the wrapper and 29 again here, with nothing in the
- * inspector to explain the second one. Measured on a live page: nine blocks
- * carried the same margin at both levels.
- *
- * A BOUND margin is the one thing this gives up, and it is not a thing: row data
- * carries prices and colours, not the spacing of the box it is drawn in.
- */
-const BOX_GEOMETRY_PREFIXES = ['margin', 'padding'];
-
-const isBoxGeometryKey = (key: string): boolean => {
-  const normalized = key.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
-  return BOX_GEOMETRY_PREFIXES.some(
-    (prefix) => normalized === prefix || normalized.startsWith(`${prefix}-`)
-  );
-};
-
 const TextBlock = ({
   block,
   currentBreakpoint = 'desktop'
@@ -68,20 +40,25 @@ const TextBlock = ({
 
   const content = getLocalizedContent();
 
-  const wrapperStyles = React.useMemo(() => {
-    const styles = block.styles || {};
-    const withoutBoxGeometry = Object.fromEntries(
-      Object.entries(styles).filter(([key]) => !isBoxGeometryKey(key))
+  /**
+   * Only the values the generated stylesheet cannot produce. Everything else
+   * now arrives as a rule against this element (`data-part="root"`), so a
+   * padding is applied once instead of landing on the designer wrapper AND
+   * being inlined here — which is what doubled every spacing set on a text.
+   */
+  const rootStyles = useMemo(() => {
+    return getInnerRootInlineStyles(
+      block.styles || {},
+      themeSettings,
+      currentBreakpoint,
+      block.rowStyleKeys
     );
-
-    return getCSSStyles(withoutBoxGeometry, themeSettings, currentBreakpoint);
-  }, [block.styles, themeSettings, currentBreakpoint]);
-
-  const hasStyles = Object.keys(wrapperStyles).length > 0;
+  }, [block.styles, block.rowStyleKeys, themeSettings, currentBreakpoint]);
 
   return (
     <div
-      {...(hasStyles ? { style: wrapperStyles } : null)}
+      {...partAttrs('root')}
+      style={rootStyles}
       dangerouslySetInnerHTML={{ __html: content }}
     />
   );

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

@@ -90,7 +90,10 @@ describe('readThemeConfig', () => {
             widthUnit: 'px',
             panelSide: 'right',
             sheetHeight: 60,
-            lockScroll: true
+            lockScroll: true,
+            padding: undefined,
+            showSheetHandle: true,
+            stretchContent: false
           },
           autoTrigger: undefined,
           visibilityRules: undefined

package/src/hooks/__tests__/use-overlay.test.tsx

@@ -5,7 +5,11 @@ import { fireEvent, render } from '@testing-library/react';
 // does not have.
 import { renderToStaticMarkup } from 'react-dom/server.node';
 
-import { useOverlay } from '../use-overlay';
+import {
+  isScrollLocked,
+  SCROLL_LOCK_ATTRIBUTE,
+  useOverlay
+} from '../use-overlay';
 import type { OverlayPointerBook } from '../use-overlay';
 
 /**
@@ -158,6 +162,15 @@ describe('useOverlay', () => {
   afterEach(() => {
     document.body.style.overflow = '';
     document.body.removeAttribute('data-overlay-state');
+    // The lock is an attribute on the root plus a stylesheet injected once and
+    // left in place, and neither belongs to the case that put it there. The
+    // render cleanup already unmounts every panel, so today it is the sheet
+    // that matters: a case asserting the rule was injected exactly once would
+    // otherwise be reading a leftover from a case before it. The attribute goes
+    // with it so that a case which ends mid-lock — one that stops asserting
+    // before the cleanup runs, say — cannot hand the next one a frozen page.
+    document.documentElement.removeAttribute(SCROLL_LOCK_ATTRIBUTE);
+    document.getElementById('pz-overlay-scroll-lock')?.remove();
   });
 
   it('reproduces the loop the per-block traps have: two document-level traps pull focus at each other forever', () => {
@@ -378,34 +391,111 @@ describe('useOverlay', () => {
     getByTestId('a-first').focus();
     bookRef.current?.track({ pointerId: 7, clientX: 10, clientY: 10 });
     expect(bookRef.current?.size()).toBe(1);
-    expect(document.body.style.overflow).toBe('hidden');
+    expect(isScrollLocked()).toBe(true);
+    // The lock is a rule of its own, so the page's inline slot still reads back
+    // exactly what the page put there while the panel is up.
+    expect(document.body.style.overflow).toBe('auto');
 
     unmount();
 
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('auto');
     expect(onDeactivate).toHaveBeenCalledTimes(1);
     expect(bookRef.current?.size()).toBe(0);
   });
 
-  it('counts every scroll-lock holder and restores the page’s own overflow only for the last', () => {
+  it('counts every scroll-lock holder and lets the page go only for the last', () => {
     document.body.style.overflow = 'auto';
 
     const { rerender } = render(<Page a={{ open: true }} b={{ open: true }} />);
-    expect(document.body.style.overflow).toBe('hidden');
+    expect(isScrollLocked()).toBe(true);
+    // Asserted at every step and not only at the end: two holders on one lock
+    // still leave the inline slot reading back exactly what the page wrote.
+    expect(document.body.style.overflow).toBe('auto');
 
     rerender(<Page a={{ open: false }} b={{ open: true }} />);
     // One holder left: the page must stay frozen behind the panel still up.
-    expect(document.body.style.overflow).toBe('hidden');
+    expect(isScrollLocked()).toBe(true);
+    expect(document.body.style.overflow).toBe('auto');
 
     rerender(<Page a={{ open: false }} b={{ open: false }} />);
+    expect(isScrollLocked()).toBe(false);
+    // Letting go is dropping the attribute, not restoring a value: two holders
+    // came and went without either of them ever taking the page's own.
     expect(document.body.style.overflow).toBe('auto');
   });
 
+  it('keeps the lock when something else writes the page’s inline overflow', () => {
+    render(<Page a={{ open: true }} />);
+
+    expect(isScrollLocked()).toBe(true);
+
+    // The write that broke the old lock, in the shape it arrives in: the
+    // commerce `Modal` a login step renders inside an open drawer sets
+    // `body.style.overflow` to `auto` from an effect that runs on MOUNT,
+    // whether that modal is open or not. It is simply the last writer of a slot
+    // the whole page shares, and it handed the shopper a scrollbar with the
+    // drawer still covering the page.
+    document.body.style.overflow = 'auto';
+
+    expect(isScrollLocked()).toBe(true);
+    expect(document.documentElement.hasAttribute(SCROLL_LOCK_ATTRIBUTE)).toBe(
+      true
+    );
+    // The attribute surviving an inline write proves nothing on its own — an
+    // inline declaration could not remove an attribute if it tried. What has to
+    // hold is the CASCADE: with `auto` sitting in the page's own inline slot,
+    // the axis the shopper scrolls still resolves to `hidden`, on the root and
+    // on the body alike.
+    expect(getComputedStyle(document.body).overflowY).toBe('hidden');
+    expect(getComputedStyle(document.documentElement).overflowY).toBe('hidden');
+  });
+
+  it('locks with one author rule that outranks any inline declaration', () => {
+    render(<Page a={{ open: true }} b={{ open: true }} />);
+
+    // The rule does nothing without the attribute, so it is injected once and
+    // left alone: a second overlay opening must not add a second copy of it.
+    const sheets = document.querySelectorAll('style#pz-overlay-scroll-lock');
+    expect(sheets).toHaveLength(1);
+
+    const rule = sheets[0].textContent ?? '';
+    // Only an `!important` author declaration outranks an inline one, and
+    // outranking inline writers is the entire point of doing it this way.
+    expect(rule).toContain('!important');
+    // The root is locked outright as well as the body, because `body`'s
+    // overflow reaches the viewport only by propagation and a brand that sets
+    // an `overflow-y` of its own on `html` stops that propagation dead. Both
+    // selectors are pinned as the LIST they form: `html[…]` on its own is a
+    // substring of `html[…]>body`, so asserting it alone would go on passing
+    // for a rule that had quietly dropped the root.
+    expect(rule).toContain(
+      `html[${SCROLL_LOCK_ATTRIBUTE}],html[${SCROLL_LOCK_ATTRIBUTE}]>body{`
+    );
+  });
+
+  it('leaves the page’s own inline overflow untouched across a whole cycle', () => {
+    // A distinctive value the page could plausibly have set for itself: the
+    // lock has no business reading it, replacing it, or putting it back.
+    document.body.style.overflow = 'clip';
+
+    const { rerender } = render(<Page a={{ open: true }} />);
+
+    expect(isScrollLocked()).toBe(true);
+    expect(document.body.style.overflow).toBe('clip');
+
+    rerender(<Page a={{ open: false }} />);
+
+    expect(isScrollLocked()).toBe(false);
+    expect(document.body.style.overflow).toBe('clip');
+  });
+
   it('leaves the page alone for an overlay that does not ask for the lock', () => {
     document.body.style.overflow = 'auto';
 
     render(<Page a={{ open: true, lockScroll: false }} />);
 
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('auto');
   });
 
@@ -481,6 +571,7 @@ describe('useOverlay', () => {
 
     // The canvas is the author's workspace: nothing may reach into it.
     expect(document.activeElement).toBe(outside);
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('auto');
     expect(getByTestId('a-panel')).not.toHaveAttribute('aria-modal');
 
@@ -521,6 +612,7 @@ describe('useOverlay', () => {
 
     expect(markup).toContain('data-testid="a-panel"');
     expect(markup).not.toContain('aria-modal');
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('auto');
     expect(addEventListener).not.toHaveBeenCalled();
 

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

@@ -10,6 +10,14 @@ import {
   toggleModal,
   useModalOpen
 } from '../overlays/overlay-bus';
+import {
+  AuthFlowIdContext,
+  DEFAULT_AUTH_FLOW_ID,
+  goBackAuthStep,
+  resolveAuthStepTarget,
+  setAuthStep
+} from '../auth/auth-flow-bus';
+import { useOtpForm } from '../auth/otp-form-context';
 
 /**
  * What a block does when it is clicked.
@@ -32,7 +40,11 @@ export type BlockActionType =
   | 'close-modal'
   | 'toggle-modal'
   | 'close-top-modal'
-  | 'scroll-to';
+  | 'scroll-to'
+  | 'auth-step'
+  | 'auth-back'
+  | 'otp-resend'
+  | 'otp-change-number';
 
 export const BLOCK_ACTION_TYPES: BlockActionType[] = [
   'none',
@@ -41,7 +53,11 @@ export const BLOCK_ACTION_TYPES: BlockActionType[] = [
   'close-modal',
   'toggle-modal',
   'close-top-modal',
-  'scroll-to'
+  'scroll-to',
+  'auth-step',
+  'auth-back',
+  'otp-resend',
+  'otp-change-number'
 ];
 
 const MODAL_ACTIONS: BlockActionType[] = [
@@ -112,6 +128,7 @@ export interface UseBlockActionResult {
     'aria-haspopup'?: 'dialog';
     'aria-expanded'?: boolean;
     'aria-controls'?: string;
+    'aria-disabled'?: boolean;
   };
 }
 
@@ -149,6 +166,19 @@ export const useBlockAction = (
     MODAL_ACTIONS.includes(type) ? target : ''
   );
 
+  // The flow a trigger inside an `auth-flow` block belongs to, so its target
+  // can be a bare step key. Empty everywhere else; the auth actions then fall
+  // back to the default flow id, which is what a lone flow on the page uses.
+  const contextFlowId = React.useContext(AuthFlowIdContext);
+
+  /**
+   * The OTP form this block stands inside, for the two controls a composed
+   * verification needs and no bus can carry: asking for a fresh code and going
+   * back to the number. Both belong to ONE form's state, so unlike the modal
+   * and auth-step actions they are reached through a context rather than by id.
+   */
+  const otpForm = useOtpForm();
+
   const handleClick = useCallback(
     (event: React.MouseEvent<HTMLElement>) => {
       if (isDesigner) return;
@@ -175,14 +205,47 @@ export const useBlockAction = (
           event.preventDefault();
           scrollToAnchor(target);
           break;
+        case 'auth-step': {
+          // A trigger that also navigates would race the step it opens.
+          event.preventDefault();
+          const resolved = resolveAuthStepTarget(target, contextFlowId);
+          if (resolved) setAuthStep(resolved.flowId, resolved.stepKey);
+          break;
+        }
+        case 'otp-resend':
+          event.preventDefault();
+          // No-ops while the countdown runs — the form owns that rule, so a
+          // resend placed anywhere obeys the same one.
+          otpForm?.resend();
+          break;
+        case 'otp-change-number':
+          event.preventDefault();
+          otpForm?.changeNumber();
+          break;
+        case 'auth-back':
+          event.preventDefault();
+          // The optional target names a flow; without one the nearest (or
+          // default) flow is walked back.
+          goBackAuthStep(target || contextFlowId || DEFAULT_AUTH_FLOW_ID);
+          break;
         default:
           break;
       }
     },
-    [isDesigner, type, target]
+    [isDesigner, type, target, contextFlowId, otpForm]
   );
 
-  const isActive = isInteractiveAction(type) && (type === 'close-top-modal' || Boolean(target));
+  /** Actions that act on what is in scope, so they need no target typed. */
+  const TARGETLESS_ACTIONS: BlockActionType[] = [
+    'close-top-modal',
+    'auth-back',
+    'otp-resend',
+    'otp-change-number'
+  ];
+
+  const isActive =
+    isInteractiveAction(type) &&
+    (TARGETLESS_ACTIONS.includes(type) || Boolean(target));
 
   if (!isActive) {
     return { isActive: false, ariaProps: {} };
@@ -190,6 +253,26 @@ export const useBlockAction = (
 
   const opensDialog = type === 'open-modal' || type === 'toggle-modal';
 
+  // A resend during the cooldown is a real control that is momentarily not
+  // available. `aria-disabled` announces that and gives the brand a selector
+  // to dim it, without taking the element out of the tab order the way
+  // `disabled` on a styled div cannot anyway.
+  // Same for "use a different number" while a REGISTRATION is being verified:
+  // the parked payload is the only copy of the sign-up, so collecting a new
+  // number would throw it away. The fixed layout hides the control outright;
+  // a composed one is a Button the author placed, so it says it is unavailable
+  // rather than disappearing out from under the design.
+  if (
+    (type === 'otp-resend' && otpForm && !otpForm.canResend) ||
+    (type === 'otp-change-number' && otpForm && !otpForm.canChangeNumber)
+  ) {
+    return {
+      isActive: true,
+      onClick: handleClick,
+      ariaProps: { 'aria-disabled': true }
+    };
+  }
+
   return {
     isActive: true,
     onClick: handleClick,

package/src/hooks/use-overlay.ts

@@ -141,20 +141,72 @@ const popOverlay = (id: string) => {
 const noOverlayOnServer = () => false;
 
 /**
- * The page's own overflow, held by whoever locked first and written back only
- * when the last holder leaves. Each block used to keep its own counter, so the
- * second block to open captured `hidden` as "the page's own value" and the
- * page stayed frozen after every panel had closed.
+ * How many overlays are holding the page still. The lock itself is a rule (see
+ * below), so the count is the only state there is: the first holder switches it
+ * on, the last one out switches it off, and nothing has to be remembered in
+ * between. Each block used to keep its own counter AND its own copy of the
+ * page's overflow, so the second block to open captured `hidden` as "the
+ * page's own value" and the page stayed frozen after every panel had closed.
  */
 let scrollLockHolders = 0;
-let scrollLockPreviousOverflow = '';
+
+/**
+ * The lock is an author rule flipped by an attribute, NOT an inline style.
+ *
+ * `body.style.overflow` is a single slot the whole page shares, and brand code
+ * writes it directly: the commerce `Modal` sets it to `auto` from an effect
+ * that runs on MOUNT — open or closed — and again on unmount. Anything of that
+ * shape appearing while an overlay is up (a consent dialog rendered by a login
+ * step, a quick-view mounted behind a drawer) was the last writer, so it handed
+ * the page its scrollbar back with the overlay still covering it. An
+ * `!important` author declaration outranks every inline one, so the lock now
+ * survives writers it does not control, and releasing it is dropping an
+ * attribute rather than restoring a value someone else may have replaced
+ * meanwhile.
+ *
+ * Both `html` and `body` are named. `body`'s overflow reaches the viewport only
+ * by propagation, which stops the moment a brand sets an overflow of its own on
+ * `html` (`overflow-y: scroll`, to keep the scrollbar's width from shifting the
+ * layout, is the common one) — so the root is locked outright and the body is
+ * locked with it.
+ *
+ * Only the block axis: `overflow-x` belongs to the page (the app template
+ * clips it, and `StickySlotOverflow` keeps that clip a `clip` rather than a
+ * `hidden` precisely so a pinned slot stays pinned), and claiming it here would
+ * unpin every sticky slot for as long as a modal is open.
+ */
+export const SCROLL_LOCK_ATTRIBUTE = 'data-pz-scroll-locked';
+
+const SCROLL_LOCK_STYLE_ID = 'pz-overlay-scroll-lock';
+
+const SCROLL_LOCK_RULE =
+  `html[${SCROLL_LOCK_ATTRIBUTE}],` +
+  `html[${SCROLL_LOCK_ATTRIBUTE}]>body{overflow-y:hidden!important}`;
+
+/**
+ * Injected once and left in place: the rule does nothing without the
+ * attribute, and a page that has opened one overlay will open another.
+ */
+const ensureScrollLockRule = () => {
+  if (document.getElementById(SCROLL_LOCK_STYLE_ID)) return;
+
+  const style = document.createElement('style');
+  style.id = SCROLL_LOCK_STYLE_ID;
+  style.textContent = SCROLL_LOCK_RULE;
+  (document.head || document.documentElement).appendChild(style);
+};
+
+/** Whether an overlay is currently holding the page still. */
+export const isScrollLocked = (): boolean =>
+  typeof document !== 'undefined' &&
+  document.documentElement.hasAttribute(SCROLL_LOCK_ATTRIBUTE);
 
 const acquireScrollLock = () => {
   if (typeof document === 'undefined') return;
 
   if (scrollLockHolders === 0) {
-    scrollLockPreviousOverflow = document.body.style.overflow;
-    document.body.style.overflow = 'hidden';
+    ensureScrollLockRule();
+    document.documentElement.setAttribute(SCROLL_LOCK_ATTRIBUTE, '');
   }
 
   scrollLockHolders += 1;
@@ -166,8 +218,7 @@ const releaseScrollLock = () => {
   scrollLockHolders -= 1;
 
   if (scrollLockHolders === 0) {
-    document.body.style.overflow = scrollLockPreviousOverflow;
-    scrollLockPreviousOverflow = '';
+    document.documentElement.removeAttribute(SCROLL_LOCK_ATTRIBUTE);
   }
 };
 

package/src/overlays/__tests__/modal-chrome-padding.test.tsx

@@ -0,0 +1,119 @@
+import { act, render } from '@testing-library/react';
+import React from 'react';
+
+jest.mock('next/navigation', () => ({
+  usePathname: () => '/',
+  useSearchParams: () => new URLSearchParams()
+}));
+
+jest.mock('next-auth/react', () => ({
+  useSession: () => ({ status: 'unauthenticated' })
+}));
+
+jest.mock('@akinon/next/hooks/use-localization', () => ({
+  useLocalization: () => ({ locale: 'en', currency: 'USD' })
+}));
+
+import ThemeModalMount from '../theme-modal-mount';
+import {
+  __resetOverlayBusForTests,
+  openModal,
+  registerModalHost
+} from '../overlay-bus';
+import { __resetModalPreviewForTests } from '../use-modal-preview';
+import { clearAutoOpenRecord } from '../modal-frequency';
+import { readThemeModals, ThemeModal } from '../modal-registry';
+
+/**
+ * The whole path of two chrome settings, from saved config to the DOM.
+ *
+ * Both were lost in the middle of it, twice over, and neither loss could show
+ * up in a unit test of either end: `readChrome` builds the chrome object field
+ * by field and simply never read them, so the panel kept its historical 24px
+ * however the designer set the control; and the mount then handed the surface
+ * a `stretchContent` prop when the surface declares `panelStretch`, which a
+ * package with no tsconfig never flagged. A designer typing 0 saw 24, and the
+ * bottom-bar CTA had nothing to stretch against.
+ *
+ * So these assertions deliberately start at the raw config and end at the
+ * rendered element — the two ends a designer actually experiences.
+ */
+
+const mkModal = (chrome: Record<string, unknown> = {}): ThemeModal =>
+  readThemeModals([
+    {
+      id: 'drawer',
+      name: 'Drawer',
+      chrome: { presentation: 'panel', ...chrome }
+    }
+  ])[0];
+
+const openWith = (chrome: Record<string, unknown> = {}) => {
+  render(
+    <ThemeModalMount modal={mkModal(chrome)}>
+      <p>composed content</p>
+    </ThemeModalMount>
+  );
+
+  act(() => {
+    openModal('drawer');
+  });
+
+  return document.querySelector('[role="dialog"]') as HTMLElement;
+};
+
+beforeEach(() => {
+  __resetOverlayBusForTests();
+  __resetModalPreviewForTests();
+  registerModalHost();
+  clearAutoOpenRecord('drawer');
+  document.body.style.overflow = '';
+});
+
+describe('the padding a designer sets on a modal', () => {
+  it('survives the config parser', () => {
+    expect(mkModal({ padding: 40 }).chrome.padding).toBe(40);
+  });
+
+  it('reaches the panel', () => {
+    expect(openWith({ padding: 40 }).style.padding).toBe('40px');
+  });
+
+  it('can be zero, which is a real answer and not an absence', () => {
+    expect(mkModal({ padding: 0 }).chrome.padding).toBe(0);
+    expect(openWith({ padding: 0 }).style.padding).toBe('0px');
+  });
+
+  it('is absent when never authored, so the panel keeps its historical 24', () => {
+    // Every modal saved before the control existed must render as it did.
+    expect(mkModal().chrome.padding).toBeUndefined();
+    expect(openWith().style.padding).toBe('24px');
+  });
+
+  it('ignores junk rather than handing the browser a broken declaration', () => {
+    expect(mkModal({ padding: 'wide' }).chrome.padding).toBeUndefined();
+  });
+
+  it('clamps a typo instead of rendering a 2400px panel', () => {
+    expect(mkModal({ padding: 2400 }).chrome.padding).toBe(200);
+  });
+});
+
+describe('stretch content to full height', () => {
+  it('survives the config parser', () => {
+    expect(mkModal({ stretchContent: true }).chrome.stretchContent).toBe(true);
+  });
+
+  it('marks the panel, which is what the stretch rules select on', () => {
+    // The rules in PANEL_STRETCH_CSS all hang off this attribute; without it
+    // nothing in the chain applies and the CTA cannot be pinned.
+    expect(openWith({ stretchContent: true })).toHaveAttribute(
+      'data-modal-stretch'
+    );
+  });
+
+  it('is off unless asked for', () => {
+    expect(mkModal().chrome.stretchContent).toBe(false);
+    expect(openWith()).not.toHaveAttribute('data-modal-stretch');
+  });
+});

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

@@ -58,7 +58,12 @@ describe('readThemeModals', () => {
           widthUnit: 'px',
           panelSide: 'right',
           sheetHeight: 60,
-          lockScroll: true
+          lockScroll: true,
+          // Absent, not defaulted: the panel's historical 24px lives in the
+          // surface, so an unauthored padding must stay unauthored here.
+          padding: undefined,
+          showSheetHandle: true,
+          stretchContent: false
         },
         autoTrigger: undefined,
         visibilityRules: undefined

package/src/overlays/__tests__/panel-stretch.test.tsx

@@ -0,0 +1,60 @@
+import { render } from '@testing-library/react';
+import React from 'react';
+
+import { PanelStretchStyles } from '../overlay-surface';
+
+/**
+ * "Stretch Content to Full Height" is what lets a drawer pin its CTA to the
+ * bottom edge, and it works by handing the panel's height DOWN a chain of
+ * wrappers. Height is not inherited — it is passed link by link — so one
+ * wrapper left at `auto` strands everything below it, and the designer sees a
+ * button that will not move however many times they type 100%.
+ *
+ * The chain is our own markup, so it is testable as a list: every structural
+ * element of an auth journey has to be in it. The composed forms included — an
+ * OTP form sits between the step and its phase.
+ */
+const cssOf = (): string => {
+  const { container } = render(<PanelStretchStyles />);
+  return container.querySelector('style')?.innerHTML ?? '';
+};
+
+const JOURNEY_PARTS = [
+  'data-auth-flow',
+  'data-auth-step',
+  'data-otp-phase',
+  'data-auth-form',
+  'data-register-form',
+  'data-otp-form',
+  'data-forgot-password'
+];
+
+describe('the panel stretch chain', () => {
+  it('starts at the placeholder and its section', () => {
+    const css = cssOf();
+
+    expect(css).toContain('[data-modal-stretch]>[data-placeholder]{');
+    expect(css).toContain('[data-modal-stretch]>[data-placeholder]>section{');
+  });
+
+  it.each(JOURNEY_PARTS)('stretches the wrapper around [%s]', (attribute) => {
+    expect(cssOf()).toContain(
+      `[data-modal-stretch] [data-block-id]:has(>[${attribute}])`
+    );
+  });
+
+  it.each(JOURNEY_PARTS)('stretches [%s] itself', (attribute) => {
+    expect(cssOf()).toContain(`[data-modal-stretch] [${attribute}]`);
+  });
+
+  it('leaves the free space to the composition, not to itself', () => {
+    const css = cssOf();
+
+    // `min-height:0` on every link, or a long code phase would refuse to
+    // shrink and the bottom bar would be pushed off the panel.
+    expect(css.match(/min-height:0/g)?.length).toBe(4);
+    // The designer's own blocks are never named here: what happens inside the
+    // section stays theirs.
+    expect(css).not.toContain('data-part');
+  });
+});