@formisch/preact 0.5.0 → 0.6.0

package/dist/index.js

@@ -4,13 +4,29 @@ import { useLayoutEffect, useMemo } from "preact/hooks";
 import { jsx } from "preact/jsx-runtime";
 
 //#region ../../packages/core/dist/index.preact.js
+/**
+* The current framework being used.
+*/
 const framework = "preact";
+/**
+* Creates a unique identifier string.
+*
+* @returns The unique identifier.
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function createId() {
 	return Math.random().toString(36).slice(2);
 }
 /**
-* TODO: Add comment
-* TODO: Should this stay in /primitives or move to /utils?
+* Initializes a field store recursively based on the schema structure. Handles
+* array, object, and value schemas, setting up all necessary signals and
+* children. Supports wrapped schemas and schema options.
+*
+* @param internalFieldStore The partial field store to initialize.
+* @param schema The Valibot schema defining the field structure.
+* @param initialInput The initial input value.
+* @param path The path to the field in the form.
+* @param nullish Whether the schema is wrapped in a nullish schema.
 */
 function initializeFieldStore(internalFieldStore, schema, initialInput, path, nullish = false) {
 	if (framework === "qwik" && schema.type === "lazy" || schema.type === "object_with_rest" || schema.type === "record" || schema.type === "tuple_with_rest" || schema.type === "promise") throw new Error(`"${schema.type}" schema is not supported`);
@@ -81,13 +97,13 @@ function initializeFieldStore(internalFieldStore, schema, initialInput, path, nu
 	}
 }
 /**
-* Copies the deeply nested state (signal values) from one array item to another.
-* This includes the `isTouched`, `isDirty`, `startInput`, `input`, `startItems`, and `items` properties.
+* Copies the deeply nested state (signal values) from one field store to
+* another. This includes the `elements`, `errors`, `startInput`, `input`,
+* `isTouched`, `isDirty`, and for arrays `startItems` and `items` properties.
 * Recursively walks through the field stores and copies all signal values.
 *
-* @param internalArrayStore - The field store of the array (not the array item)
-* @param fromIndex - The source index to copy from
-* @param toIndex - The destination index to copy to
+* @param fromInternalFieldStore The source field store to copy from.
+* @param toInternalFieldStore The destination field store to copy to.
 */
 function copyItemState(fromInternalFieldStore, toInternalFieldStore) {
 	batch(() => {
@@ -118,13 +134,14 @@ function copyItemState(fromInternalFieldStore, toInternalFieldStore) {
 	});
 }
 /**
-* Resets the state of an array item (signal values) deeply nested.
-* Sets `isTouched` and `isDirty` to `false` and `startInput`, `input`,
-* `startItems` and `items` to the new input.
-* Keeps the `initialInput` and `initialItems` state unchanged for form reset functionality.
+* Resets the state of a field store (signal values) deeply nested. Sets
+* `elements` to empty array, `errors` to `null`, `isTouched` and `isDirty` to
+* `false`, and `startInput`, `input`, `startItems`, and `items` to the new
+* input value. Keeps the `initialInput` and `initialItems` state unchanged for
+* form reset functionality.
 *
-* @param internalFieldStore - The field store of the array item
-* @param initialInput - The new input value (can be any type including array or object)
+* @param internalFieldStore The field store to reset.
+* @param initialInput The new input value (can be any type including array or object).
 */
 function resetItemState(internalFieldStore, initialInput) {
 	batch(() => {
@@ -153,12 +170,13 @@ function resetItemState(internalFieldStore, initialInput) {
 	});
 }
 /**
-* Swaps the deeply nested state (signal values) between two field stores.
-* This includes the `isTouched`, `isDirty`, `startInput`, `input`, `startItems`, and `items` properties.
-* Recursively walks through the field stores and swaps all signal values.
+* Swaps the deeply nested state (signal values) between two field stores. This
+* includes the `elements`, `errors`, `startInput`, `input`, `isTouched`,
+* `isDirty`, and for arrays `startItems` and `items` properties. Recursively
+* walks through the field stores and swaps all signal values.
 *
-* @param firstInternalFieldStore - The first field store to swap
-* @param secondInternalFieldStore - The second field store to swap
+* @param firstInternalFieldStore The first field store to swap.
+* @param secondInternalFieldStore The second field store to swap.
 */
 function swapItemState(firstInternalFieldStore, secondInternalFieldStore) {
 	batch(() => {
@@ -213,11 +231,21 @@ function swapItemState(firstInternalFieldStore, secondInternalFieldStore) {
 		});
 	});
 }
+/**
+* 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.
+*
+* @param internalFieldStore The field store to get input from.
+*
+* @returns The field input.
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getFieldInput(internalFieldStore) {
 	if (internalFieldStore.kind === "array") {
 		if (internalFieldStore.input.value) {
 			const value = [];
-			for (let index = 0; index < internalFieldStore.items.value.length; index++) value[index] = getFieldInput(internalFieldStore.children[index]);
+			for (let index = 0; index < internalFieldStore.items.value.length; index++) value[index] = /* @__PURE__ */ getFieldInput(internalFieldStore.children[index]);
 			return value;
 		}
 		return internalFieldStore.input.value;
