@sovereignfs/ui 0.41.0 → 0.54.0

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

@@ -0,0 +1,105 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen, fireEvent } from '@testing-library/react';
+import { MessageScroller } from '../MessageScroller';
+
+afterEach(cleanup);
+
+/** jsdom doesn't implement layout, so scrollHeight/clientHeight are always 0
+ * unless stubbed. Mirrors the common pattern for testing scroll behavior. */
+function stubScrollMetrics(
+  el: HTMLElement,
+  {
+    scrollHeight,
+    clientHeight,
+    scrollTop,
+  }: {
+    scrollHeight: number;
+    clientHeight: number;
+    scrollTop: number;
+  },
+) {
+  Object.defineProperty(el, 'scrollHeight', { value: scrollHeight, configurable: true });
+  Object.defineProperty(el, 'clientHeight', { value: clientHeight, configurable: true });
+  Object.defineProperty(el, 'scrollTop', { value: scrollTop, writable: true, configurable: true });
+}
+
+describe('MessageScroller', () => {
+  it('auto-scrolls to the bottom when near-bottom and children change', () => {
+    const { container, rerender } = render(
+      <MessageScroller>
+        <div>message 1</div>
+      </MessageScroller>,
+    );
+    const scrollEl = container.querySelector('[class*="scrollContainer"]') as HTMLElement;
+    stubScrollMetrics(scrollEl, { scrollHeight: 500, clientHeight: 200, scrollTop: 0 });
+
+    rerender(
+      <MessageScroller>
+        <div>message 1</div>
+        <div>message 2</div>
+      </MessageScroller>,
+    );
+
+    expect(scrollEl.scrollTop).toBe(500);
+    expect(screen.queryByText('New messages ↓')).toBeNull();
+  });
+
+  it('shows a "New messages" button instead of auto-scrolling when scrolled up', () => {
+    const { container, rerender } = render(
+      <MessageScroller>
+        <div>message 1</div>
+      </MessageScroller>,
+    );
+    const scrollEl = container.querySelector('[class*="scrollContainer"]') as HTMLElement;
+    // Simulate the user having scrolled up, far from the bottom.
+    stubScrollMetrics(scrollEl, { scrollHeight: 500, clientHeight: 200, scrollTop: 0 });
+    fireEvent.scroll(scrollEl);
+
+    rerender(
+      <MessageScroller>
+        <div>message 1</div>
+        <div>message 2</div>
+      </MessageScroller>,
+    );
+
+    expect(screen.getByText('New messages ↓')).toBeDefined();
+  });
+
+  it('scrolling back near the bottom does not force scrollTop (no fighting the user)', () => {
+    const { container } = render(
+      <MessageScroller>
+        <div>message 1</div>
+      </MessageScroller>,
+    );
+    const scrollEl = container.querySelector('[class*="scrollContainer"]') as HTMLElement;
+    stubScrollMetrics(scrollEl, { scrollHeight: 500, clientHeight: 200, scrollTop: 450 });
+    fireEvent.scroll(scrollEl);
+
+    expect(scrollEl.scrollTop).toBe(450);
+  });
+
+  it('clicking the jump button scrolls to bottom and hides the button', () => {
+    const { container, rerender } = render(
+      <MessageScroller>
+        <div>message 1</div>
+      </MessageScroller>,
+    );
+    const scrollEl = container.querySelector('[class*="scrollContainer"]') as HTMLElement;
+    stubScrollMetrics(scrollEl, { scrollHeight: 500, clientHeight: 200, scrollTop: 0 });
+    fireEvent.scroll(scrollEl);
+    rerender(
+      <MessageScroller>
+        <div>message 1</div>
+        <div>message 2</div>
+      </MessageScroller>,
+    );
+    expect(screen.getByText('New messages ↓')).toBeDefined();
+
+    scrollEl.scrollTo = vi.fn();
+    fireEvent.click(screen.getByText('New messages ↓'));
+
+    expect(scrollEl.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: 'smooth' });
+    expect(screen.queryByText('New messages ↓')).toBeNull();
+  });
+});

package/src/components/MobileAppsDrawer/MobileAppsDrawer.module.css

