@sovereignfs/ui 0.54.0 → 0.83.1

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

@@ -1,22 +1,47 @@
 // @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';
 
 // jsdom does not implement HTMLDialogElement.showModal()/close() (a
 // long-standing, documented gap) — polyfill the minimum behavior the
 // component depends on: the `open` attribute reflecting visibility, and
 // close() dispatching the native 'close' event ConfirmDialog listens for.
+//
+// Two details matter here beyond the minimum, both load-bearing for the
+// double-onClose regression tests below: (1) a no-op when already closed,
+// matching the HTML spec's own early return, and (2) the 'close' event is
+// queued rather than dispatched synchronously ("queue an element task ... to
+// fire an event named close" per spec) — deferring it means a listener
+// (re-)attached during the SAME synchronous React commit that triggered this
+// close() call is still reachable once the event actually fires, exactly as
+// in a real browser. Dispatching synchronously instead (the simpler version
+// this replaced) fires the event in the middle of React's effect
+// cleanup/setup phase, when no listener happens to be attached yet — which
+// made the double-call bug this file guards against silently unreproducible
+// in jsdom regardless of whether the underlying component bug was present.
 beforeEach(() => {
   HTMLDialogElement.prototype.showModal = function (this: HTMLDialogElement) {
     this.setAttribute('open', '');
   };
   HTMLDialogElement.prototype.close = function (this: HTMLDialogElement) {
+    if (!this.hasAttribute('open')) return;
     this.removeAttribute('open');
-    this.dispatchEvent(new Event('close'));
+    queueMicrotask(() => this.dispatchEvent(new Event('close')));
   };
 });
 
