@gram-ai/elements 1.22.5 → 1.24.0

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

@@ -1,5 +1,7 @@
 import type { Meta, StoryFn } from '@storybook/react-vite'
+import { z } from 'zod'
 import { Chat } from '..'
+import { defineFrontendTool } from '../../../lib/tools'
 
 const meta: Meta<typeof Chat> = {
   title: 'Chat/Plugins',
@@ -40,3 +42,117 @@ ChartPlugin.parameters = {
     },
   },
 }
+
+const salesData = JSON.stringify({
+  headers: ['Product', 'Q1', 'Q2', 'Q3', 'Q4'],
+  rows: [
+    ['Widget A', '$12,500', '$15,200', '$18,900', '$22,100'],
+    ['Widget B', '$8,300', '$9,100', '$11,400', '$14,200'],
+    ['Widget C', '$5,600', '$6,800', '$7,900', '$9,500'],
+  ],
+})
+
+export const GenerativeUI: Story = () => <Chat />
+GenerativeUI.parameters = {
+  elements: {
+    config: {
+      variant: 'standalone',
+      welcome: {
+        suggestions: [
+          {
+            title: 'Sales Dashboard',
+            label: 'Q4 performance metrics',
+            prompt: `Here's our Q4 sales data:
+${salesData}
+
+Summarize the Q4 performance - show total revenue, quarter-over-quarter growth, and which product performed best. We're at 85% of our Q4 target.`,
+          },
+          {
+            title: 'Task List',
+            label: 'My pending tasks',
+            prompt: `Show me my pending tasks for today. I have 3 tasks:
+1. Review PR #234 - high priority
+2. Update documentation - medium priority
+3. Team sync meeting - scheduled for 3pm`,
+          },
+          {
+            title: 'System Status',
+            label: 'Service health check',
+            prompt: `What's the current status of our services?
+- API: healthy, 99.9% uptime
+- Database: healthy, 45% capacity used
+- Cache: degraded, high latency detected
+- Queue: healthy, 1,240 jobs processed`,
+          },
+        ],
+      },
+    },
+  },
+}
+
+// Frontend tools for ActionButton demo
+const completeTaskTool = defineFrontendTool<{ taskId: number }, string>(
+  {
+    description: 'Mark a task as complete',
+    parameters: z.object({
+      taskId: z.number().describe('The task ID to mark as complete'),
+    }),
+    execute: async ({ taskId }) => {
+      await new Promise((resolve) => setTimeout(resolve, 500))
+      return `Task #${taskId} has been marked as complete.`
+    },
+  },
+  'complete_task'
+)
+
+const deleteTaskTool = defineFrontendTool<{ taskId: number }, string>(
+  {
+    description: 'Delete a task',
+    parameters: z.object({
+      taskId: z.number().describe('The task ID to delete'),
+    }),
+    execute: async ({ taskId }) => {
+      await new Promise((resolve) => setTimeout(resolve, 500))
+      return `Task #${taskId} has been deleted.`
+    },
+  },
+  'delete_task'
+)
+
+const actionTools = {
+  complete_task: completeTaskTool,
+  delete_task: deleteTaskTool,
+}
+
+/**
+ * Demonstrates ActionButton in generative UI that triggers frontend tool calls.
+ * When a button is clicked, it directly executes the tool without an LLM roundtrip.
+ */
+export const GenerativeUIWithActions: Story = () => <Chat />
+GenerativeUIWithActions.parameters = {
+  elements: {
+    config: {
+      variant: 'standalone',
+      welcome: {
+        title: 'Task Manager',
+        subtitle: 'Manage your tasks with quick actions',
+        suggestions: [
+          {
+            title: 'My Tasks',
+            label: 'View pending work',
+            prompt: `Show me my task list. I have these pending tasks:
+
+Task #1: "Update user authentication" - in progress
+Task #2: "Fix pagination bug" - pending review
+Task #3: "Write API documentation" - not started
+
+I should be able to mark tasks as complete or delete them.`,
+          },
+        ],
+      },
+      tools: {
+        frontendTools: actionTools,
+      },
+    },
+  },
+}

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

