@sovereignfs/ui 0.23.0 → 0.33.1

package/src/components/Popover/Popover.stories.tsx

@@ -11,7 +11,7 @@ const meta = {
     docs: {
       description: {
         component:
-          'Floating panel anchored below a trigger. Non-modal: closes on outside click or Escape. `align` controls which trigger edge the panel aligns to.',
+          'Floating panel anchored to a trigger, below it by default. Non-modal: closes on outside click or Escape. `align` controls which trigger edge the panel aligns to; `width` accepts a fixed px number or `"trigger"` to match the trigger\'s own rendered width. Automatically flips to open upward instead of downward if the panel wouldn\'t fit below the trigger within the viewport.',
       },
     },
   },
@@ -230,3 +230,128 @@ export const LeftAligned: Story = {
     );
   },
 };
+
+/** `panelStyle` overrides the panel's own chrome (square corners here) —
+ *  an escape hatch for compact pickers where the default rounded panel
+ *  doesn't fit the content (e.g. a small colour-swatch grid). */
+export const SquareCorners: Story = {
+  render: (_args) => {
+    const [open, setOpen] = useState(false);
+    return (
+      <div style={{ padding: 40 }}>
+        <Popover
+          open={open}
+          onClose={() => setOpen(false)}
+          align="left"
+          width={160}
+          panelStyle={{ borderRadius: 0 }}
+          aria-label="Colour"
+          trigger={<Button onClick={() => setOpen((o) => !o)}>Open (square panel)</Button>}
+        >
+          <div
+            style={{
+              padding: 16,
+              fontFamily: 'var(--sv-font-family)',
+              fontSize: 'var(--sv-font-size-sm)',
+              color: 'var(--sv-color-text-muted)',
+            }}
+          >
+            No rounded corners.
+          </div>
+        </Popover>
+      </div>
+    );
+  },
+};
+
+/** `width="trigger"` matches the panel's width to the trigger's own rendered
+ *  width — for a dropdown under a full-width form field, a fixed px value
+ *  would either overflow or leave a gap depending on the field's own width. */
+export const MatchesTriggerWidth: Story = {
+  render: (_args) => {
+    const [open, setOpen] = useState(false);
+    return (
+      <div style={{ padding: 40, width: 360 }}>
+        <Popover
+          open={open}
+          onClose={() => setOpen(false)}
+          align="left"
+          width="trigger"
+          aria-label="Set due date"
+          trigger={
+            <button
+              type="button"
+              onClick={() => setOpen((o) => !o)}
+              style={{
+                width: '100%',
+                boxSizing: 'border-box',
+                textAlign: 'left',
+                padding: '10px 14px',
+                border: '1px solid var(--sv-color-border)',
+                borderRadius: 'var(--sv-radius-md)',
+                background: 'var(--sv-color-surface-raised)',
+                fontFamily: 'var(--sv-font-family)',
+                fontSize: 'var(--sv-font-size-sm)',
+                color: 'var(--sv-color-text-primary)',
+                cursor: 'pointer',
+              }}
+            >
+              No due date
+            </button>
+          }
+        >
+          <div
+            style={{
+              padding: 16,
+              fontFamily: 'var(--sv-font-family)',
+              fontSize: 'var(--sv-font-size-sm)',
+              color: 'var(--sv-color-text-muted)',
+            }}
+          >
+            Panel width matches the 360px trigger above exactly, instead of a fixed pixel value that
+            would overflow or leave a gap at other trigger widths.
+          </div>
+        </Popover>
+      </div>
+    );
+  },
+};
+
+/** Flips to open upward automatically when the panel wouldn't fit below the
+ *  trigger within the viewport — no prop needed, this is always on. */
+export const OpensUpward: Story = {
+  render: (_args) => {
+    const [open, setOpen] = useState(false);
+    return (
+      <div
+        style={{
+          height: '70vh',
+          display: 'flex',
+          alignItems: 'flex-end',
+          justifyContent: 'center',
+          paddingBottom: 24,
+        }}
+      >
+        <Popover
+          open={open}
+          onClose={() => setOpen(false)}
+          align="left"
+          aria-label="Options"
+          trigger={<Button onClick={() => setOpen((o) => !o)}>Open (near viewport bottom)</Button>}
+        >
+          <div
+            style={{
+              padding: 16,
+              fontFamily: 'var(--sv-font-family)',
+              fontSize: 'var(--sv-font-size-sm)',
+              color: 'var(--sv-color-text-muted)',
+            }}
+          >
+            This trigger sits near the bottom of the viewport, so the panel opens upward instead of
+            getting clipped below.
+          </div>
+        </Popover>
+      </div>
+    );
+  },
+};