@@ -0,0 +1,81 @@
+/* Matches the runtime shell's own Apps drawer grid exactly
+   (runtime/app/(platform)/_components/MobileNav.module.css's .drawerGrid/
+   .drawerGridItem/.drawerGridIcon/.drawerGridName) — this component is
+   meant to replace that hand-rolled markup for any consumer building its
+   own Apps-style launcher. No header row — see the component's own doc
+   comment for why. */
+
+.grid {
+  list-style: none;
+  margin: 0;
+  /* Drawer's own grab handle already reserves a 44px touch target above this
+     — no extra top padding needed beyond a touch of breathing room. Bottom
+     gets noticeably more: with no header row to separate the grid from the
+     handle, a tight top/bottom balance read as top-heavy (grid crowding the
+     handle isn't the issue; the *last* row crowding the panel's bottom
+     edge/safe-area is). Drawer's own panel already adds
+     env(safe-area-inset-bottom) below everything, so this is on top of that,
+     not instead of it. */
+  padding: var(--sv-space-1) var(--sv-space-4) var(--sv-space-10);
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  row-gap: var(--sv-space-5);
+}
+
+.gridItem {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--sv-space-2);
+  padding: var(--sv-space-1);
+  border: none;
+  background: none;
+  text-decoration: none;
+  color: var(--sv-color-text-primary);
+  font: inherit;
+  cursor: pointer;
+  width: 100%;
+}
+
+@media (hover: hover) {
+  .gridItem:hover .gridIcon {
+    background: var(--sv-color-border);
+  }
+}
+
+.gridItem:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+  border-radius: var(--sv-radius-md);
+}
+
+/* color: text-primary, not text-muted — the reference's own drawerGridIcon
+   uses text-muted only as its monogram-fallback text color for <img>-less
+   plugin icons (raster <img> icons don't inherit CSS color at all, so that
+   value never actually painted a real icon). Every tile here renders a real
+   stroke icon via the Icon component (currentColor), which does inherit —
+   matching the reference's own explicit override for that exact case
+   (.drawerGridIconSettings, used by its Console tile) rather than the
+   fallback default. */
+.gridIcon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 56px;
+  height: 56px;
+  border-radius: 14px;
+  background: var(--sv-color-surface-sunken);
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-primary);
+  transition: background 0.1s;
+}
+
+.gridName {
+  font-size: var(--sv-font-size-sm);
+  text-align: center;
+  color: var(--sv-color-text-primary);
+  line-height: 1.3;
+  word-break: break-word;
+  max-width: 80px;
+}

package/src/components/MobileAppsDrawer/MobileAppsDrawer.tsx

