@steerable/agent-ui 0.2.3 → 0.2.4

package/src/state/useChatComposer.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Tests for `useChatComposer`. The hook is intentionally tiny so the suite is
+ * focused — keyboard semantics, the streaming guard, and the trim/clear
+ * contract are what consumers actually pin behaviour against.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useChatComposer } from './useChatComposer';
+
+function makeKey(key: string, extras: Partial<KeyboardEvent> = {}) {
+  // Construct a minimal React keyboard event matching what the hook uses.
+  return {
+    key,
+    shiftKey: extras.shiftKey ?? false,
+    metaKey: extras.metaKey ?? false,
+    ctrlKey: extras.ctrlKey ?? false,
+    preventDefault: vi.fn(),
+  } as unknown as React.KeyboardEvent<HTMLElement>;
+}
+
+describe('useChatComposer', () => {
+  it('submits the trimmed value and clears the draft', async () => {
+    const onSend = vi.fn().mockResolvedValue(undefined);
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend, initialValue: '  hello  ' }),
+    );
+
+    await act(async () => {
+      await result.current.submit();
+    });
+
+    expect(onSend).toHaveBeenCalledWith('hello');
+    expect(result.current.value).toBe('');
+  });
+
+  it('does not submit empty / whitespace-only drafts', async () => {
+    const onSend = vi.fn();
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend, initialValue: '   ' }),
+    );
+
+    await act(async () => {
+      await result.current.submit();
+    });
+
+    expect(onSend).not.toHaveBeenCalled();
+  });
+
+  it('Enter submits, Shift+Enter inserts a newline (default)', async () => {
+    const onSend = vi.fn();
+    const { result } = renderHook(() => useChatComposer({ onSend, initialValue: 'hi' }));
+
+    const submit = makeKey('Enter');
+    await act(async () => {
+      result.current.handleKeyDown(submit);
+    });
+    expect(submit.preventDefault).toHaveBeenCalled();
+    expect(onSend).toHaveBeenCalledWith('hi');
+
+    const shift = makeKey('Enter', { shiftKey: true });
+    await act(async () => {
+      result.current.handleKeyDown(shift);
+    });
+    expect(shift.preventDefault).not.toHaveBeenCalled();
+  });
+
+  it('isStreaming flips Enter into a cancel', async () => {
+    const onSend = vi.fn();
+    const onCancel = vi.fn();
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend, onCancel, isStreaming: true, initialValue: 'x' }),
+    );
+
+    const ev = makeKey('Enter');
+    await act(async () => {
+      result.current.handleKeyDown(ev);
+    });
+    expect(onCancel).toHaveBeenCalledOnce();
+    expect(onSend).not.toHaveBeenCalled();
+  });
+
+  it('Escape cancels while streaming', async () => {
+    const onCancel = vi.fn();
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend: vi.fn(), onCancel, isStreaming: true }),
+    );
+    const ev = makeKey('Escape');
+    await act(async () => {
+      result.current.handleKeyDown(ev);
+    });
+    expect(onCancel).toHaveBeenCalledOnce();
+  });
+
+  it('enterToSubmit=false requires Cmd/Ctrl+Enter', async () => {
+    const onSend = vi.fn();
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend, enterToSubmit: false, initialValue: 'hi' }),
+    );
+
+    const plain = makeKey('Enter');
+    await act(async () => {
+      result.current.handleKeyDown(plain);
+    });
+    expect(plain.preventDefault).not.toHaveBeenCalled();
+    expect(onSend).not.toHaveBeenCalled();
+
+    const cmd = makeKey('Enter', { metaKey: true });
+    await act(async () => {
+      result.current.handleKeyDown(cmd);
+    });
+    expect(cmd.preventDefault).toHaveBeenCalled();
+    expect(onSend).toHaveBeenCalledWith('hi');
+  });
+
+  it('disabled state suppresses both submit and key handling', async () => {
+    const onSend = vi.fn();
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend, disabled: true, initialValue: 'hi' }),
+    );
+
+    await act(async () => {
+      await result.current.submit();
+    });
+    const ev = makeKey('Enter');
+    await act(async () => {
+      result.current.handleKeyDown(ev);
+    });
+    expect(onSend).not.toHaveBeenCalled();
+    expect(ev.preventDefault).not.toHaveBeenCalled();
+    expect(result.current.canSubmit).toBe(false);
+  });
+
+  it('clear() empties the draft without sending', async () => {
+    const onSend = vi.fn();
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend, initialValue: 'hi' }),
+    );
+    await act(async () => {
+      result.current.clear();
+    });
+    expect(result.current.value).toBe('');
+    expect(onSend).not.toHaveBeenCalled();
+  });
+});

