@gram-ai/elements 1.8.3 → 1.9.0

package/dist/hooks/useDensity.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Density class mappings for different UI elements
+ */
+declare const densityClasses: {
+    readonly compact: {
+        readonly 'p-sm': "p-1";
+        readonly 'p-md': "p-2";
+        readonly 'p-lg': "p-3";
+        readonly 'p-xl': "p-4";
+        readonly 'px-sm': "px-2";
+        readonly 'px-md': "px-3";
+        readonly 'px-lg': "px-4";
+        readonly 'px-xl': "px-5";
+        readonly 'py-sm': "py-1";
+        readonly 'py-md': "py-1.5";
+        readonly 'py-lg': "py-2";
+        readonly 'py-xl': "py-3";
+        readonly 'gap-sm': "gap-1";
+        readonly 'gap-md': "gap-2";
+        readonly 'gap-lg': "gap-3";
+        readonly 'gap-xl': "gap-4";
+        readonly 'h-header': "h-10";
+        readonly 'h-input': "min-h-12";
+        readonly 'text-base': "text-sm";
+        readonly 'text-title': "text-xl";
+        readonly 'text-subtitle': "text-sm";
+    };
+    readonly normal: {
+        readonly 'p-sm': "p-2";
+        readonly 'p-md': "p-4";
+        readonly 'p-lg': "p-6";
+        readonly 'p-xl': "p-8";
+        readonly 'px-sm': "px-3";
+        readonly 'px-md': "px-4";
+        readonly 'px-lg': "px-6";
+        readonly 'px-xl': "px-8";
+        readonly 'py-sm': "py-1.5";
+        readonly 'py-md': "py-2.5";
+        readonly 'py-lg': "py-5";
+        readonly 'py-xl': "py-8";
+        readonly 'gap-sm': "gap-1";
+        readonly 'gap-md': "gap-2";
+        readonly 'gap-lg': "gap-3";
+        readonly 'gap-xl': "gap-5";
+        readonly 'h-header': "h-12";
+        readonly 'h-input': "min-h-16";
+        readonly 'text-base': "text-base";
+        readonly 'text-title': "text-2xl";
+        readonly 'text-subtitle': "text-base";
+    };
+    readonly spacious: {
+        readonly 'p-sm': "p-3";
+        readonly 'p-md': "p-6";
+        readonly 'p-lg': "p-8";
+        readonly 'p-xl': "p-10";
+        readonly 'px-sm': "px-4";
+        readonly 'px-md': "px-6";
+        readonly 'px-lg': "px-8";
+        readonly 'px-xl': "px-10";
+        readonly 'py-sm': "py-2";
+        readonly 'py-md': "py-4";
+        readonly 'py-lg': "py-6";
+        readonly 'py-xl': "py-10";
+        readonly 'gap-sm': "gap-2";
+        readonly 'gap-md': "gap-3";
+        readonly 'gap-lg': "gap-4";
+        readonly 'gap-xl': "gap-6";
+        readonly 'h-header': "h-14";
+        readonly 'h-input': "min-h-20";
+        readonly 'text-base': "text-lg";
+        readonly 'text-title': "text-3xl";
+        readonly 'text-subtitle': "text-lg";
+    };
+};
+type DensityToken = keyof (typeof densityClasses)['normal'];
+/**
+ * Hook to get density classes based on theme config
+ * Use: const d = useDensity(); then d('p-md') returns the appropriate padding class
+ */
+export declare const useDensity: () => (token: DensityToken) => "p-1" | "p-2" | "p-3" | "p-4" | "px-2" | "px-3" | "px-4" | "px-5" | "py-1" | "py-1.5" | "py-2" | "py-3" | "gap-1" | "gap-2" | "gap-3" | "gap-4" | "h-10" | "min-h-12" | "text-sm" | "text-xl" | "p-6" | "p-8" | "px-6" | "px-8" | "py-2.5" | "py-5" | "py-8" | "gap-5" | "h-12" | "min-h-16" | "text-base" | "text-2xl" | "p-10" | "px-10" | "py-4" | "py-6" | "py-10" | "gap-6" | "h-14" | "min-h-20" | "text-lg" | "text-3xl";
+export {};

package/dist/hooks/useExpanded.d.ts

