@sovereignfs/ui 0.23.0 → 0.33.1

package/src/components/Menu/Menu.tsx

@@ -0,0 +1,137 @@
+'use client';
+
+import type { ReactElement } from 'react';
+import { useIsMobile } from '../../hooks';
+import { Drawer } from '../Drawer/Drawer';
+import { Icon, type IconName } from '../Icon/Icon';
+import { Popover } from '../Popover/Popover';
+import styles from './Menu.module.css';
+
+export interface MenuItem {
+  type?: 'item';
+  label: string;
+  onSelect: () => void;
+  icon?: IconName;
+  /** Styles the item as a destructive action (e.g. "Delete list"). */
+  destructive?: boolean;
+  disabled?: boolean;
+  /**
+   * Marks the item as one of a mutually-exclusive set (e.g. the active sort
+   * order) — renders a leading checkmark and `role="menuitemradio"` instead
+   * of `role="menuitem"`. Pass this on every item in the group, including
+   * the unchecked ones, so their labels stay aligned with the checked one's
+   * reserved checkmark gutter. Omit entirely for plain action items (e.g.
+   * "Delete list") — they render with no reserved leading space at all.
+   */
+  checked?: boolean;
+}
+
+/** A non-interactive section heading above a run of items (e.g. "Sort by"). */
+export interface MenuLabel {
+  type: 'label';
+  label: string;
+}
+
+/** A visual divider between sections. */
+export interface MenuSeparator {
+  type: 'separator';
+}
+
+export type MenuEntry = MenuItem | MenuLabel | MenuSeparator;
+
+export interface MenuProps {
+  /** The element that opens the menu — rendered as-is; the caller wires its
+   *  onClick to flip `open` (same controlled pattern as `Popover`). */
+  trigger: ReactElement;
+  open: boolean;
+  onClose: () => void;
+  items: MenuEntry[];
+  'aria-label': string;
+  /** Forwarded to `Popover` on desktop. Has no effect on mobile, where the
+   *  menu is always a full-width `Drawer`. */
+  align?: 'left' | 'right';
+}
+
+/**
+ * Menu — an adaptive action menu: `Popover` on desktop, a bottom-sheet
+ * `Drawer` on mobile. Replaces the desktop-Popover/mobile-Drawer fork that
+ * `⋯` action menus (list options, row actions) otherwise re-derive per
+ * plugin. Same list of `items` renders in both presentations — only the
+ * surrounding chrome (floating panel vs. bottom sheet) differs, matching the
+ * platform's `useIsMobile` breakpoint.
+ *
+ * `items` accepts three entry shapes: a plain action (`MenuItem`, `type`
+ * omitted or `'item'`), a non-interactive section heading (`MenuLabel`,
+ * `type: 'label'`), and a `MenuSeparator` (`type: 'separator'`) — enough to
+ * express grouped sections like "Filter" / "Sort by" above a run of
+ * destructive actions, matching how native OS menus lay out mixed
+ * action/selection groups.
+ *
+ * Selecting an item both closes the menu and calls its `onSelect` — a
+ * consumer's `onSelect` never needs to call `onClose` itself.
+ */
+export function Menu({ trigger, open, onClose, items, 'aria-label': ariaLabel, align }: MenuProps) {
+  const isMobile = useIsMobile();
+
+  const list = (
+    <ul className={styles.list} role="menu">
+      {items.map((entry, index) => {
+        // Entries are a static, order-stable list per render — nothing
+        // reorders — so an index key is safe here.
+        if (entry.type === 'separator') {
+          return <li key={index} role="separator" className={styles.separator} />;
+        }
+        if (entry.type === 'label') {
+          return (
+            <li key={index} role="presentation" className={styles.label}>
+              {entry.label}
+            </li>
+          );
+        }
+        const isCheckable = entry.checked !== undefined;
+        return (
+          <li key={index} role="none">
+            <button
+              role={isCheckable ? 'menuitemradio' : 'menuitem'}
+              aria-checked={isCheckable ? entry.checked : undefined}
+              type="button"
+              className={[styles.item, entry.destructive ? styles.itemDestructive : '']
+                .filter(Boolean)
+                .join(' ')}
+              disabled={entry.disabled}
+              onClick={() => {
+                onClose();
+                entry.onSelect();
+              }}
+            >
+              {isCheckable && (
+                <span className={styles.check} aria-hidden>
+                  {entry.checked && <Icon name="check" size="sm" aria-hidden />}
+                </span>
+              )}
+              {entry.icon && <Icon name={entry.icon} size="sm" aria-hidden />}
+              {entry.label}
+            </button>
+          </li>
+        );
+      })}
+    </ul>
+  );
+
+  if (isMobile) {
+    return (
+      <>
+        {trigger}
+        <Drawer open={open} onClose={onClose} aria-label={ariaLabel}>
+          {list}
+        </Drawer>
+      </>
+    );
+  }
+
+  return (
+    <Popover trigger={trigger} open={open} onClose={onClose} aria-label={ariaLabel} align={align}>
+      {list}
+    </Popover>
+  );
+}

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

