@sovereignfs/ui 0.54.0 → 0.83.1

package/src/components/Dialog/Dialog.tsx

@@ -3,19 +3,15 @@
 import { createContext, type ReactNode, useContext, useEffect, useRef, useState } from 'react';
 import { useMountTransition, usePrefersReducedMotion } from '../../motion';
 import {
+  OVERLAY_MOTION_DURATION_MS,
   useOverlayFocusCapture,
   useOverlayKeyboardTrap,
   useOverlayScrollLock,
 } from '../../overlay-shell';
+import { Icon } from '../Icon/Icon';
 import { OverlayHeader } from '../OverlayHeader/OverlayHeader';
 import styles from './Dialog.module.css';
 
-// Matches --sv-motion-duration-base (Dialog.module.css) — kept as a plain JS
-// constant rather than read from the CSS custom property so the unmount timer
-// and the CSS transition duration can't silently drift apart at build time;
-// change both together if this value ever changes.
-const MOTION_DURATION_MS = 250;
-
 // undefined (the default, outside any Provider) means "no Dialog ancestor" —
 // distinct from a real setter function, so useOverlaySecondRow can silently
 // no-op when called outside a Dialog instead of throwing.
@@ -26,11 +22,13 @@ const OverlaySecondRowContext = createContext<((node: ReactNode | null) => void)
 /**
  * Lets content deep inside a `Dialog` (e.g. a plugin's own route layout,
  * rendered several levels below wherever the `Dialog` itself is
- * instantiated) supply the second-row content of the Dialog's mobile
- * `OverlayHeader` — typically a tab strip. Solves the "double header"
- * problem: without this, a plugin's own tab strip has no way to reach the
- * Dialog's header and ends up rendered a second time, as its own sticky bar,
- * inside the scrolling content area.
+ * instantiated) supply the second-row content of the Dialog's `OverlayHeader`
+ * — typically a tab strip. Solves the "double header" problem: without this,
+ * a plugin's own tab strip has no way to reach the Dialog's header and ends
+ * up rendered a second time, as its own sticky bar, inside the scrolling
+ * content area. Reaches the header regardless of whether it's showing via
+ * the `header` prop (both breakpoints) or the default `title`-driven mobile
+ * bar (mobile only) — see `DialogProps.header`'s own doc comment.
  *
  * A no-op when there is no enclosing `Dialog` (e.g. the same plugin layout
  * also rendered on a plain, non-overlay route) — safe to call unconditionally.
@@ -56,7 +54,27 @@ export function useOverlaySecondRow(node: ReactNode | null): boolean {
   return setSecondRow !== undefined;
 }
 
-export type DialogSize = 'sm' | 'md' | 'lg' | 'full';
+// BREAKING (packages/ui minor bump + docs/upgrade.md migration note): `xl`
+// and `full` were removed here — `full` was a dead alias of `lg` (identical
+// CSS), and `xl` was a fixed-width variant with no distinct behavior `auto`
+// doesn't now cover better. `auto` sizes to content on BOTH width and
+// height, capped rather than fixed on either axis — for content whose
+// natural size varies a lot (a card detail modal with an optional
+// checklist/comments section) rather than reliably filling a fixed width.
+// `lg` is a true fixed 100%/100% box — the panel holds still regardless of
+// content, at the cost of always filling the viewport.
+//
+// `fixed` (added for epic task 14.5, Account's vertical nav): a true fixed
+// box like `lg` — width AND height set, content never resizes it — but
+// capped rather than filling the viewport. Named distinctly from the
+// component's own always-applied `.panel` CSS class (Dialog.module.css),
+// not from `lg`'s own fixed-ness. For a plugin that needs a stable
+// footprint (e.g. one whose route tree includes a client-side redirect
+// through a near-empty intermediate page — `auto`/`sm`/`md`'s
+// content-driven sizing would visibly shrink to fit that empty page, then
+// grow once the real content lands) without reading as heavy as `lg`'s
+// full-screen box for what is a compact settings surface.
+export type DialogSize = 'sm' | 'md' | 'lg' | 'auto' | 'fixed';
 
 export interface DialogProps {
   /** Whether the dialog is shown. When false, nothing renders. */
