@sovereignfs/ui 0.23.0 → 0.33.0

package/src/components/Drawer/Drawer.tsx

@@ -1,41 +1,84 @@
 'use client';
 
-import { type ReactNode, useEffect, useRef } from 'react';
+import { type PointerEvent as ReactPointerEvent, type ReactNode, useEffect, useRef } from 'react';
 import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
+import { useMountTransition, usePrefersReducedMotion } from '../../motion';
 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;
-  /** Called on Esc or scrim click. */
+  /** Called on Esc, scrim click, or a swipe-down past the dismiss threshold. */
   onClose: () => void;
   /** Accessible name for the drawer panel (sets `aria-label`). */
   'aria-label'?: string;
+  /** `'content'` (default) sizes to content, capped at 80dvh. `'half'` fixes
+   *  the panel to 50dvh regardless of content — per the design-system's
+   *  "half screen or less" convention for Drawer, this is the only other
+   *  supported size; taller content should use `Sheet` instead. */
+  snapHeight?: 'content' | 'half';
   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
+// the mobile design-system plan), not a separate technique invented here.
+const SWIPE_DISMISS_THRESHOLD_PX = 100;
+
 /**
  * Drawer — a dismissable bottom-sheet panel. Used by the mobile shell for
  * plugin navigation; also available to plugins for any bottom-up surface.
  *
- * Behaviour: Esc and scrim-click dismiss; focus moves to the first focusable
- * element on open and is restored on close; Tab is trapped within the panel.
- * The panel respects `env(safe-area-inset-bottom)` so it clears the home
- * indicator in standalone/fullscreen mode. Shares dismissal conventions and
- * tokens (`--sv-color-scrim`, `--sv-shadow-overlay`) with `Dialog`.
+ * Behaviour: Esc, scrim click, or dragging the grab handle down past
+ * `SWIPE_DISMISS_THRESHOLD_PX` all dismiss; focus moves to the first
+ * focusable element on open and is restored on close; Tab is trapped within
+ * the panel. The panel respects `env(safe-area-inset-bottom)` so it clears
+ * the home indicator in standalone/fullscreen mode. Shares dismissal
+ * conventions and tokens (`--sv-color-scrim`, `--sv-shadow-overlay`) with
+ * `Dialog`.
+ *
+ * Animated open/close: slides up from the bottom, scrim fades. The `open`/
+ * `onClose` API is unchanged — closing stays mounted internally for the exit
+ * transition before actually unmounting; `prefers-reduced-motion: reduce`
+ * collapses it to near-instant.
+ *
+ * The grab handle is the *only* drag-initiation region (not the whole panel)
+ * — dragging from body content would fight that content's own internal
+ * scroll, the same reasoning behind the tasks plugin's edge-zone-only
+ * swipe-to-reveal technique.
  */
