Introduction of the Form component (#2474)

Author: pascalbaljet

packages/core/src/formObject.ts

@@ -0,0 +1,99 @@
+import { get, set } from 'es-toolkit/compat'
+import { FormDataConvertible } from './types'
+
+/**
+ * Transform dotted notation to bracket notation.
+ *
+ * Examples:
+ *   user.name => user[name]
+ *   user.profile.city => user[profile][city]
+ *   user.skills[] => user[skills][]
+ *   users.company[address].street => users[company][address][street]
+ *   config\.app\.name => config.app.name (escaped, literal)
+ */
+function undotKey(key: string): string {
+  if (!key.includes('.')) {
+    return key
+  }
+
+  const transformSegment = (segment: string): string => {
+    if (segment.startsWith('[') && segment.endsWith(']')) {
+      return segment // Already in bracket notation - leave untouched
+    }
+
+    // Convert dotted segment to bracket notation: "user.name" → "user[name]"
+    return segment.split('.').reduce((result, part, index) => (index === 0 ? part : `${result}[${part}]`))
+  }
+
+  return key
+    .replace(/\\\./g, '__ESCAPED_DOT__') // Temporarily replace escaped dots (\.) to protect them from transformation
+    .split(/(\[[^\]]*\])/) // Split on bracket notation while preserving the brackets in the result array
+    .filter(Boolean) // Remove empty strings from the split operation
+    .map(transformSegment) // Transform each segment: dotted parts become bracketed, existing brackets stay as-is
+    .join('') // Reassemble all segments back into a single string
+    .replace(/__ESCAPED_DOT__/g, '.') // Restore the escaped dots as literal dots in the final result
+}
+
+/**
+ * Parse a key into an array of path segments.
+ *
+ * Examples:
+ * - "user[name]" => ["user", "name"]
+ * - "tags[]" => ["tags", ""]
+ * - "items[0][name]" => ["items", 0, "name"]
+ */
+function parseKey(key: string): (string | number | '')[] {
+  const path: (string | number | '')[] = []
+  const pattern = /([^\[\]]+)|\[(\d*)\]/g
+  let match: RegExpExecArray | null
+
+  while ((match = pattern.exec(key)) !== null) {
+    if (match[1] !== undefined) {
+      path.push(match[1])
+    } else if (match[2] !== undefined) {
+      path.push(match[2] === '' ? '' : Number(match[2]))
+    }
+  }
+
+  return path
+}
+
+/**
+ * Convert a FormData instance into an object structure.
+ */
+export function formDataToObject(source: FormData): Record<string, FormDataConvertible> {
+  const form: Record<string, any> = {}
+
+  // formData.entries() returns an iterator where the first element is the key and the second element
+  // is the value. Examples of the keys are "user[name]", "tags[]", "items[0][name]", "user.name", etc.
+  // We should construct a new (nested) object based on these keys.
+  for (const [key, value] of source.entries()) {
+    if (value instanceof File && value.size === 0 && value.name === '') {
+      // Check if the given value is an empty file. We want to filter
+      // those out as they prevent us from comparing objects with
+      // each other, which we do to set the isDirty prop.
+      continue
+    }
+
+    const path = parseKey(undotKey(key))
+
+    // If the key ends with an empty string (''), treat it as an array push (e.g., "tags[]")
+    if (path[path.length - 1] === '') {
+      const arrayPath = path.slice(0, -1)
+      const existing = get(form, arrayPath)
+
+      if (Array.isArray(existing)) {
+        existing.push(value)
+      } else {
+        set(form, arrayPath, [value])
+      }
+
+      continue
+    }
+
+    // No brackets: last value wins when multiple fields have the same key
+    set(form, path, value)
+  }
+
+  return form
+}

packages/core/src/index.ts

@@ -1,5 +1,7 @@
 import { Router } from './router'
 
+export { objectToFormData } from './formData'
+export { formDataToObject } from './formObject'
 export { default as createHeadManager } from './head'
 export { hide as hideProgress, reveal as revealProgress, default as setupProgress } from './progress'
 export { default as shouldIntercept } from './shouldIntercept'

packages/core/src/types.ts

@@ -341,6 +341,36 @@ export type ProgressSettings = {
   color: string
 }
 
