@sovereignfs/ui 0.45.0 → 0.83.1

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/ResponsiveSurface/ResponsiveSurface.tsx

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+import { useResponsiveLayout } from '../../hooks/useResponsiveLayout';
+
+export interface ResponsiveSurfaceProps {
+  web: ReactNode;
+  mobile: ReactNode;
+  breakpointPx?: number;
+}
+
+/**
+ * ResponsiveSurface — thin JSX convenience wrapper around
+ * `useResponsiveLayout` for the common two-tree case: render an entirely
+ * different component tree below the breakpoint, not a CSS squeeze of the
+ * same one. Renders only whichever side is active — the other tree is never
+ * mounted.
+ *
+ * This does not replace a plugin's own shell component (e.g. a
+ * `MobileAwareShell` that also threads plugin-specific props like a refresh
+ * signal) — those stay a thin per-plugin wrapper around this.
+ */
+export function ResponsiveSurface({ web, mobile, breakpointPx }: ResponsiveSurfaceProps) {
+  const { value } = useResponsiveLayout({ web, mobile, breakpointPx });
+  return <>{value}</>;
+}

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

@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render, screen } from '@testing-library/react';
+import { ResponsiveSurface } from '../ResponsiveSurface';
+
+let changeHandler: ((e: MediaQueryListEvent) => void) | null = null;
+let matches = false;
+
+function installMatchMedia() {
+  changeHandler = null;
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches,
+      media: query,
+      addEventListener: (_: string, cb: (e: MediaQueryListEvent) => void) => {
+        changeHandler = cb;
+      },
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}
+
+describe('ResponsiveSurface', () => {
+  beforeEach(() => {
+    matches = false;
+    installMatchMedia();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('renders the web tree by default and never mounts the mobile tree', () => {
+    render(
+      <ResponsiveSurface
+        web={<div data-testid="web">web</div>}
+        mobile={<div data-testid="mobile">mobile</div>}
+      />,
+    );
+    expect(screen.getByTestId('web')).toBeDefined();
+    expect(screen.queryByTestId('mobile')).toBeNull();
+  });
+
+  it('renders only the mobile tree below the breakpoint', () => {
+    matches = true;
+    installMatchMedia();
+    render(
+      <ResponsiveSurface
+        web={<div data-testid="web">web</div>}
+        mobile={<div data-testid="mobile">mobile</div>}
+      />,
+    );
+    expect(screen.getByTestId('mobile')).toBeDefined();
+    expect(screen.queryByTestId('web')).toBeNull();
+  });
+
+  it('swaps trees live when the viewport crosses the breakpoint', () => {
+    render(
+      <ResponsiveSurface
+        web={<div data-testid="web">web</div>}
+        mobile={<div data-testid="mobile">mobile</div>}
+      />,
+    );
+    expect(screen.getByTestId('web')).toBeDefined();
+    act(() => changeHandler?.({ matches: true } as MediaQueryListEvent));
+    expect(screen.getByTestId('mobile')).toBeDefined();
+    expect(screen.queryByTestId('web')).toBeNull();
+  });
+});

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

package/src/components/RootLayout/RootLayout.tsx

@@ -0,0 +1,185 @@
+'use client';
+
+import { Children } from 'react';
+import type { ReactNode } from 'react';
+import { HeaderFooterLayout } from '../HeaderFooterLayout/HeaderFooterLayout';
+import { ResponsiveSurface } from '../ResponsiveSurface/ResponsiveSurface';
+import { ThreeColumnLayout } from '../ThreeColumnLayout/ThreeColumnLayout';
+import styles from './RootLayout.module.css';
+
+export type RootLayoutVariant = 'plain' | 'sidebar' | 'header' | 'shell';
+
+export interface RootLayoutProps {
+  /**
+   * Which chrome shape this page uses. Children are positional and their
+   * count is fixed per variant:
+   *  - `'plain'` — 1 child: `[main]`. No chrome on either breakpoint.
+   *  - `'sidebar'` — 2 children: `[sidebar, main]`. Sidebar + main on web
+   *    only — on mobile, sidebar is dropped and only main renders.
+   *  - `'header'` — 2 children: `[header, main]`. Header + main on both
+   *    breakpoints — same structure, but the header's own height differs
+   *    per breakpoint (`headerHeight` on web, `mobileHeaderHeight` on
+   *    mobile), matching how real `shell: minimal` plugins actually do
+   *    this (a compact web top bar vs. the platform's mobile chrome
+   *    height).
+   *  - `'shell'` — 3 children: `[header, main, footer]`. Header + main +
+   *    footer on mobile only — on web, header/footer are dropped and only
+   *    main renders.
+   * Default `'plain'`.
+   */
+  variant?: RootLayoutVariant;
+  children: ReactNode;
+  /** px. Default 64 — matches the platform's own persistent nav rail
+   *  (`--sv-shell-sidebar-width`, runtime/app/(platform)/shell.module.css).
+   *  Only used by `'sidebar'`. */
+  sidebarWidth?: number;
+  /** px. Default 48 — matches a real `shell: minimal` plugin's own compact
+   *  web header (e.g. Kanban's `KanbanHeader`, deliberately not the
+   *  platform's 60px shell header since a `shell: minimal` plugin owns its
+   *  whole viewport). Web only — used by `'header'` on web. */
+  headerHeight?: number;
+  /** px. Default 60 — matches the platform's own mobile chrome
+   *  (`--sv-shell-header-height`, `MobileHeader`'s default). Mobile only —
+   *  used by `'header'` and `'shell'` on mobile. */
+  mobileHeaderHeight?: number;
+  /** px. Default 60 — matches the platform's own mobile chrome
+   *  (`--sv-shell-footer-height`, `MobileFooter`'s default). Mobile only —
+   *  used by `'shell'`. */
+  footerHeight?: number;
+  className?: string;
+}
+
+const EXPECTED_CHILD_COUNT: Record<RootLayoutVariant, number> = {
+  plain: 1,
+  sidebar: 2,
+  header: 2,
+  shell: 3,
+};
+
+interface RootLayoutWebProps {
+  variant: RootLayoutVariant;
+  items: ReactNode[];
+  sidebarWidth: number;
+  headerHeight: number;
+}
+
+// internal — not exported
+function RootLayoutWeb({ variant, items, sidebarWidth, headerHeight }: RootLayoutWebProps) {
+  if (variant === 'sidebar') {
+    const [sidebar, main] = items;
+    return (
+      <ThreeColumnLayout sidebarWidth={sidebarWidth}>
+        {sidebar}
+        {main}
+      </ThreeColumnLayout>
+    );
+  }
+  if (variant === 'header') {
+    const [header, main] = items;
+    return (
+      <HeaderFooterLayout header={header} headerHeight={headerHeight}>
+        {main}
+      </HeaderFooterLayout>
+    );
+  }
+  // 'plain' and 'shell' both render plain on web — shell's chrome is mobile-only.
+  const main = variant === 'shell' ? items[1] : items[0];
+  return <>{main}</>;
+}
+
+interface RootLayoutMobileProps {
+  variant: RootLayoutVariant;
+  items: ReactNode[];
+  mobileHeaderHeight: number;
+  footerHeight: number;
+}
+
+// internal — not exported
+function RootLayoutMobile({
+  variant,
+  items,
+  mobileHeaderHeight,
+  footerHeight,
+}: RootLayoutMobileProps) {
+  if (variant === 'header') {
+    const [header, main] = items;
+    return (
+      <HeaderFooterLayout header={header} headerHeight={mobileHeaderHeight}>
+        {main}
+      </HeaderFooterLayout>
+    );
+  }
+  if (variant === 'shell') {
+    const [header, main, footer] = items;
+    return (
+      <HeaderFooterLayout
+        header={header}
+        footer={footer}
+        headerHeight={mobileHeaderHeight}
+        footerHeight={footerHeight}
+      >
+        {main}
+      </HeaderFooterLayout>
+    );
+  }
+  // 'plain' and 'sidebar' both render plain on mobile — sidebar's chrome is web-only.
+  const main = variant === 'sidebar' ? items[1] : items[0];
+  return <>{main}</>;
+}
+
+/**
+ * RootLayout — the root-level layout a plugin's page tree sits in. Enforces
+ * only structure and dimensions (`width: 100%; height: 100%`, filling
+ * whatever real height the platform shell's own ancestor chain already
+ * establishes — not viewport units, since a plugin isn't alone on the
+ * page). A definite height, not min-height: ThreeColumnLayout/
+ * HeaderFooterLayout's own .shell need one to resolve their own height:
+ * 100% against (see RootLayout.module.css's comment). All content comes
+ * from children; RootLayout has no opinion on what's inside any region.
+ *
+ * The web/mobile fork is `ResponsiveSurface` — only one of
+ * `RootLayoutWeb`/`RootLayoutMobile` is ever mounted, never a CSS squeeze of
+ * the same tree. Each variant's actual shape is delegated entirely to
+ * `ThreeColumnLayout`/`HeaderFooterLayout`; RootLayout itself contains no
+ * media queries.
+ */
+export function RootLayout({
+  variant = 'plain',
+  children,
+  sidebarWidth = 64,
+  headerHeight = 48,
+  mobileHeaderHeight = 60,
+  footerHeight = 60,
+  className,
+}: RootLayoutProps) {
+  const items = Children.toArray(children);
+
+  if (process.env.NODE_ENV !== 'production' && items.length !== EXPECTED_CHILD_COUNT[variant]) {
+    console.warn(
+      `[RootLayout] variant="${variant}" expects ${EXPECTED_CHILD_COUNT[variant]} children; received ${items.length}.`,
+    );
+  }
+
+  return (
+    <div className={[styles.root, className].filter(Boolean).join(' ')}>
+      <ResponsiveSurface
+        web={
+          <RootLayoutWeb
+            variant={variant}
+            items={items}
+            sidebarWidth={sidebarWidth}
+            headerHeight={headerHeight}
+          />
+        }
+        mobile={
+          <RootLayoutMobile
+            variant={variant}
+            items={items}
+            mobileHeaderHeight={mobileHeaderHeight}
+            footerHeight={footerHeight}
+          />
+        }
+      />
+    </div>
+  );
+}