@gram-ai/elements 1.18.4 → 1.18.6

package/src/hooks/useDensity.ts

@@ -0,0 +1,110 @@
+import { useElements } from './useElements'
+
+/**
+ * Density class mappings for different UI elements
+ */
+const densityClasses = {
+  compact: {
+    // Padding - small increments (1, 1.5, 2, 2.5, 3)
+    'p-xs': 'p-1',
+    'p-sm': 'p-1.5',
+    'p-md': 'p-2',
+    'p-lg': 'p-2.5',
+    'p-xl': 'p-3',
+    'px-xs': 'px-1',
+    'px-sm': 'px-1.5',
+    'px-md': 'px-2',
+    'px-lg': 'px-2.5',
+    'px-xl': 'px-3',
+    'py-xs': 'py-1',
+    'py-sm': 'py-1.5',
+    'py-md': 'py-2',
+    'py-lg': 'py-2.5',
+    'py-xl': 'py-3',
+    // Gaps - small increments
+    'gap-sm': 'gap-1',
+    'gap-md': 'gap-1.5',
+    'gap-lg': 'gap-2',
+    'gap-xl': 'gap-2.5',
+    // Heights
+    'h-header': 'h-10',
+    'h-input': 'min-h-10',
+    // Text
+    'text-base': 'text-sm',
+    'text-title': 'text-xl',
+    'text-subtitle': 'text-sm',
+  },
+  normal: {
+    // Padding - medium increments (1, 2, 3, 4, 5, 6)
+    'p-xs': 'p-1',
+    'p-sm': 'p-2',
+    'p-md': 'p-3',
+    'p-lg': 'p-4',
+    'p-xl': 'p-6',
+    'px-xs': 'px-1',
+    'px-sm': 'px-2',
+    'px-md': 'px-3',
+    'px-lg': 'px-4',
+    'px-xl': 'px-6',
+    'py-xs': 'py-1',
+    'py-sm': 'py-2',
+    'py-md': 'py-3',
+    'py-lg': 'py-4',
+    'py-xl': 'py-6',
+    // Gaps - medium increments
+    'gap-sm': 'gap-1.5',
+    'gap-md': 'gap-2',
+    'gap-lg': 'gap-3',
+    'gap-xl': 'gap-4',
+    // Heights
+    'h-header': 'h-12',
+    'h-input': 'min-h-12',
+    // Text
+    'text-base': 'text-base',
+    'text-title': 'text-2xl',
+    'text-subtitle': 'text-base',
+  },
+  spacious: {
+    // Padding - large increments (2, 3, 4, 6, 8, 10)
+    'p-xs': 'p-2',
+    'p-sm': 'p-3',
+    'p-md': 'p-4',
+    'p-lg': 'p-6',
+    'p-xl': 'p-10',
+    'px-xs': 'px-2',
+    'px-sm': 'px-3',
+    'px-md': 'px-4',
+    'px-lg': 'px-6',
+    'px-xl': 'px-10',
+    'py-xs': 'py-2',
+    'py-sm': 'py-3',
+    'py-md': 'py-4',
+    'py-lg': 'py-6',
+    'py-xl': 'py-10',
+    // Gaps - large increments
+    'gap-sm': 'gap-2',
+    'gap-md': 'gap-3',
+    'gap-lg': 'gap-4',
+    'gap-xl': 'gap-6',
+    // Heights
+    'h-header': 'h-14',
+    'h-input': 'min-h-16',
+    // Text
+    'text-base': 'text-lg',
+    'text-title': 'text-3xl',
+    'text-subtitle': 'text-lg',
+  },
+} as const
+
+type DensityToken = keyof (typeof densityClasses)['normal']
+
+/**
+ * Hook to get density classes based on theme config
+ * Use: const d = useDensity(); then d('p-md') returns the appropriate padding class
+ */
+export const useDensity = () => {
+  const { config } = useElements()
+  const density = config.theme?.density ?? 'normal'
+
+  return (token: DensityToken) => densityClasses[density][token]
+}

package/src/hooks/useElements.ts

