@sovereignfs/ui 0.41.0 → 0.54.0

package/src/components/MobileHeader/MobileHeader.module.css

@@ -0,0 +1,63 @@
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--sv-space-3);
+  width: 100%;
+  /* Mobile-only component — never render wider than the platform's own
+     mobile breakpoint, even if a consumer accidentally mounts it in a wider
+     container (e.g. an un-gated preview). At real mobile widths this is a
+     no-op since the viewport itself is already narrower. */
+  max-width: 768px;
+  margin-inline: auto;
+  min-height: var(--sv-shell-header-height, 60px);
+  padding: var(--sv-space-3) var(--sv-space-4);
+  padding-top: max(var(--sv-space-3), env(safe-area-inset-top));
+  padding-right: max(var(--sv-space-4), env(safe-area-inset-right));
+  padding-left: max(var(--sv-space-4), env(safe-area-inset-left));
+  background-color: var(--sv-color-surface);
+  border-bottom: 1px solid var(--sv-color-border);
+  position: sticky;
+  top: 0;
+  z-index: 101;
+}
+
+.brandGroup {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-3);
+  min-width: 0;
+}
+
+/* Matches the runtime shell's own .mobileBrandIcon (shell.module.css) — the
+   default logo shown when the consumer doesn't supply one. */
+.defaultLogo {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 36px;
+  height: 36px;
+  border-radius: var(--sv-radius-md);
+  background-color: var(--sv-color-accent);
+  color: var(--sv-color-text-on-accent);
+  font-weight: var(--sv-font-weight-semibold);
+  overflow: hidden;
+}
+
+.title {
+  font-size: var(--sv-font-size-md);
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-primary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.right {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-2);
+  margin-left: auto;
+  flex-shrink: 0;
+}

package/src/components/MobileHeader/MobileHeader.stories.tsx

@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { MobileHeader } from './MobileHeader';
+import { Avatar } from '../Avatar/Avatar';
+import { Icon } from '../Icon/Icon';
+
+function Logo() {
+  return (
+    <span
+      aria-label="Home"
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: 28,
+        height: 28,
+        borderRadius: 'var(--sv-radius-sm)',
+        background: 'var(--sv-color-accent)',
+        color: 'var(--sv-color-text-on-accent)',
+        fontWeight: 700,
+        fontSize: 13,
+        flexShrink: 0,
+      }}
+    >
+      S
+    </span>
+  );
+}
+
+const meta = {
+  title: 'Components/MobileHeader',
+  component: MobileHeader,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Mobile shell header content row (RFC 0088). Logo, bell, and avatarMenu are always rendered by the consumer — the optional title is the only overridable part. Presentational only, no data fetching. See Overview/Mobile Patterns for the full immutable/overridable boundary.',
+      },
+    },
+  },
+  args: {
+    logo: <Logo />,
+    bell: <Icon name="bell" size="md" aria-label="Notifications" />,
+    avatarMenu: <Avatar name="Jamie Doe" size="sm" />,
+  },
+} satisfies Meta<typeof MobileHeader>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithTitle: Story = {
+  args: {
+    title: 'Tasks',
+  },
+};

package/src/components/MobileHeader/MobileHeader.tsx