@@ -65,11 +83,42 @@ export interface DialogProps {
   onClose: () => void;
   /** Panel size on desktop. Mobile always renders as a full-screen sheet. */
   size?: DialogSize;
-  /** Accessible name for the dialog (sets `aria-label` on the panel). */
+  /** Accessible name for the dialog (sets `aria-label` on the panel). Falls
+   *  back to `title` when omitted — this still applies even when `header` is
+   *  used instead of `title` for the visible header (see `header`'s own doc
+   *  comment), so pass `aria-label` explicitly in that case if `title` is
+   *  also omitted. */
   'aria-label'?: string;
-  /** On mobile: shown in the top bar alongside the close button so the title
-   *  and dismiss affordance occupy the same row instead of stacking. */
+  /** Shown in the top bar alongside the close button, on mobile only —
+   *  desktop has no header row by default (see `header` for that). Ignored
+   *  as visible content when `header` is provided; still used as the
+   *  `aria-label` fallback either way. */
   title?: string;
+  /** Renders a persistent header row (via the same `OverlayHeader` component
+   *  `title` alone only shows on mobile) on **both** desktop and mobile —
+   *  the "Header + Body" / "Header + Body + Footer" shapes. Supersedes
+   *  `title` for visible content when provided; `title` remains the
+   *  `aria-label` fallback if `aria-label` is also omitted. Omitting both
+   *  `header` and `footer` is "Body only" — today's default, unchanged. */
+  header?: ReactNode;
+  /** Renders a persistent footer row below the scrollable body — pinned on
+   *  both desktop and mobile the same way `header`/the mobile title bar are
+   *  (a non-scrolling flex sibling, not `position: sticky`): only the region
+   *  between header and footer scrolls. Typically action buttons (Save/
+   *  Cancel). Omit for no footer — today's default, where any actions live
+   *  inside `children` and scroll with the rest of the body. Layout-agnostic
+   *  (no built-in button alignment) — arrange the footer's own content as
+   *  needed, same as `children`. */
+  footer?: ReactNode;
+  /** Forwarded to the active `OverlayHeader` instance's own `rowClassName`
+   *  (whichever is showing — `header` or the mobile `title` bar) — restyle
+   *  the title row (e.g. tighter padding to match a consumer's own compact
+   *  header elsewhere) without changing its title/close layout. */
+  rowClassName?: string;
+  /** Forwarded to the active `OverlayHeader` instance's own `titleClassName`
+   *  — restyle the title text (e.g. a smaller font size to match a
+   *  consumer's own compact header elsewhere). */
+  titleClassName?: string;
   children: ReactNode;
 }
 
