@gram-ai/elements 1.12.0 → 1.13.0

package/README.md

@@ -110,6 +110,7 @@ The `ElementsConfig` object accepts the following configuration options:
 | `environment`  | `Record<string, unknown>`                                  | No       | ✅ Implemented | `undefined`           | Custom environment variable overrides for the MCP server. See [Gram documentation](https://www.speakeasy.com/docs/gram/host-mcp/public-private-servers#pass-through-authentication) for pass-through authentication |
 | `variant`      | `'widget' \| 'sidecar' \| 'standalone'`                    | No       | ✅ Implemented | `'widget'`            | The layout variant for the chat interface. `widget` is a popup modal, `sidecar` is a side panel, `standalone` is a full-page experience                                                                             |
 | `plugins`      | [`Plugin[]`](#plugins)                                     | No       | ✅ Implemented | `[]`                  | Array of plugins to extend rendering capabilities. See [Plugins section](#plugins) for details                                                                                                                      |
+| `components`   | [`ComponentOverrides`](#component-overrides)               | No       | ✅ Implemented | `undefined`           | Override default UI components with custom implementations. See [Component Overrides section](#component-overrides) for details                                                                                     |
 | `theme`        | [`ThemeConfig`](#theme-configuration-themeconfig)          | No       | ✅ Implemented | `undefined`           | Visual appearance configuration options                                                                                                                                                                             |
 | `welcome`      | [`WelcomeConfig`](#welcome-configuration-welcomeconfig)    | Yes      | ✅ Implemented | -                     | Configuration for the welcome message and initial suggestions                                                                                                                                                       |
 | `composer`     | [`ComposerConfig`](#composer-configuration-composerconfig) | No       | ✅ Implemented | `undefined`           | Configuration for the composer input                                                                                                                                                                                |
@@ -220,6 +221,160 @@ The following models are currently supported:
 | ------------ | ---------------------------------------------- | -------- | -------------- | ----------- | ------------------------------------------------------------------------------------------ |
 | `components` | `Record<string, ToolCallMessagePartComponent>` | No       | ✅ Implemented | `undefined` | Override default React components for specific tool results. Tool names must match exactly |
 
+## Component Overrides
+
+The `components` property in `ElementsConfig` allows you to override default UI components with your own custom implementations. This provides fine-grained control over the appearance and behavior of different parts of the chat interface.
+
+### Available Component Overrides
+
+| Component          | Type                            | Description                                                  |
+| ------------------ | ------------------------------- | ------------------------------------------------------------ |
+| `Composer`         | `ComponentType`                 | The composer input area where users type messages            |
+| `UserMessage`      | `ComponentType`                 | The entire user message bubble/container                     |
+| `EditComposer`     | `ComponentType`                 | The composer shown when editing a user message               |
+| `AssistantMessage` | `ComponentType`                 | The entire assistant message bubble/container                |
+| `ThreadWelcome`    | `ComponentType`                 | The welcome screen shown when the thread is empty            |
+| `Text`             | `TextMessagePartComponent`      | Text content within messages (supports Markdown by default)  |
+| `Image`            | `ImageMessagePartComponent`     | Image attachments within messages                            |
+| `ToolFallback`     | `ToolCallMessagePartComponent`  | Default component for tool results without custom components |
+| `Reasoning`        | `ReasoningMessagePartComponent` | Individual reasoning steps shown in assistant messages       |
+| `ReasoningGroup`   | `ReasoningGroupComponent`       | Container for grouped reasoning steps                        |
+| `ToolGroup`        | `ComponentType`                 | Container for grouped tool calls                             |
+
+### Component Override Examples
+
+#### Basic Text Override
+
+Override how text is rendered in assistant messages:
+
+```typescript
+import { ElementsConfig } from '@gram-ai/elements'
+import { useAssistantState } from '@assistant-ui/react'
+
+const config: ElementsConfig = {
+  projectSlug: 'my-project',
+  mcp: 'https://app.getgram.ai/mcp/my-mcp-slug',
+  welcome: {
+    title: 'Hello!',
+    subtitle: 'How can I help you today?',
+  },
+  components: {
+    Text: () => {
+      const message = useAssistantState(({ message }) => message)
+      const text = message.parts
+        .map((part) => (part.type === 'text' ? part.text : ''))
+        .join('')
+
+      return (
+        <div className="custom-text">
+          {text}
+        </div>
+      )
+    },
+  },
+}
+```
+
+#### Custom Welcome Screen
+
+Override the welcome screen with your own design:
+
+```typescript
+import { ElementsConfig } from '@gram-ai/elements'
+
+const CustomWelcome = () => {
+  return (
+    <div className="flex flex-col items-center justify-center h-full">
+      <h1 className="text-4xl font-bold mb-4">Welcome to My AI Assistant!</h1>
+      <p className="text-gray-600">Start chatting below</p>
+    </div>
+  )
+}
+
+const config: ElementsConfig = {
+  projectSlug: 'my-project',
+  mcp: 'https://app.getgram.ai/mcp/my-mcp-slug',
+  welcome: {
+    title: 'Hello!',
+    subtitle: 'How can I help you today?',
+  },
+  components: {
+    ThreadWelcome: CustomWelcome,
+  },
+}
+```
+
+#### Custom Message Containers
+
+Override the entire message container for more control:
+
+```typescript
+import { ElementsConfig } from '@gram-ai/elements'
+import { MessagePrimitive } from '@assistant-ui/react'
+
+const CustomUserMessage = () => {
+  return (
+    <MessagePrimitive.Root>
+      <div className="my-custom-user-message">
+        <div className="message-avatar">👤</div>
+        <div className="message-content">
+          <MessagePrimitive.Parts />
+        </div>
+      </div>
+    </MessagePrimitive.Root>
+  )
+}
+
+const config: ElementsConfig = {
+  projectSlug: 'my-project',
+  mcp: 'https://app.getgram.ai/mcp/my-mcp-slug',
+  welcome: {
+    title: 'Hello!',
+    subtitle: 'How can I help you today?',
+  },
+  components: {
+    UserMessage: CustomUserMessage,
+  },
+}
+```
+
+#### Combining Multiple Overrides
+
+You can override multiple components at once:
+
+```typescript
+import { ElementsConfig } from '@gram-ai/elements'
+import {
+  CustomComposer,
+  CustomUserMessage,
+  CustomAssistantMessage,
+  CustomText,
+} from './components'
+
+const config: ElementsConfig = {
+  projectSlug: 'my-project',
+  mcp: 'https://app.getgram.ai/mcp/my-mcp-slug',
+  welcome: {
+    title: 'Hello!',
+    subtitle: 'How can I help you today?',
+  },
+  components: {
+    Composer: CustomComposer,
+    UserMessage: CustomUserMessage,
+    AssistantMessage: CustomAssistantMessage,
+    Text: CustomText,
+  },
+}
+```
+
+### Notes on Component Overrides
+
+- Component overrides give you full control over rendering, but you're responsible for maintaining the expected behavior
+- When overriding message containers (`UserMessage`, `AssistantMessage`), make sure to include `MessagePrimitive.Root` and `MessagePrimitive.Parts` to maintain compatibility with the assistant-ui runtime
+- For text content overrides, the default `Text` component supports Markdown rendering. If you override it, you'll need to implement your own Markdown support if needed
+- Component overrides are applied globally across your chat interface
+- For building custom components from scratch, refer to the [assistant-ui Context API documentation](https://www.assistant-ui.com/docs/guides/context-api) which provides detailed information about the state management system, available actions, and hooks like `useAssistantState`, `useAssistantApi`, and `useAssistantEvent`
+
 ### Configuration Examples
 
 #### Minimal Configuration
@@ -243,6 +398,7 @@ const config: ElementsConfig = {
 import { ElementsConfig } from '@gram-ai/elements'
 import { recommended } from '@gram-ai/elements/plugins'
 import { WeatherComponent } from './components/WeatherComponent'
+import { CustomText } from './components/CustomText'
 
 const config: ElementsConfig = {
   systemPrompt: 'You are a helpful AI assistant.',
@@ -251,6 +407,9 @@ const config: ElementsConfig = {
   chatEndpoint: '/api/chat',
   variant: 'widget',
   plugins: recommended,
+  components: {
+    Text: CustomText,
+  },
   theme: {
     colorScheme: 'system',
     density: 'normal',
@@ -308,76 +467,6 @@ const config: ElementsConfig = {
 }
 ```
 
-#### Widget Variant with Custom Modal Icon
-
-```typescript
-import { ElementsConfig } from '@gram-ai/elements'
-import { MessageSquare, X } from 'lucide-react'
-
-const config: ElementsConfig = {
-  projectSlug: 'my-project',
-  mcp: 'https://app.getgram.ai/mcp/my-mcp-slug',
-  variant: 'widget',
-  welcome: {
-    title: 'Chat with us!',
-    subtitle: 'Ask anything',
-  },
-  modal: {
-    defaultOpen: true,
-    icon: (state) => (state === 'open' ? <X /> : <MessageSquare />),
-  },
-}
-```
-
-#### Standalone Variant with Model Picker
-
-```typescript
-import { ElementsConfig } from '@gram-ai/elements'
-
-const config: ElementsConfig = {
-  projectSlug: 'my-project',
-  mcp: 'https://app.getgram.ai/mcp/my-mcp-slug',
-  variant: 'standalone',
-  welcome: {
-    title: 'AI Assistant',
-    subtitle: 'Choose a model and start chatting',
-  },
-  composer: {
-    placeholder: 'Ask me anything...',
-  },
-  model: {
-    showModelPicker: true,
-    defaultModel: 'openai/gpt-4o',
-  },
-}
-```
-
-#### Sidecar Variant with Custom Theme
-
-```typescript
-import { ElementsConfig } from '@gram-ai/elements'
-
-const config: ElementsConfig = {
-  projectSlug: 'my-project',
-  mcp: 'https://app.getgram.ai/mcp/my-mcp-slug',
-  variant: 'sidecar',
-  theme: {
-    colorScheme: 'dark',
-    density: 'compact',
-    radius: 'round',
-  },
-  welcome: {
-    title: 'Support Chat',
-    subtitle: "We're here to help",
-  },
-  sidecar: {
-    title: 'Customer Support',
-    width: '450px',
-    expandedWidth: '900px',
-  },
-}
-```
-
 ## Plugins
 
 Plugins extend the Gram Elements library with custom rendering capabilities for specific content types. They allow you to transform markdown code blocks into rich, interactive visualizations and components.

package/dist/components/ui/button.d.ts

@@ -2,7 +2,7 @@ import { VariantProps } from 'class-variance-authority';
 import * as React from 'react';
 declare const Button: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLButtonElement> & React.ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<(props?: ({
     variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
-    size?: "icon" | "default" | "sm" | "lg" | "icon-sm" | "icon-lg" | null | undefined;
+    size?: "icon" | "sm" | "lg" | "default" | "icon-sm" | "icon-lg" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string> & {
     asChild?: boolean;
 }, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/ui/buttonVariants.d.ts

@@ -1,4 +1,4 @@
 export declare const buttonVariants: (props?: ({
     variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
-    size?: "icon" | "default" | "sm" | "lg" | "icon-sm" | "icon-lg" | null | undefined;
+    size?: "icon" | "sm" | "lg" | "default" | "icon-sm" | "icon-lg" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;