@octanejs/formisch 0.0.1

package/src/methods/getInput/index.ts

@@ -0,0 +1 @@
+export * from './getInput.ts';

package/src/methods/handleSubmit/handleSubmit.ts

@@ -0,0 +1,83 @@
+import {
+	type BaseFormStore,
+	type FormSchema,
+	INTERNAL,
+	type SubmitEventHandler,
+	type SubmitHandler,
+	validateFormInput,
+} from '../../core/index.ts';
+
+/**
+ * Creates a submit event handler for the form that 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.
+ */
+export function handleSubmit<TSchema extends FormSchema>(
+	form: BaseFormStore<TSchema>,
+	handler: SubmitHandler<TSchema>,
+): () => Promise<void>;
+
+/**
+ * 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.
+ */
+export function handleSubmit<TSchema extends FormSchema>(
+	form: BaseFormStore<TSchema>,
+	handler: SubmitEventHandler<TSchema>,
+): (event: SubmitEvent) => Promise<void>;
+
+// @__NO_SIDE_EFFECTS__
+export function handleSubmit(
+	form: BaseFormStore,
+	handler: SubmitHandler<FormSchema> | SubmitEventHandler<FormSchema>,
+): (event?: SubmitEvent) => Promise<void> {
+	return async (event?: SubmitEvent) => {
+		// Prevent default browser form submission
+		event?.preventDefault();
+
+		// Get internal form store
+		const internalFormStore = form[INTERNAL];
+
+		// Mark form as submitted and submitting
+		internalFormStore.isSubmitted.value = true;
+		internalFormStore.isSubmitting.value = true;
+
+		// Try to run submit actions if form is valid
+		try {
+			const result = await validateFormInput(internalFormStore, {
+				shouldFocus: true,
+			});
+
+			if (result.success) {
+				// @ts-expect-error - union of SubmitHandler and SubmitEventHandler
+				await handler(result.output, event);
+			}
+
+			// If an error occurred, set form errors
+		} catch (error: unknown) {
+			internalFormStore.errors.value = [
+				error &&
+				typeof error === 'object' &&
+				'message' in error &&
+				typeof error.message === 'string'
+					? error.message
+					: 'An unknown error has occurred.',
+			];
+
+			// Finally reset submitting state
+		} finally {
+			internalFormStore.isSubmitting.value = false;
+		}
+	};
+}

package/src/methods/handleSubmit/index.ts

@@ -0,0 +1 @@
+export * from './handleSubmit.ts';

package/src/methods/index.ts

@@ -0,0 +1,23 @@
+export * from './focus/index.ts';
+export * from './getDeepErrorEntries/index.ts';
+export * from './getDeepErrors/index.ts';
+export * from './getDirtyInput/index.ts';
+export * from './getDirtyPaths/index.ts';
+export * from './getErrors/index.ts';
+export * from './getInput/index.ts';
+export * from './handleSubmit/index.ts';
+export * from './insert/index.ts';
+export * from './isDirty/index.ts';
+export * from './isEdited/index.ts';
+export * from './isTouched/index.ts';
+export * from './isValid/index.ts';
+export * from './move/index.ts';
+export * from './pickDirty/index.ts';
+export * from './remove/index.ts';
+export * from './replace/index.ts';
+export * from './reset/index.ts';
+export * from './setErrors/index.ts';
+export * from './setInput/index.ts';
+export * from './submit/index.ts';
+export * from './swap/index.ts';
+export * from './validate/index.ts';

package/src/methods/insert/index.ts

@@ -0,0 +1 @@
+export * from './insert.ts';

package/src/methods/insert/insert.ts

