@factorialco/f0-react 2.21.0 → 2.23.0

package/dist/f0.d.ts

@@ -1,5 +1,4 @@
 import { AgentState } from '@livekit/components-react';
-import { AIMessage } from '@copilotkit/shared';
 import { AlertAvatarProps as AlertAvatarProps_2 } from './F0AvatarAlert';
 import { AlertTagCellValue } from './f0';
 import { AlertTagCellValue as AlertTagCellValue_2 } from './types/alertTag';
@@ -30,7 +29,6 @@ import { ComponentProps } from 'react';
 import { ComponentType } from 'react';
 import { CompoundCellValue } from './types/compound';
 import { Context } from 'react';
-import { CopilotKitProps } from '@copilotkit/react-core';
 import { CountCellValue } from './types/count';
 import { CountryCellValue } from './types/country';
 import { CSSProperties } from 'react';
@@ -101,7 +99,6 @@ import { LineChartConfig as LineChartConfig_2 } from './f0';
 import { LineChartPropsBase } from './utils/types';
 import { LocalAudioTrack } from 'livekit-client';
 import { LongTextCellValue } from './types/longText';
-import { Message as Message_2 } from '@copilotkit/shared';
 import { NumberCellValue } from './f0';
 import { NumberCellValue as NumberCellValue_2 } from './types/number';
 import { NumberFilterOptions } from './NumberFilter/NumberFilter';
