@factorialco/f0-react 1.454.0 → 1.456.0

package/dist/f0.d.ts

@@ -25,6 +25,7 @@ import { ChartPropsBase } from './utils/types';
 import { ClassValue } from 'cva';
 import { CompanyCellValue } from './f0';
 import { CompanyCellValue as CompanyCellValue_2 } from './types/company';
+import { CompanyItemProps } from './types';
 import { ComponentProps } from 'react';
 import { ComponentType } from 'react';
 import { CompoundCellValue } from './types/compound';
@@ -42,6 +43,7 @@ import { DotTagCellValue } from './f0';
 import { DotTagCellValue as DotTagCellValue_2 } from './types/dotTag';
 import type * as echarts_2 from 'echarts';
 import { Editor } from '@tiptap/react';
+import { EmployeeItemProps } from './types';
 import { F0AnalyticsDashboardProps as F0AnalyticsDashboardProps_2 } from './types';
 import { F0AvatarCompanyProps as F0AvatarCompanyProps_2 } from './types';
 import { F0AvatarDateProps } from './F0AvatarDate';
@@ -90,6 +92,7 @@ import { InputProps } from '@copilotkit/react-ui';
 import { internalAvatarColors as internalAvatarColors_2 } from './f0';
 import { internalAvatarSizes as internalAvatarSizes_2 } from './f0';
 import { internalAvatarTypes as internalAvatarTypes_2 } from './f0';
+import { ItemProps } from './types';
 import { JSONContent } from '@tiptap/react';
 import { JSONContent as JSONContent_2 } from '@tiptap/core';
 import { JSX as JSX_2 } from 'react';
@@ -117,6 +120,7 @@ import * as React_2 from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import * as RechartsPrimitive from 'recharts';
+import { Ref } from 'react';
 import { RefAttributes } from 'react';
 import { RefObject } from 'react';
 import { RemoteAudioTrack } from 'livekit-client';
@@ -127,14 +131,22 @@ import { StatusCellValue as StatusCellValue_2 } from './types/status';
 import { SummaryCellValue } from './types/summary';
 import { SVGProps } from 'react';
 import * as SwitchPrimitive from '@radix-ui/react-switch';
+import { TagAlertProps as TagAlertProps_2 } from './f0';
+import { TagBalanceProps as TagBalanceProps_2 } from './f0';
 import { TagCellValue } from './f0';
 import { TagCellValue as TagCellValue_2 } from './types/tag';
+import { TagDotProps as TagDotProps_2 } from './f0';
 import { TagListCellValue } from './f0';
 import { TagListCellValue as TagListCellValue_2 } from './types/tagList';
+import { TagListProps as TagListProps_2 } from './f0';
+import { TagRawProps as TagRawProps_2 } from './f0';
+import { TagStatusProps as TagStatusProps_2 } from './f0';
 import { TagType as TagType_2 } from './types';
+import { TagType as TagType_3 } from './f0';
 import { TagVariant as TagVariant_2 } from './F0Tag';
 import { TeamCellValue } from './f0';
 import { TeamCellValue as TeamCellValue_2 } from './types/team';
+import { TeamItemProps } from './types';
 import { TextCellValue } from './f0';
 import { TextCellValue as TextCellValue_2 } from './types/text';
 import { TrackReferenceOrPlaceholder } from '@livekit/components-react';
