@formisch/svelte 0.3.0 → 0.4.0

package/dist/core/index.svelte.js

@@ -2,10 +2,27 @@ import * as v from "valibot";
 import { untrack } from "svelte";
 
 //#region src/framework/index.svelte.ts
+/**
+* The current framework being used.
+*/
 const framework = "svelte";
+/**
+* Creates a unique identifier string.
+*
+* @returns The unique identifier.
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function createId() {
 	return Math.random().toString(36).slice(2);
 }
+/**
+* Creates a reactive signal with an initial value.
+*
+* @param initialValue The initial value.
+*
+* @returns The created signal.
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function createSignal(initialValue) {
 	let signal = $state.raw(initialValue);
 	return {
@@ -17,6 +34,14 @@ function createSignal(initialValue) {
 		}
 	};
 }
+/**
+* Batches multiple signal updates into a single update cycle. This is a
+* no-op in Svelte as batching is handled automatically.
+*
+* @param fn The function to execute.
+*
+* @returns The return value of the function.
+*/
 function batch(fn) {
 	return fn();
 }
@@ -24,8 +49,15 @@ function batch(fn) {
 //#endregion
 //#region src/field/initializeFieldStore/initializeFieldStore.ts
 /**
-* 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`);
@@ -99,13 +131,13 @@ function initializeFieldStore(internalFieldStore, schema, initialInput, path, nu
 //#endregion
 //#region src/array/copyItemState/copyItemState.ts
 /**
-* 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(() => {
@@ -139,13 +171,14 @@ function copyItemState(fromInternalFieldStore, toInternalFieldStore) {
 //#endregion
 //#region src/array/resetItemState/resetItemState.ts
 /**
-* 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(() => {
@@ -177,12 +210,13 @@ function resetItemState(internalFieldStore, initialInput) {
 //#endregion
 //#region src/array/swapItemState/swapItemState.ts
 /**
-* 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(() => {
@@ -240,11 +274,21 @@ function swapItemState(firstInternalFieldStore, secondInternalFieldStore) {
 
 //#endregion
 //#region src/field/getFieldInput/getFieldInput.ts
+/**
+* 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;
@@ -252,7 +296,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;
@@ -263,13 +307,15 @@ function getFieldInput(internalFieldStore) {
 //#endregion
 //#region src/field/getElementInput/getElementInput.ts
 /**
-* 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") {
@@ -291,14 +337,24 @@ function getElementInput(element, internalFieldStore) {
 
 //#endregion
 //#region src/field/getFieldBool/getFieldBool.ts
+/**
+* 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;
@@ -306,6 +362,16 @@ function getFieldBool(internalFieldStore, type) {
 
 //#endregion
 //#region src/field/getFieldStore/getFieldStore.ts
+/**
+* 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];
@@ -314,6 +380,14 @@ function getFieldStore(internalFormStore, path) {
 
 //#endregion
 //#region src/field/setFieldBool/setFieldBool.ts
+/**
+* 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") {
@@ -326,6 +400,13 @@ function setFieldBool(internalFieldStore, type, bool) {
 
 //#endregion
 //#region src/field/setFieldInput/setFieldInput.ts
+/**
+* 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") {
@@ -344,7 +425,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") {
@@ -357,6 +438,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(() => {
@@ -372,6 +461,14 @@ function setFieldInput(internalFormStore, path, input) {
 
 //#endregion
 //#region src/field/setInitialFieldInput/setInitialFieldInput.ts
+/**
+* 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") {
@@ -397,6 +494,13 @@ function setInitialFieldInput(internalFieldStore, initialInput) {
 
 //#endregion
 //#region src/field/walkFieldStore/walkFieldStore.ts
+/**
+* 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);
@@ -405,9 +509,20 @@ function walkFieldStore(internalFieldStore, callback) {
 
 //#endregion
 //#region src/form/createFormStore/createFormStore.ts
+/**
+* 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;
@@ -419,6 +534,16 @@ function createFormStore(config, parse) {
 
 //#endregion
 //#region src/form/validateFormInput/validateFormInput.ts
+/**
+* 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;
@@ -464,12 +589,24 @@ async function validateFormInput(internalFormStore, config) {
 
 //#endregion
 //#region src/form/validateIfRequired/validateIfRequired.ts
+/**
+* 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);
 }
 
 //#endregion
 //#region src/values.ts
+/**
+* Internal symbol constant.
+*/
 const INTERNAL = "~internal";
 
 //#endregion