@sovereignfs/ui 0.54.0 → 0.83.1

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

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

@@ -0,0 +1,161 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { RootLayout } from '../RootLayout';
+
+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('RootLayout', () => {
+  beforeEach(() => {
+    matches = false;
+    installMatchMedia();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('plain: renders the single child on web and mobile', () => {
+    render(
+      <RootLayout variant="plain">
+        <span>Main</span>
+      </RootLayout>,
+    );
+    expect(screen.getByText('Main')).toBeDefined();
+    cleanup();
+
+    matches = true;
+    installMatchMedia();
+    render(
+      <RootLayout variant="plain">
+        <span>Main</span>
+      </RootLayout>,
+    );
+    expect(screen.getByText('Main')).toBeDefined();
+  });
+
+  it('sidebar: renders sidebar + main on web, main only on mobile', () => {
+    render(
+      <RootLayout variant="sidebar">
+        <nav>Sidebar</nav>
+        <main>Main</main>
+      </RootLayout>,
+    );
+    expect(screen.getByText('Sidebar')).toBeDefined();
+    expect(screen.getByText('Main')).toBeDefined();
+    cleanup();
+
+    matches = true;
+    installMatchMedia();
+    render(
+      <RootLayout variant="sidebar">
+        <nav>Sidebar</nav>
+        <main>Main</main>
+      </RootLayout>,
+    );
+    expect(screen.queryByText('Sidebar')).toBeNull();
+    expect(screen.getByText('Main')).toBeDefined();
+  });
+
+  it('header: renders header + main identically on web and mobile', () => {
+    render(
+      <RootLayout variant="header">
+        <header>Header</header>
+        <main>Main</main>
+      </RootLayout>,
+    );
+    expect(screen.getByText('Header')).toBeDefined();
+    expect(screen.getByText('Main')).toBeDefined();
+    cleanup();
+
+    matches = true;
+    installMatchMedia();
+    render(
+      <RootLayout variant="header">
+        <header>Header</header>
+        <main>Main</main>
+      </RootLayout>,
+    );
+    expect(screen.getByText('Header')).toBeDefined();
+    expect(screen.getByText('Main')).toBeDefined();
+  });
+
+  it('header: applies headerHeight on web and mobileHeaderHeight on mobile', () => {
+    render(
+      <RootLayout variant="header">
+        <header>Header</header>
+        <main>Main</main>
+      </RootLayout>,
+    );
+    expect(screen.getByText('Header').parentElement?.style.height).toBe('48px');
+    cleanup();
+
+    matches = true;
+    installMatchMedia();
+    render(
+      <RootLayout variant="header">
+        <header>Header</header>
+        <main>Main</main>
+      </RootLayout>,
+    );
+    expect(screen.getByText('Header').parentElement?.style.height).toBe('60px');
+  });
+
+  it('shell: renders main only on web, header + main + footer on mobile', () => {
+    render(
+      <RootLayout variant="shell">
+        <header>Header</header>
+        <main>Main</main>
+        <footer>Footer</footer>
+      </RootLayout>,
+    );
+    expect(screen.queryByText('Header')).toBeNull();
+    expect(screen.getByText('Main')).toBeDefined();
+    expect(screen.queryByText('Footer')).toBeNull();
+    cleanup();
+
+    matches = true;
+    installMatchMedia();
+    render(
+      <RootLayout variant="shell">
+        <header>Header</header>
+        <main>Main</main>
+        <footer>Footer</footer>
+      </RootLayout>,
+    );
+    expect(screen.getByText('Header')).toBeDefined();
+    expect(screen.getByText('Main')).toBeDefined();
+    expect(screen.getByText('Footer')).toBeDefined();
+  });
+
+  it('warns in development when the child count does not match the variant', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+    render(
+      <RootLayout variant="sidebar">
+        <span>Only one child</span>
+      </RootLayout>,
+    );
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('variant="sidebar"'));
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('expects 2'));
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('received 1'));
+
+    warn.mockRestore();
+  });
+});

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

@@ -2,7 +2,7 @@
   display: inline-flex;
   background: var(--sv-color-surface-sunken);
   border-radius: var(--sv-radius-full);
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   padding: 2px;
   gap: 2px;
 }

package/src/components/Select/Select.module.css

