@sovereignfs/ui 0.41.0 → 0.54.0

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/PageContainer/PageContainer.module.css

@@ -0,0 +1,20 @@
+.container {
+  width: 100%;
+  margin-inline: auto;
+}
+
+.sm {
+  max-width: 640px;
+}
+
+.md {
+  max-width: 960px;
+}
+
+.lg {
+  max-width: 1200px;
+}
+
+.full {
+  max-width: none;
+}

package/src/components/PageContainer/PageContainer.tsx

@@ -0,0 +1,31 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import styles from './PageContainer.module.css';
+
+export interface PageContainerProps extends HTMLAttributes<HTMLDivElement> {
+  /** Constrains and centers content width. Adds no padding of its own — the
+   * runtime shell already pads plugin content. Defaults to 'md'. */
+  maxWidth?: 'sm' | 'md' | 'lg' | 'full';
+  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,
+};
+
+export function PageContainer({
+  maxWidth = 'md',
+  className,
+  children,
+  ...rest
+}: PageContainerProps) {
+  const cls = [styles.container, maxWidthClass[maxWidth], className].filter(Boolean).join(' ');
+
+  return (
+    <div className={cls} {...rest}>
+      {children}
+    </div>
+  );
+}

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

@@ -0,0 +1,37 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { PageContainer } from '../PageContainer';
+
+afterEach(cleanup);
+
+describe('PageContainer', () => {
+  it('renders its children', () => {
+    render(<PageContainer>content</PageContainer>);
+    expect(screen.getByText('content')).toBeDefined();
+  });
+
+  it('defaults to md max-width', () => {
+    render(<PageContainer>content</PageContainer>);
+    expect(screen.getByText('content').className).toContain('md');
+  });
+
+  it('applies sm, lg, and full max-width classes', () => {
+    const { rerender } = render(<PageContainer maxWidth="sm">content</PageContainer>);
+    expect(screen.getByText('content').className).toContain('sm');
+    rerender(<PageContainer maxWidth="lg">content</PageContainer>);
+    expect(screen.getByText('content').className).toContain('lg');
+    rerender(<PageContainer maxWidth="full">content</PageContainer>);
+    expect(screen.getByText('content').className).toContain('full');
+  });
+
+  it('forwards className and other div props', () => {
+    render(
+      <PageContainer className="custom" data-testid="container">
+        content
+      </PageContainer>,
+    );
+    const el = screen.getByTestId('container');
+    expect(el.className).toContain('custom');
+  });
+});

package/src/components/PageHeader/PageHeader.tsx

@@ -6,13 +6,27 @@ export interface PageHeaderProps {
   description?: string;
   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. */
+  headingLevel?: 1 | 2 | 3;
 }
 
-export function PageHeader({ title, description, action, className }: PageHeaderProps) {
+const HEADING_TAG = { 1: 'h1', 2: 'h2', 3: 'h3' } as const;
+
+export function PageHeader({
+  title,
+  description,
+  action,
+  className,
+  headingLevel = 1,
+}: PageHeaderProps) {
+  const Heading = HEADING_TAG[headingLevel];
   return (
     <header className={[styles.header, className].filter(Boolean).join(' ')}>
       <div className={styles.text}>
-        <h1 className={styles.title}>{title}</h1>
+        <Heading className={styles.title}>{title}</Heading>
         {description && <p className={styles.description}>{description}</p>}
       </div>
       {action && <div className={styles.action}>{action}</div>}

package/src/components/Pagination/Pagination.module.css

@@ -0,0 +1,98 @@
+.nav {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-1);
+}
+
+.list {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-1);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* Icon-only nav buttons — same footprint as Dialog's close button. */
+.navButton {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--sv-space-8);
+  height: var(--sv-space-8);
+  border: none;
+  border-radius: var(--sv-radius-md);
+  background: transparent;
+  color: var(--sv-color-text-primary);
+  cursor: pointer;
+}
+
+.navButton:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+@media (hover: hover) {
+  .navButton:not(:disabled):hover {
+    background: var(--sv-color-surface-sunken);
+  }
+}
+
+.navButton:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+}
+
+@media (pointer: coarse) {
+  .navButton {
+    width: var(--sv-touch-target-min, 44px);
+    height: var(--sv-touch-target-min, 44px);
+  }
+}
+
+.pageButton {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: var(--sv-space-8);
+  height: var(--sv-space-8);
+  padding: 0 var(--sv-space-2);
+  border: none;
+  border-radius: var(--sv-radius-md);
+  background: transparent;
+  color: var(--sv-color-text-primary);
+  font-size: var(--sv-font-size-sm);
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .pageButton:not(.active):hover {
+    background: var(--sv-color-surface-sunken);
+  }
+}
+
+.pageButton:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+}
+
+.active {
+  background: var(--sv-color-accent);
+  color: var(--sv-color-text-on-accent);
+}
+
+@media (pointer: coarse) {
+  .pageButton {
+    min-width: var(--sv-touch-target-min, 44px);
+    height: var(--sv-touch-target-min, 44px);
+  }
+}
+
+.ellipsis {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: var(--sv-space-8);
+  height: var(--sv-space-8);
+  color: var(--sv-color-text-muted);
+}