@@ -0,0 +1,134 @@
+import {
+	type BaseFormStore,
+	batch,
+	copyItemState,
+	createId,
+	type DeepPartial,
+	type FormSchema,
+	initializeFieldStore,
+	INTERNAL,
+	type InternalArrayStore,
+	type InternalFieldStore,
+	type PathValue,
+	type RequiredPath,
+	resetItemState,
+	untrack,
+	type ValidArrayPath,
+	validateIfRequired,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Insert array field config interface.
+ */
+export interface InsertConfig<TSchema extends FormSchema, 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.
+ */
+export function insert<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>(
+	form: BaseFormStore<TSchema>,
+	config: InsertConfig<TSchema, TFieldArrayPath>,
+): void {
+	// Get internal form store
+	const internalFormStore = form[INTERNAL];
+
+	// Walk path to get internal field store and mark all parents as having input
+	let internalFieldStore: InternalFieldStore = internalFormStore;
+	for (let index = 0; index < config.path.length; index++) {
+		// @ts-expect-error
+		internalFieldStore = internalFieldStore.children[config.path[index]];
+		if (index < config.path.length - 1) {
+			internalFieldStore.input.value = true;
+		}
+	}
+
+	// Last internal field store of path is array store
+	const internalArrayStore = internalFieldStore as InternalArrayStore;
+
+	// Get current items of field array
+	const items = untrack(() => internalArrayStore.items.value);
+
+	// Determine insertion index (default to end of array)
+	const insertIndex = config.at === undefined ? items.length : config.at;
+
+	// Continue if insertion index is valid
+	if (insertIndex >= 0 && insertIndex <= items.length) {
+		batch(() => {
+			// Insert new item ID at the specified index
+			const newItems = [...items];
+			newItems.splice(insertIndex, 0, createId());
+			internalArrayStore.items.value = newItems;
+
+			// Move all child stores after the insertion point one index up
+			for (let index = items.length; index > insertIndex; index--) {
+				if (!internalArrayStore.children[index]) {
+					// @ts-expect-error
+					internalArrayStore.children[index] = {};
+					initializeFieldStore(
+						internalFormStore,
+						internalArrayStore.children[index],
+						// @ts-expect-error
+						internalArrayStore.schema.item,
+						undefined,
+						[...internalArrayStore.path, index],
+					);
+				}
+				copyItemState(
+					internalFormStore,
+					internalArrayStore.children[index - 1],
+					internalArrayStore.children[index],
+				);
+			}
+
+			if (!internalArrayStore.children[insertIndex]) {
+				// @ts-expect-error
+				internalArrayStore.children[insertIndex] = {};
+				initializeFieldStore(
+					internalFormStore,
+					internalArrayStore.children[insertIndex],
+					// @ts-expect-error
+					internalArrayStore.schema.item,
+					config.initialInput,
+					[...internalArrayStore.path, insertIndex],
+				);
+			} else {
+				resetItemState(
+					internalFormStore,
+					internalArrayStore.children[insertIndex],
+					config.initialInput,
+				);
+			}
+
+			// Mark array input as present in children
+			internalArrayStore.input.value = true;
+
+			// Mark field array as touched, edited and dirty
+			internalArrayStore.isTouched.value = true;
+			internalArrayStore.isEdited.value = true;
+			internalArrayStore.isDirty.value = true;
+
+			// Validate if required
+			// TODO: Should we validate on touch, change and blur too?
+			validateIfRequired(internalFormStore, internalArrayStore, 'input');
+		});
+	}
+}

package/src/methods/isDirty/index.ts

@@ -0,0 +1 @@
+export * from './isDirty.ts';

package/src/methods/isDirty/isDirty.ts

@@ -0,0 +1,72 @@
+import {
+	type BaseFormStore,
+	type FormSchema,
+	getFieldBool,
+	getFieldStore,
+	INTERNAL,
+	type RequiredPath,
+	type ValidPath,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Is form dirty config interface.
+ */
+export interface IsFormDirtyConfig {
+	/**
+	 * The path to a field. Leave undefined to check the entire form.
+	 */
+	readonly path?: undefined;
+}
+
+/**
+ * Is field dirty config interface.
+ */
+export interface IsFieldDirtyConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+	/**
+	 * The path to the field to check for dirtiness.
+	 */
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+
+/**
+ * Checks whether a specific field or the entire form is dirty by walking
+ * through the field store and all its descendants. A field is dirty when its
+ * input differs from its initial value.
+ *
+ * @param form The form store to check for dirtiness.
+ *
+ * @returns Whether the field or form is dirty.
+ */
+export function isDirty<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): boolean;
+
+/**
+ * Checks whether a specific field or the entire form is dirty by walking
+ * through the field store and all its descendants. A field is dirty when its
+ * input differs from its initial value.
+ *
+ * @param form The form store to check for dirtiness.
+ * @param config The is dirty configuration.
+ *
+ * @returns Whether the field or form is dirty.
+ */
+export function isDirty<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? IsFieldDirtyConfig<TSchema, TFieldPath>
+		: IsFormDirtyConfig,
+): boolean;
+
+// @__NO_SIDE_EFFECTS__
+export function isDirty(
+	form: BaseFormStore,
+	config?: IsFormDirtyConfig | IsFieldDirtyConfig<FormSchema, RequiredPath>,
+): boolean {
+	return getFieldBool(
+		config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL],
+		'isDirty',
+	);
+}

package/src/methods/isEdited/index.ts