@@ -0,0 +1,14 @@
+import { useContext } from 'react'
+import { ElementsContext } from '@/contexts/contexts'
+
+/**
+ * @private Internal hook to access the ElementsContext
+ *
+ */
+export const useElements = () => {
+  const context = useContext(ElementsContext)
+  if (!context) {
+    throw new Error('useElements must be used within a ElementsProvider')
+  }
+  return context
+}

package/src/hooks/useExpanded.ts

@@ -0,0 +1,20 @@
+import { Dispatch, SetStateAction } from 'react'
+import { useElements } from './useElements'
+
+interface UseExpandedAPI {
+  expandable: boolean
+  isExpanded: boolean
+  defaultExpanded: boolean
+  setIsExpanded: Dispatch<SetStateAction<boolean>>
+}
+
+export const useExpanded = (): UseExpandedAPI => {
+  const { config, isExpanded, setIsExpanded } = useElements()
+  const defaultExpanded = config.modal?.defaultExpanded ?? false
+  return {
+    expandable: config.modal?.expandable ?? false,
+    isExpanded,
+    setIsExpanded,
+    defaultExpanded,
+  }
+}

package/src/hooks/useMCPTools.ts

@@ -0,0 +1,73 @@
+import { assert } from '@/lib/utils'
+import { experimental_createMCPClient as createMCPClient } from '@ai-sdk/mcp'
+import { useQuery, type UseQueryResult } from '@tanstack/react-query'
+import { Auth } from './useAuth'
+
+type MCPToolsResult = Awaited<
+  ReturnType<Awaited<ReturnType<typeof createMCPClient>>['tools']>
+>
+
+export function useMCPTools({
+  auth,
+  mcp,
+  environment,
+}: {
+  auth: Auth
+  mcp: string | undefined
+  environment: Record<string, unknown>
+}): UseQueryResult<MCPToolsResult, Error> {
+  const authQueryKey = Object.entries(auth.headers ?? {}).map(
+    (k, v) => `${k}:${v}`
+  )
+
+  const queryResult = useQuery({
+    queryKey: ['mcpTools', mcp, ...authQueryKey],
+    queryFn: async () => {
+      assert(!auth.isLoading, 'No auth found')
+      assert(mcp, 'No MCP URL found')
+
+      const mcpClient = await createMCPClient({
+        name: 'gram-elements-mcp-client',
+        transport: {
+          type: 'http',
+          url: mcp,
+          headers: {
+            ...transformEnvironmentToHeaders(environment ?? {}),
+            ...auth.headers,
+          },
+        },
+      })
+
+      const mcpTools = await mcpClient.tools()
+      return mcpTools
+    },
+    enabled: !auth.isLoading && !!mcp,
+    staleTime: Infinity,
+    gcTime: Infinity,
+  })
+
+  return queryResult
+}
+
+const HEADER_PREFIX = 'MCP-'
+
+function transformEnvironmentToHeaders(environment: Record<string, unknown>) {
+  if (typeof environment !== 'object' || environment === null) {
+    return {}
+  }
+  return Object.entries(environment).reduce(
+    (acc, [key, value]) => {
+      // Normalize key: replace underscores with dashes
+      const normalizedKey = key.replace(/_/g, '-')
+
+      // Add MCP- prefix if it doesn't already have it
+      const headerKey = normalizedKey.startsWith(HEADER_PREFIX)
+        ? normalizedKey
+        : `${HEADER_PREFIX}${normalizedKey}`
+
+      acc[headerKey] = value as string
+      return acc
+    },
+    {} as Record<string, string>
+  )
+}

package/src/hooks/usePluginComponents.ts

