@factorialco/f0-react 1.361.0 → 1.362.0

package/dist/f0.d.ts

@@ -3741,6 +3741,12 @@ declare interface F0FormDefaultSubmitConfig extends F0FormSubmitConfigBase {
      * @default "default"
      */
     type?: "default";
+    /**
+     * When true, hides the submit button.
+     * Useful when using `useF0Form` hook to submit from outside the form.
+     * @default false
+     */
+    hideSubmitButton?: boolean;
 }
 
 /**
@@ -3902,6 +3908,40 @@ export declare interface F0FormProps<TSchema extends z.ZodObject<ZodRawShape>> {
      * Controls section sidebar visibility and box wrapping.
      */
     styling?: F0FormStylingConfig;
+    /**
+     * Ref to control the form programmatically from outside.
+     * Use with the `useF0Form` hook to get a ref and submit/reset functions.
+     *
+     * @example
+     * ```tsx
+     * const { formRef, submit } = useF0Form()
+     *
+     * <F0Form formRef={formRef} ... />
+     * <Button onClick={submit}>Submit</Button>
+     * ```
+     */
+    formRef?: React.MutableRefObject<F0FormRef | null>;
+}
+
+/**
+ * Interface for the F0Form ref methods
+ */
+export declare interface F0FormRef {
+    /**
+     * Programmatically submit the form.
+     * Will only call onSubmit if validation passes.
+     * @returns Promise that resolves when submission completes (or rejects on validation failure)
+     */
+    submit: () => Promise<void>;
+    /**
+     * Reset the form to its default values
+     */
+    reset: () => void;
+    /**
+     * Check if the form has unsaved changes
+     */
+    isDirty: () => boolean;
+    /* Excluded from this release type: _setStateCallback */
 }
 
 /**
@@ -3909,6 +3949,14 @@ export declare interface F0FormProps<TSchema extends z.ZodObject<ZodRawShape>> {
  */
 export declare type F0FormSchema<T extends Record<string, ZodTypeAny>> = z.ZodObject<T>;
 
+/**
+ * Callback to update form state in the hook
+ */
+declare type F0FormStateCallback = (state: {
+    isSubmitting: boolean;
+    hasErrors: boolean;
+}) => void;
+
 /**
  * Styling configuration for the form layout and appearance
  */
@@ -7256,6 +7304,79 @@ export declare const useEmojiConfetti: () => {
 
 export declare const useF0Dialog: () => F0DialogContextType;
 
+/**
+ * Hook to control F0Form programmatically.
+ *
+ * Useful when you need to submit the form from outside the component,
+ * such as when the form is inside a dialog and the submit button is
+ * in the dialog's footer.
+ *
+ * @example
+ * ```tsx
+ * import { useF0Form, F0Form } from "@factorialco/factorial-one/experimental"
+ *
+ * function FormInDialog() {
+ *   const { formRef, submit } = useF0Form()
+ *   const [open, setOpen] = useState(false)
+ *
+ *   return (
+ *     <Dialog open={open} onOpenChange={setOpen}>
+ *       <DialogContent>
+ *         <F0Form
+ *           formRef={formRef}
+ *           name="my-form"
+ *           schema={schema}
+ *           defaultValues={defaultValues}
+ *           onSubmit={async (data) => {
+ *             // Handle submission
+ *             setOpen(false)
+ *             return { success: true }
+ *           }}
+ *         />
+ *         <DialogFooter>
+ *           <Button onClick={() => setOpen(false)}>Cancel</Button>
+ *           <Button onClick={submit}>Save</Button>
+ *         </DialogFooter>
+ *       </DialogContent>
+ *     </Dialog>
+ *   )
+ * }
+ * ```
+ */
+export declare function useF0Form(): UseF0FormReturn;
+
+/**
+ * Return type for the useF0Form hook
+ */
+export declare interface UseF0FormReturn {
+    /**
+     * Ref to pass to the F0Form component's `formRef` prop
+     */
+    formRef: React.MutableRefObject<F0FormRef | null>;
+    /**
+     * Programmatically submit the form.
+     * Will only trigger onSubmit if all validations pass.
+     * @returns Promise that resolves when submission completes
+     */
+    submit: () => Promise<void>;
+    /**
+     * Reset the form to its default values
+     */
+    reset: () => void;
+    /**
+     * Check if the form has unsaved changes
+     */
+    isDirty: () => boolean;
+    /**
+     * Whether the form is currently submitting
+     */
+    isSubmitting: boolean;
+    /**
+     * Whether the form has validation errors
+     */
+    hasErrors: boolean;
+}
+
 export declare const useGroups: <R extends RecordType>(groups: GroupRecord<R>[], defaultOpenGroups?: boolean | GroupRecord<R>["key"][]) => {
     openGroups: Record<string, boolean>;
     setGroupOpen: (key: string, open: boolean) => void;