@formisch/svelte 0.2.0 → 0.4.0

package/dist/methods/index.svelte.d.ts

@@ -2,126 +2,440 @@ import { BaseFormStore, DeepPartial, PartialValues, PathValue, RequiredPath, Sch
 import * as v from "valibot";
 
 //#region src/focus/focus.d.ts
+
+/**
+* Focus field config interface.
+*/
 interface FocusFieldConfig<TSchema extends Schema, TFieldPath extends RequiredPath> {
-  readonly form: BaseFormStore<TSchema>;
+  /**
+  * The path to the field to focus.
+  */
   readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
 }
-declare function focus<TSchema extends Schema, TFieldPath extends RequiredPath>(config: FocusFieldConfig<TSchema, TFieldPath>): void;
+/**
+* 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.
+*/
+declare function focus<TSchema extends Schema, TFieldPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: FocusFieldConfig<TSchema, TFieldPath>): void;
 //#endregion
 //#region src/getAllErrors/getAllErrors.d.ts
+/**
+* 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.
+*/
 declare function getAllErrors(form: BaseFormStore): [string, ...string[]] | null;
 //#endregion
 //#region src/getErrors/getErrors.d.ts
+/**
+* Get form errors config interface.
+*/
 interface GetFormErrorsConfig {
+  /**
+  * The path to a field. Leave undefined to get form-level errors.
+  */
   readonly path?: undefined;
 }
+/**
+* Get field errors config interface.
+*/
 interface GetFieldErrorsConfig<TSchema extends Schema, TFieldPath extends RequiredPath> {
+  /**
+  * The path to the field to retrieve errors from.
+  */
   readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
 }
+/**
+* Retrieves error messages from the form. When called without a config,
+* returns form-level errors. When called with a path, returns errors for
+* that specific field.
+*
+* @param form The form store to retrieve errors from.
+*
+* @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;
+/**
+* Retrieves error messages from the form. When called without a config,
+* returns form-level errors. When called with a path, returns errors for
+* that specific field.
+*
+* @param form The form store to retrieve errors from.
+* @param config The get errors configuration.
+*
+* @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;
 //#endregion
 //#region src/getInput/getInput.d.ts
+/**
+* Get form input config interface.
+*/
 interface GetFormInputConfig {
+  /**
+  * The path to a field. Leave undefined to get the entire form input.
+  */
   readonly path?: undefined;
 }
+/**
+* Get field input config interface.
+*/
 interface GetFieldInputConfig<TSchema extends Schema, TFieldPath extends RequiredPath> {
+  /**
+  * The path to the field to retrieve input from.
+  */
   readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
 }
+/**
+* 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.
+*
+* @param form The form store to retrieve input from.
+*
+* @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>>;
+/**
+* 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.
+*
+* @param form The form store to retrieve input from.
+* @param config The get input configuration.
+*
+* @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>>;
 //#endregion
 //#region src/handleSubmit/handleSubmit.d.ts
+/**
+* Creates a submit event handler for the form that prevents default browser
+* submission, validates the form input, and calls the provided handler if
+* validation succeeds. This is designed to be used with the form's onsubmit event.
+*
+* @param form The form store to handle submission for.
+* @param handler The submit handler function called with validated output if validation succeeds.
+*
+* @returns A submit event handler function to attach to the form element.
+*/
 declare function handleSubmit<TSchema extends Schema>(form: BaseFormStore<TSchema>, handler: SubmitHandler<TSchema>): (event: SubmitEvent) => void;
 //#endregion
 //#region src/insert/insert.d.ts
+/**
+* Insert array field config interface.
+*/
 interface InsertConfig<TSchema extends Schema, TFieldArrayPath extends RequiredPath> {
+  /**
+  * The path to the field array to insert into.
+  */
   readonly path: ValidArrayPath<v.InferInput<TSchema>, TFieldArrayPath>;
+  /**
+  * The index to insert the new item at. If undefined, appends to the end.
+  */
   readonly at?: number | undefined;
+  /**
+  * The partial initial input value for the new item.
+  */
   readonly initialInput?: DeepPartial<PathValue<v.InferInput<TSchema>, [...TFieldArrayPath, number]>> | undefined;
 }
+/**
+* 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.
+*/
 declare function insert<TSchema extends Schema, 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> {
+  /**
+  * The path to the field array to move an item within.
+  */
   readonly path: ValidArrayPath<v.InferInput<TSchema>, TFieldArrayPath>;
+  /**
+  * The index of the item to move from.
+  */
   readonly from: number;
+  /**
+  * The index to move the item to.
+  */
   readonly to: number;
 }
+/**
+* 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.
+*/
 declare function move<TSchema extends Schema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: MoveConfig<TSchema, TFieldArrayPath>): void;
 //#endregion
 //#region src/remove/remove.d.ts
