@useatlas/react 0.0.1

package/src/lib/helpers.ts

@@ -0,0 +1,198 @@
+/** Extract tool invocation input from a ToolUIPart. Returns empty object if unavailable. */
+export function getToolArgs(part: unknown): Record<string, unknown> {
+  if (part == null || typeof part !== "object") return {};
+  const input = (part as Record<string, unknown>).input;
+  if (input == null || typeof input !== "object") return {};
+  return input as Record<string, unknown>;
+}
+
+/** Extract tool output from a ToolUIPart. Returns null if not yet available. */
+export function getToolResult(part: unknown): unknown {
+  if (part == null || typeof part !== "object") return null;
+  return (part as Record<string, unknown>).output ?? null;
+}
+
+/** True when the tool invocation has finished successfully (state is "output-available"). */
+export function isToolComplete(part: unknown): boolean {
+  if (part == null || typeof part !== "object") return false;
+  return (part as Record<string, unknown>).state === "output-available";
+}
+
+/** Parse a CSV string into headers + rows. Handles basic quoting and escaped quotes (""). */
+export function parseCSV(csv: string): { headers: string[]; rows: string[][] } {
+  if (!csv || !csv.trim()) return { headers: [], rows: [] };
+
+  const lines = csv.trim().split("\n");
+  if (lines.length === 0) return { headers: [], rows: [] };
+
+  function parseLine(line: string): string[] {
+    const result: string[] = [];
+    let current = "";
+    let inQuotes = false;
+    for (let k = 0; k < line.length; k++) {
+      const char = line[k];
+      if (char === '"') {
+        if (inQuotes && line[k + 1] === '"') {
+          current += '"';
+          k++;
+        } else {
+          inQuotes = !inQuotes;
+        }
+      } else if (char === "," && !inQuotes) {
+        result.push(current.trim());
+        current = "";
+      } else {
+        current += char;
+      }
+    }
+    result.push(current.trim());
+    return result;
+  }
+
+  return {
+    headers: parseLine(lines[0]),
+    rows: lines
+      .slice(1)
+      .filter((l) => l.trim())
+      .map(parseLine),
+  };
+}
+
+/** Serialize columns + rows to a CSV string. Handles commas, quotes, and newlines in values. */
+export function toCsvString(columns: string[], rows: Record<string, unknown>[]): string {
+  const escape = (v: unknown) => {
+    const s = v == null ? "" : String(v);
+    return s.includes(",") || s.includes('"') || s.includes("\n")
+      ? `"${s.replace(/"/g, '""')}"`
+      : s;
+  };
+  const header = columns.map(escape).join(",");
+  const body = rows.map((row) => columns.map((col) => escape(row[col])).join(","));
+  return [header, ...body].join("\n");
+}
+
+/** Trigger a CSV download in the browser. */
+export function downloadCSV(csv: string, filename = "atlas-results.csv") {
+  let url: string | null = null;
+  try {
+    const blob = new Blob([csv], { type: "text/csv" });
+    url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = filename;
+    a.click();
+  } catch (err) {
+    console.error("CSV download failed:", err);
+    window.alert("CSV download failed");
+  } finally {
+    if (url) {
+      const blobUrl = url;
+      setTimeout(() => URL.revokeObjectURL(blobUrl), 10_000);
+    }
+  }
+}
+
+/** Strict ISO date pattern: YYYY-MM-DD with optional time component. */
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})?)?$/;
+
+/** Coerce a cell value to a typed Excel cell: numbers/booleans pass through, ISO dates become Date objects, null becomes empty string. Exported for testing. */
+export function coerceExcelCell(v: unknown): unknown {
+  if (v == null) return "";
+  if (typeof v === "number" || typeof v === "boolean") return v;
+  if (typeof v === "string" && ISO_DATE_RE.test(v) && !isNaN(Date.parse(v))) {
+    return new Date(v);
+  }
+  return String(v);
+}
+
+/** Trigger an Excel (.xlsx) download in the browser. Dynamically imports xlsx to avoid bundle bloat. */
+export async function downloadExcel(
+  columns: string[],
+  rows: Record<string, unknown>[],
+  filename = "atlas-results.xlsx",
+) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let XLSX: any;
+  try {
+    XLSX = await import("xlsx" /* webpackIgnore: true */);
+  } catch (err) {
+    console.error("Failed to load xlsx library:", err);
+    window.alert("Excel export is unavailable. The spreadsheet library failed to load.");
+    return;
+  }
+
+  let url: string | null = null;
+  try {
+    const data = rows.map((row) => {
+      const obj: Record<string, unknown> = {};
+      for (const col of columns) {
+        obj[col] = coerceExcelCell(row[col]);
+      }
+      return obj;
+    });
+    const ws = XLSX.utils.json_to_sheet(data, { header: columns });
+    const wb = XLSX.utils.book_new();
+    XLSX.utils.book_append_sheet(wb, ws, "Results");
+    const wbOut = XLSX.write(wb, { bookType: "xlsx", type: "array" });
+    const blob = new Blob([wbOut], {
+      type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    });
+    url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = filename;
+    a.click();
+  } catch (err) {
+    console.error("Excel download failed:", err);
+    const detail = err instanceof Error ? err.message : "Unknown error";
+    window.alert(`Excel download failed: ${detail}\n\nYou can try the CSV download as an alternative.`);
+  } finally {
+    if (url) {
+      const blobUrl = url;
+      setTimeout(() => URL.revokeObjectURL(blobUrl), 10_000);
+    }
+  }
+}
+
+const SUGGESTIONS_RE = /<suggestions>\s*([\s\S]*?)\s*<\/suggestions>/g;
+
+/** Extract follow-up suggestions from assistant message content and return the cleaned text + suggestions.
+ *  All `<suggestions>` blocks are stripped; suggestions from all blocks are merged. */
+export function parseSuggestions(content: string): { text: string; suggestions: string[] } {
+  const suggestions: string[] = [];
+  let match;
+  while ((match = SUGGESTIONS_RE.exec(content)) !== null) {
+    const lines = match[1].split("\n").map((l) => l.trim()).filter(Boolean);
+    suggestions.push(...lines);
+  }
+  SUGGESTIONS_RE.lastIndex = 0;
+  if (suggestions.length === 0) return { text: content, suggestions: [] };
+  const text = content.replace(SUGGESTIONS_RE, "").trimEnd();
+  SUGGESTIONS_RE.lastIndex = 0;
+  return { text, suggestions: suggestions.slice(0, 5) };
+}
+
+/**
+ * Normalize a record-or-array field from the API into a flat array.
+ * When the data is a Record, the key is merged in under `keyName`.
+ * Used by both admin entity-detail and schema explorer components.
+ */
+export function normalizeList<T>(
+  data: Record<string, T> | T[] | undefined,
+  keyName: string,
+): (T & Record<string, unknown>)[] {
+  if (!data) return [];
+  if (Array.isArray(data)) return data as (T & Record<string, unknown>)[];
+  return Object.entries(data).map(([key, value]) => ({ ...value, [keyName]: key }));
+}
+
+/** Format a cell value: null as em-dash, numbers with locale formatting, else stringified. */
+export function formatCell(value: unknown): string {
+  if (value == null) return "\u2014";
+  if (typeof value === "number") {
+    return Number.isInteger(value)
+      ? value.toLocaleString()
+      : value.toLocaleString(undefined, { maximumFractionDigits: 2 });
+  }
+  return String(value);
+}

