@sovereignfs/ui 0.41.0 → 0.45.0

package/src/components/Menubar/Menubar.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { NavigationMenu } from '../NavigationMenu/NavigationMenu';
+import { MenuEntries, type MenuEntry } from '../Menu/Menu';
+
+export interface MenubarMenu {
+  label: string;
+  items: MenuEntry[];
+}
+
+export interface MenubarProps {
+  menus: MenubarMenu[];
+  'aria-label'?: string;
+}
+
+/**
+ * Menubar — desktop app-style menu bar (File / Edit / View...). A thin
+ * composition of `NavigationMenu` (top-level triggers, per-item flyout
+ * positioning, hover-switches-when-one-is-open, arrow-key navigation) with
+ * `MenuEntries` (the same item list markup `Menu`'s dropdowns use) as each
+ * item's flyout content — no positioning or list-rendering logic
+ * duplicated from either.
+ */
+export function Menubar({ menus, 'aria-label': ariaLabel = 'Menu bar' }: MenubarProps) {
+  return (
+    <NavigationMenu
+      aria-label={ariaLabel}
+      items={menus.map((menu) => ({
+        label: menu.label,
+        content: (close: () => void) => (
+          <MenuEntries
+            items={menu.items}
+            onSelect={(entry) => {
+              close();
+              entry.onSelect();
+            }}
+          />
+        ),
+      }))}
+    />
+  );
+}

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

@@ -0,0 +1,45 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen, fireEvent } from '@testing-library/react';
+import { Menubar } from '../Menubar';
+
+afterEach(cleanup);
+
+describe('Menubar', () => {
+  it('opens a menu on trigger click, showing its items', () => {
+    render(<Menubar menus={[{ label: 'File', items: [{ label: 'New', onSelect: () => {} }] }]} />);
+    fireEvent.click(screen.getByRole('button', { name: 'File' }));
+    expect(screen.getByRole('menuitem', { name: 'New' })).toBeDefined();
+  });
+
+  it('selecting an item calls onSelect and closes the menu', () => {
+    const onSelect = vi.fn();
+    render(<Menubar menus={[{ label: 'File', items: [{ label: 'New', onSelect }] }]} />);
+    fireEvent.click(screen.getByRole('button', { name: 'File' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: 'New' }));
+    expect(onSelect).toHaveBeenCalled();
+    expect(screen.queryByRole('menuitem', { name: 'New' })).toBeNull();
+  });
+
+  it('switches directly between menus on hover once one is open, like a real menu bar', () => {
+    render(
+      <Menubar
+        menus={[
+          { label: 'File', items: [{ label: 'New', onSelect: () => {} }] },
+          { label: 'Edit', items: [{ label: 'Undo', onSelect: () => {} }] },
+        ]}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'File' }));
+    expect(screen.getByRole('menuitem', { name: 'New' })).toBeDefined();
+
+    fireEvent.mouseEnter(screen.getByRole('button', { name: 'Edit' }));
+    expect(screen.getByRole('menuitem', { name: 'Undo' })).toBeDefined();
+    expect(screen.queryByRole('menuitem', { name: 'New' })).toBeNull();
+  });
+
+  it('defaults to an accessible "Menu bar" label', () => {
+    render(<Menubar menus={[{ label: 'File', items: [] }]} />);
+    expect(screen.getByRole('navigation', { name: 'Menu bar' })).toBeDefined();
+  });
+});

package/src/components/Message/Message.module.css

@@ -0,0 +1,99 @@
+.row {
+  display: flex;
+  flex-direction: column;
+  max-width: 80%;
+}
+
+.user {
+  align-self: flex-end;
+  align-items: flex-end;
+}
+
+.assistant,
+.tool {
+  align-self: flex-start;
+  align-items: flex-start;
+}
+
+.bubble {
+  padding: var(--sv-space-2) var(--sv-space-3);
+  border-radius: var(--sv-radius-xl);
+  font-size: var(--sv-font-size-sm);
+  line-height: 1.5;
+  white-space: pre-wrap;
+  overflow-wrap: break-word;
+}
+
+.user .bubble {
+  background: var(--sv-color-accent);
+  color: var(--sv-color-text-on-accent);
+  border-bottom-right-radius: var(--sv-radius-sm);
+}
+
+.assistant .bubble {
+  background: var(--sv-color-surface-raised);
+  border: 1px solid var(--sv-color-border);
+  color: var(--sv-color-text-primary);
+  border-bottom-left-radius: var(--sv-radius-sm);
+}
+
+.tool .bubble {
+  background: var(--sv-color-surface-sunken);
+  color: var(--sv-color-text-muted);
+  font-family: var(--sv-font-family-mono);
+  font-size: var(--sv-font-size-xs);
+  border-bottom-left-radius: var(--sv-radius-sm);
+}
+
+.actions {
+  display: flex;
+  gap: var(--sv-space-2);
+  margin-top: var(--sv-space-1);
+  font-size: var(--sv-font-size-caption);
+  color: var(--sv-color-text-muted);
+}
+
+/* Typing indicator — three dots, staggered pulse. */
+.typingDots {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  padding: var(--sv-space-1) 0;
+}
+
+.dot {
+  width: 6px;
+  height: 6px;
+  border-radius: var(--sv-radius-full);
+  background: currentColor;
+  opacity: 0.4;
+  animation: typing-pulse 1.2s ease-in-out infinite;
+}
+
+.dot:nth-child(2) {
+  animation-delay: 0.2s;
+}
+
+.dot:nth-child(3) {
+  animation-delay: 0.4s;
+}
+
+@keyframes typing-pulse {
+  0%,
+  80%,
+  100% {
+    opacity: 0.4;
+    transform: scale(0.85);
+  }
+  40% {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .dot {
+    animation: none;
+    opacity: 0.7;
+  }
+}

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