@formisch/svelte 0.2.0 → 0.4.0

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

@@ -2,60 +2,198 @@ import * as v from "valibot";
 import { untrack } from "svelte";
 
 //#region src/types/schema.d.ts
+/**
+* Schema type.
+*/
 type Schema = v.GenericSchema | v.GenericSchemaAsync;
 //#endregion
 //#region src/types/signal.d.ts
+/**
+* Signal interface.
+*/
 interface Signal<T> {
+  /**
+  * The value of the signal.
+  */
   value: T;
 }
+/**
+* Batch interface.
+*/
 interface Batch {
   <T>(fn: () => T): T;
 }
+/**
+* Untrack interface.
+*/
 interface Untrack {
   <T>(fn: () => T): T;
 }
 //#endregion
 //#region src/types/field.d.ts
 /**
-* Value type of the field element.
+* Field element type.
 */
 type FieldElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+/**
+* Internal base store interface.
+*/
 interface InternalBaseStore {
+  /**
+  * The kind of field store.
+  */
   kind: "array" | "object" | "value";
+  /**
+  * The name of the field.
+  */
   name: string;
+  /**
+  * The schema of the field.
+  */
   schema: Schema;
+  /**
+  * The initial elements of the field.
+  */
   initialElements: FieldElement[];
+  /**
+  * The elements of the field.
+  */
   elements: FieldElement[];
+  /**
+  * The errors of the field.
+  */
   errors: Signal<[string, ...string[]] | null>;
+  /**
+  * The touched state of the field.
+  */
   isTouched: Signal<boolean>;
+  /**
+  * The dirty state of the field.
+  */
   isDirty: Signal<boolean>;
 }
+/**
+* Internal array store interface.
+*/
 interface InternalArrayStore extends InternalBaseStore {
+  /**
+  * The kind of field store.
+  */
   kind: "array";
+  /**
+  * The children of the array field.
+  */
   children: InternalFieldStore[];
+  /**
+  * The initial input of the array field.
+  *
+  * Hint: The initial input is used for resetting and may only be changed
+  * during this process. It does not move when a field is moved.
+  */
   initialInput: Signal<true | null | undefined>;
+  /**
+  * The start input of the array field.
+  *
+  * Hint: The start input is used to determine whether the field is dirty
+  * and moves with it.
+  */
   startInput: Signal<true | null | undefined>;
+  /**
+  * The input of the array field.
+  *
+  * Hint: The input indicates whether it is `null`, `undefined`, or found in
+  * the children.
+  */
   input: Signal<true | null | undefined>;
+  /**
+  * The initial items of the array field.
+  *
+  * Hint: The initial items are used for resetting and may only be changed
+  * during this process. It does not move when a field is moved.
+  */
   initialItems: Signal<string[]>;
+  /**
+  * The start items of the array field.
+  *
+  * Hint: The start items are used to determine whether the field is dirty
+  * and moves with it.
+  */
   startItems: Signal<string[]>;
+  /**
+  * The items of the array field.
+  */
   items: Signal<string[]>;
 }
+/**
+* Internal object store interface.
+*/
 interface InternalObjectStore extends InternalBaseStore {
+  /**
+  * The kind of field store.
+  */
   kind: "object";
+  /**
+  * The children of the object field.
+  */
   children: Record<string, InternalFieldStore>;
+  /**
+  * The initial input of the object field.
+  *
+  * Hint: The initial input is used for resetting and may only be changed
+  * during this process. It does not move when a field is moved.
+  */
   initialInput: Signal<true | null | undefined>;
+  /**
+  * The start input of the object field.
+  *
+  * Hint: The start input is used to determine whether the field is dirty
+  * and moves with it.
+  */
   startInput: Signal<true | null | undefined>;
+  /**
+  * The input of the object field.
+  *
+  * Hint: The input indicates whether it is `null`, `undefined`, or found in
+  * the children.
+  */
   input: Signal<true | null | undefined>;
 }
