Three modules, one package
| Import | Responsibility |
|---|---|
package:jaspr_hooks/hooks.dart |
Component lifecycle, local state, subscriptions and effects |
package:jaspr_hooks/query.dart |
Cached server state, mutations, retries, hydration and invalidation |
package:jaspr_hooks/form.dart |
Typed drafts, fields, validation, submissions, dirty state and autosave |
The existing jaspr_hooks.dart umbrella remains compatible and exports all three.
Forms do not import queries: submit callbacks can call mutation.mutateAsync, a
repository, or another asynchronous persistence API.
Forms, inspired by TanStack Form
The headless native Dart module follows TanStack Form concepts and naming. Typed field lenses replace TypeScript deep-key inference. It has no JavaScript, schema-library, protobuf, router or design-system dependency.
final form = useForm(FormOptions<String>(
defaultValues: '',
onSubmit: (context) async {
await repository.saveName(context.value);
return const FormSubmitResult.success();
},
));
final name = useField(form, FormFieldKey<String, String>(
'name', read: (value) => value, write: (_, value) => value,
), validators: FieldValidators<String, String>(
onChange: (value, _) => value.trim().isEmpty
? [const FormIssue('Enter a name.', code: 'required')]
: [],
));
final submitting = useFormState(form, (state) => state.isSubmitting);
// Bind name.value, name.handleChange, name.handleBlur and name.meta.errors
// to existing accessible controls. Submit with form.handleSubmit().
-
Typed drafts and fields:
FormController<T>,FormFieldKey<T, V>andFieldController<T, V>. Keep partially entered numeric/date text in the draft; parse it through domain validation and request mapping. -
Validation: field/form
onChange,onBlur,onSubmitand async equivalents, debounce, linked fields (listenTo), cancellation signals and stale-result protection. Multiple errors can retain indexed paths and backend rule codes. -
Error ownership:
errorMapseparates validation events and server errors. Editing one field retains errors on other fields. Put unknown backend paths inFormErrors.form; transport exceptions remain separate from field validation. -
Submission:
handleSubmitvalidates, prevents duplicate writes, awaits the callback and records failures. Return.invalid(errors)for server rejection or.uncertain()when a write may have committed;allowRetry()acknowledges uncertainty. Mutations never retry automatically. -
Baselines:
isDirtyrecords edit history;isDefaultValuecompares with defaults.hasUnsavedChangescompares against the last confirmed save. Saving an older revision never clears edits made in flight.reset(newValues)is an explicit replacement of the draft and baseline. -
Subscriptions:
useFormowns the controller;useFieldanduseFormStatesubscribe consumers. Use stable selectors or an equality function for allocated selections. Defaults changing on rebuild never replace edited values. -
Optional autosave:
useFormAutosave/FormAutosavedebounce and serialize writes.canSavecan defer saving while focused; callflush()on blur. Failed revisions remain dirty and require a new edit or explicit retry. -
Navigation:
useFormNavigationGuardregisters a live predicate with the router-neutralFormNavigationGuard. App adapters cover routes/history, browser unload and dialog dismissal usingstate.shouldBlockNavigation. - SSR: form hooks do not submit, validate asynchronously, start autosave or register blockers on the server. Subscriptions and timers dispose on unmount.
Use immutable drafts or supply FormOptions.copy and equals. Backend mapping,
localization, focus management and business validation stay in app adapters;
transport deadlines and cache updates stay in mutations. The following recipes show those boundaries.
Map server errors without coupling the form to a transport
A submit callback receives a snapshot and revision. Convert your application API's
response to FormErrors at this boundary. A known path becomes a field error; an
unknown or cross-field violation belongs in the summary. Keep the original path
and rule code when translating the message.
return FormSubmitResult.invalid(FormErrors(
fields: {
'email': [FormIssue('This email is already used.',
path: 'customer.email', code: 'unique')],
},
form: [FormIssue('Check the customer assignment.',
path: 'customer.assignment', code: 'invalid')],
));
Throw transport failures from the callback; state.error retains the exception.
A failed or invalid write never acknowledges the draft. Return
FormSubmitResult.uncertain() if the server may have committed a timed-out write;
reconcile with the server before calling allowRetry() or resetValues().
Async validation and linked inputs
FieldValidators<CustomerDraft, String>(
onChangeAsync: (email, values, signal) async {
final available = await repository.isEmailAvailable(email);
if (signal.isCancelled) return [];
return available ? [] : [const FormIssue('Email is already used.')];
},
asyncDebounce: const Duration(milliseconds: 300),
listenTo: ['customerType'],
);
The form ignores stale results even if the transport cannot cancel its request.
Use signal.onCancel when your API supports cancellation. A field's listenTo
paths cause its validators to run when a related input changes. Submit validation
runs without the debounce delay. Separate onChange, onBlur,
onSubmit and
onServer entries remain inspectable in errorMap.
Optional autosave and navigation
final autosave = useFormAutosave(form,
debounce: const Duration(milliseconds: 600),
canSave: () => autosaveEnabled && !editingFocusedField,
);
// Call autosave.flush() when a focus-based deferral ends.
final guard = useMemoized(FormNavigationGuard.new);
useFormNavigationGuard(guard, () => form.state.shouldBlockNavigation);
// The app/router asks guard.canLeave(confirmDiscard) before leaving.
Autosave serializes writes and acknowledges only their submitted snapshot. It does not repeatedly retry a rejected revision. A subsequent edit, explicit flush or user retry can attempt saving again. For a permanently mounted browser adapter, register history listeners before route observers, which can synchronously dispose a form and remove its blocker. Cover browser unload and modal dismissal in the app as well; the portable hook does not install DOM events.
Reset and field metadata
reset() returns to initial defaults, while resetValues(value) explicitly
replaces defaults, current values and the accepted baseline. Use resetValues(null)
when the draft type is nullable. Reset clears interaction metadata and errors.
acceptBaseline(submitted) acknowledges an externally managed save without
replacing newer edits or clearing sticky isDirty history.
Fields expose isTouched, isBlurred, isDirty, isPristine,
isDefaultValue,
hasUnsavedChanges, isValidating, isValid and source-specific
errorMap.
useFormState supports selectors and custom equality. useField
subscribes its
consumer to form changes; it does not promise per-field render isolation.
Keep submit buttons available when a field is invalid so a user can request full
validation and focus feedback. Disable them during state.isSubmitting; rendering
an async-validation spinner should not swallow a click triggered by field blur.