@sovereignfs/ui 0.45.0 → 0.83.1

package/src/components/PageHeader/PageHeader.tsx

@@ -1,21 +1,176 @@
+'use client';
+
 import type { ReactNode } from 'react';
+import { Button } from '../Button/Button';
+import { Icon } from '../Icon/Icon';
+import type { IconName } from '../Icon/Icon';
+import { ResponsiveSurface } from '../ResponsiveSurface/ResponsiveSurface';
 import styles from './PageHeader.module.css';
 
 export interface PageHeaderProps {
   title: string;
   description?: string;
+  /** Optional icon rendered inline before the title text, on both breakpoints — e.g. `folder-open` next to a folder's name. */
+  icon?: IconName;
+  /**
+   * Page-level controls — anywhere from one button to a whole toolbar.
+   * Renders on both breakpoints unchanged; if it needs to look different on
+   * mobile (e.g. collapsing into its own "⋮" trigger), that's the action
+   * content's own responsibility — same pattern Shopper's `ListHeaderActions`
+   * already follows (it calls `useIsMobile()` internally). `PageHeader`
+   * itself has no opinion on what's inside this slot.
+   */
   action?: ReactNode;
   className?: string;
+  /** Heading level for the title. Defaults to `1` for standalone use; pass
+   * `2` or `3` when the page already sits under a shell/plugin `<h1>`, to
+   * avoid a duplicate top-level heading. Visual style is unchanged at every
+   * level — only the rendered tag changes. Applies on both breakpoints. */
+  headingLevel?: 1 | 2 | 3;
+  /** Mobile only — shows a back button (calling this) to the left of the
+   *  title when provided. Omit it to render without one. */
+  onBack?: () => void;
+  /** Mobile only — shows a vertical-ellipsis icon button (calling this) at
+   *  the far right when provided, typically to open a drawer/menu. PageHeader
+   *  has no opinion on what that menu contains — it only renders the trigger
+   *  and calls back. Separate from `action`, which renders identically on
+   *  both breakpoints; this is a mobile-only affordance with no web
+   *  equivalent. */
+  onMenuClick?: () => void;
 }
 
