@sovereignfs/ui 0.21.3 → 0.33.0

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);
+  }
+}

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/Select/Select.module.css

@@ -33,6 +33,15 @@
   border-radius: var(--sv-radius-sm);
 }
 
+/* iOS Safari zooms the page when a <select> under 16px receives focus, exactly
+   as it does for text inputs. Lift the default size to >=16px on touch devices;
+   the compact `.sm` variant is for dense desktop tables and is left untouched. */
+@media (pointer: coarse) {
+  .select {
+    font-size: var(--sv-font-size-md);
+  }
+}
+
 .select:focus-visible {
   outline: none;
   border-color: var(--sv-color-accent);

package/src/components/Select/Select.tsx

@@ -12,13 +12,21 @@ export type SelectProps = Omit<SelectHTMLAttributes<HTMLSelectElement>, 'size'>
  * Uses the native picker on mobile — no custom dropdown, maximum a11y coverage.
  *
  * RSC-safe: presentational, no hooks, forwards all native select props.
+ *
+ * `className` sizes the outer box (the wrapper), not the `<select>` itself —
+ * the chevron is absolutely positioned against the wrapper, so a className
+ * that constrains only the `<select>` (e.g. `max-width`) shrinks the select
+ * while the wrapper (and thus the chevron) stays full width, leaving the
+ * chevron stranded past the visible box.
  */
 export function Select({ className, size = 'md', children, ...rest }: SelectProps) {
   return (
     <div
-      className={[styles.wrapper, size === 'sm' ? styles.sm : undefined].filter(Boolean).join(' ')}
+      className={[styles.wrapper, size === 'sm' ? styles.sm : undefined, className]
+        .filter(Boolean)
+        .join(' ')}
     >
-      <select className={[styles.select, className].filter(Boolean).join(' ')} {...rest}>
+      <select className={styles.select} {...rest}>
         {children}
       </select>
       <svg

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;
+}