basalt-ui 1.26.0 → 1.28.0

package/src/forms/use-field-array.ts

@@ -0,0 +1,94 @@
+/**
+ * ./forms — useFieldArray: the list-field surface over Mantine's four list actions.
+ * Mantine-coupled. Optional peer: @mantine/form.
+ *
+ * The gap (audit B §4): `insertListItem` / `removeListItem` / `reorderListItem` are all reachable
+ * off the raw form object, but they are unexported by name, undocumented in the forms doctrine, and
+ * each takes a different argument shape (`(path, item, index?)`, `(path, index)`,
+ * `(path, { from, to })`). The list ALSO has to be read back out of the values by dotted path, and
+ * every row needs `form.key(\`${path}.${i}\`)` or the uncontrolled reconciler reuses the wrong DOM
+ * node when a row is removed from the middle — which is the defect this hook exists to make
+ * unwritable.
+ */
+import type { FormArrayElement, LooseKeys, UseFormReturnType } from '@mantine/form'
+
+export type UseFieldArrayReturn<Item> = {
+  /** The live list. `[]` when the path holds nothing, so a call site never guards before mapping. */
+  items: Item[]
+  /** Push one item onto the end. */
+  append: (value: Item) => void
+  /** Drop the item at `index`. Mantine re-indexes the field errors with it. */
+  remove: (index: number) => void
+  /** Move one item, e.g. from a drag handle or a pair of arrow buttons. */
+  move: (from: number, to: number) => void
+  /**
+   * Mantine's reconciler key for row `index` (`form.key('<path>.<index>')`) — pass it as the row's
+   * JSX `key`, never spread it.
+   *
+   * **Positional, and that is a real limit worth stating**: it identifies the SLOT, not the item.
+   * Mantine's list actions write values through `$values` directly and never bump the form-level
+   * key generation (verified in 9.3.2's use-form-list), so removing row 0 does not change row 0's
+   * key — it changes which item sits there. That is correct for an append/remove list, where the
+   * uncontrolled inputs below re-read their `defaultValue` from the new values anyway. A list the
+   * USER reorders wants an identity key instead: put a `randomId()` on the item and key the row on
+   * that.
+   */
+  key: (index: number) => string
+}
+
+/**
+ * Reads and edits a list field as one object.
+ *
+ * **`items` is read from `form.getValues()`, not from `form.values`**, so it is correct under the
+ * `mode: 'uncontrolled'` default `useBasaltForm` sets: the list actions all re-render the form
+ * (they call `setValues` with `updateState: true`), so the snapshot this returns is the one the
+ * caller just produced.
+ *
+ * @example
+ * const items = useFieldArray(form, 'contacts')
+ *
+ * {items.items.map((_, index) => (
+ *   <FormRow key={items.key(index)} label={`Contact ${index + 1}`}>
+ *     <TextInput
+ *       key={fieldKey(form, `contacts.${index}.email`)}
+ *       {...inputProps(form, `contacts.${index}.email`)}
+ *     />
+ *     <Button onClick={() => items.remove(index)}>Remove</Button>
+ *   </FormRow>
+ * ))}
+ * <Button onClick={() => items.append({ email: '' })}>Add contact</Button>
+ */
+export function useFieldArray<
+  Values extends Record<string, unknown>,
+  Path extends LooseKeys<Values>,
+>(
+  form: UseFormReturnType<Values>,
+  path: Path,
+): UseFieldArrayReturn<FormArrayElement<Values, Path & string>> {
+  type Item = FormArrayElement<Values, Path & string>
+
+  return {
+    items: readList<Item>(form.getValues(), String(path)),
+    append: (value) => form.insertListItem(path, value),
+    remove: (index) => form.removeListItem(path, index),
+    move: (from, to) => form.reorderListItem(path, { from, to }),
+    key: (index) => form.key(`${String(path)}.${index}`),
+  }
+}
+
+/**
+ * The dotted-path read. Mantine's own `getPath` is internal to `@mantine/form/paths` and is not on
+ * the package's public entry, so this walks the path itself rather than reaching past the export
+ * map for six lines.
+ *
+ * Returns `[]` for a missing path or a non-array value: the alternative is a `.map` on `undefined`
+ * at the call site, and "the field is not a list" is a typing error the compiler already reports.
+ */
+function readList<Item>(values: Record<string, unknown>, path: string): Item[] {
+  let current: unknown = values
+  for (const segment of path.split('.')) {
+    if (current === null || typeof current !== 'object') return []
+    current = (current as Record<string, unknown>)[segment]
+  }
+  return Array.isArray(current) ? (current as Item[]) : []
+}