@@ -0,0 +1,8 @@
+import { Dispatch, SetStateAction } from 'react';
+interface UseExpandedAPI {
+    expandable: boolean;
+    isExpanded: boolean;
+    setIsExpanded: Dispatch<SetStateAction<boolean>>;
+}
+export declare const useExpanded: () => UseExpandedAPI;
+export {};

package/dist/hooks/useRadius.d.ts

@@ -0,0 +1,7 @@
+type RadiusSize = 'sm' | 'md' | 'lg' | 'xl' | 'full';
+/**
+ * Hook to get radius classes based on theme config
+ * Use: const r = useRadius(); then r('lg') returns the appropriate rounded class
+ */
+export declare const useRadius: () => (size: RadiusSize) => string;
+export {};

package/dist/hooks/useThemeProps.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Hook to get theme-related props including dark mode class
+ */
+export declare const useThemeProps: () => {
+    readonly className: "dark" | undefined;
+};

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { ElementsProvider as GramElementsProvider } from './contexts/ElementsProvider';
 export { useElements as useGramElements } from './hooks/useElements';
 export { Chat } from './components/Chat';
-export type { ElementsConfig, ComposerConfig, ModalConfig, ToolsConfig, ModelConfig, WelcomeConfig, Suggestion, Model, ModalTriggerPosition, } from './types';
+export { ToolUI, ToolUISection } from './components/ui/tool-ui';
+export type { ToolUIProps, ToolUISectionProps, ToolStatus, } from './components/ui/tool-ui';
+export type { ElementsConfig, ComposerConfig, AttachmentsConfig, ModalConfig, SidecarConfig, ToolsConfig, ModelConfig, ThemeConfig, WelcomeConfig, Suggestion, Model, ModalTriggerPosition, } from './types';

package/dist/lib/easing.d.ts

@@ -0,0 +1 @@
+export declare const EASE_OUT_QUINT: readonly [0.23, 1, 0.32, 1];

package/dist/lib/utils.d.ts

@@ -1,2 +1,3 @@
 import { ClassValue } from 'clsx';
 export declare function cn(...inputs: ClassValue[]): string;
+export declare function assertNever(value: unknown): never;

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 import { MODELS } from '../lib/models';
 import { ToolCallMessagePartComponent } from '@assistant-ui/react';
