@formisch/react 0.5.0 → 0.6.0

package/README.md

@@ -9,6 +9,7 @@ Formisch is also available for [Preact][formisch-preact], [Qwik][formisch-qwik],
 - Small bundle size starting at 2.5 kB
 - Schema-based validation with Valibot
 - Type safety with autocompletion in editor
+- Open source and fully tested with 100 % coverage
 - It's fast – re-renders only if necessary
 - Minimal, readable and well thought out API
 - Supports all native HTML form fields

package/dist/index.d.ts

@@ -72,6 +72,13 @@ interface InternalBaseStore {
   schema: Schema;
   /**
   * The initial elements of the field.
+  *
+  * Hint: This may look unused, but do not remove it. `copyItemState` and
+  * `swapItemState` move the `elements` reference between field stores when
+  * array items are inserted, moved, removed or swapped, and `reset` restores
+  * each field's original element via `elements = initialElements`. Without it,
+  * focus and file reset target the wrong element after a reorder followed by a
+  * reset.
   */
   initialElements: FieldElement[];
   /**
@@ -395,7 +402,10 @@ type ExactRequired<TValue> = TValue extends Record<PropertyKey, unknown> ? IsExa
 */
 type PathValue<TValue, TPath extends Path> = TPath extends readonly [infer TKey, ...infer TRest extends Path] ? TKey extends ExactKeysOf<ExactRequired<TValue>> ? PathValue<PropertiesOf<ExactRequired<TValue>>[TKey], TRest> : unknown : TValue;
 /**
-* Checks whether a value is an array or contains one anywhere in its shape.
+* Checks whether a value is a dynamic array or contains one anywhere in its
+* shape. A fixed-length tuple is not itself a dynamic array, but it counts when
+* it contains one, so paths can still navigate through tuples to reach nested
+* arrays.
 *
 * Hint: The inner conditionals (`TValue extends readonly unknown[]` and
 * `TValue extends Record<PropertyKey, unknown>`) distribute over union members,
@@ -406,7 +416,7 @@ type PathValue<TValue, TPath extends Path> = TPath extends readonly [infer TKey,
 * `true extends ...`, which is `true` whenever at least one union member
 * contributed `true`.
 */
-type IsOrHasArray<TValue> = true extends (IsAny<TValue> extends true ? false : TValue extends readonly unknown[] ? true : TValue extends Record<PropertyKey, unknown> ? { [TKey in keyof TValue]: IsOrHasArray<TValue[TKey]> }[keyof TValue] : false) ? true : false;
+type IsOrHasArray<TValue> = true extends (IsAny<TValue> extends true ? false : TValue extends readonly unknown[] ? number extends TValue["length"] ? true : IsOrHasArray<TValue[number]> : TValue extends Record<PropertyKey, unknown> ? { [TKey in keyof TValue]: IsOrHasArray<TValue[TKey]> }[keyof TValue] : false) ? true : false;
 /**
 * Extracts the exact keys of a tuple, array or object that contain arrays.
 */
@@ -421,7 +431,7 @@ type PropertiesOfArrayPath<TValue> = { [TKey in ExactKeysOfArrayPath<TValue>]: T
 /**
 * Lazily evaluates only the first valid array path segment based on the given value.
 */
-type LazyArrayPath<TValue, TPathToCheck extends Path, TValidPath extends Path = readonly []> = TPathToCheck extends readonly [] ? TValue extends readonly unknown[] ? TValidPath : readonly [...TValidPath, ExactKeysOfArrayPath<TValue>] : TPathToCheck extends readonly [infer TFirstKey extends ExactKeysOfArrayPath<TValue>, ...infer TPathRest extends Path] ? LazyArrayPath<Required<PropertiesOfArrayPath<TValue>[TFirstKey]>, TPathRest, readonly [...TValidPath, TFirstKey]> : IsNever<ExactKeysOfArrayPath<TValue>> extends false ? readonly [...TValidPath, ExactKeysOfArrayPath<TValue>] : never;
+type LazyArrayPath<TValue, TPathToCheck extends Path, TValidPath extends Path = readonly []> = TPathToCheck extends readonly [] ? TValue extends readonly unknown[] ? number extends TValue["length"] ? TValidPath : IsNever<ExactKeysOfArrayPath<TValue>> extends false ? readonly [...TValidPath, ExactKeysOfArrayPath<TValue>] : never : readonly [...TValidPath, ExactKeysOfArrayPath<TValue>] : TPathToCheck extends readonly [infer TFirstKey extends ExactKeysOfArrayPath<TValue>, ...infer TPathRest extends Path] ? LazyArrayPath<Required<PropertiesOfArrayPath<TValue>[TFirstKey]>, TPathRest, readonly [...TValidPath, TFirstKey]> : IsNever<ExactKeysOfArrayPath<TValue>> extends false ? readonly [...TValidPath, ExactKeysOfArrayPath<TValue>] : never;
 /**
 * Returns the path if valid, otherwise the first possible valid array path
 * based on the given value.
@@ -473,7 +483,7 @@ interface FocusFieldConfig<TSchema extends FormSchema, TFieldPath extends Requir
   readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
 }
 /**
-* Focuses the first input element of a field. This is useful for
+* Focuses the first focusable input element of a field. This is useful for
 * programmatically setting focus to a specific field, such as after
 * validation errors or user interactions.
 *

package/dist/index.js

@@ -228,31 +228,45 @@ function copyItemState(fromInternalFieldStore, toInternalFieldStore) {
 * form reset functionality.
 *
 * @param internalFieldStore The field store to reset.
-* @param initialInput The new input value (can be any type including array or object).
+* @param input The new input value (can be any type including array or object).
+* @param keepStart Whether to keep `startInput` and `startItems` as the dirty
+* baseline instead of resetting them to the new input. Used when a field store
+* is reused for an in-place edit so its dirty state is detected correctly.
 */
-function resetItemState(internalFieldStore, initialInput) {
+function resetItemState(internalFieldStore, input, keepStart = false) {
 	batch(() => {
-		internalFieldStore.elements = [];
+		const elements = [];
+		if (internalFieldStore.elements === internalFieldStore.initialElements) internalFieldStore.initialElements = elements;
+		internalFieldStore.elements = elements;
 		internalFieldStore.errors.value = null;
 		internalFieldStore.isTouched.value = false;
 		internalFieldStore.isDirty.value = false;
 		if (internalFieldStore.kind === "array" || internalFieldStore.kind === "object") {
-			const objectInput = initialInput == null ? initialInput : true;
-			internalFieldStore.startInput.value = objectInput;
+			const objectInput = input == null ? input : true;
+			if (!keepStart) internalFieldStore.startInput.value = objectInput;
 			internalFieldStore.input.value = objectInput;
-			if (internalFieldStore.kind === "array") if (initialInput) {
-				const newItems = initialInput.map(createId);
-				internalFieldStore.startItems.value = newItems;
+			if (internalFieldStore.kind === "array") if (input) {
+				const length = internalFieldStore.schema.type === "array" ? input.length : internalFieldStore.children.length;
+				const newItems = Array.from({ length }, createId);
+				if (!keepStart) internalFieldStore.startItems.value = newItems;
 				internalFieldStore.items.value = newItems;
-				for (let index = 0; index < initialInput.length; index++) if (internalFieldStore.children[index]) resetItemState(internalFieldStore.children[index], initialInput[index]);
+				let path;
+				for (let index = 0; index < length; index++) if (internalFieldStore.children[index]) resetItemState(internalFieldStore.children[index], input[index], keepStart);
+				else {
+					path ??= JSON.parse(internalFieldStore.name);
+					internalFieldStore.children[index] = {};
+					path.push(index);
+					initializeFieldStore(internalFieldStore.children[index], internalFieldStore.schema.item, input[index], path);
+					path.pop();
+				}
 			} else {
-				internalFieldStore.startItems.value = [];
+				if (!keepStart) internalFieldStore.startItems.value = [];
 				internalFieldStore.items.value = [];
 			}
-			else for (const key in internalFieldStore.children) resetItemState(internalFieldStore.children[key], initialInput?.[key]);
+			else for (const key in internalFieldStore.children) resetItemState(internalFieldStore.children[key], input?.[key], keepStart);
 		} else {
-			internalFieldStore.startInput.value = initialInput;
-			internalFieldStore.input.value = initialInput;
+			if (!keepStart) internalFieldStore.startInput.value = input;
+			internalFieldStore.input.value = input;
 		}
 	});
 }
@@ -319,6 +333,28 @@ function swapItemState(firstInternalFieldStore, secondInternalFieldStore) {
 	});
 }
 /**
+* Focuses the first focusable element of a field store. The elements are tried
+* in order and the first one that actually receives focus wins, so detached,
+* disabled or hidden elements are skipped. The browser decides focusability,
+* which is read back via the element's root `activeElement` so elements in a
+* shadow root or another document are handled correctly.
+*
+* Hint: A `display: none` or `hidden` element is correctly skipped in real
+* browsers, but jsdom has no layout and focuses it anyway, so that case cannot
+* be covered by unit tests.
+*
+* @param internalFieldStore The field store to focus.
+*
+* @returns Whether an element was focused.
+*/
+function focusFieldElement(internalFieldStore) {
+	for (const element of internalFieldStore.elements) {
+		element.focus();
+		if (element.getRootNode().activeElement === element) return true;
+	}
+	return false;
+}
+/**
 * Returns whether the specified boolean property is true for the field store
 * or any of its nested children. Recursively checks arrays and objects.
 *
@@ -456,11 +492,9 @@ function getFieldStore(internalFormStore, path) {
 */
 function setFieldBool(internalFieldStore, type, bool) {
 	batch(() => {
-		if (internalFieldStore.kind === "array") {
-			internalFieldStore[type].value = bool;
-			for (let index = 0; index < untrack(() => internalFieldStore.items.value).length; index++) setFieldBool(internalFieldStore.children[index], type, bool);
-		} else if (internalFieldStore.kind == "object") for (const key in internalFieldStore.children) setFieldBool(internalFieldStore.children[key], type, bool);
-		else internalFieldStore[type].value = bool;
+		internalFieldStore[type].value = bool;
+		if (internalFieldStore.kind === "array") for (let index = 0; index < untrack(() => internalFieldStore.items.value).length; index++) setFieldBool(internalFieldStore.children[index], type, bool);
+		else if (internalFieldStore.kind === "object") for (const key in internalFieldStore.children) setFieldBool(internalFieldStore.children[key], type, bool);
 	});
 }
 /**
@@ -475,20 +509,20 @@ function setNestedInput(internalFieldStore, input) {
 	if (internalFieldStore.kind === "array") {
 		const arrayInput = input ?? [];
 		const items = internalFieldStore.items.value;
-		if (arrayInput.length < items.length) internalFieldStore.items.value = items.slice(0, arrayInput.length);
-		else if (arrayInput.length > items.length) {
-			if (arrayInput.length > internalFieldStore.children.length) {
-				const path = JSON.parse(internalFieldStore.name);
-				for (let index = internalFieldStore.children.length; index < arrayInput.length; index++) {
-					internalFieldStore.children[index] = {};
-					path.push(index);
-					initializeFieldStore(internalFieldStore.children[index], internalFieldStore.schema.item, arrayInput[index], path);
-					path.pop();
-				}
+		const length = internalFieldStore.schema.type === "array" ? arrayInput.length : internalFieldStore.children.length;
+		if (length < items.length) internalFieldStore.items.value = items.slice(0, length);
+		else if (length > items.length) {
+			const path = JSON.parse(internalFieldStore.name);
+			for (let index = items.length; index < length; index++) if (internalFieldStore.children[index]) resetItemState(internalFieldStore.children[index], arrayInput[index], true);
+			else {
+				internalFieldStore.children[index] = {};
+				path.push(index);
+				initializeFieldStore(internalFieldStore.children[index], internalFieldStore.schema.item, arrayInput[index], path);
+				path.pop();
 			}
-			internalFieldStore.items.value = [...items, ...arrayInput.slice(items.length).map(createId)];
+			internalFieldStore.items.value = [...items, ...Array.from({ length: length - items.length }, createId)];
 		}
-		for (let index = 0; index < arrayInput.length; index++) setNestedInput(internalFieldStore.children[index], arrayInput[index]);
+		for (let index = 0; index < length; index++) setNestedInput(internalFieldStore.children[index], arrayInput[index]);
 		internalFieldStore.input.value = input == null ? input : true;
 		internalFieldStore.isDirty.value = internalFieldStore.startInput.value !== internalFieldStore.input.value || internalFieldStore.startItems.value.length !== internalFieldStore.items.value.length;
 	} else if (internalFieldStore.kind === "object") {
@@ -532,21 +566,22 @@ function setFieldInput(internalFormStore, path, input) {
 function setInitialFieldInput(internalFieldStore, initialInput) {
 	batch(() => {
 		if (internalFieldStore.kind === "array") {
-			internalFieldStore.input.value = initialInput == null ? initialInput : true;
+			internalFieldStore.initialInput.value = initialInput == null ? initialInput : true;
 			const initialArrayInput = initialInput ?? [];
-			if (initialArrayInput.length > internalFieldStore.children.length) {
+			const length = internalFieldStore.schema.type === "array" ? initialArrayInput.length : internalFieldStore.children.length;
+			if (length > internalFieldStore.children.length) {
 				const path = JSON.parse(internalFieldStore.name);
-				for (let index = internalFieldStore.children.length; index < initialArrayInput.length; index++) {
+				for (let index = internalFieldStore.children.length; index < length; index++) {
 					internalFieldStore.children[index] = {};
 					path.push(index);
 					initializeFieldStore(internalFieldStore.children[index], internalFieldStore.schema.item, initialArrayInput[index], path);
 					path.pop();
 				}
 			}
-			internalFieldStore.initialItems.value = initialArrayInput.map(createId);
+			internalFieldStore.initialItems.value = Array.from({ length }, createId);
 			for (let index = 0; index < internalFieldStore.children.length; index++) setInitialFieldInput(internalFieldStore.children[index], initialArrayInput[index]);
 		} else if (internalFieldStore.kind === "object") {
-			internalFieldStore.input.value = initialInput == null ? initialInput : true;
+			internalFieldStore.initialInput.value = initialInput == null ? initialInput : true;
 			for (const key in internalFieldStore.children) setInitialFieldInput(internalFieldStore.children[key], initialInput?.[key]);
 		} else internalFieldStore.initialInput.value = initialInput;
 	});
@@ -598,44 +633,49 @@ function createFormStore(config, parse) {
 async function validateFormInput(internalFormStore, config) {
 	internalFormStore.validators++;
 	internalFormStore.isValidating.value = true;
-	const result = await internalFormStore.parse(untrack(() => /* @__PURE__ */ getFieldInput(internalFormStore)));
-	let rootErrors;
-	let nestedErrors;
-	if (result.issues) {
-		nestedErrors = {};
-		for (const issue of result.issues) if (issue.path) {
-			const path = [];
-			for (const pathItem of issue.path) {
-				const key = pathItem.key;
-				const keyType = typeof key;
-				const itemType = pathItem.type;
-				if (keyType !== "string" && keyType !== "number" || itemType === "map" || itemType === "set") break;
-				path.push(key);
-			}
-			const name = JSON.stringify(path);
-			const fieldErrors = nestedErrors[name];
-			if (fieldErrors) fieldErrors.push(issue.message);
-			else nestedErrors[name] = [issue.message];
-		} else if (rootErrors) rootErrors.push(issue.message);
-		else rootErrors = [issue.message];
-	}
-	let shouldFocus = config?.shouldFocus ?? false;
-	batch(() => {
-		walkFieldStore(internalFormStore, (internalFieldStore) => {
-			if (internalFieldStore.name === "[]") internalFieldStore.errors.value = rootErrors ?? null;
-			else {
-				const fieldErrors = nestedErrors?.[internalFieldStore.name] ?? null;
-				internalFieldStore.errors.value = fieldErrors;
-				if (shouldFocus && fieldErrors) {
-					internalFieldStore.elements[0]?.focus();
-					shouldFocus = false;
+	try {
+		const result = await internalFormStore.parse(untrack(() => /* @__PURE__ */ getFieldInput(internalFormStore)));
+		let rootErrors;
+		let nestedErrors;
+		if (result.issues) {
+			nestedErrors = {};
+			for (const issue of result.issues) if (issue.path) {
+				const path = [];
+				for (const pathItem of issue.path) {
+					const key = pathItem.key;
+					const keyType = typeof key;
+					const itemType = pathItem.type;
+					if (keyType !== "string" && keyType !== "number" || itemType === "map" || itemType === "set") break;
+					path.push(key);
 				}
-			}
+				const name = JSON.stringify(path);
+				const fieldErrors = nestedErrors[name];
+				if (fieldErrors) fieldErrors.push(issue.message);
+				else nestedErrors[name] = [issue.message];
+			} else if (rootErrors) rootErrors.push(issue.message);
+			else rootErrors = [issue.message];
+		}
+		let shouldFocus = config?.shouldFocus ?? false;
+		batch(() => {
+			walkFieldStore(internalFormStore, (internalFieldStore) => {
+				if (internalFieldStore.name === "[]") internalFieldStore.errors.value = rootErrors ?? null;
+				else {
+					const fieldErrors = nestedErrors?.[internalFieldStore.name] ?? null;
+					internalFieldStore.errors.value = fieldErrors;
+					if (shouldFocus && fieldErrors && focusFieldElement(internalFieldStore)) shouldFocus = false;
+				}
+			});
+			internalFormStore.validators--;
+			internalFormStore.isValidating.value = internalFormStore.validators > 0;
 		});
-		internalFormStore.validators--;
-		internalFormStore.isValidating.value = internalFormStore.validators > 0;
-	});
-	return result;
+		return result;
+	} catch (error) {
+		batch(() => {
+			internalFormStore.validators--;
+			internalFormStore.isValidating.value = internalFormStore.validators > 0;
+		});
+		throw error;
+	}
 }
 /**
 * Validates the form input if required based on the validation mode and form
@@ -657,7 +697,7 @@ const INTERNAL = "~internal";
 //#endregion
 //#region ../../packages/methods/dist/index.react.js
 /**
-* Focuses the first input element of a field. This is useful for
+* Focuses the first focusable input element of a field. This is useful for
 * programmatically setting focus to a specific field, such as after
 * validation errors or user interactions.
 *
@@ -665,7 +705,7 @@ const INTERNAL = "~internal";
 * @param config The focus field configuration.
 */
 function focus(form, config) {
-	getFieldStore(form[INTERNAL], config.path).elements[0]?.focus();
+	focusFieldElement(getFieldStore(form[INTERNAL], config.path));
 }
 /**
 * Retrieves all error messages from all fields in the form by walking through
@@ -1001,7 +1041,9 @@ function useField(form, config) {
 	const internalFieldStore = getFieldStore(internalFormStore, config.path);
 	useEffect(() => {
 		return () => {
-			internalFieldStore.elements = internalFieldStore.elements.filter((element) => element.isConnected);
+			const elements = internalFieldStore.elements.filter((element) => element.isConnected);
+			if (internalFieldStore.elements === internalFieldStore.initialElements) internalFieldStore.initialElements = elements;
+			internalFieldStore.elements = elements;
 		};
 	}, [internalFieldStore]);
 	return useMemo(() => ({

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.5.0",
+  "version": "0.6.0",
   "license": "MIT",
   "author": "Fabian Hiller",
   "homepage": "https://formisch.dev",
@@ -51,7 +51,7 @@
     "@types/react": "^19.2.5",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.1.1",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/coverage-v8": "^4.1.7",
     "eslint": "^9.39.1",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.24",
@@ -62,7 +62,7 @@
     "tsdown": "^0.16.8",
     "typescript": "~5.9.3",
     "vite": "^7.2.4",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.7"
   },
   "peerDependencies": {
     "react": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",