@gram-ai/elements 1.16.5 → 1.18.0

package/README.md

@@ -4,13 +4,6 @@ Elements is a library built for the agentic age. We provide customizable and ele
 
 ## Setup
 
-### Package Exports
-
-This package provides two separate exports with different dependencies:
-
-- **`@gram-ai/elements`** - React UI components (requires React and related dependencies)
-- **`@gram-ai/elements/server`** - Server-side handlers (does NOT require React)
-
 ### Frontend Setup
 
 First ensure that you have installed the required peer dependencies:
@@ -48,7 +41,16 @@ const app = express()
 
 app.use(express.json())
 
-app.post('/chat/completions', handlers.chat)
+app.post('/chat/session', (req, res) =>
+  handlers.session(req, res, {
+    // The origin from which the token will be used
+    embedOrigin: 'http://localhost:3000',
+    // A free-form user identifier
+    userIdentifier: 'user-123',
+    // Token expiration in seconds (max / default 3600)
+    expiresAfter: 3600,
+  })
+)
 ```
 
 You will need to add an environment variable to your backend and make it available to the process:
@@ -71,8 +73,6 @@ import '@gram-ai/elements/elements.css'
 const config: ElementsConfig = {
   projectSlug: 'xxx',
   mcp: 'https://app.getgram.ai/mcp/{your_slug}',
-  // Points to your backend endpoint
-  chatEndpoint: '/chat/completions',
   variant: 'widget',
   welcome: {
     title: 'Hello!',
@@ -95,6 +95,37 @@ export const App = () => {
 }
 ```
 
+### Custom Session Endpoint
+
+By default, Elements expects the session endpoint on your backend to be located at `/chat/session`. If you've mounted your session endpoint at a different path, you can provide a custom `getSession` function in the `ElementsProvider`:
+
+```jsx
+import { GramElementsProvider, Chat, type ElementsConfig, type GetSessionFn } from '@gram-ai/elements'
+import '@gram-ai/elements/elements.css'
+
+const config: ElementsConfig = {
+  projectSlug: 'xxx',
+  mcp: 'https://app.getgram.ai/mcp/{your_slug}',
+  // ... other config
+}
+
+const customGetSession: GetSessionFn = async () => {
+  const response = await fetch('/api/custom-session-endpoint', {
+    method: 'POST',
+  })
+  const data = await response.json()
+  return data.client_token
+}
+
+export const App = () => {
+  return (
+    <GramElementsProvider config={config} getSession={customGetSession}>
+      <Chat />
+    </GramElementsProvider>
+  )
+}
+```
+
 ## Configuration
 
 For complete configuration options and TypeScript type definitions, see the [API documentation](./docs/interfaces/ElementsConfig.md).