+/**
+* Internal value store interface.
+*/
 interface InternalValueStore extends InternalBaseStore {
+  /**
+  * The kind of field store.
+  */
   kind: "value";
+  /**
+  * The initial input of the value field.
+  *
+  * Hint: The initial input is used for resetting and may only be changed
+  * during this process. It does not move when a field is moved.
+  */
   initialInput: Signal<unknown>;
+  /**
+  * The start input of the value field.
+  *
+  * Hint: The start input is used to determine whether the field is dirty
+  * and moves with it.
+  */
   startInput: Signal<unknown>;
+  /**
+  * The input of the value field.
+  */
   input: Signal<unknown>;
 }
+/**
+* Internal field store type.
+*/
 type InternalFieldStore = InternalArrayStore | InternalObjectStore | InternalValueStore;
 //#endregion
 //#region src/values.d.ts
+/**
+* Internal symbol constant.
+*/
 declare const INTERNAL: "~internal";
 //#endregion
 //#region src/types/utils.d.ts
@@ -82,28 +220,81 @@ type PartialValues<TValue> = TValue extends readonly unknown[] ? number extends
 //#endregion
 //#region src/types/form.d.ts
 /**
-* Value type of the validation mode.
+* Validation mode type.
 */
 type ValidationMode = "initial" | "touch" | "input" | "change" | "blur" | "submit";
+/**
+* Form config interface.
+*/
 interface FormConfig<TSchema extends Schema = Schema> {
+  /**
+  * The schema of the form.
+  */
   readonly schema: TSchema;
+  /**
+  * The initial input of the form.
+  */
   readonly initialInput?: DeepPartial<v.InferInput<TSchema>> | undefined;
+  /**
+  * The validation mode of the form.
+  */
   readonly validate?: ValidationMode | undefined;
+  /**
+  * The revalidation mode of the form.
+  */
   readonly revalidate?: Exclude<ValidationMode, "initial"> | undefined;
 }
+/**
+* Internal form store interface.
+*/
 interface InternalFormStore<TSchema extends Schema = Schema> extends InternalObjectStore {
+  /**
+  * The element of the form.
+  */
   element?: HTMLFormElement;
+  /**
+  * The number of active validators.
+  */
   validators: number;
+  /**
+  * The validation mode of the form.
+  */
   validate: ValidationMode;
+  /**
+  * The revalidation mode of the form.
+  */
   revalidate: Exclude<ValidationMode, "initial">;
+  /**
+  * The parse function of the form.
+  */
   parse: (input: unknown) => Promise<v.SafeParseResult<TSchema>>;
+  /**
+  * The submitting state of the form.
+  */
   isSubmitting: Signal<boolean>;
+  /**
+  * The submitted state of the form.
+  */
   isSubmitted: Signal<boolean>;
+  /**
+  * The validating state of the form.
+  */
   isValidating: Signal<boolean>;
 }
+/**
+* Base form store interface.
+*/
 interface BaseFormStore<TSchema extends Schema = Schema> {
-  [INTERNAL]: InternalFormStore<TSchema>;
+  /**
+  * The internal form store.
+  *
+  * @internal
+  */
+  readonly [INTERNAL]: InternalFormStore<TSchema>;
 }
+/**
+* Submit handler type.
+*/
 type SubmitHandler<TSchema extends Schema> = (output: v.InferOutput<TSchema>, event: SubmitEvent) => MaybePromise<unknown>;
 //#endregion
 //#region src/types/path.d.ts
