@sovereignfs/ui 0.45.0 → 0.83.1

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

@@ -0,0 +1,78 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { NotificationsPanel } from '../NotificationsPanel';
+
+afterEach(() => {
+  cleanup();
+});
+
+const items = [
+  {
+    id: '1',
+    icon: <span>icon</span>,
+    title: 'Added to a project',
+    timeLabel: '2d ago',
+    read: false,
+    onOpen: vi.fn(),
+    onDismiss: vi.fn(),
+  },
+];
+
+describe('NotificationsPanel', () => {
+  it('renders a closed trigger with an unread badge', () => {
+    render(<NotificationsPanel items={items} unreadCount={1} />);
+    expect(screen.getByRole('button', { name: /1 unread/ })).toBeTruthy();
+    expect(screen.queryByText('Added to a project')).toBeNull();
+  });
+
+  it('renders no badge when there are no unread notifications', () => {
+    render(<NotificationsPanel items={[]} unreadCount={0} />);
+    expect(screen.getByRole('button', { name: 'Notifications' })).toBeTruthy();
+  });
+
+  it('opens the panel on trigger click, showing items', () => {
+    render(<NotificationsPanel items={items} unreadCount={1} />);
+    fireEvent.click(screen.getByRole('button', { name: /unread/ }));
+    expect(screen.getByText('Added to a project')).toBeTruthy();
+    expect(screen.getByText('2d ago')).toBeTruthy();
+  });
+
+  it('shows an empty state when there are no items', () => {
+    render(<NotificationsPanel items={[]} unreadCount={0} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Notifications' }));
+    expect(screen.getByText('No notifications.')).toBeTruthy();
+  });
+
+  it('calls onOpen when an unread title is clicked', () => {
+    render(<NotificationsPanel items={items} unreadCount={1} />);
+    fireEvent.click(screen.getByRole('button', { name: /unread/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Mark as read: Added to a project' }));
+    expect(items[0]?.onOpen).toHaveBeenCalledOnce();
+  });
+
+  it('calls onDismiss when the dismiss button is clicked', () => {
+    render(<NotificationsPanel items={items} unreadCount={1} />);
+    fireEvent.click(screen.getByRole('button', { name: /unread/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Dismiss: Added to a project' }));
+    expect(items[0]?.onDismiss).toHaveBeenCalledOnce();
+  });
+
+  it('calls onMarkAllRead and onClearAll from the header actions', () => {
+    const onMarkAllRead = vi.fn();
+    const onClearAll = vi.fn();
+    render(
+      <NotificationsPanel
+        items={items}
+        unreadCount={1}
+        onMarkAllRead={onMarkAllRead}
+        onClearAll={onClearAll}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: /unread/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Mark all read' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Clear all' }));
+    expect(onMarkAllRead).toHaveBeenCalledOnce();
+    expect(onClearAll).toHaveBeenCalledOnce();
+  });
+});

package/src/components/OfflineGate/OfflineGate.tsx

@@ -0,0 +1,44 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { useIsOffline } from '../../hooks/useIsOffline';
+import { EmptyState } from '../EmptyState/EmptyState';
+
+export interface OfflineGateProps {
+  children: ReactNode;
+  /** Defaults to a generic "this section" phrasing — pass the surface's own name. */
+  surfaceName?: string;
+  className?: string;
+}
+
+/**
+ * OfflineGate — blocks administrative/settings surfaces from rendering
+ * (possibly stale) cached content while the device has no network, showing an
+ * explanatory empty state instead (research 0012, epic task 2.32).
+ *
+ * Distinct from `OfflineBanner`: the banner is an informational overlay that
+ * coexists with normal content everywhere in the shell. This is a hard block
+ * for surfaces where operating against stale data is actively wrong — e.g. a
+ * Console user list or an Account billing page reflects a point-in-time
+ * snapshot the moment it's server-rendered, and any cached copy replayed
+ * later has no way to signal that it may already be stale. `OfflineGate`
+ * doesn't try to tell staleness apart from freshness; it removes the
+ * question by not rendering the content at all while offline.
+ *
+ * `children` is rendered unconditionally while online, so this adds no cost
+ * to the common case — it only decides what to show, never how the wrapped
+ * content itself is fetched or cached.
+ */
+export function OfflineGate({ children, surfaceName, className }: OfflineGateProps) {
+  const isOffline = useIsOffline();
+  if (!isOffline) return <>{children}</>;
+
+  return (
+    <EmptyState
+      icon="alert-triangle"
+      heading="You're offline"
+      description={`${surfaceName ?? 'This section'} needs a connection — reconnect to continue.`}
+      className={className}
+    />
+  );
+}

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

@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render, screen } from '@testing-library/react';
+import { OfflineGate } from '../OfflineGate';
+
+describe('OfflineGate', () => {
+  beforeEach(() => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: true });
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('renders children unchanged while online', () => {
+    render(
+      <OfflineGate>
+        <p>Live content</p>
+      </OfflineGate>,
+    );
+    expect(screen.getByText('Live content')).toBeDefined();
+  });
+
+  it('replaces children with an explanatory empty state while offline', () => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    render(
+      <OfflineGate>
+        <p>Live content</p>
+      </OfflineGate>,
+    );
+    expect(screen.queryByText('Live content')).toBeNull();
+    expect(screen.getByText("You're offline")).toBeDefined();
+  });
+
+  it('names the surface in the offline message when provided', () => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    render(
+      <OfflineGate surfaceName="Console">
+        <p>Live content</p>
+      </OfflineGate>,
+    );
+    expect(screen.getByText(/Console needs a connection/)).toBeDefined();
+  });
+
+  it('falls back to generic phrasing with no surface name', () => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    render(
+      <OfflineGate>
+        <p>Live content</p>
+      </OfflineGate>,
+    );
+    expect(screen.getByText(/This section needs a connection/)).toBeDefined();
+  });
+
+  it('swaps back to children on reconnect', () => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    render(
+      <OfflineGate>
+        <p>Live content</p>
+      </OfflineGate>,
+    );
+    expect(screen.getByText("You're offline")).toBeDefined();
+    act(() => window.dispatchEvent(new Event('online')));
+    expect(screen.getByText('Live content')).toBeDefined();
+  });
+});