package/src/lib/tool-renderer-types.ts

@@ -0,0 +1,76 @@
+import type { ComponentType } from "react";
+
+/** Props passed to custom tool renderers. */
+export interface ToolRendererProps<T = unknown> {
+  /** Name of the tool being rendered. */
+  toolName: string;
+  /** Input arguments passed to the tool invocation. */
+  args: Record<string, unknown>;
+  /** Tool output. For built-in tools, `null` while the tool is still running. */
+  result: T;
+  /** Whether the tool invocation is still in progress. */
+  isLoading: boolean;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Known tool result types                                            */
+/* ------------------------------------------------------------------ */
+
+/** Result shape from the executeSQL tool. Subset covering fields most useful for rendering. */
+export type SQLToolResult =
+  | {
+      success: true;
+      columns: string[];
+      rows: Record<string, unknown>[];
+      truncated?: boolean;
+      explanation?: string;
+      row_count?: number;
+    }
+  | {
+      success: false;
+      error: string;
+    };
+
+/** Result shape from the explore tool (semantic layer exploration output). */
+export type ExploreToolResult = string;
+
+/** Result shape from the executePython tool. */
+export type PythonToolResult =
+  | {
+      success: true;
+      output?: string;
+      explanation?: string;
+      table?: { columns: string[]; rows: unknown[][] };
+      charts?: { base64: string; mimeType: "image/png" }[];
+      rechartsCharts?: {
+        type: "line" | "bar" | "pie";
+        data: Record<string, unknown>[];
+        categoryKey: string;
+        valueKeys: string[];
+      }[];
+    }
+  | {
+      success: false;
+      error: string;
+      output?: string;
+    };
+
+/* ------------------------------------------------------------------ */
+/*  Tool renderers map                                                 */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Map of tool names to custom renderer components.
+ *
+ * Known tool names (executeSQL, explore, executePython) get typed result generics.
+ * Arbitrary tool names are also supported via the index signature with `unknown` result type.
+ *
+ * Custom renderers take precedence over built-in defaults, including the action approval UI.
+ */
+export type ToolRenderers = {
+  executeSQL?: ComponentType<ToolRendererProps<SQLToolResult | null>>;
+  explore?: ComponentType<ToolRendererProps<ExploreToolResult | null>>;
+  executePython?: ComponentType<ToolRendererProps<PythonToolResult | null>>;
+} & {
+  [toolName: string]: ComponentType<ToolRendererProps> | undefined;
+};

package/src/lib/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared types for Atlas UI.
+ *
+ * All types are canonical from @useatlas/types — no local duplication.
+ */
+
+export { AUTH_MODES, DB_TYPES, CHAT_ERROR_CODES } from "@useatlas/types";
+export type {
+  AuthMode,
+  MessageRole,
+  Surface,
+  Conversation,
+  Message,
+  ConversationWithMessages,
+  DBType,
+  HealthStatus,
+  ConnectionHealth,
+  ConnectionInfo,
+  ChatErrorCode,
+  ChatErrorInfo,
+  Dimension,
+  Join,
+  Measure,
+  QueryPattern,
+  SemanticEntitySummary,
+  SemanticEntityDetail,
+  EntityData,
+} from "@useatlas/types";
+export { authErrorMessage, parseChatError } from "@useatlas/types/errors";

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/src/styles.css

@@ -0,0 +1,59 @@
+/*
+ * @useatlas/react — Base styles
+ *
+ * Import this CSS in your app:
+ *   import "@useatlas/react/styles.css";
+ *
+ * Also configure Tailwind CSS 4 to scan this package:
+ *   @source "../node_modules/@useatlas/react/dist";
+ *
+ * These CSS custom properties define the Atlas design tokens.
+ * They match shadcn/ui's "neutral" base with "new-york" style.
+ * Scoped to .atlas-root to avoid clobbering host app styles.
+ */
+
+.atlas-root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --atlas-brand: oklch(0.759 0.148 167.71);
+}
+
+.dark .atlas-root {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.145 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.145 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.985 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.396 0.141 25.723);
+  --destructive-foreground: oklch(0.637 0.237 25.331);
+  --border: oklch(0.269 0 0);
+  --input: oklch(0.269 0 0);
+  --ring: oklch(0.439 0 0);
+}

