@sovereignfs/ui 0.40.0 → 0.45.0

package/src/components/NavigationMenu/NavigationMenu.tsx

@@ -0,0 +1,125 @@
+'use client';
+
+import { useRef, useState } from 'react';
+import type { ReactNode, KeyboardEvent as ReactKeyboardEvent } from 'react';
+import { Popover } from '../Popover/Popover';
+import styles from './NavigationMenu.module.css';
+
+export interface NavigationMenuItem {
+  label: string;
+  /** A plain link with no flyout — mutually exclusive with `content`. */
+  href?: string;
+  /** Flyout panel content shown when this item is triggered. Pass a
+   * function instead of a plain node when the content needs to close its
+   * own flyout after an action (e.g. `Menubar`'s menu items) — it receives
+   * a `close` callback. */
+  content?: ReactNode | ((close: () => void) => ReactNode);
+}
+
+export interface NavigationMenuProps {
+  items: NavigationMenuItem[];
+  /** Renders a plain-link item's anchor. Defaults to `<a href>`, which
+   * causes a full page reload — pass Next's `<Link>` (or equivalent) to
+   * keep navigation client-side. */
+  renderLink?: (href: string, children: ReactNode) => ReactNode;
+  'aria-label'?: string;
+}
+
+/**
+ * NavigationMenu — top-level nav bar where some items open a flyout panel.
+ *
+ * Desktop-oriented by design — a hover-triggered flyout bar has no mobile
+ * equivalent (Research 0004); it renders as-is on touch rather than
+ * attempting a redesign no consumer has asked for yet.
+ *
+ * Each flyout is its own `Popover` instance rather than one shared
+ * positioned panel, reusing its collision detection per item. Once one
+ * flyout is open, moving the pointer to a sibling trigger switches directly
+ * to that one — standard menu-bar behavior — and ArrowLeft/ArrowRight move
+ * focus between top-level triggers (a roving-tabindex bar, per the
+ * WAI-ARIA menu pattern), Escape closes.
+ */
+export function NavigationMenu({
+  items,
+  renderLink,
+  'aria-label': ariaLabel,
+}: NavigationMenuProps) {
+  const [openIndex, setOpenIndex] = useState<number | null>(null);
+  const triggerRefs = useRef<(HTMLButtonElement | null)[]>([]);
+
+  function handleKeyDown(e: ReactKeyboardEvent, index: number) {
+    if (e.key === 'Escape') {
+      setOpenIndex(null);
+      triggerRefs.current[index]?.focus();
+      return;
+    }
+    if (e.key === 'ArrowRight' || e.key === 'ArrowLeft') {
+      e.preventDefault();
+      const direction = e.key === 'ArrowRight' ? 1 : -1;
+      const nextIndex = (index + direction + items.length) % items.length;
+      triggerRefs.current[nextIndex]?.focus();
+    }
+  }
+
+  return (
+    <nav aria-label={ariaLabel} className={styles.nav}>
+      <ul className={styles.list}>
+        {items.map((item, index) => {
+          if (!item.content) {
+            const linkChildren = item.label;
+            return (
+              <li key={item.label}>
+                {item.href && renderLink ? (
+                  renderLink(item.href, linkChildren)
+                ) : (
+                  <a href={item.href} className={styles.link}>
+                    {linkChildren}
+                  </a>
+                )}
+              </li>
+            );
+          }
+
+          const isOpen = openIndex === index;
+          return (
+            <li key={item.label}>
+              <Popover
+                aria-label={item.label}
+                open={isOpen}
+                onClose={() => setOpenIndex((current) => (current === index ? null : current))}
+                trigger={
+                  <button
+                    ref={(el) => {
+                      triggerRefs.current[index] = el;
+                    }}
+                    type="button"
+                    className={[styles.trigger, isOpen ? styles.triggerOpen : '']
+                      .filter(Boolean)
+                      .join(' ')}
+                    aria-expanded={isOpen}
+                    onClick={() => setOpenIndex((current) => (current === index ? null : index))}
+                    onMouseEnter={() => {
+                      // Once a sibling is already open, hovering another
+                      // trigger switches directly to it — standard menu-bar
+                      // behavior. Otherwise hovering alone does not open
+                      // one; that stays an explicit click, since a nav bar
+                      // (unlike HoverCard) isn't a "preview" surface.
+                      setOpenIndex((current) => (current !== null ? index : current));
+                    }}
+                    onKeyDown={(e) => handleKeyDown(e, index)}
+                  >
+                    {item.label}
+                  </button>
+                }
+              >
+                {typeof item.content === 'function'
+                  ? item.content(() => setOpenIndex(null))
+                  : item.content}
+              </Popover>
+            </li>
+          );
+        })}
+      </ul>
+    </nav>
+  );
+}

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