package/src/components/OverlayHeader/OverlayHeader.module.css

@@ -6,7 +6,7 @@
 .header {
   flex-shrink: 0;
   background: var(--sv-color-surface);
-  border-bottom: 1px solid var(--sv-color-border);
+  border-bottom: var(--sv-border-width-hairline) solid var(--sv-color-border);
 }
 
 .row {

package/src/components/OverlayHeader/OverlayHeader.tsx

@@ -5,8 +5,12 @@ 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;
+   *  row's close button present even when no title applies. Accepts any
+   *  `ReactNode`, not just a string — e.g. `Dialog`'s `header` prop passes
+   *  arbitrary content through here (an icon next to text, etc.); the
+   *  row's title slot still assumes single-line content sized like text
+   *  (see the component's own doc comment for the line this doesn't cross). */
+  title?: ReactNode;
   /** Always renders a close button; called on click. */
   onClose: () => void;
   /** When provided, renders a back-chevron button before the title (for
@@ -18,6 +22,15 @@ export interface OverlayHeaderProps {
   /** A second row below the title row — e.g. a tab strip. */
   secondRow?: ReactNode;
   className?: string;
+  /** Override the title row's own className (e.g. tighter padding to match
+   *  a consumer's own compact header elsewhere in the same surface) — the
+   *  row keeps its standard title/back/action/close layout, just restyled.
+   *  For a genuinely different shape, don't use `OverlayHeader` at all (see
+   *  this component's own doc comment). */
+  rowClassName?: string;
+  /** Override the title text's own className (e.g. a smaller font size to
+   *  match a consumer's own compact header elsewhere in the same surface). */
+  titleClassName?: string;
 }
 
 /**
@@ -41,16 +54,18 @@ export function OverlayHeader({
   action,
   secondRow,
   className,
+  rowClassName,
+  titleClassName,
 }: OverlayHeaderProps) {
   return (
     <div className={[styles.header, className].filter(Boolean).join(' ')}>
-      <div className={styles.row}>
+      <div className={[styles.row, rowClassName].filter(Boolean).join(' ')}>
         {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>
+        <span className={[styles.title, titleClassName].filter(Boolean).join(' ')}>{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 />

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

@@ -48,4 +48,22 @@ describe('OverlayHeader', () => {
     render(<OverlayHeader title="Account" onClose={() => {}} secondRow={<nav>Tab strip</nav>} />);
     expect(screen.getByText('Tab strip')).toBeTruthy();
   });
+
+  it('accepts arbitrary ReactNode content for title, not just a string', () => {
+    // Locks in the type widening (title?: string -> title?: ReactNode) that
+    // Dialog's `header` prop relies on (Dialog.tsx passes header through
+    // here as `title`) — a plain string title must keep working unchanged.
+    render(
+      <OverlayHeader
+        title={
+          <>
+            <strong>Card</strong> detail
+          </>
+        }
+        onClose={() => {}}
+      />,
+    );
+    expect(screen.getByText('Card').tagName).toBe('STRONG');
+    expect(screen.getByText('detail')).toBeTruthy();
+  });
 });

package/src/components/PageContainer/PageContainer.module.css

@@ -0,0 +1,82 @@
+.container {
+  width: 100%;
+  margin-inline: auto;
+  /* Declared explicitly rather than inherited from a host reset: `maxWidth`
+     and `padding` land on this same element, so whether the max-width bound
+     includes the padding must not depend on whether the consuming app ships
+     a global `box-sizing` reset. @sovereignfs/ui is usable standalone
+     (task 9.17), where no such reset is guaranteed. Same reason Input,
+     Select, Combobox, DatePicker, and FileDropzone each set it locally. */
+  box-sizing: border-box;
+}
+
+/* ── Max width ──────────────────────────────────────────────────────────── */
+
+/* Outer bound, padding included (see box-sizing above): `md` + `padding="md"`
+   yields a 960px box with 896px of content, not 1024px. */
+
+.sm {
+  max-width: 640px;
+}
+
+.md {
+  max-width: 960px;
+}
+
+.lg {
+  max-width: 1200px;
+}
+
+.full {
+  max-width: none;
+}
+
+/* ── Padding ────────────────────────────────────────────────────────────── */
+
+/* The page gutter, owned by the plugin rather than the runtime shell
+   (task 9.25). `md` reproduces the exact values the shell used to apply
+   (--sv-space-8 desktop / --sv-space-4 mobile), so a bare <PageContainer>
+   renders identically to a pre-9.25 plugin that relied on the shell.
+
+   A fixed four-step scale, deliberately: the review behind task 9.18 found
+   four different ad-hoc padding combinations across plugins, and a free-form
+   value would relocate that inconsistency from CSS modules into JSX.
+
+   --sv-page-gutter is the stand-down hook for an ancestor that *already*
+   supplies the gutter: Dialog sets it to 0 on its content region, so an
+   overlay plugin whose page is one tree rendered into two hosts — the
+   Dialog on soft navigation, the runtime shell on a hard load — is padded
+   exactly once in both, with no prop threading and no knowledge of which
+   host it is in. Setting it to anything other than 0 defeats the fixed
+   scale above and is not a supported use. */
+
+.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/PageContainer/PageContainer.tsx

