@factorialco/f0-react 1.449.2 → 1.450.0

package/dist/f0.d.ts

@@ -854,6 +854,9 @@ export declare const aiTranslations: {
             readonly reportLabel: "Report";
             readonly openButton: "Open";
         };
+        readonly formCard: {
+            readonly moreFields: "Open to see all fields";
+        };
         readonly dataDownload: {
             readonly title: "Download";
             readonly download: "Download {{format}}";
@@ -1721,7 +1724,7 @@ declare type CandidateProfile = {
  * Discriminated union for canvas panel content.
  * Add new entity types to this union as they are implemented.
  */
-export declare type CanvasContent = DashboardCanvasContent | DataDownloadCanvasContent;
+export declare type CanvasContent = DashboardCanvasContent | FormCanvasContent | DataDownloadCanvasContent;
 
 /**
  * Base shape shared by all canvas content types.
@@ -1730,6 +1733,7 @@ export declare type CanvasContent = DashboardCanvasContent | DataDownloadCanvasC
 export declare type CanvasContentBase = {
     type: string;
     title: string;
+    description?: string;
     toolCallId?: string;
 };
 
@@ -1766,6 +1770,11 @@ export declare type CanvasEntityDefinition<T extends CanvasContentBase = CanvasC
         content: T;
         children: ReactNode;
     }) => ReactNode;
+    /**
+     * When true the content area uses `overflow-hidden` instead of
+     * `overflow-auto`, letting the entity manage its own scrolling.
+     */
+    overflowHidden?: boolean;
 };
 
 declare type CardAvatarVariant = AvatarVariant | {
@@ -3665,6 +3674,7 @@ export declare const defaultTranslations: {
         readonly expand: "Expand";
         readonly showAll: "Show all";
         readonly showLess: "Show less";
+        readonly seeMore: "See more";
         readonly skipToContent: "Skip to content";
         readonly view: "View";
         readonly unselect: "Unselect";
@@ -3942,6 +3952,9 @@ export declare const defaultTranslations: {
             readonly reportLabel: "Report";
             readonly openButton: "Open";
         };
+        readonly formCard: {
+            readonly moreFields: "Open to see all fields";
+        };
         readonly dataDownload: {
             readonly title: "Download";
             readonly download: "Download {{format}}";
@@ -4681,13 +4694,13 @@ export declare interface F0AiAvailableFormDefinition<TParams extends Record<stri
     schema: F0FormSchema;
     /**
      * Default values for the form fields.
-     * Can be a static object or a function that receives params (supplied by the AI via presentForm)
+     * Can be a static object or a function that receives params (supplied by the AI)
      * and returns the defaults.
      */
     defaultValues?: Record<string, unknown> | ((params: TParams) => Record<string, unknown>);
     /**
      * Zod schema that describes the params accepted by a functional `defaultValues`.
-     * When provided, the AI will see this schema and can supply params when calling presentForm.
+     * When provided, the AI will see this schema and can supply params.
      * Params are validated against this schema before being passed to `defaultValues`.
      */
     defaultValuesParamsSchema?: ZodType<TParams>;
@@ -4699,8 +4712,14 @@ export declare interface F0AiAvailableFormDefinition<TParams extends Record<stri
     title?: string;
     /** Description shown under the title in dialog mode */
     description?: string;
+    /** Module associated with this form (for avatar display in canvas cards) */
+    module?: ModuleId;
     /** Wizard steps (required for wizard mode to work with multiple steps) */
     steps?: F0WizardFormStep[];
+    /** Submit button configuration (label, icon, etc.) */
+    submitConfig?: F0FormSubmitConfig;
+    /** When to trigger validation errors */
+    errorTriggerMode?: F0FormErrorTriggerMode;
 }
 
 /**
@@ -4715,64 +4734,97 @@ export declare const F0AiChatProvider: ({ enabled, greeting, initialMessage, wel
 
 export declare const F0AiChatTextArea: ({ submitLabel, inProgress, onSend, onStop, creditWarning, }: ChatTextareaProps) => JSX_2.Element;
 
+/**
+ * Context value for the AI form registry
+ */
+/** Full runtime description of a form (used for formsOnCurrentPage and activeForm) */
+declare interface F0AiFormDescription {
+    formName: string;
+    description?: string;
+    module?: ModuleId;
+    /** Custom title for the card (set via fillForm) */
+    cardTitle: string;
+    /** Custom description for the card (set via fillForm) */
+    cardDescription: string;
+    formSchema: Record<string, unknown>;
+    fieldDescriptions: Record<string, {
+        label: string;
+        section?: string;
+        placeholder?: string;
+        helpText?: string;
+        description?: string;
+        fieldType?: string;
+    }>;
+    sectionDescriptions: Record<string, {
+        title: string;
+        description?: string;
+    }>;
+    formValues: Record<string, unknown>;
+    formErrors: Record<string, unknown>;
+    isDirty: boolean;
+    /** JSON Schema of defaultValuesParams (only for forms with defaultValuesParamsSchema) */
+    defaultValuesParamsSchema?: Record<string, unknown>;
+}
+
 /**
  * Entry in the AI form registry
  */
 export declare interface F0AiFormEntry {
     ref: React.MutableRefObject<F0FormRef | null>;
     schema: F0FormSchema;
+    /** Human-readable description of the form's purpose */
+    description?: string;
+    /** Module associated with this form (for avatar display in canvas cards) */
+    module?: ModuleId;
     /** Whether this entry was registered from an availableFormDefinition (not a rendered form) */
     virtual?: boolean;
     /** Section configs (title, description) keyed by section ID */
     sections?: Record<string, F0SectionConfig>;
-    /** Zod schema for params accepted by presentForm (virtual entries only) */
+    /** Zod schema for params accepted by the AI (virtual entries only) */
     defaultValuesParamsSchema?: ZodType;
     /** Raw defaultValues function that accepts params (from rendered forms with defaultValuesParamsSchema) */
     defaultValuesFn?: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
     /** Field names explicitly set via setValue/setValues on a virtual ref */
     dirtyFields?: Set<string>;
+    /** Consumer submit callback (from availableFormDefinition). Preserved across virtual ↔ rendered transitions. */
+    onSubmit?: (values: Record<string, unknown>) => void | Promise<void>;
+    /** Wizard steps (for multi-step form rendering) */
+    steps?: F0WizardFormStep[];
+    /** Submit button configuration (label, icon, etc.) */
+    submitConfig?: F0FormSubmitConfig;
+    /** When to trigger validation errors */
+    errorTriggerMode?: F0FormErrorTriggerMode;
 }
 
-/**
- * Context value for the AI form registry
- */
 declare interface F0AiFormRegistryContextValue {
-    register: (name: string, ref: React.MutableRefObject<F0FormRef | null>, schema: F0FormSchema, sections?: Record<string, F0SectionConfig>, defaultValuesParamsSchema?: ZodType, defaultValuesFn?: (params: Record<string, unknown>) => Promise<Record<string, unknown>>) => void;
+    register: (name: string, ref: React.MutableRefObject<F0FormRef | null>, schema: F0FormSchema, sections?: Record<string, F0SectionConfig>, defaultValuesParamsSchema?: ZodType, defaultValuesFn?: (params: Record<string, unknown>) => Promise<Record<string, unknown>>, description?: string, module?: ModuleId) => void;
     unregister: (name: string) => void;
     get: (name: string) => F0AiFormEntry | undefined;
     getFormNames: () => string[];
     /** Rebuild the form descriptions snapshot (call after mutating form state) */
     rebuildDescriptions: () => void;
-    /** Structured descriptions of all active forms, updated on register/unregister */
-    formDescriptions: {
-        formName: string;
-        formSchema: Record<string, unknown>;
-        fieldDescriptions: Record<string, {
-            label: string;
-            section?: string;
-            placeholder?: string;
-            helpText?: string;
-            description?: string;
-        }>;
-        sectionDescriptions: Record<string, {
-            title: string;
-            description?: string;
-        }>;
-        formValues: Record<string, unknown>;
-        formErrors: Record<string, unknown>;
-        isDirty: boolean;
-        /** JSON Schema of defaultValuesParams accepted by presentForm (only for forms with defaultValuesParamsSchema) */
-        defaultValuesParamsSchema?: Record<string, unknown>;
-    }[];
-    /** Currently AI-presented form, or null */
-    presentedForm: F0AiPresentedForm | null;
-    /** Called by the AI tool to present a form */
-    presentForm: (formName: string, mode: "dialog" | "wizard", defaultValuesParams?: Record<string, unknown>) => {
+    /** Full runtime state of all rendered (non-virtual) forms on the current page */
+    formsOnCurrentPage: F0AiFormDescription[];
+    /** Full runtime state of all virtual/available forms */
+    availableForms: F0AiFormDescription[];
+    /** Full runtime state of the form the AI is actively co-editing, or null */
+    activeForm: F0AiFormDescription | null;
+    /** Set an available form as the active co-editing form */
+    setActiveForm: (formName: string, cardMeta?: {
+        cardTitle: string;
+        cardDescription: string;
+    }) => {
         success: boolean;
         error?: string;
     };
-    /** Called when the presented form is closed (submit/cancel) */
-    dismissForm: () => void;
+    /** Clear the active co-editing form (e.g. after submit) */
+    clearActiveForm: () => void;
+    /** Bump the fill-version counter for a form (called after fillForm succeeds) */
+    incrementFillVersion: (formName: string) => void;
+    /** Reset the fill-version counter for a form (e.g. after submit) */
+    resetFillVersion: (formName: string) => void;
+    /** Get the fill-version counter for a form (0 = never filled) */
+    getFillVersion: (formName: string) => number;
 }
 
 /**
@@ -4846,20 +4898,6 @@ export declare class F0AiMask {
     private render;
 }
 
-/**
- * Tracks an AI-presented form (opened via the presentForm tool)
- */
-export declare interface F0AiPresentedForm {
-    /** Name of the form (matches an availableFormDefinition) */
-    name: string;
-    /** Render mode chosen by the LLM */
-    mode: "dialog" | "wizard";
-    /** Resolved definition from availableFormDefinitions */
-    definition: F0AiAvailableFormDefinition;
-    /** Snapshot of the virtual form's values at the time presentForm was called */
-    initialValues: Record<string, unknown>;
-}
-
 export declare const F0Alert: WithDataTestIdReturnType_3<({ title, description, action, link, icon, variant, onClose, }: F0AlertProps) => JSX_2.Element>;
 
 export declare interface F0AlertProps {
@@ -6507,6 +6545,10 @@ export declare type F0FormDefinition<T extends F0FormSchema_2 | F0PerSectionSche
 export declare interface F0FormDefinitionPerSection<T extends F0PerSectionSchema_2> {
     /* Excluded from this release type: _brand */
     name: string;
+    /** Human-readable description of the form's purpose */
+    description?: string;
+    /** Module associated with this form (for avatar display in canvas cards) */
+    module?: ModuleId;
     schema: T;
     sections?: Record<string, F0PerSectionSectionConfig>;
     defaultValues?: {
@@ -6523,11 +6565,17 @@ export declare interface F0FormDefinitionPerSection<T extends F0PerSectionSchema
     defaultValuesFn?: (params: Record<string, unknown>) => Promise<{
         [K in keyof T]?: Partial<z.infer<T[K]>>;
     }>;
+    /** Wizard steps — when present, F0WizardForm uses these instead of auto-deriving from sections */
+    steps?: F0WizardFormStep[];
 }
 
 export declare interface F0FormDefinitionSingleSchema<TSchema extends F0FormSchema_2> {
     /* Excluded from this release type: _brand */
     name: string;
+    /** Human-readable description of the form's purpose */
+    description?: string;
+    /** Module associated with this form (for avatar display in canvas cards) */
+    module?: ModuleId;
     schema: TSchema;
     sections?: Record<string, F0SectionConfig>;
     defaultValues?: Partial<z.infer<TSchema>>;
@@ -6540,6 +6588,8 @@ export declare interface F0FormDefinitionSingleSchema<TSchema extends F0FormSche
     defaultValuesParamsSchema?: ZodType;
     /** Raw defaultValues function for AI registry use when params are involved */
     defaultValuesFn?: (params: Record<string, unknown>) => Promise<Partial<z.infer<TSchema>>>;
+    /** Wizard steps — when present, F0WizardForm uses these instead of auto-deriving from sections */
+    steps?: F0WizardFormStep[];
 }
 
 /**
@@ -6791,6 +6841,10 @@ export declare interface F0FormPropsWithPerSectionSchema<T extends F0PerSectionS
 export declare interface F0FormPropsWithSingleSchema<TSchema extends F0FormSchema> {
     /** Unique name for the form, used for generating anchor links */
     name: string;
+    /** Human-readable description of the form's purpose */
+    description?: string;
+    /** Module associated with this form (for avatar display in canvas cards) */
+    module?: ModuleId;
     /** Zod object schema with F0 field configurations */
     schema: TSchema;
     /** Section configurations keyed by section ID */
@@ -8270,6 +8324,16 @@ declare type FormatPreset = {
     type: "compact";
 };
 
+/**
+ * Form canvas content — renders an interactive F0Form in the canvas panel.
+ */
+declare type FormCanvasContent = CanvasContentBase & {
+    type: "form";
+    formName: string;
+    formDescription?: string;
+    formModule?: ModuleId;
+};
+
 /* Excluded from this release type: FormDefinitionItem */
 
 /**
@@ -12245,11 +12309,17 @@ export declare function useF0FormDefinition<T extends F0PerSectionSchema_2, TPar
 /** Base fields shared by all per-section input variants */
 declare interface UseF0FormDefinitionPerSectionInputBase<T extends F0PerSectionSchema_2> {
     name: string;
+    /** Human-readable description of the form's purpose */
+    description?: string;
+    /** Module associated with this form (for avatar display in canvas cards) */
+    module?: ModuleId;
     schema: T;
     sections?: Record<string, F0PerSectionSectionConfig>;
     onSubmit: (arg: F0WizardFormPerSectionSubmitArg<T>) => Promise<F0FormSubmitResult> | F0FormSubmitResult;
     submitConfig?: F0PerSectionSubmitConfig;
     errorTriggerMode?: F0FormErrorTriggerMode;
+    /** Wizard steps — when present, F0WizardForm uses these instead of auto-deriving from sections */
+    steps?: F0WizardFormStep[];
 }
 
 /** Per-section input WITHOUT `defaultValuesParamsSchema` */
@@ -12273,11 +12343,17 @@ declare interface UseF0FormDefinitionPerSectionInputWithParams<T extends F0PerSe
 /** Base fields shared by all single-schema input variants */
 declare interface UseF0FormDefinitionSingleSchemaInputBase<TSchema extends F0FormSchema_2> {
     name: string;
+    /** Human-readable description of the form's purpose */
+    description?: string;
+    /** Module associated with this form (for avatar display in canvas cards) */
+    module?: ModuleId;
     schema: TSchema;
     sections?: Record<string, F0SectionConfig>;
     onSubmit: (arg: F0WizardFormSingleSubmitArg<TSchema>) => Promise<F0FormSubmitResult> | F0FormSubmitResult;
     submitConfig?: F0FormSubmitConfig;
     errorTriggerMode?: F0FormErrorTriggerMode;
+    /** Wizard steps — when present, F0WizardForm uses these instead of auto-deriving from sections */
+    steps?: F0WizardFormStep[];
 }
 
 /** Single-schema input WITHOUT `defaultValuesParamsSchema` → `defaultValues` is sync or `(signal) => Promise<T>` */
@@ -12731,16 +12807,11 @@ declare module "gridstack" {
 }
 
 
-declare namespace Calendar {
-    var displayName: string;
-}
-
-
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        enhanceHighlight: {
-            setEnhanceHighlight: (from: number, to: number) => ReturnType;
-            clearEnhanceHighlight: () => ReturnType;
+        aiBlock: {
+            insertAIBlock: (data: AIBlockData, config: AIBlockConfig) => ReturnType;
+            executeAIAction: (actionType: string, config: AIBlockConfig) => ReturnType;
         };
     }
 }
@@ -12748,9 +12819,9 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        aiBlock: {
-            insertAIBlock: (data: AIBlockData, config: AIBlockConfig) => ReturnType;
-            executeAIAction: (actionType: string, config: AIBlockConfig) => ReturnType;
+        enhanceHighlight: {
+            setEnhanceHighlight: (from: number, to: number) => ReturnType;
+            clearEnhanceHighlight: () => ReturnType;
         };
     }
 }
@@ -12783,3 +12854,8 @@ declare module "@tiptap/core" {
         };
     }
 }
+
+
+declare namespace Calendar {
+    var displayName: string;
+}