-import { ReactNode } from 'react';
+import { Dispatch, SetStateAction, ReactNode } from 'react';
 import { z } from 'zod';
 export interface ElementsProviderProps {
     /**
@@ -13,6 +13,8 @@ export interface ElementsProviderProps {
     config: ElementsConfig;
 }
 type ServerUrl = string;
+export declare const VARIANTS: readonly ["widget", "sidecar", "standalone"];
+export type Variant = (typeof VARIANTS)[number];
 export interface ElementsConfig {
     /**
      * The system prompt to use for the Elements library.
@@ -46,9 +48,15 @@ export interface ElementsConfig {
      */
     environment?: Record<string, unknown>;
     /**
-     * Whether to render the chat window inside of an expandable modal or a standalone chat window.
+     * The layout variant for the chat interface.
+     *
+     * - `widget`: A popup modal anchored to the bottom-right corner (default)
+     * - `sidecar`: A side panel that slides in from the right edge of the screen
+     * - `standalone`: A full-page chat experience
+     *
+     * @default 'widget'
      */
-    variant?: 'widget' | 'standalone';
+    variant?: Variant;
     /**
      * LLM model configuration.
      *
@@ -62,11 +70,10 @@ export interface ElementsConfig {
      */
     model?: ModelConfig;
     /**
-     * The theme to use for the Elements library.
-     *
-     * TODO: Not yet implemented
+     * Visual appearance configuration options.
+     * Similar to OpenAI ChatKit's ThemeOption.
      */
-    theme?: 'light' | 'dark' | 'system';
+    theme?: ThemeConfig;
     /**
      * The configuration for the welcome message and initial suggestions.
      */
@@ -80,6 +87,11 @@ export interface ElementsConfig {
      * Does not apply if variant is 'standalone'.
      */
     modal?: ModalConfig;
+    /**
+     * The configuration for the sidecar panel.
+     * Only applies if variant is 'sidecar'.
+     */
+    sidecar?: SidecarConfig;
     /**
      * The configuration for the tools.
      */
@@ -100,6 +112,48 @@ export interface ModelConfig {
      */
     defaultModel?: Model;
 }
+export declare const DENSITIES: readonly ["compact", "normal", "spacious"];
+export type Density = (typeof DENSITIES)[number];
+export declare const COLOR_SCHEMES: readonly ["light", "dark", "system"];
+export type ColorScheme = (typeof COLOR_SCHEMES)[number];
+export declare const RADII: readonly ["round", "soft", "sharp"];
+export type Radius = (typeof RADII)[number];
+/**
+ * ThemeConfig provides visual appearance customization options.
+ * Inspired by OpenAI ChatKit's ThemeOption.
+ *
+ * @example
+ * const config: ElementsConfig = {
+ *   theme: {
+ *     colorScheme: 'dark',
+ *     density: 'compact',
+ *     radius: 'round',
+ *   },
+ * }
+ */
+export interface ThemeConfig {
+    /**
+     * The color scheme to use for the UI.
+     * @default 'light'
+     */
+    colorScheme?: ColorScheme;
+    /**
+     * Determines the overall spacing of the UI.
+     * - `compact`: Reduced padding and margins for dense layouts
+     * - `normal`: Standard spacing (default)
+     * - `spacious`: Increased padding and margins for airy layouts
+     * @default 'normal'
+     */
+    density?: Density;
+    /**
+     * Determines the overall roundness of the UI.
+     * - `round`: Large border radius
+     * - `soft`: Moderate border radius (default)
+     * - `sharp`: Minimal border radius
+     * @default 'soft'
+     */
+    radius?: Radius;
+}
 /**
  * ToolsConfig is used to configure tool support in the Elements library.
  * At the moment, you can override the default React components used by
@@ -162,6 +216,11 @@ export interface ModalConfig {
      * Whether to open the modal window by default.
      */
     defaultOpen?: boolean;
+    /**
+     * The title displayed in the modal header.
+     * @default 'Chat'
+     */
+    title?: string;
     /**
      * The position of the modal trigger
      *
@@ -194,21 +253,72 @@ export interface ModalConfig {
 export interface ComposerConfig {
     /**
      * The placeholder text for the composer input.
+     * @default 'Send a message...'
      */
-    placeholder: string;
+    placeholder?: string;
     /**
-     * Whether to enable attachments in the composer.
-     *
-     * NOTE: Not yet implemented
+     * Configuration for file attachments in the composer.
+     * Set to `false` to disable attachments entirely.
+     * Set to `true` for default attachment behavior.
+     * Or provide an object for fine-grained control.
+     * @default true
+     */
+    attachments?: boolean | AttachmentsConfig;
+}
+/**
+ * AttachmentsConfig provides fine-grained control over file attachments.
+ * Inspired by OpenAI ChatKit's attachment options.
+ */
+export interface AttachmentsConfig {
+    /**
+     * Accepted file types. Can be MIME types or file extensions.
+     * @example ['image/*', '.pdf', '.docx']
+     */
+    accept?: string[];
+    /**
+     * Maximum number of files that can be attached at once.
+     * @default 10
+     */
+    maxCount?: number;
+    /**
+     * Maximum file size in bytes.
+     * @default 104857600 (100MB)
+     */
+    maxSize?: number;
+}
+export interface SidecarConfig {
+    /**
+     * The title displayed in the sidecar header.
+     * @default 'Chat'
+     */
+    title?: string;
+    /**
+     * The width of the sidecar panel.
+     * @default '400px'
+     */
+    width?: string | number | `${number}%`;
+    /**
+     * The width of the sidecar panel when expanded.
+     * @default '800px'
+     */
+    expandedWidth?: string | number | `${number}%`;
+    /**
+     * Callback when the pop-out button is clicked.
+     * If provided, the pop-out button will be shown.
+     */
+    onPopOut?: () => void;
+    /**
+     * Callback when the collapse button is clicked.
+     * If provided, the collapse button will be shown.
      */
-    attachments: boolean;
+    onCollapse?: () => void;
 }
 export type ElementsContextType = {
     config: ElementsConfig;
     setModel: (model: Model) => void;
     model: Model;
     isExpanded: boolean;
-    setIsExpanded: (isExpanded: boolean) => void;
+    setIsExpanded: Dispatch<SetStateAction<boolean>>;
     isOpen: boolean;
     setIsOpen: (isOpen: boolean) => void;
 };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@gram-ai/elements",
   "description": "Gram Elements is a library of UI primitives for building chat-like experiences for MCP Servers.",
   "type": "module",
-  "version": "1.8.3",
+  "version": "1.9.0",
   "main": "dist/index.js",
   "exports": {
     ".": {