@@ -225,7 +253,7 @@ function getFieldInput(internalFieldStore) {
 	if (internalFieldStore.kind === "object") {
 		if (internalFieldStore.input.value) {
 			const value = {};
-			for (const key in internalFieldStore.children) value[key] = getFieldInput(internalFieldStore.children[key]);
+			for (const key in internalFieldStore.children) value[key] = /* @__PURE__ */ getFieldInput(internalFieldStore.children[key]);
 			return value;
 		}
 		return internalFieldStore.input.value;
@@ -233,13 +261,15 @@ function getFieldInput(internalFieldStore) {
 	return internalFieldStore.input.value;
 }
 /**
-* Returns the current input of the element.
+* Returns the current input of the element. Handles special cases for select
+* multiple, checkbox groups, radio groups, and file inputs.
 *
 * @param element The field element.
-* @param interalFieldStore The interal field store.
+* @param internalFieldStore The internal field store.
 *
 * @returns The element input.
 */
+/* @__NO_SIDE_EFFECTS__ */
 function getElementInput(element, internalFieldStore) {
 	if (element.options && element.multiple) return [...element.options].filter((option) => option.selected && !option.disabled).map((option) => option.value);
 	if (element.type === "checkbox") {
@@ -248,7 +278,7 @@ function getElementInput(element, internalFieldStore) {
 		return element.checked;
 	}
 	if (element.type === "radio") {
-		const prevValue = untrack(() => getFieldInput(internalFieldStore));
+		const prevValue = untrack(() => /* @__PURE__ */ getFieldInput(internalFieldStore));
 		if (element.checked) return [...prevValue, element.value];
 		return prevValue.filter((value) => value !== element.value);
 	}
@@ -258,23 +288,51 @@ 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 (getFieldBool(internalFieldStore.children[index], type)) return true;
+		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 (getFieldBool(internalFieldStore.children[key], type)) return true;
+		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.
+*
+* @param internalFormStore The form store to traverse.
+* @param path The path to the field store.
+*
+* @returns The field store.
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getFieldStore(internalFormStore, path) {
 	let internalFieldStore = internalFormStore;
 	for (const key of path) internalFieldStore = internalFieldStore.children[key];
 	return internalFieldStore;
 }
+/**
+* Sets the specified boolean property for the field store and all nested
+* children. Recursively updates arrays and objects.
+*
+* @param internalFieldStore The field store to update.
+* @param type The boolean property type to set.
+* @param bool The boolean value to set.
+*/
 function setFieldBool(internalFieldStore, type, bool) {
 	batch(() => {
 		if (internalFieldStore.kind === "array") {
@@ -284,6 +342,13 @@ function setFieldBool(internalFieldStore, type, bool) {
 		else internalFieldStore[type].value = bool;
 	});
 }
+/**
+* Sets the input for a nested field store and all its children, updating
+* touched and dirty states accordingly. Handles dynamic array resizing.
+*
+* @param internalFieldStore The field store to update.
+* @param input The new input value.
+*/
 function setNestedInput(internalFieldStore, input) {
 	internalFieldStore.isTouched.value = true;
 	if (internalFieldStore.kind === "array") {
@@ -302,7 +367,7 @@ function setNestedInput(internalFieldStore, input) {
 			}
 			internalFieldStore.items.value = [...items, ...arrayInput.slice(items.length).map(createId)];
 		}
-		for (let index = 0; index < items.length; index++) setNestedInput(internalFieldStore.children[index], arrayInput[index]);
+		for (let index = 0; index < arrayInput.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 !== items.length;
 	} else if (internalFieldStore.kind === "object") {
@@ -315,6 +380,14 @@ function setNestedInput(internalFieldStore, input) {
 		internalFieldStore.isDirty.value = startInput !== input && (startInput !== void 0 || input !== "" && !Number.isNaN(input));
 	}
 }
+/**
+* Sets the input for a field at the specified path in the form store,
+* traversing the path and updating all parent fields along the way.
+*
+* @param internalFormStore The form store containing the field.
+* @param path The path to the field.
+* @param input The new input value.
+*/
 function setFieldInput(internalFormStore, path, input) {
 	batch(() => {
 		untrack(() => {
@@ -327,6 +400,14 @@ function setFieldInput(internalFormStore, path, input) {
 		});
 	});
 }
+/**
+* Sets the initial input for a field store and all its children recursively.
+* For arrays, initializes missing children if needed. Updates `initialInput`
+* and `initialItems` properties.
+*
+* @param internalFieldStore The field store to update.
+* @param initialInput The initial input value.
+*/
 function setInitialFieldInput(internalFieldStore, initialInput) {
 	batch(() => {
 		if (internalFieldStore.kind === "array") {
@@ -349,14 +430,32 @@ function setInitialFieldInput(internalFieldStore, initialInput) {
 		} else internalFieldStore.initialInput.value = initialInput;
 	});
 }
+/**
+* Walks through the field store and all nested children, calling the callback
+* for each field store in depth-first order.
+*
+* @param internalFieldStore The field store to walk.
+* @param callback The callback to invoke for each field store.
+*/
 function walkFieldStore(internalFieldStore, callback) {
 	callback(internalFieldStore);
 	if (internalFieldStore.kind === "array") for (let index = 0; index < untrack(() => internalFieldStore.items.value).length; index++) walkFieldStore(internalFieldStore.children[index], callback);
 	else if (internalFieldStore.kind === "object") for (const key in internalFieldStore.children) walkFieldStore(internalFieldStore.children[key], callback);
 }
+/**
+* Creates a new internal form store from the provided configuration.
+* Initializes the field store hierarchy, sets validation modes, and
+* creates form state signals.
+*
+* @param config The form configuration.
+* @param parse The schema parse function.
+*
+* @returns The internal form store.
+*/
 function createFormStore(config, parse) {
 	const store = {};
 	initializeFieldStore(store, config.schema, config.initialInput, []);
+	store.validators = 0;
 	store.validate = config.validate ?? "submit";
 	store.revalidate = config.revalidate ?? "input";
 	store.parse = parse;
@@ -365,10 +464,20 @@ function createFormStore(config, parse) {
 	store.isValidating = createSignal(false);
 	return store;
 }
+/**
+* Validates the form input using the configured Valibot schema. Parses the
+* current form input, processes validation issues, assigns errors to fields,
+* and optionally focuses the first field with an error.
+*
+* @param internalFormStore The form store to validate.
+* @param config The validation configuration.
+*
+* @returns The Valibot validation result.
+*/
 async function validateFormInput(internalFormStore, config) {
 	internalFormStore.validators++;
 	internalFormStore.isValidating.value = true;
-	const result = await internalFormStore.parse(untrack(() => getFieldInput(internalFormStore)));
+	const result = await internalFormStore.parse(untrack(() => /* @__PURE__ */ getFieldInput(internalFormStore)));
 	let rootErrors;
 	let nestedErrors;
 	if (result.issues) {
@@ -407,16 +516,46 @@ async function validateFormInput(internalFormStore, config) {
 	});
 	return result;
 }
+/**
+* Validates the form input if required based on the validation mode and form
+* state. Determines whether to use initial validation mode, revalidation mode,
+* or skip validation entirely.
+*
+* @param internalFormStore The form store to validate.
+* @param internalFieldStore The field store that triggered validation.
+* @param validationMode The validation mode that triggered this check.
+*/
 function validateIfRequired(internalFormStore, internalFieldStore, validationMode) {
-	if (validationMode === (internalFormStore.validate === "initial" || (internalFormStore.validate === "submit" ? untrack(() => internalFormStore.isSubmitted.value) : untrack(() => getFieldBool(internalFieldStore, "errors"))) ? internalFormStore.revalidate : internalFormStore.validate)) validateFormInput(internalFormStore);
+	if (validationMode === (internalFormStore.validate === "initial" || (internalFormStore.validate === "submit" ? untrack(() => internalFormStore.isSubmitted.value) : untrack(() => /* @__PURE__ */ getFieldBool(internalFieldStore, "errors"))) ? internalFormStore.revalidate : internalFormStore.validate)) validateFormInput(internalFormStore);
 }
+/**
+* Internal symbol constant.
+*/
 const INTERNAL = "~internal";
 
 //#endregion
 //#region ../../packages/methods/dist/index.preact.js
-function focus(config) {
-	getFieldStore(config.form[INTERNAL], config.path).elements[0]?.focus();
+/**
+* Focuses the first input element of a field. This is useful for
+* programmatically setting focus to a specific field, such as after
+* validation errors or user interactions.
+*
+* @param form The form store containing the field.
+* @param config The focus field configuration.
+*/
+function focus(form, config) {
+	getFieldStore(form[INTERNAL], config.path).elements[0]?.focus();
 }
+/**
+* Retrieves all error messages from all fields in the form by walking through
+* the entire field store tree. This is useful for displaying a summary of all
+* validation errors across the form.
+*
+* @param form The form store to retrieve errors from.
+*
+* @returns A non-empty array of error messages, or null if no errors exist.
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getAllErrors(form) {
 	let allErrors = null;
 	walkFieldStore(form[INTERNAL], (internalFieldStore) => {
@@ -426,12 +565,15 @@ function getAllErrors(form) {
 	});
 	return allErrors;
 }
+/* @__NO_SIDE_EFFECTS__ */
 function getErrors(form, config) {
 	return (config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL]).errors.value;
 }
+/* @__NO_SIDE_EFFECTS__ */
 function getInput(form, config) {
 	return getFieldInput(config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL]);
 }
+/* @__NO_SIDE_EFFECTS__ */
 function handleSubmit(form, handler) {
 	return async (event) => {
 		event.preventDefault();
@@ -448,6 +590,13 @@ function handleSubmit(form, handler) {
 		}
 	};
 }
+/**
+* Inserts a new item into a field array at the specified index. All items at
+* or after the insertion point are shifted up by one index.
+*
+* @param form The form store containing the field array.
+* @param config The insert configuration specifying the path, index, and initial value.
+*/
 function insert(form, config) {
 	const internalFormStore = form[INTERNAL];
 	let internalFieldStore = internalFormStore;
@@ -475,6 +624,13 @@ function insert(form, config) {
 		validateIfRequired(internalFormStore, internalArrayStore, "input");
 	});
 }
+/**
+* Moves an item from one index to another within a field array. All items
+* between the source and destination indices are shifted accordingly.
+*
+* @param form The form store containing the field array.
+* @param config The move configuration specifying the path and source/destination indices.
+*/
 function move(form, config) {
 	const internalFormStore = form[INTERNAL];
 	const internalArrayStore = getFieldStore(internalFormStore, config.path);
@@ -494,6 +650,13 @@ function move(form, config) {
 		validateIfRequired(internalFormStore, internalArrayStore, "input");
 	});
 }
+/**
+* Removes an item from a field array at the specified index. All items after
+* the removed item are shifted down by one index.
+*
+* @param form The form store containing the field array.
+* @param config The remove configuration specifying the path and index.
+*/
 function remove(form, config) {
 	const internalFormStore = form[INTERNAL];
 	const internalArrayStore = getFieldStore(internalFormStore, config.path);
@@ -508,6 +671,12 @@ function remove(form, config) {
 		validateIfRequired(internalFormStore, internalArrayStore, "input");
 	});
 }
+/**
+* Replaces an item in a field array at the specified index with new initial input.
+*
+* @param form The form store containing the field array.
+* @param config The replace configuration specifying the path, index, and initial input.
+*/
 function replace(form, config) {
 	const internalFormStore = form[INTERNAL];
 	const internalArrayStore = getFieldStore(internalFormStore, config.path);
@@ -563,9 +732,21 @@ function setInput(form, config) {
 		validateIfRequired(internalFormStore, config.path ? getFieldStore(internalFormStore, config.path) : internalFormStore, "input");
 	});
 }
+/**
+* Programmatically requests form submission by calling the native
+* `requestSubmit()` method on the underlying form element.
+*
+* @param form The form store to submit.
+*/
 function submit(form) {
 	form[INTERNAL].element?.requestSubmit();
 }
+/**
+* Swaps two items in a field array by exchanging their positions.
+*
+* @param form The form store containing the field array.
+* @param config The swap configuration specifying the path and indices to swap.
+*/
 function swap(form, config) {
 	const internalFormStore = form[INTERNAL];
 	const internalArrayStore = getFieldStore(internalFormStore, config.path);
@@ -582,25 +763,53 @@ function swap(form, config) {
 		validateIfRequired(internalFormStore, internalArrayStore, "input");
 	});
 }
+/**
+* Validates the entire form input against its schema. Returns a safe parse result
+* indicating success or failure with detailed issues. Optionally focuses the first
+* field with validation errors.
+*
+* @param form The form store to validate.
+* @param config The validate form configuration specifying focus behavior.
+*
+* @returns A promise resolving to the validation result.
+*/
 function validate(form, config) {
 	return validateFormInput(form[INTERNAL], config);
 }
 
 //#endregion
 //#region src/hooks/usePathSignal/usePathSignal.ts
+/**
+* Compares two paths for equality.
+*
+* @param a The first path.
+* @param b The second path.
+*
+* @returns Whether the paths are equal.
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function isEqual(a, b) {
 	if (a.length !== b.length) return false;
 	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
 	return true;
 }
+/**
+* Creates a readonly signal for a path that updates when the path changes.
+*
+* @param path The path value.
+*
+* @returns A readonly signal containing the path.
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function usePathSignal(path) {
 	const signal = useSignal(path);
-	if (!isEqual(signal.value, path)) signal.value = path;
+	if (!/* @__PURE__ */ isEqual(signal.value, path)) signal.value = path;
 	return signal;
 }
 
 //#endregion
 //#region src/hooks/useField/useField.ts
+/* @__NO_SIDE_EFFECTS__ */
 function useField(form, config) {
 	const pathSignal = usePathSignal(config.path);
 	const internalFormStore = form[INTERNAL];
@@ -645,6 +854,7 @@ function useField(form, config) {
 
 //#endregion
 //#region src/hooks/useFieldArray/useFieldArray.ts
+/* @__NO_SIDE_EFFECTS__ */
 function useFieldArray(form, config) {
 	const pathSignal = usePathSignal(config.path);
 	const internalFieldStore = useComputed(() => getFieldStore(form[INTERNAL], pathSignal.value));
@@ -660,6 +870,7 @@ function useFieldArray(form, config) {
 
 //#endregion
 //#region src/hooks/useForm/useForm.ts
+/* @__NO_SIDE_EFFECTS__ */
 function useForm(config) {
 	const form = useMemo(() => {
 		const internalFormStore = createFormStore(config, (input) => v.safeParseAsync(config.schema, input));
@@ -683,8 +894,15 @@ function useForm(config) {
 //#endregion
 //#region src/components/Field/Field.tsx
 /**
-* Headless form field that provides reactive properties and state.
+* Headless form field component that provides reactive properties and state.
+* The field component takes a form store, path to field, and a render function
+* that receives a field store to display field state and handle user interactions.
+*
+* @param props The field component props.
+*
+* @returns The UI of the field to be rendered.
 */
+/* @__NO_SIDE_EFFECTS__ */
 function Field({ of, path, children }) {
 	const field = useField(of, { path });
 	return children(field);
@@ -693,8 +911,16 @@ function Field({ of, path, children }) {
 //#endregion
 //#region src/components/FieldArray/FieldArray.tsx
 /**
-* Headless field array that provides reactive properties and state.
+* Headless field array component that provides reactive properties and state.
+* The field array component takes a form store, path to array field, and a render
+* function that receives a field array store to manage array items and handle
+* array operations.
+*
+* @param props The field array component props.
+*
+* @returns The UI of the field array to be rendered.
 */
+/* @__NO_SIDE_EFFECTS__ */
 function FieldArray({ of, path, children }) {
 	const field = useFieldArray(of, { path });
 	return children(field);
@@ -702,6 +928,7 @@ function FieldArray({ of, path, children }) {
 
 //#endregion
 //#region src/components/Form/Form.tsx
+/* @__NO_SIDE_EFFECTS__ */
 function Form({ of, onSubmit,...other }) {
 	return /* @__PURE__ */ jsx("form", {
 		...other,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formisch/preact",
   "description": "The modular and type-safe form library for Preact",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "MIT",
   "author": "Fabian Hiller",
   "homepage": "https://formisch.dev",
@@ -43,8 +43,8 @@
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.37.0",
     "vite": "^6.0.4",
-    "@formisch/core": "0.4.0",
-    "@formisch/methods": "0.3.0"
+    "@formisch/methods": "0.4.0",
+    "@formisch/core": "0.4.1"
   },
   "peerDependencies": {
     "@preact/signals": "^2.0.0",