@@ -0,0 +1,78 @@
+import type { Meta, StoryFn } from '@storybook/react-vite'
+import { Chat } from '..'
+
+const meta: Meta<typeof Chat> = {
+  title: 'Chat/Thread',
+  component: Chat,
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof Chat>
+
+export default meta
+
+type Story = StoryFn<typeof Chat>
+
+/**
+ * Demonstrates follow-up suggestions that appear after the assistant responds.
+ * Send a message and watch as AI-generated follow-up questions appear below the response.
+ */
+export const FollowUpSuggestions: Story = () => <Chat />
+FollowUpSuggestions.parameters = {
+  elements: {
+    config: {
+      variant: 'widget',
+      modal: {
+        defaultOpen: true,
+      },
+      systemPrompt:
+        'You are a helpful assistant. Keep ALL responses extremely brief - 1-2 sentences only. No lists, no elaboration.',
+      welcome: {
+        title: 'Explore Paris',
+        subtitle: 'Ask me anything about the City of Light',
+        suggestions: [
+          {
+            title: 'Cool places',
+            label: 'to visit in Paris',
+            prompt: 'Tell me about cool places to visit in Paris',
+          },
+        ],
+      },
+      thread: {
+        followUpSuggestions: true,
+      },
+    },
+  },
+}
+
+/**
+ * Shows the thread with follow-up suggestions disabled.
+ * No suggestions will appear after the assistant responds.
+ */
+export const FollowUpSuggestionsDisabled: Story = () => <Chat />
+FollowUpSuggestionsDisabled.parameters = {
+  elements: {
+    config: {
+      variant: 'widget',
+      modal: {
+        defaultOpen: true,
+      },
+      systemPrompt:
+        'You are a helpful assistant. Keep ALL responses extremely brief - 1-2 sentences only. No lists, no elaboration.',
+      welcome: {
+        title: 'Explore Paris',
+        subtitle: 'Ask me anything about the City of Light',
+        suggestions: [
+          {
+            title: 'Cool places',
+            label: 'to visit in Paris',
+            prompt: 'Tell me about cool places to visit in Paris',
+          },
+        ],
+      },
+      thread: {
+        followUpSuggestions: false,
+      },
+    },
+  },
+}

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

@@ -1,7 +1,9 @@
 import { ToolCallMessagePartProps } from '@assistant-ui/react'
 import type { Meta, StoryFn } from '@storybook/react-vite'
 import React from 'react'
+import z from 'zod'
 import { Chat } from '..'
+import { defineFrontendTool } from '../../../lib/tools'
 
 const meta: Meta<typeof Chat> = {
   title: 'Chat/Tools',
@@ -166,3 +168,123 @@ CustomToolComponent.parameters = {
     },
   },
 }
