@sovereignfs/ui 0.45.0 → 0.83.1

package/src/components/Drawer/Drawer.stories.tsx

@@ -75,6 +75,50 @@ export const Closed: Story = {
   ),
 };
 
+function DrawerWithTitleDemo() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open drawer</Button>
+      <Drawer open={open} onClose={() => setOpen(false)} title="Apps">
+        <ul style={{ listStyle: 'none', margin: 0, padding: '8px 0' }}>
+          {(['house', 'grid-2x2', 'settings', 'user'] as const).map((icon) => (
+            <li key={icon}>
+              <button
+                onClick={() => setOpen(false)}
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 12,
+                  width: '100%',
+                  padding: '12px 20px',
+                  background: 'none',
+                  border: 'none',
+                  cursor: 'pointer',
+                  fontSize: 15,
+                  color: 'var(--sv-color-text-primary)',
+                  fontFamily: 'system-ui',
+                }}
+              >
+                <Icon name={icon} size="md" aria-hidden />
+                {icon.replace(/-/g, ' ')}
+              </button>
+            </li>
+          ))}
+        </ul>
+      </Drawer>
+    </>
+  );
+}
+
+/** Opt-in `title` prop renders a built-in `OverlayHeader` (title + close)
+ * below the grab handle — hidden by default (see the `Default` story), for
+ * consumers that want one instead of building their own header markup. */
+export const WithTitle: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => <DrawerWithTitleDemo />,
+};
+
 /** Play function opens the drawer and asserts its list items are visible. */
 export const OpenViaInteraction: Story = {
   args: { open: false, onClose: () => {}, children: null },

package/src/components/Drawer/Drawer.tsx

@@ -1,15 +1,16 @@
 'use client';
 
-import { type PointerEvent as ReactPointerEvent, type ReactNode, useEffect, useRef } from 'react';
-import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
+import { type PointerEvent as ReactPointerEvent, type ReactNode, useRef } from 'react';
 import { useMountTransition, usePrefersReducedMotion } from '../../motion';
+import {
+  OVERLAY_MOTION_DURATION_MS,
+  useOverlayFocusCapture,
+  useOverlayKeyboardTrap,
+  useOverlayScrollLock,
+} from '../../overlay-shell';
+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;
@@ -22,12 +23,15 @@ export interface DrawerProps {
    *  "half screen or less" convention for Drawer, this is the only other
    *  supported size; taller content should use `Sheet` instead. */
   snapHeight?: 'content' | 'half';
+  /** Renders a built-in `OverlayHeader` (title + close) below the grab
+   *  handle. Omit when the content supplies its own header, or none is
+   *  needed at all — e.g. the mobile shell's Apps drawer, whose grab handle
+   *  and swipe-down/scrim-tap dismissal are enough on their own. Mirrors
+   *  `Sheet`'s identical `title` prop. */
+  title?: string;
   children: ReactNode;
 }
 
-const FOCUSABLE =
-  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
-
 // Downward drag distance (px) past which releasing dismisses the drawer
 // instead of snapping back open. Distance-only, no velocity tracking — matches
 // the swipe-to-reveal gesture already established in consuming plugins (see
@@ -61,67 +65,23 @@ export function Drawer({
   onClose,
   'aria-label': ariaLabel,
   snapHeight = 'content',
+  title,
   children,
 }: DrawerProps) {
   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 { 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.
   const dragStartY = useRef<number | null>(null);
 
-  // Locked for the whole mounted lifetime (including the exit animation), not
-  // just while `open` — see Dialog.tsx's identical comment for why.
-  useEffect(() => {
-    if (!mounted) return;
-    lockBodyScroll();
-    return unlockBodyScroll;
-  }, [mounted]);
-
-  useEffect(() => {
-    if (!open) return;
-    previouslyFocused.current = document.activeElement as HTMLElement | null;
-    const panel = panelRef.current;
-    const first = panel?.querySelector<HTMLElement>(FOCUSABLE);
-    (first ?? panel)?.focus();
-    return () => previouslyFocused.current?.focus();
-  }, [open]);
-
-  // Keyboard handling: Escape closes, Tab cycles within the panel (focus trap).
-  // Attached at document level so no keyboard listener is needed on the dialog
-  // div itself (which would trigger jsx-a11y/no-noninteractive-element-interactions).
-  useEffect(() => {
-    if (!open) return;
-    function handleKeyDown(e: KeyboardEvent) {
-      if (e.key === 'Escape') {
-        e.stopPropagation();
-        onClose();
-        return;
-      }
-      if (e.key !== 'Tab') return;
-      const panel = panelRef.current;
-      if (!panel) return;
-      const focusable = [...panel.querySelectorAll<HTMLElement>(FOCUSABLE)];
-      const first = focusable[0];
-      const last = focusable.at(-1);
-      if (!first || !last) {
-        e.preventDefault();
-        return;
-      }
-      const active = document.activeElement;
-      if (e.shiftKey && active === first) {
-        e.preventDefault();
-        last.focus();
-      } else if (!e.shiftKey && active === last) {
-        e.preventDefault();
-        first.focus();
-      }
-    }
-    document.addEventListener('keydown', handleKeyDown);
-    return () => document.removeEventListener('keydown', handleKeyDown);
-  }, [open, onClose]);
+  useOverlayScrollLock(mounted);
+  useOverlayFocusCapture(panelRef, open);
+  useOverlayKeyboardTrap(panelRef, open, onClose);
 
   // Swipe-down-to-dismiss, initiated only from the grab handle (see the
   // component doc comment for why not the whole panel). Drags the panel
@@ -171,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}
@@ -207,7 +167,8 @@ export function Drawer({
           onPointerUp={(e) => releaseDrag(e, true)}
           onPointerCancel={(e) => releaseDrag(e, false)}
         />
-        {children}
+        {title && <OverlayHeader title={title} onClose={onClose} />}
+        <div className={styles.body}>{children}</div>
       </div>
     </div>
   );

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

@@ -63,16 +63,24 @@ describe('Drawer', () => {
     expect(panel.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(
-      <Drawer open onClose={onClose}>
-        Body
+      <Drawer open onClose={onClose} aria-label="Panel">
+        <button>Focus me</button>
       </Drawer>,
     );
-    // Keyboard handler is registered on document (not the drawer 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();
   });
 
@@ -110,6 +118,47 @@ describe('Drawer', () => {
     expect(screen.getByRole('dialog').className).not.toMatch(/panelHalf/);
   });
 
+  it('does not render OverlayHeader when title is omitted (hidden by default)', () => {
+    render(
+      <Drawer open onClose={() => {}} aria-label="Nav">
+        <button type="button">Own action</button>
+      </Drawer>,
+    );
+    // Only the content's own button — no OverlayHeader close button.
+    expect(screen.getAllByRole('button')).toHaveLength(1);
+  });
+
+  it('renders children inside a scrollable body, separate from the grab handle', () => {
+    // Regression test: the panel used to be the sole scroll container
+    // (overflow-y: auto on .panel itself), so a tall drawer scrolled the
+    // grab handle out of view along with the content. The handle must stay
+    // a sibling of the scrollable region, not a descendant of it.
+    render(
+      <Drawer open onClose={() => {}} aria-label="Nav">
+        <button type="button">Own action</button>
+      </Drawer>,
+    );
+    const panel = screen.getByRole('dialog');
+    const handle = panel.firstElementChild as HTMLElement;
+    const button = screen.getByRole('button', { name: 'Own action' });
+    const body = button.parentElement as HTMLElement;
+    expect(body).not.toBe(panel);
+    expect(body.contains(handle)).toBe(false);
+    expect(panel.contains(body)).toBe(true);
+  });
+
+  it('renders OverlayHeader (title + close) when title is provided', () => {
+    const onClose = vi.fn();
+    render(
+      <Drawer open onClose={onClose} aria-label="Nav" title="Apps">
+        Body
+      </Drawer>,
+    );
+    expect(screen.getByText('Apps')).toBeTruthy();
+    fireEvent.click(screen.getByRole('button', { name: 'Close' }));
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
   describe('swipe-down-to-dismiss (grab handle)', () => {
     // The handle is the panel's first child, aria-hidden and unlabeled —
     // same "select via DOM position" approach the scrim-click test above

package/src/components/GripIcon/GripIcon.tsx

@@ -0,0 +1,27 @@
+export interface GripIconProps {
+  size?: number;
+  className?: string;
+}
+
+/** Six-dot drag-handle affordance. No baked-in pointer-events or color —
+ *  a consumer that needs `pointer-events: none` (e.g. a button wrapping it)
+ *  or a specific color passes those via `className`/`currentColor`. */
+export function GripIcon({ size = 14, className }: GripIconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 14 14"
+      fill="none"
+      aria-hidden="true"
+      className={className}
+    >
+      {/* 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/Header/Header.module.css

@@ -0,0 +1,62 @@
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  min-height: 48px;
+  padding: var(--sv-space-2) var(--sv-space-4);
+  border-bottom: var(--sv-border-width-hairline) solid var(--sv-color-border);
+  background-color: var(--sv-color-surface);
+}
+
+.left {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-2);
+  min-width: 0;
+}
+
+.right {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-1);
+  flex-shrink: 0;
+}
+
+.brandBadge {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 28px;
+  height: 28px;
+  border-radius: var(--sv-radius-md);
+  background-color: var(--sv-color-accent);
+  color: var(--sv-color-text-on-accent);
+  font-size: var(--sv-font-size-xs);
+  font-weight: var(--sv-font-weight-semibold);
+  text-decoration: none;
+  overflow: hidden;
+}
+
+.brandLogoImg {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.plugin {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-1);
+  min-width: 0;
+  text-decoration: none;
+  color: var(--sv-color-text-primary);
+}
+
+.pluginName {
+  font-size: var(--sv-font-size-md);
+  font-weight: var(--sv-font-weight-semibold);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}