@gram-ai/elements 1.22.5 → 1.24.0

package/README.md

@@ -263,6 +263,67 @@ To create your own plugins, see the comprehensive [Plugin Development Guide](./s
 - Real-world examples
 - Troubleshooting tips
 
+## Replay
+
+Replay lets you play back a pre-recorded conversation with streaming animations — no auth, MCP, or network calls required. This is useful for marketing demos, documentation, and testing.
+
+### Recording a cassette
+
+A cassette is a JSON file that captures a conversation. To record one from a live chat session, enable the built-in recorder by setting this environment variable:
+
+```
+VITE_ELEMENTS_ENABLE_CASSETTE_RECORDING=true
+```
+
+This adds a record button to the composer. Click it to open the recorder popover, then start recording. Chat normally, and when you're done, click **Stop & Download** to save the cassette as a `.cassette.json` file.
+
+You can also record programmatically using the `useRecordCassette` hook:
+
+```tsx
+import {
+  GramElementsProvider,
+  Chat,
+  useRecordCassette,
+} from '@gram-ai/elements'
+
+function RecordableChat() {
+  const { isRecording, startRecording, download } = useRecordCassette()
+  return (
+    <>
+      <Chat />
+      <button onClick={startRecording}>Record</button>
+      <button onClick={() => download('demo')}>Save</button>
+    </>
+  )
+}
+```
+
+### Playing back a cassette
+
+Use the `<Replay>` component, which replaces `GramElementsProvider` entirely:
+
+```tsx
+import { Replay, Chat } from '@gram-ai/elements'
+import cassette from './demo.cassette.json'
+
+function MarketingDemo() {
+  return (
+    <Replay cassette={cassette} config={{ variant: 'standalone' }}>
+      <Chat />
+    </Replay>
+  )
+}
+```
+
+`<Replay>` accepts optional timing props to control the playback speed:
+
+| Prop                  | Default | Description                                     |
+| --------------------- | ------- | ----------------------------------------------- |
+| `typingSpeed`         | `15`    | Milliseconds per character for streaming        |
+| `userMessageDelay`    | `800`   | Milliseconds before each user message appears   |
+| `assistantStartDelay` | `400`   | Milliseconds before the assistant starts typing |
+| `onComplete`          | —       | Callback when replay finishes                   |
+
 ## Contributing
 
 We welcome pull requests to Elements. Please read the contributing guide.

package/dist/components/Chat/stories/MessageFeedback.stories.d.ts

@@ -0,0 +1,28 @@
+import { Chat } from '..';
+import { Meta, StoryFn } from '@storybook/react-vite';
+declare const meta: Meta<typeof Chat>;
+export default meta;
+type Story = StoryFn<typeof Chat>;
+/**
+ * The feedback buttons appear on the last assistant message after it finishes streaming.
+ * Send a message to see the feedback UI animate in.
+ */
+export declare const Default: Story;
+/**
+ * Widget variant with feedback buttons.
+ */
+export declare const Widget: Story;
+/**
+ * Sidecar variant with feedback buttons.
+ */
+export declare const Sidecar: Story;
+/**
+ * Demonstrates feedback UI combined with follow-up suggestions.
+ * After the assistant responds, you'll see both AI-generated follow-up questions
+ * and feedback buttons (like/dislike) to mark the conversation as resolved.
+ */
+export declare const WithFollowUpSuggestions: Story;
+/**
+ * Standalone component demo showing the feedback buttons in isolation.
+ */
+export declare const ComponentOnly: StoryFn;

package/dist/components/Chat/stories/Plugins.stories.d.ts

@@ -4,3 +4,9 @@ declare const meta: Meta<typeof Chat>;
 export default meta;
 type Story = StoryFn<typeof Chat>;
 export declare const ChartPlugin: Story;
+export declare const GenerativeUI: Story;
+/**
+ * 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 declare const GenerativeUIWithActions: Story;

package/dist/components/Chat/stories/Thread.stories.d.ts

@@ -0,0 +1,15 @@
+import { Meta, StoryFn } from '@storybook/react-vite';
+import { Chat } from '..';
+declare const meta: 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 declare const FollowUpSuggestions: Story;
+/**
+ * Shows the thread with follow-up suggestions disabled.
+ * No suggestions will appear after the assistant responds.
+ */
+export declare const FollowUpSuggestionsDisabled: Story;

package/dist/components/Chat/stories/Tools.stories.d.ts

@@ -4,3 +4,18 @@ declare const meta: Meta<typeof Chat>;
 export default meta;
 type Story = StoryFn<typeof Chat>;
 export declare const CustomToolComponent: Story;
+/**
+ * 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 declare const GenerativeUI: Story;
+/**
+ * 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 declare const GenerativeUIWithActions: Story;

package/dist/components/Replay.d.ts

@@ -0,0 +1,11 @@
+import { Cassette, ReplayOptions } from '../lib/cassette';
+import { ElementsConfig } from '../types';
+import { ReactNode } from 'react';
+export interface ReplayProps extends ReplayOptions {
+    /** The recorded cassette to replay. */
+    cassette: Cassette;
+    children: ReactNode;
+    /** Optional ElementsConfig for visual customization (theme, variant, etc.) */
+    config?: Partial<ElementsConfig>;
+}
+export declare const Replay: ({ cassette, children, config: partialConfig, typingSpeed, userMessageDelay, assistantStartDelay, onComplete, }: ReplayProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/Replay.stories.d.ts

@@ -0,0 +1,34 @@
+import { StoryFn } from '@storybook/react-vite';
+import { Replay } from './Replay';
+declare const meta: any;
+export default meta;
+type Story = StoryFn<typeof Replay>;
+/**
+ * Basic text conversation replay. Messages stream in character-by-character
+ * with a typing effect, just like a real chat session.
+ */
+export declare const TextConversation: Story;
+/**
+ * Replay with tool calls. The assistant invokes tools with visible
+ * arguments and results, demonstrating the tool call rendering pipeline.
+ */
+export declare const ToolCalls: Story;
+/**
+ * Replay with reasoning (chain-of-thought) content. The assistant's
+ * internal reasoning is shown before the final response.
+ */
+export declare const Reasoning: Story;
+/**
+ * Multi-turn conversation with multiple user/assistant exchanges,
+ * demonstrating extended conversations with rich markdown formatting.
+ */
+export declare const MultiTurn: Story;
+/**
+ * Replay rendered in the widget (modal) variant, showing how replays
+ * work inside a modal container.
+ */
+export declare const WidgetVariant: Story;
+/**
+ * Fast replay with minimal delays — useful for quick demos or testing.
+ */
+export declare const FastReplay: Story;

package/dist/components/assistant-ui/connection-status-indicator.d.ts

@@ -0,0 +1,16 @@
+import { FC } from 'react';
+interface ConnectionStatusIndicatorProps {
+    className?: string;
+}
+/**
+ * iOS-style floating island that appears when connection is lost.
+ * Shows "Reconnecting..." with a spinner, or "Connection Lost" after timeout.
+ */
+export declare const ConnectionStatusIndicator: FC<ConnectionStatusIndicatorProps>;
+/**
+ * Wrapper version that handles the case when ConnectionStatusProvider is not available.
+ * Uses useConnectionStatusOptional() which returns null instead of throwing,
+ * since try-catch around JSX won't catch hook errors (they throw during render phase).
+ */
+export declare const ConnectionStatusIndicatorSafe: FC<ConnectionStatusIndicatorProps>;
+export {};

package/dist/components/assistant-ui/follow-on-suggestions.d.ts

@@ -0,0 +1,6 @@
+import { FC } from 'react';
+/**
+ * Displays follow-on suggestions after the assistant finishes responding.
+ * These are dynamically generated based on the conversation context.
+ */
+export declare const FollowOnSuggestions: FC;

package/dist/components/assistant-ui/message-feedback.d.ts

@@ -0,0 +1,9 @@
+import { FC } from 'react';
+export type FeedbackType = 'dislike' | 'like';
+interface MessageFeedbackProps {
+    onFeedback?: (type: FeedbackType) => void;
+    onResolved?: () => void;
+    className?: string;
+}
+export declare const MessageFeedback: FC<MessageFeedbackProps>;
+export {};

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

@@ -1,7 +1,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?: "default" | "link" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
+    variant?: "default" | "link" | "secondary" | "outline" | "destructive" | "ghost" | null | undefined;
     size?: "default" | "icon" | "sm" | "lg" | "icon-sm" | "icon-lg" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string> & {
     asChild?: boolean;

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

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

package/dist/components/ui/generative-ui.d.ts

@@ -0,0 +1,13 @@
+import { FC } from 'react';
+interface GenerativeUIProps {
+    /** The JSON content to render - can be a json-render tree or raw object */
+    content: unknown;
+    /** Additional class names */
+    className?: string;
+}
+/**
+ * GenerativeUI component renders json-render compatible JSON as dynamic UI widgets.
+ * This is used by the generativeUI plugin to render `ui` code blocks.
+ */
+export declare const GenerativeUI: FC<GenerativeUIProps>;
+export type { GenerativeUIProps };

package/dist/contexts/ConnectionStatusContext.d.ts

@@ -0,0 +1,27 @@
+import { ReactNode } from 'react';
+export type ConnectionState = 'connected' | 'reconnecting' | 'disconnected';
+interface ConnectionStatusContextValue {
+    /** Current connection state */
+    state: ConnectionState;
+    /** Number of reconnection attempts */
+    retryCount: number;
+    /** Whether the browser reports being online */
+    isOnline: boolean;
+    /** Mark connection as failed - will trigger reconnecting state */
+    markDisconnected: () => void;
+    /** Mark connection as restored */
+    markConnected: () => void;
+    /** Reset the connection state */
+    reset: () => void;
+}
+interface ConnectionStatusProviderProps {
+    children: ReactNode;
+}
+export declare const ConnectionStatusProvider: ({ children, }: ConnectionStatusProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const useConnectionStatus: () => ConnectionStatusContextValue;
+/**
+ * Hook that returns connection status helpers for use in sendMessages.
+ * Returns null if not within a ConnectionStatusProvider (for backwards compatibility).
+ */
+export declare const useConnectionStatusOptional: () => ConnectionStatusContextValue | null;
+export {};

package/dist/contexts/ReplayContext.d.ts

@@ -0,0 +1,6 @@
+export declare const ReplayContext: import('react').Context<{
+    isReplay: boolean;
+} | null>;
+export declare function useReplayContext(): {
+    isReplay: boolean;
+} | null;

package/dist/contexts/ToolExecutionContext.d.ts

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+interface ExecutableTool {
+    execute?: (args: unknown, options?: unknown) => Promise<unknown>;
+}
+type ExecutableToolSet = Record<string, ExecutableTool | undefined>;
+export interface ToolExecutionResult {
+    success: boolean;
+    result?: unknown;
+    error?: string;
+}
+interface ToolExecutionContextValue {
+    executeTool: (toolName: string, args: Record<string, unknown>) => Promise<ToolExecutionResult>;
+    isToolAvailable: (toolName: string) => boolean;
+}
+interface ToolExecutionProviderProps {
+    children: ReactNode;
+    tools: ExecutableToolSet | undefined;
+}
+export declare function ToolExecutionProvider({ children, tools, }: ToolExecutionProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useToolExecution(): ToolExecutionContextValue;
+export {};

package/dist/elements.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-Dip7A_UI.cjs"),r=require("./index-CNVoovK7.cjs");exports.Chat=e.Chat;exports.ChatHistory=e.ChatHistory;exports.ElementsProvider=e.ElementsProvider;exports.GramElementsProvider=e.ElementsProvider;exports.MODELS=e.MODELS;exports.ShareButton=e.ShareButton;exports.defineFrontendTool=e.defineFrontendTool;exports.trackError=e.trackError;exports.useThreadId=e.useThreadId;exports.useElements=r.useElements;exports.useGramElements=r.useElements;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-Bps9R2k6.cjs"),r=require("./index-iUSSoKFz.cjs");exports.Chat=e.Chat;exports.ChatHistory=e.ChatHistory;exports.ElementsProvider=e.ElementsProvider;exports.GramElementsProvider=e.ElementsProvider;exports.MODELS=e.MODELS;exports.Replay=e.Replay;exports.ShareButton=e.ShareButton;exports.defineFrontendTool=e.defineFrontendTool;exports.trackError=e.trackError;exports.useRecordCassette=e.useRecordCassette;exports.useThreadId=e.useThreadId;exports.useElements=r.useElements;exports.useGramElements=r.useElements;
 //# sourceMappingURL=elements.cjs.map