-export function Drawer({ open, onClose, 'aria-label': ariaLabel, children }: DrawerProps) {
+export function Drawer({
+  open,
+  onClose,
+  'aria-label': ariaLabel,
+  snapHeight = 'content',
+  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);
+  // 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 (!open) return;
+    if (!mounted) return;
     lockBodyScroll();
     return unlockBodyScroll;
-  }, [open]);
+  }, [mounted]);
 
   useEffect(() => {
     if (!open) return;
@@ -80,13 +123,56 @@ export function Drawer({ open, onClose, 'aria-label': ariaLabel, children }: Dra
     return () => document.removeEventListener('keydown', handleKeyDown);
   }, [open, onClose]);
 
-  if (!open) return null;
+  // Swipe-down-to-dismiss, initiated only from the grab handle (see the
+  // component doc comment for why not the whole panel). Drags the panel
+  // directly via inline style while active (transition: none, so it tracks
+  // the finger 1:1 with no lag) and lets go on release: clearing the inline
+  // transform in the same commit that re-enables the CSS transition makes
+  // the panel animate from wherever the drag ended to its resolved position
+  // — open (snap back) or closed (the exit transition, same as a
+  // programmatic close) — rather than jump-cutting there. Same technique as
+  // the tasks plugin's row swipe-to-reveal.
+  function handleHandlePointerDown(e: ReactPointerEvent) {
+    e.currentTarget.setPointerCapture(e.pointerId);
+    dragStartY.current = e.clientY;
+  }
+
+  function handleHandlePointerMove(e: ReactPointerEvent) {
+    const startY = dragStartY.current;
+    if (startY === null) return;
+    const dy = Math.max(0, e.clientY - startY); // upward drag has no effect — already fully open
+    const panel = panelRef.current;
+    if (!panel) return;
+    panel.style.transition = 'none';
+    panel.style.transform = `translateY(${dy}px)`;
+  }
+
+  // Releases the drag and resolves it to open (snap back) or closed, based on
+  // distance. Shared by pointerup (a completed gesture) and pointercancel
+  // (the browser took the gesture away, e.g. for a system gesture) — cancel
+  // always snaps back rather than honoring the distance, since it wasn't a
+  // deliberate release.
+  function releaseDrag(e: ReactPointerEvent, honorDistance: boolean) {
+    const startY = dragStartY.current;
+    dragStartY.current = null;
+    if (startY === null) return;
+    const dy = Math.max(0, e.clientY - startY);
+    const panel = panelRef.current;
+    if (panel) {
+      panel.style.transform = '';
+      panel.style.transition = '';
+    }
+    if (honorDistance && dy > SWIPE_DISMISS_THRESHOLD_PX) onClose();
+  }
+
+  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();
@@ -101,8 +187,26 @@ export function Drawer({ open, onClose, 'aria-label': ariaLabel, children }: Dra
         aria-modal="true"
         aria-label={ariaLabel}
         tabIndex={-1}
-        className={styles.panel}
+        className={[
+          styles.panel,
+          snapHeight === 'half' ? styles.panelHalf : '',
+          isOpenPhase ? styles.panelOpen : '',
+        ]
+          .filter(Boolean)
+          .join(' ')}
       >
+        {/* The only drag-initiation region for swipe-down-to-dismiss — see the
+            component doc comment for why not the whole panel. Decorative +
+            functional, so no aria-label of its own; Esc and the scrim remain
+            the accessible dismiss paths. */}
+        <div
+          className={styles.handle}
+          aria-hidden="true"
+          onPointerDown={handleHandlePointerDown}
+          onPointerMove={handleHandlePointerMove}
+          onPointerUp={(e) => releaseDrag(e, true)}
+          onPointerCancel={(e) => releaseDrag(e, false)}
+        />
         {children}
       </div>
     </div>

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

@@ -1,10 +1,48 @@
 // @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 { Drawer } from '../Drawer';
 
+// Drawer'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(),
+    })),
+  );
+}
+
+// jsdom does not implement Element.setPointerCapture/releasePointerCapture
+// (another documented gap, alongside matchMedia and HTMLDialogElement) — the
+// grab handle's pointerdown handler calls setPointerCapture unconditionally.
+function installPointerCapture() {
+  if (!Element.prototype.setPointerCapture) {
+    Element.prototype.setPointerCapture = () => {};
+  }
+  if (!Element.prototype.releasePointerCapture) {
+    Element.prototype.releasePointerCapture = () => {};
+  }
+}
+
 describe('Drawer', () => {
-  afterEach(cleanup);
+  beforeEach(() => {
+    installMatchMedia();
+    installPointerCapture();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
 
   it('renders nothing when closed', () => {
     render(
@@ -53,4 +91,87 @@ describe('Drawer', () => {
     fireEvent.click(scrim);
     expect(onClose).toHaveBeenCalledOnce();
   });
+
+  it('applies the half snapHeight class', () => {
+    render(
+      <Drawer open onClose={() => {}} aria-label="Nav" snapHeight="half">
+        Body
+      </Drawer>,
+    );
+    expect(screen.getByRole('dialog').className).toMatch(/panelHalf/);
+  });
+
+  it('does not apply the half snapHeight class by default (content-sized)', () => {
+    render(
+      <Drawer open onClose={() => {}} aria-label="Nav">
+        Body
+      </Drawer>,
+    );
+    expect(screen.getByRole('dialog').className).not.toMatch(/panelHalf/);
+  });
+
+  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
+    // already uses for a similarly unlabeled element.
+    function getHandle() {
+      return screen.getByRole('dialog').firstElementChild as HTMLElement;
+    }
+
+    it('dismisses when dragged past the threshold', () => {
+      const onClose = vi.fn();
+      render(
+        <Drawer open onClose={onClose} aria-label="Nav">
+          Body
+        </Drawer>,
+      );
+      const handle = getHandle();
+      fireEvent.pointerDown(handle, { clientY: 0 });
+      fireEvent.pointerMove(handle, { clientY: 150 });
+      fireEvent.pointerUp(handle, { clientY: 150 }); // 150px > 100px threshold
+      expect(onClose).toHaveBeenCalledOnce();
+    });
+
+    it('snaps back without dismissing when released under the threshold', () => {
+      const onClose = vi.fn();
+      render(
+        <Drawer open onClose={onClose} aria-label="Nav">
+          Body
+        </Drawer>,
+      );
+      const handle = getHandle();
+      fireEvent.pointerDown(handle, { clientY: 0 });
+      fireEvent.pointerMove(handle, { clientY: 40 });
+      fireEvent.pointerUp(handle, { clientY: 40 }); // 40px < 100px threshold
+      expect(onClose).not.toHaveBeenCalled();
+    });
+
+    it('snaps back without dismissing on pointercancel, regardless of distance', () => {
+      const onClose = vi.fn();
+      render(
+        <Drawer open onClose={onClose} aria-label="Nav">
+          Body
+        </Drawer>,
+      );
+      const handle = getHandle();
+      fireEvent.pointerDown(handle, { clientY: 0 });
+      fireEvent.pointerMove(handle, { clientY: 200 }); // well past the threshold
+      fireEvent.pointerCancel(handle, { clientY: 200 });
+      expect(onClose).not.toHaveBeenCalled();
+    });
+
+    it('ignores upward drags (already fully open)', () => {
+      const onClose = vi.fn();
+      render(
+        <Drawer open onClose={onClose} aria-label="Nav">
+          Body
+        </Drawer>,
+      );
+      const handle = getHandle();
+      fireEvent.pointerDown(handle, { clientY: 100 });
+      fireEvent.pointerMove(handle, { clientY: 0 }); // upward
+      fireEvent.pointerUp(handle, { clientY: 0 });
+      expect(onClose).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/components/Icon/Icon.module.css

@@ -6,6 +6,11 @@
   /* Color follows the surrounding text via currentColor — no token needed. */
 }
 
+.xs {
+  width: var(--sv-icon-size-xs);
+  height: var(--sv-icon-size-xs);
+}
+
 .sm {
   width: var(--sv-icon-size-sm);
   height: var(--sv-icon-size-sm);

package/src/components/Icon/Icon.stories.tsx

@@ -18,7 +18,7 @@ const meta = {
   },
   argTypes: {
     name: { control: 'select', options: ALL_NAMES },
-    size: { control: 'select', options: ['sm', 'md', 'lg'] },
+    size: { control: 'select', options: ['xs', 'sm', 'md', 'lg'] },
   },
 } satisfies Meta<typeof Icon>;
 
@@ -35,17 +35,18 @@ export const Meaningful: Story = {
   args: { name: 'settings', size: 'md', 'aria-label': 'Open settings' },
 };
 
+export const SizeExtraSmall: Story = { args: { name: 'bell', size: 'xs', 'aria-hidden': true } };
 export const SizeSmall: Story = { args: { name: 'bell', size: 'sm', 'aria-hidden': true } };
 export const SizeMedium: Story = { args: { name: 'bell', size: 'md', 'aria-hidden': true } };
 export const SizeLarge: Story = { args: { name: 'bell', size: 'lg', 'aria-hidden': true } };
 
-/** Full icon grid — every name across all three sizes. */
+/** Full icon grid — every name across all four sizes. */
 export const AllIcons: Story = {
   parameters: { layout: 'padded' },
   args: { name: 'house', 'aria-hidden': true },
   render: (_args) => (
     <div>
-      {(['sm', 'md', 'lg'] as const).map((sz) => (
+      {(['xs', 'sm', 'md', 'lg'] as const).map((sz) => (
         <section key={sz} style={{ marginBottom: 32 }}>
           <h3
             style={{

package/src/components/Icon/Icon.tsx

@@ -12,7 +12,7 @@ export interface IconProps {
   /** Name of the icon from the curated Sovereign set. */
   name: IconName;
   /** Visual size. Defaults to `"md"` (20 px). */
-  size?: 'sm' | 'md' | 'lg';
+  size?: 'xs' | 'sm' | 'md' | 'lg';
   /** Additional CSS class applied to the SVG element. */
   className?: string;
 }

package/src/components/Icon/icons/calendar.tsx

@@ -0,0 +1,23 @@
+// Generated by scripts/generate-icons.ts — do not edit.
+// Source: Lucide (https://lucide.dev) — ISC license, see packages/ui/NOTICE.
+import type { SVGProps } from 'react';
+
+export function CalendarIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...props}
+    >
+      <path d="M8 2v4" />
+      <path d="M16 2v4" />
+      <rect width="18" height="18" x="3" y="4" rx="2" />
+      <path d="M3 10h18" />
+    </svg>
+  );
+}

package/src/components/Icon/icons/ellipsis-vertical.tsx

@@ -0,0 +1,22 @@
+// Generated by scripts/generate-icons.ts — do not edit.
+// Source: Lucide (https://lucide.dev) — ISC license, see packages/ui/NOTICE.
+import type { SVGProps } from 'react';
+
+export function EllipsisVerticalIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...props}
+    >
+      <circle cx="12" cy="12" r="1" />
+      <circle cx="12" cy="5" r="1" />
+      <circle cx="12" cy="19" r="1" />
+    </svg>
+  );
+}

package/src/components/Icon/icons/index.ts

@@ -26,8 +26,9 @@ import { PackageIcon } from './package';
 import { Grid2x2Icon } from './grid-2x2';
 import { InfoIcon } from './info';
 import { AlertTriangleIcon } from './alert-triangle';
+import { CalendarIcon } from './calendar';
 import { SlidersHorizontalIcon } from './sliders-horizontal';
-import { TerminalIcon } from './terminal';
+import { EllipsisVerticalIcon } from './ellipsis-vertical';
 
 export type IconName =
   | 'house'
@@ -56,8 +57,9 @@ export type IconName =
   | 'grid-2x2'
   | 'info'
   | 'alert-triangle'
+  | 'calendar'
   | 'sliders-horizontal'
-  | 'terminal';
+  | 'ellipsis-vertical';
 
 export type IconComponent = (props: SVGProps<SVGSVGElement>) => ReactElement;
 
@@ -88,8 +90,9 @@ export const ICONS: Record<IconName, IconComponent> = {
   'grid-2x2': Grid2x2Icon,
   info: InfoIcon,
   'alert-triangle': AlertTriangleIcon,
+  calendar: CalendarIcon,
   'sliders-horizontal': SlidersHorizontalIcon,
-  terminal: TerminalIcon,
+  'ellipsis-vertical': EllipsisVerticalIcon,
 };
 
 export { HouseIcon } from './house';
@@ -118,5 +121,6 @@ export { PackageIcon } from './package';
 export { Grid2x2Icon } from './grid-2x2';
 export { InfoIcon } from './info';
 export { AlertTriangleIcon } from './alert-triangle';
+export { CalendarIcon } from './calendar';
 export { SlidersHorizontalIcon } from './sliders-horizontal';
-export { TerminalIcon } from './terminal';
+export { EllipsisVerticalIcon } from './ellipsis-vertical';

package/src/components/Icon/icons/sliders-horizontal.tsx

@@ -14,15 +14,15 @@ export function SlidersHorizontalIcon(props: SVGProps<SVGSVGElement>) {
       strokeLinejoin="round"
       {...props}
     >
-      <line x1="21" x2="14" y1="4" y2="4" />
-      <line x1="10" x2="3" y1="4" y2="4" />
-      <line x1="21" x2="12" y1="12" y2="12" />
-      <line x1="8" x2="3" y1="12" y2="12" />
-      <line x1="21" x2="16" y1="20" y2="20" />
-      <line x1="12" x2="3" y1="20" y2="20" />
-      <line x1="14" x2="14" y1="2" y2="6" />
-      <line x1="8" x2="8" y1="10" y2="14" />
-      <line x1="16" x2="16" y1="18" y2="22" />
+      <path d="M10 5H3" />
+      <path d="M12 19H3" />
+      <path d="M14 3v4" />
+      <path d="M16 17v4" />
+      <path d="M21 12h-9" />
+      <path d="M21 19h-5" />
+      <path d="M21 5h-7" />
+      <path d="M8 10v4" />
+      <path d="M8 12H3" />
     </svg>
   );
 }

package/src/components/Menu/Menu.module.css

@@ -0,0 +1,82 @@
+/* Menu — the item list shared by both presentations (Popover panel on
+ * desktop, Drawer panel on mobile); the presentational chrome around it is
+ * entirely owned by those two components, not duplicated here. */
+
+.list {
+  list-style: none;
+  margin: 0;
+  padding: var(--sv-space-1);
+  display: flex;
+  flex-direction: column;
+}
+
+.item {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-2);
+  width: 100%;
+  /* Min touch target (WCAG 2.5.5 / Apple HIG) — this menu renders as a
+     Drawer sheet on mobile, so every item must be comfortably tappable. */
+  min-height: var(--sv-touch-target-min, 44px);
+  padding: var(--sv-space-2) var(--sv-space-3);
+  border: none;
+  border-radius: var(--sv-radius-sm);
+  background: transparent;
+  color: var(--sv-color-text-primary);
+  font: inherit;
+  font-size: var(--sv-font-size-sm);
+  text-align: left;
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .item:hover:not(:disabled) {
+    background: var(--sv-color-surface-sunken);
+  }
+}
+
+.item:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: -2px;
+}
+
+.item:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.itemDestructive {
+  color: var(--sv-color-error-text);
+}
+
+@media (hover: hover) {
+  .itemDestructive:hover:not(:disabled) {
+    background: var(--sv-color-error-surface);
+  }
+}
+
+/* Reserved checkmark gutter for a checkable item — sized so unchecked
+   siblings in the same group still align with the checked one's icon. */
+.check {
+  display: inline-flex;
+  flex-shrink: 0;
+  width: var(--sv-icon-size-sm);
+  height: var(--sv-icon-size-sm);
+  align-items: center;
+  justify-content: center;
+}
+
+.label {
+  padding: var(--sv-space-2) var(--sv-space-3) var(--sv-space-1);
+  font-size: var(--sv-font-size-label);
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.separator {
+  height: 1px;
+  margin: var(--sv-space-1) var(--sv-space-2);
+  background: var(--sv-color-border);
+}