-export function PageHeader({ title, description, action, className }: PageHeaderProps) {
+const HEADING_TAG = { 1: 'h1', 2: 'h2', 3: 'h3' } as const;
+
+interface PageHeaderWebProps {
+  title: string;
+  description?: string;
+  icon?: IconName;
+  action?: ReactNode;
+  headingLevel: 1 | 2 | 3;
+  className?: string;
+}
+
+// internal — not exported
+function PageHeaderWeb({
+  title,
+  description,
+  icon,
+  action,
+  headingLevel,
+  className,
+}: PageHeaderWebProps) {
+  const Heading = HEADING_TAG[headingLevel];
   return (
     <header className={[styles.header, className].filter(Boolean).join(' ')}>
       <div className={styles.text}>
-        <h1 className={styles.title}>{title}</h1>
+        <div className={styles.titleRow}>
+          {icon && <Icon name={icon} size="lg" aria-hidden={true} />}
+          <Heading className={styles.title}>{title}</Heading>
+        </div>
         {description && <p className={styles.description}>{description}</p>}
       </div>
       {action && <div className={styles.action}>{action}</div>}
     </header>
   );
 }
+
+interface PageHeaderMobileProps {
+  title: string;
+  icon?: IconName;
+  action?: ReactNode;
+  headingLevel: 1 | 2 | 3;
+  onBack?: () => void;
+  onMenuClick?: () => void;
+  className?: string;
+}
+
+// internal — not exported
+// No `description` here, deliberately — matches the one real mobile
+// page-header precedent this was generalized from (Kanban's own
+// MobileBoardHeader), which has no subtitle handling either. A single
+// fixed-shape row, consistent with every other mobile chrome bar in this
+// design system rather than a variable-height two-line header.
+function PageHeaderMobile({
+  title,
+  icon,
+  action,
+  headingLevel,
+  onBack,
+  onMenuClick,
+  className,
+}: PageHeaderMobileProps) {
+  const Heading = HEADING_TAG[headingLevel];
+  return (
+    <header className={[styles.mobileHeader, className].filter(Boolean).join(' ')}>
+      {onBack && (
+        <Button
+          variant="ghost"
+          size="sm"
+          aria-label="Back"
+          onClick={onBack}
+          className={styles.mobileBack}
+        >
+          <Icon name="circle-chevron-left" size="md" aria-hidden />
+        </Button>
+      )}
+      {icon && <Icon name={icon} size="md" aria-hidden={true} className={styles.mobileTitleIcon} />}
+      <Heading className={styles.mobileTitle}>{title}</Heading>
+      {action && <div className={styles.mobileAction}>{action}</div>}
+      {onMenuClick && (
+        <Button
+          variant="ghost"
+          size="sm"
+          aria-label="Menu"
+          onClick={onMenuClick}
+          className={styles.mobileMenu}
+        >
+          <Icon name="ellipsis-vertical" size="md" aria-hidden />
+        </Button>
+      )}
+    </header>
+  );
+}
+
+/**
+ * PageHeader — a page's title section. Web: title + description on the
+ * left, action on the right. Mobile: an optional back button, a single-line
+ * title, and the same action slot — a compact single row, matching Kanban's
+ * own hand-rolled MobileBoardHeader this was generalized from. The
+ * web/mobile fork is `ResponsiveSurface` — only one tree is ever mounted.
+ */
+export function PageHeader({
+  title,
+  description,
+  icon,
+  action,
+  className,
+  headingLevel = 1,
+  onBack,
+  onMenuClick,
+}: PageHeaderProps) {
+  return (
+    <ResponsiveSurface
+      web={
+        <PageHeaderWeb
+          title={title}
+          description={description}
+          icon={icon}
+          action={action}
+          headingLevel={headingLevel}
+          className={className}
+        />
+      }
+      mobile={
+        <PageHeaderMobile
+          title={title}
+          icon={icon}
+          action={action}
+          headingLevel={headingLevel}
+          onBack={onBack}
+          onMenuClick={onMenuClick}
+          className={className}
+        />
+      }
+    />
+  );
+}

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

@@ -0,0 +1,103 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { PageHeader } from '../PageHeader';
+
+let matches = false;
+
+function installMatchMedia() {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches,
+      media: query,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}
+
+describe('PageHeader', () => {
+  beforeEach(() => {
+    matches = false;
+    installMatchMedia();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('web: renders title, description, and action', () => {
+    render(
+      <PageHeader
+        title="Users"
+        description="Manage who has access to this instance."
+        action={<button type="button">Invite user</button>}
+      />,
+    );
+
+    expect(screen.getByRole('heading', { name: 'Users' })).toBeDefined();
+    expect(screen.getByText('Manage who has access to this instance.')).toBeDefined();
+    expect(screen.getByRole('button', { name: 'Invite user' })).toBeDefined();
+  });
+
+  it('web: renders no back button even when onBack is given', () => {
+    render(<PageHeader title="Users" onBack={() => undefined} />);
+
+    expect(screen.queryByRole('button', { name: 'Back' })).toBeNull();
+  });
+
+  it('mobile: renders no description, no back button, no menu button by default', () => {
+    matches = true;
+    installMatchMedia();
+
+    render(<PageHeader title="Users" description="Manage who has access to this instance." />);
+
+    expect(screen.getByRole('heading', { name: 'Users' })).toBeDefined();
+    expect(screen.queryByText('Manage who has access to this instance.')).toBeNull();
+    expect(screen.queryByRole('button', { name: 'Back' })).toBeNull();
+    expect(screen.queryByRole('button', { name: 'Menu' })).toBeNull();
+  });
+
+  it('mobile: renders a back button that calls onBack when given', () => {
+    matches = true;
+    installMatchMedia();
+    const onBack = vi.fn();
+
+    render(<PageHeader title="Users" onBack={onBack} />);
+
+    const back = screen.getByRole('button', { name: 'Back' });
+    fireEvent.click(back);
+    expect(onBack).toHaveBeenCalledOnce();
+  });
+
+  it('mobile: renders a menu button that calls onMenuClick when given', () => {
+    matches = true;
+    installMatchMedia();
+    const onMenuClick = vi.fn();
+
+    render(<PageHeader title="Users" onMenuClick={onMenuClick} />);
+
+    const menu = screen.getByRole('button', { name: 'Menu' });
+    fireEvent.click(menu);
+    expect(onMenuClick).toHaveBeenCalledOnce();
+  });
+
+  it('web: renders no menu button even when onMenuClick is given', () => {
+    render(<PageHeader title="Users" onMenuClick={() => undefined} />);
+
+    expect(screen.queryByRole('button', { name: 'Menu' })).toBeNull();
+  });
+
+  it('mobile: renders the same action content as web', () => {
+    matches = true;
+    installMatchMedia();
+
+    render(<PageHeader title="Users" action={<button type="button">Invite user</button>} />);
+
+    expect(screen.getByRole('button', { name: 'Invite user' })).toBeDefined();
+  });
+});

package/src/components/PageLayout/PageLayout.module.css

@@ -0,0 +1,51 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  min-width: 100%;
+  min-height: 100%;
+}
+
+.header {
+  flex-shrink: 0;
+}
+
+.content {
+  flex: 1;
+}
+
+/* ── Padding ────────────────────────────────────────────────────────────── */
+/* Same four-step scale and --sv-page-gutter stand-down hook as
+   PageContainer (see that component's own CSS comment for the full
+   rationale) — kept identical so this can absorb PageContainer's role
+   later without a behavior change for existing consumers. */
+
+.padNone {
+  padding: 0;
+}
+
+.padSm {
+  padding: var(--sv-page-gutter, var(--sv-space-4));
+}
+
+.padMd {
+  padding: var(--sv-page-gutter, var(--sv-space-8));
+}
+
+.padLg {
+  padding: var(--sv-page-gutter, var(--sv-space-12));
+}
+
+/* Matches the breakpoint Dialog, MobileHeader, and MobileFooter already use. */
+@media (max-width: 768px) {
+  .padSm {
+    padding: var(--sv-page-gutter, var(--sv-space-3));
+  }
+
+  .padMd {
+    padding: var(--sv-page-gutter, var(--sv-space-4));
+  }
+
+  .padLg {
+    padding: var(--sv-page-gutter, var(--sv-space-6));
+  }
+}

package/src/components/PageLayout/PageLayout.stories.tsx

@@ -0,0 +1,73 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { PageLayout } from './PageLayout';
+
+function Content() {
+  return (
+    <div
+      style={{
+        fontFamily: 'var(--sv-font-family)',
+        fontSize: 'var(--sv-font-size-sm)',
+        color: 'var(--sv-color-text-primary)',
+      }}
+    >
+      {Array.from({ length: 6 }, (_, index) => (
+        <p key={index}>Page content row {index + 1}.</p>
+      ))}
+    </div>
+  );
+}
+
+function PageHeader() {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        padding: 'var(--sv-space-3) var(--sv-space-4)',
+        borderBottom: '1px solid var(--sv-color-border)',
+        fontFamily: 'var(--sv-font-family)',
+        fontSize: 'var(--sv-font-size-md)',
+        fontWeight: 600,
+        color: 'var(--sv-color-text-primary)',
+      }}
+    >
+      Sv Wallet
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Components/PageLayout',
+  component: PageLayout,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          "A single page's content area, nested inside RootLayout's main slot — not a replacement for RootLayout. No padding by default; opt in via the padding prop (same scale as PageContainer). The optional header is page-specific (e.g. a board title/toolbar), not the app-level header RootLayout already renders.",
+      },
+    },
+  },
+  args: {
+    children: <Content />,
+  },
+} satisfies Meta<typeof PageLayout>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithPadding: Story = {
+  args: {
+    padding: 'lg',
+  },
+};
+
+export const WithHeader: Story = {
+  args: {
+    header: <PageHeader />,
+    padding: 'md',
+  },
+};

