@factorialco/f0-react 1.384.0 → 1.386.0

package/dist/f0.d.ts

@@ -331,6 +331,19 @@ export declare type AiChatProviderProps = {
      * Optional footer content rendered below the textarea
      */
     footer?: React.ReactNode;
+    /**
+     * Async resolver functions for entity references in markdown.
+     * Used to fetch profile data for inline entity mentions (hover cards).
+     * The consuming app provides these so the chat can resolve entity IDs
+     * (e.g. employee IDs) into rich profile data without knowing the API.
+     */
+    entityResolvers?: EntityResolvers;
+    /**
+     * Available tool hints that the user can activate to provide intent context
+     * to the AI. Renders a selector button next to the send button.
+     * Only one tool hint can be active at a time.
+     */
+    toolHints?: AiChatToolHint[];
     onThumbsUp?: (message: AIMessage, { threadId, feedback }: {
         threadId: string;
         feedback: string;
@@ -339,6 +352,7 @@ export declare type AiChatProviderProps = {
         threadId: string;
         feedback: string;
     }) => void;
+    tracking?: AiChatTrackingOptions;
 } & Pick<CopilotKitProps, "agent" | "credentials" | "children" | "runtimeUrl" | "showDevConsole" | "threadId" | "headers">;
 
 /**
@@ -369,6 +383,7 @@ declare type AiChatProviderReturnValue = {
         threadId: string;
         feedback: string;
     }) => void;
+    tracking?: AiChatTrackingOptions;
     /**
      * Clear/reset the chat conversation
      */
@@ -409,7 +424,12 @@ 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>>;
-} & Pick<AiChatState, "greeting" | "agent" | "disclaimer" | "resizable">;
+} & Pick<AiChatState, "greeting" | "agent" | "disclaimer" | "resizable" | "entityResolvers" | "toolHints"> & {
+    /** The currently active tool hint, or null if none is selected */
+    activeToolHint: AiChatToolHint | null;
+    /** Set the active tool hint (pass null to clear) */
+    setActiveToolHint: React.Dispatch<React.SetStateAction<AiChatToolHint | null>>;
+};
 
 /**
  * Internal state for the AiChat provider
@@ -425,6 +445,8 @@ declare interface AiChatState {
     defaultVisualizationMode?: VisualizationMode;
     lockVisualizationMode?: boolean;
     footer?: React.ReactNode;
+    entityResolvers?: EntityResolvers;
+    toolHints?: AiChatToolHint[];
     placeholders?: string[];
     setPlaceholders?: React.Dispatch<React.SetStateAction<string[]>>;
     onThumbsUp?: (message: AIMessage, { threadId, feedback }: {
@@ -435,8 +457,42 @@ declare interface AiChatState {
         threadId: string;
         feedback: string;
     }) => void;
+    tracking?: AiChatTrackingOptions;
 }
 
+/**
+ * A tool hint that can be activated to prepend invisible context to the user's
+ * message, telling the AI about the user's intent (e.g. "generate tables",
+ * "data analysis"). Similar to Gemini's tool selector UI.
+ *
+ * Only one tool hint can be active at a time. It persists across messages
+ * until the user explicitly removes it.
+ */
+export declare type AiChatToolHint = {
+    /** Unique identifier for this tool hint */
+    id: string;
+    /** Display label shown in the selector and chip */
+    label: string;
+    /** Optional icon shown in the selector and chip */
+    icon?: IconType;
+    /**
+     * Prompt text injected as invisible context before the user's message.
+     * The AI receives this but the user never sees it in the chat.
+     */
+    prompt: string;
+};
+
+/**
+ * Tracking options for the AI chat
+ */
+declare type AiChatTrackingOptions = {
+    onVisibility?: () => void;
+    onClose?: () => void;
+    onWelcomeSuggestionClick?: (suggestion: WelcomeScreenSuggestion) => void;
+    onNewChat?: () => void;
+    onMessage?: (message: Message) => void;
+};
+
 /**
  * AI Chat translations type
  */