package/src/test-setup.ts

@@ -0,0 +1,55 @@
+import { Window } from "happy-dom";
+
+const win = new Window({ url: "http://localhost:3000" });
+
+const DOM_GLOBALS = [
+  "document", "navigator", "location", "history", "screen",
+  "HTMLElement", "HTMLInputElement", "HTMLTextAreaElement", "HTMLButtonElement",
+  "HTMLFormElement", "HTMLAnchorElement", "HTMLImageElement", "HTMLDivElement",
+  "HTMLSpanElement", "HTMLTableElement", "HTMLPreElement", "HTMLHeadingElement",
+  "HTMLParagraphElement", "HTMLUListElement", "HTMLOListElement", "HTMLLIElement",
+  "HTMLQuoteElement", "HTMLTableRowElement", "HTMLTableCellElement",
+  "HTMLTableSectionElement", "HTMLBRElement", "HTMLHRElement",
+  "HTMLSelectElement", "HTMLOptionElement", "HTMLCanvasElement",
+  "HTMLBodyElement", "HTMLHtmlElement", "HTMLStyleElement", "HTMLScriptElement",
+  "HTMLLinkElement", "HTMLMetaElement", "HTMLLabelElement",
+  "Element", "Node", "Text", "Comment", "Document", "DocumentFragment",
+  "NodeList", "HTMLCollection", "NamedNodeMap",
+  "DOMParser", "XMLSerializer", "Range", "Selection",
+  "TreeWalker", "NodeIterator", "NodeFilter",
+  "CSSStyleDeclaration", "CSSStyleSheet", "StyleSheet", "MediaQueryList",
+  "DOMTokenList", "DOMRect", "DOMRectReadOnly",
+  "Event", "MouseEvent", "KeyboardEvent", "FocusEvent", "InputEvent", "CustomEvent",
+  "PointerEvent", "WheelEvent", "UIEvent", "ErrorEvent", "ProgressEvent",
+  "AnimationEvent", "TransitionEvent", "ClipboardEvent",
+  "MutationObserver", "MutationRecord", "IntersectionObserver", "ResizeObserver",
+  "Headers", "Request", "Response", "URL", "URLSearchParams",
+  "Blob", "File", "FileReader", "FormData", "FileList",
+  "AbortController", "AbortSignal",
+  "SVGElement", "SVGSVGElement",
+  "Image", "getComputedStyle", "matchMedia",
+  "DOMException",
+  "XMLHttpRequest", "WebSocket",
+  "Storage", "localStorage", "sessionStorage",
+] as const;
+
+for (const key of DOM_GLOBALS) {
+  const val = (win as unknown as Record<string, unknown>)[key];
+  if (val !== undefined) {
+    try {
+      const descriptor = Object.getOwnPropertyDescriptor(globalThis, key);
+      if (descriptor && !descriptor.configurable) continue;
+      (globalThis as Record<string, unknown>)[key] = val;
+    } catch {
+      // skip non-configurable globals
+    }
+  }
+}
+
+try { (globalThis as Record<string, unknown>).window = win; }
+catch { /* skip */ }
+try { (globalThis as Record<string, unknown>).self = win; }
+catch { /* skip */ }
+(globalThis as Record<string, unknown>).requestAnimationFrame = (cb: FrameRequestCallback) =>
+  setTimeout(cb, 0) as unknown as number;
+(globalThis as Record<string, unknown>).cancelAnimationFrame = (id: number) => clearTimeout(id);