package/src/components/PageLayout/PageLayout.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import styles from './PageLayout.module.css';
+
+export type PageLayoutPadding = 'none' | 'sm' | 'md' | 'lg';
+
+export interface PageLayoutProps {
+  /**
+   * A page-specific header — e.g. a board title + search/share toolbar.
+   * Not the app-level header (that's `RootLayout`'s `header`/`shell`
+   * variants) — this is a second, contextual row scoped to this one page.
+   * Renders edge-to-edge above the padded content, outside `padding`.
+   */
+  header?: ReactNode;
+  /** The page gutter. Default `'none'` — unlike `PageContainer`, a bare
+   *  `PageLayout` applies no padding at all; opt in per page. Same four-step
+   *  scale and `--sv-page-gutter` stand-down hook as `PageContainer` (steps
+   *  down at the same 768px breakpoint `Dialog`/`MobileHeader` use). */
+  padding?: PageLayoutPadding;
+  children: ReactNode;
+  className?: string;
+}
+
+const paddingClass: Record<PageLayoutPadding, string> = {
+  none: styles.padNone as string,
+  sm: styles.padSm as string,
+  md: styles.padMd as string,
+  lg: styles.padLg as string,
+};
+
+/**
+ * PageLayout — a single page's content area within a plugin (nested inside
+ * `RootLayout`'s `main` slot, not a replacement for it). Enforces only
+ * structure and dimensions; content always comes from props/children.
+ *
+ * `min-width: 100%; min-height: 100%` — safe here (unlike `RootLayout`'s own
+ * root) because `PageLayout` is always nested inside an already
+ * flex-stretched region (`ThreeColumnLayout`/`HeaderFooterLayout`'s
+ * `.main`), and a stretched flex item's cross-size is definite for its
+ * descendants' percentage resolution, so no separate height-cascading fix
+ * is needed the way `RootLayout`'s root required one.
+ */
+export function PageLayout({ header, padding = 'none', children, className }: PageLayoutProps) {
+  return (
+    <div className={[styles.root, className].filter(Boolean).join(' ')}>
+      {header && <div className={styles.header}>{header}</div>}
+      <div className={[styles.content, paddingClass[padding]].join(' ')}>{children}</div>
+    </div>
+  );
+}

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