package/src/components/Popover/Popover.tsx

@@ -1,6 +1,14 @@
 'use client';
 
-import { useEffect, useRef, type ReactElement, type ReactNode } from 'react';
+import {
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
 import styles from './Popover.module.css';
 
 export interface PopoverProps {
@@ -10,17 +18,57 @@ export interface PopoverProps {
   onClose: () => void;
   /** Which edge of the trigger the panel aligns to. Default: 'right'. */
   align?: 'left' | 'right';
-  /** Panel width in px. Default: 288. */
-  width?: number;
+  /** Panel width in px, or `'trigger'` to match the trigger element's own
+   *  rendered width exactly (e.g. a dropdown under a full-width form field,
+   *  where a fixed pixel width would either overflow or leave a gap
+   *  depending on viewport size). Default: 288. */
+  width?: number | 'trigger';
+  /**
+   * Inline style overrides for the panel, merged after `width`. Escape hatch
+   * for callers that need to override the panel's own chrome (e.g. no
+   * rounded corners for a compact swatch picker) — inline styles always win
+   * regardless of CSS module load order, unlike passing an extra className.
+   */
+  panelStyle?: CSSProperties;
   'aria-label': string;
   children: ReactNode;
 }
 
+// Matches the gap already applied via .panel's `calc(100% + var(--sv-space-2))`
+// offset — used here in plain px since layout math needs a number, not a
+// CSS custom property.
+const TRIGGER_GAP = 8;
+// Breathing room kept between the panel and the viewport edge it's closest
+// to — without this, a panel that just barely fits ends up flush against
+// the edge (e.g. touching a mobile footer nav bar with no gap at all). Kept
+// small deliberately: this subtracts directly from the space available
+// before the internal-scroll cap kicks in (see the layout effect below), so
+// a larger value here trades "more edge clearance" for "more panels that
+// would otherwise fit exactly get an unwanted scrollbar instead" — a bad
+// trade for a purely cosmetic gap.
+const VIEWPORT_MARGIN = 4;
+
 /**
- * Popover — floating panel anchored below a trigger element.
+ * Popover — floating panel anchored to a trigger element, below it by
+ * default.
  *
  * Positioning is `position: absolute` inside a `position: relative` wrapper —
- * no floating-ui dependency. Supports left/right alignment against the trigger edge.
+ * no floating-ui dependency. Supports left/right alignment against the trigger
+ * edge, and automatically opens on whichever side (above or below the
+ * trigger) has more room within the viewport.
+ *
+ * If the panel doesn't fit on *either* side as the trigger currently sits —
+ * common for a tall panel (e.g. a full calendar month) nested partway down a
+ * long scrollable mobile sheet — the trigger's scrollable ancestor is
+ * scrolled so the trigger sits at the top of it first, maximizing the room
+ * available below, then the panel opens downward against that. This mirrors
+ * how most mobile date pickers behave (scroll the page, not the picker) and
+ * avoids the panel needing its own internal scroll in the vast majority of
+ * cases. If it's still too tall even after that (a genuinely tiny viewport,
+ * or an unusually tall panel), it's capped to whatever room actually exists
+ * and scrolls internally as a last resort, rather than rendering past the
+ * edge of the viewport with no way to reach the rest of it.
+ *
  * Closes on outside click or Escape. Does not trap focus (it is non-modal).
  */
 export function Popover({
@@ -29,10 +77,88 @@ export function Popover({
   onClose,
   align = 'right',
   width = 288,
+  panelStyle,
   'aria-label': ariaLabel,
   children,
 }: PopoverProps) {
   const containerRef = useRef<HTMLDivElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const [triggerWidth, setTriggerWidth] = useState<number | null>(null);
+  // Whether the panel opens upward instead of downward. Defaults to false
+  // (today's only behavior) so nothing shifts before this can actually be
+  // measured.
+  const [openUpward, setOpenUpward] = useState(false);
+  // Caps the panel to whatever room actually exists on its chosen side, only
+  // when the panel is taller than that — null leaves it at its natural
+  // height, unconstrained, for the common case where it already fits.
+  const [maxHeight, setMaxHeight] = useState<number | null>(null);
+
+  // width="trigger": measure the trigger's own rendered width and keep the
+  // panel matching it, including live resizes (e.g. rotating the device, or
+  // the trigger's own width changing for any other reason).
+  useEffect(() => {
+    if (width !== 'trigger') return;
+    const el = containerRef.current?.firstElementChild as HTMLElement | null;
+    if (!el) return;
+    function recompute() {
+      if (el) setTriggerWidth(el.getBoundingClientRect().width);
+    }
+    recompute();
+    const ro = new ResizeObserver(recompute);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [width]);
+
+  // Collision detection: once open, measure the room available above and
+  // below the trigger within the viewport. If neither side has enough for
+  // the panel as things currently sit, scroll the trigger's scrollable
+  // ancestor so the trigger sits at the top of it (scrollIntoView with
+  // behavior: 'instant' applies synchronously, so re-measuring right after
+  // reflects the new position with no extra frame to wait for) — this is
+  // usually enough on its own to make the panel fit below. Whatever's left
+  // after that: open on whichever side has more room, and only if it still
+  // doesn't fit, cap the panel's height to that room (.panel's overflow-y:
+  // auto then lets it scroll internally as a last resort, rather than
+  // extending past the viewport edge with no way to reach the clipped part).
+  // Runs in a layout effect (before paint) so there's no visible flash of
+  // "opens one way, then snaps to the other" — measured and corrected within
+  // the same commit the browser paints.
+  useLayoutEffect(() => {
+    if (!open) {
+      setOpenUpward(false);
+      setMaxHeight(null);
+      return;
+    }
+    const container = containerRef.current;
+    const panel = panelRef.current;
+    if (!container || !panel) return;
+
+    // Arrow function expression, not a hoisted declaration — TypeScript only
+    // preserves the non-null narrowing above for a closure defined after it.
+    const measure = () => {
+      const triggerRect = container.getBoundingClientRect();
+      const panelHeight = panel.getBoundingClientRect().height;
+      return {
+        panelHeight,
+        spaceBelow: window.innerHeight - triggerRect.bottom - TRIGGER_GAP - VIEWPORT_MARGIN,
+        spaceAbove: triggerRect.top - TRIGGER_GAP - VIEWPORT_MARGIN,
+      };
+    };
+
+    let { panelHeight, spaceBelow, spaceAbove } = measure();
+    if (panelHeight > spaceBelow && panelHeight > spaceAbove) {
+      container.scrollIntoView({ block: 'start', behavior: 'instant' });
+      ({ panelHeight, spaceBelow, spaceAbove } = measure());
+    }
+
+    const upward = panelHeight > spaceBelow && spaceAbove > spaceBelow;
+    setOpenUpward(upward);
+    const available = upward ? spaceAbove : spaceBelow;
+    setMaxHeight(panelHeight > available ? Math.max(available, 0) : null);
+    // children included: content that changes the panel's height (e.g. a
+    // calendar switching months to a row with fewer/more weeks) should
+    // re-run this measurement, not just the open/close transition itself.
+  }, [open, children]);
 
   // Outside-click dismissal
   useEffect(() => {
@@ -61,11 +187,18 @@ export function Popover({
       {trigger}
       {open && (
         <div
+          ref={panelRef}
           role="dialog"
           aria-label={ariaLabel}
           aria-modal={false}
-          className={[styles.panel, styles[align]].join(' ')}
-          style={{ width }}
+          className={[styles.panel, styles[align], openUpward ? styles.upward : '']
+            .filter(Boolean)
+            .join(' ')}
+          style={{
+            width: width === 'trigger' ? (triggerWidth ?? undefined) : width,
+            maxHeight: maxHeight ?? undefined,
+            ...panelStyle,
+          }}
         >
           {children}
         </div>

package/src/components/SegmentedControl/SegmentedControl.module.css

@@ -48,6 +48,8 @@
   color: var(--sv-color-text-muted);
 }
 
-.inactive:hover {
-  color: var(--sv-color-text-primary);
+@media (hover: hover) {
+  .inactive:hover {
+    color: var(--sv-color-text-primary);
+  }
 }

package/src/components/Sheet/Sheet.module.css

@@ -0,0 +1,55 @@
+/* Sheet — fills the same rect as a plugin's content area (between the shell's
+ * sticky header and footer nav — see --sv-shell-header-height /
+ * --sv-shell-footer-height, set by the shell), sliding in from an edge
+ * instead of Dialog's centered box or Drawer's partial-height sheet-over-
+ * scrim. z-index matches Dialog/Drawer's scrim so it layers consistently
+ * with any other overlay. No scrim of its own — see the component doc
+ * comment for why. */
+
+.panel {
+  position: fixed;
+  left: 0;
+  right: 0;
+  top: var(--sv-shell-header-height, 0);
+  bottom: var(--sv-shell-footer-height, 0);
+  z-index: 100;
+  display: flex;
+  flex-direction: column;
+  background: var(--sv-color-surface);
+  outline: none;
+  transform: translateY(100%);
+  transition: transform var(--sv-motion-duration-base) var(--sv-motion-ease-out);
+}
+
+.panelOpen {
+  transform: translateY(0);
+}
+
+/* Opt-in top variant (slideFrom="top") — a short options/actions menu opened
+ * from a header button reads more naturally sliding down from that button's
+ * edge than traveling up from off-screen bottom. :not(.panelOpen) is what
+ * lets this coexist with .panelOpen above despite equal-looking single-class
+ * specificity elsewhere in this file: its (0,2,0) beats .panelOpen's (0,1,0)
+ * while closed/entering/closing, and yields to it (transform: translateY(0),
+ * same value either direction) once open. */
+.panelFromTop:not(.panelOpen) {
+  transform: translateY(-100%);
+}
+
+/* See Dialog.module.css's identical rule for why 0.01ms rather than 0. */
+@media (prefers-reduced-motion: reduce) {
+  .panel {
+    transition-duration: 0.01ms;
+  }
+}
+
+/* Always the scroll container, with or without OverlayHeader present (see
+ * Sheet.tsx). No opinionated padding here — matches Drawer's convention of
+ * leaving horizontal/top padding and safe-area-bottom clearance to the
+ * content itself, since a Sheet's content shape varies far more than a
+ * fixed-size Dialog's. */
+.content {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}

package/src/components/Sheet/Sheet.tsx

@@ -0,0 +1,151 @@
+'use client';
+
+import { type ReactNode, useEffect, useRef } from 'react';
+import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
+import { useMountTransition, usePrefersReducedMotion } from '../../motion';
+import { OverlayHeader } from '../OverlayHeader/OverlayHeader';
+import styles from './Sheet.module.css';
+
+export interface SheetProps {
+  /** Whether the sheet is shown. When false, nothing renders. */
+  open: boolean;
+  /** Called on Esc, or the built-in `OverlayHeader`'s close button. There is
+   *  no scrim to tap — a Sheet replaces the content area it fills, not a
+   *  layer floating above it (see the component doc comment). */
+  onClose: () => void;
+  /** Accessible name for the sheet. Defaults to `title` when omitted. */
+  'aria-label'?: string;
+  /** Renders a built-in `OverlayHeader` (title + close, optional back button
+   *  and trailing action). Omit when the content supplies its own header —
+   *  e.g. a form whose title doubles as an editable field. */
+  title?: string;
+  /** Forwarded to `OverlayHeader` — see its own `onBack` doc. Has no effect
+   *  without `title`. */
+  onBack?: () => void;
+  /** Forwarded to `OverlayHeader`'s trailing-action slot. Has no effect
+   *  without `title`. */
+  headerAction?: ReactNode;
+  /**
+   * Which edge the panel slides in from. Defaults to `'bottom'` (detail
+   * views, forms — content the user is reaching down into). `'top'` suits a
+   * short options/actions menu opened from a header button near the top of
+   * the screen, where sliding up from the bottom would travel past empty
+   * space before reaching content that visually belongs near the trigger.
+   */
+  slideFrom?: 'bottom' | 'top';
+  children: ReactNode;
+}
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+// Matches --sv-motion-duration-base (Sheet.module.css) — see Dialog.tsx's
+// identical constant for why this stays a plain JS number.
+const MOTION_DURATION_MS = 250;
+
+/**
+ * Sheet — a full-page overlay that replaces a plugin's content area between
+ * the shell's fixed header and footer (RFC 0013's mobile chrome stays visible
+ * and interactive around it), sliding in from an edge instead of centering
+ * like `Dialog`. Promoted from the tasks plugin's `MobileFullPageOverlay`
+ * (now the reference pattern for this component). Desktop has no equivalent
+ * presentation — a desktop layout shows the same content inline (columns,
+ * panes) instead of mounting a `Sheet` at all; this component is for the
+ * mobile case specifically.
+ *
+ * Unlike `Dialog`/`Drawer` there is no scrim: a Sheet visually *replaces* the
+ * region it covers rather than floating a layer above it, so there is no
+ * "outside" to tap-dismiss. Behaviour: Esc dismisses; focus moves into the
+ * panel on open and is restored on close; Tab is trapped within the panel;
+ * animated open/close via the same two-phase mount as `Dialog`/`Drawer`,
+ * respecting `prefers-reduced-motion`.
+ */
+export function Sheet({
+  open,
+  onClose,
+  'aria-label': ariaLabel,
+  title,
+  onBack,
+  headerAction,
+  slideFrom = 'bottom',
+  children,
+}: SheetProps) {
+  const panelRef = useRef<HTMLDivElement>(null);
+  const previouslyFocused = useRef<HTMLElement | null>(null);
+  const reducedMotion = usePrefersReducedMotion();
+  const { mounted, phase } = useMountTransition(open, reducedMotion ? 0 : MOTION_DURATION_MS);
+
+  useEffect(() => {
+    if (!mounted) return;
+    lockBodyScroll();
+    return unlockBodyScroll;
+  }, [mounted]);
+
+  useEffect(() => {
+    if (!mounted) 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();
+  }, [mounted]);
+
+  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]);
+
+  if (!mounted) return null;
+
+  return (
+    <div
+      ref={panelRef}
+      role="dialog"
+      aria-modal="true"
+      aria-label={ariaLabel ?? title}
+      tabIndex={-1}
+      className={[
+        styles.panel,
+        slideFrom === 'top' ? styles.panelFromTop : '',
+        phase === 'open' ? styles.panelOpen : '',
+      ]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      {title && (
+        <OverlayHeader title={title} onClose={onClose} onBack={onBack} action={headerAction} />
+      )}
+      {/* Content is always the scroll container — with or without a header —
+          so a header's sibling stays fixed and any content-owned internal
+          sticky positioning (e.g. a form's own sub-header) resolves against
+          this same scrolling ancestor either way. */}
+      <div className={styles.content}>{children}</div>
+    </div>
+  );
+}

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

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { Sheet } from '../Sheet';
+
+// Sheet's exit animation reads prefers-reduced-motion via matchMedia, which
+// jsdom does not implement — see Dialog.test.tsx's identical setup.
+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('Sheet', () => {
+  beforeEach(installMatchMedia);
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('renders nothing when closed', () => {
+    render(
+      <Sheet open={false} onClose={() => {}}>
+        Body
+      </Sheet>,
+    );
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+
+  it('renders the panel with its accessible name when open', () => {
+    render(
+      <Sheet open onClose={() => {}} aria-label="Task detail">
+        Body
+      </Sheet>,
+    );
+    const panel = screen.getByRole('dialog', { name: 'Task detail' });
+    expect(panel.getAttribute('aria-modal')).toBe('true');
+  });
+
+  it('falls back to title for the accessible name when aria-label is omitted', () => {
+    render(
+      <Sheet open onClose={() => {}} title="Edit list">
+        Body
+      </Sheet>,
+    );
+    expect(screen.getByRole('dialog', { name: 'Edit list' })).toBeTruthy();
+  });
+
+  it('does not render OverlayHeader when title is omitted (headerless escape hatch)', () => {
+    render(
+      <Sheet open onClose={() => {}} aria-label="Custom">
+        <button type="button">Own close button</button>
+      </Sheet>,
+    );
+    // Only the content's own button — no OverlayHeader close button.
+    expect(screen.getAllByRole('button')).toHaveLength(1);
+  });
+
+  it('renders OverlayHeader (title + close) when title is provided', () => {
+    const onClose = vi.fn();
+    render(
+      <Sheet open onClose={onClose} title="Edit list">
+        Body
+      </Sheet>,
+    );
+    expect(screen.getByText('Edit list')).toBeTruthy();
+    fireEvent.click(screen.getByRole('button', { name: 'Close' }));
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('calls onClose on Escape', () => {
+    const onClose = vi.fn();
+    render(
+      <Sheet open onClose={onClose} aria-label="Panel">
+        Body
+      </Sheet>,
+    );
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('applies the top slide-from variant class', () => {
+    render(
+      <Sheet open onClose={() => {}} aria-label="Menu" slideFrom="top">
+        Body
+      </Sheet>,
+    );
+    expect(screen.getByRole('dialog').className).toMatch(/panelFromTop/);
+  });
+});