@@ -18,7 +18,7 @@
   line-height: 1.5;
   color: var(--sv-color-text-primary);
   background-color: var(--sv-color-surface);
-  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-md);
   cursor: pointer;
   /* Remove native OS chevron */

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

@@ -1,6 +1,9 @@
 /* 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
+ * --sv-shell-footer-height, set by the platform shell or, for a plugin that
+ * self-renders MobileHeader/MobileFooter instead (shellConfig.mobileHeader/
+ * mobileFooter: false), by that component itself — see
+ * usePublishShellChromeHeight), 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

package/src/components/Sheet/Sheet.tsx

@@ -3,6 +3,7 @@
 import { type ReactNode, useRef } from 'react';
 import { useMountTransition, usePrefersReducedMotion } from '../../motion';
 import {
+  OVERLAY_MOTION_DURATION_MS,
   useOverlayFocusCapture,
   useOverlayKeyboardTrap,
   useOverlayScrollLock,
@@ -40,10 +41,6 @@ export interface SheetProps {
   children: ReactNode;
 }
 
-// Matches --sv-motion-duration-base (Sheet.module.css) — see Dialog.tsx's
-// identical constant for why this stays a plain JS number.
-const MOTION_DURATION_MS = 250;
-
 /**
  * Sheet — a full-page overlay that replaces a plugin's content area between
  * the shell's fixed header and footer (RFC 0013's mobile chrome stays visible
@@ -73,7 +70,10 @@ export function Sheet({
 }: SheetProps) {
   const panelRef = useRef<HTMLDivElement>(null);
   const reducedMotion = usePrefersReducedMotion();
-  const { mounted, phase } = useMountTransition(open, reducedMotion ? 0 : MOTION_DURATION_MS);
+  const { mounted, phase } = useMountTransition(
+    open,
+    reducedMotion ? 0 : OVERLAY_MOTION_DURATION_MS,
+  );
 
   useOverlayScrollLock(mounted);
   useOverlayFocusCapture(panelRef, mounted);

package/src/components/SplitPane/SplitPane.module.css

@@ -5,7 +5,7 @@
     minmax(0, calc(100% - var(--split-pane-primary-size, 50%)));
   width: 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);
@@ -25,7 +25,7 @@
 }
 
 .pane + .pane {
-  border-left: 1px solid var(--sv-color-border);
+  border-left: var(--sv-border-width-hairline) solid var(--sv-color-border);
 }
 
 .handle {
@@ -34,7 +34,7 @@
   min-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);
 }
@@ -79,7 +79,7 @@
   }
 
   .pane + .pane {
-    border-top: 1px solid var(--sv-color-border);
+    border-top: var(--sv-border-width-hairline) solid var(--sv-color-border);
     border-left: 0;
   }
 }

package/src/components/StatusBadge/StatusBadge.module.css

@@ -5,7 +5,7 @@
   min-height: 24px;
   gap: var(--sv-space-1);
   padding: 2px var(--sv-space-2);
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   border-radius: var(--sv-radius-full);
   font-family: var(--sv-font-family);
   font-size: var(--sv-font-size-xs);

package/src/components/StepStrip/StepStrip.module.css

@@ -0,0 +1,53 @@
+.strip {
+  display: flex;
+  align-items: stretch;
+  overflow-x: auto;
+}
+
+.step {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+.connector {
+  width: var(--sv-space-4);
+  height: 2px;
+  flex-shrink: 0;
+  background: var(--sv-color-border);
+}
+
+.connectorDashed {
+  background-image: repeating-linear-gradient(
+    to right,
+    var(--sv-color-border) 0,
+    var(--sv-color-border) 4px,
+    transparent 4px,
+    transparent 7px
+  );
+}
+
+.addChip {
+  all: unset;
+  box-sizing: border-box;
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-1);
+  padding: var(--sv-space-3) var(--sv-space-4);
+  border: var(--sv-border-width-hairline) dashed var(--sv-color-border);
+  border-radius: var(--sv-radius-lg);
+  color: var(--sv-color-text-muted);
+  font-size: var(--sv-font-size-sm);
+  cursor: pointer;
+}
+
+.addChip:hover {
+  background: var(--sv-color-surface-sunken);
+  color: var(--sv-color-text-primary);
+}
+
+.addChip:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+}

package/src/components/StepStrip/StepStrip.tsx

@@ -0,0 +1,74 @@
+import type { ReactNode } from 'react';
+import { Icon } from '../Icon/Icon';
+import styles from './StepStrip.module.css';
+
+export interface StepStripItem {
+  id: string;
+}
+
+export interface StepStripProps<T extends StepStripItem> {
+  items: T[];
+  activeId: string | null;
+  /** Full control over each chip's content, click handling, and (if needed) drag-reorder wiring. */
+  renderItem: (item: T, state: { isActive: boolean; index: number }) => ReactNode;
+  /** Trailing dashed "add" chip — omit to render the strip with no add affordance. */
+  onAdd?: () => void;
+  addLabel?: string;
+  className?: string;
+  'aria-label'?: string;
+}
+
+/**
+ * StepStrip — a horizontal, connected sequence of steps (a route or
+ * itinerary strip): ordered chips joined by a thin connector line, with an
+ * optional trailing dashed "add" chip. Purely presentational — it owns
+ * layout and the connector lines, nothing else.
+ *
+ * Each chip's content, active styling, and click handling are entirely up
+ * to `renderItem`; if a consumer needs drag-reorder, `renderItem` attaches
+ * its own dnd-kit `useSortable` ref/listeners to whatever it returns. This
+ * mirrors `DragHandleRow`'s existing split (DS owns chrome, consumer wires
+ * dnd-kit via passed-through props) generalized for a horizontal,
+ * handle-less strip where the whole rendered item — not a separate handle
+ * icon — is both the click target and the drag surface.
+ */
+export function StepStrip<T extends StepStripItem>({
+  items,
+  activeId,
+  renderItem,
+  onAdd,
+  addLabel = 'Add',
+  className,
+  'aria-label': ariaLabel,
+}: StepStripProps<T>) {
+  return (
+    <div
+      className={[styles.strip, className].filter(Boolean).join(' ')}
+      role="list"
+      aria-label={ariaLabel}
+    >
+      {items.map((item, index) => (
+        <div key={item.id} className={styles.step} role="listitem">
+          {renderItem(item, { isActive: item.id === activeId, index })}
+          {(index < items.length - 1 || onAdd) && (
+            <div
+              className={[
+                styles.connector,
+                index === items.length - 1 ? styles.connectorDashed : '',
+              ]
+                .filter(Boolean)
+                .join(' ')}
+              aria-hidden="true"
+            />
+          )}
+        </div>
+      ))}
+      {onAdd && (
+        <button type="button" className={styles.addChip} onClick={onAdd}>
+          <Icon name="plus" size="sm" aria-hidden={true} />
+          {addLabel}
+        </button>
+      )}
+    </div>
+  );
+}

