@distri/react 0.2.7 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Agent as Agent$1, DistriChatMessage, DistriBaseTool, ToolExecutionOptions, DistriMessage, DistriPart, AgentDefinition, DistriThread, DistriFnTool, ToolCall, ToolResult, PlanStep, DistriConfiguration, DistriClientConfig, DistriClient, SpeechToTextConfig, StreamingTranscriptionOptions, ConfigurationMeta, ConfigurationResponse, DistriEvent, ImagePart } from '@distri/core';
+import { Agent as Agent$1, DistriChatMessage, DistriBaseTool, ToolExecutionOptions, DistriMessage, DistriPart, AgentDefinition, DistriThread, ThreadListParams, AgentUsageInfo, DistriFnTool, ToolCall, ToolResult, PlanStep, DistriConfiguration, DistriClient, DistriClientConfig, SpeechToTextConfig, StreamingTranscriptionOptions, ConfigurationMeta, ConfigurationResponse, DistriEvent, ImagePart } from '@distri/core';
 import * as React$1 from 'react';
 import React__default, { ReactNode } from 'react';
 import * as zustand from 'zustand';
@@ -13,7 +13,7 @@ import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
 
 interface UseChatOptions {
     threadId: string;
-    agent?: Agent$1;
+    agent: Agent$1 | null;
     onMessage?: (message: DistriChatMessage) => void;
     onError?: (error: Error) => void;
     getMetadata?: () => Promise<Record<string, unknown>>;
@@ -37,6 +37,7 @@ declare function useChat({ threadId, onError, getMetadata, agent, externalTools,
 
 interface UseAgentOptions {
     agentIdOrDef: string | AgentDefinition;
+    enabled?: boolean;
 }
 interface UseAgentResult {
     agent: Agent$1 | null;
@@ -47,7 +48,7 @@ interface UseAgentResult {
  * useAgent is for agent configuration and invocation.
  * For chat UIs, use useChat instead.
  */
-declare function useAgent({ agentIdOrDef, }: UseAgentOptions): UseAgentResult;
+declare function useAgent({ agentIdOrDef, enabled, }: UseAgentOptions): UseAgentResult;
 
 interface UseAgentsResult {
     agents: AgentDefinition[];
@@ -60,18 +61,78 @@ declare function useAgentDefinitions(): UseAgentsResult;
 
 interface UseThreadsResult {
     threads: DistriThread[];
+    total: number;
+    page: number;
+    pageSize: number;
     loading: boolean;
     error: Error | null;
+    params: ThreadListParams;
+    setParams: (params: ThreadListParams) => void;
     refetch: () => Promise<void>;
     deleteThread: (threadId: string) => Promise<void>;
     fetchThread: (threadId: string) => Promise<DistriThread>;
     updateThread: (threadId: string, localId?: string) => Promise<void>;
+    nextPage: () => void;
+    prevPage: () => void;
+    goToPage: (page: number) => void;
+    setPageSize: (size: number) => void;
+}
+interface UseThreadsOptions {
+    enabled?: boolean;
+    initialParams?: ThreadListParams;
+}
+declare function useThreads(options?: UseThreadsOptions): UseThreadsResult;
+/**
+ * Hook to get agents sorted by usage (thread count)
+ */
+interface UseAgentsByUsageResult {
+    agents: AgentUsageInfo[];
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
 }
-declare function useThreads(): UseThreadsResult;
+declare function useAgentsByUsage(): UseAgentsByUsageResult;
 interface UseThreadMessagesOptions {
     threadId: string | null;
 }
 
+type LoadingAnimationPreset = 'typing-dots' | 'pulse-ring' | 'teacher-typing' | 'spinner' | 'wave';
+interface LoadingAnimationConfig {
+    /** Preset animation style */
+    preset?: LoadingAnimationPreset;
+    /** Custom CSS class for the container */
+    className?: string;
+    /** Primary color (CSS color value) */
+    primaryColor?: string;
+    /** Secondary color for gradients (CSS color value) */
+    secondaryColor?: string;
+    /** Avatar emoji/icon for teacher-typing preset */
+    avatar?: string;
+    /** Label text shown alongside animation */
+    label?: string;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+}
+interface LoadingAnimationProps {
+    config?: LoadingAnimationConfig;
+}
+/**
+ * LoadingAnimation component that renders various loading indicator styles.
+ *
+ * @example
+ * // Default typing dots
+ * <LoadingAnimation />
+ *
+ * @example
+ * // Teacher typing style with avatar
+ * <LoadingAnimation config={{ preset: 'teacher-typing', avatar: '🎓', label: 'Teacher is typing...' }} />
+ *
+ * @example
+ * // Custom colored pulse ring
+ * <LoadingAnimation config={{ preset: 'pulse-ring', primaryColor: '#6366F1' }} />
+ */
+declare const LoadingAnimation: React__default.FC<LoadingAnimationProps>;
+
 type ToolCallStatus = 'pending' | 'running' | 'completed' | 'error' | 'user_action_required';
 type DistriAnyTool = DistriFnTool | DistriUiTool;
 interface DistriUiTool extends DistriBaseTool {
@@ -171,9 +232,9 @@ interface ChatState {
     wrapOptions?: {
         autoExecute?: boolean;
     };
-    browserFrame?: string;
-    browserFrameFormat?: string;
-    browserFrameUpdatedAt?: number;
+    browserSessionId?: string;
+    browserViewerUrl?: string;
+    browserStreamUrl?: string;
 }
 type ChatStateTool = DistriAnyTool & {
     executionType: 'backend' | 'external';
@@ -185,12 +246,12 @@ interface ChatStateStore extends ChatState {
     setDebug: (debug: boolean) => void;
     setStreamingIndicator: (indicator: StreamingIndicator | undefined) => void;
     setCurrentThought: (thought: string | undefined) => void;
-    setBrowserFrame: (frameSrc: string, format?: string) => void;
+    setBrowserSession: (sessionId: string, viewerUrl?: string, streamUrl?: string) => void;
+    clearBrowserSession: () => void;
     addMessage: (message: DistriChatMessage) => void;
     processMessage: (message: DistriChatMessage, isFromStream?: boolean) => void;
     clearAllStates: () => void;
     clearTask: (taskId: string) => void;
-    clearBrowserFrame: () => void;
     getToolByName: (toolName: string) => ChatStateTool | undefined;
     completeRunningSteps: () => void;
     resetStreamingStates: () => void;
@@ -222,16 +283,28 @@ declare const useChatStateStore: zustand.UseBoundStore<zustand.StoreApi<ChatStat
 
 interface ChatEmptyStateStarter {
     id?: string;
+    /** Display label for the starter button */
     label: string;
+    /** The prompt text to send (defaults to label if not provided) */
     prompt?: string;
+    /** Optional description shown below the label */
     description?: string;
+    /** Whether to auto-send when clicked (defaults to true) */
     autoSend?: boolean;
+    /** Optional icon/emoji to display before the label */
+    icon?: string;
+    /** Optional variant for different styling */
+    variant?: 'default' | 'outline' | 'ghost';
 }
 interface ChatEmptyStateCategory {
     id: string;
     title?: string;
     description?: string;
+    /** Icon for the category header */
+    icon?: string;
     starters?: ChatEmptyStateStarter[];
+    /** Layout for starters: 'list' (default) or 'grid' */
+    layout?: 'list' | 'grid';
 }
 interface ChatEmptyStateOptions {
     eyebrow?: string;
@@ -242,6 +315,8 @@ interface ChatEmptyStateOptions {
     startersLabel?: string;
     categories?: ChatEmptyStateCategory[];
     autoSendOnStarterClick?: boolean;
+    /** Default layout for all categories: 'list' (default) or 'grid' */
+    layout?: 'list' | 'grid';
 }
 
 interface ModelOption {
@@ -269,7 +344,7 @@ interface ChatEmptyStateController {
 }
 interface ChatProps {
     threadId: string;
-    agent?: Agent$1;
+    agent?: Agent$1 | null;
     onMessage?: (message: DistriChatMessage) => void;
     beforeSendMessage?: (content: DistriMessage) => Promise<DistriMessage>;
     onError?: (error: Error) => void;
@@ -287,6 +362,22 @@ interface ChatProps {
     onTaskFinish?: (task: TaskState) => void;
     renderEmptyState?: (controller: ChatEmptyStateController) => React__default.ReactNode;
     emptyState?: ChatEmptyStateOptions;
+    /**
+     * Starter commands shown in empty state. These are quick-action buttons
+     * that users can click to send predefined prompts.
+     * Alternative to emptyState.categories - if provided, these will be merged.
+     */
+    starterCommands?: ChatEmptyStateStarter[];
+    /**
+     * Configuration for the loading/typing animation shown while waiting for responses.
+     * Supports presets like 'typing-dots', 'teacher-typing', 'pulse-ring', 'spinner', 'wave'.
+     */
+    loadingAnimation?: LoadingAnimationConfig;
+    /**
+     * Custom render function for the loading animation.
+     * If provided, overrides loadingAnimation config.
+     */
+    renderLoadingAnimation?: () => React__default.ReactNode;
     voiceEnabled?: boolean;
     useSpeechRecognition?: boolean;
     ttsConfig?: {
@@ -297,7 +388,16 @@ interface ChatProps {
     initialInput?: string;
     allowBrowserPreview?: boolean;
     maxWidth?: string;
+    className?: string;
+    agentId?: string;
+    enableHistory?: boolean;
+}
+declare const ChatInner: React__default.ForwardRefExoticComponent<ChatProps & React__default.RefAttributes<ChatInstance>>;
+interface ChatContainerProps extends ChatProps {
 }
+/**
+ * The main Chat component that handles authentication via AuthLoading guardian.
+ */
 declare const Chat: React__default.ForwardRefExoticComponent<ChatProps & React__default.RefAttributes<ChatInstance>>;
 
 interface Agent {
@@ -327,6 +427,12 @@ interface AppSidebarProps {
 }
 declare function AppSidebar({ selectedThreadId, currentPage, onNewChat, onThreadSelect, onThreadDelete, onThreadRename, onLogoClick, onPageChange, }: AppSidebarProps): react_jsx_runtime.JSX.Element;
 
+declare global {
+    interface Window {
+        CodeMirror?: any;
+        __distriCodeMirrorLoader?: Promise<void>;
+    }
+}
 interface AttachedImage {
     id: string;
     file: File;
@@ -339,6 +445,10 @@ interface ChatInputProps {
     onSend: (content: string | DistriPart[]) => void;
     onStop?: () => void;
     browserEnabled?: boolean;
+    /** Whether browser has an active session (used for highlighting) */
+    browserHasSession?: boolean;
+    /** Whether browser session is being created */
+    browserLoading?: boolean;
     onToggleBrowser?: (enabled: boolean) => void;
     placeholder?: string;
     disabled?: boolean;
@@ -378,7 +488,8 @@ declare const BrowserPreviewPanel: React__default.FC<BrowserPreviewPanelProps>;
 interface BrowserViewportProps {
     className?: string;
     emptyState?: React__default.ReactNode;
-    showTimestamp?: boolean;
+    /** Optional custom viewer URL override */
+    viewerUrl?: string;
 }
 declare const BrowserViewport: React__default.FC<BrowserViewportProps>;
 
@@ -404,24 +515,86 @@ declare const useTheme: () => ThemeProviderState;
 
 declare function ThemeToggle(): react_jsx_runtime.JSX.Element;
 
+interface AuthLoadingProps {
+    children?: React__default.ReactNode;
+    className?: string;
+}
+declare const AuthLoading: React__default.FC<AuthLoadingProps>;
+
 interface DistriContextValue {
     client: DistriClient | null;
     error: Error | null;
     isLoading: boolean;
+    token?: string | null;
 }
+declare const DistriContext: React$1.Context<DistriContextValue>;
 interface DistriProviderProps {
     config: DistriClientConfig;
     children: ReactNode;
     defaultTheme?: 'dark' | 'light' | 'system';
+    /**
+     * Set to false while waiting for auth token from backend.
+     * When false, isLoading will be true and hooks will wait.
+     * Defaults to true (auth is ready).
+     *
+     * @example
+     * // Backend token loading
+     * const [token, setToken] = useState<string | null>(null);
+     * useEffect(() => { fetchToken().then(setToken); }, []);
+     *
+     * <DistriProvider
+     *   config={{ ...config, accessToken: token }}
+     *   authReady={token !== null}
+     * />
+     */
+    authReady?: boolean;
 }
-declare function DistriProvider({ config, children, defaultTheme }: DistriProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Core provider for Distri SDK. Initializes the DistriClient and handles authentication.
+ *
+ * If `config.clientId` is provided, it will automatically handle cloud authentication
+ * using a dedicated headless provisioner.
+ */
+declare function DistriProvider(props: DistriProviderProps): react_jsx_runtime.JSX.Element;
 declare function useDistri(): DistriContextValue;
+declare function useDistriToken(): {
+    token: string | null | undefined;
+    isLoading: boolean;
+};
+
+type AuthStatus = 'idle' | 'loading' | 'authenticated' | 'error';
+interface DistriAuthContextValue {
+    token: string | null;
+    status: AuthStatus;
+    error: string | null;
+    requestAuth: () => Promise<string | null>;
+    setToken: (token: string | null) => void;
+    setStatus: (status: AuthStatus) => void;
+    setError: (error: string | null) => void;
+    resolveAuth: (token: string | null) => void;
+    config: {
+        clientId: string;
+        theme: 'dark' | 'light';
+        baseUrl: string;
+        debug: boolean;
+    };
+}
+interface DistriAuthProviderProps {
+    clientId: string;
+    theme?: 'dark' | 'light';
+    children: ReactNode;
+    debug?: boolean;
+    baseUrl?: string;
+}
+declare function DistriAuthProvider({ clientId, theme, children, debug, baseUrl }: DistriAuthProviderProps): react_jsx_runtime.JSX.Element;
+declare function useDistriAuth(): DistriAuthContextValue;
 
 interface UseChatMessagesOptions {
     initialMessages?: DistriChatMessage[];
     agent?: Agent$1;
     threadId?: string;
     onError?: (error: Error) => void;
+    enabled?: boolean;
 }
 interface UseChatMessagesReturn {
     messages: DistriChatMessage[];
@@ -431,7 +604,7 @@ interface UseChatMessagesReturn {
     isLoading: boolean;
     error: Error | null;
 }
-declare function useChatMessages({ initialMessages, threadId, onError, }?: UseChatMessagesOptions): UseChatMessagesReturn;
+declare function useChatMessages({ initialMessages, threadId, onError, enabled, }?: UseChatMessagesOptions): UseChatMessagesReturn;
 
 interface TtsRequest {
     text: string;
@@ -626,7 +799,7 @@ declare const Separator: React$1.ForwardRefExoticComponent<Omit<_radix_ui_react_
 
 declare const Sheet: React$1.FC<SheetPrimitive.DialogProps>;
 declare const sheetVariants: (props?: ({
-    side?: "top" | "right" | "bottom" | "left" | null | undefined;
+    side?: "bottom" | "left" | "right" | "top" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface SheetContentProps extends React$1.ComponentProps<typeof SheetPrimitive.Content>, VariantProps<typeof sheetVariants> {
 }
@@ -735,4 +908,4 @@ interface UserMessageRendererProps {
 }
 declare const UserMessageRenderer: React__default.FC<UserMessageRendererProps>;
 
-export { AgentSelect, AppSidebar, AssistantMessageRenderer, type AssistantMessageRendererProps, type AttachedImage, Badge, BrowserPreviewPanel, BrowserViewport, type BrowserViewportProps, Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Chat, type ChatCustomRenderers, type ChatEmptyStateCategory, type ChatEmptyStateController, type ChatEmptyStateOptions, type ChatEmptyStateStarter, ChatInput, type ChatInputProps, type ChatInstance, type ChatProps, type ChatState, type ChatStateStore, ConfigurationPanel, DialogRoot as Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger, type DistriAnyTool, DistriProvider, type DistriUiTool, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, type ExtractedContent, ImageRenderer, type ImageRendererProps, Input, LoadingShimmer, MessageRenderer, type MessageRendererProps, type ModelOption, type PlanState, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, StepBasedRenderer, type StepBasedRendererProps, type StepState, type StreamingIndicator, StreamingTextRenderer, type StreamingTtsOptions, type TaskState, Textarea, ThemeProvider, ThemeToggle, ThinkingRenderer, type ThinkingRendererProps, type ToolCallState, type ToolCallStatus, type ToolRendererMap, type ToolRendererProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type TtsConfig, type TtsRequest, TypingIndicator, type UiToolProps, type UseAgentOptions, type UseAgentResult, type UseAgentsResult, type UseChatMessagesOptions, type UseChatMessagesReturn, type UseChatOptions, type UseChatReturn, type UseConfigurationResult, type UseThreadMessagesOptions, type UseThreadsResult, UserMessageRenderer, type UserMessageRendererProps, VoiceInput, type VoiceInputProps, extractContent, useAgent, useAgentDefinitions, useChat, useChatMessages, useChatStateStore, useConfiguration, useDistri, useSidebar, useSpeechToText, useTheme, useThreads, useTts, wrapFnToolAsUiTool, wrapTools };
+export { AgentSelect, AppSidebar, AssistantMessageRenderer, type AssistantMessageRendererProps, type AttachedImage, AuthLoading, type AuthStatus, Badge, BrowserPreviewPanel, BrowserViewport, type BrowserViewportProps, Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Chat, type ChatContainerProps, type ChatCustomRenderers, type ChatEmptyStateCategory, type ChatEmptyStateController, type ChatEmptyStateOptions, type ChatEmptyStateStarter, ChatInner, ChatInput, type ChatInputProps, type ChatInstance, type ChatProps, type ChatState, type ChatStateStore, ConfigurationPanel, DialogRoot as Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger, type DistriAnyTool, DistriAuthProvider, DistriContext, DistriProvider, type DistriUiTool, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, type ExtractedContent, ImageRenderer, type ImageRendererProps, Input, LoadingAnimation, type LoadingAnimationConfig, type LoadingAnimationPreset, type LoadingAnimationProps, LoadingShimmer, MessageRenderer, type MessageRendererProps, type ModelOption, type PlanState, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, StepBasedRenderer, type StepBasedRendererProps, type StepState, type StreamingIndicator, StreamingTextRenderer, type StreamingTtsOptions, type TaskState, Textarea, ThemeProvider, ThemeToggle, ThinkingRenderer, type ThinkingRendererProps, type ToolCallState, type ToolCallStatus, type ToolRendererMap, type ToolRendererProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type TtsConfig, type TtsRequest, TypingIndicator, type UiToolProps, type UseAgentOptions, type UseAgentResult, type UseAgentsByUsageResult, type UseAgentsResult, type UseChatMessagesOptions, type UseChatMessagesReturn, type UseChatOptions, type UseChatReturn, type UseConfigurationResult, type UseThreadMessagesOptions, type UseThreadsOptions, type UseThreadsResult, UserMessageRenderer, type UserMessageRendererProps, VoiceInput, type VoiceInputProps, extractContent, useAgent, useAgentDefinitions, useAgentsByUsage, useChat, useChatMessages, useChatStateStore, useConfiguration, useDistri, useDistriAuth, useDistriToken, useSidebar, useSpeechToText, useTheme, useThreads, useTts, wrapFnToolAsUiTool, wrapTools };