@@ -0,0 +1,34 @@
+import {
+  CodeHeaderProps,
+  SyntaxHighlighterProps,
+} from '@assistant-ui/react-markdown'
+import { ComponentType, useMemo } from 'react'
+import { Plugin } from '@/types/plugins'
+
+type ComponentsByLanguage =
+  | Record<
+      string,
+      {
+        CodeHeader?: ComponentType<CodeHeaderProps> | undefined
+        SyntaxHighlighter?: ComponentType<SyntaxHighlighterProps> | undefined
+      }
+    >
+  | undefined
+
+export function useComponentsByLanguage(plugins: Plugin[]) {
+  return useMemo(() => {
+    return plugins.reduce((acc, plugin) => {
+      if (acc?.[plugin.language] && !plugin.overrideExisting) {
+        return acc
+      }
+      acc = {
+        ...acc,
+        [plugin.language]: {
+          CodeHeader: plugin.Header ?? (() => null),
+          SyntaxHighlighter: plugin.Component ?? undefined,
+        },
+      }
+      return acc
+    }, {} as ComponentsByLanguage)
+  }, [plugins])
+}

package/src/hooks/useRadius.ts

@@ -0,0 +1,42 @@
+import { Radius } from '@/types'
+import { useElements } from './useElements'
+
+/**
+ * Radius class mappings for different UI elements
+ */
+const radiusClasses: Record<Radius, Record<RadiusSize, string>> = {
+  sharp: {
+    sm: 'rounded-sm',
+    md: 'rounded',
+    lg: 'rounded-md',
+    xl: 'rounded-lg',
+    full: 'rounded-lg',
+  },
+  soft: {
+    sm: 'rounded',
+    md: 'rounded-lg',
+    lg: 'rounded-xl',
+    xl: 'rounded-2xl',
+    full: 'rounded-full',
+  },
+  round: {
+    sm: 'rounded-lg',
+    md: 'rounded-xl',
+    lg: 'rounded-2xl',
+    xl: 'rounded-3xl',
+    full: 'rounded-full',
+  },
+} as const
+
+type RadiusSize = 'sm' | 'md' | 'lg' | 'xl' | 'full'
+
+/**
+ * Hook to get radius classes based on theme config
+ * Use: const r = useRadius(); then r('lg') returns the appropriate rounded class
+ */
+export const useRadius = () => {
+  const { config } = useElements()
+  const radius = config.theme?.radius ?? 'soft'
+
+  return (size: RadiusSize) => radiusClasses[radius][size]
+}

package/src/hooks/useSession.ts

@@ -0,0 +1,38 @@
+import { GetSessionFn } from '@/types'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+
+/**
+ * Hook to fetch or retrieve the session token for the chat.
+ * @returns The session token string or null
+ */
+export const useSession = ({
+  getSession,
+  projectSlug,
+  enabled,
+}: {
+  getSession: GetSessionFn | null
+  projectSlug: string
+  enabled: boolean
+}): string | null => {
+  const queryClient = useQueryClient()
+  const queryKey = ['chatSession', projectSlug]
+
+  const queryState = queryClient.getQueryState(queryKey)
+  const hasData = queryState?.data !== undefined
+  // Check if data is stale - with staleTime: Infinity, data never becomes stale
+  // but we check dataUpdatedAt to determine if we should refetch
+  const dataUpdatedAt = queryState?.dataUpdatedAt ?? 0
+  const staleTime = Infinity // Matches the staleTime in useQuery options
+  const isStale = hasData && Date.now() - dataUpdatedAt > staleTime
+  const shouldFetch = !hasData || isStale
+
+  const { data: fetchedSessionToken } = useQuery({
+    queryKey,
+    queryFn: () => getSession!({ projectSlug }),
+    enabled: enabled && shouldFetch && getSession !== null,
+    staleTime: Infinity, // Session tokens don't need to be refetched
+    gcTime: Infinity, // Keep in cache indefinitely
+  })
+
+  return fetchedSessionToken ?? null
+}

package/src/hooks/useThemeProps.ts

@@ -0,0 +1,24 @@
+import { useMemo } from 'react'
+import { useElements } from './useElements'
+
+/**
+ * Hook to get theme-related props including dark mode class
+ */
+export const useThemeProps = () => {
+  const { config } = useElements()
+  const theme = config.theme ?? {}
+
+  return useMemo(() => {
+    const { colorScheme = 'light' } = theme
+
+    const isDark =
+      colorScheme === 'dark' ||
+      (colorScheme === 'system' &&
+        typeof window !== 'undefined' &&
+        window.matchMedia('(prefers-color-scheme: dark)').matches)
+
+    return {
+      className: isDark ? 'dark' : undefined,
+    } as const
+  }, [theme])
+}

