@gram-ai/elements 1.20.1 → 1.21.1

package/src/components/Chat/stories/FrontendTools.stories.tsx

@@ -11,13 +11,6 @@ const meta: Meta<typeof Chat> = {
   parameters: {
     layout: 'fullscreen',
   },
-  decorators: [
-    (Story) => (
-      <div className="m-auto flex h-screen w-full max-w-3xl flex-col">
-        <Story />
-      </div>
-    ),
-  ],
 } satisfies Meta<typeof Chat>
 
 export default meta

package/src/components/Chat/stories/Model.stories.tsx

@@ -8,13 +8,6 @@ const meta: Meta<typeof Chat> = {
   parameters: {
     layout: 'fullscreen',
   },
-  decorators: [
-    (Story) => (
-      <div className="m-auto flex h-screen w-full max-w-3xl flex-col">
-        <Story />
-      </div>
-    ),
-  ],
 } satisfies Meta<typeof Chat>
 
 export default meta

package/src/components/Chat/stories/Plugins.stories.tsx

@@ -8,13 +8,6 @@ const meta: Meta<typeof Chat> = {
   parameters: {
     layout: 'fullscreen',
   },
-  decorators: [
-    (Story) => (
-      <div className="m-auto flex h-screen w-full max-w-3xl flex-col">
-        <Story />
-      </div>
-    ),
-  ],
 } satisfies Meta<typeof Chat>
 
 export default meta

package/src/components/Chat/stories/Radius.stories.tsx

@@ -8,13 +8,6 @@ const meta: Meta<typeof Chat> = {
   parameters: {
     layout: 'fullscreen',
   },
-  decorators: [
-    (Story) => (
-      <div className="m-auto flex h-screen w-full max-w-3xl flex-col">
-        <Story />
-      </div>
-    ),
-  ],
 } satisfies Meta<typeof Chat>
 
 export default meta

package/src/components/Chat/stories/ToolApproval.stories.tsx

@@ -10,13 +10,6 @@ const meta: Meta<typeof Chat> = {
   parameters: {
     layout: 'fullscreen',
   },
-  decorators: [
-    (Story) => (
-      <div className="m-auto flex h-screen w-full max-w-3xl flex-col">
-        <Story />
-      </div>
-    ),
-  ],
 } satisfies Meta<typeof Chat>
 
 export default meta
@@ -44,6 +37,30 @@ SingleTool.parameters = {
   },
 }
 
+export const SingleToolWithFunction: Story = () => <Chat />
+SingleToolWithFunction.storyName =
+  'Single Tool Requiring Approval with Function'
+SingleToolWithFunction.parameters = {
+  elements: {
+    config: {
+      variant: 'standalone',
+      tools: {
+        toolsRequiringApproval: ({ toolName }: { toolName: string }) =>
+          toolName.endsWith('salutation'),
+      },
+      welcome: {
+        suggestions: [
+          {
+            title: 'Call a tool requiring approval',
+            label: 'Get a salutation',
+            action: 'Get a salutation',
+          },
+        ],
+      },
+    },
+  },
+}
+
 export const MultipleGroupedTools: Story = () => <Chat />
 MultipleGroupedTools.storyName = 'Multiple Grouped Tools'
 MultipleGroupedTools.parameters = {
@@ -108,3 +125,30 @@ FrontendTool.parameters = {
     },
   },
 }
+
+export const FrontendToolWithFunction: Story = () => <Chat />
+FrontendToolWithFunction.storyName =
+  'Frontend Tool Requiring Approval with Function'
+FrontendToolWithFunction.parameters = {
+  elements: {
+    config: {
+      variant: 'standalone',
+      tools: {
+        frontendTools: {
+          deleteFile,
+        },
+        toolsRequiringApproval: ({ toolName }: { toolName: string }) =>
+          toolName.startsWith('delete'),
+      },
+      welcome: {
+        suggestions: [
+          {
+            title: 'Delete a file',
+            label: 'Delete a file',
+            action: 'Delete file with ID 123',
+          },
+        ],
+      },
+    },
+  },
+}

package/src/components/Chat/stories/Tools.stories.tsx

@@ -9,13 +9,6 @@ const meta: Meta<typeof Chat> = {
   parameters: {
     layout: 'fullscreen',
   },
-  decorators: [
-    (Story) => (
-      <div className="m-auto flex h-screen w-full max-w-3xl flex-col">
-        <Story />
-      </div>
-    ),
-  ],
 } satisfies Meta<typeof Chat>
 
 export default meta

