@gram-ai/elements 1.10.0 → 1.11.0

package/README.md

@@ -109,6 +109,7 @@ The `ElementsConfig` object accepts the following configuration options:
 | `chatEndpoint` | `string`                                                   | No       | ✅ Implemented | `'/chat/completions'` | The path of your backend's chat endpoint                                                                                                                                                                            |
 | `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                                                                                                                      |
 | `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                                                                                                                                                                                |
@@ -240,6 +241,7 @@ const config: ElementsConfig = {
 
 ```typescript
 import { ElementsConfig } from '@gram-ai/elements'
+import { recommended } from '@gram-ai/elements/plugins'
 import { WeatherComponent } from './components/WeatherComponent'
 
 const config: ElementsConfig = {
@@ -248,6 +250,7 @@ const config: ElementsConfig = {
   mcp: 'https://app.getgram.ai/mcp/my-mcp-slug',
   chatEndpoint: '/api/chat',
   variant: 'widget',
+  plugins: recommended,
   theme: {
     colorScheme: 'system',
     density: 'normal',
@@ -375,6 +378,106 @@ const config: ElementsConfig = {
 }
 ```
 
+## 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.
+
+### How Plugins Work
+
+When you add a plugin:
+
+1. The plugin extends the system prompt with instructions for the LLM
+2. The LLM returns code blocks marked with the plugin's language identifier
+3. The plugin's custom component renders the code block content
+
+For example, the built-in chart plugin instructs the LLM to return Vega specifications for visualizations, which are then rendered as interactive charts.
+
+### Using Recommended Plugins
+
+Gram Elements includes a set of recommended plugins that you can use out of the box:
+
+```typescript
+import { GramElementsProvider, Chat, type ElementsConfig } from '@gram-ai/elements'
+import { recommended } from '@gram-ai/elements/plugins'
+import '@gram-ai/elements/elements.css'
+
+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?',
+  },
+  // Add all recommended plugins
+  plugins: recommended,
+}
+
+export const App = () => {
+  return (
+    <GramElementsProvider config={config}>
+      <Chat />
+    </GramElementsProvider>
+  )
+}
+```
+
+#### Available Recommended Plugins
+
+- **`chart`** - Renders Vega chart specifications as interactive visualizations
+
+### Using Individual Plugins
+
+You can also import and use plugins individually:
+
+```typescript
+import { chart } from '@gram-ai/elements/plugins'
+
+const config: ElementsConfig = {
+  // ... other config
+  plugins: [chart],
+}
+```
+
+### Using Custom Plugins
+
+You can create your own custom plugins to add specialized rendering capabilities:
+
+```typescript
+import { GramElementsProvider, Chat, type ElementsConfig } from '@gram-ai/elements'
+import { chart } from '@gram-ai/elements/plugins'
+import { myCustomPlugin } from './plugins/myCustomPlugin'
+import '@gram-ai/elements/elements.css'
+
+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?',
+  },
+  // Combine built-in and custom plugins
+  plugins: [chart, myCustomPlugin],
+}
+
+export const App = () => {
+  return (
+    <GramElementsProvider config={config}>
+      <Chat />
+    </GramElementsProvider>
+  )
+}
+```
+
+### Creating Custom Plugins
+
+To create your own plugins, see the comprehensive [Plugin Development Guide](./src/plugins/README.md). The guide covers:
+
+- Plugin architecture and interface
+- Step-by-step tutorial for creating plugins
+- Best practices and common patterns
+- Real-world examples
+- Troubleshooting tips
+
 ## Contributing
 
 We welcome pull requests to Elements. Please read the contributing guide.