+
+/**
+ * Demonstrates the generativeUI plugin which renders `ui` code blocks
+ * as dynamic UI widgets.
+ *
+ * The LLM outputs JSON in a ```ui code fence, and the plugin renders it
+ * using the built-in component catalog (Card, Grid, Metric, Table, etc.)
+ */
+export const GenerativeUI: Story = () => <Chat />
+GenerativeUI.parameters = {
+  elements: {
+    config: {
+      variant: 'standalone',
+      welcome: {
+        title: 'Data Explorer',
+        subtitle: 'Ask questions about your data',
+        suggestions: [
+          {
+            title: 'Sales metrics',
+            label: 'This month',
+            prompt:
+              'What are our sales numbers this month? Revenue is $125,000, conversion rate is 3.2%, and we have 1,420 orders.',
+          },
+          {
+            title: 'Team members',
+            label: 'Directory',
+            prompt:
+              'List our team members: Alice (alice@co.com, Admin, Active), Bob (bob@co.com, Editor, Active), Charlie (charlie@co.com, Viewer, Pending)',
+          },
+          {
+            title: 'Project status',
+            label: 'Sprint progress',
+            prompt:
+              'How is our current sprint going? We have 12 tasks total, 8 completed, 3 in progress, and 1 blocked. The team has 4 developers.',
+          },
+          {
+            title: 'Website analytics',
+            label: 'Last 7 days',
+            prompt:
+              "Show me last week's website stats: 45,000 page views, 2.1% bounce rate, 3m 24s average session, top pages are /home, /pricing, /docs",
+          },
+        ],
+      },
+    },
+  },
+}
+
+// Frontend tools for the ActionButton demo
+const ApproveRequestTool = defineFrontendTool<{ id: number }, string>(
+  {
+    description: 'Approve a pending request',
+    parameters: z.object({
+      id: z.number().describe('The request ID to approve'),
+    }),
+    execute: async ({ id }) => {
+      // Simulate API call
+      await new Promise((resolve) => setTimeout(resolve, 500))
+      return `Request #${id} has been approved successfully.`
+    },
+  },
+  'approve_request'
+)
+
+const RejectRequestTool = defineFrontendTool<
+  { id: number; reason?: string },
+  string
+>(
+  {
+    description: 'Reject a pending request',
+    parameters: z.object({
+      id: z.number().describe('The request ID to reject'),
+      reason: z.string().optional().describe('Reason for rejection'),
+    }),
+    execute: async ({ id, reason }) => {
+      await new Promise((resolve) => setTimeout(resolve, 500))
+      return `Request #${id} has been rejected.${reason ? ` Reason: ${reason}` : ''}`
+    },
+  },
+  'reject_request'
+)
+
+const actionTools = {
+  approve_request: ApproveRequestTool,
+  reject_request: RejectRequestTool,
+}
+
+/**
+ * Demonstrates ActionButton in generative UI that triggers tool calls.
+ *
+ * The LLM generates UI with ActionButton components that, when clicked,
+ * directly execute the tool without an LLM roundtrip.
+ */
+export const GenerativeUIWithActions: Story = () => <Chat />
+GenerativeUIWithActions.parameters = {
+  elements: {
+    config: {
+      variant: 'standalone',
+      welcome: {
+        title: 'Expense Approvals',
+        subtitle: 'Review and process pending requests',
+        suggestions: [
+          {
+            title: 'Pending expenses',
+            label: 'Needs review',
+            prompt: `I need to review these pending expense requests:
+
+Request #1247: Sarah Chen submitted $450 for conference registration
+Request #1248: Mike Johnson submitted $89 for software subscription
+Request #1249: Lisa Park submitted $1,200 for client dinner
+
+I need to be able to approve or reject each one.`,
+          },
+        ],
+      },
+      tools: {
+        frontendTools: actionTools,
+      },
+    },
+  },
+}

package/src/components/Replay.stories.tsx