@@ -0,0 +1,77 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import styles from './MobileHeader.module.css';
+
+export interface MobileHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  /** The brand/logo element — already a complete, clickable link home (e.g. an
+   * instance logo wrapped in the consumer's own router `Link`). Always
+   * rendered. `MobileHeader` stays router-agnostic, so this is provided
+   * fully built rather than as a bare icon + href. Optional — omit it to get
+   * a default "S" badge (matching the runtime shell's own fallback brand
+   * icon when no instance logo is configured), sized and styled to the same
+   * 36px/radius-md convention a custom logo is expected to follow. */
+  logo?: ReactNode;
+  /** Optional contextual title rendered beside the logo (e.g. the active
+   * plugin's name). Absent by default — this is the one overridable part of
+   * the header. See RFC 0088. */
+  title?: string;
+  /** Notification bell — always rendered; not overridable.
+   * TODO: this is just an icon slot today (the consumer wires up its own
+   * click handler/content) — it doesn't yet accommodate a full notification
+   * feature (unread badge, dropdown panel, etc. — see the runtime shell's
+   * own NotificationBell). Deferred; revisit once a plugin actually needs
+   * more than a bare bell icon here. */
+  bell: ReactNode;
+  /** Avatar / account menu trigger — always rendered; not overridable. */
+  avatarMenu: ReactNode;
+}
+
+/** Default fallback logo — matches the runtime shell's own .mobileBrandIcon
+ *  exactly (36px, radius-md, accent background) for the "no instance logo
+ *  configured" case, just with a fixed "S" instead of the instance name's
+ *  first letter (this component can't know the instance name — no data
+ *  fetching, see the component's own doc comment). */
+function DefaultLogo() {
+  return (
+    <span className={styles.defaultLogo} aria-hidden="true">
+      S
+    </span>
+  );
+}
+
+/**
+ * The mobile header bar: brand/logo (always shown), an optional contextual
+ * title, and a fixed bell + avatar-menu cluster. Owns its own chrome —
+ * background, border-bottom, sticky positioning, safe-area-aware padding,
+ * and a 768px max-width (so it never stretches full-bleed if mounted outside
+ * an actual mobile viewport) — matching the runtime shell's own mobile
+ * header exactly, since this component is meant to replace that hand-rolled
+ * markup. Presentational only — no data fetching; the consumer supplies
+ * `bell`/`avatarMenu` (and, optionally, `logo`) as already-wired components
+ * (their own sizing — 36px logo/avatar, 44px bell tap target — is the
+ * consumer's responsibility, matching the reference implementation in the
+ * runtime shell). See RFC 0088 for the immutable/overridable boundary this
+ * enforces.
+ */
+export function MobileHeader({
+  logo,
+  title,
+  bell,
+  avatarMenu,
+  className,
+  ...rest
+}: MobileHeaderProps) {
+  const cls = [styles.header, className].filter(Boolean).join(' ');
+
+  return (
+    <div className={cls} {...rest}>
+      <div className={styles.brandGroup}>
+        {logo ?? <DefaultLogo />}
+        {title && <span className={styles.title}>{title}</span>}
+      </div>
+      <div className={styles.right}>
+        {bell}
+        {avatarMenu}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { MobileHeader } from '../MobileHeader';
+
+afterEach(() => {
+  cleanup();
+});
+
+describe('MobileHeader', () => {
+  it('always renders the logo, bell, and avatar menu slots', () => {
+    render(
+      <MobileHeader
+        logo={<a href="/">logo</a>}
+        bell={<span data-testid="bell">bell</span>}
+        avatarMenu={<span data-testid="avatar">avatar</span>}
+      />,
+    );
+
+    expect(screen.getByText('logo')).toBeDefined();
+    expect(screen.getByTestId('bell')).toBeDefined();
+    expect(screen.getByTestId('avatar')).toBeDefined();
+  });
+
+  it('renders no title by default', () => {
+    render(<MobileHeader logo={<a href="/">logo</a>} bell={<span />} avatarMenu={<span />} />);
+
+    expect(screen.queryByText(/tasks/i)).toBeNull();
+  });
+
+  it('renders the optional title when provided', () => {
+    render(
+      <MobileHeader
+        logo={<a href="/">logo</a>}
+        title="Tasks"
+        bell={<span />}
+        avatarMenu={<span />}
+      />,
+    );
+
+    expect(screen.getByText('Tasks')).toBeDefined();
+  });
+
+  it('renders a default "S" badge when logo is omitted', () => {
+    render(<MobileHeader bell={<span />} avatarMenu={<span />} />);
+
+    expect(screen.getByText('S')).toBeDefined();
+  });
+
+  it('renders the supplied logo instead of the default badge when provided', () => {
+    render(
+      <MobileHeader logo={<a href="/">custom logo</a>} bell={<span />} avatarMenu={<span />} />,
+    );
+
+    expect(screen.getByText('custom logo')).toBeDefined();
+    expect(screen.queryByText('S')).toBeNull();
+  });
+});

package/src/components/NavTabs/NavTabs.tsx

@@ -1,3 +1,4 @@
+import { Fragment, type ReactNode } from 'react';
 import styles from './NavTabs.module.css';
 
 export interface NavTabItem {
@@ -6,28 +7,55 @@ export interface NavTabItem {
   active?: boolean;
 }
 
+/** Props to spread onto a consumer-supplied link element — keeps NavTabs' own
+ * class names and a11y attributes in sync with whatever the consumer renders. */
+export interface NavTabLinkProps {
+  href: string;
+  className: string;
+  'aria-current': 'page' | undefined;
+  children: ReactNode;
+}
+
 export interface NavTabsProps {
   items: NavTabItem[];
   className?: string;
   'aria-label'?: string;
+  /** Render a tab as something other than a plain `<a href>` — e.g. Next's
+   * `<Link replace>` inside an overlay-shell plugin, where a full page
+   * navigation would break the dialog's history contract. Receives the item
+   * plus the class name/aria attributes NavTabs would otherwise apply. */
+  renderLink?: (item: NavTabItem, linkProps: NavTabLinkProps) => ReactNode;
 }
 
-export function NavTabs({ items, className, 'aria-label': ariaLabel }: NavTabsProps) {
+export function NavTabs({ items, className, 'aria-label': ariaLabel, renderLink }: NavTabsProps) {
   return (
     <nav
       className={[styles.nav, className].filter(Boolean).join(' ')}
       aria-label={ariaLabel ?? 'Page navigation'}
     >
-      {items.map((item) => (
-        <a
-          key={item.href}
-          href={item.href}
-          className={[styles.link, item.active && styles.active].filter(Boolean).join(' ')}
-          aria-current={item.active ? 'page' : undefined}
-        >
-          {item.label}
-        </a>
-      ))}
+      {items.map((item) => {
+        const linkProps: NavTabLinkProps = {
+          href: item.href,
+          className: [styles.link, item.active && styles.active].filter(Boolean).join(' '),
+          'aria-current': item.active ? 'page' : undefined,
+          children: item.label,
+        };
+        return (
+          <Fragment key={item.href}>
+            {renderLink ? (
+              renderLink(item, linkProps)
+            ) : (
+              <a
+                href={linkProps.href}
+                className={linkProps.className}
+                aria-current={linkProps['aria-current']}
+              >
+                {linkProps.children}
+              </a>
+            )}
+          </Fragment>
+        );
+      })}
     </nav>
   );
 }

package/src/components/NavigationMenu/NavigationMenu.module.css

@@ -0,0 +1,53 @@
+.nav {
+  min-width: 0;
+}
+
+.list {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-1);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.link,
+.trigger {
+  display: inline-flex;
+  align-items: center;
+  height: 36px;
+  padding: 0 var(--sv-space-3);
+  border: none;
+  border-radius: var(--sv-radius-md);
+  background: transparent;
+  color: var(--sv-color-text-primary);
+  font-family: var(--sv-font-family);
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-medium);
+  text-decoration: none;
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .link:hover,
+  .trigger:hover {
+    background: var(--sv-color-surface-sunken);
+  }
+}
+
+.link:focus-visible,
+.trigger:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+}
+
+.triggerOpen {
+  background: var(--sv-color-surface-sunken);
+}
+
+@media (pointer: coarse) {
+  .link,
+  .trigger {
+    min-height: var(--sv-touch-target-min, 44px);
+  }
+}

package/src/components/NavigationMenu/NavigationMenu.stories.tsx

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { NavigationMenu } from './NavigationMenu';
+
+const meta = {
+  title: 'Components/NavigationMenu',
+  component: NavigationMenu,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Top-level nav bar where some items open a flyout panel. Desktop-oriented by design — a hover-triggered flyout bar has no mobile equivalent. Once one flyout is open, hovering a sibling switches directly to it; ArrowLeft/ArrowRight move focus between triggers.',
+      },
+    },
+  },
+  args: { 'aria-label': 'Main' },
+} satisfies Meta<typeof NavigationMenu>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+const FlyoutContent = ({ links }: { links: string[] }) => (
+  <div style={{ padding: 'var(--sv-space-3)', display: 'flex', flexDirection: 'column', gap: 4 }}>
+    {links.map((link) => (
+      <a
+        key={link}
+        href={`/${link.toLowerCase().replace(/\s+/g, '-')}`}
+        style={{
+          fontSize: 14,
+          color: 'var(--sv-color-text-primary)',
+          textDecoration: 'none',
+          padding: 'var(--sv-space-1) var(--sv-space-2)',
+        }}
+      >
+        {link}
+      </a>
+    ))}
+  </div>
+);
+
+export const Default: Story = {
+  args: {
+    items: [
+      { label: 'Home', href: '/home' },
+      {
+        label: 'Products',
+        content: <FlyoutContent links={['Tasks', 'Ledger', 'Shopper', 'Wallet']} />,
+      },
+      {
+        label: 'Company',
+        content: <FlyoutContent links={['About', 'Blog', 'Careers']} />,
+      },
+      { label: 'Docs', href: '/docs' },
+    ],
+  },
+};

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