package/src/forms/use-form-draft.ts

@@ -2,28 +2,21 @@
  * ./forms — useFormDraft: autosave/restore/clear draft persistence via createPersistedState.
  * Mantine-coupled (reads from UseFormReturnType). Optional peer: @mantine/form.
  *
- * AUTOSAVE NOTE: @mantine/form v9 has no whole-form subscription hook on an existing form
- * instance — `form.watch` is per-path only. The cleanest autosave path is to thread
- * `onValuesChange` through useBasaltForm at creation time (the consumer passes the callback
- * there). useFormDraft therefore exposes an explicit `saveDraft()` that the consumer calls
- * at field blur / form change events. Wire it via useBasaltForm's `onValuesChange` prop for
- * fully-automatic autosave:
+ * AUTOSAVE: `autosave: true` and the hook owns its own subscription. It used to be a documented
+ * ref dance — declare a `saveDraftRef`, pass `onValuesChange: () => saveDraftRef.current?.()` into
+ * `useBasaltForm`, assign the ref after the hook returns — which was copied verbatim into the
+ * playground, and a five-line init-order puzzle a consumer has to re-derive is a hook that has not
+ * finished being written. The dance still works; it is no longer the recommended path.
  *
- * @example (manual blur-based autosave)
+ * @example (automatic)
  * const form = useBasaltForm({ initialValues, schema })
- * const { clearDraft, saveDraft } = useFormDraft(form, { key: 'my-form', version: 1 })
- * <TextInput {...field(form, 'name')} onBlur={saveDraft} />
+ * const { clearDraft, hasDraft } = useFormDraft(form, { key: 'my-form', version: 1, autosave: true })
  *
- * @example (automatic via onValuesChange in useBasaltForm — use saveDraft ref pattern)
- * const saveDraftRef = useRef<(() => void) | null>(null)
- * const form = useBasaltForm({ initialValues, schema, onValuesChange: () => saveDraftRef.current?.() })
+ * @example (manual — a blur-only save, or a form not created by useBasaltForm)
  * const { clearDraft, saveDraft } = useFormDraft(form, { key: 'my-form', version: 1 })
- * saveDraftRef.current = saveDraft
- * // NOTE: the ref pattern avoids the init-order problem — form is created first, the ref
- * // is populated after useFormDraft runs (hooks run top-to-bottom), so by the time
- * // onValuesChange fires on user interaction the ref is always populated.
+ * <TextInput key={fieldKey(form, 'name')} {...inputProps(form, 'name')} onBlur={saveDraft} />
  */
-import { useEffect, useRef } from 'react'
+import { useCallback, useEffect, useRef } from 'react'
 import type { UseFormReturnType } from '@mantine/form'
 import { createPersistedState } from '../state'
 import type { StandardSchemaV1 } from '../register'