package/src/state/useChatComposer.ts

@@ -0,0 +1,117 @@
+/**
+ * `useChatComposer` — input draft + send/cancel + keyboard glue.
+ *
+ * Lifted from deeppath-agent's `LocalChatPanel.tsx` (inline `inputValue` /
+ * `handleSubmit`) and deeppath's `ChatInput` (cancel handling). The hook is
+ * intentionally UI-free: it owns the draft string and the keyboard
+ * dispatcher; the visible textarea and send button live in the consuming
+ * component.
+ *
+ * Typical wiring:
+ *
+ *   const composer = useChatComposer({ onSend: send, onCancel: cancel });
+ *
+ *   <textarea
+ *     value={composer.value}
+ *     onChange={(e) => composer.setValue(e.target.value)}
+ *     onKeyDown={composer.handleKeyDown}
+ *   />
+ *   <button onClick={composer.submit}>Send</button>
+ */
+
+import { useCallback, useRef, useState } from 'react';
+
+export interface UseChatComposerOptions {
+  initialValue?: string;
+  /** Called with the trimmed value when the user submits a non-empty draft. */
+  onSend: (value: string) => void | Promise<void>;
+  /** Called when the user wants to cancel the in-flight stream. Optional. */
+  onCancel?: () => void;
+  /**
+   * If true (default), Enter submits and Shift+Enter inserts a newline. Set
+   * to false for "Enter inserts newline, Cmd/Ctrl+Enter submits" semantics.
+   */
+  enterToSubmit?: boolean;
+  /** Whether the composer is currently disabled (no submit / no key handling). */
+  disabled?: boolean;
+  /**
+   * Whether the parent reports an in-flight stream. When true, `submit()` is
+   * a no-op and Enter triggers `onCancel` instead. Mirrors the cloud product.
+   */
+  isStreaming?: boolean;
+}
+
+export interface UseChatComposerReturn {
+  value: string;
+  setValue: (value: string) => void;
+  submit: () => Promise<void> | void;
+  cancel: () => void;
+  clear: () => void;
+  handleKeyDown: (e: React.KeyboardEvent<HTMLElement>) => void;
+  /** True if `value.trim()` is non-empty and we're not disabled. */
+  canSubmit: boolean;
+}
+
+export function useChatComposer(options: UseChatComposerOptions): UseChatComposerReturn {
+  const [value, setValue] = useState(options.initialValue ?? '');
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const submit = useCallback(async () => {
+    const opts = optionsRef.current;
+    if (opts.disabled || opts.isStreaming) return;
+    const trimmed = value.trim();
+    if (!trimmed) return;
+    // Clear synchronously so the user can keep typing while the request flies.
+    setValue('');
+    await opts.onSend(trimmed);
+  }, [value]);
+
+  const cancel = useCallback(() => {
+    optionsRef.current.onCancel?.();
+  }, []);
+
+  const clear = useCallback(() => setValue(''), []);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLElement>) => {
+      const opts = optionsRef.current;
+      if (opts.disabled) return;
+      const enterSubmits = opts.enterToSubmit ?? true;
+      if (e.key === 'Enter') {
+        if (enterSubmits && !e.shiftKey && !e.metaKey && !e.ctrlKey) {
+          e.preventDefault();
+          if (opts.isStreaming) {
+            cancel();
+          } else {
+            void submit();
+          }
+          return;
+        }
+        if (!enterSubmits && (e.metaKey || e.ctrlKey)) {
+          e.preventDefault();
+          if (opts.isStreaming) cancel();
+          else void submit();
+          return;
+        }
+      }
+      if (e.key === 'Escape' && opts.isStreaming) {
+        e.preventDefault();
+        cancel();
+      }
+    },
+    [submit, cancel],
+  );
+
+  const canSubmit = value.trim().length > 0 && !(options.disabled || options.isStreaming);
+
+  return {
+    value,
+    setValue,
+    submit,
+    cancel,
+    clear,
+    handleKeyDown,
+    canSubmit,
+  };
+}

