@useatlas/react 0.0.1

package/src/hooks/use-atlas-chat.ts

@@ -0,0 +1,102 @@
+"use client";
+
+import { useState, useRef, useMemo } from "react";
+import { useChat, type UIMessage } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import { useAtlasContext } from "./provider";
+
+export type AtlasChatStatus = "submitted" | "streaming" | "ready" | "error";
+
+export interface UseAtlasChatOptions {
+  /** Conversation ID to associate with this chat session. The server will append messages to this conversation. To load prior messages, use loadConversation() from useAtlasConversations and pass them via setMessages. */
+  initialConversationId?: string;
+  /** Called when the server assigns or changes the conversation ID. */
+  onConversationIdChange?: (id: string) => void;
+}
+
+export interface UseAtlasChatReturn {
+  messages: UIMessage[];
+  /** Replace all messages, or update via callback `(prev) => next`. */
+  setMessages: (messages: UIMessage[] | ((prev: UIMessage[]) => UIMessage[])) => void;
+  /** Send a text message. Rejects on failure (also surfaces via `error`). */
+  sendMessage: (text: string) => Promise<void>;
+  /** Current input value (managed by the hook). */
+  input: string;
+  /** Update the input value. */
+  setInput: (input: string) => void;
+  /** Chat status from the AI SDK. */
+  status: AtlasChatStatus;
+  /** Whether the chat is currently loading (streaming or submitted). */
+  isLoading: boolean;
+  /** Last error, if any. */
+  error: Error | null;
+  /** Current conversation ID. Initially set from options, updated when the server returns an x-conversation-id header. */
+  conversationId: string | null;
+  /** Manually set the conversation ID. */
+  setConversationId: (id: string | null) => void;
+}
+
+export function useAtlasChat(options: UseAtlasChatOptions = {}): UseAtlasChatReturn {
+  const { apiUrl, apiKey, isCrossOrigin } = useAtlasContext();
+  const [conversationId, setConversationId] = useState<string | null>(
+    options.initialConversationId ?? null,
+  );
+  const conversationIdRef = useRef(conversationId);
+  conversationIdRef.current = conversationId;
+
+  const onChangeRef = useRef(options.onConversationIdChange);
+  onChangeRef.current = options.onConversationIdChange;
+
+  const transport = useMemo(() => {
+    const headers: Record<string, string> = {};
+    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+
+    return new DefaultChatTransport({
+      api: `${apiUrl}/api/chat`,
+      headers,
+      credentials: isCrossOrigin ? "include" : undefined,
+      body: () =>
+        conversationIdRef.current
+          ? { conversationId: conversationIdRef.current }
+          : {},
+      fetch: (async (input: RequestInfo | URL, init?: RequestInit) => {
+        const response = await globalThis.fetch(input, init);
+        const convId = response.headers.get("x-conversation-id");
+        if (convId && convId !== conversationIdRef.current) {
+          setConversationId(convId);
+          onChangeRef.current?.(convId);
+        }
+        return response;
+      }) as typeof fetch,
+    });
+  }, [apiKey, apiUrl, isCrossOrigin]);
+
+  const { messages, setMessages, sendMessage: rawSend, status, error } =
+    useChat({ transport });
+
+  const [input, setInput] = useState("");
+
+  const sendMessage = async (text: string) => {
+    const previousInput = input;
+    setInput("");
+    try {
+      await rawSend({ text });
+    } catch (err) {
+      setInput(previousInput);
+      throw err;
+    }
+  };
+
+  return {
+    messages,
+    setMessages,
+    sendMessage,
+    input,
+    setInput,
+    status: status as AtlasChatStatus,
+    isLoading: status === "streaming" || status === "submitted",
+    error: error ?? null,
+    conversationId,
+    setConversationId,
+  };
+}

package/src/hooks/use-atlas-conversations.ts