+/**
+* Remove array field config interface.
+*/
 interface RemoveConfig<TSchema extends Schema, TFieldArrayPath extends RequiredPath> {
+  /**
+  * The path to the field array to remove an item from.
+  */
   readonly path: ValidArrayPath<v.InferInput<TSchema>, TFieldArrayPath>;
+  /**
+  * The index of the item to remove.
+  */
   readonly at: number;
 }
+/**
+* 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.
+*/
 declare function remove<TSchema extends Schema, 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> {
+  /**
+  * The path to the field array to replace an item within.
+  */
   readonly path: ValidArrayPath<v.InferInput<TSchema>, TFieldArrayPath>;
+  /**
+  * The index of the item to replace.
+  */
   readonly at: number;
+  /**
+  * The partial initial input value for the replacement item.
+  */
   readonly initialInput?: DeepPartial<PathValue<v.InferInput<TSchema>, [...TFieldArrayPath, number]>> | undefined;
 }
+/**
+* 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.
+*/
 declare function replace<TSchema extends Schema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: ReplaceConfig<TSchema, TFieldArrayPath>): void;
 //#endregion
 //#region src/reset/reset.d.ts
+/**
+* Reset base config interface.
+*/
 interface ResetBaseConfig {
+  /**
+  * Whether to keep the current input values during reset. Defaults to false.
+  */
   readonly keepInput?: boolean | undefined;
+  /**
+  * Whether to keep the touched state during reset. Defaults to false.
+  */
   readonly keepTouched?: boolean | undefined;
+  /**
+  * Whether to keep the error messages during reset. Defaults to false.
+  */
   readonly keepErrors?: boolean | undefined;
 }
+/**
+* Reset form config interface.
+*/
 interface ResetFormConfig<TSchema extends Schema> extends ResetBaseConfig {
+  /**
+  * The path to a field. Leave undefined to reset the entire form.
+  */
   readonly path?: undefined;
+  /**
+  * The new initial input to reset to. If provided, replaces the form's
+  * initial input.
+  */
   readonly initialInput?: DeepPartial<v.InferInput<TSchema>> | undefined;
-  readonly keepSubmitCount?: boolean | undefined;
+  /**
+  * Whether to keep the submitted state during reset. Defaults to false.
+  */
   readonly keepSubmitted?: boolean | undefined;
 }
+/**
+* Reset field config interface.
+*/
 interface ResetFieldConfig<TSchema extends Schema, TFieldPath extends RequiredPath> extends ResetBaseConfig {
+  /**
+  * The path to the field to reset.
+  */
   readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+  /**
+  * The new initial input to reset the field to. If provided, replaces the
+  * field's initial input.
+  */
   readonly initialInput?: DeepPartial<PathValue<v.InferInput<TSchema>, TFieldPath>>;
 }
+/**
+* Resets a specific field or the entire form to its initial state. Provides
+* fine-grained control over which state to preserve during reset through the
+* configuration options.
+*
+* @param form The form store to reset.
+*/
 declare function reset(form: BaseFormStore): void;
+/**
+* Resets a specific field or the entire form to its initial state. Provides
+* fine-grained control over which state to preserve during reset through the
+* configuration options.
+*
+* @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;
 //#endregion
 //#region src/setErrors/setErrors.d.ts
+/**
+* Set form errors config interface.
+*/
 interface SetFormErrorsConfig {
+  /**
+  * The path to a field. Leave undefined to set form-level errors.
+  */
   readonly path?: undefined;
+  /**
+  * The error messages to set, or null to clear errors.
+  */
   readonly errors: [string, ...string[]] | null;
 }
+/**
+* Set field errors config interface.
+*/
 interface SetFieldErrorsConfig<TSchema extends Schema, TFieldPath extends RequiredPath> {
+  /**
+  * The path to the field to set errors on.
+  */
   readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+  /**
+  * The error messages to set, or null to clear errors.
+  */
   readonly errors: [string, ...string[]] | null;
 }
+/**
+* Sets or clears error messages on the form or a specific field. This is
+* useful for setting custom validation errors that don't come from schema
+* validation.
+*
+* @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;
 //#endregion
 //#region src/setInput/setInput.d.ts
+/**
+* Set form input config interface.
+*/
 interface SetFormInputConfig<TSchema extends Schema> {
+  /**
+  * The path to a field. Leave undefined to set the entire form input.
+  */
   readonly path?: undefined;
+  /**
+  * The input value to set for the form.
+  */
   readonly input: v.InferInput<TSchema>;
 }
+/**
+* Set field input config interface.
+*/
 interface SetFieldInputConfig<TSchema extends Schema, TFieldPath extends RequiredPath> {
+  /**
+  * The path to the field to set input on.
+  */
   readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+  /**
+  * The input value to set for the field.
+  */
   readonly input: PathValue<v.InferInput<TSchema>, TFieldPath>;
 }