@@ -0,0 +1,326 @@
+import type { StoryFn } from '@storybook/react-vite'
+import { Chat } from '@/components/Chat'
+import { Replay } from '@/components/Replay'
+import type { Cassette } from '@/lib/cassette'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const meta: any = {
+  title: 'Replay',
+  component: Replay,
+  parameters: {
+    layout: 'fullscreen',
+    // Skip the global ElementsProvider — Replay is its own provider
+    elements: { skipProvider: true },
+  },
+}
+
+export default meta
+
+type Story = StoryFn<typeof Replay>
+
+// ---------------------------------------------------------------------------
+// Sample cassettes
+// ---------------------------------------------------------------------------
+
+const textOnlyCassette: Cassette = {
+  messages: [
+    {
+      role: 'user',
+      content: [{ type: 'text', text: 'What can you help me with?' }],
+    },
+    {
+      role: 'assistant',
+      content: [
+        {
+          type: 'text',
+          text: "I can help you with a wide range of tasks! Here are a few things I'm great at:\n\n- **Answering questions** about virtually any topic\n- **Writing and editing** emails, documents, and code\n- **Brainstorming ideas** for projects, names, or strategies\n- **Explaining concepts** in simple terms\n- **Analyzing data** and summarizing information\n\nWhat would you like to explore?",
+        },
+      ],
+    },
+    {
+      role: 'user',
+      content: [{ type: 'text', text: 'Tell me about the Speakeasy SDK.' }],
+    },
+    {
+      role: 'assistant',
+      content: [
+        {
+          type: 'text',
+          text: 'Speakeasy generates **type-safe, idiomatic SDKs** from your OpenAPI spec. You get production-ready client libraries in TypeScript, Python, Go, and more — complete with authentication, pagination, and retries built in.\n\nThe generated SDKs stay in sync with your API automatically through CI/CD integration, so your users always have an up-to-date client library. No more hand-writing API wrappers!',
+        },
+      ],
+    },
+  ],
+}
+
+const toolCallCassette: Cassette = {
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: "What's the weather like in San Francisco?" },
+      ],
+    },
+    {
+      role: 'assistant',
+      content: [
+        {
+          type: 'text',
+          text: 'Let me check the current weather in San Francisco for you.',
+        },
+        {
+          type: 'tool-call',
+          toolCallId: 'tc_weather_1',
+          toolName: 'getWeather',
+          args: { city: 'San Francisco', units: 'fahrenheit' },
+          result: {
+            temperature: 68,
+            conditions: 'Partly cloudy',
+            humidity: 72,
+            wind: '12 mph NW',
+          },
+        },
+        {
+          type: 'text',
+          text: "It's currently **68°F** in San Francisco with partly cloudy skies. The humidity is at 72% with northwest winds at 12 mph. A beautiful day to be outside!",
+        },
+      ],
+    },
+    {
+      role: 'user',
+      content: [{ type: 'text', text: 'How about New York?' }],
+    },
+    {
+      role: 'assistant',
+      content: [
+        {
+          type: 'tool-call',
+          toolCallId: 'tc_weather_2',
+          toolName: 'getWeather',
+          args: { city: 'New York', units: 'fahrenheit' },
+          result: {
+            temperature: 45,
+            conditions: 'Rainy',
+            humidity: 89,
+            wind: '8 mph E',
+          },
+        },
+        {
+          type: 'text',
+          text: "New York is quite different — it's **45°F** and rainy with high humidity at 89%. You'd want an umbrella and a warm coat today!",
+        },
+      ],
+    },
+  ],
+}
+
+const reasoningCassette: Cassette = {
+  messages: [
+    {
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: 'If I have 3 boxes, each containing 2 red balls and 1 blue ball, what is the probability of drawing a red ball from each box?',
+        },
+      ],
+    },
+    {
+      role: 'assistant',
+      content: [
+        {
+          type: 'reasoning',
+          text: 'The user wants to find the probability of drawing a red ball from each of the 3 boxes.\n\nEach box has 3 balls total: 2 red and 1 blue.\nProbability of red from one box = 2/3.\nSince the draws are independent, I multiply the probabilities:\nP(all red) = (2/3) × (2/3) × (2/3) = 8/27 ≈ 0.296',
+        },
+        {
+          type: 'text',
+          text: "Each box contains 3 balls (2 red, 1 blue), so the probability of drawing red from a single box is **2/3**.\n\nSince you're drawing independently from each box, you multiply the probabilities:\n\n$$P(\\text{all red}) = \\frac{2}{3} \\times \\frac{2}{3} \\times \\frac{2}{3} = \\frac{8}{27} \\approx 29.6\\%$$\n\nSo there's roughly a **29.6% chance** of drawing a red ball from every box.",
+        },
+      ],
+    },
+  ],
+}
+
+const multiTurnCassette: Cassette = {
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'Help me plan a REST API for a todo app.' },
+      ],
+    },
+    {
+      role: 'assistant',
+      content: [
+        {
+          type: 'text',
+          text: "Here's a clean REST API design for a todo app:\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/todos` | List all todos |\n| `POST` | `/todos` | Create a new todo |\n| `GET` | `/todos/:id` | Get a single todo |\n| `PATCH` | `/todos/:id` | Update a todo |\n| `DELETE` | `/todos/:id` | Delete a todo |\n\nWant me to define the request/response schemas?",
+        },
+      ],
+    },
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'Yes, show me the schema for creating a todo.' },
+      ],
+    },
+    {
+      role: 'assistant',
+      content: [
+        {
+          type: 'text',
+          text: '**POST `/todos`**\n\n**Request body:**\n```json\n{\n  "title": "Buy groceries",\n  "description": "Milk, eggs, bread",\n  "dueDate": "2025-03-15T10:00:00Z",\n  "priority": "medium"\n}\n```\n\n**Response (`201 Created`):**\n```json\n{\n  "id": "td_abc123",\n  "title": "Buy groceries",\n  "description": "Milk, eggs, bread",\n  "completed": false,\n  "dueDate": "2025-03-15T10:00:00Z",\n  "priority": "medium",\n  "createdAt": "2025-03-10T14:30:00Z",\n  "updatedAt": "2025-03-10T14:30:00Z"\n}\n```\n\nThe `title` field is required — everything else is optional. The server generates `id`, `completed` (defaults to `false`), and timestamps.',
+        },
+      ],
+    },
+    {
+      role: 'user',
+      content: [{ type: 'text', text: 'What about validation errors?' }],
+    },
+    {
+      role: 'assistant',
+      content: [
+        {
+          type: 'text',
+          text: 'For validation errors, return `422 Unprocessable Entity` with a structured error body:\n\n```json\n{\n  "error": "validation_error",\n  "message": "Request validation failed",\n  "details": [\n    {\n      "field": "title",\n      "message": "Title is required and must be between 1-200 characters"\n    },\n    {\n      "field": "priority",\n      "message": "Must be one of: low, medium, high"\n    }\n  ]\n}\n```\n\nThis gives clients enough information to display field-level errors in the UI. Keep the `details` array consistent across all endpoints.',
+        },
+      ],
+    },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+/**
+ * Basic text conversation replay. Messages stream in character-by-character
+ * with a typing effect, just like a real chat session.
+ */
+export const TextConversation: Story = () => (
+  <Replay
+    cassette={textOnlyCassette}
+    config={{ variant: 'standalone' }}
+    typingSpeed={10}
+    userMessageDelay={600}
+  >
+    <Chat />
+  </Replay>
+)
+TextConversation.decorators = [
+  (Story) => (
+    <div className="m-auto flex h-screen w-full max-w-3xl flex-col px-4">
+      <Story />
+    </div>
+  ),
+]
+
+/**
+ * Replay with tool calls. The assistant invokes tools with visible
+ * arguments and results, demonstrating the tool call rendering pipeline.
+ */
+export const ToolCalls: Story = () => (
+  <Replay
+    cassette={toolCallCassette}
+    config={{
+      variant: 'standalone',
+      tools: { expandToolGroupsByDefault: true },
+    }}
+    typingSpeed={10}
+    userMessageDelay={600}
+  >
+    <Chat />
+  </Replay>
+)
+ToolCalls.decorators = [
+  (Story) => (
+    <div className="m-auto flex h-screen w-full max-w-3xl flex-col px-4">
+      <Story />
+    </div>
+  ),
+]
+
+/**
+ * Replay with reasoning (chain-of-thought) content. The assistant's
+ * internal reasoning is shown before the final response.
+ */
+export const Reasoning: Story = () => (
+  <Replay
+    cassette={reasoningCassette}
+    config={{ variant: 'standalone' }}
+    typingSpeed={10}
+    userMessageDelay={600}
+  >
+    <Chat />
+  </Replay>
+)
+Reasoning.decorators = [
+  (Story) => (
+    <div className="m-auto flex h-screen w-full max-w-3xl flex-col px-4">
+      <Story />
+    </div>
+  ),
+]
+
+/**
+ * Multi-turn conversation with multiple user/assistant exchanges,
+ * demonstrating extended conversations with rich markdown formatting.
+ */
+export const MultiTurn: Story = () => (
+  <Replay
+    cassette={multiTurnCassette}
+    config={{ variant: 'standalone' }}
+    typingSpeed={8}
+    userMessageDelay={500}
+    assistantStartDelay={300}
+  >
+    <Chat />
+  </Replay>
+)
+MultiTurn.decorators = [
+  (Story) => (
+    <div className="m-auto flex h-screen w-full max-w-3xl flex-col px-4">
+      <Story />
+    </div>
+  ),
+]
+
+/**
+ * Replay rendered in the widget (modal) variant, showing how replays
+ * work inside a modal container.
+ */
+export const WidgetVariant: Story = () => (
+  <Replay
+    cassette={textOnlyCassette}
+    config={{
+      variant: 'widget',
+      modal: { defaultOpen: true },
+    }}
+    typingSpeed={10}
+    userMessageDelay={600}
+  >
+    <Chat />
+  </Replay>
+)
+
+/**
+ * Fast replay with minimal delays — useful for quick demos or testing.
+ */
+export const FastReplay: Story = () => (
+  <Replay
+    cassette={multiTurnCassette}
+    config={{ variant: 'standalone' }}
+    typingSpeed={2}
+    userMessageDelay={200}
+    assistantStartDelay={100}
+  >
+    <Chat />
+  </Replay>
+)
+FastReplay.decorators = [
+  (Story) => (
+    <div className="m-auto flex h-screen w-full max-w-3xl flex-col px-4">
+      <Story />
+    </div>
+  ),
+]