@sovereignfs/ui 0.45.0 → 0.83.1

package/src/components/Toast/Toast.module.css

@@ -1,7 +1,9 @@
 /* Toast — transient notification snackbar.
  *
- * Fixed top-right, 320px. Slides in from above. Each toast auto-dismisses
- * after `duration` ms. Leading status icon reinforces category at a glance.
+ * Desktop: fixed top-right, 320px, slides in from above. Mobile floats
+ * bottom-center instead (see the media query near the bottom of this file
+ * for why). Each toast auto-dismisses after `duration` ms. Leading status
+ * icon reinforces category at a glance.
  *
  * Category variants map to the semantic status tokens (info/success/warning/
  * error) so the visual language is consistent with banners and badges.
@@ -28,7 +30,7 @@
   padding: var(--sv-space-3) var(--sv-space-4);
   background: var(--sv-color-surface-raised);
   color: var(--sv-color-text-primary);
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   border-radius: var(--sv-radius-md);
   box-shadow: var(--sv-shadow-overlay);
   pointer-events: all;
@@ -124,6 +126,63 @@
   }
 }
 
+/* Mobile (<=768px, the design system's canonical breakpoint): float
+ * bottom-center instead of top-right. Clears any mobile footer/tab bar
+ * (--sv-shell-footer-height) and the home-indicator safe area, plus extra
+ * breathing room so it visibly floats above the edge rather than sitting
+ * flush against it — matches the platform convention (Android Toast,
+ * Material 3's "floating" Snackbar). Deliberately not threaded through
+ * --sv-shell-header-height instead: a toast can appear on a page with or
+ * without a self-rendered mobile header, and bottom-anchoring sidesteps that
+ * entirely rather than requiring every call site to account for it.
+ * Each toast is centered and content-sized (capped at 360px) rather than
+ * stretched to the region's full width, and slides up from below instead of
+ * down from above to match its new anchor. */
+@media (max-width: 768px) {
+  .region {
+    top: auto;
+    left: var(--sv-space-4);
+    right: var(--sv-space-4);
+    bottom: calc(
+      var(--sv-shell-footer-height, 0px) + env(safe-area-inset-bottom, 0px) + var(--sv-space-4)
+    );
+    width: auto;
+    align-items: center;
+  }
+
+  .toast {
+    width: 100%;
+    max-width: 360px;
+    animation-name: toastInMobile;
+  }
+
+  .toast.exiting {
+    animation-name: toastOutMobile;
+  }
+}
+
+@keyframes toastInMobile {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes toastOutMobile {
+  from {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .toast,
   .toast.exiting {

package/src/components/Toast/Toast.stories.tsx

@@ -10,7 +10,7 @@ const meta = {
     docs: {
       description: {
         component:
-          'Fixed top-right notification stack. Use `<ToastProvider>` at the app root and `useToast()` to imperatively show toasts. Each toast has a leading status icon matched to its category.',
+          'Fixed top-right notification stack on desktop; floats bottom-center on mobile (<=768px), clearing any mobile footer/tab bar and the home-indicator safe area. Use `<ToastProvider>` at the app root and `useToast()` to imperatively show toasts. Each toast has a leading status icon matched to its category. Switch the viewport toolbar to a mobile width to see the bottom-center placement.',
       },
     },
   },

package/src/components/Tooltip/Tooltip.module.css

@@ -9,7 +9,7 @@
   white-space: nowrap;
   padding: var(--sv-space-1) var(--sv-space-2);
   background: var(--sv-color-surface-raised);
-  border: 1px solid var(--sv-color-border);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
   border-radius: var(--sv-radius-md);
   box-shadow: var(--sv-shadow-popover);
   font-size: var(--sv-font-size-xs);

package/src/components/UserMenu/UserMenu.module.css

@@ -0,0 +1,90 @@
+.trigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 36px;
+  height: 36px;
+  padding: 0;
+  border: var(--sv-border-width-hairline) solid var(--sv-color-accent);
+  border-radius: var(--sv-radius-full);
+  background-color: var(--sv-color-accent);
+  color: var(--sv-color-text-on-accent);
+  font-size: var(--sv-font-size-xs);
+  font-weight: var(--sv-font-weight-semibold);
+  overflow: hidden;
+  cursor: pointer;
+}
+
+/* The compact `Header` top-bar context's own avatar size. */
+.triggerSm {
+  width: 32px;
+  height: 32px;
+}
+
+.triggerImg {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.panelHeader {
+  padding: var(--sv-space-1) var(--sv-space-1) 0;
+}
+
+.userHeader {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-3);
+  padding: var(--sv-space-2) var(--sv-space-3);
+}
+
+.menuAvatar {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 38px;
+  height: 38px;
+  border-radius: var(--sv-radius-full);
+  background-color: var(--sv-color-accent);
+  color: var(--sv-color-text-on-accent);
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-semibold);
+  overflow: hidden;
+}
+
+.menuAvatarImg {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.userInfo {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.userName {
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-primary);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.userEmail {
+  font-size: var(--sv-font-size-caption);
+  color: var(--sv-color-text-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.divider {
+  margin: var(--sv-space-1) 0 0;
+  border: none;
+  border-top: var(--sv-border-width-hairline) solid var(--sv-color-border);
+}

package/src/components/UserMenu/UserMenu.stories.tsx

@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { UserMenu } from './UserMenu';
+
+const meta = {
+  title: 'Components/UserMenu',
+  component: UserMenu,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'The account avatar trigger + dropdown, generalized from the runtime shell\'s own AccountMenu — accent-filled avatar, name/email header block, then a plain item list. Presentational only: items carry their own onSelect and/or href. size="md" (36px, default) matches the platform sidebar\'s own avatar; size="sm" (32px) suits the more compact Header top-bar context instead.',
+      },
+    },
+  },
+  args: {
+    name: 'Kasun Benthara',
+    email: 'kasun@openfs.io',
+    items: [
+      { label: 'Account', icon: 'user', href: '/account' },
+      { label: 'Preferences', icon: 'sliders-horizontal', href: '/account/preferences' },
+      { label: 'Sign out', icon: 'log-out', destructive: true, onSelect: () => {} },
+    ],
+  },
+} satisfies Meta<typeof UserMenu>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithAvatarImage: Story = {
+  args: {
+    avatarUrl: 'https://i.pravatar.cc/80',
+  },
+};
+
+export const NoUserInfo: Story = {
+  args: {
+    name: undefined,
+    email: undefined,
+  },
+};
+
+export const CompactSize: Story = {
+  args: {
+    size: 'sm',
+  },
+};

package/src/components/UserMenu/UserMenu.tsx

@@ -0,0 +1,132 @@
+'use client';
+
+import { useState } from 'react';
+import type { IconName } from '../Icon/Icon';
+import { MenuEntries, type MenuItem } from '../Menu/Menu';
+import { Popover } from '../Popover/Popover';
+import styles from './UserMenu.module.css';
+
+export interface UserMenuItem {
+  label: string;
+  icon: IconName;
+  /** Optional when `href` is provided (a pure navigation entry needs no
+   *  extra callback). Required otherwise (e.g. "Sign out"). */
+  onSelect?: () => void;
+  /** Renders the entry as a link (`<a href>`) instead of a button — same
+   *  href-vs-onClick convention as `MobileAppsDrawer`'s items. */
+  href?: string;
+  destructive?: boolean;
+}
+
+export interface UserMenuProps {
+  name?: string;
+  email?: string;
+  avatarUrl?: string;
+  items: UserMenuItem[];
+  /** Trigger button's accessible label. Defaults to "Account". */
+  'aria-label'?: string;
+  align?: 'left' | 'right';
+  /** Trigger avatar size: `'md'` (36px) matches the platform sidebar's own
+   *  `.avatar` exactly — the default, for that context. `'sm'` (32px) suits
+   *  the more compact `Header` top-bar context instead. The panel's own
+   *  user-info avatar (38px) is unaffected either way — only the trigger
+   *  scales. */
+  size?: 'sm' | 'md';
+}
+
+function initials(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return '?';
+  const [first = '', second = ''] = trimmed.split(/\s+/);
+  return (second ? first.charAt(0) + second.charAt(0) : first.slice(0, 2)).toUpperCase();
+}
+
+/**
+ * UserMenu — the account avatar trigger + dropdown, generalized from the
+ * runtime shell's own `AccountMenu.tsx` (the real, currently-shipped
+ * component that every `shell: minimal` plugin would otherwise have to
+ * hand-rebuild locally instead of importing). Same visual structure and
+ * copy: an accent-filled avatar trigger (36px, matching the sidebar's own
+ * `.avatar`), a name+email header block (38px avatar) above a divider, then
+ * a plain item list.
+ *
+ * Presentational only — no auth/session/routing logic of its own. The
+ * consumer supplies `items`, each with its own `onSelect` and/or `href`,
+ * matching `MobileHeader`'s "consumer wires it up" boundary; a real
+ * "Sign out" is just an item whose `onSelect` does whatever the consuming
+ * app's sign-out actually requires. Built on the shared `Popover` primitive
+ * (self-contained open state, matching the original's own architecture)
+ * rather than a hand-rolled outside-click/Escape listener — the original
+ * `AccountMenu` and every plugin-local rebuild of it independently re-derive
+ * that same logic; one primitive here means one implementation to get
+ * right. Always a small anchored dropdown, never a full-width sheet —
+ * this is deliberately not built on the adaptive `Menu` component (which
+ * becomes a bottom `Drawer` on mobile): the real account menu is a compact
+ * floating panel on every surface, mobile included.
+ */
+export function UserMenu({
+  name,
+  email,
+  avatarUrl,
+  items,
+  'aria-label': ariaLabel = 'Account',
+  align = 'right',
+  size = 'md',
+}: UserMenuProps) {
+  const [open, setOpen] = useState(false);
+  const displayName = name || email || '';
+
+  return (
+    <Popover
+      align={align}
+      width={240}
+      aria-label={ariaLabel}
+      open={open}
+      onClose={() => setOpen(false)}
+      trigger={
+        <button
+          type="button"
+          aria-label={ariaLabel}
+          aria-haspopup="menu"
+          aria-expanded={open}
+          onClick={() => setOpen((v) => !v)}
+          className={[styles.trigger, size === 'sm' ? styles.triggerSm : '']
+            .filter(Boolean)
+            .join(' ')}
+        >
+          {avatarUrl ? (
+            <img src={avatarUrl} alt="" className={styles.triggerImg} />
+          ) : (
+            initials(displayName)
+          )}
+        </button>
+      }
+    >
+      {displayName && (
+        <div className={styles.panelHeader}>
+          <div className={styles.userHeader}>
+            <span className={styles.menuAvatar} aria-hidden="true">
+              {avatarUrl ? (
+                <img src={avatarUrl} alt="" className={styles.menuAvatarImg} />
+              ) : (
+                initials(displayName)
+              )}
+            </span>
+            <span className={styles.userInfo}>
+              {name && <span className={styles.userName}>{name}</span>}
+              {email && <span className={styles.userEmail}>{email}</span>}
+            </span>
+          </div>
+          <hr className={styles.divider} />
+        </div>
+      )}
+      <MenuEntries
+        items={items}
+        onSelect={(entry: MenuItem) => {
+          setOpen(false);
+          entry.onSelect?.();
+        }}
+      />
+    </Popover>
+  );
+}

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

@@ -0,0 +1,77 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { UserMenu } from '../UserMenu';
+
+afterEach(() => {
+  cleanup();
+});
+
+const items = [
+  { label: 'Account', icon: 'user' as const, href: '/account' },
+  { label: 'Preferences', icon: 'sliders-horizontal' as const, href: '/account/preferences' },
+  { label: 'Sign out', icon: 'log-out' as const, destructive: true, onSelect: vi.fn() },
+];
+
+describe('UserMenu', () => {
+  it('renders a closed trigger by default, showing initials from name', () => {
+    render(<UserMenu name="Jamie Doe" email="jamie@example.com" items={items} />);
+    expect(screen.getByRole('button', { name: 'Account' })).toBeTruthy();
+    expect(screen.getByText('JD')).toBeTruthy();
+    expect(screen.queryByRole('menuitem')).toBeNull();
+  });
+
+  it('opens the panel on trigger click, showing name, email, and items', () => {
+    render(<UserMenu name="Jamie Doe" email="jamie@example.com" items={items} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Account' }));
+
+    expect(screen.getByText('Jamie Doe')).toBeTruthy();
+    expect(screen.getByText('jamie@example.com')).toBeTruthy();
+    expect(screen.getByRole('menuitem', { name: /Account/ })).toBeTruthy();
+    expect(screen.getByRole('menuitem', { name: /Preferences/ })).toBeTruthy();
+    expect(screen.getByRole('menuitem', { name: /Sign out/ })).toBeTruthy();
+  });
+
+  it('renders href items as links', () => {
+    render(<UserMenu name="Jamie Doe" items={items} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Account' }));
+    const accountLink = screen.getByRole('menuitem', { name: /Account/ });
+    expect(accountLink.tagName).toBe('A');
+    expect(accountLink.getAttribute('href')).toBe('/account');
+  });
+
+  it('closes and calls onSelect when a plain item is clicked', () => {
+    const onSelect = vi.fn();
+    render(
+      <UserMenu name="Jamie Doe" items={[{ label: 'Sign out', icon: 'log-out', onSelect }]} />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Account' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: /Sign out/ }));
+    expect(onSelect).toHaveBeenCalledOnce();
+    expect(screen.queryByRole('menuitem')).toBeNull();
+  });
+
+  it('renders no user header block when neither name nor email is provided', () => {
+    render(<UserMenu items={items} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Account' }));
+    expect(screen.queryByText('Jamie Doe')).toBeNull();
+    expect(screen.getByRole('menuitem', { name: /Account/ })).toBeTruthy();
+  });
+
+  it('falls back to email initials when name is omitted', () => {
+    render(<UserMenu email="jamie@example.com" items={items} />);
+    expect(screen.getByText('JA')).toBeTruthy();
+  });
+
+  it('defaults to the md (36px sidebar) trigger size', () => {
+    render(<UserMenu name="Jamie Doe" items={items} />);
+    const trigger = screen.getByRole('button', { name: 'Account' });
+    expect(trigger.className).not.toMatch(/triggerSm/);
+  });
+
+  it('applies the sm (32px, Header top-bar) trigger size when requested', () => {
+    render(<UserMenu name="Jamie Doe" items={items} size="sm" />);
+    const trigger = screen.getByRole('button', { name: 'Account' });
+    expect(trigger.className).toMatch(/triggerSm/);
+  });
+});

package/src/hooks/__tests__/useCarouselRouteSync.test.tsx

@@ -0,0 +1,126 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render } from '@testing-library/react';
+import { useCarouselRouteSync } from '../useCarouselRouteSync';
+
+const SLIDES = ['/a', '/b', '/c'];
+function indexForPathname(pathname: string) {
+  const i = SLIDES.indexOf(pathname);
+  return i === -1 ? 0 : i;
+}
+function pathForIndex(index: number) {
+  return SLIDES[index] ?? '/a';
+}
+
+function Harness({
+  pathname,
+  onNavigate,
+  onResult,
+}: {
+  pathname: string;
+  onNavigate: (path: string) => void;
+  onResult: (result: { activeIndex: number; onSettle: (i: number) => void }) => void;
+}) {
+  const result = useCarouselRouteSync({ indexForPathname, pathForIndex, pathname, onNavigate });
+  onResult(result);
+  return <span data-testid="active">{result.activeIndex}</span>;
+}
+
+afterEach(cleanup);
+
+describe('useCarouselRouteSync', () => {
+  it('initializes activeIndex from the current pathname', () => {
+    const onNavigate = vi.fn();
+    const { getByTestId } = render(
+      <Harness pathname="/b" onNavigate={onNavigate} onResult={() => {}} />,
+    );
+    expect(getByTestId('active').textContent).toBe('1');
+    expect(onNavigate).not.toHaveBeenCalled();
+  });
+
+  it('an external pathname change (tapped Link, browser back/forward) updates activeIndex without calling onNavigate', () => {
+    const onNavigate = vi.fn();
+    const { getByTestId, rerender } = render(
+      <Harness pathname="/a" onNavigate={onNavigate} onResult={() => {}} />,
+    );
+    expect(getByTestId('active').textContent).toBe('0');
+
+    rerender(<Harness pathname="/c" onNavigate={onNavigate} onResult={() => {}} />);
+    expect(getByTestId('active').textContent).toBe('2');
+    expect(onNavigate).not.toHaveBeenCalled();
+  });
+
+  it("onSettle calls onNavigate with pathForIndex's output and updates activeIndex synchronously", () => {
+    const onNavigate = vi.fn();
+    let latest: { activeIndex: number; onSettle: (i: number) => void } = {
+      activeIndex: -1,
+      onSettle: () => {},
+    };
+    const { getByTestId } = render(
+      <Harness
+        pathname="/a"
+        onNavigate={onNavigate}
+        onResult={(r) => {
+          latest = r;
+        }}
+      />,
+    );
+
+    act(() => void latest.onSettle(2));
+
+    expect(getByTestId('active').textContent).toBe('2');
+    expect(onNavigate).toHaveBeenCalledWith('/c');
+    expect(onNavigate).toHaveBeenCalledTimes(1);
+  });
+
+  it('does NOT re-trigger the external-nav branch on the pathname-effect run that follows its own onSettle-driven navigation', () => {
+    // This is the isInternalNav dance: onSettle navigates via onNavigate; the
+    // caller's router then re-renders this hook with the new pathname — that
+    // pathname change must be recognized as "our own settle, already
+    // applied" and NOT reprocessed as an external nav. Both existing plugins'
+    // code comments describe a real double-flicker bug from getting this
+    // wrong, so this is the highest-value assertion in this file.
+    const onNavigate = vi.fn();
+    let latest: { activeIndex: number; onSettle: (i: number) => void } = {
+      activeIndex: -1,
+      onSettle: () => {},
+    };
+    const { getByTestId, rerender } = render(
+      <Harness
+        pathname="/a"
+        onNavigate={onNavigate}
+        onResult={(r) => {
+          latest = r;
+        }}
+      />,
+    );
+
+    // Settle on /b (index 1) — this is the carousel's own gesture-driven navigation.
+    act(() => void latest.onSettle(1));
+    expect(getByTestId('active').textContent).toBe('1');
+    expect(onNavigate).toHaveBeenCalledWith('/b');
+
+    // The caller's router "commits" the navigation by re-rendering with the
+    // new pathname (exactly what onNavigate's real router.replace would
+    // eventually cause). If this were misidentified as an external nav, the
+    // effect would recompute indexForPathname('/b') anyway — same value, so
+    // a bug here wouldn't show up as a *wrong* index, only as an extra,
+    // redundant setState (the actual symptom in the original bug was a
+    // visible re-snap/flicker, not a wrong end state) — so this test also
+    // asserts onNavigate is never called a second time as a side effect of
+    // that re-render, which would happen if the effect treated it as new
+    // settle-worthy input rather than a no-op resync.
+    rerender(<Harness pathname="/b" onNavigate={onNavigate} onResult={(r) => (latest = r)} />);
+
+    expect(getByTestId('active').textContent).toBe('1');
+    expect(onNavigate).toHaveBeenCalledTimes(1);
+  });
+
+  it('an unrecognized pathname falls back to index 0', () => {
+    const onNavigate = vi.fn();
+    const { getByTestId } = render(
+      <Harness pathname="/unknown" onNavigate={onNavigate} onResult={() => {}} />,
+    );
+    expect(getByTestId('active').textContent).toBe('0');
+  });
+});

package/src/hooks/__tests__/useIsOffline.test.tsx

@@ -0,0 +1,53 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render } from '@testing-library/react';
+import { useIsOffline } from '../useIsOffline';
+
+function Harness() {
+  const isOffline = useIsOffline();
+  return <span data-testid="out">{String(isOffline)}</span>;
+}
+
+describe('useIsOffline', () => {
+  beforeEach(() => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: true });
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('reflects navigator.onLine after mount', () => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    const { getByTestId } = render(<Harness />);
+    expect(getByTestId('out').textContent).toBe('true');
+  });
+
+  it('does not report offline when navigator.onLine is true', () => {
+    const { getByTestId } = render(<Harness />);
+    expect(getByTestId('out').textContent).toBe('false');
+  });
+
+  it('flips on the offline event', () => {
+    const { getByTestId } = render(<Harness />);
+    expect(getByTestId('out').textContent).toBe('false');
+    act(() => window.dispatchEvent(new Event('offline')));
+    expect(getByTestId('out').textContent).toBe('true');
+  });
+
+  it('flips back on the online event', () => {
+    vi.stubGlobal('navigator', { ...window.navigator, onLine: false });
+    const { getByTestId } = render(<Harness />);
+    expect(getByTestId('out').textContent).toBe('true');
+    act(() => window.dispatchEvent(new Event('online')));
+    expect(getByTestId('out').textContent).toBe('false');
+  });
+
+  it('removes its listeners on unmount', () => {
+    const removeSpy = vi.spyOn(window, 'removeEventListener');
+    const { unmount } = render(<Harness />);
+    unmount();
+    expect(removeSpy).toHaveBeenCalledWith('offline', expect.any(Function));
+    expect(removeSpy).toHaveBeenCalledWith('online', expect.any(Function));
+  });
+});