package/src/hooks/useToolApproval.ts

@@ -0,0 +1,16 @@
+import { useContext } from 'react'
+import { ToolApprovalContext } from '@/contexts/contexts'
+
+/**
+ * Hook to access the tool approval context for managing human-in-the-loop
+ * tool execution approval.
+ */
+export const useToolApproval = () => {
+  const context = useContext(ToolApprovalContext)
+  if (!context) {
+    throw new Error(
+      'useToolApproval must be used within a ToolApprovalProvider'
+    )
+  }
+  return context
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+// Side-effect import to include CSS in build (consumers import via @gram-ai/elements/elements.css)
+import './global.css'
+
+// Context Providers
+export { ElementsProvider as GramElementsProvider } from './contexts/ElementsProvider'
+export { useElements as useGramElements } from './hooks/useElements'
+
+// Core Components
+export { Chat } from '@/components/Chat'
+
+// Frontend Tools
+export { defineFrontendTool } from './lib/tools'
+export type { FrontendTool } from './lib/tools'
+
+// Types
+export type {
+  AttachmentsConfig,
+  COLOR_SCHEMES,
+  ColorScheme,
+  ComponentOverrides,
+  ComposerConfig,
+  DENSITIES,
+  Density,
+  Dimension,
+  Dimensions,
+  ElementsConfig,
+  GetSessionFn,
+  ModalConfig,
+  ModalTriggerPosition,
+  Model,
+  ModelConfig,
+  RADII,
+  Radius,
+  SidecarConfig,
+  Suggestion,
+  ThemeConfig,
+  ToolsConfig,
+  Variant,
+  VARIANTS,
+  WelcomeConfig,
+} from './types'
+
+export { MODELS } from './lib/models'
+
+export type { Plugin } from './types/plugins'

package/src/lib/api.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import type { ElementsConfig } from '@/types'
+
+describe('getApiUrl', () => {
+  beforeEach(() => {
+    vi.resetModules()
+  })
+
+  async function loadGetApiUrl(gramApiUrl: string | undefined) {
+    vi.stubGlobal('__GRAM_API_URL__', gramApiUrl)
+    const { getApiUrl } = await import('./api')
+    return getApiUrl
+  }
+
+  it('uses config.api.url when set', async () => {
+    const getApiUrl = await loadGetApiUrl('https://env.example.com')
+    const config: ElementsConfig = {
+      projectSlug: 'test',
+      api: { url: 'https://config.example.com', UNSAFE_apiKey: 'test-key' },
+    }
+
+    expect(getApiUrl(config)).toBe('https://config.example.com')
+  })
+
+  it('falls back to __GRAM_API_URL__ when config.api.url is not set', async () => {
+    const getApiUrl = await loadGetApiUrl('https://env.example.com')
+    const config: ElementsConfig = {
+      projectSlug: 'test',
+      api: { UNSAFE_apiKey: 'test-key' },
+    }
+
+    expect(getApiUrl(config)).toBe('https://env.example.com')
+  })
+
+  it('falls back to __GRAM_API_URL__ when config.api is undefined', async () => {
+    const getApiUrl = await loadGetApiUrl('https://env.example.com')
+    const config: ElementsConfig = {
+      projectSlug: 'test',
+    }
+
+    expect(getApiUrl(config)).toBe('https://env.example.com')
+  })
+
+  it('falls back to default URL when both config.api.url and __GRAM_API_URL__ are not set', async () => {
+    const getApiUrl = await loadGetApiUrl('')
+    const config: ElementsConfig = {
+      projectSlug: 'test',
+    }
+
+    expect(getApiUrl(config)).toBe('https://app.getgram.ai')
+  })
+
+  it('falls back to default URL when __GRAM_API_URL__ is undefined', async () => {
+    const getApiUrl = await loadGetApiUrl(undefined)
+    const config: ElementsConfig = {
+      projectSlug: 'test',
+    }
+
+    expect(getApiUrl(config)).toBe('https://app.getgram.ai')
+  })
+
+  it('skips empty string config.api.url and uses __GRAM_API_URL__', async () => {
+    const getApiUrl = await loadGetApiUrl('https://env.example.com')
+    const config: ElementsConfig = {
+      projectSlug: 'test',
+      api: { url: '', UNSAFE_apiKey: 'test-key' },
+    }
+
+    expect(getApiUrl(config)).toBe('https://env.example.com')
+  })
+
+  it('removes trailing slashes from the URL', async () => {
+    const getApiUrl = await loadGetApiUrl('')
+    const config: ElementsConfig = {
+      projectSlug: 'test',
+      api: { url: 'https://config.example.com///', UNSAFE_apiKey: 'test-key' },
+    }
+
+    expect(getApiUrl(config)).toBe('https://config.example.com')
+  })
+
+  it('removes trailing slashes from __GRAM_API_URL__', async () => {
+    const getApiUrl = await loadGetApiUrl('https://env.example.com//')
+    const config: ElementsConfig = {
+      projectSlug: 'test',
+    }
+
+    expect(getApiUrl(config)).toBe('https://env.example.com')
+  })
+})

package/src/lib/api.ts

@@ -0,0 +1,8 @@
+import { ElementsConfig } from '@/types'
+
+export function getApiUrl(config: ElementsConfig): string {
+  // The api.url in the config should take precedence over the __GRAM_API_URL__ environment variable
+  // because it is a user-defined override
+  const apiURL = config.api?.url || __GRAM_API_URL__ || 'https://app.getgram.ai'
+  return apiURL.replace(/\/+$/, '') // Remove trailing slashes
+}

package/src/lib/auth.ts

@@ -0,0 +1,10 @@
+import { ApiKeyAuthConfig, AuthConfig } from '@/types'
+
+/**
+ * Checks if the auth config is an API key auth config
+ */
+export function isApiKeyAuth(
+  auth: AuthConfig | undefined
+): auth is ApiKeyAuthConfig {
+  return !!auth && 'UNSAFE_apiKey' in auth
+}

package/src/lib/easing.ts

@@ -0,0 +1 @@
+export const EASE_OUT_QUINT = [0.23, 1, 0.32, 1] as const

package/src/lib/humanize.ts

@@ -0,0 +1,14 @@
+// humanize tool name:
+// - split camel case into words
+// - capitalize first letter of each word
+// - remove hyphens / underscores
+// - title case the string
+export function humanizeToolName(toolName: string): string {
+  return toolName
+    .replace(/[-_]/g, ' ') // Replace hyphens and underscores with spaces
+    .split(/(?=[A-Z])/) // Split on camelCase boundaries
+    .join(' ') // Join with spaces
+    .split(/\s+/) // Split on any whitespace to normalize
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()) // Title case each word
+    .join(' ')
+}

package/src/lib/models.ts

@@ -0,0 +1,22 @@
+// List of openrouter models available to the user
+// This list should be updated to match the model whitelist on the backend side.
+export const MODELS = [
+  'anthropic/claude-sonnet-4.5',
+  'anthropic/claude-haiku-4.5',
+  'anthropic/claude-sonnet-4',
+  'anthropic/claude-opus-4.5',
+  'openai/gpt-4o',
+  'openai/gpt-4o-mini',
+  'openai/gpt-5.1-codex',
+  'openai/gpt-5',
+  'openai/gpt-5.1',
+  'openai/gpt-4.1',
+  'anthropic/claude-3.7-sonnet',
+  'anthropic/claude-opus-4',
+  'google/gemini-2.5-pro-preview',
+  'google/gemini-3-pro-preview',
+  'moonshotai/kimi-k2',
+  'mistralai/mistral-medium-3',
+  'mistralai/mistral-medium-3.1',
+  'mistralai/codestral-2501',
+] as const