@@ -0,0 +1,61 @@
+"use client";
+
+import type { UIMessage } from "@ai-sdk/react";
+import { useAtlasContext } from "./provider";
+import { useConversations } from "./use-conversations";
+import type { Conversation } from "../lib/types";
+
+export interface UseAtlasConversationsOptions {
+  /** When false, refresh() becomes a no-op. Defaults to true. */
+  enabled?: boolean;
+}
+
+export interface UseAtlasConversationsReturn {
+  conversations: Conversation[];
+  total: number;
+  isLoading: boolean;
+  available: boolean;
+  selectedId: string | null;
+  setSelectedId: (id: string | null) => void;
+  refresh: () => Promise<void>;
+  loadConversation: (id: string) => Promise<UIMessage[] | null>;
+  deleteConversation: (id: string) => Promise<boolean>;
+  starConversation: (id: string, starred: boolean) => Promise<boolean>;
+}
+
+/**
+ * Manage conversation history with auth automatically wired from AtlasProvider.
+ *
+ * Wraps the lower-level `useConversations` hook with context-derived
+ * API URL and credentials.
+ */
+export function useAtlasConversations(
+  options: UseAtlasConversationsOptions = {},
+): UseAtlasConversationsReturn {
+  const { apiUrl, apiKey, isCrossOrigin } = useAtlasContext();
+  const { enabled = true } = options;
+
+  const inner = useConversations({
+    apiUrl,
+    enabled,
+    getHeaders: () => {
+      const headers: Record<string, string> = {};
+      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+      return headers;
+    },
+    getCredentials: () => (isCrossOrigin ? "include" : "same-origin"),
+  });
+
+  return {
+    conversations: inner.conversations,
+    total: inner.total,
+    isLoading: inner.loading,
+    available: inner.available,
+    selectedId: inner.selectedId,
+    setSelectedId: inner.setSelectedId,
+    refresh: inner.refresh,
+    loadConversation: inner.loadConversation,
+    deleteConversation: inner.deleteConversation,
+    starConversation: inner.starConversation,
+  };
+}

package/src/hooks/use-atlas-theme.ts

@@ -0,0 +1,34 @@
+"use client";
+
+import {
+  useDarkMode,
+  useThemeMode,
+  setTheme,
+  applyBrandColor,
+  type ThemeMode,
+} from "./use-dark-mode";
+
+export type { ThemeMode };
+
+export interface UseAtlasThemeReturn {
+  /** Current theme setting: "light", "dark", or "system". */
+  theme: ThemeMode;
+  /** Whether the effective (resolved) theme is dark. */
+  isDark: boolean;
+  /** Set the theme mode. Persists to localStorage. */
+  setTheme: (mode: ThemeMode) => void;
+  /** Apply a brand color (oklch format, e.g. "oklch(0.759 0.148 167.71)") via CSS custom property --atlas-brand. */
+  applyBrandColor: (color: string) => void;
+}
+
+export function useAtlasTheme(): UseAtlasThemeReturn {
+  const theme = useThemeMode();
+  const isDark = useDarkMode();
+
+  return {
+    theme,
+    isDark,
+    setTheme,
+    applyBrandColor,
+  };
+}

package/src/hooks/use-conversations.ts