@@ -0,0 +1,34 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { PageLayout } from '../PageLayout';
+
+afterEach(cleanup);
+
+describe('PageLayout', () => {
+  it('renders children with no header by default', () => {
+    render(<PageLayout>Content</PageLayout>);
+
+    expect(screen.getByText('Content')).toBeDefined();
+    expect(screen.queryByText('Header')).toBeNull();
+  });
+
+  it('renders a page-specific header when given', () => {
+    render(<PageLayout header={<span>Header</span>}>Content</PageLayout>);
+
+    expect(screen.getByText('Header')).toBeDefined();
+    expect(screen.getByText('Content')).toBeDefined();
+  });
+
+  it('applies no padding by default', () => {
+    render(<PageLayout>Content</PageLayout>);
+
+    expect(screen.getByText('Content').className).toContain('padNone');
+  });
+
+  it('applies the requested padding step', () => {
+    render(<PageLayout padding="lg">Content</PageLayout>);
+
+    expect(screen.getByText('Content').className).toContain('padLg');
+  });
+});

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

@@ -8,7 +8,7 @@
   top: calc(100% + var(--sv-space-2));
   z-index: 60;
   background: var(--sv-color-surface);
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   border-radius: var(--sv-radius-2xl);
   box-shadow: var(--sv-shadow-popover);
   /* auto, not hidden: Popover.tsx applies an inline max-height only when the

package/src/components/Popover/Popover.tsx

@@ -9,6 +9,11 @@ import {
   type ReactElement,
   type ReactNode,
 } from 'react';
+import {
+  isTopmostOpenOverlay,
+  registerOpenOverlay,
+  unregisterOpenOverlay,
+} from '../../overlay-shell';
 import styles from './Popover.module.css';
 
 export interface PopoverProps {
@@ -30,6 +35,17 @@ export interface PopoverProps {
    * regardless of CSS module load order, unlike passing an extra className.
    */
   panelStyle?: CSSProperties;
+  /**
+   * Class applied to the popover's own wrapper around `trigger` — the
+   * element that participates in the caller's layout.
+   *
+   * Mostly needed for flex sizing: the wrapper is an `inline-flex` box with
+   * the default `min-width: auto`, which pins it to the trigger's content
+   * width. Inside a flex row that has to shrink, that stops a truncatable
+   * trigger from ever giving up space, and pushes its siblings out of the
+   * container instead. Pass a class setting `min-width: 0` there.
+   */
+  className?: string;
   'aria-label': string;
   children: ReactNode;
 }