@@ -470,8 +526,6 @@ export declare const aiTranslations: {
         thoughtsGroupTitle: string;
         resourcesGroupTitle: string;
         thinking: string;
-        exportTable: string;
-        generatedTableFilename: string;
         feedbackModal: {
             positive: {
                 title: string;
@@ -484,9 +538,12 @@ export declare const aiTranslations: {
                 placeholder: string;
             };
         };
+        dataDownloadPreview: string;
         expandChat: string;
         collapseChat: string;
         ask: string;
+        viewProfile: string;
+        tools: string;
     };
 };
 
@@ -2451,9 +2508,12 @@ export declare const defaultTranslations: {
                 readonly placeholder: "Share what didn’t work";
             };
         };
+        readonly dataDownloadPreview: "Preview {{shown}} of {{total}} rows — download the Excel to see all data.";
         readonly expandChat: "Expand chat";
         readonly collapseChat: "Collapse chat";
         readonly ask: "Ask One";
+        readonly viewProfile: "View profile";
+        readonly tools: "Tools";
         readonly growth: {
             readonly demoCard: {
                 readonly title: "See {{moduleName}} in action";
@@ -2705,8 +2765,6 @@ export declare function DndProvider({ driver, children, }: {
     children: ReactNode;
 }): JSX_2.Element;
 
-export declare function downloadTableAsExcel(table: HTMLTableElement, filename?: string): void;
-
 export declare type DragPayload<T = unknown> = {
     kind: string;
     id: string;
@@ -2770,6 +2828,38 @@ declare const emojiVariants: (props?: ({
     className?: ClassValue;
 })) | undefined) => string;
 
+/**
+ * Generic entity reference renderer for custom `<entity-ref>` HTML tags
+ * embedded in AI chat markdown output.
+ *
+ * Dispatches to type-specific renderers based on the `type` attribute.
+ * Falls back to rendering children as plain text for unknown types.
+ *
+ * Usage in markdown (via rehype-raw):
+ *   <entity-ref type="person" id="123">Ana García</entity-ref>
+ */
+export declare function EntityRef({ type, id, children, }: {
+    type?: string;
+    id?: string;
+    children?: ReactNode;
+}): JSX_2.Element;
+
+/**
+ * Map of async resolver functions keyed by entity type.
+ * Each resolver takes an entity ID and returns the profile data
+ * needed to render the entity reference hover card.
+ *
+ * Extensible: add new entity types here as needed (e.g. `team`, `department`).
+ */
+export declare type EntityResolvers = {
+    person?: (id: string) => Promise<PersonProfile>;
+    /**
+     * Search for persons by name query. Used by the @mention autocomplete
+     * in the chat input to let users reference specific employees.
+     */
+    searchPersons?: (query: string) => Promise<PersonProfile[]>;
+};
+
 declare type Enumerate<N extends number, Acc extends number[] = []> = Acc["length"] extends N ? [...Acc, N][number] : Enumerate<N, [...Acc, Acc["length"]]>;
 
 export declare interface ErrorMessageProps {
@@ -2833,9 +2923,9 @@ export declare const F0AiChat: () => JSX_2.Element | null;
 /**
  * @experimental This is an experimental component use it at your own risk
  */
-export declare const F0AiChatProvider: ({ enabled, greeting, initialMessage, welcomeScreenSuggestions, disclaimer, resizable, defaultVisualizationMode, lockVisualizationMode, footer, onThumbsUp, onThumbsDown, children, agent, ...copilotKitProps }: AiChatProviderProps) => JSX_2.Element;
+export declare const F0AiChatProvider: ({ enabled, greeting, initialMessage, welcomeScreenSuggestions, disclaimer, resizable, defaultVisualizationMode, lockVisualizationMode, footer, entityResolvers, toolHints, onThumbsUp, onThumbsDown, children, agent, tracking, ...copilotKitProps }: AiChatProviderProps) => JSX_2.Element;
 
-export declare const F0AiChatTextArea: ({ submitLabel, inProgress, onSend, onStop, placeholders, defaultPlaceholder, autoFocus, }: F0AiChatTextAreaProps) => JSX_2.Element;
+export declare const F0AiChatTextArea: ({ submitLabel, inProgress, onSend, onStop, placeholders, defaultPlaceholder, autoFocus, entityResolvers, toolHints, activeToolHint, onActiveToolHintChange, }: F0AiChatTextAreaProps) => JSX_2.Element;
 
 /**
  * Props for the F0AiChatTextArea component
@@ -2872,6 +2962,25 @@ export declare interface F0AiChatTextAreaProps {
      * @default true
      */
     autoFocus?: boolean;
+    /**
+     * Entity resolvers for @mention autocomplete and entity reference rendering.
+     * When `searchPersons` is provided, typing @ in the textarea opens an
+     * autocomplete popover to mention employees.
+     */
+    entityResolvers?: EntityResolvers;
+    /**
+     * Available tool hints that the user can activate.
+     * Renders a selector button to the left of the send button.
+     */
+    toolHints?: AiChatToolHint[];
+    /**
+     * The currently active tool hint, or null if none is selected.
+     */
+    activeToolHint?: AiChatToolHint | null;
+    /**
+     * Callback when the active tool hint changes (selection or removal).
+     */
+    onActiveToolHintChange?: (toolHint: AiChatToolHint | null) => void;
 }
 
 export declare const F0AiCollapsibleMessage: ({ icon, title, children, }: F0AiCollapsibleMessageProps) => JSX_2.Element;
@@ -3529,6 +3638,68 @@ declare type F0CustomFieldConfigWithConfig<TValue = unknown, TConfig = unknown>
     fieldType: "custom";
 };
 
+/**
+ * Component that renders an optional markdown preview followed by
+ * a dropdown button with "Download Excel" as the primary action and
+ * "Download CSV" as a secondary option. Files are generated client-side
+ * from the raw dataset provided by the agent.
+ */
+export declare const F0DataDownload: ({ markdown, filename, dataset, }: F0DataDownloadProps) => JSX_2.Element;
+
+/**
+ * Inline dataset for client-side file generation (Excel / CSV).
+ * Sent by the agent with the raw query results.
+ */
+export declare type F0DataDownloadDataset = {
+    /**
+     * Column headers in display order.
+     */
+    columns: string[];
+    /**
+     * Array of row objects keyed by column name.
+     */
+    rows: Record<string, unknown>[];
+    /**
+     * Total number of rows returned by the query (before truncation).
+     * Used together with previewCount to render the preview note.
+     */
+    totalCount?: number;
+    /**
+     * Number of rows shown in the markdown preview table.
+     * Used together with totalCount to render the preview note.
+     */
+    previewCount?: number;
+    /**
+     * Map of raw column names to human-readable labels in the user's language.
+     * Used for Excel/CSV headers. Falls back to the raw column name when absent.
+     */
+    columnLabels?: Record<string, string>;
+};
+
+/**
+ * Props for the F0DataDownload component.
+ *
+ * Renders an optional markdown preview/description followed by
+ * "Download Excel" and "Download CSV" buttons. The component generates
+ * the files client-side from the provided dataset.
+ */
+export declare type F0DataDownloadProps = {
+    /**
+     * Optional markdown content to display above the download buttons.
+     * Typically a 5-row preview table generated by the agent.
+     */
+    markdown?: string;
+    /**
+     * Descriptive filename (without extension) for the downloaded files.
+     * Generated by the AI to reflect the query content in the user's language.
+     */
+    filename?: string;
+    /**
+     * Raw dataset for client-side Excel and CSV generation.
+     */
+    dataset: F0DataDownloadDataset;
+};
+
 /**
  * F0 config options specific to date fields
  *
@@ -4342,6 +4513,12 @@ export declare type F0LinkProps = Omit<ActionLinkProps, "variant" | "href"> & {
 
 export declare const f0MarkdownRenderers: NonNullable<AssistantMessageProps["markdownTagRenderers"]>;
 
+/**
+ * Markdown renderers without the table download button.
+ * Use this when the parent component already provides its own download controls.
+ */
+export declare const f0MarkdownRenderersSimple: NonNullable<AssistantMessageProps["markdownTagRenderers"]>;
+
 export declare const F0MessageSources: ({ sources }: F0MessageSourcesProps) => JSX_2.Element | null;
 
 /**
@@ -4437,12 +4614,16 @@ export declare interface F0OneIconProps extends SVGProps<SVGSVGElement> {
     size?: "xs" | "sm" | "md" | "lg";
 }
 
-export declare const F0OneSwitch: ({ className, disabled, tooltip, autoOpen, }: F0OneSwitchProps) => JSX_2.Element | null;
+export declare const F0OneSwitch: ({ className, disabled, onVisible, tooltip, autoOpen, onToggle, }: F0OneSwitchProps) => JSX_2.Element | null;
 
 /**
  * Props for the F0OneSwitch component
  */
 export declare type F0OneSwitchProps = React.ComponentPropsWithoutRef<typeof SwitchPrimitive.Root> & {
+    /** Callback when the switch is visible */
+    onVisible?: () => void;
+    /** Callback when the switch is toggled */
+    onToggle?: () => void;
     /** Custom text shown in the tooltip when the chat is closed */
     tooltip?: {
         whenDisabled?: string;
@@ -6512,6 +6693,18 @@ export declare type PersonAvatarVariant = Extract<AvatarVariant, {
     type: "person";
 }>;
 
+/**
+ * Profile data for a person entity (employee), resolved asynchronously
+ * and displayed in the entity reference hover card.
+ */
+export declare type PersonProfile = {
+    id: string | number;
+    firstName: string;
+    lastName: string;
+    avatarUrl?: string;
+    jobTitle?: string;
+};
+
 declare type PersonTagProps = ComponentProps<typeof F0TagPerson>;
 
 export declare const PieChart: WithDataTestIdReturnType_5<ForwardRefExoticComponent<Omit<PieChartProps & RefAttributes<HTMLDivElement>, "ref"> & RefAttributes<HTMLElement | SVGElement>>>;
@@ -7228,6 +7421,12 @@ declare interface TableHeadProps {
 
 declare type TableOfContentPopoverVariant = "dark" | "light";
 
+/**
+ * Table variant without the built-in download button.
+ * Used inside components that already provide their own download controls.
+ */
+export declare function TableSimple({ children, ...props }: React.HTMLAttributes<HTMLTableElement>): JSX_2.Element;
+
 declare type TableVisualizationOptions<R extends RecordType, _Filters extends FiltersDefinition, Sortings extends SortingsDefinition, Summaries extends SummariesDefinition> = {
     /**
      * The columns to display
@@ -8329,11 +8528,6 @@ declare module "gridstack" {
 }
 
 
-declare namespace Calendar {
-    var displayName: string;
-}
-
-
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
         aiBlock: {
@@ -8346,9 +8540,8 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        enhanceHighlight: {
-            setEnhanceHighlight: (from: number, to: number) => ReturnType;
-            clearEnhanceHighlight: () => ReturnType;
+        moodTracker: {
+            insertMoodTracker: (data: MoodTrackerData) => ReturnType;
         };
     }
 }
@@ -8356,8 +8549,9 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        moodTracker: {
-            insertMoodTracker: (data: MoodTrackerData) => ReturnType;
+        enhanceHighlight: {
+            setEnhanceHighlight: (from: number, to: number) => ReturnType;
+            clearEnhanceHighlight: () => ReturnType;
         };
     }
 }
@@ -8381,3 +8575,8 @@ declare module "@tiptap/core" {
         };
     }
 }
+
+
+declare namespace Calendar {
+    var displayName: string;
+}