@@ -0,0 +1,93 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen, fireEvent } from '@testing-library/react';
+import { NavigationMenu } from '../NavigationMenu';
+
+afterEach(cleanup);
+
+const items = [
+  { label: 'Home', href: '/home' },
+  { label: 'Products', content: <div>Products flyout</div> },
+  { label: 'Company', content: <div>Company flyout</div> },
+];
+
+describe('NavigationMenu', () => {
+  it('renders a plain link for an item with no content', () => {
+    render(<NavigationMenu items={items} aria-label="Main" />);
+    const link = screen.getByRole('link', { name: 'Home' });
+    expect(link.getAttribute('href')).toBe('/home');
+  });
+
+  it('renders a toggle trigger for an item with content, collapsed by default', () => {
+    render(<NavigationMenu items={items} aria-label="Main" />);
+    expect(screen.getByRole('button', { name: 'Products' }).getAttribute('aria-expanded')).toBe(
+      'false',
+    );
+  });
+
+  it('opens a flyout on trigger click', () => {
+    render(<NavigationMenu items={items} aria-label="Main" />);
+    fireEvent.click(screen.getByRole('button', { name: 'Products' }));
+    expect(screen.getByText('Products flyout')).toBeDefined();
+  });
+
+  it('closes on a second click of the same trigger', () => {
+    render(<NavigationMenu items={items} aria-label="Main" />);
+    const trigger = screen.getByRole('button', { name: 'Products' });
+    fireEvent.click(trigger);
+    fireEvent.click(trigger);
+    expect(screen.queryByText('Products flyout')).toBeNull();
+  });
+
+  it('switches directly to a sibling on hover once one flyout is already open', () => {
+    render(<NavigationMenu items={items} aria-label="Main" />);
+    fireEvent.click(screen.getByRole('button', { name: 'Products' }));
+    expect(screen.getByText('Products flyout')).toBeDefined();
+
+    fireEvent.mouseEnter(screen.getByRole('button', { name: 'Company' }));
+    expect(screen.getByText('Company flyout')).toBeDefined();
+    expect(screen.queryByText('Products flyout')).toBeNull();
+  });
+
+  it('does not open a flyout on hover alone when nothing else is open', () => {
+    render(<NavigationMenu items={items} aria-label="Main" />);
+    fireEvent.mouseEnter(screen.getByRole('button', { name: 'Products' }));
+    expect(screen.queryByText('Products flyout')).toBeNull();
+  });
+
+  it('ArrowRight/ArrowLeft move focus between top-level triggers', () => {
+    render(<NavigationMenu items={items} aria-label="Main" />);
+    const products = screen.getByRole('button', { name: 'Products' });
+    const company = screen.getByRole('button', { name: 'Company' });
+    products.focus();
+    fireEvent.keyDown(products, { key: 'ArrowRight' });
+    expect(document.activeElement).toBe(company);
+    fireEvent.keyDown(company, { key: 'ArrowLeft' });
+    expect(document.activeElement).toBe(products);
+  });
+
+  it('Escape closes the open flyout and returns focus to its trigger', () => {
+    render(<NavigationMenu items={items} aria-label="Main" />);
+    const trigger = screen.getByRole('button', { name: 'Products' });
+    fireEvent.click(trigger);
+    fireEvent.keyDown(trigger, { key: 'Escape' });
+    expect(screen.queryByText('Products flyout')).toBeNull();
+    expect(document.activeElement).toBe(trigger);
+  });
+
+  it('uses a caller-supplied renderLink for plain links instead of a bare <a>', () => {
+    render(
+      <NavigationMenu
+        items={items}
+        aria-label="Main"
+        renderLink={(href, children) => (
+          <button type="button" data-href={href}>
+            {children}
+          </button>
+        )}
+      />,
+    );
+    expect(screen.queryByRole('link', { name: 'Home' })).toBeNull();
+    expect(screen.getByRole('button', { name: 'Home' })).toHaveProperty('dataset.href', '/home');
+  });
+});

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