@gram-ai/elements 1.19.1 → 1.20.1

package/src/index.ts

@@ -3,10 +3,13 @@ import './global.css'
 
 // Context Providers
 export { ElementsProvider as GramElementsProvider } from './contexts/ElementsProvider'
+export { ElementsProvider } from './contexts/ElementsProvider'
 export { useElements as useGramElements } from './hooks/useElements'
+export { useElements } from './hooks/useElements'
 
 // Core Components
 export { Chat } from '@/components/Chat'
+export { ThreadList as ChatHistory } from '@/components/assistant-ui/thread-list'
 
 // Frontend Tools
 export { defineFrontendTool } from './lib/tools'
@@ -25,6 +28,7 @@ export type {
   Dimensions,
   ElementsConfig,
   GetSessionFn,
+  HistoryConfig,
   ModalConfig,
   ModalTriggerPosition,
   Model,

package/src/lib/messageConverter.ts

@@ -0,0 +1,241 @@
+/**
+ * Message format converter for Gram API <-> assistant-ui.
+ *
+ * The Gram API returns chat messages in its own schema (GramChatMessage),
+ * while assistant-ui expects messages in its internal ThreadMessage format.
+ * This module bridges that gap by converting between the two formats.
+ *
+ * Main export: `convertGramMessagesToExported` - converts an array of Gram
+ * messages into an ExportedMessageRepository with parent-child relationships
+ * for conversation threading.
+ */
+
+import type {
+  ExportedMessageRepository,
+  ThreadMessage,
+  ThreadUserMessagePart,
+  ThreadAssistantMessagePart,
+  TextMessagePart,
+} from '@assistant-ui/react'
+
+/**
+ * Represents a chat message from the Gram API.
+ * This mirrors the ChatMessage type from @gram/sdk without requiring the SDK dependency.
+ */
+export interface GramChatMessage {
+  id: string
+  role: string
+  content?: string
+  model: string
+  toolCallId?: string
+  toolCalls?: string
+  createdAt: Date | string
+}
+
+/**
+ * Represents a chat from the Gram API.
+ */
+export interface GramChat {
+  id: string
+  title: string
+  userId: string
+  numMessages: number
+  messages: GramChatMessage[]
+  createdAt: Date | string
+  updatedAt: Date | string
+}
+
+/**
+ * Represents a chat overview from the Gram API (without full messages).
+ */
+export interface GramChatOverview {
+  id: string
+  title: string
+  userId: string
+  numMessages: number
+  createdAt: Date | string
+  updatedAt: Date | string
+}
+
+/**
+ * Normalizes a role string to valid ThreadMessage roles.
+ */
+function normalizeRole(role: string): 'user' | 'assistant' | 'system' {
+  if (role === 'user') return 'user'
+  if (role === 'assistant') return 'assistant'
+  if (role === 'system') return 'system'
+  // Tool role messages should be handled differently, but for now treat as assistant
+  return 'assistant'
+}
+
+/**
+ * Parses a date that might be a string or Date object.
+ */
+function parseDate(date: Date | string): Date {
+  return typeof date === 'string' ? new Date(date) : date
+}
+
+/**
+ * Builds content parts for a user message.
+ */
+function buildUserContentParts(msg: GramChatMessage): ThreadUserMessagePart[] {
+  const parts: ThreadUserMessagePart[] = []
+
+  if (msg.content) {
+    parts.push({
+      type: 'text',
+      text: msg.content,
+    } as TextMessagePart)
+  }
+
+  // Return at least an empty text part if no content
+  if (parts.length === 0) {
+    parts.push({
+      type: 'text',
+      text: '',
+    } as TextMessagePart)
+  }
+
+  return parts
+}
+
+/**
+ * Builds content parts for an assistant message, including tool calls.
+ */
+function buildAssistantContentParts(
+  msg: GramChatMessage
+): ThreadAssistantMessagePart[] {
+  const parts: ThreadAssistantMessagePart[] = []
+
+  if (msg.content) {
+    parts.push({
+      type: 'text',
+      text: msg.content,
+    } as TextMessagePart)
+  }
+
+  if (msg.toolCalls) {
+    try {
+      const toolCalls = JSON.parse(msg.toolCalls)
+      for (const tc of toolCalls) {
+        const args = tc.function?.arguments ?? tc.args ?? {}
+        const argsText = typeof args === 'string' ? args : JSON.stringify(args)
+        parts.push({
+          type: 'tool-call',
+          toolCallId: tc.id ?? tc.toolCallId ?? '',
+          toolName: tc.function?.name ?? tc.toolName ?? '',
+          args: typeof args === 'string' ? JSON.parse(args) : args,
+          argsText,
+          result: undefined,
+        } as ThreadAssistantMessagePart)
+      }
+    } catch {
+      // Ignore JSON parse errors for tool calls
+    }
+  }
+
+  // Return at least an empty text part if no content
+  if (parts.length === 0) {
+    parts.push({
+      type: 'text',
+      text: '',
+    } as TextMessagePart)
+  }
+
+  return parts
+}
+
+/**
+ * Converts a single Gram ChatMessage to a ThreadMessage.
+ */
+function convertGramMessageToThreadMessage(
+  msg: GramChatMessage
+): ThreadMessage {
+  const role = normalizeRole(msg.role)
+  const createdAt = parseDate(msg.createdAt)
+
+  const baseMetadata = {
+    unstable_state: undefined,
+    unstable_annotations: undefined,
+    unstable_data: undefined,
+    steps: undefined,
+    submittedFeedback: undefined,
+    custom: {},
+  }
+
+  if (role === 'user') {
+    return {
+      id: msg.id,
+      role: 'user',
+      createdAt,
+      content: buildUserContentParts(msg),
+      attachments: [],
+      metadata: baseMetadata,
+    }
+  }
+
+  if (role === 'system') {
+    return {
+      id: msg.id,
+      role: 'system',
+      createdAt,
+      content: [{ type: 'text', text: msg.content ?? '' }],
+      metadata: baseMetadata,
+    }
+  }
+
+  // Assistant message
+  return {
+    id: msg.id,
+    role: 'assistant',
+    createdAt,
+    content: buildAssistantContentParts(msg),
+    status: { type: 'complete', reason: 'stop' },
+    metadata: {
+      unstable_state: null,
+      unstable_annotations: [],
+      unstable_data: [],
+      steps: [],
+      submittedFeedback: undefined,
+      custom: {},
+    },
+  }
+}
+
+/**
+ * Converts an array of Gram ChatMessages to an ExportedMessageRepository.
+ * Creates parent-child relationships based on message order.
+ *
+ * Note: System messages are filtered out because assistant-ui's
+ * `fromThreadMessageLike` doesn't support them in the exported format.
+ */
+export function convertGramMessagesToExported(
+  messages: GramChatMessage[]
+): ExportedMessageRepository {
+  if (messages.length === 0) {
+    return { messages: [], headId: null }
+  }
+
+  const exportedMessages: ExportedMessageRepository['messages'] = []
+  let prevId: string | null = null
+
+  for (const msg of messages) {
+    // Skip system messages - they're not supported in the exported message format
+    if (msg.role === 'system') {
+      continue
+    }
+
+    const threadMessage = convertGramMessageToThreadMessage(msg)
+    exportedMessages.push({
+      message: threadMessage,
+      parentId: prevId,
+      runConfig: undefined,
+    })
+    prevId = msg.id
+  }
+
+  return {
+    messages: exportedMessages,
+    headId: prevId,
+  }
+}

package/src/plugins/chart/component.tsx

@@ -3,18 +3,15 @@
 import { useDensity } from '@/hooks/useDensity'
 import { useRadius } from '@/hooks/useRadius'
 import { cn } from '@/lib/utils'
-import { useAssistantState } from '@assistant-ui/react'
 import { SyntaxHighlighterProps } from '@assistant-ui/react-markdown'
 import { AlertCircleIcon } from 'lucide-react'
 import { FC, useEffect, useMemo, useRef, useState } from 'react'
 import { parse, View, Warn } from 'vega'
 
 export const ChartRenderer: FC<SyntaxHighlighterProps> = ({ code }) => {
-  const message = useAssistantState(({ message }) => message)
   const containerRef = useRef<HTMLDivElement>(null)
   const viewRef = useRef<View | null>(null)
   const [error, setError] = useState<string | null>(null)
-  const messageIsComplete = message.status?.type === 'complete'
   const r = useRadius()
   const d = useDensity()
 
@@ -24,14 +21,25 @@ export const ChartRenderer: FC<SyntaxHighlighterProps> = ({ code }) => {
     if (!trimmedCode) return null
 
     try {
-      return JSON.parse(trimmedCode) as Record<string, unknown>
+      const spec = JSON.parse(trimmedCode) as Record<string, unknown>
+
+      // Validate that data array exists and has at least one record with values
+      const dataArray = spec.data as Array<{ values?: unknown[] }> | undefined
+      if (!dataArray?.length) return null
+
+      const hasValidData = dataArray.some(
+        (d) => Array.isArray(d.values) && d.values.length > 0
+      )
+      if (!hasValidData) return null
+
+      return spec
     } catch {
       return null
     }
   }, [code])
 
-  // Only render when we have valid JSON AND message is complete
-  const shouldRender = messageIsComplete && parsedSpec !== null
+  // Only render when we have valid JSON
+  const shouldRender = parsedSpec !== null
 
   useEffect(() => {
     if (!containerRef.current || !shouldRender) {
@@ -78,7 +86,7 @@ export const ChartRenderer: FC<SyntaxHighlighterProps> = ({ code }) => {
     <div
       className={cn(
         // the after:hidden is to prevent assistant-ui from showing its default code block loading indicator
-        'relative flex min-h-[400px] w-fit max-w-full min-w-[400px] items-center justify-center border p-6 after:hidden',
+        'relative min-h-[400px] w-fit max-w-full min-w-[400px] overflow-auto border p-6 after:hidden',
         r('lg'),
         d('p-lg')
       )}

package/src/plugins/chart/index.ts

@@ -21,7 +21,89 @@ CONTENT GUIDELINES:
 - Do not describe visual properties or technical implementation details
 - Do not mention "Vega" or other technical terms - this is user-facing
 
-The Vega spec will be parsed with JSON.parse() - if it fails, the chart will error. Ensure strict JSON validity.`,
+The Vega spec will be parsed with JSON.parse() - if it fails, the chart will error. Ensure strict JSON validity.
+
+REQUIRED STRUCTURE:
+Every spec needs: "$schema", "width", "height", "data", "scales", "marks". Include "padding" (5 or object) and "axes" for readability.
+Data format:
+{"name": "table", "values": [{"category": "A", "amount": 28}]}
+SCALES - Choose the right type:
+- "band": categorical x-axis (bar charts) - domain from data field, range: "width", padding: 0.1
+- "linear": numerical axes - domain from data field, range: "width"/"height", nice: true
+- "time"/"utc": temporal data
+- "ordinal": for colors use range: {"scheme": "category10"} or range: ["#1f77b4", "#ff7f0e", "#2ca02c"]
+MARKS - Common types:
+- "rect": bar charts (requires x, width, y, y2)
+- "line": time series (requires x, y)
+- "area": filled areas (requires x, y, y2)
+- "symbol": scatter plots (requires x, y)
+CHART PATTERNS:
+Bar: band scale (x) + linear scale (y) + rect marks. Set y2: {"scale": "yscale", "value": 0}
+Line: linear/point scale (x) + linear scale (y) + line mark. Add "interpolate": "monotone"
+Scatter: linear scales (both) + symbol marks
+Area: like line but use area mark with y2: {"scale": "yscale", "value": 0}
+Stacked: add transform [{"type": "stack", "groupby": ["x"], "field": "y"}], use y0/y1 fields
+CRITICAL RULES:
+1. Data must contain at least one record with valid (non-null) values for ALL fields used in scales
+2. ONLY reference fields that actually exist in your data - never use datum.meta, datum.id, or any field not in your values array
+3. Always include y2 for rect/area marks (or bars/areas have zero height)
+4. Use "band" for categories, not "linear"
+5. For position scales use "range": "width" or "height". For color scales NEVER use "range": "category10" - use "range": {"scheme": "category10"} or an array
+6. Match scale/data names exactly between definition and usage
+7. Include "from": {"data": "dataName"} on marks
+8. Add padding to prevent label cutoff
+EXAMPLE: COMPLETE BAR CHART
+{
+  "$schema": "https://vega.github.io/schema/vega/v5.json",
+  "width": 500,
+  "height": 300,
+  "padding": 5,
+  "data": [
+    {
+      "name": "table",
+      "values": [
+        {"category": "A", "amount": 28},
+        {"category": "B", "amount": 55},
+        {"category": "C", "amount": 43}
+      ]
+    }
+  ],
+  "scales": [
+    {
+      "name": "xscale",
+      "type": "band",
+      "domain": {"data": "table", "field": "category"},
+      "range": "width",
+      "padding": 0.1
+    },
+    {
+      "name": "yscale",
+      "type": "linear",
+      "domain": {"data": "table", "field": "amount"},
+      "range": "height",
+      "nice": true
+    }
+  ],
+  "axes": [
+    {"scale": "xscale", "orient": "bottom"},
+    {"scale": "yscale", "orient": "left", "title": "Amount"}
+  ],
+  "marks": [
+    {
+      "type": "rect",
+      "from": {"data": "table"},
+      "encode": {
+        "enter": {
+          "x": {"scale": "xscale", "field": "category"},
+          "width": {"scale": "xscale", "band": 1},
+          "y": {"scale": "yscale", "field": "amount"},
+          "y2": {"scale": "yscale", "value": 0},
+          "fill": {"value": "steelblue"}
+        }
+      }
+    }
+  ]
+}`,
   Component: ChartRenderer,
   Header: undefined,
 }

package/src/types/index.ts

@@ -261,6 +261,20 @@ export interface ElementsConfig {
    */
   tools?: ToolsConfig
 
+  /**
+   * Configuration for chat history and thread persistence.
+   * When enabled, conversations are saved and the thread list is shown.
+   *
+   * @example
+   * const config: ElementsConfig = {
+   *   history: {
+   *     enabled: true,
+   *     showThreadList: true,
+   *   },
+   * }
+   */
+  history?: HistoryConfig
+
   /**
    * The API configuration to use for the Elements library.
    *
@@ -736,6 +750,34 @@ export interface SidecarConfig extends ExpandableConfig {
   title?: string
 }
 
+/**
+ * Configuration for chat history persistence.
+ * When enabled, threads are persisted and can be restored from the thread list.
+ *
+ * @example
+ * const config: ElementsConfig = {
+ *   history: {
+ *     enabled: true,
+ *     showThreadList: true,
+ *   },
+ * }
+ */
+export interface HistoryConfig {
+  /**
+   * Whether to enable chat history persistence.
+   * When true, threads will be saved and can be loaded from the thread list.
+   * @default false
+   */
+  enabled: boolean
+
+  /**
+   * Whether to show the thread list sidebar/panel.
+   * Only applies when history is enabled.
+   * @default true when history.enabled is true
+   */
+  showThreadList?: boolean
+}
+
 /**
  * @internal
  */