@sovereignfs/ui 0.23.0 → 0.33.1

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

@@ -31,6 +31,16 @@
   padding: var(--sv-space-8);
   padding-left: calc(var(--sv-dialog-inset-left, 0px) + var(--sv-space-8));
   background: var(--sv-color-scrim);
+  /* Entrance/exit fade. The Dialog component drives this via a two-phase
+     mount (see motion.ts) — .scrimOpen is added one frame after mount so this
+     transition has somewhere to animate from, and removed (while staying
+     mounted) for the exit before the component actually unmounts. */
+  opacity: 0;
+  transition: opacity var(--sv-motion-duration-base) var(--sv-motion-ease-out);
+}
+
+.scrimOpen {
+  opacity: 1;
 }
 
 .panel {
@@ -43,6 +53,30 @@
   border: 1px 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
+     .scrim above. Mobile overrides this to a slide-up instead (below). */
+  opacity: 0;
+  transform: scale(0.96);
+  transition:
+    opacity var(--sv-motion-duration-base) var(--sv-motion-ease-out),
+    transform var(--sv-motion-duration-base) var(--sv-motion-ease-out);
+}
+
+.panelOpen {
+  opacity: 1;
+  transform: scale(1);
+}
+
+/* prefers-reduced-motion: collapse both fade/scale and slide to near-instant.
+   Not literally 0 — a 0ms transition can skip applying entirely in some
+   engines, and the JS unmount timer (Dialog.tsx's MOTION_DURATION_MS,
+   switched to ~0 via usePrefersReducedMotion) needs a transition to still be
+   "present" for the visual state to actually reach its end value in time. */
+@media (prefers-reduced-motion: reduce) {
+  .scrim,
+  .panel {
+    transition-duration: 0.01ms;
+  }
 }
 
 .content {
@@ -53,7 +87,7 @@
   /* 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
-     reveals white panel-background between the mobileBar and the sticky tab
+     reveals white panel-background between OverlayHeader and the sticky tab
      strip on iOS PWA. A dialog is a bounded surface where bounce is a visual
      bug, not a feature. */
   overscroll-behavior: none;
@@ -100,9 +134,11 @@
   cursor: pointer;
 }
 