@@ -0,0 +1,64 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import styles from './PageContainer.module.css';
+
+export interface PageContainerProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Constrains and centers content width. The bound includes `padding`
+   * (the container is `border-box`). Defaults to `'full'` — narrowing is
+   * opt-in, so wrapping a page in `PageContainer` never silently clamps it.
+   */
+  maxWidth?: 'sm' | 'md' | 'lg' | 'full';
+  /**
+   * The page gutter. Responsive — each step is tighter at ≤768px. Defaults
+   * to `'md'`, which is exactly what the runtime shell used to apply
+   * (`--sv-space-8` desktop / `--sv-space-4` mobile), so a bare
+   * `<PageContainer>` is the correct wrapper for a plugin that previously
+   * relied on the shell for its padding.
+   *
+   * Use `'none'` when an ancestor already supplies the gutter — inside a
+   * `Dialog`, whose own content region is padded.
+   */
+  padding?: 'none' | 'sm' | 'md' | 'lg';
+  children: ReactNode;
+}
+
+const maxWidthClass: Record<NonNullable<PageContainerProps['maxWidth']>, string> = {
+  sm: styles.sm as string,
+  md: styles.md as string,
+  lg: styles.lg as string,
+  full: styles.full as string,
+};
+
+const paddingClass: Record<NonNullable<PageContainerProps['padding']>, string> = {
+  none: styles.padNone as string,
+  sm: styles.padSm as string,
+  md: styles.padMd as string,
+  lg: styles.padLg as string,
+};
+
+/**
+ * The shared page wrapper every plugin's own layout or page renders through.
+ *
+ * A plugin owns its page gutter; the runtime shell does not impose one
+ * (task 9.25). The shell still reserves space for chrome a plugin cannot
+ * know about — the offline banner's height and the mobile footer's — but it
+ * contributes no inset of its own, so this component is the single place a
+ * plugin's four-sided padding comes from.
+ */
+export function PageContainer({
+  maxWidth = 'full',
+  padding = 'md',
+  className,
+  children,
+  ...rest
+}: PageContainerProps) {
+  const cls = [styles.container, maxWidthClass[maxWidth], paddingClass[padding], className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <div className={cls} {...rest}>
+      {children}
+    </div>
+  );
+}

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