@@ -42,8 +35,26 @@ export type UseFormDraftOptions<Values> = {
   version: number
   /** Optional Standard Schema to validate the persisted draft before restoring. */
   schema?: StandardSchemaV1<unknown, Values>
+  /**
+   * Persist on every value change, debounced. `true` uses {@link DEFAULT_AUTOSAVE_DEBOUNCE_MS};
+   * pass `{ debounceMs }` to tune it (`0` saves on the next macrotask).
+   *
+   * **The on/off decision and the watched key set are read ONCE, on mount.** The subscription is
+   * `form.watch` per top-level key, and `watch` calls `useEffect` internally, so both are a hook
+   * count and neither may move between renders. Flipping this prop later therefore neither starts
+   * nor stops autosaving; a form whose top-level SHAPE changes after mount needs `saveDraft` called
+   * by hand for the new keys. `debounceMs` is the exception — it is read at FIRE time, so a form
+   * that widens its window mid-edit gets the new one.
+   *
+   * Nested edits are covered: Mantine notifies a parent-path subscriber for a `a.b.c` change, so
+   * watching the top level watches the whole tree.
+   */
+  autosave?: boolean | { debounceMs?: number }
 }
 
+/** Long enough that a typed word is one write, short enough that a closed tab keeps the sentence. */
+export const DEFAULT_AUTOSAVE_DEBOUNCE_MS = 500
+
 /** Return value of useFormDraft. */
 export type UseFormDraftReturn = {
   /** True when a draft different from the initial values is persisted. */
@@ -63,15 +74,13 @@ export type UseFormDraftReturn = {
  * MUST-HAVES:
  * - Restores the draft once on mount if a draft is persisted.
  * - `clearDraft()` removes the persisted draft (call in onSubmit success).
- * - `saveDraft()` snapshots current form values (call onBlur or wire into useBasaltForm's `onValuesChange`).
- *
- * AUTOSAVE: @mantine/form has no whole-form change subscription on an existing form.
- * The cleanest path is to pass `saveDraft` to `useBasaltForm({ onValuesChange: () => saveDraft() })`.
- * For forms not created via useBasaltForm, call `saveDraft` manually on blur.
+ * - `saveDraft()` snapshots current form values (call onBlur, or leave it to `autosave`).
+ * - `autosave: true` subscribes for you — see {@link UseFormDraftOptions.autosave} for the two
+ *   properties that are frozen at mount, and why.
  *
  * @example
  * import * as v from 'valibot'
- * import { useBasaltForm, field, FormErrorSummary, useFormDraft } from 'basalt-ui/forms'
+ * import { useBasaltForm, inputProps, fieldKey, FormErrorSummary, useFormDraft } from 'basalt-ui/forms'
  *
  * const Schema = v.object({ name: v.pipe(v.string(), v.minLength(2)), amount: v.number() })
  * type Values = v.InferOutput<typeof Schema>
@@ -79,13 +88,11 @@ export type UseFormDraftReturn = {
  *
  * function MyForm() {
  *   const form = useBasaltForm({ initialValues: INITIAL, schema: Schema, mode: 'uncontrolled' })
- *   const { clearDraft, saveDraft, hasDraft } = useFormDraft(form, { key: 'my-form', version: 1 })
- *   // Wire saveDraft into onValuesChange after form creation via a ref or external callback:
- *   // form is created above; wire via onBlur as the safe fallback shown here.
+ *   const { clearDraft, hasDraft } = useFormDraft(form, { key: 'my-form', version: 1, autosave: true })
  *   return (
  *     <form onSubmit={form.onSubmit((values) => { submit(values); clearDraft() })}>
  *       <FormErrorSummary form={form} />
- *       <TextInput {...field(form, 'name')} onBlur={saveDraft} />
+ *       <TextInput key={fieldKey(form, 'name')} {...inputProps(form, 'name')} />
  *       {hasDraft && <Button onClick={clearDraft}>Clear draft</Button>}
  *     </form>
  *   )
@@ -95,40 +102,21 @@ export function useFormDraft<Values extends Record<string, unknown>>(
   form: UseFormReturnType<Values>,
   opts: UseFormDraftOptions<Values>,
 ): UseFormDraftReturn {
-  const { key, version, schema } = opts
+  const { key, version, schema, autosave } = opts
 
   // Create ONE stable store instance per key. useRef + lazy init so it is never
   // recreated on re-render. `key` MUST be stable (document this invariant above).
   // The storage key becomes `basalt:form:<key>` (createPersistedState auto-namespaces `basalt:*`).
-  type DraftEnvelope = { values: Values } | null
-  const storeRef = useRef<ReturnType<typeof createPersistedState<DraftEnvelope>> | null>(null)
+  const storeRef = useRef<ReturnType<typeof createPersistedState<DraftEnvelope<Values>>> | null>(
+    null,
+  )
   if (storeRef.current === null) {
-    // Wrap the Values schema into a DraftEnvelope schema using the ~standard interface.
-    // We validate the inner `values` field so stale/invalid drafts fall back to null.
-    // Only created when schema is provided — exactOptionalPropertyTypes forbids `schema: undefined`.
-    const envelopeSchema: StandardSchemaV1<unknown, DraftEnvelope> | undefined =
-      schema !== undefined
-        ? {
-            '~standard': {
-              version: 1 as const,
-              vendor: 'basalt-form-draft',
-              validate: (raw: unknown) => {
-                if (typeof raw !== 'object' || raw === null || !('values' in raw)) {
-                  return { value: null }
-                }
-                const result = schema['~standard'].validate((raw as { values: unknown }).values)
-                if (result instanceof Promise) return { value: null }
-                if (result.issues !== undefined) return { value: null }
-                return { value: { values: result.value } }
-              },
-            },
-          }
-        : undefined
-
-    storeRef.current = createPersistedState<DraftEnvelope>({
+    const envelopeSchema = wrapEnvelopeSchema(schema)
+    storeRef.current = createPersistedState<DraftEnvelope<Values>>({
       key: `form:${key}`,
       version,
       initial: null,
+      // exactOptionalPropertyTypes forbids `schema: undefined`, so it is spread or omitted.
       ...(envelopeSchema !== undefined && { schema: envelopeSchema }),
     })
   }
@@ -166,5 +154,109 @@ export function useFormDraft<Values extends Record<string, unknown>>(
     setDraft(null)
   }
 
+  useAutosave(form, autosave, saveDraft)
+
   return { hasDraft, saveDraft, clearDraft }
 }
+
+// ── the two pieces the hook composes ─────────────────────────────────────────
+
+/** What `createPersistedState` stores: the values under one key, or nothing persisted at all. */
+type DraftEnvelope<Values> = { values: Values } | null
+
+/**
+ * Lifts a `Values` schema into a `DraftEnvelope<Values>` one, through the `~standard` interface.
+ *
+ * Only the inner `values` field is validated, and every failure resolves to `null` rather than to an
+ * issue list: a draft is a convenience, so a stale or hand-edited one is DROPPED, never surfaced as
+ * a validation error against a form the user has not touched yet. The async arm resolves to `null`
+ * for the same reason `useBasaltForm` pins `sync: true` — `createPersistedState` reads storage
+ * synchronously and has nowhere to await.
+ *
+ * Outside the hook because it is pure, closes over nothing, and inside it read as a third
+ * responsibility in a body that already owned the store, the restore and the autosave.
+ */
+function wrapEnvelopeSchema<Values>(
+  schema: StandardSchemaV1<unknown, Values> | undefined,
+): StandardSchemaV1<unknown, DraftEnvelope<Values>> | undefined {
+  if (schema === undefined) return undefined
+  return {
+    '~standard': {
+      version: 1 as const,
+      vendor: 'basalt-form-draft',
+      validate: (raw: unknown) => {
+        if (typeof raw !== 'object' || raw === null || !('values' in raw)) return { value: null }
+        const result = schema['~standard'].validate((raw as { values: unknown }).values)
+        if (result instanceof Promise) return { value: null }
+        if (result.issues !== undefined) return { value: null }
+        return { value: { values: result.value } }
+      },
+    },
+  }
+}
+
+/**
+ * The debounced `form.watch` subscription behind `autosave`.
+ *
+ * **It relies on `form.watch` calling exactly one `useEffect` per call**, which is why the watched
+ * path set is frozen on the first render: `watch` registers that effect INSIDE itself (checked in
+ * the installed `@mantine/form` 9.3.2 source, `use-form-watch.ts`), so the number of `watch` calls
+ * IS a hook count and a set that changed between renders would trip React's hook-order invariant.
+ * Freezing it is what makes the loop below legal.
+ *
+ * That is a load-bearing dependency on an implementation detail of a peer, so state it plainly: a
+ * `@mantine/form` minor that moves `watch` off `useEffect` — or calls a second hook from it —
+ * changes the shape of this file. The failure would be loud (a hook-order error in dev on the first
+ * autosaving form), not silent, but it is a real upgrade risk and belongs in the upgrade's diff
+ * review rather than in a consumer's bug report.
+ *
+ * Nested edits need no extra paths: Mantine notifies a parent-path subscriber for an `a.b.c` write,
+ * so watching every top-level key watches the whole tree.
+ */
+function useAutosave<Values extends Record<string, unknown>>(
+  form: UseFormReturnType<Values>,
+  autosave: UseFormDraftOptions<Values>['autosave'],
+  saveDraft: () => void,
+): void {
+  const watchedPathsRef = useRef<string[] | null>(null)
+  if (watchedPathsRef.current === null) {
+    watchedPathsRef.current =
+      autosave === undefined || autosave === false ? [] : Object.keys(form.getValues())
+  }
+
+  // Read at FIRE time, not at schedule time, so a window that opened three renders ago still writes
+  // the current values and the current debounce.
+  const debounceRef = useRef(DEFAULT_AUTOSAVE_DEBOUNCE_MS)
+  debounceRef.current =
+    typeof autosave === 'object'
+      ? (autosave.debounceMs ?? DEFAULT_AUTOSAVE_DEBOUNCE_MS)
+      : DEFAULT_AUTOSAVE_DEBOUNCE_MS
+  // `saveDraft` is a fresh closure each render and `watch`'s effect re-subscribes whenever its
+  // callback identity changes, so the callback handed to `watch` must be stable and read the ref.
+  const saveRef = useRef<() => void>(saveDraft)
+  saveRef.current = saveDraft
+
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const scheduleSave = useCallback(() => {
+    if (timerRef.current !== null) clearTimeout(timerRef.current)
+    timerRef.current = setTimeout(() => {
+      timerRef.current = null
+      saveRef.current()
+    }, debounceRef.current)
+  }, [])
+
+  // An unmount mid-window flushes the pending write rather than dropping it — a closed tab keeps
+  // the sentence.
+  useEffect(
+    () => () => {
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current)
+        timerRef.current = null
+        saveRef.current()
+      }
+    },
+    [],
+  )
+
+  for (const path of watchedPathsRef.current) form.watch(path, scheduleSave)
+}

package/src/forms/use-form-submit.ts

@@ -0,0 +1,199 @@
+/**
+ * ./forms — useFormSubmit: the submit lifecycle Mantine leaves to every call site.
+ * Mantine-coupled. Optional peer: @mantine/form.
+ *
+ * The gap (audit B §4): `form.onSubmit` gives you validation and a `submitting` flag and nothing
+ * else. A real submit also has to catch the handler's throw, turn it into a message a human can
+ * read, route a server's per-FIELD errors back onto the fields, and put the caret on the first
+ * thing that is wrong. Four jobs, re-written per form, and the last one is the one everybody skips.
+ */
+import { useCallback, useRef, useState } from 'react'
+import type { SyntheticEvent } from 'react'
+import type { UseFormReturnType } from '@mantine/form'
+import { toErrorMessage } from '../query/error-message'
+
+// ── The server field-error envelope ───────────────────────────────────────────
+
+/**
+ * Per-field messages keyed by the same dotted paths `inputProps(form, path)` uses
+ * (`'email'`, `'addresses.0.city'`). The shape a server returns for a 422, and the shape
+ * `validateAsync` returns for a uniqueness check.
+ */
+export type FormFieldErrors = Record<string, string>
+
+/**
+ * Whether a thrown value carries `{ fieldErrors }` — the envelope `useFormSubmit` routes back onto
+ * the fields instead of into one form-level message.
+ *
+ * Structural, not `instanceof`: the throw crosses a transport (Eden, `fetch`, a mutation wrapper)
+ * and arrives as a plain object, so an `Error` subclass would only match the one shape basalt
+ * itself constructed. The keys are checked to be STRINGS — a `{ fieldErrors: { email: 422 } }`
+ * would otherwise reach `form.setErrors` and render a number under an input.
+ *
+ * @example
+ * throw Object.assign(new Error('Validation failed'), { fieldErrors: { email: 'Already taken' } })
+ */
+export function isFieldErrorEnvelope(err: unknown): err is { fieldErrors: FormFieldErrors } {
+  if (err === null || typeof err !== 'object') return false
+  const fieldErrors = (err as { fieldErrors?: unknown }).fieldErrors
+  if (fieldErrors === null || typeof fieldErrors !== 'object' || Array.isArray(fieldErrors)) {
+    return false
+  }
+  return Object.values(fieldErrors).every((message) => typeof message === 'string')
+}
+
+// ── Focus-first-error ─────────────────────────────────────────────────────────
+
+/**
+ * Puts the caret on the first errored field. `form.getInputNode(path)` is Mantine v9's own lookup
+ * (a `[data-path]` query over the attribute `getInputProps` writes, verified in the installed
+ * 9.3.2 source); the `[name]` query is the fallback for a control that spreads its own props and
+ * never got the attribute.
+ *
+ * Order is the ERROR RECORD's key order, not the DOM's: Mantine builds it from the schema, so it is
+ * the order the fields were declared in — which for a form written top-to-bottom is the visual
+ * order, and unlike a DOM sweep it costs no traversal.
+ *
+ * A no-op without a document (SSR), because `getInputNode` reaches straight for `document`.
+ */
+function focusFirstError<Values extends Record<string, unknown>>(
+  form: UseFormReturnType<Values>,
+  errors: Record<string, unknown>,
+): void {
+  if (typeof document === 'undefined') return
+  for (const [path, message] of Object.entries(errors)) {
+    if (message === null || message === undefined || message === false) continue
+    const node =
+      form.getInputNode<HTMLElement, string>(path) ??
+      document.querySelector<HTMLElement>(`[name="${path}"]`)
+    if (node !== null) {
+      node.focus()
+      return
+    }
+  }
+}
+
+// ── useFormSubmit ─────────────────────────────────────────────────────────────
+
+export type UseFormSubmitOptions<Values extends Record<string, unknown>> = {
+  /** Ran after the handler resolves. The success path — close the modal, clear the draft, navigate. */
+  onSuccess?: (values: Values) => void
+  /** Ran on any throw, after `submitError` is set. For telemetry or a toast; not required for either. */
+  onError?: (err: unknown) => void
+  /**
+   * Turns a thrown value into the message `submitError` carries. Defaults to `toErrorMessage`
+   * (`basalt-ui/query`), which already unwraps `Error`, `{ message }` and Eden's `{ status, value }`.
+   * Override it to brand the copy or to branch on `errorStatus(err)`.
+   */
+  mapError?: (err: unknown) => string
+  /**
+   * The async half of validation, run AFTER the schema passes and BEFORE the handler — a uniqueness
+   * check, a server-side cross-field rule, anything that needs the network.
+   *
+   * It lives here rather than on `useBasaltForm` because that hook hard-codes
+   * `schemaResolver(schema, { sync: true })` so `validate()`/`isValid()` stay synchronous for every
+   * field-level read. Moving the async rule to submit time keeps that property AND gives the rule a
+   * home; the cost, stated plainly, is that it does not run on blur.
+   *
+   * Return `null` (or an empty record) for "valid". Anything else is set on the fields, the first
+   * one is focused, and the handler never runs.
+   */
+  validateAsync?: (values: Values) => Promise<FormFieldErrors | null>
+}
+
+export type UseFormSubmitReturn = {
+  /** Hand straight to `<form onSubmit={submit}>`, or call it from a button's `onClick`. */
+  submit: (event?: SyntheticEvent<HTMLFormElement>) => void
+  /** True from the moment a submit starts until the handler settles. Mantine's own `form.submitting`. */
+  isSubmitting: boolean
+  /** The form-level failure message, or `null`. Cleared at the start of every submit. */
+  submitError: string | null
+  /** Clears `submitError` without submitting — for a "dismiss" on the error banner. */
+  reset: () => void
+}
+
+/**
+ * Wraps `form.onSubmit` with the four things a real submit needs: a busy flag, a caught and decoded
+ * error, a server field-error envelope routed back onto the fields, and focus on the first thing
+ * that is wrong.
+ *
+ * **`isSubmitting` IS `form.submitting`**, not a second piece of state beside it. Mantine already
+ * flips that flag around a handler returning a promise, and this handler always does; duplicating it
+ * would give a form two busy flags that can disagree, which is the failure a `FormStateProvider`
+ * reading the wrong one produces.
+ *
+ * **Focus moves on BOTH failure paths** — a schema failure (through `onSubmit`'s own
+ * `handleValidationFailure`) and a thrown `{ fieldErrors }` envelope. A server's 422 lands exactly
+ * where a client-side error does.
+ *
+ * @example
+ * const { submit, isSubmitting, submitError } = useFormSubmit(
+ *   form,
+ *   async (values) => { await unwrap(api.users.post({ body: values })) },
+ *   { onSuccess: () => { clearDraft(); close() }, validateAsync: checkHandleFree },
+ * )
+ *
+ * <form onSubmit={submit}>
+ *   <FormStateProvider submitting={isSubmitting}>
+ *     {submitError !== null && <Alert color="red">{submitError}</Alert>}
+ *     …
+ *   </FormStateProvider>
+ * </form>
+ */
+export function useFormSubmit<Values extends Record<string, unknown>>(
+  form: UseFormReturnType<Values>,
+  handler: (values: Values) => void | Promise<void>,
+  options: UseFormSubmitOptions<Values> = {},
+): UseFormSubmitReturn {
+  const [submitError, setSubmitError] = useState<string | null>(null)
+
+  // The handler and the callbacks are read at FIRE time, never captured into a memo: a submit
+  // handler closes over the freshest props by definition, and a stale one here would post the
+  // previous render's values.
+  const handlerRef = useRef(handler)
+  handlerRef.current = handler
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+  const formRef = useRef(form)
+  formRef.current = form
+
+  const submit = form.onSubmit(
+    async (values) => {
+      const { onSuccess, onError, mapError, validateAsync } = optionsRef.current
+      setSubmitError(null)
+      try {
+        const fieldErrors = await validateAsync?.(values)
+        if (fieldErrors !== undefined && fieldErrors !== null && hasEntries(fieldErrors)) {
+          applyFieldErrors(formRef.current, fieldErrors)
+          return
+        }
+        await handlerRef.current(values)
+        onSuccess?.(values)
+      } catch (err) {
+        // Both, not either: the envelope's per-field messages go on the fields AND its decoded
+        // message goes in the banner. A 422 whose fields are all off-screen would otherwise report
+        // nothing at all where the user is looking.
+        if (isFieldErrorEnvelope(err)) applyFieldErrors(formRef.current, err.fieldErrors)
+        setSubmitError(mapError === undefined ? toErrorMessage(err) : mapError(err))
+        onError?.(err)
+      }
+    },
+    (errors) => focusFirstError(formRef.current, errors),
+  )
+
+  const reset = useCallback(() => setSubmitError(null), [])
+
+  return { submit, isSubmitting: form.submitting, submitError, reset }
+}
+
+function hasEntries(errors: FormFieldErrors): boolean {
+  return Object.keys(errors).length > 0
+}
+
+function applyFieldErrors<Values extends Record<string, unknown>>(
+  form: UseFormReturnType<Values>,
+  fieldErrors: FormFieldErrors,
+): void {
+  form.setErrors(fieldErrors)
+  focusFirstError(form, fieldErrors)
+}