@gram-ai/elements 1.20.1 → 1.21.1

package/src/global.css

@@ -1,6 +1,7 @@
-@import "tailwindcss";
-@import "tw-animate-css";
-@import "tw-shimmer";
+@import 'tw-animate-css';
+@import 'tw-shimmer';
+@layer theme, base, components, utilities;
+@import 'tailwindcss/theme.css' layer(theme);
 
 @custom-variant dark (&:is(.dark *));
 
@@ -42,7 +43,20 @@
   --color-sidebar-ring: var(--sidebar-ring);
 }
 
-:root {
+/* Scope ALL variables to .gram-elements instead of :root */
+.gram-elements {
+  /* Scoped preflight/base styles */
+  font-family:
+    ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
+    'Segoe UI Symbol', 'Noto Color Emoji';
+  font-feature-settings: normal;
+  font-variation-settings: normal;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  line-height: 1.5;
+  -webkit-tap-highlight-color: transparent;
+  tab-size: 4;
+
   /* Theme: Radius - set via data-radius attribute */
   --radius: 0.625rem;
   --background: oklch(1 0 0);
@@ -78,7 +92,9 @@
   --sidebar-ring: oklch(0.705 0.015 286.067);
 }
 
-.dark {
+/* Dark mode scoped to .gram-elements */
+.gram-elements.dark,
+.dark .gram-elements {
   --background: oklch(0.141 0.005 285.823);
   --foreground: oklch(0.985 0 0);
   --card: oklch(0.21 0.006 285.885);
@@ -113,24 +129,121 @@
 }
 
 @layer base {
-  * {
-    @apply border-border outline-ring/50;
-  }
-  body {
-    @apply bg-background text-foreground;
+  .gram-elements {
+    @tailwind utilities;
+
+    /* We can't use tailwind's preflight styles here because we need to scope them to .gram-elements so therefore we just include a version of them inline here */
+    *,
+    *::before,
+    *::after {
+      box-sizing: border-box;
+      border-width: 0;
+      border-style: solid;
+      @apply border-border outline-ring/50;
+    }
+
+    /* Reset margins and padding for common elements */
+    h1,
+    h2,
+    h3,
+    h4,
+    h5,
+    h6,
+    p,
+    blockquote,
+    pre,
+    ul,
+    ol,
+    figure {
+      margin: 0;
+      padding: 0;
+    }
+
+    /* List style reset */
+    ul,
+    ol {
+      list-style: none;
+    }
+
+    /* Image defaults */
+    img,
+    svg,
+    video,
+    canvas,
+    audio,
+    iframe,
+    embed,
+    object {
+      display: block;
+    }
+
+    img,
+    video {
+      max-width: 100%;
+      height: auto;
+    }
+
+    /* Button/input reset */
+    button,
+    input,
+    optgroup,
+    select,
+    textarea {
+      font-family: inherit;
+      font-feature-settings: inherit;
+      font-variation-settings: inherit;
+      font-size: 100%;
+      font-weight: inherit;
+      line-height: inherit;
+      letter-spacing: inherit;
+      color: inherit;
+      margin: 0;
+      padding: 0;
+    }
+
+    button,
+    select {
+      text-transform: none;
+    }
+
+    button,
+    input:where([type='button']),
+    input:where([type='reset']),
+    input:where([type='submit']) {
+      appearance: button;
+      -webkit-appearance: button;
+      background-color: transparent;
+      background-image: none;
+    }
+
+    a {
+      color: inherit;
+      text-decoration: inherit;
+    }
+
+    /* Table reset */
+    table {
+      text-indent: 0;
+      border-color: inherit;
+      border-collapse: collapse;
+    }
   }
 }
 
-/* Theme: Radius variants via data attribute */
-[data-radius='sharp'] {
+/* Theme: Radius variants via data attribute - scoped */
+.gram-elements[data-radius='sharp'],
+[data-radius='sharp'] .gram-elements {
   --radius: 0.25rem;
 }
-[data-radius='soft'] {
+.gram-elements[data-radius='soft'],
+[data-radius='soft'] .gram-elements {
   --radius: 0.625rem;
 }
-[data-radius='round'] {
+.gram-elements[data-radius='round'],
+[data-radius='round'] .gram-elements {
   --radius: 1rem;
 }
-[data-radius='pill'] {
+.gram-elements[data-radius='pill'],
+[data-radius='pill'] .gram-elements {
   --radius: 9999px;
-}
+}

package/src/hooks/useAuth.ts

@@ -1,7 +1,7 @@
-import { hasExplicitSessionAuth, isApiKeyAuth } from '@/lib/auth'
+import { hasExplicitSessionAuth, isStaticSessionAuth } from '@/lib/auth'
+import { useMemo } from 'react'
 import { ApiConfig } from '../types'
 import { useSession } from './useSession'
-import { useMemo } from 'react'
 
 export type Auth =
   | {
@@ -38,33 +38,23 @@ export const useAuth = ({
   projectSlug: string
 }): Auth => {
   const getSession = useMemo(() => {
-    if (isApiKeyAuth(auth)) {
-      return null
+    if (isStaticSessionAuth(auth)) {
+      return () => Promise.resolve(auth.sessionToken)
     }
-    return !isApiKeyAuth(auth) && hasExplicitSessionAuth(auth)
+    return !isStaticSessionAuth(auth) && hasExplicitSessionAuth(auth)
       ? auth.sessionFn
       : defaultGetSession
   }, [auth])
+
   // The session request is only neccessary if we are not using an API key auth
   // configuration. If a custom session fetcher is provided, we use it,
   // otherwise we fallback to the default session fetcher
   const session = useSession({
     // We want to check it's NOT API key auth, as the default auth scheme is session auth (if the user hasn't provided an explicit API config, we have a session auth config by default)
-    enabled: !isApiKeyAuth(auth),
     getSession,
     projectSlug,
   })
 
-  if (isApiKeyAuth(auth)) {
-    return {
-      headers: {
-        'Gram-Project': projectSlug,
-        'Gram-Key': auth.UNSAFE_apiKey,
-      },
-      isLoading: false,
-    }
-  }
-
   return !session
     ? {
         isLoading: true,

package/src/hooks/usePortalContainer.ts

@@ -0,0 +1,16 @@
+'use client'
+
+import { useContext } from 'react'
+import { PortalContainerContext } from '@/contexts/portal-container-context'
+
+/**
+ * Because we do not want Tailwind to leak from the Elements library, and
+ * because some UI elements such as Dialogs and Tooltips need to be rendered in
+ * a different container than the root element, we need to use a portal
+ * container, which renders any tooltips, dialogs etc within the .gram-elements
+ * scope so that they still inherit the Elements CSS
+ */
+export function usePortalContainer(): HTMLElement | null {
+  const ref = useContext(PortalContainerContext)
+  return ref?.current ?? null
+}

package/src/hooks/useSession.ts

@@ -8,11 +8,9 @@ import { useQuery, useQueryClient } from '@tanstack/react-query'
 export const useSession = ({
   getSession,
   projectSlug,
-  enabled,
 }: {
   getSession: GetSessionFn | null
   projectSlug: string
-  enabled: boolean
 }): string | null => {
   const queryClient = useQueryClient()
   const queryKey = ['chatSession', projectSlug]
@@ -29,7 +27,7 @@ export const useSession = ({
   const { data: fetchedSessionToken } = useQuery({
     queryKey,
     queryFn: () => getSession!({ projectSlug }),
-    enabled: enabled && shouldFetch && getSession !== null,
+    enabled: shouldFetch && getSession !== null,
     staleTime: Infinity, // Session tokens don't need to be refetched
     gcTime: Infinity, // Keep in cache indefinitely
   })

package/src/index.ts

@@ -15,6 +15,10 @@ export { ThreadList as ChatHistory } from '@/components/assistant-ui/thread-list
 export { defineFrontendTool } from './lib/tools'
 export type { FrontendTool } from './lib/tools'
 
+// Error Tracking
+export { trackError } from './lib/errorTracking'
+export type { ErrorContext } from './lib/errorTracking'
+
 // Types
 export type {
   AttachmentsConfig,
@@ -27,6 +31,7 @@ export type {
   Dimension,
   Dimensions,
   ElementsConfig,
+  ErrorTrackingConfigOption,
   GetSessionFn,
   HistoryConfig,
   ModalConfig,

package/src/lib/api.test.ts

@@ -1,5 +1,5 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
 import type { ElementsConfig } from '@/types'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 describe('getApiUrl', () => {
   beforeEach(() => {
@@ -16,7 +16,7 @@ describe('getApiUrl', () => {
     const getApiUrl = await loadGetApiUrl('https://env.example.com')
     const config: ElementsConfig = {
       projectSlug: 'test',
-      api: { url: 'https://config.example.com', UNSAFE_apiKey: 'test-key' },
+      api: { url: 'https://config.example.com', sessionToken: 'test-key' },
     }
 
     expect(getApiUrl(config)).toBe('https://config.example.com')
@@ -26,7 +26,7 @@ describe('getApiUrl', () => {
     const getApiUrl = await loadGetApiUrl('https://env.example.com')
     const config: ElementsConfig = {
       projectSlug: 'test',
-      api: { UNSAFE_apiKey: 'test-key' },
+      api: { sessionToken: 'test-key' },
     }
 
     expect(getApiUrl(config)).toBe('https://env.example.com')
@@ -63,7 +63,7 @@ describe('getApiUrl', () => {
     const getApiUrl = await loadGetApiUrl('https://env.example.com')
     const config: ElementsConfig = {
       projectSlug: 'test',
-      api: { url: '', UNSAFE_apiKey: 'test-key' },
+      api: { url: '', sessionToken: 'test-key' },
     }
 
     expect(getApiUrl(config)).toBe('https://env.example.com')
@@ -73,7 +73,7 @@ describe('getApiUrl', () => {
     const getApiUrl = await loadGetApiUrl('')
     const config: ElementsConfig = {
       projectSlug: 'test',
-      api: { url: 'https://config.example.com///', UNSAFE_apiKey: 'test-key' },
+      api: { url: 'https://config.example.com///', sessionToken: 'test-key' },
     }
 
     expect(getApiUrl(config)).toBe('https://config.example.com')

package/src/lib/auth.ts

@@ -1,12 +1,12 @@
-import { ApiKeyAuthConfig, ApiConfig, SessionAuthConfig } from '@/types'
+import { ApiConfig, SessionAuthConfig, StaticSessionAuthConfig } from '@/types'
 
 /**
  * Checks if the auth config is an API key auth config
  */
-export function isApiKeyAuth(
+export function isStaticSessionAuth(
   auth: ApiConfig | undefined
-): auth is ApiKeyAuthConfig {
-  return !!auth && 'UNSAFE_apiKey' in auth
+): auth is StaticSessionAuthConfig {
+  return !!auth && 'sessionToken' in auth
 }
 
 export function hasExplicitSessionAuth(

package/src/lib/errorTracking.config.ts

@@ -0,0 +1,16 @@
+/**
+ * Datadog RUM configuration for Gram Elements.
+ * Values are injected at build time via environment variables.
+ * These client tokens are designed to be client-side safe.
+ *
+ * Required env vars for build:
+ * - VITE_DATADOG_APPLICATION_ID
+ * - VITE_DATADOG_CLIENT_TOKEN
+ * - VITE_DATADOG_SITE (optional, defaults to datadoghq.com)
+ */
+export const DATADOG_CONFIG = {
+  applicationId: import.meta.env.VITE_DATADOG_APPLICATION_ID ?? '',
+  clientToken: import.meta.env.VITE_DATADOG_CLIENT_TOKEN ?? '',
+  site: import.meta.env.VITE_DATADOG_SITE ?? 'datadoghq.com',
+  service: 'gram-elements',
+} as const

package/src/lib/errorTracking.ts

@@ -0,0 +1,104 @@
+import { datadogRum } from '@datadog/browser-rum'
+import { DATADOG_CONFIG } from './errorTracking.config'
+
+let initialized = false
+let enabled = true
+
+export interface ErrorTrackingConfig {
+  enabled?: boolean
+  projectSlug?: string
+  variant?: string
+}
+
+export interface ErrorContext {
+  source: 'error-boundary' | 'streaming' | 'stream-creation' | 'custom'
+  componentStack?: string
+  [key: string]: unknown
+}
+
+/**
+ * Initialize Datadog RUM for error tracking.
+ * Should be called once when the ElementsProvider mounts.
+ */
+export function initErrorTracking(config: ErrorTrackingConfig = {}): void {
+  // Check if explicitly disabled
+  if (config.enabled === false) {
+    enabled = false
+    return
+  }
+
+  // Prevent double initialization
+  if (initialized) {
+    return
+  }
+
+  // Skip if credentials not configured (e.g., local dev without env vars)
+  if (!DATADOG_CONFIG.applicationId || !DATADOG_CONFIG.clientToken) {
+    enabled = false
+    return
+  }
+
+  try {
+    datadogRum.init({
+      applicationId: DATADOG_CONFIG.applicationId,
+      clientToken: DATADOG_CONFIG.clientToken,
+      site: DATADOG_CONFIG.site,
+      service: DATADOG_CONFIG.service,
+      env: process.env.NODE_ENV || 'production',
+      sessionSampleRate: 100,
+      sessionReplaySampleRate: 100,
+      trackUserInteractions: true,
+      trackResources: true,
+      trackLongTasks: true,
+
+      // Note: we need to mask everything, not just user input, as sensitive data may be echo-ed
+      // back in the LLM messages or the user messages in the chat window
+      defaultPrivacyLevel: 'mask',
+    })
+
+    // Set global context
+    if (config.projectSlug) {
+      datadogRum.setGlobalContextProperty('projectSlug', config.projectSlug)
+    }
+    if (config.variant) {
+      datadogRum.setGlobalContextProperty('variant', config.variant)
+    }
+
+    initialized = true
+  } catch (error) {
+    console.warn('[Elements] Failed to initialize Datadog RUM:', error)
+    enabled = false
+  }
+}
+
+/**
+ * Track an error to Datadog RUM.
+ * Includes context about where the error originated.
+ */
+export function trackError(
+  error: Error | unknown,
+  context: ErrorContext
+): void {
+  if (!enabled || !initialized) {
+    return
+  }
+
+  const errorObj = error instanceof Error ? error : new Error(String(error))
+
+  try {
+    datadogRum.addError(errorObj, {
+      ...context,
+      timestamp: new Date().toISOString(),
+    })
+  } catch (e) {
+    // Silently fail - we don't want error tracking to cause more errors
+    console.warn('[Elements] Failed to track error:', e)
+  }
+}
+
+/**
+ * Check if error tracking is currently enabled.
+ */
+export function isErrorTrackingEnabled(): boolean {
+  return enabled && initialized
+}

package/src/lib/tools.ts

@@ -6,6 +6,7 @@ import {
 } from '@assistant-ui/react'
 import z from 'zod'
 import { FC } from 'react'
+import type { ToolsRequiringApproval } from '@/types'
 
 /**
  * Converts from assistant-ui tool format to the AI SDK tool shape
@@ -50,7 +51,7 @@ export type FrontendTool<TArgs extends Record<string, unknown>, TResult> = FC<
  */
 let approvalConfig: {
   helpers: ApprovalHelpers
-  toolsRequiringApproval: Set<string>
+  requiresApproval: (toolName: string) => boolean
 } | null = null
 
 /**
@@ -58,11 +59,12 @@ let approvalConfig: {
  */
 export function setFrontendToolApprovalConfig(
   helpers: ApprovalHelpers,
-  toolsRequiringApproval: string[]
+  toolsRequiringApproval: ToolsRequiringApproval
 ): void {
+  const requiresApproval = createRequiresApprovalFn(toolsRequiringApproval)
   approvalConfig = {
     helpers,
-    toolsRequiringApproval: new Set(toolsRequiringApproval),
+    requiresApproval,
   }
 }
 
@@ -73,6 +75,25 @@ export function clearFrontendToolApprovalConfig(): void {
   approvalConfig = null
 }
 
+/**
+ * Creates a function that checks if a tool requires approval.
+ * Handles both array and function-based configurations.
+ */
+function createRequiresApprovalFn(
+  toolsRequiringApproval: ToolsRequiringApproval | undefined
+): (toolName: string) => boolean {
+  if (!toolsRequiringApproval) {
+    return () => false
+  }
+
+  if (typeof toolsRequiringApproval === 'function') {
+    return (toolName: string) => toolsRequiringApproval({ toolName })
+  }
+
+  const approvalSet = new Set(toolsRequiringApproval)
+  return (toolName: string) => approvalSet.has(toolName)
+}
+
 /**
  * Make a frontend tool
  */
@@ -90,7 +111,7 @@ export const defineFrontendTool = <
     ...tool,
     execute: async (args: TArgs, context: ToolExecutionContext) => {
       // Check if this tool requires approval at runtime
-      if (approvalConfig?.toolsRequiringApproval.has(name)) {
+      if (approvalConfig?.requiresApproval(name)) {
         const { helpers } = approvalConfig
         const toolCallId = context.toolCallId ?? ''
 
@@ -136,18 +157,26 @@ export interface ApprovalHelpers {
  */
 export function wrapToolsWithApproval(
   tools: ToolSet,
-  toolsRequiringApproval: string[] | undefined,
+  toolsRequiringApproval: ToolsRequiringApproval | undefined,
   approvalHelpers: ApprovalHelpers
 ): ToolSet {
-  if (!toolsRequiringApproval || toolsRequiringApproval.length === 0) {
+  if (!toolsRequiringApproval) {
     return tools
   }
 
-  const approvalSet = new Set(toolsRequiringApproval)
+  // Handle empty array case
+  if (
+    Array.isArray(toolsRequiringApproval) &&
+    toolsRequiringApproval.length === 0
+  ) {
+    return tools
+  }
+
+  const requiresApproval = createRequiresApprovalFn(toolsRequiringApproval)
 
   return Object.fromEntries(
     Object.entries(tools).map(([name, tool]) => {
-      if (!approvalSet.has(name)) {
+      if (!requiresApproval(name)) {
         return [name, tool]
       }
 

package/src/types/index.ts

@@ -288,6 +288,30 @@ export interface ElementsConfig {
    * }
    */
   api?: ApiConfig
+
+  /**
+   * Error tracking configuration.
+   * By default, errors are reported to help improve the Elements library.
+   *
+   * @example
+   * const config: ElementsConfig = {
+   *   errorTracking: {
+   *     enabled: false, // Opt out of error reporting
+   *   },
+   * }
+   */
+  errorTracking?: ErrorTrackingConfigOption
+}
+
+/**
+ * Configuration for error tracking.
+ */
+export interface ErrorTrackingConfigOption {
+  /**
+   * Set to false to disable error reporting.
+   * @default true
+   */
+  enabled?: boolean
 }
 
 /**
@@ -325,32 +349,27 @@ export type SessionAuthConfig = {
 }
 
 /**
- * The API key auth config is used to authenticate the Elements library using an API key only.
- *
- * NOTE: This is not recommended for production use, and a warning
- * will be displayed in the chat interface if you use this config.
- * Define a session endpoint instead to avoid this warning.
+ * The static session auth config is used to authenticate the Elements library using a static session token only.
  *
  * @example
  * const config: ElementsConfig = {
  *   api: {
- *     UNSAFE_apiKey: 'your-api-key',
+ *     sessionToken: 'your-session-token',
  *   },
  * }
  */
-export type ApiKeyAuthConfig = {
+export type StaticSessionAuthConfig = {
   /**
-   * The API key to use if you haven't yet configured a session endpoint.
-   * Do not use this in production.
+   * A static session token to use if you haven't yet configured a session endpoint.
    *
    * @example
    * const config: ElementsConfig = {
    *   api: {
-   *     UNSAFE_apiKey: 'your-api-key',
+   *     sessionToken: 'your-session-token',
    *   },
    * }
    */
-  UNSAFE_apiKey: string
+  sessionToken: string
 }
 
 /**
@@ -359,7 +378,7 @@ export type ApiKeyAuthConfig = {
 export type ApiConfig =
   | BaseApiConfig
   | (BaseApiConfig & SessionAuthConfig)
-  | (BaseApiConfig & ApiKeyAuthConfig)
+  | (BaseApiConfig & StaticSessionAuthConfig)
 
 /**
  * The LLM model to use for the Elements library.
@@ -490,6 +509,10 @@ export interface ComponentOverrides {
   >
 }
 
+export type ToolsRequiringApproval =
+  | string[]
+  | (({ toolName }: { toolName: string }) => boolean)
+
 /**
  * ToolsConfig is used to configure tool support in the Elements library.
  * At the moment, you can override the default React components used by
@@ -504,7 +527,6 @@ export interface ComponentOverrides {
  *   },
  * }
  */
-
 export interface ToolsConfig {
   /**
    * Whether individual tool calls within a group should be expanded by default.
@@ -584,17 +606,27 @@ export interface ToolsConfig {
 
   /**
    * List of tool names that require confirmation from the end user before
-   * being executed. The user can choose to approve once or approve for the
+   * being executed. A function can also be provided to dynamically determine if a tool requires approval.
+   * The user can choose to approve once or approve for the
    * entire session via the UI.
    *
-   * @example
+   * @example Using an array of tool names
    * ```ts
    * tools: {
    *   toolsRequiringApproval: ['delete_file', 'send_email'],
    * }
    * ```
+   *
+   * @example Using a function to dynamically determine if a tool requires approval
+   * ```ts
+   * tools: {
+   *   toolsRequiringApproval: (toolName) => {
+   *     return toolName.startsWith('protected_')
+   *   },
+   * }
+   * ```
    */
-  toolsRequiringApproval?: string[]
+  toolsRequiringApproval?: ToolsRequiringApproval
 }
 
 export interface WelcomeConfig {