package/src/widget-entry.ts

@@ -0,0 +1,20 @@
+/**
+ * Widget bundle entry point.
+ *
+ * Produces a self-contained ESM file that exposes React, ReactDOM/client,
+ * and the AtlasChat component on `globalThis.AtlasWidget` so the widget
+ * host HTML can render without any external CDN dependencies.
+ *
+ * Built by `tsup` — see tsup.config.ts for the widget-specific config.
+ */
+
+import { createElement, Component } from "react";
+import { createRoot } from "react-dom/client";
+import { AtlasChat } from "./components/atlas-chat";
+import { setTheme } from "./hooks/use-dark-mode";
+
+const AtlasWidget = { createElement, Component, createRoot, AtlasChat, setTheme };
+
+Object.assign(globalThis, { AtlasWidget });
+
+export { createElement, Component, createRoot, AtlasChat, setTheme };

package/src/widget.css

@@ -0,0 +1,12 @@
+/*
+ * Widget Tailwind CSS source.
+ *
+ * Compiled by @tailwindcss/cli during `bun run build` to produce
+ * dist/widget.css — a static CSS file containing all Tailwind
+ * utility classes used by @useatlas/react components.
+ *
+ * Pre-compiled at build time to avoid runtime CSS generation overhead.
+ */
+
+@import "tailwindcss";
+@source "./";