@@ -132,7 +323,7 @@ type KeyOf<TValue> = IsAny<TValue> extends true ? never : TValue extends readonl
 */
 type MergeUnion<T> = { [K in KeyOf<T>]: T extends Record<K, infer V> ? V : never };
 /**
-* Lazily evaluate only the first valid path segment based on the given value.
+* Lazily evaluates only the first valid path segment based on the given value.
 */
 type LazyPath<TValue, TPathToCheck extends Path, TValidPath extends Path = readonly []> = TPathToCheck extends readonly [] ? TValidPath : TPathToCheck extends readonly [infer TFirstKey extends KeyOf<TValue>, ...infer TPathRest extends Path] ? LazyPath<Required<MergeUnion<TValue>[TFirstKey]>, TPathRest, readonly [...TValidPath, TFirstKey]> : IsNever<KeyOf<TValue>> extends false ? readonly [...TValidPath, KeyOf<TValue>] : TValidPath;
 /**
@@ -153,109 +344,241 @@ type IsOrHasArray<TValue> = IsAny<TValue> extends true ? false : TValue extends
 */
 type KeyOfArrayPath<TValue> = IsAny<TValue> extends true ? never : TValue extends readonly (infer TItem)[] ? number extends TValue["length"] ? IsOrHasArray<TItem> extends true ? number : never : { [TKey in keyof TValue]: TKey extends `${infer TIndex extends number}` ? IsOrHasArray<NonNullable<TValue[TKey]>> extends true ? TIndex : never : never }[number] : TValue extends Record<string, unknown> ? { [TKey in keyof TValue]: IsOrHasArray<NonNullable<TValue[TKey]>> extends true ? TKey : never }[keyof TValue] & PathKey : never;
 /**
-* Lazily evaluate only the first valid array path segment based on the given value.
+* 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, KeyOfArrayPath<TValue>] : TPathToCheck extends readonly [infer TFirstKey extends KeyOfArrayPath<TValue>, ...infer TPathRest extends Path] ? LazyArrayPath<Required<MergeUnion<TValue>[TFirstKey]>, TPathRest, readonly [...TValidPath, TFirstKey]> : IsNever<KeyOfArrayPath<TValue>> extends false ? readonly [...TValidPath, KeyOfArrayPath<TValue>] : never;
 /**
-* Returns the path if valid, otherwise the first possible valid array path based on
-* the given value.
+* Returns the path if valid, otherwise the first possible valid array path
+* based on the given value.
 */
 type ValidArrayPath<TValue, TPath extends RequiredPath> = TPath extends LazyArrayPath<Required<TValue>, TPath> ? TPath : LazyArrayPath<Required<TValue>, TPath>;
 //#endregion
 //#region src/array/copyItemState/copyItemState.d.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.
 */
 declare function copyItemState(fromInternalFieldStore: InternalFieldStore, toInternalFieldStore: InternalFieldStore): void;
 //#endregion
 //#region src/array/resetItemState/resetItemState.d.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).
 */
 declare function resetItemState(internalFieldStore: InternalFieldStore, initialInput: unknown): void;
 //#endregion
 //#region src/array/swapItemState/swapItemState.d.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.
 */
 declare function swapItemState(firstInternalFieldStore: InternalFieldStore, secondInternalFieldStore: InternalFieldStore): void;
 //#endregion
 //#region src/field/getElementInput/getElementInput.d.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.
 */
 declare function getElementInput(element: FieldElement, internalFieldStore: InternalFieldStore): unknown;
 //#endregion
 //#region src/field/getFieldBool/getFieldBool.d.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.
+*/
 declare function getFieldBool(internalFieldStore: InternalFieldStore, type: "errors" | "isTouched" | "isDirty"): boolean;
 //#endregion
 //#region src/field/getFieldInput/getFieldInput.d.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.
+*/
 declare function getFieldInput(internalFieldStore: InternalFieldStore): unknown;
 //#endregion
 //#region src/field/getFieldStore/getFieldStore.d.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.
+*/
 declare function getFieldStore(internalFormStore: InternalFormStore, path: Path): InternalFieldStore;
 //#endregion
 //#region src/field/initializeFieldStore/initializeFieldStore.d.ts
 type FieldSchema = v.ArraySchema<v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>, v.ErrorMessage<v.ArrayIssue> | undefined> | v.ExactOptionalSchema<any, any> | v.IntersectSchema<any, any> | v.LazySchema<any> | v.LooseObjectSchema<any, any> | v.LooseTupleSchema<any, any> | v.NonNullableSchema<any, any> | v.NonNullishSchema<any, any> | v.NonOptionalSchema<any, any> | v.NullableSchema<any, any> | v.NullishSchema<any, any> | v.ObjectSchema<v.ObjectEntries, v.ErrorMessage<v.ObjectIssue> | undefined> | v.ObjectWithRestSchema<v.ObjectEntries, v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>, v.ErrorMessage<v.ObjectWithRestIssue> | undefined> | v.OptionalSchema<any, any> | v.PromiseSchema<any> | v.RecordSchema<any, any, any> | v.StrictObjectSchema<any, any> | v.StrictTupleSchema<any, any> | v.TupleSchema<v.TupleItems, v.ErrorMessage<v.TupleIssue> | undefined> | v.TupleWithRestSchema<any, any, any> | v.UndefinedableSchema<any, any> | v.UnionSchema<any, any> | v.VariantSchema<any, any, any>;
 /**
-* 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.
 */
 declare function initializeFieldStore(internalFieldStore: Partial<InternalFieldStore>, schema: FieldSchema, initialInput: unknown, path: PathKey[], nullish?: boolean): void;
 //#endregion
 //#region src/field/setFieldBool/setFieldBool.d.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.
