@sovereignfs/ui 0.54.0 → 0.83.1

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,
           }}
         >

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

@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import { StrictMode, useState } from 'react';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { cleanup, render, screen, fireEvent } from '@testing-library/react';
 import { Popover } from '../Popover';
@@ -76,6 +77,53 @@ describe('Popover', () => {
     expect(onClose).toHaveBeenCalledOnce();
   });
 
+  describe('Escape precedence with a nested Popover', () => {
+    it('defers Escape to a nested open Popover instead of closing the outer one', () => {
+      const outerOnClose = vi.fn();
+
+      function NestedHarness() {
+        // Starts closed and opens via a later click, matching the real
+        // sequence (e.g. a date-picker Popover opened from a field inside a
+        // Combobox's own popover content) — mounting both already-open in
+        // the same initial render would instead have React fire the child's
+        // registration effect before the parent's in that one shared commit,
+        // the one case this stack-order approach doesn't handle (see the
+        // equivalent Dialog+ConfirmDialog regression test's own note).
+        const [innerOpen, setInnerOpen] = useState(false);
+        return (
+          <Popover open={true} onClose={outerOnClose} aria-label="Outer" trigger={trigger}>
+            <button type="button" onClick={() => setInnerOpen(true)}>
+              Open inner
+            </button>
+            <Popover
+              open={innerOpen}
+              onClose={() => setInnerOpen(false)}
+              aria-label="Inner"
+              trigger={<span />}
+            >
+              Inner content
+            </Popover>
+          </Popover>
+        );
+      }
+
+      render(<NestedHarness />);
+      fireEvent.click(screen.getByRole('button', { name: 'Open inner' }));
+      expect(screen.getByRole('dialog', { name: 'Inner' })).toBeTruthy();
+
+      // The nested Popover is topmost — the outer Popover's own Escape
+      // listener must not act while it's open.
+      fireEvent.keyDown(document, { key: 'Escape' });
+      expect(outerOnClose).not.toHaveBeenCalled();
+      expect(screen.queryByRole('dialog', { name: 'Inner' })).toBeNull();
+
+      // With the inner one dismissed, the outer Popover is topmost again —
+      // a second Escape now reaches it.
+      fireEvent.keyDown(document, { key: 'Escape' });
+      expect(outerOnClose).toHaveBeenCalledOnce();
+    });
+  });
+
   it('does not call onClose when clicking inside the panel', () => {
     const onClose = vi.fn();
     render(
@@ -95,4 +143,121 @@ describe('Popover', () => {
     );
     expect((screen.getByRole('dialog') as HTMLElement).style.width).toBe('320px');
   });
+
+  describe('horizontal viewport clamp', () => {
+    const rect = (partial: Partial<DOMRect>): DOMRect =>
+      ({
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        width: 0,
+        height: 0,
+        x: 0,
+        y: 0,
+        toJSON() {},
+        ...partial,
+      }) as DOMRect;
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('shifts the panel back on-screen when align="right" would overflow the left edge', () => {
+      // A 340px-wide panel right-aligned under a trigger sitting near the
+      // right edge of a 375px viewport (e.g. a mobile header bell) — its
+      // natural `right: 0` position runs off the left edge, mirroring the
+      // real KanbanNotificationBell overflow found live-testing at 375px.
+      Object.defineProperty(window, 'innerWidth', { value: 375, configurable: true });
+      Object.defineProperty(window, 'innerHeight', { value: 800, configurable: true });
+      const containerRect = rect({ left: 275, right: 319, top: 12, bottom: 56 });
+      const panelRect = rect({
+        left: -21,
+        right: 319,
+        top: 64,
+        bottom: 200,
+        width: 340,
+        height: 136,
+      });
+      vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation(function (
+        this: Element,
+      ) {
+        return this.getAttribute('role') === 'dialog' ? panelRect : containerRect;
+      });
+
+      render(
+        <Popover open={true} onClose={() => {}} aria-label="Menu" width={340} trigger={trigger}>
+          Content
+        </Popover>,
+      );
+
+      const panel = screen.getByRole('dialog') as HTMLElement;
+      // containerRect.left (275) + style.left must land the panel's left
+      // edge at the 4px viewport margin: 4 - 275 = -271.
+      expect(panel.style.left).toBe('-271px');
+      expect(panel.style.right).toBe('auto');
+    });
+
+    it('leaves alignment untouched when the panel already fits the viewport', () => {
+      Object.defineProperty(window, 'innerWidth', { value: 1280, configurable: true });
+      Object.defineProperty(window, 'innerHeight', { value: 800, configurable: true });
+      const containerRect = rect({ left: 900, right: 944, top: 12, bottom: 56 });
+      const panelRect = rect({
+        left: 604,
+        right: 944,
+        top: 64,
+        bottom: 200,
+        width: 340,
+        height: 136,
+      });
+      vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation(function (
+        this: Element,
+      ) {
+        return this.getAttribute('role') === 'dialog' ? panelRect : containerRect;
+      });
+
+      render(
+        <Popover open={true} onClose={() => {}} aria-label="Menu" width={340} trigger={trigger}>
+          Content
+        </Popover>,
+      );
+
+      const panel = screen.getByRole('dialog') as HTMLElement;
+      expect(panel.style.left).toBe('');
+      expect(panel.style.right).toBe('');
+    });
+
+    it('stays clamped under StrictMode double-invoked layout effects', () => {
+      // Regression test: an earlier version of this clamp measured the
+      // panel's *current* `left`/`right` off the DOM to decide whether a
+      // correction was needed. That's not idempotent — StrictMode's dev-only
+      // double-invoke of layout effects re-ran the same measurement against
+      // the panel's own just-applied correction, saw a rect that already
+      // looked fine, and reset `horizontalOffset` back to null before first
+      // paint (found live: the panel visibly overflowed again after HMR).
+      // The fix derives the natural position analytically from `containerRect`
+      // instead, which StrictMode's replay can't perturb.
+      Object.defineProperty(window, 'innerWidth', { value: 375, configurable: true });
+      Object.defineProperty(window, 'innerHeight', { value: 800, configurable: true });
+      const containerRect = rect({ left: 275, right: 319, top: 12, bottom: 56 });
+      const panelWidthOnly = rect({ width: 340, height: 136, top: 64, bottom: 200 });
+      vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation(function (
+        this: Element,
+      ) {
+        return this.getAttribute('role') === 'dialog' ? panelWidthOnly : containerRect;
+      });
+
+      render(
+        <StrictMode>
+          <Popover open={true} onClose={() => {}} aria-label="Menu" width={340} trigger={trigger}>
+            Content
+          </Popover>
+        </StrictMode>,
+      );
+
+      const panel = screen.getByRole('dialog') as HTMLElement;
+      expect(panel.style.left).toBe('-271px');
+      expect(panel.style.right).toBe('auto');
+    });
+  });
 });