@@ -0,0 +1 @@
+export * from './isEdited.ts';

package/src/methods/isEdited/isEdited.ts

@@ -0,0 +1,72 @@
+import {
+	type BaseFormStore,
+	type FormSchema,
+	getFieldBool,
+	getFieldStore,
+	INTERNAL,
+	type RequiredPath,
+	type ValidPath,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Is form edited config interface.
+ */
+export interface IsFormEditedConfig {
+	/**
+	 * The path to a field. Leave undefined to check the entire form.
+	 */
+	readonly path?: undefined;
+}
+
+/**
+ * Is field edited config interface.
+ */
+export interface IsFieldEditedConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+	/**
+	 * The path to the field to check for being edited.
+	 */
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+
+/**
+ * Checks whether a specific field or the entire form is edited by walking
+ * through the field store and all its descendants. A field is edited once its
+ * value has been changed by the user.
+ *
+ * @param form The form store to check for being edited.
+ *
+ * @returns Whether the field or form is edited.
+ */
+export function isEdited<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): boolean;
+
+/**
+ * Checks whether a specific field or the entire form is edited by walking
+ * through the field store and all its descendants. A field is edited once its
+ * value has been changed by the user.
+ *
+ * @param form The form store to check for being edited.
+ * @param config The is edited configuration.
+ *
+ * @returns Whether the field or form is edited.
+ */
+export function isEdited<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? IsFieldEditedConfig<TSchema, TFieldPath>
+		: IsFormEditedConfig,
+): boolean;
+
+// @__NO_SIDE_EFFECTS__
+export function isEdited(
+	form: BaseFormStore,
+	config?: IsFormEditedConfig | IsFieldEditedConfig<FormSchema, RequiredPath>,
+): boolean {
+	return getFieldBool(
+		config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL],
+		'isEdited',
+	);
+}

package/src/methods/isTouched/index.ts

@@ -0,0 +1 @@
+export * from './isTouched.ts';

package/src/methods/isTouched/isTouched.ts

@@ -0,0 +1,72 @@
+import {
+	type BaseFormStore,
+	type FormSchema,
+	getFieldBool,
+	getFieldStore,
+	INTERNAL,
+	type RequiredPath,
+	type ValidPath,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Is form touched config interface.
+ */
+export interface IsFormTouchedConfig {
+	/**
+	 * The path to a field. Leave undefined to check the entire form.
+	 */
+	readonly path?: undefined;
+}
+
+/**
+ * Is field touched config interface.
+ */
+export interface IsFieldTouchedConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+	/**
+	 * The path to the field to check for being touched.
+	 */
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+
+/**
+ * Checks whether a specific field or the entire form is touched by walking
+ * through the field store and all its descendants. A field is touched once it
+ * has received and lost focus.
+ *
+ * @param form The form store to check for being touched.
+ *
+ * @returns Whether the field or form is touched.
+ */
+export function isTouched<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): boolean;
+
+/**
+ * Checks whether a specific field or the entire form is touched by walking
+ * through the field store and all its descendants. A field is touched once it
+ * has received and lost focus.
+ *
+ * @param form The form store to check for being touched.
+ * @param config The is touched configuration.
+ *
+ * @returns Whether the field or form is touched.
+ */
+export function isTouched<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? IsFieldTouchedConfig<TSchema, TFieldPath>
+		: IsFormTouchedConfig,
+): boolean;
+
+// @__NO_SIDE_EFFECTS__
+export function isTouched(
+	form: BaseFormStore,
+	config?: IsFormTouchedConfig | IsFieldTouchedConfig<FormSchema, RequiredPath>,
+): boolean {
+	return getFieldBool(
+		config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL],
+		'isTouched',
+	);
+}

package/src/methods/isValid/index.ts

@@ -0,0 +1 @@
+export * from './isValid.ts';

package/src/methods/isValid/isValid.ts

