Support for Precognition in useForm()

packages/core/package.json

@@ -54,6 +54,7 @@
   },
   "dependencies": {
     "@types/lodash-es": "^4.17.12",
+    "laravel-precognition": "^0.7.3",
     "axios": "^1.13.2",
     "lodash-es": "^4.17.21",
     "qs": "^6.14.0"

packages/core/src/index.ts

@@ -1,6 +1,8 @@
 import { Config } from './config'
 import { Router } from './router'
 
+export { UseFormUtils } from './useFormUtils'
+
 export { config } from './config'
 export { getScrollableParent } from './domUtils'
 export { objectToFormData } from './formData'

packages/core/src/types.ts

@@ -585,6 +585,23 @@ export type ProgressSettings = {
 
 export type UrlMethodPair = { url: string; method: Method }
 
+export type UseFormTransformCallback<TForm> = (data: TForm) => object
+export type UseFormWithPrecognitionArguments =
+  | [Method | (() => Method), string | (() => string)]
+  | [UrlMethodPair | (() => UrlMethodPair)]
+
+type UseFormInertiaArguments<TForm> = [data: TForm | (() => TForm)] | [rememberKey: string, data: TForm | (() => TForm)]
+type UseFormPrecognitionArguments<TForm> =
+  | [urlMethodPair: UrlMethodPair | (() => UrlMethodPair), data: TForm | (() => TForm)]
+  | [method: Method | (() => Method), url: string | (() => string), data: TForm | (() => TForm)]
+export type UseFormArguments<TForm> = UseFormInertiaArguments<TForm> | UseFormPrecognitionArguments<TForm>
+
+export type UseFormSubmitOptions = Omit<VisitOptions, 'data'>
+export type UseFormSubmitArguments =
+  | [Method, string, UseFormSubmitOptions?]
+  | [UrlMethodPair, UseFormSubmitOptions?]
+  | [UseFormSubmitOptions?]
+
 export type FormComponentOptions = Pick<
   VisitOptions,
   'preserveScroll' | 'preserveState' | 'preserveUrl' | 'replace' | 'only' | 'except' | 'reset'

packages/core/src/useFormUtils.ts

@@ -0,0 +1,116 @@
+import {
+  FormDataType,
+  Method,
+  UrlMethodPair,
+  UseFormArguments,
+  UseFormSubmitArguments,
+  UseFormSubmitOptions,
+} from './types'
+import { isUrlMethodPair } from './url'
+
+export class UseFormUtils {
+  /**
+   * Creates a callback that returns a UrlMethodPair.
+   *
+   * createWayfinderCallback(urlMethodPair)
+   * createWayfinderCallback(method, url)
+   * createWayfinderCallback(() => urlMethodPair)
+   * createWayfinderCallback(() => method, () => url)
+   */
+  public static createWayfinderCallback(
+    ...args: [UrlMethodPair | (() => UrlMethodPair)] | [Method | (() => Method), string | (() => string)]
+  ): () => UrlMethodPair {
+    return () => {
+      if (args.length === 1) {
+        // Wayfinder object, return as-is or call function...
+        return isUrlMethodPair(args[0]) ? args[0] : args[0]()
+      }
+
+      // Separate method and url, reconstruct Wayfinder object...
+      return {
+        method: typeof args[0] === 'function' ? args[0]() : args[0],
+        url: typeof args[1] === 'function' ? args[1]() : args[1],
+      }
+    }
+  }
+
+  /**
+   * Parses all useForm() arguments into { rememberKey, data, precognitionEndpoint }.
+   *
+   * useForm(data)
+   * useForm(rememberKey, data)
+   * useForm(method, url, data)
+   * useForm(urlMethodPair, data)
+   *
+   */
+  public static parseUseFormArguments<TForm extends FormDataType<TForm>>(
+    ...args: UseFormArguments<TForm>
+  ): {
+    rememberKey: string | null
+    data: TForm | (() => TForm)
+    precognitionEndpoint: (() => UrlMethodPair) | null
+  } {
+    if (args.length === 1) {
+      // Basic form: useForm(data)
+      return {
+        rememberKey: null,
+        data: args[0],
+        precognitionEndpoint: null,
+      }
+    }
+
+    if (args.length === 2) {
+      if (typeof args[0] === 'string') {
+        // Rememberable form: useForm(rememberKey, data)
+        return {
+          rememberKey: args[0],
+          data: args[1],
+          precognitionEndpoint: null,
+        }
+      }
+
+      // Form with Precognition + Wayfinder: useForm(wayfinder, data)
+      return {
+        rememberKey: null,
+        data: args[1],
+        precognitionEndpoint: this.createWayfinderCallback(args[0]),
+      }
+    }
+
+    // Form with Precognition: useForm(method, url, data)
+    return {
+      rememberKey: null,
+      data: args[2],
+      precognitionEndpoint: this.createWayfinderCallback(args[0], args[1]),
+    }
+  }
+
+  /**
+   * Parses all submission arguments into { method, url, options }.
+   * It uses the Precognition endpoint if no explicit method/url are provided.
+   *
+   * form.submit(method, url)
+   * form.submit(method, url, options)
+   * form.submit(urlMethodPair)
+   * form.submit(urlMethodPair, options)
+   * form.submit()
+   * form.submit(options)
+   */
+  public static parseSubmitArguments(
+    args: UseFormSubmitArguments,
+    precognitionEndpoint: (() => UrlMethodPair) | null,
+  ): { method: Method; url: string; options: UseFormSubmitOptions } {
+    if (args.length === 3 || (args.length === 2 && typeof args[0] === 'string')) {
+      // Explicit method and url provided...
+      return { method: args[0], url: args[1], options: args[2] ?? {} }
+    }
+
+    if (isUrlMethodPair(args[0])) {
+      // Wayfinder object provided...
+      return { ...args[0], options: (args[1] as UseFormSubmitOptions) ?? {} }
+    }
+
+    // Use Precognition endpoint with optional options...
+    return { ...precognitionEndpoint!(), options: (args[0] as UseFormSubmitOptions) ?? {} }
+  }
+}

packages/react/package.json

@@ -67,6 +67,7 @@
   "dependencies": {
     "@inertiajs/core": "workspace:*",
     "@types/lodash-es": "^4.17.12",
+    "laravel-precognition": "^0.7.3",
     "lodash-es": "^4.17.21"
   }
 }