@@ -88,6 +137,12 @@ export interface DialogProps {
  * `onClose` API is unchanged — closing still stays mounted internally for the
  * exit transition before actually unmounting; `prefers-reduced-motion: reduce`
  * collapses both to near-instant.
+ *
+ * Three composition shapes, chosen by which of `header`/`footer` are passed:
+ * Body only (both omitted — today's default), Header + Body (`header` only),
+ * Header + Body + Footer (`header` and `footer`). Whichever of header/footer
+ * are present render as non-scrolling flex siblings around `.content`, which
+ * stays the only scrollable region in every shape.
  */
 export function Dialog({
   open,
@@ -95,11 +150,18 @@ export function Dialog({
   size = 'lg',
   'aria-label': ariaLabel,
   title,
+  header,
+  footer,
+  rowClassName,
+  titleClassName,
   children,
 }: DialogProps) {
   const panelRef = useRef<HTMLDivElement>(null);
   const reducedMotion = usePrefersReducedMotion();
-  const { mounted, phase } = useMountTransition(open, reducedMotion ? 0 : MOTION_DURATION_MS);
+  const { mounted, phase } = useMountTransition(
+    open,
+    reducedMotion ? 0 : OVERLAY_MOTION_DURATION_MS,
+  );
   const [secondRow, setSecondRow] = useState<ReactNode | null>(null);
 
   useOverlayScrollLock(mounted);
@@ -112,15 +174,17 @@ export function Dialog({
   return (
     // role="presentation" removes the scrim from the AT (it is purely visual).
     // e.target check lets clicks inside the panel bubble without triggering dismiss.
+    // No onKeyDown here — useOverlayKeyboardTrap above already owns Escape via a
+    // document-level listener; a second handler here used to double-fire onClose
+    // per keypress (the keydown bubbles through this element on its way to
+    // document), which is exactly the kind of bug that turns a single Escape
+    // press into two router.back() calls for @modal-driven consumers.
     <div
       className={[styles.scrim, isOpenPhase ? styles.scrimOpen : ''].filter(Boolean).join(' ')}
       role="presentation"
       onClick={(e) => {
         if (e.target === e.currentTarget) onClose();
       }}
-      onKeyDown={(e) => {
-        if (e.key === 'Escape') onClose();
-      }}
     >
       <div
         ref={panelRef}
@@ -132,28 +196,58 @@ export function Dialog({
           .filter(Boolean)
           .join(' ')}
       >
-        {/* Mobile: shared OverlayHeader (title + close in one row, hidden on
-            desktop via CSS — see .mobileHeader). secondRow is populated by a
-            descendant's useOverlaySecondRow call, e.g. a plugin's own tab
-            strip — see that hook's doc comment for why. */}
-        <OverlayHeader
-          title={title}
-          onClose={onClose}
-          secondRow={secondRow}
-          className={styles.mobileHeader}
-        />
-        {/* Desktop: absolute close button (hidden on mobile via CSS). */}
-        <button type="button" className={styles.close} aria-label="Close" onClick={onClose}>
-          ×
-        </button>
+        {header ? (
+          /* header supersedes the mobile-only title bar below — OverlayHeader
+             itself has no internal breakpoint gating (see its own module
+             CSS), so rendering it with no Dialog-level display-toggling
+             className, as here, is what makes it show on both desktop and
+             mobile. It carries its own close button, so the separate
+             desktop-only .close button below is skipped entirely in this
+             branch — never render both at once. */
+          <OverlayHeader
+            title={header}
+            onClose={onClose}
+            secondRow={secondRow}
+            rowClassName={rowClassName}
+            titleClassName={titleClassName}
+          />
+        ) : (
+          <>
+            {/* Mobile: shared OverlayHeader (title + close in one row, hidden
+                on desktop via CSS — see .mobileHeader). secondRow is
+                populated by a descendant's useOverlaySecondRow call, e.g. a
+                plugin's own tab strip — see that hook's doc comment for why. */}
+            <OverlayHeader
+              title={title}
+              onClose={onClose}
+              secondRow={secondRow}
+              className={styles.mobileHeader}
+              rowClassName={rowClassName}
+              titleClassName={titleClassName}
+            />
+            {/* Desktop: absolute close button (hidden on mobile via CSS).
+                Plain `x`, matching the mobile OverlayHeader's own close icon
+                above it (OverlayHeader.tsx) — a single consistent close
+                affordance across breakpoints instead of desktop's own
+                separate `circle-x` glyph (the previous choice here).
+                Platform-wide: every `Dialog` consumer without a `header`
+                gets this, not just the one it was requested against —
+                `Dialog` has no per-instance override for its own close
+                button. */}
+            <button type="button" className={styles.close} aria-label="Close" onClick={onClose}>
+              <Icon name="x" size="md" aria-hidden={true} />
+            </button>
+          </>
+        )}
         {/* The panel is a fixed-size box; only this region scrolls, so the
-            panel never resizes with its content and the close button stays
-            pinned. */}
+            panel never resizes with its content and the header/close button
+            and footer (if present) stay pinned. */}
         <div className={styles.content}>
           <OverlaySecondRowContext.Provider value={setSecondRow}>
             {children}
           </OverlaySecondRowContext.Provider>
         </div>
+        {footer && <div className={styles.footer}>{footer}</div>}
       </div>
     </div>
   );

package/src/components/Dialog/__tests__/Dialog.test.tsx

@@ -1,6 +1,8 @@
 // @vitest-environment jsdom
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { useState } from 'react';
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { ConfirmDialog } from '../../ConfirmDialog/ConfirmDialog';
 import { Dialog, useOverlaySecondRow } from '../Dialog';
 
 // Dialog's exit animation reads prefers-reduced-motion via matchMedia, which
@@ -48,16 +50,24 @@ describe('Dialog', () => {
     expect(dialog.getAttribute('aria-modal')).toBe('true');
   });
 
-  it('calls onClose on Escape', () => {
+  it('calls onClose exactly once on Escape with focus inside the panel', () => {
     const onClose = vi.fn();
     render(
-      <Dialog open onClose={onClose}>
-        Body
+      <Dialog open onClose={onClose} aria-label="Panel">
+        <button>Focus me</button>
       </Dialog>,
     );
-    // Keyboard handler is registered on document (not the dialog element) so
-    // screen readers and keyboard users can dismiss from anywhere in the page.
-    fireEvent.keyDown(document, { key: 'Escape' });
+    // Dispatched from the actually-focused element (matching real usage,
+    // where useOverlayFocusCapture moves focus into the panel on open) so the
+    // keydown bubbles through the scrim on its way to document — the exact
+    // path that used to trigger both the scrim's own (now-removed) Escape
+    // handler and useOverlayKeyboardTrap's document-level listener, double-
+    // firing onClose. Dispatching straight on `document` (the previous form
+    // of this test) skips that bubble path and would pass even if the bug
+    // were reintroduced.
+    const button = screen.getByRole('button', { name: 'Focus me' });
+    button.focus();
+    fireEvent.keyDown(button, { key: 'Escape' });
     expect(onClose).toHaveBeenCalledOnce();
   });
 
@@ -78,11 +88,11 @@ describe('Dialog', () => {
 
   it('applies the size class', () => {
     render(
-      <Dialog open onClose={() => {}} size="full" aria-label="Big">
+      <Dialog open onClose={() => {}} size="lg" aria-label="Big">
         Body
       </Dialog>,
     );
-    expect(screen.getByRole('dialog').className).toContain('full');
+    expect(screen.getByRole('dialog').className).toContain('lg');
   });
 
   it('supports the sm size', () => {
@@ -94,6 +104,24 @@ describe('Dialog', () => {
     expect(screen.getByRole('dialog').className).toContain('sm');
   });
 
+  it('supports the auto size', () => {
+    render(
+      <Dialog open onClose={() => {}} size="auto" aria-label="Auto-sized">
+        Body
+      </Dialog>,
+    );
+    expect(screen.getByRole('dialog').className).toContain('auto');
+  });
+
+  it('supports the fixed size (epic task 14.5)', () => {
+    render(
+      <Dialog open onClose={() => {}} size="fixed" aria-label="Fixed-size">
+        Body
+      </Dialog>,
+    );
+    expect(screen.getByRole('dialog').className).toContain('fixed');
+  });
+
   it('renders a descendant-supplied secondRow via useOverlaySecondRow', () => {
     function TabStrip() {
       useOverlaySecondRow(<nav>Tab strip</nav>);
@@ -134,4 +162,157 @@ describe('Dialog', () => {
     expect(screen.getByText('Standalone content')).toBeTruthy();
     expect(screen.queryByText('Tab strip')).toBeNull();
   });
+
+  describe('Body only (default — no header/footer props)', () => {
+    it('renders exactly one close button and no footer', () => {
+      render(
+        <Dialog open onClose={() => {}} title="Settings" aria-label="Settings">
+          Body
+        </Dialog>,
+      );
+      // Both the mobile-only OverlayHeader's close button and the
+      // desktop-only floating one are always in the DOM (CSS toggles which
+      // is visible per breakpoint, not React) — unchanged from before this
+      // task, since this is the `header`-omitted branch.
+      expect(screen.getAllByRole('button', { name: 'Close' })).toHaveLength(2);
+      expect(screen.getByText('Settings')).toBeTruthy();
+    });
+  });
+
+  describe('Header + Body (header prop)', () => {
+    it('renders header content via a single OverlayHeader, on both breakpoints, instead of the mobile-only title bar', () => {
+      render(
+        <Dialog open onClose={() => {}} header={<span>Card detail</span>} aria-label="Card detail">
+          Body
+        </Dialog>,
+      );
+      expect(screen.getByText('Card detail')).toBeTruthy();
+      // Only one close button now — the header branch skips the separate
+      // desktop .close button entirely (see Dialog.tsx's own comment).
+      expect(screen.getAllByRole('button', { name: 'Close' })).toHaveLength(1);
+    });
+
+    it('supersedes title for visible content but keeps title as the aria-label fallback', () => {
+      render(
+        <Dialog open onClose={() => {}} title="Fallback name" header={<span>Visible header</span>}>
+          Body
+        </Dialog>,
+      );
+      expect(screen.getByText('Visible header')).toBeTruthy();
+      expect(screen.queryByText('Fallback name')).toBeNull();
+      expect(screen.getByRole('dialog', { name: 'Fallback name' })).toBeTruthy();
+    });
+  });
+
+  describe('Header + Body + Footer (header and footer props)', () => {
+    it('renders footer content as a non-scrolling sibling of the body', () => {
+      render(
+        <Dialog
+          open
+          onClose={() => {}}
+          header={<span>Card detail</span>}
+          footer={<button type="button">Save</button>}
+          aria-label="Card detail"
+        >
+          <p>Body content</p>
+        </Dialog>,
+      );
+      const footerButton = screen.getByRole('button', { name: 'Save' });
+      const bodyText = screen.getByText('Body content');
+      expect(footerButton).toBeTruthy();
+      // Footer is a sibling of .content (the scroll region), not nested
+      // inside it — it must never scroll away with the body.
+      expect(bodyText.closest('[class*="content"]')?.contains(footerButton)).toBe(false);
+    });
+
+    it('omits the footer row entirely when footer is not provided', () => {
+      render(
+        <Dialog open onClose={() => {}} header={<span>Card detail</span>} aria-label="Card detail">
+          Body
+        </Dialog>,
+      );
+      expect(screen.queryByRole('button', { name: 'Save' })).toBeNull();
+    });
+  });
+});
+
+describe('Dialog Escape precedence with a nested ConfirmDialog', () => {
+  beforeEach(() => {
+    installMatchMedia();
+    // jsdom does not implement HTMLDialogElement — see ConfirmDialog.test.tsx
+    // for the full rationale on the guard + deferred dispatch (both matter
+    // here too: without the guard, this file's own reuse of the mock across
+    // renders would double-dispatch; without deferring, ConfirmDialog's
+    // unregister-on-close wouldn't have run yet by the time this test reads
+    // the outer Dialog's response to a second Escape).
+    HTMLDialogElement.prototype.showModal = function (this: HTMLDialogElement) {
+      this.setAttribute('open', '');
+    };
+    HTMLDialogElement.prototype.close = function (this: HTMLDialogElement) {
+      if (!this.hasAttribute('open')) return;
+      this.removeAttribute('open');
+      queueMicrotask(() => this.dispatchEvent(new Event('close')));
+    };
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  async function flush() {
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+  }
+
+  it('defers Escape to a nested open ConfirmDialog instead of closing the outer Dialog', async () => {
+    const outerOnClose = vi.fn();
+
+    function NestedHarness() {
+      // Starts closed and opens via a later click — matching the real
+      // sequence (CardDetailOverlay: the outer Dialog is already mounted and
+      // registered before the user ever triggers the nested confirm).
+      // Mounting both already-open in the same initial render would instead
+      // have React fire the child's (ConfirmDialog's) registration effect
+      // before the parent's (Dialog's) in that one shared commit — the one
+      // case this stack-order approach doesn't handle, and not the shape of
+      // the bug this task fixes.
+      const [confirmOpen, setConfirmOpen] = useState(false);
+      return (
+        <Dialog open onClose={outerOnClose} aria-label="Card detail">
+          <button onClick={() => setConfirmOpen(true)}>Delete card…</button>
+          <ConfirmDialog
+            open={confirmOpen}
+            onClose={() => setConfirmOpen(false)}
+            onConfirm={() => {}}
+            title="Delete card?"
+            message="This can't be undone."
+          />
+        </Dialog>
+      );
+    }
+
+    render(<NestedHarness />);
+    fireEvent.click(screen.getByRole('button', { name: 'Delete card…' }));
+    await flush();
+    expect(screen.getByRole('button', { name: 'Cancel' })).toBeTruthy();
+
+    // The nested ConfirmDialog is topmost — the outer Dialog's document-level
+    // Escape listener must not act while it's open.
+    fireEvent.keyDown(document, { key: 'Escape' });
+    await flush();
+    expect(outerOnClose).not.toHaveBeenCalled();
+    expect(screen.getByRole('button', { name: 'Cancel' })).toBeTruthy();
+
+    // Dismiss the nested confirm (unregisters it from the open-overlay
+    // stack) — the outer Dialog is now topmost again.
+    fireEvent.click(screen.getByRole('button', { name: 'Cancel' }));
+    await flush();
+    expect(screen.queryByRole('button', { name: 'Cancel' })).toBeNull();
+
+    // A second Escape now reaches the outer Dialog.
+    fireEvent.keyDown(document, { key: 'Escape' });
+    await flush();
+    expect(outerOnClose).toHaveBeenCalledOnce();
+  });
 });

package/src/components/DragHandleRow/DragHandleRow.tsx

@@ -1,4 +1,5 @@
 import type { HTMLAttributes, ReactNode } from 'react';
+import { GripIcon } from '../GripIcon/GripIcon';
 import styles from './DragHandleRow.module.css';
 
 export interface DragHandleRowProps extends HTMLAttributes<HTMLDivElement> {
@@ -33,29 +34,9 @@ export function DragHandleRow({
         tabIndex={-1}
         {...handleProps}
       >
-        <DragIcon />
+        <GripIcon className={styles.icon} />
       </button>
       <div className={styles.content}>{children}</div>
     </div>
   );
 }
-
-function DragIcon() {
-  return (
-    <svg
-      width="14"
-      height="14"
-      viewBox="0 0 14 14"
-      fill="none"
-      aria-hidden="true"
-      className={styles.icon}
-    >
-      {/* Two columns of three dots */}
-      {[3, 7, 11].map((cy) =>
-        [4, 10].map((cx) => (
-          <circle key={`${cx}-${cy}`} cx={cx} cy={cy} r={1.2} fill="currentColor" />
-        )),
-      )}
-    </svg>
-  );
-}

package/src/components/Drawer/Drawer.module.css

@@ -7,8 +7,10 @@
 .scrim {
   position: fixed;
   inset: 0;
-  /* When the shell declares --sv-shell-footer-height (mobile nav bar), stop the
-     scrim above the footer so the panel never hides behind it. */
+  /* When --sv-shell-footer-height is set (mobile nav bar — by the platform
+     shell, or by a self-rendered MobileFooter via usePublishShellChromeHeight
+     for a shellConfig.mobileFooter: false plugin), stop the scrim above the
+     footer so the panel never hides behind it. */
   bottom: var(--sv-shell-footer-height, 0);
   z-index: 100;
   display: flex;
@@ -27,14 +29,21 @@
 .panel {
   width: 100%;
   max-height: 80dvh;
-  overflow-y: auto;
-  overscroll-behavior: contain;
+  /* The panel itself no longer scrolls — see .body below. display: flex
+     (column) lets .handle (and OverlayHeader, when title is set) stay
+     fixed while .body's own overflow-y handles content taller than the
+     80dvh cap, the same fixed-header/scrollable-body split Sheet.module.css
+     already establishes (its .panel/.content pair). Before this, the whole
+     .panel scrolled as one block, so a tall drawer (e.g. many installed
+     plugins in the Apps grid) scrolled the grab handle itself out of view
+     along with the content — reachable in the DOM, invisible on screen. */
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
   background: var(--sv-color-surface-raised);
-  border-top: 1px solid var(--sv-color-border);
+  border-top: var(--sv-border-width-hairline) solid var(--sv-color-border);
   border-radius: var(--sv-radius-3xl) var(--sv-radius-3xl) 0 0;
   box-shadow: var(--sv-shadow-overlay);
-  /* Pull content above the home indicator / bottom bar in standalone mode. */
-  padding-bottom: env(safe-area-inset-bottom);
   outline: none;
   /* Slide up from below the viewport. Always a bottom sheet, so unlike Dialog
      there's no desktop-vs-mobile fork here. */
@@ -42,6 +51,26 @@
   transition: transform var(--sv-motion-duration-base) var(--sv-motion-ease-out);
 }
 
+/* The scroll container — everything below the fixed handle/OverlayHeader.
+   Scrollbar hidden (not overflow removed) the same way Tabs.module.css's
+   .tablist already does for this design system; scroll-driven UI here reads
+   as a native swipe list, not a document needing a visible scroll affordance. */
+.body {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  scrollbar-width: none;
+  /* Pull content above the home indicator / bottom bar in standalone mode —
+     moved here from .panel now that this is the element whose bottom edge
+     is the actual scrollable content boundary. */
+  padding-bottom: env(safe-area-inset-bottom);
+}
+
+.body::-webkit-scrollbar {
+  display: none;
+}
+
 .panelOpen {
   transform: translateY(0);
 }

package/src/components/Drawer/Drawer.tsx

@@ -3,6 +3,7 @@
 import { type PointerEvent as ReactPointerEvent, type ReactNode, useRef } from 'react';
 import { useMountTransition, usePrefersReducedMotion } from '../../motion';
 import {
+  OVERLAY_MOTION_DURATION_MS,
   useOverlayFocusCapture,
   useOverlayKeyboardTrap,
   useOverlayScrollLock,
@@ -10,11 +11,6 @@ import {
 import { OverlayHeader } from '../OverlayHeader/OverlayHeader';
 import styles from './Drawer.module.css';
 
-// Matches --sv-motion-duration-base (Drawer.module.css) — see Dialog.tsx's
-// identical constant for why this stays a plain JS number instead of being
-// read from the CSS custom property.
-const MOTION_DURATION_MS = 250;
-
 export interface DrawerProps {
   /** Whether the drawer is shown. When false, nothing renders. */
   open: boolean;
@@ -74,7 +70,10 @@ export function Drawer({
 }: DrawerProps) {
   const panelRef = useRef<HTMLDivElement>(null);
   const reducedMotion = usePrefersReducedMotion();
-  const { mounted, phase } = useMountTransition(open, reducedMotion ? 0 : MOTION_DURATION_MS);
+  const { mounted, phase } = useMountTransition(
+    open,
+    reducedMotion ? 0 : OVERLAY_MOTION_DURATION_MS,
+  );
   // Tracks an in-progress handle drag. Kept in a ref (not state) so pointermove
   // updates the DOM directly at 60fps instead of re-rendering on every event —
   // same technique as the tasks plugin's swipe-to-reveal rows.
@@ -132,15 +131,15 @@ export function Drawer({
   return (
     // role="presentation" removes the scrim from the AT (it is purely visual).
     // e.target check lets clicks inside the panel bubble without triggering dismiss.
+    // No onKeyDown here — useOverlayKeyboardTrap above already owns Escape via a
+    // document-level listener; a second handler here used to double-fire onClose
+    // per keypress (see Dialog.tsx's identical fix for the full explanation).
     <div
       className={[styles.scrim, isOpenPhase ? styles.scrimOpen : ''].filter(Boolean).join(' ')}
       role="presentation"
       onClick={(e) => {
         if (e.target === e.currentTarget) onClose();
       }}
-      onKeyDown={(e) => {
-        if (e.key === 'Escape') onClose();
-      }}
     >
       <div
         ref={panelRef}
@@ -169,7 +168,7 @@ export function Drawer({
           onPointerCancel={(e) => releaseDrag(e, false)}
         />
         {title && <OverlayHeader title={title} onClose={onClose} />}
-        {children}
+        <div className={styles.body}>{children}</div>
       </div>
     </div>
   );