package/src/components/SuggestionInput/SuggestionInput.module.css

@@ -7,7 +7,7 @@
   line-height: 1.5;
   color: var(--sv-color-text-primary);
   background-color: var(--sv-color-surface);
-  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-md);
   transition:
     border-color 0.15s ease,
@@ -99,5 +99,5 @@
 
 .divider {
   margin: var(--sv-space-1) var(--sv-space-2);
-  border-top: 1px solid var(--sv-color-border);
+  border-top: var(--sv-border-width-hairline) solid var(--sv-color-border);
 }

package/src/components/SwipableMobileCarousel/SwipableMobileCarousel.module.css

@@ -39,10 +39,19 @@
   flex-direction: column;
 }
 
-.dots {
+.indicatorSlot {
   /* Overlays the bottom of .wrap rather than taking its own layout row —
      matches both sovereign-tasks' and sovereign-shopper's existing dots
-     placement. */
+     placement. Applied by the carousel itself around WHATEVER
+     renderIndicator returns (the default SwipableMobileCarouselDots or a
+     caller-supplied override) — a custom renderIndicator has no way to
+     import this module's locally-scoped class itself (CSS Modules classnames
+     aren't cross-file importable), so positioning must live here, not be
+     something each indicator implementation opts into. Previously this class
+     was only ever applied to the *default* indicator branch, which silently
+     left any custom renderIndicator unpositioned — a static, in-flow sibling
+     pushed below the full-height .scroller and clipped out of view instead
+     of overlaid on top of it. */
   position: absolute;
   left: 0;
   right: 0;
@@ -50,6 +59,6 @@
   pointer-events: none;
 }
 
-.dots > * {
+.indicatorSlot > * {
   pointer-events: auto;
 }