@gram-ai/elements 1.14.0 → 1.15.0

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 import { MODELS } from '../lib/models';
-import { ImageMessagePartComponent, ReasoningGroupComponent, ReasoningMessagePartComponent, TextMessagePartComponent, ToolCallMessagePartComponent } from '@assistant-ui/react';
+import { AssistantTool, ImageMessagePartComponent, ReasoningGroupComponent, ReasoningMessagePartComponent, TextMessagePartComponent, ToolCallMessagePartComponent } from '@assistant-ui/react';
 import { ComponentType, Dispatch, PropsWithChildren, SetStateAction, ReactNode } from 'react';
 import { Plugin } from './plugins';
 export interface ElementsProviderProps {
@@ -15,6 +15,14 @@ export interface ElementsProviderProps {
 type ServerUrl = string;
 export declare const VARIANTS: readonly ["widget", "sidecar", "standalone"];
 export type Variant = (typeof VARIANTS)[number];
+/**
+ * The top level configuration object for the Elements library.
+ *
+ * @example
+ * const config: ElementsConfig = {
+ *   systemPrompt: 'You are a helpful assistant.',
+ * }
+ */
 export interface ElementsConfig {
     /**
      * The system prompt to use for the Elements library.
@@ -26,9 +34,41 @@ export interface ElementsConfig {
      * @default import { recommended } from '@gram-ai/elements/plugins'
      */
     plugins?: Plugin[];
+    /**
+     * Override the default components used by the Elements library.
+     *
+     * The available components are:
+     * - Composer
+     * - UserMessage
+     * - EditComposer
+     * - AssistantMessage
+     * - ThreadWelcome
+     * - Text
+     * - Image
+     * - ToolFallback
+     * - Reasoning
+     * - ReasoningGroup
+     * - ToolGroup
+     *
+     * To understand how to override these components, please consult the [assistant-ui documentation](https://www.assistant-ui.com/docs).
+     *
+     * @example
+     * const config: ElementsConfig = {
+     *   components: {
+     *     Composer: CustomComposerComponent,
+     *   },
+     * }
+     */
     components?: ComponentOverrides;
     /**
      * The project slug to use for the Elements library.
+     *
+     * Your project slug can be found within the Gram dashboard.
+     *
+     * @example
+     * const config: ElementsConfig = {
+     *   projectSlug: 'your-project-slug',
+     * }
      */
     projectSlug: string;
     /**
@@ -36,10 +76,16 @@ export interface ElementsConfig {
      * Can be retrieved from https://app.getgram.ai/{team}/{project}/mcp/{mcp_slug}
      *
      * Note: This config option will likely change in the future
+     *
+     * @example
+     * const config: ElementsConfig = {
+     *   mcp: 'https://app.getgram.ai/mcp/your-mcp-slug',
+     * }
      */
     mcp: ServerUrl;
     /**
      * The path of your backend's chat endpoint.
+     *
      * @default '/chat/completions'
      *
      * @example
@@ -51,6 +97,7 @@ export interface ElementsConfig {
     /**
      * Custom environment variable overrides for the Elements library.
      * Will be used to override the environment variables for the MCP server.
+     *
      * For more documentation on passing through different kinds of environment variables, including bearer tokens, see the [Gram documentation](https://www.speakeasy.com/docs/gram/host-mcp/public-private-servers#pass-through-authentication).
      */
     environment?: Record<string, unknown>;
@@ -78,32 +125,112 @@ export interface ElementsConfig {
     model?: ModelConfig;
     /**
      * Visual appearance configuration options.
-     * Similar to OpenAI ChatKit's ThemeOption.
+     * Similar to OpenAI ChatKit's ThemeOption.\
+     *
+     * @example
+     * const config: ElementsConfig = {
+     *   theme: {
+     *     colorScheme: 'dark',
+     *     density: 'compact',
+     *     radius: 'round',
+     *   },
+     * }
      */
     theme?: ThemeConfig;
     /**
      * The configuration for the welcome message and initial suggestions.
+     *
+     * @example
+     * const config: ElementsConfig = {
+     *   welcome: {
+     *     title: 'Welcome to the chat',
+     *     subtitle: 'This is a chat with a bot',
+     *     suggestions: [
+     *       { title: 'Suggestion 1', label: 'Suggestion 1', action: 'action1' },
+     *     ],
+     *   },
+     * }
      */
     welcome: WelcomeConfig;
     /**
      * The configuration for the composer.
+     *
+     * @example
+     * const config: ElementsConfig = {
+     *   composer: {
+     *     placeholder: 'Enter your message...',
+     *   },
+     * }
      */
     composer?: ComposerConfig;
     /**
      * The configuration for the modal window.
      * Does not apply if variant is 'standalone'.
+     *
+     * @example
+     * const config: ElementsConfig = {
+     *   modal: {
+     *     title: 'Chat',
+     *     position: 'bottom-right',
+     *   },
+     *   expandable: true,
+     *   defaultExpanded: false,
+     *   dimensions: {
+     *     width: 400,
+     *     height: 600,
+     *   },
+     * }
      */
     modal?: ModalConfig;
     /**
      * The configuration for the sidecar panel.
      * Only applies if variant is 'sidecar'.
+     *
+     * @example
+     * const config: ElementsConfig = {
+     *   sidecar: {
+     *     title: 'Chat',
+     *   },
+     *   expandable: true,
+     *   defaultExpanded: false,
+     *   dimensions: {
+     *     width: 400,
+     *     height: 600,
+     *   },
+     * }
      */
     sidecar?: SidecarConfig;
     /**
      * The configuration for the tools.
+     *
+     * @example
+     * const config: ElementsConfig = {
+     *   tools: {
+     *     expandToolGroupsByDefault: true,
+     *   },
+     *   components: {
+     *     ToolFallback: CustomToolFallbackComponent,
+     *   },
+     *   frontendTools: {
+     *     fetchUrl: FetchTool,
+     *   },
+     *   components: {
+     *     fetchUrl: FetchToolComponent,
+     *   },
+     * }
      */
     tools?: ToolsConfig;
 }
+/**
+ * The LLM model to use for the Elements library.
+ *
+ * @example
+ * const config: ElementsConfig = {
+ *   model: {
+ *     defaultModel: 'openai/gpt-4o',
+ *   },
+ * }
+ */
 export type Model = (typeof MODELS)[number];
 /**
  * ModelConfig is used to configure model support in the Elements library.
@@ -248,6 +375,54 @@ export interface ToolsConfig {
      * }
      */
     components?: Record<string, ToolCallMessagePartComponent | undefined> | undefined;
+    /**
+     * The frontend tools to use for the Elements library.
+     *
+     * @example
+     * ```ts
+     * import { defineFrontendTool } from '@gram-ai/elements'
+     *
+     * const FetchTool = defineFrontendTool<{ url: string }, string>(
+     *   {
+     *     description: 'Fetch a URL (supports CORS-enabled URLs like httpbin.org)',
+     *     parameters: z.object({
+     *       url: z.string().describe('URL to fetch (must support CORS)'),
+     *     }),
+     *     execute: async ({ url }) => {
+     *       const response = await fetch(url as string)
+     *       const text = await response.text()
+     *       return text
+     *     },
+     *   },
+     *   'fetchUrl'
+     * )
+     * const config: ElementsConfig = {
+     *   frontendTools: {
+     *     fetchUrl: FetchTool,
+     *   },
+     * }
+     * ```
+     *
+     * You can also override the default components used by the
+     * Elements library for a given tool result.
+     *
+     * @example
+     * ```ts
+     * import { FetchToolComponent } from './components/FetchToolComponent'
+     *
+     * const config: ElementsConfig = {
+     *   tools: {
+     *     frontendTools: {
+     *       fetchUrl: FetchTool,
+     *     },
+     *     components: {
+     *       'fetchUrl': FetchToolComponent, // will override the default component used by the Elements library for the 'fetchUrl' tool
+     *     },
+     *   },
+     * }
+     * ```
+     */
+    frontendTools?: Record<string, AssistantTool>;
 }
 export interface WelcomeConfig {
     /**

package/package.json

@@ -2,7 +2,7 @@
   "name": "@gram-ai/elements",
   "description": "Gram Elements is a library of UI primitives for building chat-like experiences for MCP Servers.",
   "type": "module",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "main": "dist/index.js",
   "exports": {
     ".": {
@@ -114,7 +114,7 @@
   },
   "devDependencies": {
     "@ai-sdk/openai": "^2.0.0-beta.5",
-    "@assistant-ui/react": "^0.11.37",
+    "@assistant-ui/react": "^0.11.53",
     "@assistant-ui/react-ai-sdk": "^1.1.16",
     "@assistant-ui/react-markdown": "^0.11.4",
     "@eslint/compat": "^2.0.0",