package/src/state/useChatList.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Tests for `useChatList`. The generics are deliberately unconstrained, so
+ * here we instantiate with simple `{id,title}`-shaped chats and agents to
+ * keep the suite readable.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import {
+  useChatList,
+  type ChatListTransport,
+} from './useChatList';
+
+interface ChatDouble {
+  id: string;
+  title: string;
+}
+
+interface AgentDouble {
+  id: string;
+}
+
+function makeTransport(): {
+  transport: ChatListTransport<ChatDouble, AgentDouble>;
+  listChats: ReturnType<typeof vi.fn>;
+  listAgents: ReturnType<typeof vi.fn>;
+  createChat: ReturnType<typeof vi.fn>;
+  deleteChat: ReturnType<typeof vi.fn>;
+} {
+  const listChats = vi.fn(async ({ page }: { page: number }) => ({
+    chats:
+      page === 1
+        ? [
+            { id: 'c1', title: 'First' },
+            { id: 'c2', title: 'Second' },
+          ]
+        : [{ id: 'c3', title: 'Third' }],
+    hasMore: page === 1,
+  }));
+  const listAgents = vi.fn(async () => [{ id: 'a1' }, { id: 'a2' }]);
+  const createChat = vi.fn(async () => ({ id: 'c-new', title: 'New' }));
+  const deleteChat = vi.fn(async () => true);
+  return {
+    transport: {
+      listChats,
+      listAgents,
+      createChat,
+      deleteChat,
+      getChatId: (c) => c.id,
+      setChatTitle: (c, title) => ({ ...c, title }),
+      getAgentId: (a) => a.id,
+    },
+    listChats,
+    listAgents,
+    createChat,
+    deleteChat,
+  };
+}
+
+describe('useChatList', () => {
+  it('loads chats + agents on mount', async () => {
+    const { transport } = makeTransport();
+    const { result } = renderHook(() => useChatList({ transport, pageSize: 50 }));
+
+    await waitFor(() => {
+      expect(result.current.chats.length).toBe(2);
+      expect(result.current.agents.length).toBe(2);
+    });
+    expect(result.current.hasMoreChats).toBe(true);
+  });
+
+  it('loadMoreChats appends page 2 results', async () => {
+    const { transport } = makeTransport();
+    const { result } = renderHook(() => useChatList({ transport, pageSize: 50 }));
+
+    await waitFor(() => expect(result.current.chats.length).toBe(2));
+
+    await act(async () => {
+      await result.current.loadMoreChats();
+    });
+
+    expect(result.current.chats.map((c) => c.id)).toEqual(['c1', 'c2', 'c3']);
+    expect(result.current.hasMoreChats).toBe(false);
+  });
+
+  it('patchChatTitle updates without re-fetching', async () => {
+    const { transport, listChats } = makeTransport();
+    const { result } = renderHook(() => useChatList({ transport, pageSize: 50 }));
+    await waitFor(() => expect(result.current.chats.length).toBe(2));
+
+    act(() => {
+      result.current.patchChatTitle('c1', 'Renamed');
+    });
+
+    expect(result.current.chats[0].title).toBe('Renamed');
+    expect(listChats).toHaveBeenCalledTimes(1);
+  });
+
+  it('createChat triggers refresh + returns id', async () => {
+    const { transport } = makeTransport();
+    const { result } = renderHook(() => useChatList({ transport, pageSize: 50 }));
+    await waitFor(() => expect(result.current.chats.length).toBe(2));
+
+    let id: string | null = null;
+    await act(async () => {
+      id = await result.current.createChat();
+    });
+    expect(id).toBe('c-new');
+  });
+
+  it('deleteChat optimistically removes the chat', async () => {
+    const { transport } = makeTransport();
+    const { result } = renderHook(() => useChatList({ transport, pageSize: 50 }));
+    await waitFor(() => expect(result.current.chats.length).toBe(2));
+
+    await act(async () => {
+      await result.current.deleteChat('c1');
+    });
+
+    expect(result.current.chats.map((c) => c.id)).toEqual(['c2']);
+  });
+
+  it('selectedAgentId is settable and persists across renders', async () => {
+    const { transport } = makeTransport();
+    const { result, rerender } = renderHook(() =>
+      useChatList({ transport, pageSize: 50 }),
+    );
+    await waitFor(() => expect(result.current.agents.length).toBe(2));
+
+    act(() => result.current.setSelectedAgentId('a2'));
+    expect(result.current.selectedAgentId).toBe('a2');
+    rerender();
+    expect(result.current.selectedAgentId).toBe('a2');
+  });
+});

package/src/state/useChatList.ts

