@sovereignfs/ui 0.40.0 → 0.45.0

package/src/components/Message/Message.stories.tsx

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Message } from './Message';
+
+const meta = {
+  title: 'Components/Message',
+  component: Message,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          "A single chat turn, for the Sovereign Harness assistant (RFC 0040). `sender` is one of user/assistant/tool — matching harness_messages (named `sender`, not `role`, to avoid colliding with the ARIA role attribute). Content is caller-controlled ReactNode; markdown rendering, if any, is the consumer's choice.",
+      },
+    },
+  },
+  args: { sender: 'assistant', children: 'Your task is due Thursday.' },
+} satisfies Meta<typeof Message>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const User: Story = {
+  args: { sender: 'user', children: 'What tasks do I have due this week?' },
+};
+
+export const Assistant: Story = {
+  args: { sender: 'assistant' },
+};
+
+export const Tool: Story = {
+  args: { sender: 'tool', children: 'query_tasks({ dueBefore: "2026-08-01" }) → 3 results' },
+};
+
+export const Pending: Story = {
+  args: { sender: 'assistant', pending: true },
+};
+
+export const WithActions: Story = {
+  args: {
+    sender: 'assistant',
+    actions: (
+      <>
+        <button type="button" style={{ all: 'unset', cursor: 'pointer' }}>
+          Forget this
+        </button>
+        <span>·</span>
+        <button type="button" style={{ all: 'unset', cursor: 'pointer' }}>
+          Copy
+        </button>
+      </>
+    ),
+  },
+};
+
+export const Conversation: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+      <Message sender="user">What tasks do I have due this week?</Message>
+      <Message sender="tool">
+        query_tasks({'{'} dueBefore: "2026-08-01" {'}'}) → 3 results
+      </Message>
+      <Message
+        sender="assistant"
+        actions={
+          <button type="button" style={{ all: 'unset', cursor: 'pointer' }}>
+            Forget this
+          </button>
+        }
+      >
+        You have 3 tasks due this week: review the Q3 report, reply to the design feedback thread,
+        and renew the domain registration.
+      </Message>
+      <Message sender="user">Thanks!</Message>
+      <Message sender="assistant" pending />
+    </div>
+  ),
+};

package/src/components/Message/Message.tsx

@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react';
+import styles from './Message.module.css';
+
+export type MessageSender = 'user' | 'assistant' | 'tool';
+
+export interface MessageProps {
+  /** Matches the three roles Sovereign Harness stores per RFC 0040:
+   * user, assistant, and tool messages. Named `sender`, not `role`, to
+   * avoid colliding with the ARIA `role` attribute in JSX tooling. */
+  sender: MessageSender;
+  children?: ReactNode;
+  /** Shows a "thinking" indicator instead of children — before the first
+   * token of a streaming response arrives. Once content starts streaming
+   * in, pass it as children and stop passing `pending`. */
+  pending?: boolean;
+  /** Rendered in a small row below the bubble — e.g. "Forget this" (RFC
+   * 0040's per-message memory action), "Copy", "Regenerate". */
+  actions?: ReactNode;
+  className?: string;
+}
+
+/** Message — a single chat turn. Content is caller-controlled `ReactNode`
+ * (markdown rendering, if any, is the consumer's choice, not baked in here). */
+export function Message({ sender, children, pending, actions, className }: MessageProps) {
+  return (
+    <div className={[styles.row, styles[sender], className].filter(Boolean).join(' ')}>
+      <div className={styles.bubble}>
+        {pending ? (
+          <span className={styles.typingDots} aria-label="Thinking">
+            <span className={styles.dot} />
+            <span className={styles.dot} />
+            <span className={styles.dot} />
+          </span>
+        ) : (
+          children
+        )}
+      </div>
+      {actions && !pending && <div className={styles.actions}>{actions}</div>}
+    </div>
+  );
+}

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