package/src/components/QuantityStepper/QuantityStepper.module.css

@@ -3,7 +3,7 @@
   align-items: center;
   gap: var(--sv-space-1);
   padding: var(--sv-space-1);
-  border: 1px solid var(--sv-color-border-strong);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border-strong);
   border-radius: var(--sv-radius-full);
   background: var(--sv-color-surface-sunken);
 }

package/src/components/Resizable/Resizable.module.css

@@ -4,7 +4,7 @@
   width: 100%;
   height: 100%;
   min-height: 320px;
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   border-radius: var(--sv-radius-lg);
   overflow: hidden;
   background: var(--sv-color-surface);
@@ -27,7 +27,7 @@
   width: 12px;
   padding: 0;
   border: 0;
-  border-inline: 1px solid var(--sv-color-border);
+  border-inline: var(--sv-border-width-hairline) solid var(--sv-color-border);
   cursor: col-resize;
   background: var(--sv-color-surface-sunken);
 }
@@ -36,7 +36,7 @@
   width: 100%;
   height: 12px;
   border-inline: 0;
-  border-block: 1px solid var(--sv-color-border);
+  border-block: var(--sv-border-width-hairline) solid var(--sv-color-border);
   cursor: row-resize;
 }
 

package/src/components/RootLayout/RootLayout.module.css