@@ -0,0 +1,74 @@
+import {
+	type BaseFormStore,
+	type FormSchema,
+	getFieldBool,
+	getFieldStore,
+	INTERNAL,
+	type RequiredPath,
+	type ValidPath,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Is form valid config interface.
+ */
+export interface IsFormValidConfig {
+	/**
+	 * The path to a field. Leave undefined to check the entire form.
+	 */
+	readonly path?: undefined;
+}
+
+/**
+ * Is field valid config interface.
+ */
+export interface IsFieldValidConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+	/**
+	 * The path to the field to check for validity.
+	 */
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+
+/**
+ * Checks whether a specific field or the entire form is valid by walking
+ * through the field store and all its descendants. A field is valid when
+ * neither it nor any of its descendants contains an error. Form-level errors
+ * are included.
+ *
+ * @param form The form store to check for validity.
+ *
+ * @returns Whether the field or form is valid.
+ */
+export function isValid<TSchema extends FormSchema>(form: BaseFormStore<TSchema>): boolean;
+
+/**
+ * Checks whether a specific field or the entire form is valid by walking
+ * through the field store and all its descendants. A field is valid when
+ * neither it nor any of its descendants contains an error. Form-level errors
+ * are included.
+ *
+ * @param form The form store to check for validity.
+ * @param config The is valid configuration.
+ *
+ * @returns Whether the field or form is valid.
+ */
+export function isValid<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? IsFieldValidConfig<TSchema, TFieldPath>
+		: IsFormValidConfig,
+): boolean;
+
+// @__NO_SIDE_EFFECTS__
+export function isValid(
+	form: BaseFormStore,
+	config?: IsFormValidConfig | IsFieldValidConfig<FormSchema, RequiredPath>,
+): boolean {
+	return !getFieldBool(
+		config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL],
+		'errors',
+	);
+}

package/src/methods/move/index.ts

@@ -0,0 +1 @@
+export * from './move.ts';

package/src/methods/move/move.ts

@@ -0,0 +1,124 @@
+import {
+	type BaseFormStore,
+	batch,
+	copyItemState,
+	type FormSchema,
+	getFieldStore,
+	initializeFieldStore,
+	INTERNAL,
+	type InternalArrayStore,
+	type InternalFieldStore,
+	type RequiredPath,
+	untrack,
+	type ValidArrayPath,
+	validateIfRequired,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Move array field config interface.
+ */
+export interface MoveConfig<TSchema extends FormSchema, 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.
+ */
+export function move<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>(
+	form: BaseFormStore<TSchema>,
+	config: MoveConfig<TSchema, TFieldArrayPath>,
+): void {
+	// Get internal form and array store
+	const internalFormStore = form[INTERNAL];
+	const internalArrayStore = getFieldStore(internalFormStore, config.path) as InternalArrayStore;
+
+	// Get current items of field array
+	const items = untrack(() => internalArrayStore.items.value);
+
+	// Continue if both indices are valid and different
+	if (
+		config.from >= 0 &&
+		config.from <= items.length - 1 &&
+		config.to >= 0 &&
+		config.to <= items.length - 1 &&
+		config.from !== config.to
+	) {
+		batch(() => {
+			// Move item ID in the items array
+			const newItems = [...items];
+			newItems.splice(config.to, 0, newItems.splice(config.from, 1)[0]);
+			internalArrayStore.items.value = newItems;
+
+			// Create temporary internal field store
+			const tempInternalFieldStore = {} as InternalFieldStore;
+			initializeFieldStore(
+				internalFormStore,
+				tempInternalFieldStore,
+				// @ts-expect-error
+				internalArrayStore.schema.item,
+				undefined,
+				[],
+			);
+
+			// Copy item state that gets overwritten to temporary store
+			copyItemState(
+				internalFormStore,
+				internalArrayStore.children[config.from],
+				tempInternalFieldStore,
+			);
+
+			if (config.from < config.to) {
+				// Move child stores between 'from' and 'to' one index down
+				for (let index = config.from; index < config.to; index++) {
+					copyItemState(
+						internalFormStore,
+						internalArrayStore.children[index + 1],
+						internalArrayStore.children[index],
+					);
+				}
+			} else {
+				// Move child stores between 'to' and 'from' one index up
+				for (let index = config.from; index > config.to; index--) {
+					copyItemState(
+						internalFormStore,
+						internalArrayStore.children[index - 1],
+						internalArrayStore.children[index],
+					);
+				}
+			}
+
+			// Copy item state from temporary store to new position
+			copyItemState(
+				internalFormStore,
+				tempInternalFieldStore,
+				internalArrayStore.children[config.to],
+			);
+
+			// Mark field array as touched and edited and update dirty state
+			internalArrayStore.isTouched.value = true;
+			internalArrayStore.isEdited.value = true;
+			internalArrayStore.isDirty.value =
+				internalArrayStore.startItems.value.join() !== newItems.join();
+
+			// Validate if required
+			// TODO: Should we validate on touch, change and blur too?
+			validateIfRequired(internalFormStore, internalArrayStore, 'input');
+		});
+	}
+}

package/src/methods/pickDirty/index.ts

@@ -0,0 +1 @@
+export * from './pickDirty.ts';