+*/
 declare function setFieldBool(internalFieldStore: InternalFieldStore, type: "isTouched" | "isDirty", bool: boolean): void;
 //#endregion
 //#region src/field/setFieldInput/setFieldInput.d.ts
+/**
+* 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.
+*/
 declare function setFieldInput(internalFormStore: InternalFormStore, path: Path, input: unknown): void;
 //#endregion
 //#region src/field/setInitialFieldInput/setInitialFieldInput.d.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.
+*/
 declare function setInitialFieldInput(internalFieldStore: InternalFieldStore, initialInput: unknown): void;
 //#endregion
 //#region src/field/walkFieldStore/walkFieldStore.d.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.
+*/
 declare function walkFieldStore(internalFieldStore: InternalFieldStore, callback: (internalFieldStore: InternalFieldStore) => void): void;
 //#endregion
 //#region src/form/createFormStore/createFormStore.d.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.
+*/
 declare function createFormStore(config: FormConfig, parse: (input: unknown) => Promise<v.SafeParseResult<Schema>>): InternalFormStore;
 //#endregion
 //#region src/form/validateFormInput/validateFormInput.d.ts
+/**
+* Validate form input config interface.
+*/
 interface ValidateFormInputConfig {
+  /**
+  * Whether to focus the first field with an error.
+  */
   readonly shouldFocus?: boolean | undefined;
 }
+/**
+* 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.
+*/
 declare function validateFormInput(internalFormStore: InternalFormStore, config?: ValidateFormInputConfig): Promise<v.SafeParseResult<Schema>>;
 //#endregion
 //#region src/form/validateIfRequired/validateIfRequired.d.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.
+*/
 declare function validateIfRequired(internalFormStore: InternalFormStore, internalFieldStore: InternalFieldStore, validationMode: ValidationMode): void;
 //#endregion
 //#region src/framework/index.d.ts
+/**
+* Framework type.
+*/
 type Framework = "preact" | "qwik" | "solid" | "svelte" | "vue";
+/**
+* The current framework being used.
+*/
 //#endregion
 //#region src/framework/index.svelte.d.ts
+/**
+* The current framework being used.
+*/
 declare const framework: Framework;
+/**
+* Creates a unique identifier string.
+*
+* @returns The unique identifier.
+*/
 declare function createId(): string;
+/**
+* Creates a reactive signal with an initial value.
+*
+* @param initialValue The initial value.
+*
+* @returns The created signal.
+*/
 declare function createSignal<T>(initialValue: T): Signal<T>;
+/**
+* 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.
+*/
 declare function batch<T>(fn: () => T): T;
 //#endregion
 export { BaseFormStore, Batch, DeepPartial, FieldElement, FieldSchema, FormConfig, INTERNAL, InternalArrayStore, InternalBaseStore, InternalFieldStore, InternalFormStore, InternalObjectStore, InternalValueStore, IsAny, IsNever, MaybePromise, PartialValues, Path, PathKey, PathValue, RequiredPath, Schema, Signal, SubmitHandler, Untrack, ValidArrayPath, ValidPath, ValidateFormInputConfig, ValidationMode, batch, copyItemState, createFormStore, createId, createSignal, framework, getElementInput, getFieldBool, getFieldInput, getFieldStore, initializeFieldStore, resetItemState, setFieldBool, setFieldInput, setInitialFieldInput, swapItemState, untrack, validateFormInput, validateIfRequired, walkFieldStore };