@@ -0,0 +1,197 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { Menu, type MenuItem } from '../Menu';
+
+let mobile = false;
+function installMatchMedia() {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      // useIsMobile's query is '(max-width: ...)'; everything else (e.g.
+      // Drawer's prefers-reduced-motion check) defaults to false so the
+      // mobile-branch Drawer isn't accidentally forced into the
+      // reduced-motion path.
+      matches: query.includes('max-width') ? mobile : false,
+      media: query,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}
+
+function installPointerCapture() {
+  if (!Element.prototype.setPointerCapture) {
+    Element.prototype.setPointerCapture = () => {};
+  }
+}
+
+const items: MenuItem[] = [
+  { label: 'Rename', onSelect: vi.fn() },
+  { label: 'Delete', onSelect: vi.fn(), destructive: true },
+];
+
+describe('Menu', () => {
+  beforeEach(() => {
+    mobile = false;
+    installMatchMedia();
+    installPointerCapture();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('renders the trigger regardless of open state', () => {
+    render(
+      <Menu
+        trigger={<button type="button">Open menu</button>}
+        open={false}
+        onClose={() => {}}
+        items={items}
+        aria-label="List actions"
+      />,
+    );
+    expect(screen.getByRole('button', { name: 'Open menu' })).toBeTruthy();
+  });
+
+  it('renders as a Popover on desktop', () => {
+    render(
+      <Menu
+        trigger={<button type="button">Open menu</button>}
+        open
+        onClose={() => {}}
+        items={items}
+        aria-label="List actions"
+      />,
+    );
+    const menu = screen.getByRole('dialog', { name: 'List actions' });
+    // Popover's own aria-modal is explicitly false (non-modal floating panel).
+    expect(menu.getAttribute('aria-modal')).toBe('false');
+    expect(screen.getByRole('menuitem', { name: 'Rename' })).toBeTruthy();
+  });
+
+  it('renders as a Drawer on mobile', () => {
+    mobile = true;
+    installMatchMedia();
+    render(
+      <Menu
+        trigger={<button type="button">Open menu</button>}
+        open
+        onClose={() => {}}
+        items={items}
+        aria-label="List actions"
+      />,
+    );
+    const menu = screen.getByRole('dialog', { name: 'List actions' });
+    expect(menu.getAttribute('aria-modal')).toBe('true');
+    expect(screen.getByRole('menuitem', { name: 'Rename' })).toBeTruthy();
+  });
+
+  it('calls both onClose and the item onSelect when an item is chosen', () => {
+    const onClose = vi.fn();
+    const onSelect = vi.fn();
+    render(
+      <Menu
+        trigger={<button type="button">Open menu</button>}
+        open
+        onClose={onClose}
+        items={[{ label: 'Rename', onSelect }]}
+        aria-label="List actions"
+      />,
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Rename' }));
+    expect(onSelect).toHaveBeenCalledOnce();
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('disables an item and does not fire onSelect when clicked', () => {
+    const onSelect = vi.fn();
+    render(
+      <Menu
+        trigger={<button type="button">Open menu</button>}
+        open
+        onClose={() => {}}
+        items={[{ label: 'Archive', onSelect, disabled: true }]}
+        aria-label="List actions"
+      />,
+    );
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Archive' }));
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+
+  it('marks a destructive item distinctly from a default one', () => {
+    render(
+      <Menu
+        trigger={<button type="button">Open menu</button>}
+        open
+        onClose={() => {}}
+        items={items}
+        aria-label="List actions"
+      />,
+    );
+    const renameClass = screen.getByRole('menuitem', { name: 'Rename' }).className;
+    const deleteClass = screen.getByRole('menuitem', { name: 'Delete' }).className;
+    expect(deleteClass).not.toBe(renameClass);
+  });
+
+  it('renders section labels and separators as non-interactive entries', () => {
+    render(
+      <Menu
+        trigger={<button type="button">Open menu</button>}
+        open
+        onClose={() => {}}
+        items={[
+          { type: 'label', label: 'Sort by' },
+          { label: 'Title', onSelect: vi.fn(), checked: true },
+          { type: 'separator' },
+          { label: 'Delete list', onSelect: vi.fn(), destructive: true },
+        ]}
+        aria-label="List actions"
+      />,
+    );
+    expect(screen.getByText('Sort by').getAttribute('role')).toBe('presentation');
+    expect(screen.getByRole('separator')).toBeTruthy();
+    // Only the plain action item is a plain menuitem; the checkable one is a menuitemradio.
+    expect(screen.getAllByRole('menuitem')).toHaveLength(1);
+  });
+
+  it('renders a checkable item as menuitemradio with aria-checked', () => {
+    render(
+      <Menu
+        trigger={<button type="button">Open menu</button>}
+        open
+        onClose={() => {}}
+        items={[
+          { label: 'Manual', onSelect: vi.fn(), checked: false },
+          { label: 'Title', onSelect: vi.fn(), checked: true },
+        ]}
+        aria-label="List actions"
+      />,
+    );
+    const unchecked = screen.getByRole('menuitemradio', { name: 'Manual' });
+    const checked = screen.getByRole('menuitemradio', { name: 'Title' });
+    expect(unchecked.getAttribute('aria-checked')).toBe('false');
+    expect(checked.getAttribute('aria-checked')).toBe('true');
+  });
+
+  it('closes and selects when a checkable item is clicked', () => {
+    const onClose = vi.fn();
+    const onSelect = vi.fn();
+    render(
+      <Menu
+        trigger={<button type="button">Open menu</button>}
+        open
+        onClose={onClose}
+        items={[{ label: 'Title', onSelect, checked: false }]}
+        aria-label="List actions"
+      />,
+    );
+    fireEvent.click(screen.getByRole('menuitemradio', { name: 'Title' }));
+    expect(onSelect).toHaveBeenCalledOnce();
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+});

package/src/components/NavTabs/NavTabs.module.css

@@ -17,8 +17,10 @@
   transition: color 0.1s ease;
 }
 
-.link:hover {
-  color: var(--sv-color-text-primary);
+@media (hover: hover) {
+  .link:hover {
+    color: var(--sv-color-text-primary);
+  }
 }
 
 .link:focus-visible {

package/src/components/OverlayHeader/OverlayHeader.module.css

@@ -0,0 +1,98 @@
+/* OverlayHeader — shared fixed secondary header for Dialog's mobile mode,
+ * Sheet, and Drawer. Not itself pinned via position — the consumer renders it
+ * as a flex-shrink: 0 sibling before its own scrolling content region (see
+ * the component's own doc comment). */
+
+.header {
+  flex-shrink: 0;
+  background: var(--sv-color-surface);
+  border-bottom: 1px solid var(--sv-color-border);
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-2);
+  padding: var(--sv-space-3) var(--sv-space-4);
+}
+
+.backButton {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--sv-touch-target-min, 44px);
+  height: var(--sv-touch-target-min, 44px);
+  flex-shrink: 0;
+  /* Pull the touch-target padding back so the chevron glyph still sits close
+     to the title, matching the visual (not hit-area) spacing of .row's own
+     gap — otherwise a 44px box reads as a large empty gap before the title. */
+  margin-left: calc(-1 * (var(--sv-touch-target-min, 44px) - var(--sv-icon-size-md)) / 2);
+  margin-right: calc(
+    -1 * (var(--sv-touch-target-min, 44px) - var(--sv-icon-size-md)) / 2 + var(--sv-space-1)
+  );
+  border: none;
+  border-radius: var(--sv-radius-md);
+  background: transparent;
+  color: var(--sv-color-text-muted);
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .backButton:hover {
+    background: var(--sv-color-surface-sunken);
+    color: var(--sv-color-text-primary);
+  }
+}
+
+.backButton:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: -2px;
+}
+
+.title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--sv-font-size-xl);
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-primary);
+}
+
+.action {
+  flex-shrink: 0;
+}
+
+.closeButton {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--sv-touch-target-min, 44px);
+  height: var(--sv-touch-target-min, 44px);
+  flex-shrink: 0;
+  /* Pull the touch-target padding back so the × sits flush with the row's own
+     edge padding, same reasoning as .backButton above. */
+  margin-right: calc(-1 * (var(--sv-touch-target-min, 44px) - var(--sv-icon-size-sm)) / 2);
+  border: none;
+  border-radius: var(--sv-radius-md);
+  background: transparent;
+  color: var(--sv-color-text-muted);
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .closeButton:hover {
+    background: var(--sv-color-surface-sunken);
+    color: var(--sv-color-text-primary);
+  }
+}
+
+.closeButton:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: -2px;
+}
+
+.secondRow {
+  padding: 0 var(--sv-space-2) var(--sv-space-2);
+}

package/src/components/OverlayHeader/OverlayHeader.tsx

@@ -0,0 +1,62 @@
+import type { ReactNode } from 'react';
+import { Icon } from '../Icon/Icon';
+import styles from './OverlayHeader.module.css';
+
+export interface OverlayHeaderProps {
+  /** Overlay title, shown between the optional back button and the trailing
+   *  slots. Optional — some consumers (e.g. `Dialog`'s mobile bar) need the
+   *  row's close button present even when no title applies. */
+  title?: string;
+  /** Always renders a close button; called on click. */
+  onClose: () => void;
+  /** When provided, renders a back-chevron button before the title (for
+   *  hierarchical navigation within a single overlay — going back without
+   *  fully closing it). Omit for a flat overlay that only ever closes. */
+  onBack?: () => void;
+  /** Trailing slot next to the close button — e.g. a "Save" action. */
+  action?: ReactNode;
+  /** A second row below the title row — e.g. a tab strip. */
+  secondRow?: ReactNode;
+  className?: string;
+}
+
+/**
+ * OverlayHeader — the shared fixed secondary header for `Dialog`'s mobile
+ * mode, `Sheet`, and `Drawer`: title + close (+ optional back button /
+ * trailing action / tab-strip row). Not itself `position: sticky` or
+ * `position: fixed` — it stays visually pinned because the consuming overlay
+ * renders it as a non-scrolling flex sibling before its own scrollable
+ * content region, the same technique `Dialog`'s `.mobileBar` already used
+ * before this component existed to generalize it.
+ *
+ * Content that needs a fully custom header (e.g. an editable title, or
+ * controls that aren't a simple title/back/action shape) should not use this
+ * component — render its own header row instead; `Sheet`'s `title` prop is
+ * optional specifically to leave that escape hatch open.
+ */
+export function OverlayHeader({
+  title,
+  onClose,
+  onBack,
+  action,
+  secondRow,
+  className,
+}: OverlayHeaderProps) {
+  return (
+    <div className={[styles.header, className].filter(Boolean).join(' ')}>
+      <div className={styles.row}>
+        {onBack && (
+          <button type="button" className={styles.backButton} aria-label="Back" onClick={onBack}>
+            <Icon name="chevron-left" size="md" aria-hidden />
+          </button>
+        )}
+        <span className={styles.title}>{title}</span>
+        {action && <div className={styles.action}>{action}</div>}
+        <button type="button" className={styles.closeButton} aria-label="Close" onClick={onClose}>
+          <Icon name="x" size="sm" aria-hidden />
+        </button>
+      </div>
+      {secondRow && <div className={styles.secondRow}>{secondRow}</div>}
+    </div>
+  );
+}

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

@@ -0,0 +1,51 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { OverlayHeader } from '../OverlayHeader';
+
+describe('OverlayHeader', () => {
+  afterEach(cleanup);
+
+  it('renders the title and calls onClose on the close button', () => {
+    const onClose = vi.fn();
+    render(<OverlayHeader title="Account" onClose={onClose} />);
+    expect(screen.getByText('Account')).toBeTruthy();
+    fireEvent.click(screen.getByRole('button', { name: 'Close' }));
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('does not render a back button when onBack is omitted', () => {
+    render(<OverlayHeader title="Account" onClose={() => {}} />);
+    expect(screen.queryByRole('button', { name: 'Back' })).toBeNull();
+  });
+
+  it('renders and wires a back button when onBack is provided', () => {
+    const onBack = vi.fn();
+    render(<OverlayHeader title="Account" onClose={() => {}} onBack={onBack} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Back' }));
+    expect(onBack).toHaveBeenCalledOnce();
+  });
+
+  it('renders the trailing action slot', () => {
+    render(
+      <OverlayHeader
+        title="Edit list"
+        onClose={() => {}}
+        action={<button type="button">Save</button>}
+      />,
+    );
+    expect(screen.getByRole('button', { name: 'Save' })).toBeTruthy();
+  });
+
+  it('renders just the close button when title is omitted', () => {
+    const onClose = vi.fn();
+    render(<OverlayHeader onClose={onClose} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Close' }));
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('renders the second row', () => {
+    render(<OverlayHeader title="Account" onClose={() => {}} secondRow={<nav>Tab strip</nav>} />);
+    expect(screen.getByText('Tab strip')).toBeTruthy();
+  });
+});

package/src/components/Popover/Popover.module.css

@@ -11,7 +11,16 @@
   border: 1px solid var(--sv-color-border);
   border-radius: var(--sv-radius-2xl);
   box-shadow: var(--sv-shadow-popover);
-  overflow: hidden;
+  /* auto, not hidden: Popover.tsx applies an inline max-height only when the
+     panel is taller than the room actually available on whichever side it
+     opens (e.g. a tall calendar on a short mobile viewport, where neither
+     above nor below has enough space for the whole thing) — auto lets that
+     capped case scroll internally instead of silently clipping content with
+     no way to reach it. When no max-height is applied (the common case, panel
+     already fits), auto behaves identically to hidden — nothing to scroll,
+     content still clips at the rounded corners exactly as before. */
+  overflow-x: hidden;
+  overflow-y: auto;
   /* Slide in from slightly above */
   animation: sv-popover-in 0.12s ease;
 }
@@ -42,3 +51,24 @@
 .left {
   left: 0;
 }
+
+/* Collision flip: opens above the trigger instead of below, when the panel
+   wouldn't fit within the viewport underneath it (see Popover.tsx's
+   layout-effect measurement). Same slide-in treatment, mirrored to slide up
+   from slightly below instead of down from slightly above. */
+.upward {
+  top: auto;
+  bottom: calc(100% + var(--sv-space-2));
+  animation-name: sv-popover-in-upward;
+}
+
+@keyframes sv-popover-in-upward {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}