@@ -0,0 +1,46 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { Message } from '../Message';
+
+afterEach(cleanup);
+
+describe('Message', () => {
+  it('renders children content', () => {
+    render(<Message sender="user">Hello there</Message>);
+    expect(screen.getByText('Hello there')).toBeDefined();
+  });
+
+  it('shows a "Thinking" indicator instead of children when pending', () => {
+    render(
+      <Message sender="assistant" pending>
+        Not shown yet
+      </Message>,
+    );
+    expect(screen.getByLabelText('Thinking')).toBeDefined();
+    expect(screen.queryByText('Not shown yet')).toBeNull();
+  });
+
+  it('renders actions below the bubble when given and not pending', () => {
+    render(
+      <Message sender="assistant" actions={<button type="button">Forget this</button>}>
+        Your task is due Thursday.
+      </Message>,
+    );
+    expect(screen.getByRole('button', { name: 'Forget this' })).toBeDefined();
+  });
+
+  it('hides actions while pending', () => {
+    render(
+      <Message sender="assistant" pending actions={<button type="button">Forget this</button>}>
+        content
+      </Message>,
+    );
+    expect(screen.queryByRole('button', { name: 'Forget this' })).toBeNull();
+  });
+
+  it.each(['user', 'assistant', 'tool'] as const)('renders the %s sender', (sender) => {
+    render(<Message sender={sender}>content</Message>);
+    expect(screen.getByText('content')).toBeDefined();
+  });
+});

package/src/components/MessageScroller/MessageScroller.module.css

@@ -0,0 +1,54 @@
+.root {
+  position: relative;
+  height: 100%;
+  min-height: 0;
+}
+
+.scrollContainer {
+  height: 100%;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  display: flex;
+  flex-direction: column;
+  gap: var(--sv-space-3);
+  padding: var(--sv-space-3);
+  scrollbar-width: thin;
+  scrollbar-color: var(--sv-color-border-strong) transparent;
+}
+
+.scrollContainer::-webkit-scrollbar {
+  width: 8px;
+}
+
+.scrollContainer::-webkit-scrollbar-thumb {
+  background: var(--sv-color-border-strong);
+  border-radius: var(--sv-radius-full);
+}
+
+.jumpButton {
+  position: absolute;
+  bottom: var(--sv-space-3);
+  left: 50%;
+  transform: translateX(-50%);
+  padding: var(--sv-space-1) var(--sv-space-3);
+  border: 1px solid var(--sv-color-border);
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-surface-raised);
+  box-shadow: var(--sv-shadow-popover);
+  color: var(--sv-color-text-primary);
+  font-family: var(--sv-font-family);
+  font-size: var(--sv-font-size-caption);
+  font-weight: var(--sv-font-weight-medium);
+  cursor: pointer;
+}
+
+.jumpButton:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: 2px;
+}
+
+@media (hover: hover) {
+  .jumpButton:hover {
+    background: var(--sv-color-surface-sunken);
+  }
+}

package/src/components/MessageScroller/MessageScroller.stories.tsx