@@ -0,0 +1,217 @@
+/**
+ * `useChatList` — paginated chat-summary + agent-catalog state for the chat
+ * sidebar. Generic in the chat and agent shapes so cloud and local apps reuse
+ * the same hook (the cloud schema has extra fields on `Chat`, the local
+ * schema has fewer).
+ *
+ * Lifted from deeppath-agent's `useChatsAndAgents.ts` and deeppath's
+ * `useChatUI` chat-list subset. The hook owns:
+ *   - paginated chat list with "load more" and refresh
+ *   - the agent catalog (single page for now)
+ *   - the agent picked for the next new chat
+ *   - in-place title patching (used by `chat_title_updated` SSE events to
+ *     avoid clobbering pagination state with a full refresh)
+ *   - create / delete chat actions, with optimistic patching of the local
+ *     list.
+ *
+ * The transport is provided by the consumer so the same hook serves Electron
+ * IPC, the cloud REST client, or any other backend.
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type Dispatch,
+  type SetStateAction,
+} from 'react';
+
+export interface ChatListTransport<TChat, TAgent> {
+  listChats: (input: { page: number; pageSize: number }) => Promise<{
+    chats: TChat[];
+    hasMore: boolean;
+  }>;
+  listAgents: () => Promise<TAgent[]>;
+  createChat?: (input: { agentId?: string }) => Promise<TChat | string>;
+  deleteChat?: (chatId: string) => Promise<boolean>;
+  /** Tell the hook how to read a chat's id and title. */
+  getChatId: (chat: TChat) => string;
+  setChatTitle?: (chat: TChat, title: string) => TChat;
+  /** Tell the hook how to read an agent's id (for `selectedAgentId`). */
+  getAgentId: (agent: TAgent) => string;
+}
+
+export interface UseChatListOptions<TChat, TAgent> {
+  transport: ChatListTransport<TChat, TAgent>;
+  /** Defaults to 50. */
+  pageSize?: number;
+  /** Skip the mount-time fetch (e.g. SSR contexts). */
+  skipInitialLoad?: boolean;
+}
+
+export interface UseChatListReturn<TChat, TAgent> {
+  chats: TChat[];
+  agents: TAgent[];
+  isLoading: boolean;
+  isLoadingMoreChats: boolean;
+  hasMoreChats: boolean;
+  error: Error | null;
+  selectedAgentId: string | null;
+  /**
+   * Accepts either a plain value or a React-style updater function so
+   * adapters can patch the selection without re-reading the current value.
+   */
+  setSelectedAgentId: Dispatch<SetStateAction<string | null>>;
+  refreshChats: () => Promise<void>;
+  refreshAgents: () => Promise<void>;
+  loadMoreChats: () => Promise<void>;
+  createChat: (input?: { agentId?: string }) => Promise<string | null>;
+  deleteChat: (chatId: string) => Promise<boolean>;
+  /** In-place title patcher — does not hit the server. */
+  patchChatTitle: (chatId: string, title: string) => void;
+}
+
+export function useChatList<TChat, TAgent>(
+  options: UseChatListOptions<TChat, TAgent>,
+): UseChatListReturn<TChat, TAgent> {
+  const pageSize = options.pageSize ?? 50;
+  const transportRef = useRef(options.transport);
+  transportRef.current = options.transport;
+
+  const [chats, setChats] = useState<TChat[]>([]);
+  const [agents, setAgents] = useState<TAgent[]>([]);
+  const [isLoading, setLoading] = useState(!options.skipInitialLoad);
+  const [isLoadingMoreChats, setLoadingMore] = useState(false);
+  const [hasMoreChats, setHasMore] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [selectedAgentId, setSelectedAgentId] = useState<string | null>(null);
+  const pageRef = useRef(1);
+  const mountedRef = useRef(true);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const refreshChats = useCallback(async () => {
+    setLoading(true);
+    try {
+      const res = await transportRef.current.listChats({ page: 1, pageSize });
+      if (!mountedRef.current) return;
+      setChats(res.chats);
+      setHasMore(res.hasMore);
+      pageRef.current = 1;
+      setError(null);
+    } catch (err) {
+      if (mountedRef.current) setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      if (mountedRef.current) setLoading(false);
+    }
+  }, [pageSize]);
+
+  const refreshAgents = useCallback(async () => {
+    try {
+      const list = await transportRef.current.listAgents();
+      if (mountedRef.current) setAgents(list);
+    } catch (err) {
+      if (mountedRef.current) setError(err instanceof Error ? err : new Error(String(err)));
+    }
+  }, []);
+
+  const loadMoreChats = useCallback(async () => {
+    if (!hasMoreChats || isLoadingMoreChats) return;
+    setLoadingMore(true);
+    try {
+      const next = pageRef.current + 1;
+      const res = await transportRef.current.listChats({ page: next, pageSize });
+      if (!mountedRef.current) return;
+      setChats((prev) => prev.concat(res.chats));
+      setHasMore(res.hasMore);
+      pageRef.current = next;
+    } catch (err) {
+      if (mountedRef.current) setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      if (mountedRef.current) setLoadingMore(false);
+    }
+  }, [hasMoreChats, isLoadingMoreChats, pageSize]);
+
+  const createChat = useCallback(
+    async (input?: { agentId?: string }) => {
+      const t = transportRef.current;
+      if (!t.createChat) return null;
+      const created = await t.createChat({ agentId: input?.agentId ?? selectedAgentId ?? undefined });
+      // Either a chat object or a bare id.
+      const id = typeof created === 'string' ? created : t.getChatId(created);
+      await refreshChats();
+      return id;
+    },
+    [refreshChats, selectedAgentId],
+  );
+
+  const deleteChat = useCallback(
+    async (chatId: string) => {
+      const t = transportRef.current;
+      if (!t.deleteChat) return false;
+      const ok = await t.deleteChat(chatId);
+      if (ok && mountedRef.current) {
+        setChats((prev) => prev.filter((c) => t.getChatId(c) !== chatId));
+      }
+      return ok;
+    },
+    [],
+  );
+
+  const patchChatTitle = useCallback((chatId: string, title: string) => {
+    const t = transportRef.current;
+    if (!t.setChatTitle) return;
+    setChats((prev) =>
+      prev.map((c) => (t.getChatId(c) === chatId ? t.setChatTitle!(c, title) : c)),
+    );
+  }, []);
+
+  useEffect(() => {
+    if (options.skipInitialLoad) return;
+    void refreshChats();
+    void refreshAgents();
+    // Run once on mount; downstream callers use refresh* explicitly.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return useMemo<UseChatListReturn<TChat, TAgent>>(
+    () => ({
+      chats,
+      agents,
+      isLoading,
+      isLoadingMoreChats,
+      hasMoreChats,
+      error,
+      selectedAgentId,
+      setSelectedAgentId,
+      refreshChats,
+      refreshAgents,
+      loadMoreChats,
+      createChat,
+      deleteChat,
+      patchChatTitle,
+    }),
+    [
+      chats,
+      agents,
+      isLoading,
+      isLoadingMoreChats,
+      hasMoreChats,
+      error,
+      selectedAgentId,
+      refreshChats,
+      refreshAgents,
+      loadMoreChats,
+      createChat,
+      deleteChat,
+      patchChatTitle,
+    ],
+  );
+}

package/src/state/useChatSession.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Tests for `useChatSession` — the composer-meets-stream convenience hook.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { MockChatStreamTransport } from './MockChatStreamTransport';
+import { useChatSession } from './useChatSession';
+
+describe('useChatSession', () => {
+  it('routes composer.submit through the stream pipeline', async () => {
+    const transport = new MockChatStreamTransport({
+      scripts: [[
+        { type: 'content', content: 'pong' },
+        { type: 'done' },
+      ]],
+    });
+    const { result } = renderHook(() =>
+      useChatSession({ transport, initialValue: '' }),
+    );
+
+    await act(async () => {
+      result.current.composer.setValue('ping');
+    });
+    await act(async () => {
+      await result.current.composer.submit();
+    });
+
+    await waitFor(() => {
+      expect(result.current.messages.length).toBeGreaterThanOrEqual(2);
+    });
+    expect(result.current.messages[0].content).toBe('ping');
+    expect(result.current.composer.value).toBe('');
+  });
+
+  it('forwards build metadata onto the transport', async () => {
+    const stream = vi.fn().mockImplementation(async (_input, onEvent) => {
+      onEvent({ type: 'done' });
+      return () => {};
+    });
+    const { result } = renderHook(() =>
+      useChatSession({
+        transport: { stream },
+        buildMetadata: (v) => ({ length: v.length }),
+      }),
+    );
+
+    await act(async () => {
+      result.current.composer.setValue('hello');
+    });
+    await act(async () => {
+      await result.current.composer.submit();
+    });
+
+    expect(stream).toHaveBeenCalledTimes(1);
+    expect(stream.mock.calls[0][0]).toEqual({
+      content: 'hello',
+      metadata: { length: 5 },
+    });
+  });
+});