@formisch/vue 0.3.0 → 0.5.0

package/dist/index.js

@@ -2,19 +2,51 @@ import * as v from "valibot";
 import { computed, createElementBlock, defineComponent, guardReactiveProps, normalizeProps, onBeforeMount, onUnmounted, openBlock, renderSlot, shallowRef as createSignal, toValue, unref } from "vue";
 
 //#region ../../packages/core/dist/index.vue.js
+/**
+* The current framework being used.
+*/
 const framework = "vue";
+/**
+* Creates a unique identifier string.
+*
+* @returns The unique identifier.
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function createId() {
 	return Math.random().toString(36).slice(2);
 }
+/**
+* Batches multiple signal updates into a single update cycle. This is a
+* no-op in Vue as batching is handled automatically.
+*
+* @param fn The function to execute.
+*
+* @returns The return value of the function.
+*/
 function batch(fn) {
 	return fn();
 }
+/**
+* Executes a function without tracking reactive dependencies. This is a
+* no-op in Vue as untracking is not supported in Vue.
+*
+* @param fn The function to execute.
+*
+* @returns The return value of the function.
+*/
 function untrack(fn) {
 	return fn();
 }
 /**
-* 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`);
@@ -85,13 +117,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(() => {
@@ -122,13 +154,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(() => {
@@ -157,12 +190,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(() => {
@@ -217,11 +251,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;
@@ -229,30 +273,58 @@ 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;
 	}
 	return internalFieldStore.input.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") {
@@ -262,6 +334,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") {
@@ -280,7 +359,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") {
@@ -293,6 +372,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(() => {
@@ -305,6 +392,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") {
@@ -327,14 +422,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;
@@ -343,10 +456,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) {
@@ -385,16 +508,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.vue.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) => {
@@ -404,12 +557,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();
@@ -426,6 +582,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;
@@ -453,6 +616,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);
@@ -472,6 +642,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);
@@ -486,6 +663,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);
@@ -541,9 +724,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);
@@ -560,12 +755,23 @@ 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/composables/useField/useField.ts
+/* @__NO_SIDE_EFFECTS__ */
 function useField(form, config) {
 	const path = computed(() => toValue(config).path);
 	const internalFormStore = computed(() => toValue(form)[INTERNAL]);
@@ -624,6 +830,7 @@ function useField(form, config) {
 
 //#endregion
 //#region src/composables/useFieldArray/useFieldArray.ts
+/* @__NO_SIDE_EFFECTS__ */
 function useFieldArray(form, config) {
 	const internalFieldStore = computed(() => getFieldStore(toValue(form)[INTERNAL], toValue(config).path));
 	const isTouched = computed(() => getFieldBool(internalFieldStore.value, "isTouched"));
@@ -653,6 +860,7 @@ function useFieldArray(form, config) {
 
 //#endregion
 //#region src/composables/useForm/useForm.ts
+/* @__NO_SIDE_EFFECTS__ */
 function useForm(config) {
 	const internalFormStore = createFormStore(config, (input) => v.safeParseAsync(config.schema, input));
 	onBeforeMount(async () => {
@@ -698,7 +906,7 @@ var Field_vue_vue_type_script_setup_true_lang_default = /* @__PURE__ */ defineCo
 	},
 	setup(__props) {
 		const props = __props;
-		const field = useField(() => props.of, () => ({ path: props.path }));
+		const field = /* @__PURE__ */ useField(() => props.of, () => ({ path: props.path }));
 		return (_ctx, _cache) => {
 			return renderSlot(_ctx.$slots, "default", normalizeProps(guardReactiveProps(unref(field))));
 		};
@@ -720,7 +928,7 @@ var FieldArray_vue_vue_type_script_setup_true_lang_default = /* @__PURE__ */ def
 	},
 	setup(__props) {
 		const props = __props;
-		const field = useFieldArray(() => props.of, () => ({ path: props.path }));
+		const field = /* @__PURE__ */ useFieldArray(() => props.of, () => ({ path: props.path }));
 		return (_ctx, _cache) => {
 			return renderSlot(_ctx.$slots, "default", normalizeProps(guardReactiveProps(unref(field))));
 		};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formisch/vue",
   "description": "The modular and type-safe form library for Vue",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "license": "MIT",
   "author": "Fabian Hiller",
   "homepage": "https://formisch.dev",
@@ -43,8 +43,8 @@
     "valibot": "^1.1.0",
     "vue": "^3.5.18",
     "vue-tsc": "^3.0.4",
-    "@formisch/core": "0.4.0",
-    "@formisch/methods": "0.3.0"
+    "@formisch/methods": "0.4.0",
+    "@formisch/core": "0.4.1"
   },
   "peerDependencies": {
     "typescript": ">=5",