+// Flushes any chain of queueMicrotask-deferred dispatches and the React
+// state updates/effects they trigger. A single real macrotask tick is
+// enough: the microtask queue always fully drains — including microtasks
+// newly queued from within an already-running one — before a macrotask runs.
+async function flushDeferredDialogEvents() {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
 describe('ConfirmDialog', () => {
   afterEach(cleanup);
 
@@ -51,15 +76,58 @@ describe('ConfirmDialog', () => {
     expect(screen.getByText('Example').tagName).toBe('STRONG');
   });
 
-  it('calls onClose on Cancel', () => {
+  it('calls onClose on Cancel', async () => {
     const onClose = vi.fn();
     render(
       <ConfirmDialog open onClose={onClose} onConfirm={() => {}} title="Remove" message="Sure?" />,
     );
+    // Cancel now calls dialogRef.current.close() rather than onClose
+    // directly (see ConfirmDialog.tsx) — onClose only fires once the
+    // resulting (deferred, see the polyfill above) native 'close' event
+    // reaches ConfirmDialog's own listener.
     fireEvent.click(screen.getByRole('button', { name: 'Cancel' }));
+    await flushDeferredDialogEvents();
     expect(onClose).toHaveBeenCalledOnce();
   });
 
+  // Statefully wired, unlike the test above: a real consumer's onClose flips
+  // its own `open` state to false, which re-runs ConfirmDialog's internal
+  // `if (open) showModal(); else el.close();` effect and calls el.close()
+  // itself. Pre-fix, Cancel/backdrop-click also called onClose directly,
+  // so this path fired onClose a second time; the test above's static
+  // `open` prop never changes, so it can't exercise that second re-render.
+  function StatefulConfirmDialog({ onCloseSpy }: { onCloseSpy: () => void }) {
+    const [open, setOpen] = useState(true);
+    return (
+      <ConfirmDialog
+        open={open}
+        onClose={() => {
+          onCloseSpy();
+          setOpen(false);
+        }}
+        onConfirm={() => {}}
+        title="Remove"
+        message="Sure?"
+      />
+    );
+  }
+
+  it('calls onClose exactly once when a stateful consumer dismisses via Cancel', async () => {
+    const onCloseSpy = vi.fn();
+    render(<StatefulConfirmDialog onCloseSpy={onCloseSpy} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Cancel' }));
+    await flushDeferredDialogEvents();
+    expect(onCloseSpy).toHaveBeenCalledOnce();
+  });
+
+  it('calls onClose exactly once when a stateful consumer dismisses via backdrop click', async () => {
+    const onCloseSpy = vi.fn();
+    render(<StatefulConfirmDialog onCloseSpy={onCloseSpy} />);
+    fireEvent.click(screen.getByRole('dialog'));
+    await flushDeferredDialogEvents();
+    expect(onCloseSpy).toHaveBeenCalledOnce();
+  });
+
   it('calls onConfirm on the confirm action, without itself closing', () => {
     const onConfirm = vi.fn();
     const onClose = vi.fn();

package/src/components/ConsentPrompt/ConsentPrompt.module.css

@@ -0,0 +1,21 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sv-space-2);
+}
+
+.title {
+  font-size: var(--sv-font-size-sm);
+  color: var(--sv-color-text-primary);
+}
+
+.description {
+  font-size: var(--sv-font-size-sm);
+  color: var(--sv-color-text-muted);
+}
+
+.actions {
+  display: flex;
+  gap: var(--sv-space-2);
+  margin-top: var(--sv-space-1);
+}

package/src/components/ConsentPrompt/ConsentPrompt.stories.tsx

@@ -0,0 +1,31 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ConsentPrompt } from './ConsentPrompt';
+
+const meta = {
+  title: 'Components/ConsentPrompt',
+  component: ConsentPrompt,
+  parameters: { layout: 'padded' },
+  args: {
+    consumerName: 'Ledger',
+    providerName: 'Finance Tracker',
+    contract: 'expenses',
+    description: 'Monthly expense totals by category, no transaction-level detail.',
+    onAllow: () => {},
+    onDeny: () => {},
+  },
+} satisfies Meta<typeof ConsentPrompt>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {};
+
+export const NoDescription: Story = {
+  args: { description: null },
+};
+
+export const Pending: Story = {
+  args: { pending: true },
+};

package/src/components/ConsentPrompt/ConsentPrompt.tsx

@@ -0,0 +1,66 @@
+import { Button } from '../Button/Button';
+import { Card } from '../Card/Card';
+import styles from './ConsentPrompt.module.css';
+
+export interface ConsentPromptProps {
+  /** The plugin requesting access. */
+  consumerName: string;
+  /** The plugin whose data would be read. */
+  providerName: string;
+  /** The named contract being requested (e.g. `"expenses"`). */
+  contract: string;
+  /**
+   * The provider's own manifest-declared explanation of what this contract
+   * exposes (`data.provides[].description`) — never caller-supplied at
+   * request time, so a consuming plugin can't write its own persuasive copy
+   * for what it's asking to read.
+   */
+  description?: string | null;
+  onAllow: () => void;
+  onDeny?: () => void;
+  allowLabel?: string;
+  denyLabel?: string;
+  /** Disables both buttons and shows a busy state on Allow while a request is in flight. */
+  pending?: boolean;
+  className?: string;
+}
+
+/**
+ * The consent screen shown before one plugin is allowed to read another
+ * plugin's data (RFC 0002 §4) — the step that was previously missing between
+ * a `ConsentRequiredError` and a grant actually being created. Presentational
+ * only: holds no state of its own, so it renders identically wherever it's
+ * used (currently Account → Data's pending-requests list).
+ */
+export function ConsentPrompt({
+  consumerName,
+  providerName,
+  contract,
+  description,
+  onAllow,
+  onDeny,
+  allowLabel = 'Allow',
+  denyLabel = 'Not now',
+  pending = false,
+  className,
+}: ConsentPromptProps) {
+  return (
+    <Card padding="sm" className={[styles.root, className].filter(Boolean).join(' ')}>
+      <p className={styles.title}>
+        <strong>{consumerName}</strong> wants to read <strong>{contract}</strong> from{' '}
+        <strong>{providerName}</strong>
+      </p>
+      {description ? <p className={styles.description}>{description}</p> : null}
+      <div className={styles.actions}>
+        <Button variant="primary" size="sm" onClick={onAllow} disabled={pending} loading={pending}>
+          {allowLabel}
+        </Button>
+        {onDeny ? (
+          <Button variant="ghost" size="sm" onClick={onDeny} disabled={pending}>
+            {denyLabel}
+          </Button>
+        ) : null}
+      </div>
+    </Card>
+  );
+}

package/src/components/ContextMenu/ContextMenu.tsx

@@ -64,7 +64,7 @@ export function ContextMenu({ children, items, 'aria-label': ariaLabel }: Contex
       items={items}
       onSelect={(entry: MenuItem) => {
         setOpen(false);
-        entry.onSelect();
+        entry.onSelect?.();
       }}
     />
   );

package/src/components/DatePicker/DatePicker.module.css

@@ -17,7 +17,7 @@
   line-height: 1.5;
   color: var(--sv-color-text-primary);
   background-color: var(--sv-color-surface);
-  border: 1px solid var(--sv-color-border-strong);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border-strong);
   border-radius: var(--sv-radius-md);
   cursor: pointer;
   transition:

package/src/components/Dialog/Dialog.module.css

@@ -1,13 +1,31 @@
 /* Dialog — scrim + centered panel. Tokens only (z-index is structural, not a
  * theming value, so it has no token).
  *
- * Each size is a FIXED box (width AND height) — the panel never grows or
- * shrinks with its content, so switching views inside it (e.g. overlay-plugin
- * tabs) keeps the dialog the exact same size. Overflow scrolls inside `.content`
- * while the panel and its close button stay put. The scrim's padding is the
- * fixed margin `lg` leaves around the viewport; `sm`/`md` are centered and cap
- * to that available space on short screens. On mobile every size becomes a
- * full-screen sheet.
+ * `sm`/`md` are a fixed WIDTH but a content-driven height, capped at a
+ * per-size max-height: the panel grows to fit its content and shrinks when
+ * content is sparse, only hitting the cap (and scrolling internally, inside
+ * `.content`) once content actually exceeds it. Before this, height was
+ * fixed too, which left short-content consumers (e.g. a two-field form in
+ * console/plugins/PluginAccessDialog.tsx) looking like a near-empty
+ * skeleton — see docs/architecture-rules.md. `auto` goes further — content-
+ * driven on BOTH width and height, each independently capped rather than
+ * either being fixed — for content whose natural footprint varies enough
+ * (a card detail modal with an optional checklist/comments section) that a
+ * single fixed width doesn't fit it well either short or long. `lg` is a
+ * true fixed box (100%/100% of the scrim's available area) — no current
+ * overlay-shell plugin renders into it (Console did until workstream 0022
+ * moved it to `shell: "default"`; Account never resized off `overlaySize:
+ * "lg"`'s original default until epic task 14.5, see `fixed` below).
+ * `fixed` (named after its own behavior, not after this file's always-
+ * applied `.panel` wrapper class below) is also a true fixed box, width
+ * AND height both set — same "content never resizes it" guarantee as `lg`
+ * — but capped rather than filling the viewport, for a plugin whose
+ * settings-panel-shaped content doesn't warrant `lg`'s full-screen footprint
+ * (Account's own case, epic task 14.5 round 3). The close button stays
+ * pinned top-right regardless. The scrim's padding is the fixed margin
+ * `lg`/`fixed` leave around the viewport; `sm`/`md`/`auto` are centered and
+ * cap to that available space on short screens too. On mobile every size
+ * becomes a full-screen sheet.
  *
  * `--sv-dialog-inset-left` lets a host inset the scrim past a fixed left nav
  * rail (e.g. the platform sidebar) so the overlay's left margin is measured
@@ -50,7 +68,7 @@
   overflow: hidden;
   background: var(--sv-color-surface-raised);
   color: var(--sv-color-text-primary);
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   border-radius: var(--sv-radius-lg);
   box-shadow: var(--sv-shadow-overlay);
   /* Desktop entrance: fade + gentle scale-up. Same two-phase-mount pattern as
@@ -86,7 +104,21 @@
   flex: 1 1 auto;
   overflow-y: auto;
   overflow-x: hidden;
+  /* Same slim, token-colored scrollbar as `ScrollArea`/`MessageScroller` —
+     without this, a `sm`/`md` dialog whose content exceeds its max-height
+     cap (e.g. on a short viewport where the cap itself shrinks to fit) gets
+     the browser's default OS scrollbar, which on non-overlay-scrollbar
+     platforms is wide enough to visually cut into `.panel`'s rounded
+     corner right where `.content` starts, reading as a layout bug rather
+     than an intentional scroll affordance. */
+  scrollbar-width: thin;
+  scrollbar-color: var(--sv-color-border-strong) transparent;
   padding: var(--sv-space-6);
+  /* This region already supplies the page gutter, so a PageContainer rendered
+     inside it stands its own down (see PageContainer.module.css). Without
+     this, an overlay plugin — one page tree rendered into both the Dialog and
+     the full-page shell fallback — would be padded twice here. */
+  --sv-page-gutter: 0px;
   /* Disable elastic overscroll within the dialog: `none` stops both scroll-
      chaining to the parent and the iOS rubber-band bounce inside the panel.
      `contain` only prevents chaining — the panel itself still bounces, which
@@ -96,33 +128,94 @@
   overscroll-behavior: none;
 }
 
-/* Fixed sizes. `max-*: 100%` caps to the scrim's content box (viewport minus
- * margin) so a size never overflows a small viewport. */
+.content::-webkit-scrollbar {
+  width: 8px;
+}
+
+.content::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.content::-webkit-scrollbar-thumb {
+  background: var(--sv-color-border-strong);
+  border-radius: var(--sv-radius-full);
+}
+
+/* `sm`/`md`: fixed width, content-driven height up to the size's own cap
+ * (28rem/42rem — the box's old fixed heights, now a ceiling rather than a
+ * floor). `min(<cap>, 100%)` also still caps to the scrim's content box
+ * (viewport minus margin) so a size never overflows a short viewport. No
+ * explicit `height` — the panel's flex column sizes to `.content`'s natural
+ * height on its own; see the file-level comment above. */
 .sm {
   width: 24rem;
-  height: 28rem;
   max-width: 100%;
-  max-height: 100%;
+  max-height: min(28rem, 100%);
 }
 
 .md {
   width: 36rem;
-  height: 42rem;
   max-width: 100%;
-  max-height: 100%;
+  max-height: min(42rem, 100%);
 }
 
-.lg,
-.full {
+/* Content-driven on both axes, unlike `sm`/`md` (width fixed, only height
+ * content-driven) — for a dialog whose natural footprint varies a lot (a
+ * card detail modal with labels/due-date/assignees/description/checklist/
+ * comments, the case that originally motivated the now-removed `xl` size
+ * this replaces). `width: fit-content` shrink-wraps to the panel's own
+ * content (bounded by min/max-width below) the same way a flex item
+ * centered in `.scrim` naturally would with no explicit `width` at all —
+ * `min-width` just keeps sparse content (e.g. a short message) from reading
+ * as an oddly narrow sliver. Caps chosen to span roughly what `sm`/`xl`
+ * used to cover between them. */
+.auto {
+  width: fit-content;
+  min-width: min(24rem, 100%);
+  max-width: min(48rem, 100%);
+  max-height: min(48rem, 100%);
+}
+
+/* `lg`: a true fixed box, unaffected by the above — see the file-level
+ * comment. */
+.lg {
   width: 100%;
   height: 100%;
 }
 
+/* `fixed`: also a true fixed box (width AND height both set, like `lg`) but
+ * capped rather than filling the viewport — see the file-level comment.
+ * Named distinctly from the dialog's own always-applied `.panel` wrapper
+ * class above (every size gets `styles.panel` + `styles[size]` together —
+ * see Dialog.tsx) to avoid colliding with it. `max-width`/`max-height` are
+ * still needed despite `width`/`height` being fixed rem values, exactly
+ * like `sm`/`md`'s own `max-width: 100%` — a short or narrow viewport (a
+ * resized desktop window, not yet at the mobile breakpoint) must still be
+ * able to shrink this below its rem values instead of overflowing the
+ * scrim. */
+.fixed {
+  width: 64rem;
+  max-width: 100%;
+  height: 44rem;
+  max-height: 100%;
+}
+
 .close {
   position: absolute;
   top: var(--sv-space-3);
   right: var(--sv-space-3);
-  z-index: 1;
+  /* 2, not 1: a plugin's own sticky in-body header (e.g. a card detail
+     modal's title row) needs to paint above ordinary scrolling content, so
+     it sits at z-index: 1 — if `.close` also sat at 1, tree order would
+     decide the tie, and `.close` (rendered earlier in this component's own
+     JSX, before `.content` and everything a plugin nests inside it) would
+     lose to the plugin's later-in-tree header, disappearing underneath it
+     once they overlap on scroll. 2 keeps `.close` unambiguously on top
+     without relying on a tie-break plugin authors have no visibility into.
+     Found live in `sovereign-plugin-kanban`'s card detail modal — see that
+     repo's `kanban.module.css` `.cardHeader` comment for the matching half
+     of this fix and the Popover-stacking bug that motivated it. */
+  z-index: 2;
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -132,8 +225,6 @@
   border-radius: var(--sv-radius-md);
   background: transparent;
   color: var(--sv-color-text-muted);
-  font-size: var(--sv-font-size-xl);
-  line-height: 1;
   cursor: pointer;
 }
 
@@ -151,11 +242,27 @@
 
 /* Hidden on desktop; shown only on mobile where it replaces the close button.
  * OverlayHeader owns its own background/border/padding — this wrapper class
- * only toggles visibility per breakpoint. */
+ * only toggles visibility per breakpoint. Not used at all when the `header`
+ * prop is active — that OverlayHeader instance renders with no wrapper
+ * class, so it shows unconditionally on both breakpoints (see Dialog.tsx). */
 .mobileHeader {
   display: none;
 }
 
+/* The optional `footer` prop's row — shown on both desktop and mobile (no
+ * breakpoint gating, unlike `.mobileHeader`), a flex sibling after `.content`
+ * so it never scrolls, mirroring OverlayHeader's own `.header`/`.row`
+ * treatment (border on the opposite edge, same padding scale) so header and
+ * footer read as a matched pair when both are present. Layout-agnostic
+ * beyond that — the footer's own content decides its internal arrangement
+ * (e.g. a flex row with `justify-content: flex-end` for action buttons). */
+.footer {
+  flex-shrink: 0;
+  background: var(--sv-color-surface);
+  border-top: var(--sv-border-width-hairline) solid var(--sv-color-border);
+  padding: var(--sv-space-3) var(--sv-space-4);
+}
+
 /* Mobile: full-screen sheet (RFC 0001 §3, breakpoint unified to 768px per
  * RFC 0013). Every size fills the scrim's available area (which is already
  * inset from the top by --sv-dialog-inset-top when a fixed header is shown).
@@ -177,9 +284,11 @@
   .sm,
   .md,
   .lg,
-  .full {
+  .auto,
+  .fixed {
     width: 100%;
     height: 100%;
+    min-width: 0;
     max-width: none;
     max-height: none;
     border: none;

package/src/components/Dialog/Dialog.stories.tsx

@@ -9,7 +9,7 @@ function DialogDemo({
   size = 'lg',
   label = 'Example dialog',
 }: {
-  size?: 'sm' | 'md' | 'lg' | 'full';
+  size?: 'sm' | 'md' | 'lg' | 'auto' | 'fixed';
   label?: string;
 }) {
   const [open, setOpen] = useState(false);
@@ -48,7 +48,7 @@ const meta = {
     docs: {
       description: {
         component:
-          'Modal surface (scrim + panel). Router-agnostic — caller provides `onClose`. Supports Esc, scrim-click, focus trap and focus restoration. Sizes: `sm` / `md` / `lg` / `full`. Mobile always renders as a full-screen sheet.',
+          'Modal surface (scrim + panel). Router-agnostic — caller provides `onClose`. Supports Esc, scrim-click, focus trap and focus restoration. Sizes: `sm` / `md` / `lg` / `auto` / `fixed`. `sm`/`md` are fixed-width, content-driven height; `auto` is content-driven on both width and height; `lg` is a true fixed 100%/100% box; `fixed` is also a true fixed box (width and height both set, content never resizes it) but capped at 64rem×44rem rather than filling the viewport. Mobile always renders as a full-screen sheet. Three composition shapes via the optional `header`/`footer` props: Body only (both omitted, the default), Header + Body, Header + Body + Footer — see the stories below the size examples.',
       },
     },
   },
@@ -74,6 +74,62 @@ export const Large: Story = {
   render: (_args) => <DialogDemo size="lg" label="Large dialog" />,
 };
 
+/**
+ * `fixed` is a true fixed box like `lg` (width AND height both set — content
+ * never resizes it) but capped at 64rem×44rem rather than filling the
+ * viewport. Added for epic task 14.5 (Account's vertical nav): a plugin
+ * whose route tree includes a client-side redirect through a near-empty
+ * intermediate page needs a size that won't visibly shrink to fit that empty
+ * page and then grow once real content lands — every other size is
+ * content-driven on at least one axis and would do exactly that.
+ */
+export const Fixed: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => <DialogDemo size="fixed" label="Fixed dialog" />,
+};
+
+/**
+ * `auto` sizes to content on both width and height, unlike `sm`/`md` (fixed
+ * width, content-driven height only) — capped, not fixed, on either axis.
+ * This demo's own content is deliberately narrower than `md`'s 36rem, so the
+ * panel visibly shrinks below it — a fixed-width size can't do that.
+ */
+export const AutoSize: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => {
+    function Demo() {
+      const [open, setOpen] = useState(false);
+      return (
+        <>
+          <Button onClick={() => setOpen(true)}>Open auto-sized dialog</Button>
+          <Dialog open={open} onClose={() => setOpen(false)} size="auto" aria-label="Delete item?">
+            <div style={{ padding: 24, fontFamily: 'system-ui', maxWidth: '18rem' }}>
+              <h2
+                style={{
+                  fontSize: 18,
+                  fontWeight: 600,
+                  color: 'var(--sv-color-text-primary)',
+                  marginBottom: 12,
+                }}
+              >
+                Delete item?
+              </h2>
+              <p style={{ color: 'var(--sv-color-text-muted)', marginBottom: 24 }}>
+                This panel is narrower than `md`'s fixed 36rem — `auto` shrank to fit this short
+                message instead of padding out a fixed width.
+              </p>
+              <Button variant="secondary" onClick={() => setOpen(false)}>
+                Close
+              </Button>
+            </div>
+          </Dialog>
+        </>
+      );
+    }
+    return <Demo />;
+  },
+};
+
 export const Closed: Story = {
   args: { open: false, onClose: () => {}, children: null },
   render: (_args) => (
@@ -145,3 +201,124 @@ export const WithOverlaySecondRow: Story = {
     return <Demo />;
   },
 };
+
+// ---------------------------------------------------------------------------
+// Composition shapes (header/footer props) — Body only is every story above
+// this point (both props omitted); these three demonstrate the other two.
+
+/**
+ * "Body only" — the default shape (both `header` and `footer` omitted).
+ * Included explicitly alongside the size stories above as the baseline the
+ * other two composition shapes are compared against: no visible header on
+ * desktop, a floating close button instead, and any actions live inside the
+ * scrollable body.
+ */
+export const BodyOnly: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => {
+    function Demo() {
+      const [open, setOpen] = useState(false);
+      return (
+        <>
+          <Button onClick={() => setOpen(true)}>Open body-only dialog</Button>
+          <Dialog open={open} onClose={() => setOpen(false)} size="sm" aria-label="Body only">
+            <div style={{ padding: 24, fontFamily: 'system-ui' }}>
+              <p style={{ color: 'var(--sv-color-text-muted)' }}>
+                No `header` or `footer` prop — today's default. Desktop shows only the floating
+                close button; actions (if any) live in this scrolling body, same as before this
+                task.
+              </p>
+            </div>
+          </Dialog>
+        </>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+/**
+ * "Header + Body" — the `header` prop renders a persistent title/close row
+ * on both desktop and mobile (unlike the plain `title` prop, which is
+ * mobile-only). Resize the viewport to confirm the header stays visible and
+ * identically styled at both widths.
+ */
+export const HeaderAndBody: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => {
+    function Demo() {
+      const [open, setOpen] = useState(false);
+      return (
+        <>
+          <Button onClick={() => setOpen(true)}>Open header + body dialog</Button>
+          <Dialog
+            open={open}
+            onClose={() => setOpen(false)}
+            size="sm"
+            header="Card detail"
+            aria-label="Card detail"
+          >
+            <div style={{ padding: 24, fontFamily: 'system-ui' }}>
+              <p style={{ color: 'var(--sv-color-text-muted)' }}>
+                The "Card detail" title above is the `header` prop, rendered via the same shared
+                header row on both desktop and mobile — resize the viewport to confirm it doesn't
+                disappear on desktop the way a plain `title` would.
+              </p>
+            </div>
+          </Dialog>
+        </>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+/**
+ * "Header + Body + Footer" — both `header` and `footer` are pinned flex
+ * siblings around `.content`; only the body between them scrolls. The body
+ * here is long enough to actually scroll, so header/footer staying put is
+ * visible, not just theoretical — check this at both a desktop and a
+ * ≤768px viewport per this task's own review checklist.
+ */
+export const HeaderBodyFooter: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => {
+    function Demo() {
+      const [open, setOpen] = useState(false);
+      return (
+        <>
+          <Button onClick={() => setOpen(true)}>Open header + body + footer dialog</Button>
+          <Dialog
+            open={open}
+            onClose={() => setOpen(false)}
+            size="sm"
+            header="Edit card"
+            footer={
+              <div style={{ display: 'flex', gap: 12, justifyContent: 'flex-end' }}>
+                <Button variant="secondary" onClick={() => setOpen(false)}>
+                  Cancel
+                </Button>
+                <Button onClick={() => setOpen(false)}>Save</Button>
+              </div>
+            }
+            aria-label="Edit card"
+          >
+            <div style={{ padding: 24, fontFamily: 'system-ui', display: 'grid', gap: 16 }}>
+              <p style={{ color: 'var(--sv-color-text-muted)' }}>
+                Scroll this body — the "Edit card" header above and the Cancel/Save footer below
+                both stay pinned; only this region between them moves.
+              </p>
+              {Array.from({ length: 12 }, (_, i) => (
+                <p key={i} style={{ color: 'var(--sv-color-text-muted)' }}>
+                  Field {i + 1} of 12 — filler content long enough to force `.content` to actually
+                  scroll, so the pinned header/footer behavior is visible rather than theoretical.
+                </p>
+              ))}
+            </div>
+          </Dialog>
+        </>
+      );
+    }
+    return <Demo />;
+  },
+};