@sovereignfs/ui 0.45.0 → 0.83.1

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

@@ -0,0 +1,76 @@
+.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: var(--sv-border-width-hairline) solid var(--sv-color-border);
+  position: sticky;
+  top: 0;
+  z-index: 101;
+  /* WebKit momentum-scroll re-tiling quirk: a position: sticky element with
+     no compositing layer of its own can go stale/blank for a stretch of
+     frames during a fast scroll on iOS Safari instead of repainting at its
+     stuck position — only reachable when a consumer mounts this component
+     inside its own scrolling container (the platform shell's own mobile
+     header sits in a separate, non-scrolling grid row, so this is a no-op
+     there; a plugin self-rendering this via shellConfig.mobileHeader: false
+     inside a scrollable page is exactly the case this protects). Found and
+     fixed across three sticky elements in sovereign-tasks before being
+     applied here proactively — see docs/architecture-rules.md.
+     translateZ(0) promotes it to its own layer, rasterized independently of
+     the scroller's tile grid. */
+  transform: translateZ(0);
+}
+
+.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,90 @@
+'use client';
+
+import { useRef, type HTMLAttributes, type ReactNode } from 'react';
+import { usePublishShellChromeHeight } from '../../hooks/usePublishShellChromeHeight';
+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.
+ *
+ * Self-measures its own rendered height and publishes it as
+ * `--sv-shell-header-height` on the shell root — see
+ * `usePublishShellChromeHeight`'s own doc comment for why this exists (it's
+ * what makes a self-rendered header, the `shellConfig.mobileHeader: false`
+ * pattern, correctly position `Dialog`'s inset and any other consumer of
+ * that variable instead of being overlapped by it).
+ */
+export function MobileHeader({
+  logo,
+  title,
+  bell,
+  avatarMenu,
+  className,
+  ...rest
+}: MobileHeaderProps) {
+  const headerRef = useRef<HTMLDivElement>(null);
+  usePublishShellChromeHeight(headerRef, '--sv-shell-header-height');
+
+  const cls = [styles.header, className].filter(Boolean).join(' ');
+
+  return (
+    <div className={cls} {...rest} ref={headerRef}>
+      <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,113 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { MobileHeader } from '../MobileHeader';
+
+afterEach(() => {
+  cleanup();
+});
+
+describe('MobileHeader self-measured height', () => {
+  afterEach(() => {
+    document.getElementById('sv-app-shell')?.remove();
+    vi.restoreAllMocks();
+  });
+
+  it('publishes its rendered height as --sv-shell-header-height on #sv-app-shell', () => {
+    const shell = document.createElement('div');
+    shell.id = 'sv-app-shell';
+    document.body.appendChild(shell);
+    vi.spyOn(Element.prototype, 'getBoundingClientRect').mockReturnValue({
+      height: 60,
+      width: 0,
+      top: 0,
+      left: 0,
+      right: 0,
+      bottom: 0,
+      x: 0,
+      y: 0,
+      toJSON() {},
+    } as DOMRect);
+
+    render(<MobileHeader bell={<span />} avatarMenu={<span />} />);
+
+    expect(shell.style.getPropertyValue('--sv-shell-header-height')).toBe('60px');
+  });
+
+  it('removes the override on unmount', () => {
+    const shell = document.createElement('div');
+    shell.id = 'sv-app-shell';
+    document.body.appendChild(shell);
+    vi.spyOn(Element.prototype, 'getBoundingClientRect').mockReturnValue({
+      height: 60,
+      width: 0,
+      top: 0,
+      left: 0,
+      right: 0,
+      bottom: 0,
+      x: 0,
+      y: 0,
+      toJSON() {},
+    } as DOMRect);
+
+    const { unmount } = render(<MobileHeader bell={<span />} avatarMenu={<span />} />);
+    expect(shell.style.getPropertyValue('--sv-shell-header-height')).toBe('60px');
+
+    unmount();
+    expect(shell.style.getPropertyValue('--sv-shell-header-height')).toBe('');
+  });
+
+  it('never throws when #sv-app-shell is absent (Storybook, unit tests, other hosts)', () => {
+    expect(() => render(<MobileHeader bell={<span />} avatarMenu={<span />} />)).not.toThrow();
+  });
+});
+
+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/NavList/NavList.module.css

@@ -0,0 +1,130 @@
+.nav {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sv-space-5);
+  width: 100%;
+}
+
+.group {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.groupLabel {
+  padding: 0 var(--sv-space-3);
+  margin-bottom: var(--sv-space-1);
+  font-size: var(--sv-font-size-xs);
+  font-weight: var(--sv-font-weight-semibold);
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--sv-color-text-muted);
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-3);
+  min-height: var(--sv-touch-target-min);
+  padding: var(--sv-space-2) var(--sv-space-3);
+  border-radius: var(--sv-radius-md);
+  color: var(--sv-color-text-muted);
+  text-decoration: none;
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-medium);
+}
+
+.icon {
+  flex-shrink: 0;
+}
+
+.label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.badge {
+  flex-shrink: 0;
+  color: var(--sv-color-text-muted);
+  font-size: var(--sv-font-size-xs);
+}
+
+.chevron {
+  flex-shrink: 0;
+  color: var(--sv-color-text-muted);
+}
+
+/* ── static (desktop sidebar) ─────────────────────────────────────────── */
+
+.static .row {
+  transition:
+    background-color 0.1s ease,
+    color 0.1s ease;
+}
+
+@media (hover: hover) {
+  .static .row:hover {
+    background-color: var(--sv-color-surface-sunken);
+    color: var(--sv-color-text-primary);
+  }
+}
+
+.static .row:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: -2px;
+}
+
+.static .rowActive {
+  background-color: var(--sv-color-surface-sunken);
+  color: var(--sv-color-text-primary);
+  font-weight: var(--sv-font-weight-semibold);
+}
+
+.static .rowActive .icon {
+  color: var(--sv-color-text-primary);
+}
+
+/* Only meaningful combined with .static — see NavListProps.density's own
+   doc comment for why .drilldown rows never shrink. */
+.compact.static .row {
+  min-height: 0;
+  padding: var(--sv-space-2) var(--sv-space-3);
+}
+
+/* ── drilldown (mobile index) — grouped card, native-Settings-app rows ──── */
+
+.drilldown .group {
+  gap: 0;
+  border: 1px solid var(--sv-color-border);
+  border-radius: var(--sv-radius-lg);
+  overflow: hidden;
+  background-color: var(--sv-color-surface-raised);
+}
+
+.drilldown .row {
+  border-radius: 0;
+  padding: var(--sv-space-3) var(--sv-space-4);
+  color: var(--sv-color-text-primary);
+}
+
+.drilldown .row:not(:last-child) {
+  border-bottom: var(--sv-border-width-hairline) solid var(--sv-color-border);
+}
+
+@media (hover: hover) {
+  .drilldown .row:hover {
+    background-color: var(--sv-color-surface-sunken);
+  }
+}
+
+.drilldown .row:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: -2px;
+}
+
+.drilldown .icon {
+  color: var(--sv-color-text-muted);
+}