-.close:hover {
-  background: var(--sv-color-surface-sunken);
-  color: var(--sv-color-text-primary);
+@media (hover: hover) {
+  .close:hover {
+    background: var(--sv-color-surface-sunken);
+    color: var(--sv-color-text-primary);
+  }
 }
 
 .close:focus-visible {
@@ -110,8 +146,10 @@
   outline-offset: 2px;
 }
 
-/* Hidden on desktop; shown only on mobile where it replaces the close button. */
-.mobileBar {
+/* 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. */
+.mobileHeader {
   display: none;
 }
 
@@ -122,10 +160,14 @@
 @media (max-width: 768px) {
   /* On mobile the overlay feels like a full-page push, not a floating modal.
      Remove the dim scrim and panel chrome so it's indistinguishable from a
-     regular page render. router.back() still closes it correctly. */
+     regular page render. router.back() still closes it correctly.
+     bottom stops the scrim above the footer nav (matching Drawer) instead of
+     running the full viewport height — the panel used to extend under the
+     footer with only .content's own padding compensating for it. */
   .scrim {
     padding: 0;
     background: transparent;
+    bottom: var(--sv-shell-footer-height, 0);
   }
 
   .panel,
@@ -143,54 +185,39 @@
     background: var(--sv-color-surface);
   }
 
-  /* Desktop close button is replaced by mobileBar on mobile. */
-  .close {
-    display: none;
+  /* Mobile entrance is a slide-up, not the desktop fade+scale — matches "page
+     push" framing above. No opacity change (the panel is opaque full-screen
+     content, not a floating box), so only transform needs a transition here. */
+  .panel {
+    opacity: 1;
+    transform: translateY(100%);
+    transition: transform var(--sv-motion-duration-base) var(--sv-motion-ease-out);
   }
 
-  /* Title + close button in one solid row. Being a flex sibling before
-     .content means it never scrolls — the content area scrolls below it. */
-  .mobileBar {
-    display: flex;
-    align-items: center;
-    flex-shrink: 0;
-    padding: var(--sv-space-3) var(--sv-space-4);
-    background: var(--sv-color-surface);
-    border-bottom: 1px solid var(--sv-color-border);
-  }
-
-  .mobileBarTitle {
-    flex: 1;
-    font-size: var(--sv-font-size-xl);
-    font-weight: var(--sv-font-weight-semibold);
-    color: var(--sv-color-text-primary);
-  }
-
-  .mobileBarClose {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    width: var(--sv-space-8);
-    height: var(--sv-space-8);
-    flex-shrink: 0;
-    border: none;
-    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;
+  .panelOpen {
+    transform: translateY(0);
   }
 
-  .mobileBarClose:hover {
-    background: var(--sv-color-surface-sunken);
-    color: var(--sv-color-text-primary);
+  /* Desktop close button is replaced by OverlayHeader on mobile. */
+  .close {
+    display: none;
   }
 
-  /* Remove top padding so the sticky plugin header sits flush against the
-     mobileBar — no gap for scrolling content to bleed through. */
-  .content {
-    padding-top: 0;
-    padding-bottom: calc(var(--sv-shell-footer-height, 60px) + var(--sv-space-6, 24px));
+  /* Title + close button in one solid row, via the shared OverlayHeader
+     component. Being a flex sibling before .content means it never scrolls —
+     the content area scrolls below it.
+     .content itself needs no mobile override here any more: it used to zero
+     out padding-top so a plugin's hand-rolled sticky header (rendered as
+     .content's own first child, right below OverlayHeader) would sit flush
+     against it. That case no longer exists — a plugin with a tab strip/
+     secondary nav now hands it to OverlayHeader's own secondRow slot
+     (useOverlaySecondRow) instead of rendering it inside .content; Account
+     and Console both migrated to this (mobile design-system plan, Phase
+     C1b). With .content's first child back to being genuine page content, it
+     needs the same breathing room from the header that .content's own base
+     padding (var(--sv-space-6) on every side) already provides everywhere
+     else. */
+  .mobileHeader {
+    display: block;
   }
 }

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

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { expect, userEvent, within } from 'storybook/test';
 import { useState } from 'react';
 import { Button } from '../Button/Button';
-import { Dialog } from './Dialog';
+import { Dialog, useOverlaySecondRow } from './Dialog';
 
 // Controlled wrapper so the play function can open/inspect the dialog.
 function DialogDemo({
@@ -95,3 +95,53 @@ export const OpenViaInteraction: Story = {
     await expect(dialog).toBeVisible();
   },
 };
+
+// A stand-in for a plugin's own route layout — several component layers below
+// wherever <Dialog> itself is instantiated, exactly like the real
+// AccountLayout/ConsoleLayout usage this hook was built for.
+function NestedTabStrip() {
+  const insideOverlay = useOverlaySecondRow(
+    <div style={{ display: 'flex', gap: 16, padding: '0 16px' }}>
+      {['Profile', 'Security', 'Preferences'].map((tab) => (
+        <span key={tab} style={{ fontSize: 14, color: 'var(--sv-color-text-primary)' }}>
+          {tab}
+        </span>
+      ))}
+    </div>,
+  );
+  return (
+    <p style={{ color: 'var(--sv-color-text-muted)', fontSize: 13 }}>
+      useOverlaySecondRow found a Dialog ancestor: <strong>{String(insideOverlay)}</strong>. Switch
+      the viewport toolbar to a mobile width to see the tab strip render inside the Dialog's own
+      mobile OverlayHeader instead of here.
+    </p>
+  );
+}
+
+/**
+ * Demonstrates useOverlaySecondRow — solves the "double header" problem for
+ * overlay-shell plugins (Console, Account): a deeply-nested layout hands its
+ * tab strip up to the enclosing Dialog's mobile OverlayHeader instead of
+ * rendering a second header bar as ordinary content. Only visible at mobile
+ * widths, where Dialog's own OverlayHeader takes over; at desktop widths the
+ * secondRow prop has no visible effect (OverlayHeader is desktop-hidden).
+ */
+export const WithOverlaySecondRow: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => {
+    function Demo() {
+      const [open, setOpen] = useState(false);
+      return (
+        <>
+          <Button onClick={() => setOpen(true)}>Open dialog with tab strip</Button>
+          <Dialog open={open} onClose={() => setOpen(false)} title="Account" aria-label="Account">
+            <div style={{ padding: 24, fontFamily: 'system-ui' }}>
+              <NestedTabStrip />
+            </div>
+          </Dialog>
+        </>
+      );
+    }
+    return <Demo />;
+  },
+};

package/src/components/Dialog/Dialog.tsx

@@ -1,9 +1,57 @@
 'use client';
 
-import { type ReactNode, useEffect, useRef } from 'react';
+import { createContext, type ReactNode, useContext, useEffect, useRef, useState } from 'react';
 import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
+import { useMountTransition, usePrefersReducedMotion } from '../../motion';
+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.
+const OverlaySecondRowContext = createContext<((node: ReactNode | null) => void) | undefined>(
+  undefined,
+);
+
+/**
+ * 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.
+ *
+ * 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.
+ * Returns whether an enclosing `Dialog` actually received the content, so a
+ * caller that also renders its own inline header/tab-strip copy for the
+ * no-Dialog case can hide that copy on mobile specifically when this
+ * returned `true` (the Dialog's own header is showing it instead there).
+ *
+ * ```tsx
+ * function AccountLayout({ children }) {
+ *   const insideOverlay = useOverlaySecondRow(<nav>...tab strip...</nav>);
+ *   return <div>{children}</div>;
+ * }
+ * ```
+ */
+export function useOverlaySecondRow(node: ReactNode | null): boolean {
+  const setSecondRow = useContext(OverlaySecondRowContext);
+  useEffect(() => {
+    if (!setSecondRow) return;
+    setSecondRow(node);
+    return () => setSecondRow(null);
+  }, [setSecondRow, node]);
+  return setSecondRow !== undefined;
+}
+
 export type DialogSize = 'sm' | 'md' | 'lg' | 'full';
 
 export interface DialogProps {
@@ -33,6 +81,12 @@ const FOCUSABLE =
  * is restored to the previously-focused element on close; Tab is trapped within
  * the panel. Styling references `--sv-*` tokens only; on mobile the panel becomes
  * a full-screen sheet regardless of `size`.
+ *
+ * Animated open/close: fade + scale on desktop, slide-up on mobile (matching
+ * the "feels like a page push" framing of the mobile sheet). The `open`/
+ * `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.
  */
 export function Dialog({
   open,
@@ -44,15 +98,20 @@ export function Dialog({
 }: DialogProps) {
   const panelRef = useRef<HTMLDivElement>(null);
   const previouslyFocused = useRef<HTMLElement | null>(null);
+  const reducedMotion = usePrefersReducedMotion();
+  const { mounted, phase } = useMountTransition(open, reducedMotion ? 0 : MOTION_DURATION_MS);
+  const [secondRow, setSecondRow] = useState<ReactNode | null>(null);
 
-  // Prevent document-level scroll while open. Ref-counted so nested overlays
-  // (e.g. a confirmation dialog inside an overlay plugin) don't release the
-  // lock while a sibling is still open.
+  // Prevent document-level scroll for the whole mounted lifetime, including
+  // the exit animation — not just while `open` — so the background can't
+  // scroll while the panel is still visibly sliding/fading away. Ref-counted
+  // so nested overlays (e.g. a confirmation dialog inside an overlay plugin)
+  // don't release the lock while a sibling is still open.
   useEffect(() => {
-    if (!open) return;
+    if (!mounted) return;
     lockBodyScroll();
     return unlockBodyScroll;
-  }, [open]);
+  }, [mounted]);
 
   // Capture focus on open; restore it on close/unmount.
   useEffect(() => {
@@ -98,13 +157,14 @@ export function Dialog({
     return () => document.removeEventListener('keydown', handleKeyDown);
   }, [open, onClose]);
 
-  if (!open) return null;
+  if (!mounted) return null;
+  const isOpenPhase = phase === 'open';
 
   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.
     <div
-      className={styles.scrim}
+      className={[styles.scrim, isOpenPhase ? styles.scrimOpen : ''].filter(Boolean).join(' ')}
       role="presentation"
       onClick={(e) => {
         if (e.target === e.currentTarget) onClose();
@@ -119,20 +179,20 @@ export function Dialog({
         aria-modal="true"
         aria-label={ariaLabel ?? title}
         tabIndex={-1}
-        className={[styles.panel, styles[size]].join(' ')}
+        className={[styles.panel, styles[size], isOpenPhase ? styles.panelOpen : '']
+          .filter(Boolean)
+          .join(' ')}
       >
-        {/* Mobile: title + close button in one row (hidden on desktop via CSS). */}
-        <div className={styles.mobileBar}>
-          {title && <span className={styles.mobileBarTitle}>{title}</span>}
-          <button
-            type="button"
-            className={styles.mobileBarClose}
-            aria-label="Close"
-            onClick={onClose}
-          >
-            ×
-          </button>
-        </div>
+        {/* 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}>
           ×
@@ -140,7 +200,11 @@ export function Dialog({
         {/* 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. */}
-        <div className={styles.content}>{children}</div>
+        <div className={styles.content}>
+          <OverlaySecondRowContext.Provider value={setSecondRow}>
+            {children}
+          </OverlaySecondRowContext.Provider>
+        </div>
       </div>
     </div>
   );

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

@@ -1,10 +1,33 @@
 // @vitest-environment jsdom
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { cleanup, fireEvent, render, screen } from '@testing-library/react';
-import { Dialog } from '../Dialog';
+import { Dialog, useOverlaySecondRow } from '../Dialog';
+
+// Dialog's exit animation reads prefers-reduced-motion via matchMedia, which
+// jsdom does not implement. `matches: false` (motion enabled) exercises the
+// normal animated path; the actual reduced-motion behaviour is covered by
+// motion.ts's own tests.
+function installMatchMedia() {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches: false,
+      media: query,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}
 
 describe('Dialog', () => {
-  afterEach(cleanup);
+  beforeEach(installMatchMedia);
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
 
   it('renders nothing when closed', () => {
     render(
@@ -70,4 +93,45 @@ describe('Dialog', () => {
     );
     expect(screen.getByRole('dialog').className).toContain('sm');
   });
+
+  it('renders a descendant-supplied secondRow via useOverlaySecondRow', () => {
+    function TabStrip() {
+      useOverlaySecondRow(<nav>Tab strip</nav>);
+      return null;
+    }
+    render(
+      <Dialog open onClose={() => {}} title="Account" aria-label="Account">
+        <TabStrip />
+      </Dialog>,
+    );
+    expect(screen.getByText('Tab strip')).toBeTruthy();
+  });
+
+  it('removes the secondRow when the supplying descendant unmounts', () => {
+    function TabStrip() {
+      useOverlaySecondRow(<nav>Tab strip</nav>);
+      return null;
+    }
+    function Harness({ showTabs }: { showTabs: boolean }) {
+      return (
+        <Dialog open onClose={() => {}} title="Account" aria-label="Account">
+          {showTabs && <TabStrip />}
+        </Dialog>
+      );
+    }
+    const { rerender } = render(<Harness showTabs />);
+    expect(screen.getByText('Tab strip')).toBeTruthy();
+    rerender(<Harness showTabs={false} />);
+    expect(screen.queryByText('Tab strip')).toBeNull();
+  });
+
+  it('is a no-op when called outside a Dialog', () => {
+    function Standalone() {
+      useOverlaySecondRow(<nav>Tab strip</nav>);
+      return <span>Standalone content</span>;
+    }
+    render(<Standalone />);
+    expect(screen.getByText('Standalone content')).toBeTruthy();
+    expect(screen.queryByText('Tab strip')).toBeNull();
+  });
 });

package/src/components/DragHandleRow/DragHandleRow.module.css

@@ -5,9 +5,15 @@
   position: relative;
 }
 
-.row:not(:hover) .handle,
-.row:not(:focus-within) .handle {
-  opacity: 0;
+/* Hover-reveal only where hover genuinely exists — on touch the handle would
+   otherwise never become visible (tap-generated hover doesn't count as a
+   sustained hover state, and :not(:hover) is always true with no hover
+   capability at all), so it stays visible by default there. */
+@media (hover: hover) {
+  .row:not(:hover) .handle,
+  .row:not(:focus-within) .handle {
+    opacity: 0;
+  }
 }
 
 .handle {

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

@@ -14,6 +14,14 @@
   display: flex;
   align-items: flex-end;
   background: var(--sv-color-scrim);
+  /* Entrance/exit fade — same two-phase-mount pattern as Dialog (see motion.ts
+     and Drawer.tsx). */
+  opacity: 0;
+  transition: opacity var(--sv-motion-duration-base) var(--sv-motion-ease-out);
+}
+
+.scrimOpen {
+  opacity: 1;
 }
 
 .panel {
@@ -28,4 +36,57 @@
   /* 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. */
+  transform: translateY(100%);
+  transition: transform var(--sv-motion-duration-base) var(--sv-motion-ease-out);
+}
+
+.panelOpen {
+  transform: translateY(0);
+}
+
+/* 'half' snapHeight — a fixed height instead of the default content-sized cap
+ * above. Per the design-system's "half screen or less" convention for
+ * Drawer; content taller than this belongs in Sheet instead. */
+.panelHalf {
+  height: 50dvh;
+  max-height: 50dvh;
+}
+
+/* See Dialog.module.css's identical rule for why 0.01ms rather than 0. */
+@media (prefers-reduced-motion: reduce) {
+  .scrim,
+  .panel {
+    transition-duration: 0.01ms;
+  }
+}
+
+/* Grab handle — the sole drag-initiation region for swipe-down-to-dismiss
+ * (see Drawer.tsx's doc comment for why not the whole panel). The visual bar
+ * (::before) stays the small, established 36x4px size; only the hit area
+ * grows to a comfortable touch target. */
+.handle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: var(--sv-touch-target-min, 44px);
+  flex-shrink: 0;
+  cursor: grab;
+  /* JS-driven drag — the browser must not treat a press here as a
+     scroll/pan gesture that would fight it. */
+  touch-action: none;
+}
+
+.handle:active {
+  cursor: grabbing;
+}
+
+.handle::before {
+  content: '';
+  width: 36px;
+  height: 4px;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-border-strong);
 }