+export type FormComponentOptions = Pick<
+  VisitOptions,
+  'preserveScroll' | 'preserveState' | 'preserveUrl' | 'replace' | 'only' | 'except' | 'reset'
+>
+
+export type FormComponentProps = Partial<
+  Pick<Visit, 'method' | 'headers' | 'queryStringArrayFormat' | 'errorBag' | 'showProgress'> &
+    Omit<VisitCallbacks, 'onPrefetched' | 'onPrefetching'>
+> & {
+  action?: string | { url: string; method: Method }
+  transform?: (data: Record<string, FormDataConvertible>) => Record<string, FormDataConvertible>
+  options?: FormComponentOptions
+}
+
+export type FormComponentSlotProps = {
+  errors: Record<string, string>
+  hasErrors: boolean
+  processing: boolean
+  progress: Progress | null
+  wasSuccessful: boolean
+  recentlySuccessful: boolean
+  clearErrors: (...fields: string[]) => void
+  resetAndClearErrors: (...fields: string[]) => void
+  setError(field: string, value: string): void
+  setError(errors: Record<string, string>): void
+  isDirty: boolean
+  reset: () => void
+  submit: () => void
+}
+
 declare global {
   interface DocumentEventMap {
     'inertia:before': GlobalEvent<'before'>

packages/react/src/Form.ts

@@ -0,0 +1,134 @@
+import {
+  FormComponentProps,
+  FormComponentSlotProps,
+  FormDataConvertible,
+  formDataToObject,
+  mergeDataIntoQueryString,
+  Method,
+  VisitOptions,
+} from '@inertiajs/core'
+import { isEqual } from 'es-toolkit'
+import { createElement, FormEvent, ReactNode, useEffect, useMemo, useRef, useState } from 'react'
+import useForm from './useForm'
+
+type ComponentProps = (FormComponentProps &
+  Omit<React.FormHTMLAttributes<HTMLFormElement>, keyof FormComponentProps | 'children'> &
+  Omit<React.AllHTMLAttributes<HTMLFormElement>, keyof FormComponentProps | 'children'>) & {
+  children: (props: FormComponentSlotProps) => ReactNode
+}
+
+type FormSubmitOptions = Omit<VisitOptions, 'data' | 'onPrefetched' | 'onPrefetching'>
+
+const noop = () => undefined
+
+const Form = ({
+  action = '',
+  method = 'get',
+  headers = {},
+  queryStringArrayFormat = 'brackets',
+  errorBag = null,
+  showProgress = true,
+  transform = (data) => data,
+  options = {},
+  onStart = noop,
+  onProgress = noop,
+  onFinish = noop,
+  onBefore = noop,
+  onCancel = noop,
+  onSuccess = noop,
+  onError = noop,
+  onCancelToken = noop,
+  children,
+  ...props
+}: ComponentProps) => {
+  const form = useForm({})
+  const formElement = useRef<HTMLFormElement>(null)
+
+  const resolvedMethod = useMemo(() => {
+    return typeof action === 'object' ? action.method : (method.toLowerCase() as Method)
+  }, [action, method])
+
+  const [isDirty, setIsDirty] = useState(false)
+  const defaultValues = useRef<Record<string, FormDataConvertible>>({})
+
+  const getData = (): Record<string, FormDataConvertible> => {
+    // Convert the FormData to an object because we can't compare two FormData
+    // instances directly (which is needed for isDirty), mergeDataIntoQueryString()
+    // expects an object, and submitting a FormData instance directly causes problems with nested objects.
+    return formDataToObject(new FormData(formElement.current))
+  }
+
+  const updateDirtyState = (event: Event) =>
+    setIsDirty(event.type === 'reset' ? false : !isEqual(getData(), defaultValues.current))
+
+  useEffect(() => {
+    defaultValues.current = getData()
+
+    const formEvents: Array<keyof HTMLElementEventMap> = ['input', 'change', 'reset']
+
+    formEvents.forEach((e) => formElement.current.addEventListener(e, updateDirtyState))
+
+    return () => formEvents.forEach((e) => formElement.current?.removeEventListener(e, updateDirtyState))
+  }, [])
+
+  const submit = () => {
+    const [url, _data] = mergeDataIntoQueryString(
+      resolvedMethod,
+      typeof action === 'object' ? action.url : action,
+      getData(),
+      queryStringArrayFormat,
+    )
+
+    const submitOptions: FormSubmitOptions = {
+      headers,
+      errorBag,
+      showProgress,
+      onCancelToken,
+      onBefore,
+      onStart,
+      onProgress,
+      onFinish,
+      onCancel,
+      onSuccess,
+      onError,
+      ...options,
+    }
+
+    form.transform(() => transform(_data))
+    form.submit(resolvedMethod, url, submitOptions)
+  }
+
+  return createElement(
+    'form',
+    {
+      ...props,
+      ref: formElement,
+      action: typeof action === 'object' ? action.url : action,
+      method: resolvedMethod,
+      onSubmit: (event: FormEvent<HTMLFormElement>) => {
+        event.preventDefault()
+        submit()
+      },
+    },
+    typeof children === 'function'
+      ? children({
+          errors: form.errors,
+          hasErrors: form.hasErrors,
+          processing: form.processing,
+          progress: form.progress,
+          wasSuccessful: form.wasSuccessful,
+          recentlySuccessful: form.recentlySuccessful,
+          setError: form.setError,
+          clearErrors: form.clearErrors,
+          resetAndClearErrors: form.resetAndClearErrors,
+          isDirty,
+          reset: () => formElement.current?.reset(),
+          submit,
+        })
+      : children,
+  )
+}
+
+Form.displayName = 'InertiaForm'
+
+export default Form

packages/react/src/index.ts

@@ -3,6 +3,7 @@ import { router as Router } from '@inertiajs/core'
 export const router = Router
 export { default as createInertiaApp } from './createInertiaApp'
 export { default as Deferred } from './Deferred'
+export { default as Form } from './Form'
 export { default as Head } from './Head'
 export { InertiaLinkProps, default as Link } from './Link'
 export { InertiaFormProps, SetDataByObject, SetDataByMethod, SetDataByKeyValuePair, SetDataAction, default as useForm } from './useForm'

packages/react/test-app/Pages/Dump.jsx

@@ -10,18 +10,12 @@ export default (props) => {
     form: props.form,
     files: props.files ? props.files : {},
     query: props.query,
+    url: props.url,
     $page: page,
   }
 
   useEffect(() => {
-    window._inertia_request_dump = {
-      headers: props.headers,
-      method: props.method,
-      form: props.form,
-      files: props.files ? props.files : {},
-      query: props.query,
-      $page: page,
-    }
+    window._inertia_request_dump = dump
   }, [])
 
   return (

packages/react/test-app/Pages/FormComponent/DottedKeys.jsx

@@ -0,0 +1,38 @@
+import { Form } from '@inertiajs/react'
+
+export default function DottedKeys() {
+  return (
+    <div>
+      <h1>Dotted Keys Form Test</h1>
+
+      {/* Test basic and nested dotted keys */}
+      <Form action="/dump/post" method="post">
+        <h2>Basic Dotted Keys</h2>
+        <input type="text" name="user.name" placeholder="User Name" />
+        <input type="text" name="user.profile.city" placeholder="City" />
+        <input type="text" name="user.skills[]" placeholder="First Skill" />
+        <input type="text" name="user.skills[]" placeholder="Second Skill" />
+        <input type="text" name="company.address.street" placeholder="Street" />
+        <button type="submit">Submit Basic</button>
+      </Form>
+
+      {/* Test escaped dots (literal keys) */}
+      <Form action="/dump/post" method="post">
+        <h2>Escaped Dots</h2>
+        <input type="text" name="config\.app\.name" placeholder="App Name" />
+        <input type="text" name="settings.theme\.mode" placeholder="Theme Mode" />
+        <button type="submit">Submit Escaped</button>
+      </Form>
+
+      {/* Test mixed bracket and dotted notation */}
+      <Form action="/dump/post" method="post">
+        <h2>Mixed Notation</h2>
+        <input type="text" name="user[roles][]" defaultValue="admin" />
+        <input type="text" name="user[roles][]" defaultValue="editor" />
+        <input type="text" name="settings.ui.theme" placeholder="UI Theme" />
+        <button type="submit">Submit Mixed</button>
+      </Form>
+
+    </div>
+  )
+}