package/src/components/Pagination/Pagination.stories.tsx

@@ -0,0 +1,49 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Pagination } from './Pagination';
+
+const meta = {
+  title: 'Components/Pagination',
+  component: Pagination,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Page-number / prev-next control. Shows first, last, and pages near the current one, with an ellipsis for gaps once the page count grows.',
+      },
+    },
+  },
+  args: {
+    page: 1,
+    totalPages: 5,
+    onChange: () => {},
+  },
+} satisfies Meta<typeof Pagination>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const FewPages: Story = {
+  render: (args) => {
+    const [page, setPage] = useState(args.page);
+    return <Pagination {...args} page={page} totalPages={5} onChange={setPage} />;
+  },
+};
+
+export const ManyPagesWithEllipsis: Story = {
+  render: (_args) => {
+    const [page, setPage] = useState(8);
+    return <Pagination page={page} totalPages={40} onChange={setPage} />;
+  },
+};
+
+export const FirstPage: Story = {
+  args: { page: 1, totalPages: 10 },
+};
+
+export const LastPage: Story = {
+  args: { page: 10, totalPages: 10 },
+};

package/src/components/Pagination/Pagination.tsx

@@ -0,0 +1,87 @@
+import { Icon } from '../Icon/Icon';
+import styles from './Pagination.module.css';
+
+export interface PaginationProps {
+  /** 1-indexed current page. */
+  page: number;
+  totalPages: number;
+  onChange: (page: number) => void;
+  className?: string;
+  'aria-label'?: string;
+}
+
+type PageEntry = number | 'ellipsis';
+
+/** First page, last page, current page ± 1 sibling, ellipsis for gaps. */
+function getPageList(page: number, totalPages: number): PageEntry[] {
+  if (totalPages <= 1) return [1];
+
+  const siblingCount = 1;
+  const startPage = Math.max(2, page - siblingCount);
+  const endPage = Math.min(totalPages - 1, page + siblingCount);
+
+  const pages: PageEntry[] = [1];
+  if (startPage > 2) pages.push('ellipsis');
+  for (let p = startPage; p <= endPage; p++) {
+    pages.push(p);
+  }
+  if (endPage < totalPages - 1) pages.push('ellipsis');
+  pages.push(totalPages);
+  return pages;
+}
+
+export function Pagination({
+  page,
+  totalPages,
+  onChange,
+  className,
+  'aria-label': ariaLabel = 'Pagination',
+}: PaginationProps) {
+  const pages = getPageList(page, totalPages);
+
+  return (
+    <nav aria-label={ariaLabel} className={[styles.nav, className].filter(Boolean).join(' ')}>
+      <button
+        type="button"
+        className={styles.navButton}
+        onClick={() => onChange(page - 1)}
+        disabled={page <= 1}
+        aria-label="Previous page"
+      >
+        <Icon name="chevron-left" size="sm" aria-hidden />
+      </button>
+      <ul className={styles.list}>
+        {pages.map((p, index) =>
+          p === 'ellipsis' ? (
+            <li key={`ellipsis-${index}`} className={styles.ellipsis} aria-hidden="true">
+              …
+            </li>
+          ) : (
+            <li key={p}>
+              <button
+                type="button"
+                className={[styles.pageButton, p === page ? styles.active : '']
+                  .filter(Boolean)
+                  .join(' ')}
+                onClick={() => onChange(p)}
+                aria-current={p === page ? 'page' : undefined}
+                aria-label={`Page ${p}`}
+              >
+                {p}
+              </button>
+            </li>
+          ),
+        )}
+      </ul>
+      <button
+        type="button"
+        className={styles.navButton}
+        onClick={() => onChange(page + 1)}
+        disabled={page >= totalPages}
+        aria-label="Next page"
+      >
+        <Icon name="chevron-right" size="sm" aria-hidden />
+      </button>
+    </nav>
+  );
+}

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