@@ -0,0 +1,70 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { PageContainer } from '../PageContainer';
+
+afterEach(cleanup);
+
+/** Classes are unhashed under Vitest's CSS-module transform, so compare token
+ *  membership rather than substrings — `toContain('md')` would also match
+ *  `padMd`, which is exactly the confusion these two prop scales invite. */
+function classes(el: Element): string[] {
+  return el.className.split(/\s+/).filter(Boolean);
+}
+
+describe('PageContainer', () => {
+  it('renders its children', () => {
+    render(<PageContainer>content</PageContainer>);
+    expect(screen.getByText('content')).toBeDefined();
+  });
+
+  it('defaults to full max-width, so wrapping a page never silently clamps it', () => {
+    render(<PageContainer>content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('full');
+  });
+
+  it('defaults to md padding — the gutter the runtime shell used to apply', () => {
+    render(<PageContainer>content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('padMd');
+  });
+
+  it('applies sm, md, and lg max-width classes', () => {
+    const { rerender } = render(<PageContainer maxWidth="sm">content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('sm');
+    rerender(<PageContainer maxWidth="md">content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('md');
+    rerender(<PageContainer maxWidth="lg">content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('lg');
+  });
+
+  it('applies none, sm, and lg padding classes', () => {
+    const { rerender } = render(<PageContainer padding="none">content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('padNone');
+    rerender(<PageContainer padding="sm">content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('padSm');
+    rerender(<PageContainer padding="lg">content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('padLg');
+  });
+
+  it('composes max-width and padding independently', () => {
+    render(
+      <PageContainer maxWidth="sm" padding="none">
+        content
+      </PageContainer>,
+    );
+    const cls = classes(screen.getByText('content'));
+    expect(cls).toContain('sm');
+    expect(cls).toContain('padNone');
+    expect(cls).not.toContain('padSm');
+  });
+
+  it('forwards className and other div props', () => {
+    render(
+      <PageContainer className="custom" data-testid="container">
+        content
+      </PageContainer>,
+    );
+    const el = screen.getByTestId('container');
+    expect(classes(el)).toContain('custom');
+  });
+});

package/src/components/PageHeader/PageHeader.module.css

@@ -13,6 +13,17 @@
   min-width: 0;
 }
 
+/* Wraps the optional icon + `.title` so the icon sizes/aligns itself
+   without touching `.title`'s own rules — every existing icon-less usage
+   renders identically, since a single flex child behaves the same as a
+   non-flex one. */
+.titleRow {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-2);
+  color: var(--sv-color-text-primary);
+}
+
 .title {
   margin: 0;
   font-size: var(--sv-font-size-2xl);
@@ -30,3 +41,46 @@
 .action {
   flex-shrink: 0;
 }
+
+/* ── Mobile ─────────────────────────────────────────────────────────────── */
+/* A compact single row — back (optional) + title + action (optional) —
+   generalized from Kanban's own hand-rolled MobileBoardHeader. Deliberately
+   no description handling and no border; stays consistent with .header's
+   own minimal, borderless treatment, just tighter. */
+
+.mobileHeader {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-2);
+  margin-bottom: var(--sv-space-3);
+}
+
+.mobileBack {
+  flex-shrink: 0;
+}
+
+.mobileTitleIcon {
+  flex-shrink: 0;
+  color: var(--sv-color-text-primary);
+}
+
+.mobileTitle {
+  flex: 1;
+  min-width: 0;
+  margin: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--sv-font-size-md);
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-primary);
+  line-height: 1.2;
+}
+
+.mobileAction {
+  flex-shrink: 0;
+}
+
+.mobileMenu {
+  flex-shrink: 0;
+}