@formisch/react 0.4.6 → 0.5.0

package/README.md

@@ -59,7 +59,13 @@ In addition, Formisch offers several functions (we call them "methods") that can
 
 ## Comparison
 
-What makes Formisch unique is its framework-agnostic core, which is fully native to the framework you are using. It works by inserting framework-specific reactivity blocks when the core package is built. The result is a small bundle size and native performance for any UI update. This feature, along with a few others, distinguishes Formisch from other form libraries. My vision for Formisch is to create a framework-agnostic platform similar to [Vite](https://vite.dev/), but for forms.
+What makes Formisch unique is its framework-agnostic core, which is fully native to the framework you are using. It works by inserting framework-specific reactivity blocks when the core package is built, giving you native performance for any UI update. A modular methods API keeps bundles starting at just ~2.5 kB by only including the methods you import, and end-to-end type safety covers deeply nested paths and field arrays with TypeScript inference that stays fast even as forms grow.
+
+For a side-by-side look at how Formisch compares to React Hook Form and TanStack Form, see the [comparison guide](https://formisch.dev/react/guides/comparison/).
+
+## Vision
+
+My vision for Formisch is to create a framework-agnostic platform similar to [Vite](https://vite.dev/), but for forms — a shared core that lets the same mental model and codebase work natively across every modern UI framework.
 
 ## Partners
 

package/dist/index.d.ts

@@ -8,6 +8,31 @@ import { ChangeEventHandler, FocusEventHandler, FormEvent, FormHTMLAttributes, R
 * Schema type.
 */
 type Schema = v.GenericSchema | v.GenericSchemaAsync;
+/**
+* Object schema type.
+*/
+type ObjectSchema = v.LooseObjectSchema<v.ObjectEntries, v.ErrorMessage<v.LooseObjectIssue> | undefined> | v.ObjectSchema<v.ObjectEntries, v.ErrorMessage<v.ObjectIssue> | undefined> | v.StrictObjectSchema<v.ObjectEntries, v.ErrorMessage<v.StrictObjectIssue> | undefined> | v.VariantSchema<string, v.VariantOptions<string>, v.ErrorMessage<v.VariantIssue> | undefined>;
+/**
+* Object schema async type.
+*/
+type ObjectSchemaAsync = v.LooseObjectSchemaAsync<v.ObjectEntriesAsync, v.ErrorMessage<v.LooseObjectIssue> | undefined> | v.ObjectSchemaAsync<v.ObjectEntriesAsync, v.ErrorMessage<v.ObjectIssue> | undefined> | v.StrictObjectSchemaAsync<v.ObjectEntriesAsync, v.ErrorMessage<v.StrictObjectIssue> | undefined> | v.VariantSchemaAsync<string, v.VariantOptionsAsync<string>, v.ErrorMessage<v.VariantIssue> | undefined>;
+/**
+* Object root schema type.
+*/
+type ObjectRootSchema = ObjectSchema | v.IntersectSchema<ObjectSchema[], v.ErrorMessage<v.IntersectIssue> | undefined> | v.UnionSchema<ObjectSchema[], v.ErrorMessage<v.UnionIssue<v.BaseIssue<unknown>>> | undefined>;
+/**
+* Object root schema async type.
+*/
+type ObjectRootSchemaAsync = ObjectSchemaAsync | v.IntersectSchemaAsync<(ObjectSchema | ObjectSchemaAsync)[], v.ErrorMessage<v.IntersectIssue> | undefined> | v.UnionSchemaAsync<(ObjectSchema | ObjectSchemaAsync)[], v.ErrorMessage<v.UnionIssue<v.BaseIssue<unknown>>> | undefined>;
+/**
+* Form schema type.
+*
+* Hint: Forms must have an object root, so only object schemas (sync or async),
+* combinators (intersect, union, variant) whose options resolve to objects, and
+* `lazy` schemas wrapping any of these are allowed at the top level. Use
+* {@link Schema} for nested field schemas.
+*/
+type FormSchema = ObjectRootSchema | ObjectRootSchemaAsync | v.LazySchema<ObjectRootSchema> | v.LazySchemaAsync<ObjectRootSchema | ObjectRootSchemaAsync>;
 //#endregion
 //#region src/types/signal/signal.d.ts
 /**
@@ -224,7 +249,7 @@ type ValidationMode = "initial" | "touch" | "input" | "change" | "blur" | "submi
 /**
 * Form config interface.
 */
-interface FormConfig<TSchema extends Schema = Schema> {
+interface FormConfig<TSchema extends FormSchema = FormSchema> {
   /**
   * The schema of the form.
   */
@@ -245,7 +270,7 @@ interface FormConfig<TSchema extends Schema = Schema> {
 /**
 * Internal form store interface.
 */
-interface InternalFormStore<TSchema extends Schema = Schema> extends InternalObjectStore {
+interface InternalFormStore<TSchema extends FormSchema = FormSchema> extends InternalObjectStore {
   /**
   * The element of the form.
   */
@@ -282,7 +307,7 @@ interface InternalFormStore<TSchema extends Schema = Schema> extends InternalObj
 /**
 * Base form store interface.
 */
-interface BaseFormStore<TSchema extends Schema = Schema> {
+interface BaseFormStore<TSchema extends FormSchema = FormSchema> {
   /**
   * The internal form store.
   *
@@ -295,11 +320,11 @@ interface BaseFormStore<TSchema extends Schema = Schema> {
 /**
 * Submit handler type.
 */
-type SubmitHandler<TSchema extends Schema> = (output: v.InferOutput<TSchema>) => MaybePromise<unknown>;
+type SubmitHandler<TSchema extends FormSchema> = (output: v.InferOutput<TSchema>) => MaybePromise<unknown>;
 /**
 * Submit event handler type.
 */
-type SubmitEventHandler<TSchema extends Schema> = (output: v.InferOutput<TSchema>, event: FormEvent<HTMLFormElement>) => MaybePromise<unknown>;
+type SubmitEventHandler<TSchema extends FormSchema> = (output: v.InferOutput<TSchema>, event: FormEvent<HTMLFormElement>) => MaybePromise<unknown>;
 //#endregion
 //#region src/types/path/path.d.ts
 /**
@@ -402,6 +427,28 @@ type LazyArrayPath<TValue, TPathToCheck extends Path, TValidPath extends Path =
 * based on the given value.
 */
 type ValidArrayPath<TValue, TPath extends RequiredPath> = TPath extends LazyArrayPath<Required<TValue>, TPath> ? TPath : LazyArrayPath<Required<TValue>, TPath>;
+/**
+* Recursive helper for `DirtyPath` that prepends `TKey` to each deeper path,
+* or falls through to `never` when the child is not an object.
+*/
+type DeepDirtyPath<TChild, TKey$1 extends PathKey, TDepth extends 0[]> = TChild extends Record<PropertyKey, unknown> ? readonly [TKey$1, ...DirtyPath<TChild, [...TDepth, 0]>] : never;
+/**
+* Returns the union of all `RequiredPath`s that `getDirtyPaths` can emit
+* for a given input type. Object fields contribute their own path and the
+* paths of their descendants; arrays and tuples are atomic and contribute
+* only their own path, because dirty arrays are returned as complete units.
+*
+* Narrowing is exact for the first 5 levels of nesting; deeper paths fall
+* back to `RequiredPath` to keep the result a complete superset of any
+* path the runtime can address.
+*
+* Hint: Arrays and tuples are atomic because they don't structurally
+* extend `Record<PropertyKey, unknown>` and so fall through to `never`
+* via `DeepDirtyPath` — no explicit array check is needed. `TDepth` is
+* a tuple-length counter capped at 5 to bound TypeScript instantiation
+* cost.
+*/
+type DirtyPath<TValue, TDepth extends 0[] = []> = TDepth["length"] extends 5 ? RequiredPath : TValue extends Record<PropertyKey, unknown> ? { [TKey in ExactKeysOf<TValue>]: readonly [TKey] | DeepDirtyPath<NonNullable<PropertiesOf<TValue>[TKey]>, TKey, TDepth> }[ExactKeysOf<TValue>] : never;
 //#endregion
 //#region src/array/copyItemState/copyItemState.d.ts
 /**
@@ -419,7 +466,7 @@ type ValidArrayPath<TValue, TPath extends RequiredPath> = TPath extends LazyArra
 /**
 * Focus field config interface.
 */
-interface FocusFieldConfig<TSchema extends Schema, TFieldPath extends RequiredPath> {
+interface FocusFieldConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
   /**
   * The path to the field to focus.
   */
@@ -433,7 +480,7 @@ interface FocusFieldConfig<TSchema extends Schema, TFieldPath extends RequiredPa
 * @param form The form store containing the field.
 * @param config The focus field configuration.
 */
-declare function focus<TSchema extends Schema, TFieldPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: FocusFieldConfig<TSchema, TFieldPath>): void;
+declare function focus<TSchema extends FormSchema, TFieldPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: FocusFieldConfig<TSchema, TFieldPath>): void;
 //#endregion
 //#region src/getAllErrors/getAllErrors.d.ts
 /**
@@ -447,6 +494,93 @@ declare function focus<TSchema extends Schema, TFieldPath extends RequiredPath>(
 */
 declare function getAllErrors(form: BaseFormStore): [string, ...string[]] | null;
 //#endregion
+//#region src/getDirtyInput/getDirtyInput.d.ts
+/**
+* Get form dirty input config interface.
+*/
+interface GetFormDirtyInputConfig {
+  /**
+  * The path to a field. Leave undefined to get the dirty input of the entire
+  * form.
+  */
+  readonly path?: undefined;
+}
+/**
+* Get field dirty input config interface.
+*/
+interface GetFieldDirtyInputConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+  /**
+  * The path to the field to retrieve the dirty input from.
+  */
+  readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+/**
+* Retrieves only the dirty input values of a specific field or the entire
+* form. Arrays are treated as atomic and returned in full if any item is
+* dirty, while object keys without a dirty descendant are omitted. Returns
+* `undefined` if no field in the inspected subtree is dirty.
+*
+* @param form The form store to retrieve dirty input from.
+*
+* @returns The dirty input of the form or specified field, or `undefined`.
+*/
+declare function getDirtyInput<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): DeepPartial<v.InferInput<TSchema>> | undefined;
+/**
+* Retrieves only the dirty input values of a specific field or the entire
+* form. Arrays are treated as atomic and returned in full if any item is
+* dirty, while object keys without a dirty descendant are omitted. Returns
+* `undefined` if no field in the inspected subtree is dirty.
+*
+* @param form The form store to retrieve dirty input from.
+* @param config The get dirty input configuration.
+*
+* @returns The dirty input of the form or specified field, or `undefined`.
+*/
+declare function getDirtyInput<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? GetFieldDirtyInputConfig<TSchema, TFieldPath> : GetFormDirtyInputConfig): DeepPartial<TFieldPath extends RequiredPath ? PathValue<v.InferInput<TSchema>, TFieldPath> : v.InferInput<TSchema>> | undefined;
+//#endregion
+//#region src/getDirtyPaths/getDirtyPaths.d.ts
+/**
+* Get form dirty paths config interface.
+*/
+interface GetFormDirtyPathsConfig {
+  /**
+  * The path to a field. Leave undefined to inspect the entire form.
+  */
+  readonly path?: undefined;
+}
+/**
+* Get field dirty paths config interface.
+*/
+interface GetFieldDirtyPathsConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+  /**
+  * The path to the field to inspect.
+  */
+  readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+/**
+* Returns a list of paths to the dirty fields of a specific field or the
+* entire form. Arrays are treated as atomic and contribute only their own
+* path if any item is dirty, while object branches are recursed into. Returns
+* an empty list if no field in the inspected subtree is dirty.
+*
+* @param form The form store to inspect.
+*
+* @returns The list of paths to the dirty fields.
+*/
+declare function getDirtyPaths<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): DirtyPath<v.InferInput<TSchema>>[];
+/**
+* Returns a list of paths to the dirty fields of a specific field or the
+* entire form. Arrays are treated as atomic and contribute only their own
+* path if any item is dirty, while object branches are recursed into. Returns
+* an empty list if no field in the inspected subtree is dirty.
+*
+* @param form The form store to inspect.
+* @param config The get dirty paths configuration.
+*
+* @returns The list of paths to the dirty fields.
+*/
+declare function getDirtyPaths<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? GetFieldDirtyPathsConfig<TSchema, TFieldPath> : GetFormDirtyPathsConfig): DirtyPath<v.InferInput<TSchema>>[];
+//#endregion
 //#region src/getErrors/getErrors.d.ts
 /**
 * Get form errors config interface.
@@ -460,7 +594,7 @@ interface GetFormErrorsConfig {
 /**
 * Get field errors config interface.
 */
-interface GetFieldErrorsConfig<TSchema extends Schema, TFieldPath extends RequiredPath> {
+interface GetFieldErrorsConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
   /**
   * The path to the field to retrieve errors from.
   */
@@ -475,7 +609,7 @@ interface GetFieldErrorsConfig<TSchema extends Schema, TFieldPath extends Requir
 *
 * @returns A non-empty array of error messages, or null if no errors exist.
 */
-declare function getErrors<TSchema extends Schema>(form: BaseFormStore<TSchema>): [string, ...string[]] | null;
+declare function getErrors<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): [string, ...string[]] | null;
 /**
 * Retrieves error messages from the form. When called without a config,
 * returns form-level errors. When called with a path, returns errors for
@@ -486,7 +620,7 @@ declare function getErrors<TSchema extends Schema>(form: BaseFormStore<TSchema>)
 *
 * @returns A non-empty array of error messages, or null if no errors exist.
 */
-declare function getErrors<TSchema extends Schema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? GetFieldErrorsConfig<TSchema, TFieldPath> : GetFormErrorsConfig): [string, ...string[]] | null;
+declare function getErrors<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? GetFieldErrorsConfig<TSchema, TFieldPath> : GetFormErrorsConfig): [string, ...string[]] | null;
 //#endregion
 //#region src/getInput/getInput.d.ts
 /**
@@ -501,7 +635,7 @@ interface GetFormInputConfig {
 /**
 * Get field input config interface.
 */
-interface GetFieldInputConfig<TSchema extends Schema, TFieldPath extends RequiredPath> {
+interface GetFieldInputConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
   /**
   * The path to the field to retrieve input from.
   */
@@ -515,7 +649,7 @@ interface GetFieldInputConfig<TSchema extends Schema, TFieldPath extends Require
 *
 * @returns The partial input values of the form or the specified field.
 */
-declare function getInput<TSchema extends Schema>(form: BaseFormStore<TSchema>): PartialValues<v.InferInput<TSchema>>;
+declare function getInput<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): PartialValues<v.InferInput<TSchema>>;
 /**
 * Retrieves the current input value of a specific field or the entire form.
 * Returns a partial object as not all fields may have been set.
@@ -525,7 +659,7 @@ declare function getInput<TSchema extends Schema>(form: BaseFormStore<TSchema>):
 *
 * @returns The partial input values of the form or the specified field.
 */
-declare function getInput<TSchema extends Schema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? GetFieldInputConfig<TSchema, TFieldPath> : GetFormInputConfig): PartialValues<TFieldPath extends RequiredPath ? PathValue<v.InferInput<TSchema>, TFieldPath> : v.InferInput<TSchema>>;
+declare function getInput<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? GetFieldInputConfig<TSchema, TFieldPath> : GetFormInputConfig): PartialValues<TFieldPath extends RequiredPath ? PathValue<v.InferInput<TSchema>, TFieldPath> : v.InferInput<TSchema>>;
 //#endregion
 //#region src/handleSubmit/handleSubmit.react.d.ts
 /**
@@ -538,7 +672,7 @@ declare function getInput<TSchema extends Schema, TFieldPath extends RequiredPat
 *
 * @returns A submit event handler function to attach to the form element.
 */
-declare function handleSubmit<TSchema extends Schema>(form: BaseFormStore<TSchema>, handler: SubmitHandler<TSchema>): () => Promise<void>;
+declare function handleSubmit<TSchema extends FormSchema>(form: BaseFormStore<TSchema>, handler: SubmitHandler<TSchema>): () => Promise<void>;
 /**
 * Creates a submit event handler for the form that prevents default browser
 * submission, validates the form input, and calls the provided handler if
@@ -549,13 +683,13 @@ declare function handleSubmit<TSchema extends Schema>(form: BaseFormStore<TSchem
 *
 * @returns A submit event handler function to attach to the form element.
 */
-declare function handleSubmit<TSchema extends Schema>(form: BaseFormStore<TSchema>, handler: SubmitEventHandler<TSchema>): (event: FormEvent<HTMLFormElement>) => Promise<void>;
+declare function handleSubmit<TSchema extends FormSchema>(form: BaseFormStore<TSchema>, handler: SubmitEventHandler<TSchema>): (event: FormEvent<HTMLFormElement>) => Promise<void>;
 //#endregion
 //#region src/insert/insert.d.ts
 /**
 * Insert array field config interface.
 */
-interface InsertConfig<TSchema extends Schema, TFieldArrayPath extends RequiredPath> {
+interface InsertConfig<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath> {
   /**
   * The path to the field array to insert into.
   */
@@ -576,13 +710,13 @@ interface InsertConfig<TSchema extends Schema, TFieldArrayPath extends RequiredP
 * @param form The form store containing the field array.
 * @param config The insert configuration specifying the path, index, and initial value.
 */
-declare function insert<TSchema extends Schema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: InsertConfig<TSchema, TFieldArrayPath>): void;
+declare function insert<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: InsertConfig<TSchema, TFieldArrayPath>): void;
 //#endregion
 //#region src/move/move.d.ts
 /**
 * Move array field config interface.
 */
-interface MoveConfig<TSchema extends Schema, TFieldArrayPath extends RequiredPath> {
+interface MoveConfig<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath> {
   /**
   * The path to the field array to move an item within.
   */
@@ -603,13 +737,38 @@ interface MoveConfig<TSchema extends Schema, TFieldArrayPath extends RequiredPat
 * @param form The form store containing the field array.
 * @param config The move configuration specifying the path and source/destination indices.
 */
-declare function move<TSchema extends Schema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: MoveConfig<TSchema, TFieldArrayPath>): void;
+declare function move<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: MoveConfig<TSchema, TFieldArrayPath>): void;
+//#endregion
+//#region src/pickDirty/pickDirty.d.ts
+/**
+* Pick dirty config interface.
+*/
+interface PickDirtyConfig<TValue extends object> {
+  /**
+  * The value to filter down to its dirty parts. Must be structurally
+  * compatible with the form's schema.
+  */
+  readonly from: TValue;
+}
+/**
+* Picks only the dirty parts of the given value, using the form's dirty fields
+* as a structural mask. Arrays are treated as atomic and object keys without a
+* dirty descendant are omitted. Returns `undefined` if no field is dirty.
+* Useful for filtering a validated output down to its changed parts before
+* submitting.
+*
+* @param form The form store providing the dirty mask.
+* @param config The pick dirty configuration.
+*
+* @returns The dirty parts of the value, or `undefined`.
+*/
+declare function pickDirty<TSchema extends FormSchema, TValue extends object>(form: BaseFormStore<TSchema>, config: PickDirtyConfig<TValue>): DeepPartial<TValue> | undefined;
 //#endregion
 //#region src/remove/remove.d.ts
 /**
 * Remove array field config interface.
 */
-interface RemoveConfig<TSchema extends Schema, TFieldArrayPath extends RequiredPath> {
+interface RemoveConfig<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath> {
   /**
   * The path to the field array to remove an item from.
   */
@@ -626,13 +785,13 @@ interface RemoveConfig<TSchema extends Schema, TFieldArrayPath extends RequiredP
 * @param form The form store containing the field array.
 * @param config The remove configuration specifying the path and index.
 */
-declare function remove<TSchema extends Schema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: RemoveConfig<TSchema, TFieldArrayPath>): void;
+declare function remove<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: RemoveConfig<TSchema, TFieldArrayPath>): void;
 //#endregion
 //#region src/replace/replace.d.ts
 /**
 * Replace array field config interface.
 */
-interface ReplaceConfig<TSchema extends Schema, TFieldArrayPath extends RequiredPath> {
+interface ReplaceConfig<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath> {
   /**
   * The path to the field array to replace an item within.
   */
@@ -652,7 +811,7 @@ interface ReplaceConfig<TSchema extends Schema, TFieldArrayPath extends Required
 * @param form The form store containing the field array.
 * @param config The replace configuration specifying the path, index, and initial input.
 */
-declare function replace<TSchema extends Schema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: ReplaceConfig<TSchema, TFieldArrayPath>): void;
+declare function replace<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: ReplaceConfig<TSchema, TFieldArrayPath>): void;
 //#endregion
 //#region src/reset/reset.d.ts
 /**
@@ -675,7 +834,7 @@ interface ResetBaseConfig {
 /**
 * Reset form config interface.
 */
-interface ResetFormConfig<TSchema extends Schema> extends ResetBaseConfig {
+interface ResetFormConfig<TSchema extends FormSchema> extends ResetBaseConfig {
   /**
   * The path to a field. Leave undefined to reset the entire form.
   */
@@ -693,7 +852,7 @@ interface ResetFormConfig<TSchema extends Schema> extends ResetBaseConfig {
 /**
 * Reset field config interface.
 */
-interface ResetFieldConfig<TSchema extends Schema, TFieldPath extends RequiredPath> extends ResetBaseConfig {
+interface ResetFieldConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> extends ResetBaseConfig {
   /**
   * The path to the field to reset.
   */
@@ -720,7 +879,7 @@ declare function reset(form: BaseFormStore): void;
 * @param form The form store to reset.
 * @param config The reset configuration specifying what to reset and what to keep.
 */
-declare function reset<TSchema extends Schema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? ResetFieldConfig<TSchema, TFieldPath> : ResetFormConfig<TSchema>): void;
+declare function reset<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? ResetFieldConfig<TSchema, TFieldPath> : ResetFormConfig<TSchema>): void;
 //#endregion
 //#region src/setErrors/setErrors.d.ts
 /**
@@ -739,7 +898,7 @@ interface SetFormErrorsConfig {
 /**
 * Set field errors config interface.
 */
-interface SetFieldErrorsConfig<TSchema extends Schema, TFieldPath extends RequiredPath> {
+interface SetFieldErrorsConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
   /**
   * The path to the field to set errors on.
   */
@@ -757,13 +916,13 @@ interface SetFieldErrorsConfig<TSchema extends Schema, TFieldPath extends Requir
 * @param form The form store to set errors on.
 * @param config The set errors configuration specifying the path and error messages.
 */
-declare function setErrors<TSchema extends Schema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? SetFieldErrorsConfig<TSchema, TFieldPath> : SetFormErrorsConfig): void;
+declare function setErrors<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? SetFieldErrorsConfig<TSchema, TFieldPath> : SetFormErrorsConfig): void;
 //#endregion
 //#region src/setInput/setInput.d.ts
 /**
 * Set form input config interface.
 */
-interface SetFormInputConfig<TSchema extends Schema> {
+interface SetFormInputConfig<TSchema extends FormSchema> {
   /**
   * The path to a field. Leave undefined to set the entire form input.
   */
@@ -776,7 +935,7 @@ interface SetFormInputConfig<TSchema extends Schema> {
 /**
 * Set field input config interface.
 */
-interface SetFieldInputConfig<TSchema extends Schema, TFieldPath extends RequiredPath> {
+interface SetFieldInputConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
   /**
   * The path to the field to set input on.
   */
@@ -796,7 +955,7 @@ interface SetFieldInputConfig<TSchema extends Schema, TFieldPath extends Require
 * @param form The form store to set input on.
 * @param config The set form input configuration specifying the new input values.
 */
-declare function setInput<TSchema extends Schema>(form: BaseFormStore<TSchema>, config: SetFormInputConfig<TSchema>): void;
+declare function setInput<TSchema extends FormSchema>(form: BaseFormStore<TSchema>, config: SetFormInputConfig<TSchema>): void;
 /**
 * Sets the input value of a specific field or the entire form. This updates
 * the field value(s) and triggers validation if required by the form's
@@ -805,7 +964,7 @@ declare function setInput<TSchema extends Schema>(form: BaseFormStore<TSchema>,
 * @param form The form store to set input on.
 * @param config The set input configuration specifying the path and new value.
 */
-declare function setInput<TSchema extends Schema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? SetFieldInputConfig<TSchema, TFieldPath> : SetFormInputConfig<TSchema>): void;
+declare function setInput<TSchema extends FormSchema, TFieldPath extends RequiredPath | undefined = undefined>(form: BaseFormStore<TSchema>, config: TFieldPath extends RequiredPath ? SetFieldInputConfig<TSchema, TFieldPath> : SetFormInputConfig<TSchema>): void;
 //#endregion
 //#region src/submit/submit.d.ts
 /**
@@ -820,7 +979,7 @@ declare function submit(form: BaseFormStore): void;
 /**
 * Swap array field config interface.
 */
-interface SwapConfig<TSchema extends Schema, TFieldArrayPath extends RequiredPath> {
+interface SwapConfig<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath> {
   /**
   * The path to the field array to swap items within.
   */
@@ -840,7 +999,7 @@ interface SwapConfig<TSchema extends Schema, TFieldArrayPath extends RequiredPat
 * @param form The form store containing the field array.
 * @param config The swap configuration specifying the path and indices to swap.
 */
-declare function swap<TSchema extends Schema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: SwapConfig<TSchema, TFieldArrayPath>): void;
+declare function swap<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: SwapConfig<TSchema, TFieldArrayPath>): void;
 //#endregion
 //#region src/validate/validate.d.ts
 /**
@@ -862,7 +1021,7 @@ interface ValidateFormConfig {
 *
 * @returns A promise resolving to the validation result.
 */
-declare function validate<TSchema extends Schema>(form: BaseFormStore<TSchema>, config?: ValidateFormConfig): Promise<v.SafeParseResult<TSchema>>;
+declare function validate<TSchema extends FormSchema>(form: BaseFormStore<TSchema>, config?: ValidateFormConfig): Promise<v.SafeParseResult<TSchema>>;
 //#endregion
 //#endregion
 //#region src/types/field.d.ts
@@ -898,7 +1057,7 @@ interface FieldElementProps {
 /**
 * Field store interface.
 */
-interface FieldStore<TSchema extends Schema = Schema, TFieldPath extends RequiredPath = RequiredPath> {
+interface FieldStore<TSchema extends FormSchema = FormSchema, TFieldPath extends RequiredPath = RequiredPath> {
   /**
   * The path to the field within the form.
   */
@@ -935,7 +1094,7 @@ interface FieldStore<TSchema extends Schema = Schema, TFieldPath extends Require
 /**
 * Field array store interface.
 */
-interface FieldArrayStore<TSchema extends Schema = Schema, TFieldArrayPath extends RequiredPath = RequiredPath> {
+interface FieldArrayStore<TSchema extends FormSchema = FormSchema, TFieldArrayPath extends RequiredPath = RequiredPath> {
   /**
   * The path to the array field within the form.
   */
@@ -966,7 +1125,7 @@ interface FieldArrayStore<TSchema extends Schema = Schema, TFieldArrayPath exten
 /**
 * Form store interface.
 */
-interface FormStore<TSchema extends Schema = Schema> extends BaseFormStore<TSchema> {
+interface FormStore<TSchema extends FormSchema = FormSchema> extends BaseFormStore<TSchema> {
   /**
   * Whether the form is currently submitting.
   */
@@ -1004,7 +1163,7 @@ interface FormStore<TSchema extends Schema = Schema> extends BaseFormStore<TSche
 /**
 * Field component props interface.
 */
-interface FieldProps<TSchema extends Schema = Schema, TFieldPath extends RequiredPath = RequiredPath> {
+interface FieldProps<TSchema extends FormSchema = FormSchema, TFieldPath extends RequiredPath = RequiredPath> {
   /**
   * The form store to which the field belongs.
   */
@@ -1027,7 +1186,7 @@ interface FieldProps<TSchema extends Schema = Schema, TFieldPath extends Require
 *
 * @returns The UI of the field to be rendered.
 */
-declare function Field<TSchema extends Schema, TFieldPath extends RequiredPath>({
+declare function Field<TSchema extends FormSchema, TFieldPath extends RequiredPath>({
   of,
   path,
   children
@@ -1037,7 +1196,7 @@ declare function Field<TSchema extends Schema, TFieldPath extends RequiredPath>(
 /**
 * FieldArray component props interface.
 */
-interface FieldArrayProps<TSchema extends Schema = Schema, TFieldArrayPath extends RequiredPath = RequiredPath> {
+interface FieldArrayProps<TSchema extends FormSchema = FormSchema, TFieldArrayPath extends RequiredPath = RequiredPath> {
   /**
   * The form store to which the field array belongs.
   */
@@ -1061,7 +1220,7 @@ interface FieldArrayProps<TSchema extends Schema = Schema, TFieldArrayPath exten
 *
 * @returns The UI of the field array to be rendered.
 */
-declare function FieldArray<TSchema extends Schema, TFieldArrayPath extends RequiredPath>({
+declare function FieldArray<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>({
   of,
   path,
   children
@@ -1071,7 +1230,7 @@ declare function FieldArray<TSchema extends Schema, TFieldArrayPath extends Requ
 /**
 * Form component props type.
 */
-type FormProps<TSchema extends Schema = Schema> = Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "novalidate" | "noValidate"> & {
+type FormProps<TSchema extends FormSchema = FormSchema> = Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "novalidate" | "noValidate"> & {
   /**
   * The form store instance.
   */
@@ -1089,13 +1248,13 @@ type FormProps<TSchema extends Schema = Schema> = Omit<FormHTMLAttributes<HTMLFo
 *
 * @returns The a native form element.
 */
-declare function Form<TSchema extends Schema>(props: FormProps<TSchema>): ReactElement;
+declare function Form<TSchema extends FormSchema>(props: FormProps<TSchema>): ReactElement;
 //#endregion
 //#region src/hooks/useField/useField.d.ts
 /**
 * Use field config interface.
 */
-interface UseFieldConfig<TSchema extends Schema = Schema, TFieldPath extends RequiredPath = RequiredPath> {
+interface UseFieldConfig<TSchema extends FormSchema = FormSchema, TFieldPath extends RequiredPath = RequiredPath> {
   /**
   * The path to the field within the form schema.
   */
@@ -1109,13 +1268,13 @@ interface UseFieldConfig<TSchema extends Schema = Schema, TFieldPath extends Req
 *
 * @returns The field store with reactive properties and element props.
 */
-declare function useField<TSchema extends Schema, TFieldPath extends RequiredPath>(form: FormStore<TSchema>, config: UseFieldConfig<TSchema, TFieldPath>): FieldStore<TSchema, TFieldPath>;
+declare function useField<TSchema extends FormSchema, TFieldPath extends RequiredPath>(form: FormStore<TSchema>, config: UseFieldConfig<TSchema, TFieldPath>): FieldStore<TSchema, TFieldPath>;
 //#endregion
 //#region src/hooks/useFieldArray/useFieldArray.d.ts
 /**
 * Use field array config interface.
 */
-interface UseFieldArrayConfig<TSchema extends Schema = Schema, TFieldArrayPath extends RequiredPath = RequiredPath> {
+interface UseFieldArrayConfig<TSchema extends FormSchema = FormSchema, TFieldArrayPath extends RequiredPath = RequiredPath> {
   /**
   * The path to the array field within the form schema.
   */
@@ -1129,7 +1288,7 @@ interface UseFieldArrayConfig<TSchema extends Schema = Schema, TFieldArrayPath e
 *
 * @returns The field array store with reactive properties for array management.
 */
-declare function useFieldArray<TSchema extends Schema, TFieldArrayPath extends RequiredPath>(form: FormStore<TSchema>, config: UseFieldArrayConfig<TSchema, TFieldArrayPath>): FieldArrayStore<TSchema, TFieldArrayPath>;
+declare function useFieldArray<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>(form: FormStore<TSchema>, config: UseFieldArrayConfig<TSchema, TFieldArrayPath>): FieldArrayStore<TSchema, TFieldArrayPath>;
 //#endregion
 //#region src/hooks/useForm/useForm.d.ts
 /**
@@ -1140,6 +1299,6 @@ declare function useFieldArray<TSchema extends Schema, TFieldArrayPath extends R
 *
 * @returns The form store with reactive properties.
 */
-declare function useForm<TSchema extends Schema>(config: FormConfig<TSchema>): FormStore<TSchema>;
+declare function useForm<TSchema extends FormSchema>(config: FormConfig<TSchema>): FormStore<TSchema>;
 //#endregion
-export { type DeepPartial, Field, FieldArray, FieldArrayProps, FieldArrayStore, type FieldElement, FieldElementProps, FieldProps, FieldStore, FocusFieldConfig, Form, type FormConfig, FormProps, FormStore, GetFieldErrorsConfig, GetFieldInputConfig, GetFormErrorsConfig, GetFormInputConfig, InsertConfig, MoveConfig, type PartialValues, type PathValue, RemoveConfig, ReplaceConfig, type RequiredPath, ResetFieldConfig, ResetFormConfig, type Schema, SetFieldErrorsConfig, type SetFieldInputConfig, SetFormErrorsConfig, type SetFormInputConfig, type SubmitEventHandler, type SubmitHandler, SwapConfig, UseFieldArrayConfig, UseFieldConfig, type ValidArrayPath, type ValidPath, ValidateFormConfig, type ValidationMode, focus, getAllErrors, getErrors, getInput, handleSubmit, insert, move, remove, replace, reset, setErrors, setInput, submit, swap, useField, useFieldArray, useForm, validate };
+export { type DeepPartial, Field, FieldArray, FieldArrayProps, FieldArrayStore, type FieldElement, FieldElementProps, FieldProps, FieldStore, FocusFieldConfig, Form, type FormConfig, FormProps, type FormSchema, FormStore, GetFieldDirtyInputConfig, GetFieldDirtyPathsConfig, GetFieldErrorsConfig, GetFieldInputConfig, GetFormDirtyInputConfig, GetFormDirtyPathsConfig, GetFormErrorsConfig, GetFormInputConfig, InsertConfig, MoveConfig, type PartialValues, type PathValue, PickDirtyConfig, RemoveConfig, ReplaceConfig, type RequiredPath, ResetFieldConfig, ResetFormConfig, type Schema, SetFieldErrorsConfig, type SetFieldInputConfig, SetFormErrorsConfig, type SetFormInputConfig, type SubmitEventHandler, type SubmitHandler, SwapConfig, UseFieldArrayConfig, UseFieldConfig, type ValidArrayPath, type ValidPath, ValidateFormConfig, type ValidationMode, focus, getAllErrors, getDirtyInput, getDirtyPaths, getErrors, getInput, handleSubmit, insert, move, pickDirty, remove, replace, reset, setErrors, setInput, submit, swap, useField, useFieldArray, useForm, validate };

package/dist/index.js

@@ -319,6 +319,63 @@ function swapItemState(firstInternalFieldStore, secondInternalFieldStore) {
 	});
 }
 /**
+* Returns whether the specified boolean property is true for the field store
+* or any of its nested children. Recursively checks arrays and objects.
+*
+* @param internalFieldStore The field store to check.
+* @param type The boolean property type to check.
+*
+* @returns Whether the property is true.
+*/
+/* @__NO_SIDE_EFFECTS__ */
+function getFieldBool(internalFieldStore, type) {
+	if (internalFieldStore[type].value) return true;
+	if (internalFieldStore.kind === "array") {
+		for (let index = 0; index < internalFieldStore.items.value.length; index++) if (/* @__PURE__ */ getFieldBool(internalFieldStore.children[index], type)) return true;
+		return false;
+	}
+	if (internalFieldStore.kind == "object") {
+		for (const key in internalFieldStore.children) if (/* @__PURE__ */ getFieldBool(internalFieldStore.children[key], type)) return true;
+		return false;
+	}
+	return false;
+}
+/**
+* Returns only the dirty input of the field store. Arrays are treated as
+* atomic and returned in full if any item is dirty, while object keys without
+* a dirty descendant are omitted. Returns `undefined` if no descendant is
+* dirty.
+*
+* @param internalFieldStore The field store to get dirty input from.
+* @param dirtyOnly Whether to only include dirty fields. Defaults to `true`.
+*
+* @returns The dirty input, or `undefined` if no descendant is dirty.
+*/
+/* @__NO_SIDE_EFFECTS__ */
+function getDirtyFieldInput(internalFieldStore, dirtyOnly = true) {
+	if (dirtyOnly && !/* @__PURE__ */ getFieldBool(internalFieldStore, "isDirty")) return;
+	if (internalFieldStore.kind === "array") {
+		if (internalFieldStore.input.value) {
+			const value = [];
+			for (let index = 0; index < internalFieldStore.items.value.length; index++) value[index] = /* @__PURE__ */ getDirtyFieldInput(internalFieldStore.children[index], false);
+			return value;
+		}
+		return internalFieldStore.input.value;
+	}
+	if (internalFieldStore.kind === "object") {
+		if (internalFieldStore.input.value) {
+			const value = {};
+			for (const key in internalFieldStore.children) {
+				const child = internalFieldStore.children[key];
+				if (!dirtyOnly || /* @__PURE__ */ getFieldBool(child, "isDirty")) value[key] = /* @__PURE__ */ getDirtyFieldInput(child, dirtyOnly);
+			}
+			return value;
+		}
+		return internalFieldStore.input.value;
+	}
+	return internalFieldStore.input.value;
+}
+/**
 * Returns the current input of the field store. For arrays and objects,
 * recursively collects input from all children. Returns `null` or `undefined`
 * for nullish array/object inputs, or the primitive value for value fields.
@@ -375,28 +432,6 @@ function getElementInput(element, internalFieldStore) {
 	return element.value;
 }
 /**
-* Returns whether the specified boolean property is true for the field store
-* or any of its nested children. Recursively checks arrays and objects.
-*
-* @param internalFieldStore The field store to check.
-* @param type The boolean property type to check.
-*
-* @returns Whether the property is true.
-*/
-/* @__NO_SIDE_EFFECTS__ */
-function getFieldBool(internalFieldStore, type) {
-	if (internalFieldStore[type].value) return true;
-	if (internalFieldStore.kind === "array") {
-		for (let index = 0; index < internalFieldStore.items.value.length; index++) if (/* @__PURE__ */ getFieldBool(internalFieldStore.children[index], type)) return true;
-		return false;
-	}
-	if (internalFieldStore.kind == "object") {
-		for (const key in internalFieldStore.children) if (/* @__PURE__ */ getFieldBool(internalFieldStore.children[key], type)) return true;
-		return false;
-	}
-	return false;
-}
-/**
 * Returns the field store at the specified path by traversing the form store's
 * children hierarchy.
 *
@@ -653,6 +688,17 @@ function getAllErrors(form) {
 	return allErrors;
 }
 /* @__NO_SIDE_EFFECTS__ */
+function getDirtyInput(form, config) {
+	return getDirtyFieldInput(config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL]);
+}
+/* @__NO_SIDE_EFFECTS__ */
+function getDirtyPaths(form, config) {
+	config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL];
+	const paths = [];
+	config?.path && [...config.path];
+	return paths;
+}
+/* @__NO_SIDE_EFFECTS__ */
 function getErrors(form, config) {
 	return (config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL]).errors.value;
 }
@@ -750,6 +796,48 @@ function move(form, config) {
 	});
 }
 /**
+* Picks only the dirty parts of the given value, using the form's dirty fields
+* as a structural mask. Arrays are treated as atomic and object keys without a
+* dirty descendant are omitted. Returns `undefined` if no field is dirty.
+* Useful for filtering a validated output down to its changed parts before
+* submitting.
+*
+* @param form The form store providing the dirty mask.
+* @param config The pick dirty configuration.
+*
+* @returns The dirty parts of the value, or `undefined`.
+*/
+/* @__NO_SIDE_EFFECTS__ */
+function pickDirty(form, config) {
+	if (!getFieldBool(form[INTERNAL], "isDirty")) return;
+	const result = /* @__PURE__ */ pickFieldValue(form[INTERNAL], config.from);
+	return Object.keys(result).length ? result : void 0;
+}
+/**
+* Recursively picks the dirty parts of a value using the field store as a
+* structural mask, reading from the supplied value rather than the form's own
+* input. Objects with non-nullish input recurse into their dirty children that
+* are present in the value, while arrays, primitives, nullish-cleared fields
+* and shape-diverging values are returned as-is.
+*
+* @param internalFieldStore The field store used as the dirty mask.
+* @param value The value to pick the dirty parts from.
+*
+* @returns The dirty parts of the value.
+*/
+/* @__NO_SIDE_EFFECTS__ */
+function pickFieldValue(internalFieldStore, value) {
+	if (internalFieldStore.kind === "object" && internalFieldStore.input.value && value && typeof value === "object" && !Array.isArray(value)) {
+		const result = {};
+		for (const key in internalFieldStore.children) {
+			const child = internalFieldStore.children[key];
+			if (getFieldBool(child, "isDirty") && key in value) result[key] = /* @__PURE__ */ pickFieldValue(child, value[key]);
+		}
+		return result;
+	}
+	return value;
+}
+/**
 * Removes an item from a field array at the specified index. All items after
 * the removed item are shifted down by one index.
 *
@@ -1070,4 +1158,4 @@ function Form({ of, onSubmit, ...other }) {
 }
 
 //#endregion
-export { Field, FieldArray, Form, focus, getAllErrors, getErrors, getInput, handleSubmit, insert, move, remove, replace, reset, setErrors, setInput, submit, swap, useField, useFieldArray, useForm, validate };
+export { Field, FieldArray, Form, focus, getAllErrors, getDirtyInput, getDirtyPaths, getErrors, getInput, handleSubmit, insert, move, pickDirty, remove, replace, reset, setErrors, setInput, submit, swap, useField, useFieldArray, useForm, validate };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formisch/react",
   "description": "The lightweight, schema-first, and fully type-safe form library for React",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "license": "MIT",
   "author": "Fabian Hiller",
   "homepage": "https://formisch.dev",
@@ -68,7 +68,7 @@
     "react": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
     "react-dom": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
     "typescript": ">=5",
-    "valibot": "^1.0.0"
+    "valibot": "^1.4.1"
   },
   "peerDependenciesMeta": {
     "typescript": {