orchid-ai 2.0.0 → 2.0.2

package/orchid-ai.css

@@ -244,6 +244,9 @@
   border: 1px solid #e5e7eb;
   border-radius: 12px;
   padding: 16px 20px;
+  width: 100%;
+  max-width: 420px;
+  box-sizing: border-box;
 }
 
 .ai-chat-suggestions span {
@@ -260,6 +263,7 @@
   display: flex;
   flex-direction: column;
   gap: 8px;
+  padding: 0;
 }
 
 .ai-chat-suggestions li {
@@ -271,6 +275,8 @@
   border-radius: 8px;
   cursor: pointer;
   transition: background 0.15s, border-color 0.15s, color 0.15s;
+  width: 100%;
+  box-sizing: border-box;
 }
 
 .ai-chat-suggestions li:hover {
@@ -279,6 +285,17 @@
   color: #1eaaf1;
 }
 
+.ai-chat-suggestions--disabled li {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.ai-chat-suggestions--disabled li:hover {
+  background: #f9fafb;
+  border-color: #e5e7eb;
+  color: #4b5563;
+}
+
 /* ── Messages ── */
 
 .ai-chat-message {
@@ -347,6 +364,16 @@
   border-bottom-right-radius: 4px;
 }
 
+.ai-chat-bubble.user .ai-chat-user-link {
+  color: #e0f2fe;
+  text-decoration: underline;
+  word-break: break-all;
+}
+
+.ai-chat-bubble.user .ai-chat-user-link:hover {
+  color: #ffffff;
+}
+
 .ai-chat-bubble.assistant {
   position: relative;
   background: #ffffff;
@@ -1917,47 +1944,61 @@
 /* ── Print (Single Response) ── */
 
 @media print {
-  @page {
-    margin: 12mm;
+  @page { margin: 12mm; }
+
+  /*
+   * visibility:hidden on body allows #ai-cortex-print-section descendants to
+   * override with visibility:visible — this is a CSS guarantee that display:none
+   * does NOT offer (Chrome's print engine ignores the specificity override for
+   * display:none !important on body > *).
+   *
+   * Siblings are collapsed to height:0 so no blank space precedes the section.
+   * position:absolute (not fixed) allows content to paginate across pages.
+   */
+  body.ai-chat-printing {
+    visibility: hidden !important;
+    position: relative !important;
   }
 
-  /* Hide everything on the page; show only the isolated print section. */
-  body.ai-chat-printing > * {
-    display: none !important;
+  body.ai-chat-printing > *:not(#ai-cortex-print-section) {
+    height: 0 !important;
+    overflow: hidden !important;
   }
 
   body.ai-chat-printing #ai-cortex-print-section {
+    visibility: visible !important;
     display: block !important;
+    position: absolute !important;
+    top: 0 !important;
+    left: 0 !important;
+    width: 100% !important;
+    padding: 0 !important;
+    background: #ffffff;
+    color: #1f2937;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    font-size: 14px;
+    line-height: 1.6;
   }
 
-  /*
-   * Kill all CSS animations and transitions inside the print section.
-   * Browsers reset animations during the print reflow, catching elements at
-   * their `from` keyframe (opacity: 0, scale: 0) rather than their final state.
-   * Disabling animations lets elements fall back to their base CSS styles,
-   * which are always the fully-visible final appearance.
-   *
-   * print-color-adjust: exact forces Chrome to render background colours and
-   * images — without it Chrome strips inline background fills (e.g. dot colours
-   * on scatter/dot charts) and the dots appear as white outlines only.
-   */
   body.ai-chat-printing #ai-cortex-print-section * {
+    visibility: visible !important;
     animation: none !important;
     transition: none !important;
+    /* Kill any opacity:0 left by a stopped animation */
+    opacity: 1 !important;
     -webkit-print-color-adjust: exact !important;
     print-color-adjust: exact !important;
   }
 
-  /* Clean up the bubble for print */
   body.ai-chat-printing #ai-cortex-print-section .ai-chat-bubble.assistant {
-    max-width: none;
-    width: 100%;
-    border: none;
-    border-radius: 0;
-    padding: 0;
-    background: #ffffff;
-    color: #111827;
-    box-shadow: none;
+    max-width: none !important;
+    width: 100% !important;
+    border: none !important;
+    border-radius: 0 !important;
+    padding: 0 !important;
+    background: #ffffff !important;
+    color: #1f2937 !important;
+    box-shadow: none !important;
   }
 }
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "orchid-ai",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Shared Orchid AI chat UI and visualization components",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "exports": {
     ".": "./src/index.js",
     "./orchid-ai.css": "./orchid-ai.css",

package/src/components/ChatWindow.jsx

@@ -1,8 +1,14 @@
 import React, { useRef, useEffect } from 'react';
 import Message from './Message';
 
+const DEFAULT_SUGGESTIONS = [
+  'Give me brief tips for navigating iLink.',
+  'What should I check before starting a dispatch?',
+  'How do I narrow down a search in Hermes command search (⌘K)?',
+];
+
 /**
- * Hermes chat window (Markdown + optional orchid-ai-chart fenced blocks).
+ * Orchid AI chat window (Markdown + optional orchid-ai-chart fenced blocks).
  */
 export default function ChatWindow({
   messages,
@@ -11,7 +17,13 @@ export default function ChatWindow({
   onSuggestionClick,
   aiEnabled,
   organisationName,
+  appName = "Hermes Chat",
+  unavailableMessage,
+  emptyDescription,
+  suggestions = DEFAULT_SUGGESTIONS,
+  suggestionsDisabled = false,
 }) {
+  const exportPrefix = appName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
   const bottomRef = useRef(null);
 
   useEffect(() => {
@@ -20,6 +32,8 @@ export default function ChatWindow({
 
   const renderEmptyState = () => {
     if (!aiEnabled) {
+      const msg = unavailableMessage ??
+        `${appName} needs an Anthropic API key on the server. Contact your administrator if this persists.`;
       return (
         <div className="ai-chat-empty">
           <div className="ai-chat-empty-icon">
@@ -37,16 +51,14 @@ export default function ChatWindow({
               <line x1="4.93" y1="4.93" x2="19.07" y2="19.07" />
             </svg>
           </div>
-          <h2>Hermes Chat unavailable</h2>
-          <p>
-            Hermes Chat needs an Anthropic API key on the server and an active organisation. Contact your administrator
-            if this persists.
-          </p>
+          <h2>{appName} unavailable</h2>
+          <p>{msg}</p>
         </div>
       );
     }
 
     const scope = organisationName || 'your organisation';
+    const description = emptyDescription ?? `Ask about ${scope} — shipments, schedules, data insights, or what to explore next.`;
 
     return (
       <div className="ai-chat-empty">
@@ -67,21 +79,23 @@ export default function ChatWindow({
           </svg>
         </div>
         <h2>How can I help?</h2>
-        <p>{`Ask about ${scope} — jobs, routes, schedules, reminders, or what to explore next.`}</p>
-        <div className="ai-chat-suggestions">
-          <span>Try asking:</span>
-          <ul>
-            <li onClick={() => onSuggestionClick('Give me brief tips for navigating iLink.')}>
-              Give me brief tips for navigating iLink.
-            </li>
-            <li onClick={() => onSuggestionClick('What should I check before starting a dispatch?')}>
-              What should I check before starting a dispatch?
-            </li>
-            <li onClick={() => onSuggestionClick('How do I narrow down a search in Hermes command search (⌘K)?')}>
-              How do I narrow down a search in Hermes command search (⌘K)?
-            </li>
-          </ul>
-        </div>
+        <p>{description}</p>
+        {suggestions.length > 0 && (
+          <div className={`ai-chat-suggestions${suggestionsDisabled ? ' ai-chat-suggestions--disabled' : ''}`}>
+            <span>Try asking:</span>
+            <ul>
+              {suggestions.map((s) => (
+                <li
+                  key={s}
+                  onClick={suggestionsDisabled ? undefined : () => onSuggestionClick(s)}
+                  aria-disabled={suggestionsDisabled || undefined}
+                >
+                  {s}
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
       </div>
     );
   };
@@ -90,7 +104,7 @@ export default function ChatWindow({
     <div className="ai-chat-window">
       {messages?.length === 0 && !loading && renderEmptyState()}
       {(messages ?? []).map((msg, i) => (
-        <Message key={i} role={msg.role} content={msg.content} truncated={msg.truncated} />
+        <Message key={i} role={msg.role} content={msg.content} truncated={msg.truncated} exportPrefix={exportPrefix} />
       ))}
       {loading && (
         <div className="ai-chat-message assistant">

package/src/components/Message.jsx

@@ -9,7 +9,46 @@ const IS_DEV = process.env.NODE_ENV === "development";
 
 const TITLE_RE = /<!--\s*title:\s*([^-][^>]*?)\s*-->/i;
 
-export default function Message({ role, content, truncated }) {
+/** Split on http(s) URLs for lightweight linkify in user bubbles (plain text, not full markdown). */
+const URL_INLINE_RE = /(https?:\/\/[^\s<>`]+)/gi;
+
+function trimTrailingUrlPunctuation(href) {
+  return href.replace(/[),.;:!?'"\]}>]+$/g, "");
+}
+
+function linkifyUserLine(line) {
+  const parts = String(line).split(URL_INLINE_RE);
+  return parts.map((part, i) => {
+    if (part === "") return null;
+    if (/^https?:\/\//i.test(part)) {
+      const href = trimTrailingUrlPunctuation(part);
+      return (
+        <a
+          key={i}
+          href={href}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="ai-chat-user-link"
+        >
+          {part}
+        </a>
+      );
+    }
+    return <React.Fragment key={i}>{part}</React.Fragment>;
+  });
+}
+
+function UserBubbleContent({ content }) {
+  const lines = String(content).split("\n");
+  return lines.map((line, li) => (
+    <React.Fragment key={li}>
+      {li > 0 ? <br /> : null}
+      {linkifyUserLine(line)}
+    </React.Fragment>
+  ));
+}
+
+export default function Message({ role, content, truncated, exportPrefix = "orchid-ai" }) {
   const isUser = role === "user";
   const [copied, setCopied] = useState(false);
   const [isPrinting, setIsPrinting] = useState(false);
@@ -56,23 +95,21 @@ export default function Message({ role, content, truncated }) {
     const pad = (v) => String(v).padStart(2, "0");
     const timestamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}_${pad(now.getHours())}${pad(now.getMinutes())}`;
 
+    setIsPrinting(true);
+
+    const clone = bubbleContent.cloneNode(true);
+    clone.querySelectorAll(".ai-chart-export-actions, .ai-chat-message-actions").forEach((n) => n.remove());
+
     setIsPrinting(true);
     const previousTitle = document.title;
-    document.title = `orchid-ai-${slug}-${timestamp}`;
+    document.title = `${exportPrefix}-${slug}-${timestamp}`;
 
-    // Clone the bubble content into an isolated print section at the body root.
-    // This keeps the layout clean (no surrounding app chrome) while the CSS
-    // animation: none rule ensures chart elements render at their final visible
-    // state rather than being caught mid-animation by the print reflow.
     let printSection = document.getElementById("ai-cortex-print-section");
     if (!printSection) {
       printSection = document.createElement("div");
       printSection.id = "ai-cortex-print-section";
       document.body.appendChild(printSection);
     }
-
-    const clone = bubbleContent.cloneNode(true);
-    clone.querySelectorAll(".ai-chart-export-actions, .ai-chat-message-actions").forEach((n) => n.remove());
     printSection.innerHTML = "";
     printSection.appendChild(clone);
     document.body.classList.add("ai-chat-printing");
@@ -147,6 +184,16 @@ export default function Message({ role, content, truncated }) {
         </code>
       );
     },
+    a({ href, children, ...props }) {
+      if (typeof href !== "string" || !/^https?:\/\//i.test(href)) {
+        return <span {...props}>{children}</span>;
+      }
+      return (
+        <a {...props} href={href} target="_blank" rel="noopener noreferrer">
+          {children}
+        </a>
+      );
+    },
   };
 
   return (
@@ -157,12 +204,7 @@ export default function Message({ role, content, truncated }) {
       <div className={`ai-chat-bubble ${role}`}>
         <div className="ai-chat-message-content">
           {isUser ? (
-            content.split("\n").map((line, i) => (
-              <React.Fragment key={i}>
-                {line}
-                {i < content.split("\n").length - 1 && <br />}
-              </React.Fragment>
-            ))
+            <UserBubbleContent content={content} />
           ) : (
             <ReactMarkdown remarkPlugins={[remarkGfm]} components={markdownComponents}>{renderContent}</ReactMarkdown>
           )}

package/src/hooks/useOrchidAiChat.js

@@ -0,0 +1,136 @@
+import { useState, useCallback, useRef } from 'react';
+
+/**
+ * Default status message strings. Export these so server-side code can import
+ * and reference the same values, making it easy to keep client and server in sync
+ * or swap them out per-app.
+ *
+ * Set showStatus: false on the hook to disable status display entirely.
+ */
+export const ORCHID_AI_DEFAULT_STATUS = {
+  thinking: 'Thinking',
+  compilingResponse: 'Compiling response',
+  lookingUpData: 'Looking up data',
+};
+
+/**
+ * React hook for Orchid AI chat. Handles SSE streaming when the server responds
+ * with Content-Type: text/event-stream, falling back to plain JSON for non-streaming
+ * backends.
+ *
+ * @param {object} opts
+ * @param {string} opts.endpoint - POST endpoint URL
+ * @param {(userMessage: string, history: Array, sendOptions?: object) => object} opts.buildBody - builds the request body
+ * @param {() => object} [opts.getHeaders] - returns extra request headers (e.g. CSRF token)
+ * @param {boolean} [opts.showStatus=true] - set false to suppress status text entirely
+ * @param {Array} [opts.initialMessages=[]] - seed the conversation (e.g. from localStorage)
+ *
+ * @returns {{ messages, loading, statusText, sendMessage, clearMessages }}
+ */
+export function useOrchidAiChat({ endpoint, buildBody, getHeaders, showStatus = true, initialMessages = [] }) {
+  const [messages, setMessages] = useState(initialMessages);
+  const [loading, setLoading] = useState(false);
+  const [statusText, setStatusText] = useState('');
+
+  // Track messages in a ref so sendMessage always reads the latest without needing
+  // messages in its dependency array (avoids capturing stale history).
+  const messagesRef = useRef(initialMessages);
+
+  // Keep latest callbacks in refs so sendMessage identity stays stable regardless
+  // of whether the parent re-creates buildBody/getHeaders each render.
+  const buildBodyRef = useRef(buildBody);
+  const getHeadersRef = useRef(getHeaders);
+  buildBodyRef.current = buildBody;
+  getHeadersRef.current = getHeaders;
+
+  const addMessage = useCallback((msg) => {
+    setMessages((prev) => {
+      const next = [...prev, msg];
+      messagesRef.current = next;
+      return next;
+    });
+  }, []);
+
+  const sendMessage = useCallback(
+    async (userMessage, sendOptions = {}) => {
+      const history = messagesRef.current.slice();
+      addMessage({ role: 'user', content: userMessage });
+      setLoading(true);
+      setStatusText('');
+
+      try {
+        const response = await fetch(endpoint, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...getHeadersRef.current?.(),
+          },
+          body: JSON.stringify(buildBodyRef.current(userMessage, history, sendOptions)),
+        });
+
+        const contentType = response.headers.get('content-type') ?? '';
+
+        if (contentType.includes('text/event-stream')) {
+          const reader = response.body.getReader();
+          const decoder = new TextDecoder();
+          let buffer = '';
+
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+
+            for (const line of lines) {
+              if (!line.startsWith('data: ')) continue;
+              try {
+                const event = JSON.parse(line.slice(6));
+                if (event.type === 'status' && showStatus) {
+                  setStatusText(event.text);
+                } else if (event.type === 'done') {
+                  addMessage({
+                    role: 'assistant',
+                    content: event.response,
+                    truncated: event.truncated,
+                  });
+                } else if (event.type === 'error') {
+                  addMessage({
+                    role: 'assistant',
+                    content: event.error || 'Something went wrong.',
+                  });
+                }
+              } catch {
+                // ignore malformed SSE lines
+              }
+            }
+          }
+        } else {
+          // Plain JSON fallback for non-streaming backends
+          const data = await response.json();
+          if (response.ok) {
+            addMessage({ role: 'assistant', content: data.response, truncated: data.truncated });
+          } else {
+            addMessage({ role: 'assistant', content: data.error || 'Something went wrong.' });
+          }
+        }
+      } catch {
+        addMessage({
+          role: 'assistant',
+          content: 'Network error. Please check your connection and try again.',
+        });
+      } finally {
+        setLoading(false);
+        setStatusText('');
+      }
+    },
+    [endpoint, showStatus, addMessage]
+  );
+
+  const clearMessages = useCallback(() => {
+    setMessages([]);
+    messagesRef.current = [];
+  }, []);
+
+  return { messages, loading, statusText, sendMessage, clearMessages };
+}

package/src/index.d.ts

@@ -0,0 +1,139 @@
+import * as React from 'react';
+
+// ─── Chat UI ────────────────────────────────────────────────────────────────
+
+export interface ChatMessage {
+  role: 'user' | 'assistant';
+  content: string;
+  truncated?: boolean;
+}
+
+export interface ChatWindowProps {
+  messages: ChatMessage[];
+  loading?: boolean;
+  statusText?: string;
+  onSuggestionClick?: (text: string) => void;
+  aiEnabled?: boolean;
+  organisationName?: string;
+  /** Any extra props are forwarded to the root element */
+  [key: string]: unknown;
+}
+
+export interface ChatInputProps {
+  onSend: (text: string) => void;
+  disabled?: boolean;
+  disabledReason?: string;
+  onDisabledClick?: () => void;
+  [key: string]: unknown;
+}
+
+export interface MessageProps {
+  role: 'user' | 'assistant';
+  content: string;
+  truncated?: boolean;
+}
+
+export const ChatWindow: React.FC<ChatWindowProps>;
+export const ChatInput: React.FC<ChatInputProps>;
+export const Message: React.FC<MessageProps>;
+
+// ─── useOrchidAiChat ─────────────────────────────────────────────────────────
+
+/** Optional flags merged into the request by `buildBody` (e.g. web research for Hermes). */
+export interface OrchidAiChatSendOptions {
+  allowWebResearch?: boolean;
+  urlsToCheck?: string[];
+}
+
+export interface OrchidAiChatOptions {
+  /** POST endpoint that accepts the chat message */
+  endpoint: string;
+  /**
+   * Builds the request body from the user message, history, and per-send options.
+   * The third argument is only present when callers use `sendMessage(text, options)`.
+   */
+  buildBody: (
+    userMessage: string,
+    history: ChatMessage[],
+    sendOptions?: OrchidAiChatSendOptions
+  ) => Record<string, unknown>;
+  /** Returns extra request headers (e.g. CSRF token) */
+  getHeaders?: () => Record<string, string>;
+  /**
+   * Whether to display status messages during processing.
+   * Set to false to suppress all status text. Defaults to true.
+   */
+  showStatus?: boolean;
+  /** Initial transcript when mounting the hook */
+  initialMessages?: ChatMessage[];
+}
+
+export interface OrchidAiChatState {
+  messages: ChatMessage[];
+  loading: boolean;
+  /** Live status text emitted by the server (e.g. "Thinking", "Compiling response") */
+  statusText: string;
+  sendMessage: (userMessage: string, sendOptions?: OrchidAiChatSendOptions) => Promise<void>;
+  clearMessages: () => void;
+}
+
+export function useOrchidAiChat(options: OrchidAiChatOptions): OrchidAiChatState;
+
+/**
+ * Default status message strings used by the Orchid AI backend services.
+ * Import these in server-side code to keep client and server labels in sync,
+ * or to override individual values per app.
+ */
+export const ORCHID_AI_DEFAULT_STATUS: {
+  readonly thinking: string;
+  readonly compilingResponse: string;
+  readonly lookingUpData: string;
+};
+
+// ─── Visualizations ──────────────────────────────────────────────────────────
+
+export const AiVisualization: React.FC<{ data: unknown }>;
+export const BarChart: React.FC<{ data: unknown }>;
+export const LineChart: React.FC<{ data: unknown }>;
+export const DotChart: React.FC<{ data: unknown }>;
+export const ScatterPlot: React.FC<{ data: unknown }>;
+export const HistogramChart: React.FC<{ data: unknown }>;
+export const StackedBarChart: React.FC<{ data: unknown }>;
+export const GroupedBarChart: React.FC<{ data: unknown }>;
+export const DataTable: React.FC<{ data: unknown }>;
+export const StatCards: React.FC<{ data: unknown }>;
+export const Timeline: React.FC<{ data: unknown }>;
+
+// ─── Chart schema utilities ───────────────────────────────────────────────────
+
+export const CHART_BLOCK_LANGUAGE: string;
+export const LEGACY_CHART_BLOCK_LANGUAGE: string;
+export function isChartMarkdownLanguage(lang: string): boolean;
+
+export const DOT_CHART_TYPE: string;
+export const TABLE_TYPE: string;
+export const BAR_CHART_TYPE: string;
+export const STAT_CARDS_TYPE: string;
+export const TIMELINE_TYPE: string;
+export const LINE_CHART_TYPE: string;
+export const STACKED_BAR_CHART_TYPE: string;
+export const GROUPED_BAR_CHART_TYPE: string;
+export const HISTOGRAM_TYPE: string;
+export const SCATTER_PLOT_TYPE: string;
+
+export function validateBarChartPayload(data: unknown): boolean;
+export function validateLineChartPayload(data: unknown): boolean;
+export function validateStackedBarChartPayload(data: unknown): boolean;
+export function validateGroupedBarChartPayload(data: unknown): boolean;
+export function validateHistogramPayload(data: unknown): boolean;
+export function validateScatterPlotPayload(data: unknown): boolean;
+export function validateStatCardsPayload(data: unknown): boolean;
+export function validateTimelinePayload(data: unknown): boolean;
+export function validateTablePayload(data: unknown): boolean;
+
+export function parseChartBlock(block: string): unknown;
+export function resolveChartBlock(block: string): unknown;
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+export const ORCHID_AI_VISUALIZATION_INSTRUCTIONS: string;

package/src/index.js

@@ -1,5 +1,6 @@
 // Chat UI
 export { default as ChatWindow } from './components/ChatWindow';
+export { useOrchidAiChat, ORCHID_AI_DEFAULT_STATUS } from './hooks/useOrchidAiChat';
 export { default as ChatInput } from './components/ChatInput';
 export { default as Message } from './components/Message';