@@ -0,0 +1,84 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { MessageScroller } from './MessageScroller';
+import { Message } from '../Message/Message';
+import { Button } from '../Button/Button';
+
+const meta = {
+  title: 'Components/MessageScroller',
+  component: MessageScroller,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Auto-scrolling chat container. Scrolls to the newest message while the user is near the bottom; if they\'ve scrolled up, new content shows a "New messages" button instead of yanking them back down.',
+      },
+    },
+  },
+  args: { children: null },
+} satisfies Meta<typeof MessageScroller>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+const SEED_MESSAGES = [
+  { sender: 'user' as const, text: 'What tasks do I have due this week?' },
+  {
+    sender: 'assistant' as const,
+    text: 'You have 3 tasks due this week: review the Q3 report, reply to the design feedback thread, and renew the domain registration.',
+  },
+  { sender: 'user' as const, text: 'Can you summarize the Q3 report task?' },
+  {
+    sender: 'assistant' as const,
+    text: 'It\'s tagged "high priority" and due Thursday — created from your Notes plugin two days ago.',
+  },
+];
+
+export const Interactive: Story = {
+  render: () => {
+    const [messages, setMessages] = useState(SEED_MESSAGES);
+    return (
+      <div style={{ height: 420, display: 'flex', flexDirection: 'column', maxWidth: 480 }}>
+        <div style={{ flex: 1, minHeight: 0, border: '1px solid var(--sv-color-border)' }}>
+          <MessageScroller>
+            {messages.map((m, i) => (
+              <Message key={i} sender={m.sender}>
+                {m.text}
+              </Message>
+            ))}
+          </MessageScroller>
+        </div>
+        <div style={{ padding: 'var(--sv-space-3)' }}>
+          <Button
+            size="sm"
+            onClick={() =>
+              setMessages((prev) => [
+                ...prev,
+                { sender: 'assistant', text: `New message #${prev.length + 1}` },
+              ])
+            }
+          >
+            Add message
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const LongHistory: Story = {
+  render: () => (
+    <div style={{ height: 420, maxWidth: 480, border: '1px solid var(--sv-color-border)' }}>
+      <MessageScroller>
+        {Array.from({ length: 30 }, (_, i) => (
+          <Message key={i} sender={i % 2 === 0 ? 'user' : 'assistant'}>
+            Message {i + 1}
+          </Message>
+        ))}
+      </MessageScroller>
+    </div>
+  ),
+};

package/src/components/MessageScroller/MessageScroller.tsx

@@ -0,0 +1,72 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import type { ReactNode, UIEvent } from 'react';
+import styles from './MessageScroller.module.css';
+
+export interface MessageScrollerProps {
+  children: ReactNode;
+  className?: string;
+}
+
+const NEAR_BOTTOM_THRESHOLD_PX = 80;
+
+/**
+ * MessageScroller — auto-scrolling chat container.
+ *
+ * Scrolls to the newest message automatically, but only while the user is
+ * already near the bottom. If they've scrolled up to read history, new
+ * content does not yank them back down — a "New messages" button appears
+ * instead, matching the pattern every chat product (Slack, Discord,
+ * ChatGPT) already uses.
+ */
+export function MessageScroller({ children, className }: MessageScrollerProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  // A ref, not state: reading the user's scroll position must not itself
+  // retrigger the auto-scroll effect below, or scrolling back near the
+  // bottom manually would immediately snap the container the rest of the
+  // way — fighting the user's own scroll input.
+  const isNearBottomRef = useRef(true);
+  const [hasNewMessages, setHasNewMessages] = useState(false);
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    if (isNearBottomRef.current) {
+      el.scrollTop = el.scrollHeight;
+      setHasNewMessages(false);
+    } else {
+      setHasNewMessages(true);
+    }
+  }, [children]);
+
+  function handleScroll(event: UIEvent<HTMLDivElement>) {
+    const el = event.currentTarget;
+    const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+    isNearBottomRef.current = distanceFromBottom < NEAR_BOTTOM_THRESHOLD_PX;
+    if (isNearBottomRef.current) {
+      setHasNewMessages(false);
+    }
+  }
+
+  function scrollToBottom() {
+    const el = containerRef.current;
+    if (!el) return;
+    el.scrollTo({ top: el.scrollHeight, behavior: 'smooth' });
+    isNearBottomRef.current = true;
+    setHasNewMessages(false);
+  }
+
+  return (
+    <div className={[styles.root, className].filter(Boolean).join(' ')}>
+      <div className={styles.scrollContainer} ref={containerRef} onScroll={handleScroll}>
+        {children}
+      </div>
+      {hasNewMessages && (
+        <button type="button" className={styles.jumpButton} onClick={scrollToBottom}>
+          New messages ↓
+        </button>
+      )}
+    </div>
+  );
+}

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/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' },
+    ],
+  },
+};