package/src/components/NavList/NavList.tsx

@@ -0,0 +1,136 @@
+import { Fragment, type ReactNode } from 'react';
+import { Icon } from '../Icon/Icon';
+import type { IconName } from '../Icon/Icon';
+import styles from './NavList.module.css';
+
+export interface NavListItem {
+  id: string;
+  label: string;
+  href: string;
+  icon: IconName;
+  /** Trailing content, e.g. a count — reserved for a future consumer, not used by `variant="drilldown"`'s own chevron slot. */
+  badge?: ReactNode;
+  /**
+   * Only meaningful for `variant="static"` — whether this row represents the
+   * current page. Computed by the consumer (e.g. via `usePathname()` plus a
+   * longest-prefix match against every item's `href`), since this package
+   * doesn't depend on `next/navigation` — same reasoning as `NavTabs`.
+   */
+  active?: boolean;
+}
+
+export interface NavListGroup {
+  id: string;
+  /** Omit for an ungrouped leading item/group — e.g. a pinned "Overview" row above the grouped sections. */
+  label?: string;
+  items: NavListItem[];
+}
+
+/** Props to spread onto a consumer-supplied link element — mirrors `NavTabs`' `NavTabLinkProps`. */
+export interface NavListLinkProps {
+  href: string;
+  className: string;
+  'aria-current': 'page' | undefined;
+  children: ReactNode;
+}
+
+export interface NavListProps {
+  groups: NavListGroup[];
+  /**
+   * `"static"`: active row highlighted via `item.active`, no chevron — a
+   * persistent sidebar nav. `"drilldown"`: every row gets a trailing chevron
+   * and no active-state, tapping navigates to a full-screen section — a
+   * native Settings-app style index.
+   */
+  variant: 'static' | 'drilldown';
+  /**
+   * `"default"`: each row is a full `--sv-touch-target-min` tall tap target
+   * — the right choice for `variant="drilldown"`'s mobile index, and for any
+   * `static` sidebar list long enough that scanability matters more than
+   * density. `"compact"` shrinks row height/padding for a short, always-
+   * visible `static` list (e.g. 2-4 items above a longer scrollable list of
+   * something else) where the default's touch-target height reads as
+   * needlessly spaced out. Only meaningful for `variant="static"` —
+   * `drilldown` rows stay full-height regardless, since that variant is
+   * mobile-only and touch-target size there isn't optional. Defaults to
+   * `"default"` so every existing consumer (e.g. Console's own sidebar) is
+   * visually unchanged.
+   */
+  density?: 'default' | 'compact';
+  'aria-label': string;
+  className?: string;
+  /**
+   * Render a row as something other than a plain `<a href>` — e.g. Next's
+   * `<Link>`. Receives the item plus the class name/aria attributes NavList
+   * would otherwise apply, matching `NavTabs`' `renderLink` contract.
+   */
+  renderLink?: (item: NavListItem, linkProps: NavListLinkProps) => ReactNode;
+}
+
+/**
+ * NavList — a vertical list of icon+label rows, optionally grouped under
+ * section headers. Two presentations of the same `groups` data: `static` (a
+ * persistent sidebar, active item highlighted) and `drilldown` (a
+ * native-Settings-app style index, every row navigates to a full section).
+ *
+ * Framework-agnostic like `NavTabs` — no `next/navigation`/`next/link`
+ * import, no internal pathname reading. Active state and navigation behavior
+ * are supplied by the consumer via `item.active` and `renderLink`.
+ */
+export function NavList({
+  groups,
+  variant,
+  density = 'default',
+  'aria-label': ariaLabel,
+  className,
+  renderLink,
+}: NavListProps) {
+  return (
+    <nav
+      className={[styles.nav, styles[variant], density === 'compact' && styles.compact, className]
+        .filter(Boolean)
+        .join(' ')}
+      aria-label={ariaLabel}
+    >
+      {groups.map((group) => (
+        <div key={group.id} className={styles.group}>
+          {group.label && <div className={styles.groupLabel}>{group.label}</div>}
+          {group.items.map((item) => {
+            const isActive = variant === 'static' && !!item.active;
+            const rowContent = (
+              <>
+                <Icon name={item.icon} size="sm" aria-hidden className={styles.icon} />
+                <span className={styles.label}>{item.label}</span>
+                {item.badge && <span className={styles.badge}>{item.badge}</span>}
+                {variant === 'drilldown' && (
+                  <Icon name="chevron-right" size="sm" aria-hidden className={styles.chevron} />
+                )}
+              </>
+            );
+            const linkProps: NavListLinkProps = {
+              href: item.href,
+              className: [styles.row, isActive && styles.rowActive].filter(Boolean).join(' '),
+              'aria-current': isActive ? 'page' : undefined,
+              children: rowContent,
+            };
+            return (
+              <Fragment key={item.id}>
+                {renderLink ? (
+                  renderLink(item, linkProps)
+                ) : (
+                  <a
+                    href={linkProps.href}
+                    className={linkProps.className}
+                    aria-current={linkProps['aria-current']}
+                  >
+                    {linkProps.children}
+                  </a>
+                )}
+              </Fragment>
+            );
+          })}
+        </div>
+      ))}
+    </nav>
+  );
+}