@@ -511,6 +508,11 @@ export declare type AiChatMode = "chat" | "voice";
  */
 export declare type AiChatProviderProps = {
     enabled?: boolean;
+    /**
+     * Greeting phrase(s) shown by the welcome screen when the chat is empty.
+     * A single string renders once; an array rotates through phrases. Purely
+     * UI config — does not affect runtime behavior.
+     */
     initialMessage?: string | string[];
     welcomeScreenSuggestions?: WelcomeScreenSuggestion[];
     disclaimer?: AiChatDisclaimer;
@@ -588,27 +590,38 @@ export declare type AiChatProviderProps = {
      * File attachment configuration. When provided, enables file uploads in the chat.
      */
     fileAttachments?: AiChatFileAttachmentConfig;
-    onThumbsUp?: (message: AIMessage, { threadId, feedback }: {
+    onThumbsUp?: (message: F0AIMessage, { threadId, feedback }: {
         threadId: string;
         feedback: string;
     }) => void;
-    onThumbsDown?: (message: AIMessage, { threadId, feedback }: {
+    onThumbsDown?: (message: F0AIMessage, { threadId, feedback }: {
         threadId: string;
         feedback: string;
     }) => void;
     tracking?: AiChatTrackingOptions;
     /**
-     * Optional hook called before a user message is sent. Return false to block submission.
+     * Optional name of the AI agent. Forwarded to the host runtime adapter
+     * (mock in stories, CopilotKit in factorial) — f0 itself only stores it.
      */
-    onBeforeSendMessage?: () => boolean | Promise<boolean>;
+    agent?: string;
     /**
-     * Optional fetch implementation for AI runtime requests owned by F0.
+     * Slot elements rendered inside `<F0AiChat />`. Host apps (factorial in
+     * production, the mock runtime in stories) provide their own connected
+     * wrappers — f0 ships only the shell. Passing slots here makes them
+     * available to any `<F0AiChat />` mounted under this provider (used by
+     * `ApplicationFrame`, which renders the chat itself).
      */
-    runtimeFetch?: typeof fetch;
-} & Pick<CopilotKitProps, "agent" | "credentials" | "children" | "runtimeUrl" | "showDevConsole" | "threadId" | "headers">;
+    chatHeader?: React.ReactNode;
+    chatMessages?: React.ReactNode;
+    chatInput?: React.ReactNode;
+    /** Children rendered inside the provider. */
+    children?: React.ReactNode;
+};
 
 /**
- * Return value type for the useAiChat hook
+ * Return value type for the useAiChat hook. UI-only by design — message
+ * state and actions (send, clear, loadThread, etc.) live in the runtime
+ * adapter and are read via `useAiChatRuntime()`.
  */
 declare type AiChatProviderReturnValue = {
     enabled: boolean;
@@ -617,76 +630,22 @@ declare type AiChatProviderReturnValue = {
     setOpen: React.Dispatch<React.SetStateAction<boolean>>;
     shouldPlayEntranceAnimation: boolean;
     setShouldPlayEntranceAnimation: React.Dispatch<React.SetStateAction<boolean>>;
-    tmp_setAgent: (agent?: string) => void;
+    setAgent: React.Dispatch<React.SetStateAction<string | undefined>>;
     placeholders: string[];
     setPlaceholders: React.Dispatch<React.SetStateAction<string[]>>;
-    /**
-     * The initial message to display in the chat
-     */
     initialMessage?: string | string[];
     setInitialMessage: React.Dispatch<React.SetStateAction<string | string[] | undefined>>;
     welcomeScreenSuggestions: WelcomeScreenSuggestion[];
     setWelcomeScreenSuggestions: React.Dispatch<React.SetStateAction<WelcomeScreenSuggestion[]>>;
-    onThumbsUp?: (message: AIMessage, { threadId, feedback }: {
+    onThumbsUp?: (message: F0AIMessage, { threadId, feedback }: {
         threadId: string;
         feedback: string;
     }) => void;
-    onThumbsDown?: (message: AIMessage, { threadId, feedback }: {
+    onThumbsDown?: (message: F0AIMessage, { threadId, feedback }: {
         threadId: string;
         feedback: string;
     }) => void;
     tracking?: AiChatTrackingOptions;
-    /**
-     * Optional hook called before a user message is sent. Return false to block submission.
-     */
-    onBeforeSendMessage?: () => boolean | Promise<boolean>;
-    /**
-     * Fetch implementation for AI runtime requests owned by F0.
-     */
-    runtimeFetch: typeof fetch;
-    /**
-     * Clear/reset the chat conversation
-     */
-    clear: () => void;
-    /* Excluded from this release type: setClearFunction */
-    /**
-     * Title of the currently loaded thread, or null for new conversations
-     */
-    currentThreadTitle: string | null;
-    /**
-     * Load a thread by ID and set its title in the header
-     */
-    loadThread: (threadId: string, title: string) => void;
-    /* Excluded from this release type: setLoadThreadFunction */
-    /** Whether a thread's messages are currently being fetched */
-    isLoadingThread: boolean;
-    /* Excluded from this release type: setIsLoadingThread */
-    /**
-     * Send a message to the chat
-     * @param message - The message content as a string, or a full Message object
-     */
-    sendMessage: (message: string | Message_2) => void;
-    /* Excluded from this release type: setSendMessageFunction */
-    /**
-     * Append messages to the current conversation.
-     * Useful for injecting pre-built assistant responses (e.g. dashboards)
-     * from outside the chat. IDs are generated internally.
-     *
-     * @param options.persist - Whether to persist messages to the backend thread.
-     *   Defaults to `true`. Pass `false` for client-only display messages that
-     *   should not create or modify a backend thread (e.g. seed messages).
-     */
-    appendMessages: (messages: AppendMessage[], options?: {
-        persist?: boolean;
-    }) => void;
-    /* Excluded from this release type: setAppendMessagesFunction */
-    /**
-     * Atomically clear the conversation and inject new messages.
-     * Starts a fresh thread without the race condition of calling
-     * clear() + appendMessages() separately.
-     */
-    clearAndAppend: (messages: AppendMessage[]) => void;
-    /* Excluded from this release type: setReplaceMessagesFunction */
     /**
      * Current width of the chat window (for resizable mode)
      */
@@ -729,14 +688,14 @@ declare type AiChatProviderReturnValue = {
      * Set the footer content. Use this to update the footer from outside the provider (e.g. per page/route).
      */
     setFooter: React.Dispatch<React.SetStateAction<React.ReactNode | undefined>>;
-    /** Whether the assistant is currently generating a response */
-    inProgress: boolean;
-    /** Set the in-progress state (synced from CopilotKit's isLoading) */
-    setInProgress: (value: boolean) => void;
-    /** The current clarifying question shown in the textarea, or null if none */
-    clarifyingQuestion: ClarifyingQuestionState | null;
-    /** Set the current clarifying question (or null to dismiss) */
-    setClarifyingQuestion: React.Dispatch<React.SetStateAction<ClarifyingQuestionState | null>>;
+    /**
+     * True while a clarifying flow is active. F0 uses this flag to freeze
+     * layout / disable file drop / hide disclaimer. The actual panel state
+     * is owned by the host (factorial); F0 only sees the boolean.
+     */
+    isClarifying: boolean;
+    /** Set the clarifying flag. */
+    setIsClarifying: React.Dispatch<React.SetStateAction<boolean>>;
     /**
      * Whether files are currently being dragged over the chat window.
      * Set by the ChatWindow drag listeners and read by the DropOverlay
@@ -766,7 +725,7 @@ declare type AiChatProviderReturnValue = {
     pendingQuote: PendingQuote | null;
     /** Set the pending quote (pass null to clear). */
     setPendingQuote: React.Dispatch<React.SetStateAction<PendingQuote | null>>;
-} & Pick<AiChatState, "agent" | "disclaimer" | "resizable" | "entityRefs" | "canvasActions" | "canvasEntities" | "credits" | "employeeCredits" | "creditWarning" | "fileAttachments"> & {
+} & Pick<AiChatState, "agent" | "chatHeader" | "chatMessages" | "chatInput" | "disclaimer" | "resizable" | "entityRefs" | "canvasActions" | "canvasEntities" | "credits" | "employeeCredits" | "creditWarning" | "fileAttachments"> & {
     /** The current canvas content, or null when canvas is closed */
     canvasContent: CanvasContent | null;
     /** Open the canvas panel with the given content */
@@ -782,12 +741,17 @@ declare type AiChatProviderReturnValue = {
 };
 
 /**
- * Internal state for the AiChat provider
+ * Internal state for the AiChat provider. Pure UI / config concerns —
+ * message-runtime concerns (sendMessage, threadId, streaming) live in a
+ * separate adapter (mock in stories, factorial-side in production).
  */
 declare interface AiChatState {
     enabled: boolean;
     agent?: string;
     initialMessage?: string | string[];
+    chatHeader?: React.ReactNode;
+    chatMessages?: React.ReactNode;
+    chatInput?: React.ReactNode;
     welcomeScreenSuggestions?: WelcomeScreenSuggestion[];
     disclaimer?: AiChatDisclaimer;
     resizable?: boolean;
@@ -805,31 +769,23 @@ declare interface AiChatState {
     fileAttachments?: AiChatFileAttachmentConfig;
     placeholders?: string[];
     setPlaceholders?: React.Dispatch<React.SetStateAction<string[]>>;
-    onThumbsUp?: (message: AIMessage, { threadId, feedback }: {
+    onThumbsUp?: (message: F0AIMessage, { threadId, feedback }: {
         threadId: string;
         feedback: string;
     }) => void;
-    onThumbsDown?: (message: AIMessage, { threadId, feedback }: {
+    onThumbsDown?: (message: F0AIMessage, { threadId, feedback }: {
         threadId: string;
         feedback: string;
     }) => void;
     tracking?: AiChatTrackingOptions;
-    /**
-     * Optional hook called before a user message is sent. Return false to block submission.
-     */
-    onBeforeSendMessage?: () => boolean | Promise<boolean>;
-    /**
-     * Optional fetch implementation for AI runtime requests owned by F0.
-     */
-    runtimeFetch?: typeof fetch;
 }
 
-declare type AiChatTrackingOptions = {
+export declare type AiChatTrackingOptions = {
     onVisibility?: () => void;
     onClose?: () => void;
     onWelcomeSuggestionClick?: (event: WelcomeSuggestionClickEvent) => void;
     onNewChat?: () => void;
-    onMessage?: (message: Message_2) => void;
+    onMessage?: (message: F0Message) => void;
 };
 
 /**
@@ -876,7 +832,7 @@ export declare type AiInsightCardContent = {
 };
 
 /** Assistant-flavoured `Message`. Same shape — alias for self-documentation. */
-declare type AIMessage_2 = Message_3;
+declare type AIMessage = Message_2;
 
 /**
  * Default AI chat translations — derived from the global defaultTranslations
@@ -5358,7 +5314,7 @@ export declare interface F0AiAvailableFormDefinition<TParams extends Record<stri
 /**
  * @experimental This is an experimental component use it at your own risk
  */
-export declare const F0AiChat: () => JSX_2.Element | null;
+export declare const F0AiChat: ({ header: headerProp, messages: messagesProp, input: inputProp, }: F0AiChatProps) => JSX_2.Element | null;
 
 /**
  * Headless chat header. Renders a top bar with title (or thread selector),
@@ -5444,10 +5400,28 @@ export declare type F0AiChatHistoryProps = {
     onDeleteThread: (id: string) => Promise<void> | void;
 };
 
+/**
+ * Slot composition for the F0 AI chat shell. F0 ships the shell + UI
+ * primitives; the consumer (factorial in production, the mock runtime
+ * in stories) supplies the connected slot components that wire data
+ * through whatever runtime they choose (CopilotKit, Mastra, mock, …).
+ *
+ * Slots are optional so the shell renders cleanly even when no runtime
+ * is mounted (the chat just stays empty).
+ */
+export declare interface F0AiChatProps {
+    /** Header slot rendered at the top of the chat window. */
+    header?: ReactNode;
+    /** Messages slot rendered inside the scrollable area. */
+    messages?: ReactNode;
+    /** Input slot rendered at the bottom (textarea + suggestions + disclaimer). */
+    input?: ReactNode;
+}
+
 /**
  * @experimental This is an experimental component use it at your own risk
  */
-export declare const F0AiChatProvider: ({ enabled, initialMessage, welcomeScreenSuggestions, disclaimer, resizable, defaultVisualizationMode, lockVisualizationMode, historyEnabled, footer, VoiceMode, entityRefs, canvasActions, canvasEntities, credits, employeeCredits, creditWarning, fileAttachments, onThumbsUp, onThumbsDown, onBeforeSendMessage, runtimeFetch, children, agent, tracking, ...copilotKitProps }: AiChatProviderProps) => JSX_2.Element;
+export declare const F0AiChatProvider: ({ enabled, initialMessage, chatHeader, chatMessages, chatInput, welcomeScreenSuggestions, disclaimer, resizable, defaultVisualizationMode, lockVisualizationMode, historyEnabled, footer, VoiceMode, entityRefs, canvasActions, canvasEntities, credits, employeeCredits, creditWarning, fileAttachments, onThumbsUp, onThumbsDown, children, agent, tracking, }: AiChatProviderProps) => JSX_2.Element;
 
 /**
  * Headless chat composer.
@@ -5458,7 +5432,7 @@ export declare const F0AiChatProvider: ({ enabled, initialMessage, welcomeScreen
  * coupling to `useAiChat()` or CopilotKit — wrappers like F0AiChat
  * provide the wiring.
  */
-export declare const F0AiChatTextArea: ({ onSubmit, onStop, inProgress, onBeforeSubmit, placeholders, creditWarning, clarifyingQuestion, pendingContext, onPendingContextChange, pendingQuote, onPendingQuoteChange, fileAttachments, searchPersons, onProcessFilesRef, disclaimer, footer, isWelcomeScreen, fullscreen, welcomeScreenSuggestions, onSuggestionClick, ref, }: F0AiChatTextAreaProps) => JSX_2.Element;
+export declare const F0AiChatTextArea: ({ onSubmit, onStop, inProgress, onBeforeSubmit, placeholders, creditWarning, clarifyingUI, pendingContext, onPendingContextChange, pendingQuote, onPendingQuoteChange, fileAttachments, searchPersons, onProcessFilesRef, disclaimer, footer, isWelcomeScreen, fullscreen, welcomeScreenSuggestions, onSuggestionClick, ref, }: F0AiChatTextAreaProps) => JSX_2.Element;
 
 export declare type F0AiChatTextAreaProps = {
     ref: RefObject<HTMLDivElement>;
@@ -5479,10 +5453,13 @@ export declare type F0AiChatTextAreaProps = {
     /** Credit warning banner shown above the composer. */
     creditWarning?: AiChatCreditWarning;
     /**
-     * Clarifying question to render in place of the input. When non-null the
-     * panel takes over the composer surface and submission is blocked.
+     * Optional ReactNode rendered in place of the input. When present the
+     * composer enters "clarifying" mode: form submission is blocked, the
+     * gradient border activates, and a nav-hint replaces the disclaimer.
+     * The host owns the panel (typically `F0ClarifyingPanel`) and its
+     * state — F0 just renders the slot.
      */
-    clarifyingQuestion?: ClarifyingQuestionState | null;
+    clarifyingUI?: ReactNode;
     /** Pending context shown as a chip; prepended invisibly on submit. */
     pendingContext?: PendingContext | null;
     /** Called when the user dismisses pending context (or it gets consumed on submit). */
@@ -5537,16 +5514,16 @@ export declare type F0AiChatTextAreaProps = {
 /**
  * Payload emitted by `F0AiChatTextArea` when the user submits.
  *
- * `text` already contains the inline markup the renderer expects:
- * `<entity-ref>` tags for @mentions, `<reply-quote>` for the quoted
- * fragment, and HTML-escaped user-typed text. The consumer decides how
- * to wrap it (plain string vs multipart message) when forwarding to
- * the agent.
+ * `text` contains HTML-escaped user-typed text with `<entity-ref>` tags
+ * for @mentions only. The reply quote (if any) and pending context
+ * travel as separate structured fields — the adapter (factorial) owns
+ * the wire encoding when forwarding to the agent.
  */
 export declare type F0AiChatTextAreaSubmitPayload = {
     text: string;
     files: UploadedFile[];
     context: PendingContext | null;
+    quote: PendingQuote | null;
 };
 
 /**
@@ -5725,6 +5702,9 @@ export declare class F0AiMask {
     private render;
 }
 
+/** Assistant-flavoured `F0Message`. Same shape — alias kept for clarity. */
+export declare type F0AIMessage = F0Message;
+
 export declare const F0AiMessagesContainer: (props: F0AiMessagesContainerProps) => JSX_2.Element;
 
 export declare type F0AiMessagesContainerProps = {
@@ -5753,7 +5733,7 @@ export declare type F0AiMessagesContainerProps = {
     /** Called when the user selects text and clicks Reply (user or assistant bubble). */
     onReplyQuote?: (text: string) => void;
     /** Called when an assistant message finishes generating — for analytics. */
-    onAssistantMessageRendered?: (message: Message_3) => void;
+    onAssistantMessageRendered?: (message: Message_2) => void;
     /** Disables auto-scrollIntoView on new user messages (fullscreen sets false). */
     autoScrollUserIntoView?: boolean;
     /**
@@ -5887,7 +5867,7 @@ export declare const F0Alert: WithDataTestIdReturnType_3<({ title, description,
 
 export declare interface F0AlertProps {
     title: string;
-    description: string;
+    description?: string;
     action?: {
         label: string;
         disabled?: boolean;
@@ -6015,11 +5995,11 @@ declare type F0AssistantMessageExtraProps = {
      * full message list to call CopilotKit's lazy tool renderer; standalone
      * consumers can omit it.
      */
-    renderToolCall?: (message: Message_3) => ReactNode | null;
+    renderToolCall?: (message: Message_2) => ReactNode | null;
     /** Called when the user selects text in this message and clicks Reply. */
     onReplyQuote?: (text: string) => void;
     /** Called once the assistant message has finished generating — for analytics. */
-    onRendered?: (message: Message_3) => void;
+    onRendered?: (message: Message_2) => void;
     /**
      * Renders the assistant text content. The connected wrapper provides a
      * markdown-aware implementation; standalone consumers can omit it and a
@@ -8695,6 +8675,24 @@ export declare type F0LinkProps = Omit<ActionLinkProps, "variant" | "href"> & {
     href?: string;
 };
 
+export declare type F0Message = {
+    id: string;
+    role: "user" | "assistant" | "system" | "tool";
+    content?: unknown;
+    toolCalls?: F0ToolCall[];
+    toolCallId?: string;
+    createdAt?: string;
+    generativeUI?: () => unknown;
+    rawData?: unknown;
+    /**
+     * Reply quote text attached to the message by the composer. Rendered
+     * as a block above the user bubble. Adapters (factorial / mock) own
+     * the wire encoding; F0 only reads this structured field.
+     */
+    replyQuote?: string;
+    [key: string]: any;
+};
+
 export declare const F0ModuleCard: ({ moduleName, description, onAction, actionHref, imageSrc, }: F0ModuleCardProps) => JSX_2.Element;
 
 /**
@@ -9616,6 +9614,21 @@ export declare interface F0TimelineRowTaskProps extends F0TimelineRowBaseProps {
     otherActions?: F0TimelineRowOtherAction[];
 }
 
+/**
+ * Loose message shape used inside f0. Mirrors the CopilotKit `Message`
+ * shape so adapters (factorial, mock runtime) can map back and forth
+ * with no field rename, but is owned by f0 — nothing in `src/` imports
+ * from `@copilotkit/*` anymore.
+ */
+export declare type F0ToolCall = {
+    id: string;
+    type?: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+
 export declare const F0WizardForm: {
     <TSchema extends F0FormSchema_2>(props: F0WizardFormSingleSchemaProps<TSchema>): default_2.ReactElement;
     <T extends F0PerSectionSchema_2>(props: F0WizardFormPerSectionProps<T>): default_2.ReactElement;
@@ -9729,11 +9742,11 @@ export declare interface F0ZodType<T extends ZodTypeAny = ZodTypeAny> {
 
 export declare type FeedbackConfig = {
     threadId: string;
-    onThumbsUp: (msg: AIMessage_2, ctx: {
+    onThumbsUp: (msg: AIMessage, ctx: {
         threadId: string;
         feedback: string;
     }) => void;
-    onThumbsDown: (msg: AIMessage_2, ctx: {
+    onThumbsDown: (msg: AIMessage, ctx: {
         threadId: string;
         feedback: string;
     }) => void;
@@ -11114,7 +11127,7 @@ export declare interface Message {
  * Most fields are optional / wide on purpose — the headless renders
  * what it finds and ignores the rest.
  */
-declare type Message_3 = {
+declare type Message_2 = {
     id?: string;
     role?: string;
     content?: unknown;
@@ -11128,6 +11141,13 @@ declare type Message_3 = {
     }>;
     generativeUI?: () => unknown;
     rawData?: unknown;
+    /**
+     * Reply quote text the composer attached to this (user) message.
+     * Rendered as a block above the bubble. The wire protocol that carries
+     * this is owned by the adapter (factorial) — F0 only consumes the
+     * structured field.
+     */
+    replyQuote?: string;
     [key: string]: any;
 };
 
@@ -12509,7 +12529,7 @@ declare type RelaxedNumericWithFormatter = Omit<NumericWithFormatter, "numericVa
  */
 export declare type RenderableTurn = {
     /** Messages rendered before the thinking section (typically the user message). */
-    userMessages: Message_3[];
+    userMessages: Message_2[];
     /**
      * Optional collapsible "thinking" header rendered between user and
      * assistant blocks. Titles are pre-parsed upstream.
@@ -12530,7 +12550,7 @@ export declare type RenderableTurn = {
         isWriting?: boolean;
     };
     /** Messages rendered after the thinking section (assistant replies). */
-    assistantMessages: Message_3[];
+    assistantMessages: Message_2[];
     /** True while the agent is still producing content for this turn. */
     isInProgress: boolean;
     /**
@@ -12549,7 +12569,7 @@ export declare type RenderableTurn = {
         /** Concatenated assistant content for the copy button. */
         content: string;
         /** Reference message attached to feedback submissions. */
-        targetMessage: Message_3;
+        targetMessage: Message_2;
     };
 };
 
@@ -14061,9 +14081,6 @@ declare interface UpsellRequestResponseDialogProps {
  * is mounted — that case is intentional in `ApplicationFrame`, which
  * renders chat-aware components in both the AI-enabled tree and the
  * promotion-chat tree.
- *
- * Most consumers don't need to think about this — they're rendered
- * under `<F0AiChatProvider>` and receive the real context.
  */
 export declare function useAiChat(): AiChatProviderReturnValue;
 
@@ -14832,7 +14849,7 @@ export declare type WelcomeScreenSuggestionItem = {
  * analytics layer (e.g. Amplitude) needs to attribute the click: the picked
  * sub-item, its parent group, and the resolved prompt that was actually sent.
  */
-declare type WelcomeSuggestionClickEvent = {
+export declare type WelcomeSuggestionClickEvent = {
     item: WelcomeScreenSuggestionItem;
     group: WelcomeScreenSuggestion;
     /** Prompt actually sent to the AI — `item.prompt` falling back to `item.title`. */