@@ -0,0 +1,56 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { Pagination } from '../Pagination';
+
+afterEach(cleanup);
+
+describe('Pagination', () => {
+  it('marks the current page with aria-current="page"', () => {
+    render(<Pagination page={3} totalPages={5} onChange={() => {}} />);
+    expect(screen.getByRole('button', { name: 'Page 3' }).getAttribute('aria-current')).toBe(
+      'page',
+    );
+    expect(screen.getByRole('button', { name: 'Page 2' }).getAttribute('aria-current')).toBeNull();
+  });
+
+  it('calls onChange with the clicked page number', () => {
+    const onChange = vi.fn();
+    render(<Pagination page={3} totalPages={5} onChange={onChange} />);
+    screen.getByRole('button', { name: 'Page 4' }).click();
+    expect(onChange).toHaveBeenCalledWith(4);
+  });
+
+  it('disables the previous button on the first page', () => {
+    render(<Pagination page={1} totalPages={5} onChange={() => {}} />);
+    expect(screen.getByRole('button', { name: 'Previous page' })).toHaveProperty('disabled', true);
+    expect(screen.getByRole('button', { name: 'Next page' })).toHaveProperty('disabled', false);
+  });
+
+  it('disables the next button on the last page', () => {
+    render(<Pagination page={5} totalPages={5} onChange={() => {}} />);
+    expect(screen.getByRole('button', { name: 'Next page' })).toHaveProperty('disabled', true);
+  });
+
+  it('next/previous buttons step the page by one', () => {
+    const onChange = vi.fn();
+    render(<Pagination page={3} totalPages={5} onChange={onChange} />);
+    screen.getByRole('button', { name: 'Next page' }).click();
+    expect(onChange).toHaveBeenLastCalledWith(4);
+    screen.getByRole('button', { name: 'Previous page' }).click();
+    expect(onChange).toHaveBeenLastCalledWith(2);
+  });
+
+  it('shows an ellipsis and jumps to the last page for a large page count', () => {
+    render(<Pagination page={5} totalPages={20} onChange={() => {}} />);
+    expect(screen.getByRole('button', { name: 'Page 1' })).toBeDefined();
+    expect(screen.getByRole('button', { name: 'Page 20' })).toBeDefined();
+    expect(screen.queryAllByText('…').length).toBeGreaterThan(0);
+  });
+
+  it('renders no ellipsis for a small page count', () => {
+    render(<Pagination page={2} totalPages={4} onChange={() => {}} />);
+    expect(screen.queryAllByText('…').length).toBe(0);
+    expect(screen.getAllByRole('button', { name: /^Page \d$/ }).length).toBe(4);
+  });
+});

package/src/components/Progress/Progress.module.css

@@ -0,0 +1,20 @@
+.track {
+  width: 100%;
+  height: 8px;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-surface-sunken);
+  overflow: hidden;
+}
+
+.fill {
+  height: 100%;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-accent);
+  transition: width 0.2s ease;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .fill {
+    transition: none;
+  }
+}

package/src/components/Progress/Progress.stories.tsx

@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Progress } from './Progress';
+
+const meta = {
+  title: 'Components/Progress',
+  component: Progress,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Determinate progress bar. role="progressbar" with aria-valuenow/min/max so screen readers announce the current value. Indeterminate state is out of scope.',
+      },
+    },
+  },
+  args: {
+    value: 40,
+    label: 'Upload progress',
+  },
+} satisfies Meta<typeof Progress>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {};
+
+export const Empty: Story = {
+  args: { value: 0 },
+};
+
+export const Complete: Story = {
+  args: { value: 100 },
+};
+
+export const OverMax: Story = {
+  name: 'Clamped (value > 100)',
+  args: { value: 140 },
+};

package/src/components/Progress/Progress.tsx

@@ -0,0 +1,35 @@
+import styles from './Progress.module.css';
+
+export interface ProgressProps {
+  /** 0–100. Values outside that range are clamped. */
+  value: number;
+  /** Accessible name — Progress has no visible text of its own. */
+  label?: string;
+  id?: string;
+  className?: string;
+}
+
+/**
+ * Progress — determinate bar.
+ *
+ * `role="progressbar"` with `aria-valuenow`/`aria-valuemin`/`aria-valuemax`
+ * so screen readers announce the current value. Indeterminate state is out
+ * of scope until a consumer needs it.
+ */
+export function Progress({ value, label, id, className }: ProgressProps) {
+  const clamped = Math.min(100, Math.max(0, value));
+
+  return (
+    <div
+      id={id}
+      role="progressbar"
+      aria-valuenow={clamped}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-label={label}
+      className={[styles.track, className].filter(Boolean).join(' ')}
+    >
+      <div className={styles.fill} style={{ width: `${clamped}%` }} />
+    </div>
+  );
+}

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

@@ -0,0 +1,31 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { Progress } from '../Progress';
+
+afterEach(cleanup);
+
+describe('Progress', () => {
+  it('exposes progressbar ARIA attributes for the given value', () => {
+    render(<Progress value={40} label="Upload progress" />);
+    const bar = screen.getByRole('progressbar', { name: 'Upload progress' });
+    expect(bar.getAttribute('aria-valuenow')).toBe('40');
+    expect(bar.getAttribute('aria-valuemin')).toBe('0');
+    expect(bar.getAttribute('aria-valuemax')).toBe('100');
+  });
+
+  it('clamps a value above 100', () => {
+    render(<Progress value={140} label="Upload progress" />);
+    expect(screen.getByRole('progressbar').getAttribute('aria-valuenow')).toBe('100');
+  });
+
+  it('clamps a negative value to 0', () => {
+    render(<Progress value={-10} label="Upload progress" />);
+    expect(screen.getByRole('progressbar').getAttribute('aria-valuenow')).toBe('0');
+  });
+
+  it('renders without an accessible name when label is omitted', () => {
+    render(<Progress value={40} />);
+    expect(screen.getByRole('progressbar').getAttribute('aria-label')).toBeNull();
+  });
+});