+/**
+* 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
+* validation mode.
+*
+* @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;
+/**
+* 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
+* validation mode.
+*
+* @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;
 //#endregion
 //#region src/submit/submit.d.ts
+/**
+* Programmatically requests form submission by calling the native
+* `requestSubmit()` method on the underlying form element.
+*
+* @param form The form store to submit.
+*/
 declare function submit(form: BaseFormStore): void;
 //#endregion
 //#region src/swap/swap.d.ts
+/**
+* Swap array field config interface.
+*/
 interface SwapConfig<TSchema extends Schema, TFieldArrayPath extends RequiredPath> {
+  /**
+  * The path to the field array to swap items within.
+  */
   readonly path: ValidArrayPath<v.InferInput<TSchema>, TFieldArrayPath>;
+  /**
+  * The index of the first item to swap.
+  */
   readonly at: number;
+  /**
+  * The index of the second item to swap with the first.
+  */
   readonly and: number;
 }
+/**
+* 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.
+*/
 declare function swap<TSchema extends Schema, TFieldArrayPath extends RequiredPath>(form: BaseFormStore<TSchema>, config: SwapConfig<TSchema, TFieldArrayPath>): void;
 //#endregion
 //#region src/validate/validate.d.ts
+/**
+* Validate form config interface.
+*/
 interface ValidateFormConfig {
+  /**
+  * Whether to focus the first field with errors after validation. Defaults to false.
+  */
   readonly shouldFocus?: boolean | undefined;
 }
+/**
+* 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.
+*/
 declare function validate<TSchema extends Schema>(form: BaseFormStore<TSchema>, config?: ValidateFormConfig): Promise<v.SafeParseResult<TSchema>>;
 //#endregion
 export { FocusFieldConfig, GetFieldErrorsConfig, GetFieldInputConfig, GetFormErrorsConfig, GetFormInputConfig, InsertConfig, MoveConfig, RemoveConfig, ReplaceConfig, ResetFieldConfig, ResetFormConfig, SetFieldErrorsConfig, SetFieldInputConfig, SetFormErrorsConfig, SetFormInputConfig, SwapConfig, ValidateFormConfig, focus, getAllErrors, getErrors, getInput, handleSubmit, insert, move, remove, replace, reset, setErrors, setInput, submit, swap, validate };

package/dist/methods/index.svelte.js

@@ -1,12 +1,30 @@
 import { INTERNAL, batch, copyItemState, createId, getFieldInput, getFieldStore, initializeFieldStore, resetItemState, setFieldInput, setInitialFieldInput, swapItemState, untrack, validateFormInput, validateIfRequired, walkFieldStore } from "../core/index.svelte";
 
 //#region src/focus/focus.ts
-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();
 }
 
 //#endregion
 //#region src/getAllErrors/getAllErrors.ts
+/**
+* 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) => {
@@ -19,18 +37,21 @@ function getAllErrors(form) {
 
 //#endregion
 //#region src/getErrors/getErrors.ts
+/* @__NO_SIDE_EFFECTS__ */
 function getErrors(form, config) {
 	return (config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL]).errors.value;
 }
 
 //#endregion
 //#region src/getInput/getInput.ts
+/* @__NO_SIDE_EFFECTS__ */
 function getInput(form, config) {
 	return getFieldInput(config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL]);
 }
 
 //#endregion
 //#region src/handleSubmit/handleSubmit.ts
+/* @__NO_SIDE_EFFECTS__ */
 function handleSubmit(form, handler) {
 	return async (event) => {
 		event.preventDefault();
@@ -50,6 +71,13 @@ function handleSubmit(form, handler) {
 
 //#endregion
 //#region src/insert/insert.ts
+/**
+* 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;
@@ -80,6 +108,13 @@ function insert(form, config) {
 
 //#endregion
 //#region src/move/move.ts
+/**
+* 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);
@@ -102,6 +137,13 @@ function move(form, config) {
 
 //#endregion
 //#region src/remove/remove.ts
+/**
+* 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);
@@ -119,6 +161,12 @@ function remove(form, config) {
 
 //#endregion
 //#region src/replace/replace.ts
+/**
+* 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);
@@ -186,12 +234,24 @@ function setInput(form, config) {
 
 //#endregion
 //#region src/submit/submit.ts
+/**
+* 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();
 }
 
 //#endregion
 //#region src/swap/swap.ts
+/**
+* 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);
@@ -211,6 +271,16 @@ function swap(form, config) {
 
 //#endregion
 //#region src/validate/validate.ts
+/**
+* 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);
 }

package/dist/runes/createForm/createForm.svelte.d.ts

@@ -1,3 +1,11 @@
 import { type FormConfig, type Schema } from '../../core/index.svelte';
 import type { FormStore } from '../../types/index.ts';
+/**
+ * Creates a reactive form store from a form configuration. The form store
+ * manages form state and provides reactive properties.
+ *
+ * @param config The form configuration.
+ *
+ * @returns The form store with reactive properties.
+ */
 export declare function createForm<TSchema extends Schema>(config: FormConfig<TSchema>): FormStore<TSchema>;