@@ -0,0 +1,189 @@
+"use client";
+
+import { useState, useCallback, useRef } from "react";
+import type { Conversation, ConversationWithMessages, Message } from "../lib/types";
+import type { UIMessage } from "@ai-sdk/react";
+
+export interface UseConversationsOptions {
+  apiUrl: string;
+  enabled: boolean;
+  getHeaders: () => Record<string, string>;
+  getCredentials: () => RequestCredentials;
+}
+
+export interface UseConversationsReturn {
+  conversations: Conversation[];
+  total: number;
+  loading: boolean;
+  available: boolean;
+  selectedId: string | null;
+  setSelectedId: (id: string | null) => void;
+  fetchList: () => Promise<void>;
+  loadConversation: (id: string) => Promise<UIMessage[] | null>;
+  deleteConversation: (id: string) => Promise<boolean>;
+  starConversation: (id: string, starred: boolean) => Promise<boolean>;
+  refresh: () => Promise<void>;
+}
+
+export function transformMessages(messages: Message[]): UIMessage[] {
+  return messages
+    .filter((m) => m.role === "user" || m.role === "assistant")
+    .map((m) => {
+      const content = typeof m.content === "string"
+        ? m.content
+        : JSON.stringify(m.content);
+
+      return {
+        id: m.id,
+        role: m.role as "user" | "assistant",
+        parts: [{ type: "text" as const, text: content }],
+      };
+    });
+}
+
+export function useConversations(opts: UseConversationsOptions): UseConversationsReturn {
+  const [conversations, setConversations] = useState<Conversation[]>([]);
+  const [total, setTotal] = useState(0);
+  const [loading, setLoading] = useState(false);
+  const [available, setAvailable] = useState(true);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const fetchedRef = useRef(false);
+  const networkFailRef = useRef(0);
+
+  const fetchList = useCallback(async () => {
+    if (!opts.enabled || !available) return;
+    setLoading(true);
+    try {
+      const res = await fetch(`${opts.apiUrl}/api/v1/conversations?limit=50`, {
+        headers: opts.getHeaders(),
+        credentials: opts.getCredentials(),
+      });
+
+      if (res.status === 404) {
+        setAvailable(false);
+        return;
+      }
+
+      if (!res.ok) {
+        const errorBody = await res.json().catch(() => null);
+        if (errorBody?.code === "not_available") {
+          setAvailable(false);
+          return;
+        }
+        console.warn(`fetchList: HTTP ${res.status}`, errorBody);
+        return;
+      }
+
+      const data = await res.json();
+      setConversations(data.conversations ?? []);
+      setTotal(data.total ?? 0);
+      fetchedRef.current = true;
+    } catch (err) {
+      console.warn("fetchList error:", err);
+      // Network error before any successful fetch — disable temporarily.
+      // A subsequent explicit fetchList() call can retry.
+      if (!fetchedRef.current) {
+        networkFailRef.current += 1;
+        if (networkFailRef.current >= 3) setAvailable(false);
+      }
+    } finally {
+      setLoading(false);
+    }
+  }, [opts.apiUrl, opts.enabled, opts.getHeaders, opts.getCredentials, available]);
+
+  const loadConversation = useCallback(async (id: string): Promise<UIMessage[] | null> => {
+    try {
+      const res = await fetch(`${opts.apiUrl}/api/v1/conversations/${id}`, {
+        headers: opts.getHeaders(),
+        credentials: opts.getCredentials(),
+      });
+
+      if (!res.ok) {
+        console.warn(`loadConversation: HTTP ${res.status} for ${id}`);
+        return null;
+      }
+
+      const data: ConversationWithMessages = await res.json();
+      return transformMessages(data.messages);
+    } catch (err) {
+      console.warn("loadConversation error:", err);
+      return null;
+    }
+  }, [opts.apiUrl, opts.getHeaders, opts.getCredentials]);
+
+  const deleteConversation = useCallback(async (id: string): Promise<boolean> => {
+    try {
+      const res = await fetch(`${opts.apiUrl}/api/v1/conversations/${id}`, {
+        method: "DELETE",
+        headers: opts.getHeaders(),
+        credentials: opts.getCredentials(),
+      });
+
+      if (!res.ok) {
+        console.warn(`deleteConversation: HTTP ${res.status} for ${id}`);
+        return false;
+      }
+
+      setConversations((prev) => prev.filter((c) => c.id !== id));
+      setTotal((prev) => Math.max(0, prev - 1));
+
+      if (selectedId === id) setSelectedId(null);
+
+      return true;
+    } catch (err) {
+      console.warn("deleteConversation error:", err);
+      return false;
+    }
+  }, [opts.apiUrl, opts.getHeaders, opts.getCredentials, selectedId]);
+
+  const starConversation = useCallback(async (id: string, starred: boolean): Promise<boolean> => {
+    // Optimistic update
+    setConversations((prev) =>
+      prev.map((c) => (c.id === id ? { ...c, starred } : c)),
+    );
+    try {
+      const res = await fetch(`${opts.apiUrl}/api/v1/conversations/${id}/star`, {
+        method: "PATCH",
+        headers: { ...opts.getHeaders(), "Content-Type": "application/json" },
+        credentials: opts.getCredentials(),
+        body: JSON.stringify({ starred }),
+      });
+
+      if (!res.ok) {
+        console.warn(`starConversation: HTTP ${res.status} for ${id}`);
+        // Rollback
+        setConversations((prev) =>
+          prev.map((c) => (c.id === id ? { ...c, starred: !starred } : c)),
+        );
+        return false;
+      }
+
+      return true;
+    } catch (err) {
+      console.warn("starConversation error:", err);
+      // Rollback
+      setConversations((prev) =>
+        prev.map((c) => (c.id === id ? { ...c, starred: !starred } : c)),
+      );
+      return false;
+    }
+  }, [opts.apiUrl, opts.getHeaders, opts.getCredentials]);
+
+  const refresh = useCallback(async () => {
+    await fetchList();
+  }, [fetchList]);
+
+  return {
+    conversations,
+    total,
+    loading,
+    available,
+    selectedId,
+    setSelectedId,
+    fetchList,
+    loadConversation,
+    deleteConversation,
+    starConversation,
+    refresh,
+  };
+}

