@factorialco/f0-react 1.385.0 → 1.386.0

package/dist/ai.d.ts

@@ -64,6 +64,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;
@@ -144,7 +157,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
@@ -160,6 +178,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 }: {
@@ -173,6 +193,28 @@ declare interface AiChatState {
     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
  */
@@ -217,8 +259,6 @@ export declare const aiTranslations: {
         thoughtsGroupTitle: string;
         resourcesGroupTitle: string;
         thinking: string;
-        exportTable: string;
-        generatedTableFilename: string;
         feedbackModal: {
             positive: {
                 title: string;
@@ -231,9 +271,12 @@ export declare const aiTranslations: {
                 placeholder: string;
             };
         };
+        dataDownloadPreview: string;
         expandChat: string;
         collapseChat: string;
         ask: string;
+        viewProfile: string;
+        tools: string;
     };
 };
 
@@ -618,9 +661,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";
@@ -820,10 +866,40 @@ export declare const defaultTranslations: {
     };
 };
 
-export declare function downloadTableAsExcel(table: HTMLTableElement, filename?: string): void;
-
 export declare function Em({ children, ...props }: React.HTMLAttributes<HTMLSpanElement>): JSX_2.Element;
 
+/**
+ * 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[]>;
+};
+
 export declare const F0ActionItem: ({ title, status, inGroup }: F0ActionItemProps) => JSX_2.Element;
 
 /**
@@ -852,9 +928,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, tracking, ...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
@@ -891,6 +967,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;
@@ -940,6 +1035,68 @@ declare const F0AuraVoiceAnimationVariants: (props?: ({
     className?: ClassValue;
 })) | undefined) => string;
 
+/**
+ * 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;
+};
+
 export declare const F0HILActionConfirmation: ({ text, confirmationText, onConfirm, cancelText, onCancel, }: F0HILActionConfirmationProps) => JSX_2.Element;
 
 /**
@@ -970,6 +1127,12 @@ export declare type F0HILActionConfirmationProps = {
 
 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;
 
 /**
@@ -1127,12 +1290,30 @@ declare type PathsToStringProps<T> = T extends string ? [] : {
     [K in Extract<keyof T, string>]: [K, ...PathsToStringProps<T[K]>];
 }[Extract<keyof T, string>];
 
+/**
+ * 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;
+};
+
 export declare function Pre({ children, ...props }: React.HTMLAttributes<HTMLPreElement>): JSX_2.Element;
 
 export declare function Strong({ children, ...props }: React.HTMLAttributes<HTMLSpanElement>): JSX_2.Element;
 
 export declare function Table({ children, ...props }: React.HTMLAttributes<HTMLTableElement>): JSX_2.Element;
 
+/**
+ * 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;
+
 export declare function Td({ children, ...props }: React.HTMLAttributes<HTMLTableCellElement>): JSX_2.Element;
 
 export declare function Th({ children, ...props }: React.HTMLAttributes<HTMLTableCellElement>): JSX_2.Element;
@@ -1253,9 +1434,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;
         };
     }
 }
@@ -1263,8 +1443,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;
         };
     }
 }

package/dist/ai.js

@@ -1,50 +1,53 @@
-import { A as e, B as o, C as t, E as n, h as i, F as r, a as l, x as c, i as A, b as u, s as F, t as h, v as C, w as T, c as d, n as m, o as I, p as f, H as g, I as S, k as p, L as x, O as H, q as P, P as b, S as k, T as O, l as v, m as w, U as M, r as E, j as L, d as q, e as B, u as U, g as j, f as z } from "./F0AiChat-Ddo83UfP.js";
-import { defaultTranslations as R } from "./i18n-provider-defaults.js";
-import { A as y, F as G, c as J, b as K, a as N, o as Q, u as W } from "./F0HILActionConfirmation-C475SHSS.js";
+import { A as e, B as t, C as n, q as o, E as i, h as r, F as l, a as c, D as A, i as u, b as F, j as h, w as C, x as m, y as T, z as d, c as f, r as S, s as p, t as I, H as g, I as k, m as x, L as H, O as P, v as b, P as w, S as M, T as O, n as v, o as D, p as E, U as L, k as R, l as q, d as y, e as z, u as B, g as U, f as j } from "./F0AiChat-c00n76c6.js";
+import { defaultTranslations as G } from "./i18n-provider-defaults.js";
+import { A as K, F as N, c as Q, b as W, a as X, o as Y, u as Z } from "./F0HILActionConfirmation-B5YWkhyV.js";
 export {
   e as A,
-  y as AiChatTranslationsProvider,
-  o as Blockquote,
-  t as ChatSpinner,
-  n as Em,
-  i as F0ActionItem,
-  r as F0AiChat,
-  l as F0AiChatProvider,
-  c as F0AiChatTextArea,
-  A as F0AiCollapsibleMessage,
-  u as F0AiFullscreenChat,
-  G as F0AuraVoiceAnimation,
-  J as F0HILActionConfirmation,
-  F as F0MessageSources,
-  h as F0OneIcon,
-  C as F0OneSwitch,
-  T as F0Thinking,
-  d as FullscreenChatContext,
-  m as H1,
-  I as H2,
-  f as H3,
+  K as AiChatTranslationsProvider,
+  t as Blockquote,
+  n as ChatSpinner,
+  o as Em,
+  i as EntityRef,
+  r as F0ActionItem,
+  l as F0AiChat,
+  c as F0AiChatProvider,
+  A as F0AiChatTextArea,
+  u as F0AiCollapsibleMessage,
+  F as F0AiFullscreenChat,
+  N as F0AuraVoiceAnimation,
+  h as F0DataDownload,
+  Q as F0HILActionConfirmation,
+  C as F0MessageSources,
+  m as F0OneIcon,
+  T as F0OneSwitch,
+  d as F0Thinking,
+  f as FullscreenChatContext,
+  S as H1,
+  p as H2,
+  I as H3,
   g as Hr,
-  S as I18nProvider,
-  p as Image,
-  x as Li,
-  H as Ol,
-  P,
-  b as Pre,
-  k as Strong,
+  k as I18nProvider,
+  x as Image,
+  H as Li,
+  P as Ol,
+  b as P,
+  w as Pre,
+  M as Strong,
   O as Table,
-  v as Td,
-  w as Th,
-  M as Ul,
-  K as actionItemStatuses,
-  N as aiTranslations,
-  R as defaultTranslations,
-  E as downloadTableAsExcel,
-  L as f0MarkdownRenderers,
-  Q as oneIconSizes,
-  q as useAiChat,
-  W as useAiChatTranslations,
-  B as useDefaultCopilotActions,
-  U as useI18n,
-  j as useMessageSourcesAction,
-  z as useOrchestratorThinkingAction
+  v as TableSimple,
+  D as Td,
+  E as Th,
+  L as Ul,
+  W as actionItemStatuses,
+  X as aiTranslations,
+  G as defaultTranslations,
+  R as f0MarkdownRenderers,
+  q as f0MarkdownRenderersSimple,
+  Y as oneIconSizes,
+  y as useAiChat,
+  Z as useAiChatTranslations,
+  z as useDefaultCopilotActions,
+  B as useI18n,
+  U as useMessageSourcesAction,
+  j as useOrchestratorThinkingAction
 };

package/dist/experimental.d.ts

@@ -423,6 +423,19 @@ 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;
@@ -434,6 +447,28 @@ declare type AiChatProviderProps = {
     tracking?: AiChatTrackingOptions;
 } & Pick<CopilotKitProps, "agent" | "credentials" | "children" | "runtimeUrl" | "showDevConsole" | "threadId" | "headers">;
 
+/**
+ * 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.
+ */
+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
  */
@@ -2548,9 +2583,12 @@ 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";
@@ -2911,6 +2949,22 @@ export declare type enhanceTextParams = {
 
 export declare type EntityId = number | string;
 
+/**
+ * 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`).
+ */
+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[]>;
+};
+
 export declare const EntitySelect: <T>(props: EntitySelectProps<T> & {
     children?: React.ReactNode;
 }) => JSX_2.Element;
@@ -5075,6 +5129,18 @@ declare type PersonAvatarVariant = Extract<AvatarVariant, {
  */
 declare const PersonItem: ForwardRefExoticComponent<EmployeeItemProps & RefAttributes<HTMLLIElement>>;
 
+/**
+ * Profile data for a person entity (employee), resolved asynchronously
+ * and displayed in the entity reference hover card.
+ */
+declare type PersonProfile = {
+    id: string | number;
+    firstName: string;
+    lastName: string;
+    avatarUrl?: string;
+    jobTitle?: string;
+};
+
 export declare const PieChartWidget: ForwardRefExoticComponent<Omit<WidgetProps_2 & {
 chart: PieChartProps;
 } & RefAttributes<HTMLDivElement>, "ref"> & RefAttributes<HTMLElement | SVGElement>>;
@@ -6771,9 +6837,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;
         };
     }
 }
@@ -6781,8 +6846,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;
         };
     }
 }