@@ -78,6 +94,7 @@ export function Popover({
   align = 'right',
   width = 288,
   panelStyle,
+  className,
   'aria-label': ariaLabel,
   children,
 }: PopoverProps) {
@@ -92,6 +109,36 @@ export function Popover({
   // 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);
+  // Horizontal viewport clamp, as a `left` override (container-relative px)
+  // that replaces the `align`-driven `left: 0` / `right: 0` class rule —
+  // null leaves alignment at its natural, class-driven position, for the
+  // common case where the panel already fits. Needed because a fixed-width
+  // panel anchored to one edge of a trigger near the *opposite* edge of a
+  // narrow viewport (e.g. a 340px panel under a bell sitting near the right
+  // edge of a 375px mobile screen) has nowhere to go but off-screen — the
+  // existing vertical flip only ever solves the above/below axis, never
+  // this one.
+  const [horizontalOffset, setHorizontalOffset] = useState<number | null>(null);
+  const overlayIdRef = useRef<string | null>(null);
+
+  // Registers into the same open-overlay stack Dialog/Drawer/Sheet/
+  // ConfirmDialog use (overlay-shell.ts) purely so a Dialog this Popover was
+  // opened from inside of (e.g. a DatePicker/Combobox field in a modal form —
+  // Popover is what Menu/Combobox/DatePicker/ContextMenu/HoverCard/UserMenu
+  // are all built on) knows it is no longer the topmost overlay, and defers
+  // Escape to this one instead of closing itself too. A separate effect keyed
+  // only on `open`, matching useOverlayKeyboardTrap's own pattern — identity
+  // churn on `onClose` shouldn't re-register and bump this popover back to
+  // the top of the stack.
+  useEffect(() => {
+    if (!open) return;
+    const id = registerOpenOverlay();
+    overlayIdRef.current = id;
+    return () => {
+      unregisterOpenOverlay(id);
+      overlayIdRef.current = null;
+    };
+  }, [open]);
 
   // width="trigger": measure the trigger's own rendered width and keep the
   // panel matching it, including live resizes (e.g. rotating the device, or
@@ -127,6 +174,7 @@ export function Popover({
     if (!open) {
       setOpenUpward(false);
       setMaxHeight(null);
+      setHorizontalOffset(null);
       return;
     }
     const container = containerRef.current;
@@ -155,10 +203,37 @@ export function Popover({
     setOpenUpward(upward);
     const available = upward ? spaceAbove : spaceBelow;
     setMaxHeight(panelHeight > available ? Math.max(available, 0) : null);
+
+    // Horizontal clamp. Deliberately computed from `containerRect` (the
+    // trigger's own position, never affected by anything this effect does)
+    // and the panel's rendered *width* (also offset-independent) rather than
+    // reading the panel's current `left`/`right` off the DOM — those reflect
+    // whatever `horizontalOffset` a *previous* run of this same effect may
+    // already have applied. Measuring the rendered position directly is not
+    // idempotent: re-running this effect after it already nudged the panel
+    // on-screen would see an already-corrected rect that looks like it never
+    // needed correcting, and clear the very offset it just set (confirmed
+    // live — React StrictMode's dev-only double-invoke of layout effects hit
+    // exactly this: the second pass measured the first pass's fix as "fits
+    // fine" and reset `horizontalOffset` back to null before first paint).
+    // Rebuilding the *natural*, un-offset position analytically from the
+    // same `align`-driven rule the CSS class itself encodes (`right: 0` /
+    // `left: 0` relative to the container) sidesteps that entirely — the
+    // same inputs always produce the same output, however many times this
+    // runs.
+    const containerRect = container.getBoundingClientRect();
+    const panelWidth = panel.getBoundingClientRect().width;
+    const naturalLeft = align === 'right' ? containerRect.right - panelWidth : containerRect.left;
+    const clampedLeft = Math.min(
+      Math.max(naturalLeft, VIEWPORT_MARGIN),
+      window.innerWidth - VIEWPORT_MARGIN - panelWidth,
+    );
+    setHorizontalOffset(clampedLeft !== naturalLeft ? clampedLeft - containerRect.left : 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]);
+    // align included: the horizontal clamp above reads it directly.
+  }, [open, children, align]);
 
   // Outside-click dismissal
   useEffect(() => {
@@ -172,18 +247,24 @@ export function Popover({
     return () => document.removeEventListener('mousedown', handleMouseDown);
   }, [open, onClose]);
 
-  // Escape key dismissal
+  // Escape key dismissal — deferred to a nested overlay (if any) via the same
+  // topmost-overlay check useOverlayKeyboardTrap uses, so e.g. opening a
+  // ConfirmDialog from inside this panel's content doesn't also close the
+  // popover out from under it on the same Escape press.
   useEffect(() => {
     if (!open) return;
     function handleKeyDown(e: KeyboardEvent) {
-      if (e.key === 'Escape') onClose();
+      if (e.key !== 'Escape') return;
+      const id = overlayIdRef.current;
+      if (id !== null && !isTopmostOpenOverlay(id)) return;
+      onClose();
     }
     document.addEventListener('keydown', handleKeyDown);
     return () => document.removeEventListener('keydown', handleKeyDown);
   }, [open, onClose]);
 
   return (
-    <div ref={containerRef} className={styles.container}>
+    <div ref={containerRef} className={[styles.container, className].filter(Boolean).join(' ')}>
       {trigger}
       {open && (
         <div
@@ -197,6 +278,7 @@ export function Popover({
           style={{
             width: width === 'trigger' ? (triggerWidth ?? undefined) : width,
             maxHeight: maxHeight ?? undefined,
+            ...(horizontalOffset != null ? { left: horizontalOffset, right: 'auto' } : {}),
             ...panelStyle,
           }}
         >