package/src/components/Chat/stories/Variants.stories.tsx

@@ -1,6 +1,7 @@
 import { Chat } from '..'
 import type { Meta, StoryFn, StoryObj } from '@storybook/react-vite'
 import { ThreadList } from '@/components/assistant-ui/thread-list'
+import { ROOT_SELECTOR } from '@/constants/tailwind'
 
 const meta: Meta<typeof Chat> = {
   title: 'Chat/Variants',
@@ -46,8 +47,10 @@ export const StandaloneWithHistory: StoryObj<typeof Chat> = {
 }
 StandaloneWithHistory.decorators = [
   (Story) => (
-    <div className="m-auto flex h-screen w-full items-center justify-center border bg-linear-to-r from-violet-600 to-indigo-800">
-      <Story />
+    <div className={ROOT_SELECTOR}>
+      <div className="m-auto flex h-screen w-full items-center justify-center border bg-linear-to-r from-violet-600 to-indigo-800">
+        <Story />
+      </div>
     </div>
   ),
 ]

package/src/components/Chat/stories/Welcome.stories.tsx

@@ -1,4 +1,3 @@
-import React from 'react'
 import { Chat } from '..'
 import type { Meta, StoryFn } from '@storybook/react-vite'
 
@@ -8,13 +7,6 @@ const meta: Meta<typeof Chat> = {
   parameters: {
     layout: 'fullscreen',
   },
-  decorators: [
-    (Story) => (
-      <div className="m-auto flex h-screen w-full max-w-3xl flex-col">
-        <Story />
-      </div>
-    ),
-  ],
 } satisfies Meta<typeof Chat>
 
 export default meta

package/src/components/assistant-ui/assistant-modal.tsx

@@ -11,6 +11,7 @@ import {
 import { LazyMotion, domMax, AnimatePresence, MotionConfig } from 'motion/react'
 import * as m from 'motion/react-m'
 
+import { ErrorBoundary } from '@/components/assistant-ui/error-boundary'
 import { Thread } from '@/components/assistant-ui/thread'
 import { ThreadList } from '@/components/assistant-ui/thread-list'
 import { useThemeProps } from '@/hooks/useThemeProps'
@@ -240,7 +241,9 @@ export const AssistantModal: FC<AssistantModalProps> = ({ className }) => {
 
                   {/* Thread content */}
                   <div className="aui-modal-thread w-full flex-1 overflow-hidden">
-                    <Thread />
+                    <ErrorBoundary>
+                      <Thread />
+                    </ErrorBoundary>
                   </div>
                 </m.div>
               </m.div>

package/src/components/assistant-ui/assistant-sidecar.tsx

@@ -2,6 +2,7 @@
 
 import { type FC } from 'react'
 import { Loader, PanelRightClose, PanelRightOpen } from 'lucide-react'
+import { ErrorBoundary } from '@/components/assistant-ui/error-boundary'
 import { Thread } from '@/components/assistant-ui/thread'
 import { ThreadList } from '@/components/assistant-ui/thread-list'
 import { TooltipIconButton } from '@/components/assistant-ui/tooltip-icon-button'
@@ -36,10 +37,7 @@ export const AssistantSidecar: FC<AssistantSidecarProps> = ({ className }) => {
   return (
     <LazyMotion features={domMax}>
       <m.div
-        initial={{
-          width: dimensions?.default?.width ?? '400px',
-          height: dimensions?.default?.height ?? '100vh',
-        }}
+        initial={false}
         animate={{
           width: isExpanded
             ? (dimensions?.expanded?.width ?? '800px')
@@ -99,7 +97,9 @@ export const AssistantSidecar: FC<AssistantSidecarProps> = ({ className }) => {
 
           {/* Thread content */}
           <div className="aui-sidecar-content flex-1 overflow-hidden">
-            <Thread />
+            <ErrorBoundary>
+              <Thread />
+            </ErrorBoundary>
           </div>
         </div>
       </m.div>

package/src/components/assistant-ui/attachment.tsx

@@ -87,10 +87,7 @@ const AttachmentPreviewDialog: FC<PropsWithChildren> = ({ children }) => {
 
   return (
     <Dialog>
-      <DialogTrigger
-        className="aui-attachment-preview-trigger hover:bg-accent/50 cursor-pointer transition-colors"
-        asChild
-      >
+      <DialogTrigger className="aui-attachment-preview-trigger" asChild>
         {children}
       </DialogTrigger>
       <DialogContent className="aui-attachment-preview-dialog-content [&_svg]:text-background [&>button]:bg-foreground/60 [&>button]:hover:[&_svg]:text-destructive p-2 sm:max-w-3xl [&>button]:rounded-full [&>button]:p-1 [&>button]:opacity-100 [&>button]:!ring-0">

package/src/components/assistant-ui/error-boundary.tsx

@@ -0,0 +1,119 @@
+'use client'
+
+import { AlertCircle } from 'lucide-react'
+import { Component, type ErrorInfo, type ReactNode } from 'react'
+import { trackError } from '@/lib/errorTracking'
+import { cn } from '@/lib/utils'
+import { Button } from '../ui/button'
+
+interface ErrorBoundaryProps {
+  children: ReactNode
+  fallback?: ReactNode
+  onError?: (error: Error, errorInfo: ErrorInfo) => void
+  onReset?: () => void
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean
+  error: Error | null
+  resetKey: number
+}
+
+interface ErrorFallbackProps {
+  error: Error | null
+  onRetry: () => void
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+const ErrorFallback = ({ error, onRetry }: ErrorFallbackProps) => {
+  return (
+    <div
+      className={cn(
+        'aui-root aui-error-boundary bg-background flex h-full w-full flex-col items-center justify-center p-6'
+      )}
+    >
+      <div className="flex flex-col items-center gap-4 text-center">
+        <div className="text-destructive">
+          <AlertCircle className="size-12 stroke-[1.5px]" />
+        </div>
+        <div className="flex flex-col gap-2">
+          <h3 className="text-foreground text-xl font-semibold">
+            Something went wrong
+          </h3>
+          <p className="text-muted-foreground text-base">
+            An error occurred while loading the chat.
+          </p>
+          {error && (
+            <p className="text-muted-foreground/60 max-w-md truncate text-sm">
+              {error.message}
+            </p>
+          )}
+        </div>
+        <Button onClick={onRetry} variant="default" className="mt-2">
+          Try again
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+const Remounter = ({ children }: { children: ReactNode }) => <>{children}</>
+
+/**
+ * Global error boundary for the Elements library. Catches unexpected errors and renders a fallback UI.
+ * We wrap the assistant-modal, assistant-sidecar, and chat components with this error boundary.
+ * Each variant needs to have the error boundary rendered at the appropriate level e.g if using
+ * the widget variant, then the error screen must be rendered within the widget modal.
+ * TODO: We should add more granular error boundaries (e.g wrapping AssistantMessage, ThreadWelcome, etc.)
+ * TODO: We should also wrap ChatHistory, which may yield its own errors.
+ */
+export class ErrorBoundary extends Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props)
+    this.state = { hasError: false, error: null, resetKey: 0 }
+  }
+
+  static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState> {
+    return { hasError: true, error }
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
+    // Track error to Datadog RUM
+    trackError(error, {
+      source: 'error-boundary',
+      componentStack: errorInfo.componentStack ?? undefined,
+    })
+    this.props.onError?.(error, errorInfo)
+  }
+
+  handleRetry = () => {
+    // Increment resetKey to force remount of children, reinitializing the chat
+    this.setState((state) => ({
+      hasError: false,
+      error: null,
+      resetKey: state.resetKey + 1,
+    }))
+    this.props.onReset?.()
+  }
+
+  render(): ReactNode {
+    if (this.state.hasError) {
+      if (this.props.fallback) {
+        return this.props.fallback
+      }
+
+      return (
+        <ErrorFallback error={this.state.error} onRetry={this.handleRetry} />
+      )
+    }
+
+    // Use Remounter with key to force unmount/remount of children when retry is clicked
+    return (
+      <Remounter key={this.state.resetKey}>{this.props.children}</Remounter>
+    )
+  }
+}

package/src/components/assistant-ui/thread-list.tsx

@@ -11,6 +11,7 @@ import { Skeleton } from '@/components/ui/skeleton'
 import { useRadius } from '@/hooks/useRadius'
 import { cn } from '@/lib/utils'
 import { useDensity } from '@/hooks/useDensity'
+import { ROOT_SELECTOR } from '@/constants/tailwind'
 
 interface ThreadListProps {
   className?: string
@@ -23,7 +24,8 @@ export const ThreadList: FC<ThreadListProps> = ({ className }) => {
       className={cn(
         'aui-root aui-thread-list-root bg-background flex flex-col items-stretch',
         d('gap-sm'),
-        className
+        className,
+        ROOT_SELECTOR
       )}
     >
       <div

package/src/components/assistant-ui/thread.tsx

@@ -52,19 +52,18 @@ import {
 } from '../ui/tooltip'
 import { ToolGroup } from './tool-group'
 
-const ApiKeyWarning = () => (
+const StaticSessionWarning = () => (
   <div className="m-2 rounded-md border border-amber-500 bg-amber-100 px-4 py-3 text-sm text-amber-800 dark:border-amber-600 dark:bg-amber-900/30 dark:text-amber-200">
-    <strong>Warning:</strong> You are using an API key directly in the client.
-    Please{' '}
+    <strong>Warning:</strong> You are using a static session token in the
+    client. It will expire shortly. Please{' '}
     <a
       href="https://github.com/speakeasy-api/gram/tree/main/elements#setting-up-your-backend"
       target="_blank"
       rel="noopener noreferrer"
       className="text-amber-700 underline hover:text-amber-800 dark:text-amber-300 dark:hover:text-amber-200"
     >
-      set up a session endpoint
-    </a>{' '}
-    before deploying to production.
+      set up a session endpoint to avoid this warning.
+    </a>
   </div>
 )
 
@@ -77,7 +76,7 @@ export const Thread: FC<ThreadProps> = ({ className }) => {
   const d = useDensity()
   const { config } = useElements()
   const components = config.components ?? {}
-  const showApiKeyWarning = config.api && 'UNSAFE_apiKey' in config.api
+  const showStaticSessionWarning = config.api && 'sessionToken' in config.api
 
   return (
     <LazyMotion features={domAnimation}>
@@ -103,7 +102,7 @@ export const Thread: FC<ThreadProps> = ({ className }) => {
               )}
             </ThreadPrimitive.If>
 
-            {showApiKeyWarning && <ApiKeyWarning />}
+            {showStaticSessionWarning && <StaticSessionWarning />}
 
             <ThreadPrimitive.Messages
               components={{

package/src/components/ui/dialog.tsx

@@ -3,6 +3,7 @@ import * as DialogPrimitive from '@radix-ui/react-dialog'
 import { XIcon } from 'lucide-react'
 
 import { cn } from '@/lib/utils'
+import { usePortalContainer } from '@/hooks/usePortalContainer'
 
 function Dialog({
   ...props
@@ -17,9 +18,17 @@ function DialogTrigger({
 }
 
 function DialogPortal({
+  container,
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Portal>) {
-  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />
+  const portalContainer = usePortalContainer()
+  return (
+    <DialogPrimitive.Portal
+      data-slot="dialog-portal"
+      container={container ?? portalContainer}
+      {...props}
+    />
+  )
 }
 
 function DialogClose({

package/src/components/ui/popover.tsx

@@ -22,18 +22,16 @@ function PopoverContent({
   ...props
 }: React.ComponentProps<typeof PopoverPrimitive.Content>) {
   return (
-    <PopoverPrimitive.Portal>
-      <PopoverPrimitive.Content
-        data-slot="popover-content"
-        align={align}
-        sideOffset={sideOffset}
-        className={cn(
-          'bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-20 w-72 origin-(--radix-popover-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden',
-          className
-        )}
-        {...props}
-      />
-    </PopoverPrimitive.Portal>
+    <PopoverPrimitive.Content
+      data-slot="popover-content"
+      align={align}
+      sideOffset={sideOffset}
+      className={cn(
+        'bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-20 w-72 origin-(--radix-popover-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden',
+        className
+      )}
+      {...props}
+    />
   )
 }
 

package/src/components/ui/tooltip.tsx

@@ -4,6 +4,7 @@ import * as React from 'react'
 import * as TooltipPrimitive from '@radix-ui/react-tooltip'
 
 import { cn } from '@/lib/utils'
+import { usePortalContainer } from '@/hooks/usePortalContainer'
 
 function TooltipProvider({
   delayDuration = 0,
@@ -38,10 +39,14 @@ function TooltipContent({
   className,
   sideOffset = 0,
   children,
+  container,
   ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+}: React.ComponentProps<typeof TooltipPrimitive.Content> & {
+  container?: HTMLElement | null
+}) {
+  const portalContainer = usePortalContainer()
   return (
-    <TooltipPrimitive.Portal>
+    <TooltipPrimitive.Portal container={container ?? portalContainer}>
       <TooltipPrimitive.Content
         data-slot="tooltip-content"
         sideOffset={sideOffset}

package/src/constants/tailwind.ts

@@ -0,0 +1,2 @@
+// Used to scope elements styles to the Elements library
+export const ROOT_SELECTOR = 'gram-elements'

package/src/contexts/ElementsProvider.tsx

@@ -2,6 +2,7 @@ import { FrontendTools } from '@/components/FrontendTools'
 import { useMCPTools } from '@/hooks/useMCPTools'
 import { useToolApproval } from '@/hooks/useToolApproval'
 import { getApiUrl } from '@/lib/api'
+import { initErrorTracking, trackError } from '@/lib/errorTracking'
 import { MODELS } from '@/lib/models'
 import {
   clearFrontendToolApprovalConfig,
@@ -125,6 +126,15 @@ const ElementsProviderWithApproval = ({
     plugins
   )
 
+  // Initialize error tracking on mount
+  useEffect(() => {
+    initErrorTracking({
+      enabled: config.errorTracking?.enabled,
+      projectSlug: config.projectSlug,
+      variant: config.variant,
+    })
+  }, [])
+
   const { data: mcpTools } = useMCPTools({
     auth,
     mcp: config.mcp,
@@ -157,7 +167,7 @@ const ElementsProviderWithApproval = ({
 
   // Set up frontend tool approval config for runtime checking
   useEffect(() => {
-    if (config.tools?.toolsRequiringApproval?.length) {
+    if (config.tools?.toolsRequiringApproval) {
       setFrontendToolApprovalConfig(
         getApprovalHelpers(),
         config.tools.toolsRequiringApproval
@@ -173,6 +183,10 @@ const ElementsProviderWithApproval = ({
   // but runtime is created using transport. The ref gets populated after runtime creation.
   const runtimeRef = useRef<ReturnType<typeof useChatRuntime> | null>(null)
 
+  // Generate a stable chat ID for server-side persistence (when history is disabled)
+  // When history is enabled, the thread adapter manages chat IDs instead
+  const chatIdRef = useRef<string | null>(null)
+
   // Create chat transport configuration
   const transport = useMemo<ChatTransport<UIMessage>>(
     () => ({
@@ -183,18 +197,29 @@ const ElementsProviderWithApproval = ({
           throw new Error('Session is loading')
         }
 
+        // Generate chat ID on first message if not already set
+        if (!chatIdRef.current) {
+          chatIdRef.current = crypto.randomUUID()
+        }
+
         const context = runtimeRef.current?.thread.getModelContext()
         const frontendTools = toAISDKTools(
           getEnabledTools(context?.tools ?? {})
         )
 
+        // Include Gram-Chat-ID header for chat persistence
+        const headersWithChatId = {
+          ...auth.headers,
+          'Gram-Chat-ID': chatIdRef.current,
+        }
+
         // Create OpenRouter model (only needed when not using custom model)
         const openRouterModel = usingCustomModel
           ? null
           : createOpenRouter({
               baseURL: apiUrl,
               apiKey: 'unused, but must be set',
-              headers: auth.headers,
+              headers: headersWithChatId,
             })
 
         if (config.languageModel) {
@@ -234,12 +259,14 @@ const ElementsProviderWithApproval = ({
             abortSignal,
             onError: ({ error }) => {
               console.error('Stream error in onError callback:', error)
+              trackError(error, { source: 'streaming' })
             },
           })
 
           return result.toUIMessageStream()
         } catch (error) {
           console.error('Error creating stream:', error)
+          trackError(error, { source: 'stream-creation' })
           throw error
         }
       },

package/src/contexts/portal-container-context.ts

@@ -0,0 +1,4 @@
+import { createContext, type RefObject } from 'react'
+
+export const PortalContainerContext =
+  createContext<RefObject<HTMLElement | null> | null>(null)

package/src/contexts/portal-container.tsx

@@ -0,0 +1,20 @@
+'use client'
+
+import { type RefObject } from 'react'
+import { PortalContainerContext } from './portal-container-context'
+
+export { PortalContainerContext }
+
+export function PortalContainerProvider({
+  containerRef,
+  children,
+}: {
+  containerRef: RefObject<HTMLElement | null>
+  children: React.ReactNode
+}) {
+  return (
+    <PortalContainerContext.Provider value={containerRef}>
+      {children}
+    </PortalContainerContext.Provider>
+  )
+}