@@ -0,0 +1,12 @@
+/* A definite height, not min-height: ThreeColumnLayout/HeaderFooterLayout's
+   own .shell use height: 100% internally (fixed box, independently-
+   scrolling children via overflow-y: auto) — a percentage height only
+   resolves against an ancestor with a definite (not min-constrained)
+   height, so min-height here would leave their .shell unable to resolve
+   and collapse to content size. This doesn't clip taller content on its
+   own — nothing here sets overflow: hidden, so content taller than the
+   box simply overflows past it rather than being cut off. */
+.root {
+  width: 100%;
+  height: 100%;
+}

package/src/components/RootLayout/RootLayout.stories.tsx

@@ -0,0 +1,125 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { RootLayout } from './RootLayout';
+
+function Block({ label }: { label: string }) {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        height: '100%',
+        padding: 'var(--sv-space-4)',
+        fontFamily: 'var(--sv-font-family)',
+        fontSize: 'var(--sv-font-size-sm)',
+        fontWeight: 600,
+        color: 'var(--sv-color-text-primary)',
+        background: 'var(--sv-color-surface-raised)',
+      }}
+    >
+      {label}
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Components/RootLayout',
+  component: RootLayout,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          "The root-level layout a plugin's page tree sits in. Enforces only structure and dimensions — content always comes from children. Each variant is a fixed web+mobile pairing, not two independent axes; resize the viewport (or check the Mobile story) to see the fork. 'header' keeps the same header+main structure on both breakpoints, but headerHeight (48px, web) and mobileHeaderHeight (60px, mobile) are deliberately different — matching how real shell: minimal plugins do this in production.",
+      },
+    },
+  },
+  args: {
+    children: <Block label="Main" />,
+  },
+} satisfies Meta<typeof RootLayout>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** variant="plain" is the prop's own default — a single child, no chrome. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ height: '100vh' }}>
+      <RootLayout variant="plain">
+        <Block label="Main" />
+      </RootLayout>
+    </div>
+  ),
+};
+
+export const Sidebar: Story = {
+  render: () => (
+    <div style={{ height: '100vh' }}>
+      <RootLayout variant="sidebar">
+        <Block label="Sidebar" />
+        <Block label="Main" />
+      </RootLayout>
+    </div>
+  ),
+};
+
+export const SidebarMobile: Story = {
+  parameters: { viewport: { defaultViewport: 'mobile1' } },
+  render: () => (
+    <div style={{ height: '100vh' }}>
+      <RootLayout variant="sidebar">
+        <Block label="Sidebar (hidden on mobile)" />
+        <Block label="Main" />
+      </RootLayout>
+    </div>
+  ),
+};
+
+export const Header: Story = {
+  render: () => (
+    <div style={{ height: '100vh' }}>
+      <RootLayout variant="header">
+        <Block label="Header (48px)" />
+        <Block label="Main" />
+      </RootLayout>
+    </div>
+  ),
+};
+
+export const HeaderMobile: Story = {
+  parameters: { viewport: { defaultViewport: 'mobile1' } },
+  render: () => (
+    <div style={{ height: '100vh' }}>
+      <RootLayout variant="header">
+        <Block label="Header (60px)" />
+        <Block label="Main" />
+      </RootLayout>
+    </div>
+  ),
+};
+
+export const Shell: Story = {
+  render: () => (
+    <div style={{ height: '100vh' }}>
+      <RootLayout variant="shell">
+        <Block label="Header (mobile only)" />
+        <Block label="Main" />
+        <Block label="Footer (mobile only)" />
+      </RootLayout>
+    </div>
+  ),
+};
+
+export const ShellMobile: Story = {
+  parameters: { viewport: { defaultViewport: 'mobile1' } },
+  render: () => (
+    <div style={{ height: '100vh' }}>
+      <RootLayout variant="shell">
+        <Block label="Header" />
+        <Block label="Main" />
+        <Block label="Footer" />
+      </RootLayout>
+    </div>
+  ),
+};