package/src/hooks/use-dark-mode.ts

@@ -0,0 +1,150 @@
+"use client";
+
+import { createContext, useSyncExternalStore } from "react";
+
+// ---------------------------------------------------------------------------
+// Theme types & constants
+// ---------------------------------------------------------------------------
+
+import { THEME_STORAGE_KEY } from "./theme-init-script";
+
+export type ThemeMode = "light" | "dark" | "system";
+
+export { THEME_STORAGE_KEY };
+
+/**
+ * Default brand color — must match `brand.css` `:root { --atlas-brand }` and
+ * the `ATLAS_BRAND_COLOR` default in `packages/api/src/lib/settings.ts`.
+ */
+export const DEFAULT_BRAND_COLOR = "oklch(0.759 0.148 167.71)";
+
+/** Basic oklch format check — prevents obviously invalid values from breaking the theme. */
+export const OKLCH_RE = /^oklch\(\s*[\d.]+\s+[\d.]+\s+[\d.]+\s*(?:\/\s*[\d.%]+\s*)?\)$/;
+
+// ---------------------------------------------------------------------------
+// Shared state — single source of truth for the chosen mode.
+// Listeners are notified on change so useSyncExternalStore re-renders.
+// ---------------------------------------------------------------------------
+
+let _mode: ThemeMode = "system";
+const _listeners = new Set<() => void>();
+
+function notify() {
+  for (const fn of _listeners) fn();
+}
+
+/** Read stored preference (called once on module load in the browser). */
+function init() {
+  try {
+    const stored = localStorage.getItem(THEME_STORAGE_KEY);
+    if (stored === "light" || stored === "dark" || stored === "system") {
+      _mode = stored;
+    }
+  } catch (err) {
+    console.warn("Could not read theme preference from localStorage:", err);
+  }
+}
+
+if (typeof window !== "undefined") init();
+
+// ---------------------------------------------------------------------------
+// Derived boolean: is the effective theme dark?
+// ---------------------------------------------------------------------------
+
+function systemPrefersDark(): boolean {
+  return typeof window !== "undefined" && window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+function resolveIsDark(mode: ThemeMode): boolean {
+  if (mode === "dark") return true;
+  if (mode === "light") return false;
+  return systemPrefersDark();
+}
+
+function applyClass(isDark: boolean) {
+  if (typeof document === "undefined") return;
+  document.documentElement.classList.toggle("dark", isDark);
+}
+
+// ---------------------------------------------------------------------------
+// External store for isDark (reacts to both mode changes AND system changes)
+// ---------------------------------------------------------------------------
+
+function subscribeIsDark(onChange: () => void) {
+  _listeners.add(onChange);
+
+  // Also listen for system preference changes (relevant when mode === "system").
+  // Apply dark class immediately on OS change so the DOM stays in sync before React re-renders.
+  const mq = window.matchMedia("(prefers-color-scheme: dark)");
+  const handler = () => {
+    applyClass(resolveIsDark(_mode));
+    onChange();
+  };
+  mq.addEventListener("change", handler);
+
+  return () => {
+    _listeners.delete(onChange);
+    mq.removeEventListener("change", handler);
+  };
+}
+
+function getSnapshotIsDark() {
+  return resolveIsDark(_mode);
+}
+
+function getServerSnapshotIsDark() {
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// External store for mode
+// ---------------------------------------------------------------------------
+
+function subscribeMode(onChange: () => void) {
+  _listeners.add(onChange);
+  return () => {
+    _listeners.delete(onChange);
+  };
+}
+
+function getSnapshotMode() {
+  return _mode;
+}
+
+function getServerSnapshotMode(): ThemeMode {
+  return "system";
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function setTheme(mode: ThemeMode) {
+  _mode = mode;
+  const isDark = resolveIsDark(mode);
+  applyClass(isDark);
+  try {
+    localStorage.setItem(THEME_STORAGE_KEY, mode);
+  } catch (err) {
+    console.warn("Could not persist theme preference to localStorage:", err);
+  }
+  notify();
+}
+
+/** Apply --atlas-brand on :root so theme tokens update without reload. */
+export function applyBrandColor(color: string) {
+  if (typeof document === "undefined") return;
+  document.documentElement.style.setProperty("--atlas-brand", color);
+}
+
+export const DarkModeContext = createContext(false);
+
+/** Returns whether the effective theme is dark. */
+export function useDarkMode(): boolean {
+  return useSyncExternalStore(subscribeIsDark, getSnapshotIsDark, getServerSnapshotIsDark);
+}
+
+/** Returns the current ThemeMode ("light" | "dark" | "system"). */
+export function useThemeMode(): ThemeMode {
+  return useSyncExternalStore(subscribeMode, getSnapshotMode, getServerSnapshotMode);
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+// Core component
+export { AtlasChat } from "./components/atlas-chat";
+export type { AtlasChatProps } from "./components/atlas-chat";
+
+// Context & providers
+export { AtlasUIProvider, useAtlasConfig } from "./context";
+export type { AtlasUIConfig, AtlasAuthClient } from "./context";
+
+// Theme
+export { setTheme } from "./hooks/use-dark-mode";
+export type { ThemeMode } from "./hooks/use-dark-mode";
+export { buildThemeInitScript, THEME_STORAGE_KEY } from "./hooks/theme-init-script";
+
+// Types
+export type {
+  AuthMode,
+  Conversation,
+  Message,
+  ConversationWithMessages,
+  ChatErrorCode,
+  ChatErrorInfo,
+} from "./lib/types";
+export { AUTH_MODES, parseChatError } from "./lib/types";
+
+// Tool renderer types
+export type {
+  ToolRendererProps,
+  ToolRenderers,
+  SQLToolResult,
+  ExploreToolResult,
+  PythonToolResult,
+} from "./lib/tool-renderer-types";
+
+// Hooks
+export { useConversations } from "./hooks/use-conversations";
+export type { UseConversationsOptions, UseConversationsReturn } from "./hooks/use-conversations";

package/src/lib/action-types.ts

@@ -0,0 +1,11 @@
+export {
+  ALL_STATUSES,
+  RESOLVED_STATUSES,
+  isActionToolResult,
+} from "@useatlas/types/action";
+export type {
+  ActionStatus,
+  ResolvedStatus,
+  ActionToolResultShape,
+  ActionApprovalResponse,
+} from "@useatlas/types/action";