@@ -108,7 +139,6 @@ import '@gram-ai/elements/elements.css'
 const config: ElementsConfig = {
   projectSlug: 'your-project',
   mcp: 'https://app.getgram.ai/mcp/your-mcp-slug',
-  chatEndpoint: '/chat/completions',
   variant: 'widget', // 'widget' | 'sidecar' | 'standalone'
   welcome: {
     title: 'Hello!',

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

@@ -0,0 +1,42 @@
+import { Chat } from '.';
+import { Meta, StoryFn } from '@storybook/react-vite';
+import { ColorScheme, Density, Radius, Variant } from '../../types';
+declare const meta: Meta<typeof Chat>;
+export default meta;
+type Story = StoryFn<typeof Chat>;
+export declare const Default: Story;
+interface PlaygroundArgs {
+    colorScheme: ColorScheme;
+    density: Density;
+    radius: Radius;
+    variant: Variant;
+    greeting: string;
+    subtitle: string;
+    starterPrompts: 'none' | 'some' | 'many';
+    placeholder: string;
+    attachments: boolean;
+    headerTitle: string;
+}
+export declare const ThemePlayground: StoryFn<PlaygroundArgs>;
+export declare const VariantPlayground: Story;
+export declare const Standalone: Story;
+export declare const Sidecar: Story;
+export declare const WithCustomModalIcon: Story;
+export declare const WithCustomComposerPlaceholder: Story;
+export declare const WithAttachmentsDisabled: Story;
+export declare const WithCustomWelcomeMessage: Story;
+export declare const WithCustomTools: Story;
+export declare const WithModelPicker: Story;
+export declare const WithExpandableModal: Story;
+export declare const WithCustomModalTriggerPositionTopRight: Story;
+export declare const WithCustomModalTriggerPositionBottomRight: Story;
+export declare const WithCustomModalTriggerPositionBottomLeft: Story;
+export declare const WithCustomModalTriggerPositionTopLeft: Story;
+export declare const WithCustomSystemPrompt: Story;
+export declare const WithChartPlugin: Story;
+export declare const WithCustomComponentOverrides: Story;
+export declare const WithFrontendTools: Story;
+export declare const WithCustomLanguageModel: Story;
+export declare const WithToolsRequiringApproval: Story;
+export declare const WithMultipleGroupedToolsRequiringApproval: Story;
+export declare const WithFrontendToolRequiringApproval: Story;

package/dist/components/assistant-ui/tooltip-icon-button.d.ts

@@ -1,8 +1,9 @@
 import { ComponentPropsWithRef } from 'react';
 import { Button } from '../ui/button';
-export type TooltipIconButtonProps = ComponentPropsWithRef<typeof Button> & {
+type TooltipIconButtonProps = ComponentPropsWithRef<typeof Button> & {
     tooltip: string;
     side?: 'top' | 'bottom' | 'left' | 'right';
     align?: 'start' | 'center' | 'end';
 };
 export declare const TooltipIconButton: import('react').ForwardRefExoticComponent<Omit<TooltipIconButtonProps, "ref"> & import('react').RefAttributes<HTMLButtonElement>>;
+export {};

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

@@ -1,5 +1,19 @@
+import { BundledLanguage } from 'shiki';
 import * as React from 'react';
-type ToolStatus = 'pending' | 'running' | 'complete' | 'error';
+type ToolStatus = 'pending' | 'running' | 'complete' | 'error' | 'approval';
+type ContentItem = {
+    type: 'text';
+    text: string;
+    _meta?: {
+        'getgram.ai/mime-type'?: string;
+    };
+} | {
+    type: 'image';
+    data: string;
+    _meta?: {
+        'getgram.ai/mime-type'?: string;
+    };
+};
 interface ToolUIProps {
     /** Display name of the tool */
     name: string;
@@ -11,22 +25,60 @@ interface ToolUIProps {
     status?: ToolStatus;
     /** Request/input data - can be string or object */
     request?: string | Record<string, unknown>;
-    /** Result/output data - can be string or object */
-    result?: string | Record<string, unknown>;
+    /** Result/output data - can be string, object, or structured content array */
+    result?: string | Record<string, unknown> | {
+        content: ContentItem[];
+    };
     /** Whether the tool card starts expanded */
     defaultExpanded?: boolean;
     /** Additional class names */
     className?: string;
+    /** Approval callbacks */
+    onApproveOnce?: () => void;
+    onApproveForSession?: () => void;
+    onDeny?: () => void;
 }
 interface ToolUISectionProps {
     /** Section title */
     title: string;
     /** Content to display - string or object (will be JSON stringified) */
-    content: string | Record<string, unknown>;
+    content: string | Record<string, unknown> | {
+        content: ContentItem[];
+    };
     /** Whether section starts expanded */
     defaultExpanded?: boolean;
+    /** Enable syntax highlighting */
+    highlightSyntax?: boolean;
+    /** Language hint for syntax highlighting */
+    language?: BundledLanguage;
 }
-declare function ToolUISection({ title, content, defaultExpanded, }: ToolUISectionProps): import("react/jsx-runtime").JSX.Element;
-declare function ToolUI({ name, icon, provider, status, request, result, defaultExpanded, className, }: ToolUIProps): import("react/jsx-runtime").JSX.Element;
-export { ToolUI, ToolUISection };
-export type { ToolUIProps, ToolUISectionProps, ToolStatus };
+declare function StatusIndicator({ status }: {
+    status: ToolStatus;
+}): import("react/jsx-runtime").JSX.Element;
+declare function CopyButton({ content }: {
+    content: string;
+}): import("react/jsx-runtime").JSX.Element;
+declare function SyntaxHighlightedCode({ text, language, className, }: {
+    text: string;
+    language?: BundledLanguage;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+declare function ToolUISection({ title, content, defaultExpanded, highlightSyntax, language, }: ToolUISectionProps): import("react/jsx-runtime").JSX.Element;
+declare function ToolUI({ name, icon, provider, status, request, result, defaultExpanded, className, onApproveOnce, onApproveForSession, onDeny, }: ToolUIProps): import("react/jsx-runtime").JSX.Element;
+interface ToolUIGroupProps {
+    /** Title for the group header */
+    title: string;
+    /** Optional icon */
+    icon?: React.ReactNode;
+    /** Overall status of the group */
+    status?: 'running' | 'complete';
+    /** Whether the group starts expanded */
+    defaultExpanded?: boolean;
+    /** Child tool UI components */
+    children: React.ReactNode;
+    /** Additional class names */
+    className?: string;
+}
+declare function ToolUIGroup({ title, icon, status, defaultExpanded, children, className, }: ToolUIGroupProps): import("react/jsx-runtime").JSX.Element;
+export { ToolUI, ToolUISection, ToolUIGroup, SyntaxHighlightedCode, StatusIndicator, CopyButton, };
+export type { ToolUIProps, ToolUISectionProps, ToolUIGroupProps, ToolStatus, ContentItem, };

package/dist/components/ui/tool-ui.stories.d.ts

@@ -0,0 +1,14 @@
+import { Meta, StoryFn } from '@storybook/react-vite';
+import { ToolUI } from './tool-ui';
+declare const meta: Meta<typeof ToolUI>;
+export default meta;
+type Story = StoryFn<typeof ToolUI>;
+export declare const Complete: Story;
+export declare const Running: Story;
+export declare const Pending: Story;
+export declare const Error: Story;
+export declare const WithoutProvider: Story;
+export declare const WithCustomIcon: Story;
+export declare const DefaultExpanded: Story;
+export declare const LongContent: Story;
+export declare const MultipleTools: Story;

package/dist/contexts/ToolApprovalContext.d.ts

@@ -0,0 +1,24 @@
+import { ReactNode } from 'react';
+interface PendingApproval {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    resolve: (approved: boolean) => void;
+}
+interface ToolApprovalContextType {
+    pendingApprovals: Map<string, PendingApproval>;
+    approvedTools: Set<string>;
+    requestApproval: (toolName: string, toolCallId: string, args: unknown) => Promise<boolean>;
+    /** Whitelist a tool name so all future calls are auto-approved */
+    whitelistTool: (toolName: string) => void;
+    /** Confirm a specific pending tool call approval */
+    confirmPendingApproval: (toolCallId: string) => void;
+    /** Reject a specific pending tool call approval */
+    rejectPendingApproval: (toolCallId: string) => void;
+    isToolApproved: (toolName: string) => boolean;
+    getPendingApproval: (toolCallId: string) => PendingApproval | undefined;
+}
+export declare function ToolApprovalProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export type { ToolApprovalContextType };

package/dist/contexts/contexts.d.ts

@@ -0,0 +1,4 @@
+import { ElementsContextType } from '../types';
+import { ToolApprovalContextType } from './ToolApprovalContext';
+export declare const ElementsContext: import('react').Context<ElementsContextType | undefined>;
+export declare const ToolApprovalContext: import('react').Context<ToolApprovalContextType | null>;