@@ -0,0 +1,78 @@
+import type { ReactNode } from 'react';
+import { Drawer } from '../Drawer/Drawer';
+import styles from './MobileAppsDrawer.module.css';
+
+export interface MobileAppsDrawerItem {
+  /** Stable identity for this tile — used as the React key. */
+  key: string;
+  icon: ReactNode;
+  label: string;
+  /** Renders an `<a>` when set; otherwise a `<button>` calling `onClick`. */
+  href?: string;
+  onClick?: () => void;
+}
+
+export interface MobileAppsDrawerProps {
+  open: boolean;
+  onClose: () => void;
+  /** Accessible name for the drawer panel — required since there's no
+   *  visible title to fall back to (Drawer's grab handle plus swipe-down /
+   *  scrim-tap already cover dismissal, so no header row is rendered). */
+  'aria-label': string;
+  /** The grid tiles — supplied by the consumer (e.g. installed plugins,
+   *  a plugin's own sections). MobileAppsDrawer owns only the drawer
+   *  chrome/grid layout, never the item list itself. */
+  items: MobileAppsDrawerItem[];
+}
+
+function DrawerGridTile({ icon, label, href, onClick }: Omit<MobileAppsDrawerItem, 'key'>) {
+  const content = (
+    <>
+      <span className={styles.gridIcon} aria-hidden="true">
+        {icon}
+      </span>
+      <span className={styles.gridName}>{label}</span>
+    </>
+  );
+  if (href) {
+    return (
+      <a href={href} className={styles.gridItem} onClick={onClick}>
+        {content}
+      </a>
+    );
+  }
+  return (
+    <button type="button" className={styles.gridItem} onClick={onClick}>
+      {content}
+    </button>
+  );
+}
+
+/**
+ * The mobile "Apps" drawer: a bottom sheet with a 3-column grid of icon
+ * tiles — same tile size (56px, radius 14px) and grid layout as the runtime
+ * shell's own Apps drawer (MobileNav's Drawer content), generalized so the
+ * tile list comes from the consumer (the shell passes installed plugins; a
+ * plugin composing its own MobileFooter launcher passes whatever its own
+ * "apps" are, e.g. a section index) rather than being hardcoded to plugins
+ * specifically. No header row (title/close button) — Drawer's own grab
+ * handle plus swipe-down/scrim-tap dismissal are enough, and a header ate
+ * into the limited vertical space a launcher grid needs most.
+ */
+export function MobileAppsDrawer({ open, onClose, items, ...rest }: MobileAppsDrawerProps) {
+  const ariaLabel = rest['aria-label'];
+
+  return (
+    <Drawer open={open} onClose={onClose} aria-label={ariaLabel}>
+      <nav aria-label={ariaLabel}>
+        <ul className={styles.grid}>
+          {items.map(({ key, ...item }) => (
+            <li key={key}>
+              <DrawerGridTile key={key} {...item} />
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </Drawer>
+  );
+}

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

@@ -0,0 +1,80 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { MobileAppsDrawer } from '../MobileAppsDrawer';
+
+// Drawer's exit animation reads prefers-reduced-motion via matchMedia, which
+// jsdom does not implement — see Drawer's own test for the full rationale.
+function installMatchMedia() {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches: false,
+      media: query,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}
+
+function installPointerCapture() {
+  if (!Element.prototype.setPointerCapture) {
+    Element.prototype.setPointerCapture = () => {};
+  }
+  if (!Element.prototype.releasePointerCapture) {
+    Element.prototype.releasePointerCapture = () => {};
+  }
+}
+
+const items = [
+  { key: 'home', icon: <span>icon</span>, label: 'Home', href: '/home' },
+  { key: 'notes', icon: <span>icon</span>, label: 'Notes', onClick: vi.fn() },
+];
+
+describe('MobileAppsDrawer', () => {
+  beforeEach(() => {
+    installMatchMedia();
+    installPointerCapture();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('renders nothing when closed', () => {
+    render(
+      <MobileAppsDrawer open={false} onClose={() => {}} aria-label="Sections" items={items} />,
+    );
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+
+  it('renders every item when open, with no header title or close button', () => {
+    render(<MobileAppsDrawer open onClose={() => {}} aria-label="Sections" items={items} />);
+
+    expect(screen.getByRole('dialog', { name: 'Sections' })).toBeDefined();
+    expect(screen.getByText('Home')).toBeDefined();
+    expect(screen.getByText('Notes')).toBeDefined();
+    expect(screen.queryByRole('button', { name: 'Close' })).toBeNull();
+  });
+
+  it('renders an href item as a link and an onClick item as a button', () => {
+    render(<MobileAppsDrawer open onClose={() => {}} aria-label="Sections" items={items} />);
+
+    const link = screen.getByText('Home').closest('a');
+    expect(link).not.toBeNull();
+    expect(link?.getAttribute('href')).toBe('/home');
+
+    const button = screen.getByText('Notes').closest('button');
+    expect(button).not.toBeNull();
+  });
+
+  it('calls the item onClick handler when pressed', () => {
+    render(<MobileAppsDrawer open onClose={() => {}} aria-label="Sections" items={items} />);
+
+    fireEvent.click(screen.getByText('Notes'));
+    expect(items[1]?.onClick).toHaveBeenCalledTimes(1);
+  });
+});

package/src/components/MobileFooter/MobileFooter.module.css

@@ -0,0 +1,73 @@
+.footer {
+  display: flex;
+  align-items: center;
+  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-footer-height, 60px);
+  padding: 0 var(--sv-space-4);
+  padding-bottom: max(var(--sv-space-2), env(safe-area-inset-bottom));
+  background-color: var(--sv-color-surface);
+  border-top: 1px solid var(--sv-color-border);
+  position: relative;
+  z-index: 101;
+}
+
+.navItem {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex: 1;
+  min-height: 52px;
+  border: none;
+  background: transparent;
+  color: var(--sv-color-text-muted);
+  font: inherit;
+  cursor: pointer;
+  text-decoration: none;
+  border-radius: var(--sv-radius-md);
+  transition: color 0.1s;
+  outline: none;
+}
+
+@media (hover: hover) {
+  .navItem:hover {
+    color: var(--sv-color-text-primary);
+  }
+}
+
+.navItem:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: -2px;
+}
+
+.navItemActive {
+  color: var(--sv-color-text-primary);
+}
+
+.navItemApps {
+  position: relative;
+}
+
+.navItemAppsOpen {
+  color: var(--sv-color-text-primary);
+}
+
+.navItemAppsOpen::before {
+  content: '';
+  position: absolute;
+  width: 48px;
+  height: 48px;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-surface-sunken);
+}
+
+.navItemAppsOpen svg,
+.navItemAppsOpen img {
+  position: relative;
+  z-index: 1;
+}

package/src/components/MobileFooter/MobileFooter.stories.tsx

@@ -0,0 +1,47 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { MobileFooter } from './MobileFooter';
+import { Icon } from '../Icon/Icon';
+
+const homeIcon = { icon: <Icon name="house" size="md" aria-hidden />, label: 'Home', active: true };
+const searchIcon = { icon: <Icon name="search" size="md" aria-hidden />, label: 'Search' };
+const calendarIcon = { icon: <Icon name="calendar" size="md" aria-hidden />, label: 'Calendar' };
+const activityIcon = { icon: <Icon name="activity" size="md" aria-hidden />, label: 'Activity' };
+
+const meta = {
+  title: 'Components/MobileFooter',
+  component: MobileFooter,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Mobile shell footer nav row (RFC 0088). The centered launcher (onOpenApps) is always rendered; leftIcons/rightIcons take 1 or 2 items each, symmetric so the launcher stays centered. Presentational only, no data fetching.',
+      },
+    },
+  },
+  args: {
+    onOpenApps: () => {},
+    leftIcons: [homeIcon],
+    rightIcons: [searchIcon],
+  },
+} satisfies Meta<typeof MobileFooter>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const FiveIcons: Story = {
+  args: {
+    leftIcons: [homeIcon, calendarIcon],
+    rightIcons: [searchIcon, activityIcon],
+  },
+};
+
+export const LauncherOpen: Story = {
+  render: function Render(args) {
+    const [open, setOpen] = useState(true);
+    return <MobileFooter {...args} launcherOpen={open} onOpenApps={() => setOpen((v) => !v)} />;
+  },
+};

package/src/components/MobileFooter/MobileFooter.tsx

@@ -0,0 +1,109 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import { Icon } from '../Icon/Icon';
+import styles from './MobileFooter.module.css';
+
+export interface FooterIcon {
+  icon: ReactNode;
+  label: string;
+  href?: string;
+  onClick?: () => void;
+  active?: boolean;
+}
+
+export interface MobileFooterProps extends HTMLAttributes<HTMLElement> {
+  /** Opens the app drawer/launcher. Always rendered as the centered slot;
+   * not overridable. */
+  onOpenApps: () => void;
+  /** Custom launcher icon (e.g. a plugin-supplied image). Defaults to a
+   * generic grid icon. */
+  launcherIcon?: ReactNode;
+  /** Whether the launcher's own drawer is currently open (applies the
+   * pressed/active visual state). */
+  launcherOpen?: boolean;
+  /** 1 or 2 icons rendered to the left of the centered launcher. */
+  leftIcons: FooterIcon[];
+  /** 1 or 2 icons rendered to the right of the centered launcher. Must match
+   * `leftIcons.length` — the launcher stays visually centered, so a mismatch
+   * is flagged (dev-mode only, never thrown) rather than silently allowed. */
+  rightIcons: FooterIcon[];
+}
+
+function FooterNavItem({ icon, label, href, onClick, active }: FooterIcon) {
+  const className = [styles.navItem, active ? styles.navItemActive : ''].filter(Boolean).join(' ');
+  if (href) {
+    return (
+      <a
+        href={href}
+        className={className}
+        aria-label={label}
+        aria-current={active ? 'page' : undefined}
+      >
+        {icon}
+      </a>
+    );
+  }
+  return (
+    <button type="button" className={className} aria-label={label} onClick={onClick}>
+      {icon}
+    </button>
+  );
+}
+
+/**
+ * The mobile footer bar: a centered, fixed "Apps" launcher flanked by 1 or 2
+ * overridable icons on each side (3 or 5 total, matching standard
+ * iOS/Android bottom-nav conventions). Owns its own chrome — background,
+ * border-top, safe-area-aware bottom 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 footer (MobileNav) exactly,
+ * since this component is meant to replace that hand-rolled markup.
+ * Presentational only — no data fetching; the consumer owns the
+ * drawer/overlay `onOpenApps` opens. See RFC 0088 for the
+ * immutable/overridable boundary this enforces.
+ */
+export function MobileFooter({
+  onOpenApps,
+  launcherIcon,
+  launcherOpen,
+  leftIcons,
+  rightIcons,
+  className,
+  ...rest
+}: MobileFooterProps) {
+  if (process.env.NODE_ENV !== 'production' && leftIcons.length !== rightIcons.length) {
+    console.error(
+      `MobileFooter: leftIcons (${leftIcons.length}) and rightIcons (${rightIcons.length}) ` +
+        'must have the same length so the launcher stays visually centered.',
+    );
+  }
+
+  const cls = [styles.footer, className].filter(Boolean).join(' ');
+  const launcherClassName = [
+    styles.navItem,
+    styles.navItemApps,
+    launcherOpen ? styles.navItemAppsOpen : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <nav {...rest} className={cls} aria-label="App navigation">
+      {leftIcons.map((item) => (
+        <FooterNavItem key={item.label} {...item} />
+      ))}
+      <button
+        type="button"
+        className={launcherClassName}
+        aria-label="Apps"
+        aria-expanded={launcherOpen}
+        aria-haspopup="dialog"
+        onClick={onOpenApps}
+      >
+        {launcherIcon ?? <Icon name="grid-2x2" size="md" aria-hidden />}
+      </button>
+      {rightIcons.map((item) => (
+        <FooterNavItem key={item.label} {...item} />
+      ))}
+    </nav>
+  );
+}

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

@@ -0,0 +1,71 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { MobileFooter } from '../MobileFooter';
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+});
+
+const oneIcon = [{ icon: <span>icon</span>, label: 'Home' }];
+const twoIcons = [
+  { icon: <span>icon</span>, label: 'Home' },
+  { icon: <span>icon</span>, label: 'Calendar' },
+];
+const leftTwo = [
+  { icon: <span>icon</span>, label: 'Home' },
+  { icon: <span>icon</span>, label: 'Calendar' },
+];
+const rightTwo = [
+  { icon: <span>icon</span>, label: 'Search' },
+  { icon: <span>icon</span>, label: 'Activity' },
+];
+
+describe('MobileFooter', () => {
+  it('always renders the centered launcher button', () => {
+    render(<MobileFooter onOpenApps={() => {}} leftIcons={oneIcon} rightIcons={oneIcon} />);
+
+    expect(screen.getByRole('button', { name: 'Apps' })).toBeDefined();
+  });
+
+  it('calls onOpenApps when the launcher is pressed', () => {
+    const onOpenApps = vi.fn();
+    render(<MobileFooter onOpenApps={onOpenApps} leftIcons={oneIcon} rightIcons={oneIcon} />);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Apps' }));
+    expect(onOpenApps).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders 1+1 and 2+2 icon layouts', () => {
+    const { rerender } = render(
+      <MobileFooter onOpenApps={() => {}} leftIcons={oneIcon} rightIcons={oneIcon} />,
+    );
+    expect(screen.getAllByRole('button').length).toBe(3);
+
+    rerender(<MobileFooter onOpenApps={() => {}} leftIcons={leftTwo} rightIcons={rightTwo} />);
+    expect(screen.getByLabelText('Calendar')).toBeDefined();
+    expect(screen.getByLabelText('Activity')).toBeDefined();
+  });
+
+  it('logs a dev-mode console.error when left/right icon counts mismatch, but never throws', () => {
+    vi.stubEnv('NODE_ENV', 'development');
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() =>
+      render(<MobileFooter onOpenApps={() => {}} leftIcons={oneIcon} rightIcons={twoIcons} />),
+    ).not.toThrow();
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('leftIcons'));
+  });
+
+  it('does not call console.error in production even with mismatched counts', () => {
+    vi.stubEnv('NODE_ENV', 'production');
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    render(<MobileFooter onOpenApps={() => {}} leftIcons={oneIcon} rightIcons={twoIcons} />);
+
+    expect(errorSpy).not.toHaveBeenCalled();
+  });
+});