@@ -512,6 +524,11 @@ export declare type AiChatProviderProps = {
      * URL builders (navigation links) for each entity type.
      */
     entityRefs?: EntityRefs;
+    /**
+     * Canvas action callbacks grouped by entity type.
+     * Provides save/create functions for persisting canvas entities externally.
+     */
+    canvasActions?: CanvasActions;
     /**
      * Available tool hints that the user can activate to provide intent context
      * to the AI. Renders a selector button next to the send button.
@@ -599,8 +616,14 @@ declare type AiChatProviderReturnValue = {
      * 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[]) => void;
+    appendMessages: (messages: AppendMessage[], options?: {
+        persist?: boolean;
+    }) => void;
     /* Excluded from this release type: setAppendMessagesFunction */
     /**
      * Atomically clear the conversation and inject new messages.
@@ -666,7 +689,14 @@ declare type AiChatProviderReturnValue = {
      */
     fileDragOver: boolean;
     /* Excluded from this release type: setFileDragOver */
-} & Pick<AiChatState, "greeting" | "agent" | "disclaimer" | "resizable" | "entityRefs" | "toolHints" | "credits" | "creditWarning" | "fileAttachments"> & {
+    /**
+     * Pre-loaded context shown as an empty state in the chat.
+     * Prepended to the first user message as `<pending-context>`.
+     */
+    pendingContext: PendingContext | null;
+    /** Set pending context (pass null to clear) */
+    setPendingContext: React.Dispatch<React.SetStateAction<PendingContext | null>>;
+} & Pick<AiChatState, "greeting" | "agent" | "disclaimer" | "resizable" | "entityRefs" | "canvasActions" | "toolHints" | "credits" | "creditWarning" | "fileAttachments"> & {
     /** The current canvas content, or null when canvas is closed */
     canvasContent: CanvasContent | null;
     /** Open the canvas panel with the given content */
@@ -696,6 +726,7 @@ declare interface AiChatState {
     footer?: React.ReactNode;
     VoiceMode?: React.ComponentType;
     entityRefs?: EntityRefs;
+    canvasActions?: CanvasActions;
     toolHints?: AiChatToolHint[];
     credits?: AiChatCredits;
     creditWarning?: AiChatCreditWarning;
@@ -858,6 +889,19 @@ export declare const aiTranslations: {
         readonly formCard: {
             readonly moreFields: "Open to see all fields";
         };
+        readonly dashboard: {
+            readonly save: "Save";
+            readonly saveToAnalytics: "Save the dashboard in Analytics";
+            readonly saveAs: "Save as";
+            readonly saveDialog: {
+                readonly title: "Save dashboard";
+                readonly titleLabel: "Title";
+                readonly descriptionLabel: "Description";
+                readonly descriptionPlaceholder: "Add a description (optional)";
+                readonly save: "Save";
+                readonly cancel: "Cancel";
+            };
+        };
         readonly dataDownload: {
             readonly title: "Download";
             readonly download: "Download {{format}}";
@@ -984,13 +1028,26 @@ export declare type AppendMessage = {
     role: "user" | "assistant";
     content: string;
     toolCalls?: AppendToolCall[];
+} | {
+    /** Tool result message — pairs with a toolCall from a previous assistant message */
+    role: "tool";
+    content: string;
+    /**
+     * ID of the paired tool call. Must equal the corresponding assistant
+     * message's `toolCalls[i].id` — supply `AppendToolCall.id` on that call
+     * and pass the same value here so the messages are correctly paired.
+     */
+    toolCallId: string;
 };
 
 /**
  * A tool call to inject via appendMessages.
- * IDs are generated internally — callers only provide the function payload.
+ * IDs are generated internally unless `id` is provided.
+ * When pairing with a tool-result message, provide the same `id`
+ * in both the tool call and the tool-result's `toolCallId`.
  */
 export declare type AppendToolCall = {
+    id?: string;
     function: {
         name: string;
         arguments: string;
@@ -1721,6 +1778,15 @@ declare type CandidateProfile = {
     source?: string;
 };
 
+/**
+ * Canvas-level action callbacks grouped by entity type.
+ * Each entity defines its own actions type; this aggregates them.
+ * Passed by the host app to F0AiChatProvider via `canvasActions`.
+ */
+export declare type CanvasActions = {
+    dashboard?: DashboardCanvasActions;
+};
+
 /**
  * Discriminated union for canvas panel content.
  * Add new entity types to this union as they are implemented.
@@ -2857,6 +2923,16 @@ declare interface CustomFieldRenderPropsBase {
 
 export declare const Dashboard: WithDataTestIdReturnType_3<ComponentType<DashboardProps_2> & PageLayoutGroupComponent_2>;
 
+/**
+ * Callbacks for persisting dashboards externally (beyond chat history).
+ */
+declare type DashboardCanvasActions = {
+    /** Update an existing saved dashboard */
+    save: (id: string, category: string, config: ChatDashboardConfig) => Promise<void>;
+    /** Create a new saved dashboard. Returns the new dashboard ID if available. */
+    create: (title: string, description: string, config: ChatDashboardConfig, category?: string) => Promise<string | void>;
+};
+
 /**
  * Dashboard canvas content — renders an analytics dashboard.
  */
@@ -2867,6 +2943,14 @@ export declare type DashboardCanvasContent = CanvasContentBase & {
         baseUrl: string;
         headers: Record<string, string>;
     };
+    /** Present when the dashboard is a pre-saved dashboard */
+    savedDashboardId?: string;
+    /** Category of the saved dashboard */
+    savedDashboardCategory?: string;
+    /** Description of the saved dashboard */
+    savedDashboardDescription?: string;
+    /** True when the agent has iterated on a saved dashboard but the user hasn't saved yet */
+    savedDashboardUnsaved?: boolean;
 };
 
 /**
@@ -3220,6 +3304,27 @@ export declare interface DataError {
     cause?: unknown;
 }
 
+declare const DataList: ForwardRefExoticComponent<DataListProps & RefAttributes<HTMLUListElement>> & {
+    Item: ForwardRefExoticComponent<ItemProps & RefAttributes<HTMLLIElement>>;
+    CompanyItem: ForwardRefExoticComponent<CompanyItemProps & RefAttributes<HTMLLIElement>>;
+    PersonItem: ForwardRefExoticComponent<EmployeeItemProps & RefAttributes<HTMLLIElement>>;
+    TeamItem: ForwardRefExoticComponent<TeamItemProps & RefAttributes<HTMLLIElement>>;
+    DotTagItem: ForwardRefExoticComponent<TagDotProps_2 & RefAttributes<HTMLLIElement>>;
+    AlertTagItem: ForwardRefExoticComponent<TagAlertProps_2 & RefAttributes<HTMLLIElement>>;
+    BalanceTagItem: ForwardRefExoticComponent<TagBalanceProps_2 & RefAttributes<HTMLLIElement>>;
+    StatusTagItem: ForwardRefExoticComponent<TagStatusProps_2 & RefAttributes<HTMLLIElement>>;
+    RawTagItem: ForwardRefExoticComponent<TagRawProps_2 & RefAttributes<HTMLLIElement>>;
+    TagListItem: <T extends TagType_3>(props: TagListProps_2<T> & {
+        ref?: Ref<HTMLLIElement>;
+    }) => ReturnType<(<T_1 extends TagType_3>(props: TagListProps_2<T_1>, ref: ForwardedRef<HTMLLIElement>) => JSX_2.Element)>;
+};
+
+declare type DataListProps = {
+    children: ReactElement | ReactElement[];
+    label?: string;
+    isHorizontal?: boolean;
+};
+
 /**
  * Represents a data source with filtering capabilities and data fetching functionality.
  * Extends DataSourceDefinition with runtime properties for state management.
@@ -3956,6 +4061,19 @@ export declare const defaultTranslations: {
         readonly formCard: {
             readonly moreFields: "Open to see all fields";
         };
+        readonly dashboard: {
+            readonly save: "Save";
+            readonly saveToAnalytics: "Save the dashboard in Analytics";
+            readonly saveAs: "Save as";
+            readonly saveDialog: {
+                readonly title: "Save dashboard";
+                readonly titleLabel: "Title";
+                readonly descriptionLabel: "Description";
+                readonly descriptionPlaceholder: "Add a description (optional)";
+                readonly save: "Save";
+                readonly cancel: "Cancel";
+            };
+        };
         readonly dataDownload: {
             readonly title: "Download";
             readonly download: "Download {{format}}";
@@ -4186,6 +4304,8 @@ export declare const defaultTranslations: {
         };
     };
     readonly forms: {
+        readonly yes: "Yes";
+        readonly no: "No";
         readonly actionBar: {
             readonly unsavedChanges: "You have changes pending to be saved";
             readonly saving: "Saving...";
@@ -4284,6 +4404,36 @@ declare interface DeleteBlockNotesTextEditorPageDocumentPatch {
  */
 export declare function describeFormSchema(schema: F0FormSchema): FormFieldDescription[];
 
+declare type DetailsItemContent = (ComponentProps<typeof DataList.Item> & {
+    type: "item";
+}) | (ComponentProps<typeof DataList.PersonItem> & {
+    type: "person";
+}) | (ComponentProps<typeof DataList.CompanyItem> & {
+    type: "company";
+}) | (ComponentProps<typeof DataList.TeamItem> & {
+    type: "team";
+}) | (ComponentProps<typeof Weekdays> & {
+    type: "weekdays";
+}) | (ComponentProps<typeof DataList.DotTagItem> & {
+    type: "dot-tag";
+}) | (TagAlertProps & {
+    type: "alert-tag";
+}) | (TagBalanceProps & {
+    type: "balance-tag";
+}) | (TagStatusProps & {
+    type: "status-tag";
+}) | (TagRawProps & {
+    type: "raw-tag";
+}) | {
+    [T in TagType]: {
+        type: "tag-list";
+        tagList: TagListProps<T>;
+    };
+}[TagType] | {
+    type: "avatar-list";
+    avatarList: F0AvatarListProps;
+};
+
 export declare type DialogPosition = (typeof dialogPositions)[number];
 
 declare const dialogPositions: readonly ["center", "left", "right", "fullscreen"];
@@ -4735,7 +4885,7 @@ 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, historyEnabled, footer, VoiceMode, entityRefs, toolHints, credits, creditWarning, fileAttachments, onThumbsUp, onThumbsDown, children, agent, tracking, ...copilotKitProps }: AiChatProviderProps) => JSX_2.Element;
+export declare const F0AiChatProvider: ({ enabled, greeting, initialMessage, welcomeScreenSuggestions, disclaimer, resizable, defaultVisualizationMode, lockVisualizationMode, historyEnabled, footer, VoiceMode, entityRefs, canvasActions, toolHints, credits, creditWarning, fileAttachments, onThumbsUp, onThumbsDown, children, agent, tracking, ...copilotKitProps }: AiChatProviderProps) => JSX_2.Element;
 
 export declare const F0AiChatTextArea: ({ submitLabel, inProgress, onSend, onStop, creditWarning, }: ChatTextareaProps) => JSX_2.Element;
 
@@ -8378,6 +8528,23 @@ declare type FormCanvasContent = CanvasContentBase & {
     formModule?: ModuleId;
 };
 
+export declare interface FormCardValueFormatterEntry<T = unknown> {
+    /** Scope to a specific form. Omit to apply to all forms. */
+    formName?: string;
+    /** Scope to a specific custom field name. Omit to apply to all fields. */
+    customFieldName?: string;
+    /** Format function. Return `undefined` to fall back to built-in formatting. */
+    format: (value: T, meta: {
+        key: string;
+        fieldType?: string;
+        customFieldName?: string;
+    }) => DetailsItemContent | DetailsItemContent[] | undefined;
+}
+
+export declare function FormCardValueFormatterProvider({ children, }: {
+    children: ReactNode;
+}): JSX_2.Element;
+
 /* Excluded from this release type: FormDefinitionItem */
 
 /**
@@ -10210,6 +10377,19 @@ declare type PathsToStringProps<T> = T extends string ? [] : {
     [K in Extract<keyof T, string>]: [K, ...PathsToStringProps<T[K]>];
 }[Extract<keyof T, string>];
 
+/**
+ * Pre-loaded context shown as an empty state in the chat.
+ * The `context` string is prepended to the user's first message
+ * as `<pending-context>...</pending-context>` so the agent receives it.
+ * The conversation is not created until the user actually sends a message.
+ */
+declare type PendingContext = {
+    /** Human-readable label shown in the empty state (e.g. "Expenses dashboard") */
+    label: string;
+    /** Full context string prepended invisibly to the first user message */
+    context: string;
+};
+
 /**
  * Creates a union of `[sectionId, data]` pairs for each key in T.
  * Used to build a callback where TypeScript narrows `data` based on `sectionId`.
@@ -11147,6 +11327,8 @@ export declare const selectSizes: readonly ["sm", "md"];
  */
 declare type SelectValueType = string | number;
 
+declare type SetFormCardValueFormatter = <T = unknown>(entry: FormCardValueFormatterEntry<T>) => void;
+
 /**
  * @experimental This is an experimental component use it at your own risk
  */
@@ -12496,6 +12678,17 @@ export declare interface UseF0FormReturn {
  */
 export declare type UseFileUpload = () => FileUploadHookReturn;
 
+/**
+ * Returns a resolved formatter for the given `formName`.
+ * Matches registered formatters by specificity:
+ *   formName + customFieldName > formName only > customFieldName only > global
+ * Returns `null` when no provider is present or no formatters are registered.
+ */
+export declare function useFormCardValueFormatter(formName: string): ((key: string, value: unknown, meta: {
+    fieldType?: string;
+    customFieldName?: string;
+}) => DetailsItemContent | DetailsItemContent[] | undefined) | null;
+
 export declare const useFormComponent: () => F0FormLikeComponent | undefined;
 
 export declare const useGroups: <R extends RecordType>(groups: GroupRecord<R>[], defaultOpenGroups?: boolean | GroupRecord<R>["key"][]) => {
@@ -12648,6 +12841,27 @@ export declare type UseSelectableReturn<R extends RecordType, Filters extends Fi
     handleSelectGroupChange: (groupOrId: GroupRecord<R> | SelectionId | readonly SelectionId[], checked: boolean) => void;
 };
 
+/**
+ * Returns a setter to register value formatters used by FormCard.
+ *
+ * ```ts
+ * const setFormatter = useSetFormCardValueFormatter()
+ *
+ * // Global formatter (all forms, all fields)
+ * setFormatter({ format: (value) => ({ type: "item", text: String(value) }) })
+ *
+ * // Scoped to a form
+ * setFormatter({ formName: "create-task", format: (value) => ... })
+ *
+ * // Scoped to a custom field name (across all forms)
+ * setFormatter({ customFieldName: "assignees_selector", format: (value) => ... })
+ *
+ * // Scoped to both
+ * setFormatter({ formName: "create-task", customFieldName: "assignees_selector", format: (value) => ... })
+ * ```
+ */
+export declare function useSetFormCardValueFormatter(): SetFormCardValueFormatter;
+
 export declare const useXRay: () => {
     enabled: boolean;
     filter: ComponentTypes[];
@@ -12754,6 +12968,13 @@ declare type VisualizationSettings = {
     [K in keyof typeof collectionVisualizations]: ExtractVisualizationSettings<(typeof collectionVisualizations)[K]>;
 };
 
+declare const Weekdays: ForwardRefExoticComponent<WeekdaysProps & RefAttributes<HTMLDivElement>>;
+
+declare interface WeekdaysProps {
+    activatedDays?: number[];
+    daysOfTheWeek?: string[];
+}
+
 export declare const WeekStartDay: {
     readonly Sunday: 0;
     readonly Monday: 1;
@@ -12875,6 +13096,11 @@ declare module "gridstack" {
 }
 
 
+declare namespace Calendar {
+    var displayName: string;
+}
+
+
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
         aiBlock: {
@@ -12922,8 +13148,3 @@ declare module "@tiptap/core" {
         };
     }
 }
-
-
-declare namespace Calendar {
-    var displayName: string;
-}