@octanejs/formisch 0.0.1

package/src/methods/pickDirty/pickDirty.ts

@@ -0,0 +1,87 @@
+import {
+	type BaseFormStore,
+	type DeepPartial,
+	type FormSchema,
+	getFieldBool,
+	INTERNAL,
+	type InternalFieldStore,
+} from '../../core/index.ts';
+
+/**
+ * Pick dirty config interface.
+ */
+export interface PickDirtyConfig<TValue extends object> {
+	/**
+	 * The value to filter down to its dirty parts. Must be structurally
+	 * compatible with the form's schema.
+	 */
+	readonly from: TValue;
+}
+
+/**
+ * Picks only the dirty parts of the given value, using the form's dirty fields
+ * as a structural mask. Arrays are treated as atomic and object keys without a
+ * dirty descendant are omitted. Returns `undefined` if no field is dirty.
+ * Useful for filtering a validated output down to its changed parts before
+ * submitting.
+ *
+ * @param form The form store providing the dirty mask.
+ * @param config The pick dirty configuration.
+ *
+ * @returns The dirty parts of the value, or `undefined`.
+ */
+// @__NO_SIDE_EFFECTS__
+export function pickDirty<TSchema extends FormSchema, TValue extends object>(
+	form: BaseFormStore<TSchema>,
+	config: PickDirtyConfig<TValue>,
+): DeepPartial<TValue> | undefined {
+	// If no field is dirty, return undefined
+	if (!getFieldBool(form[INTERNAL], 'isDirty')) {
+		return undefined;
+	}
+
+	// Pick the dirty parts of the value using the form as a mask
+	const result = pickFieldValue(form[INTERNAL], config.from);
+
+	// Return undefined if no dirty property ended up in the result, which can
+	// happen when every dirty key is absent from the supplied value
+	return Object.keys(result as object).length ? (result as DeepPartial<TValue>) : undefined;
+}
+
+/**
+ * Recursively picks the dirty parts of a value using the field store as a
+ * structural mask, reading from the supplied value rather than the form's own
+ * input. Objects with non-nullish input recurse into their dirty children that
+ * are present in the value, while arrays, primitives, nullish-cleared fields
+ * and shape-diverging values are returned as-is.
+ *
+ * @param internalFieldStore The field store used as the dirty mask.
+ * @param value The value to pick the dirty parts from.
+ *
+ * @returns The dirty parts of the value.
+ */
+// @__NO_SIDE_EFFECTS__
+function pickFieldValue(internalFieldStore: InternalFieldStore, value: unknown): unknown {
+	// If field store is object with non-nullish input and the value is a
+	// matching (non-array) object, recurse into children
+	if (
+		internalFieldStore.kind === 'object' &&
+		internalFieldStore.input.value &&
+		value &&
+		typeof value === 'object' &&
+		!Array.isArray(value)
+	) {
+		// Collect dirty parts from each dirty property present in value
+		const result: Record<string, unknown> = {};
+		for (const key in internalFieldStore.children) {
+			const child = internalFieldStore.children[key];
+			if (getFieldBool(child, 'isDirty') && key in value) {
+				result[key] = pickFieldValue(child, (value as Record<string, unknown>)[key]);
+			}
+		}
+		return result;
+	}
+
+	// Otherwise, field is atomic or its shape diverges, so return as-is
+	return value;
+}

package/src/methods/remove/index.ts

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

package/src/methods/remove/remove.ts

@@ -0,0 +1,76 @@
+import {
+	type BaseFormStore,
+	batch,
+	copyItemState,
+	type FormSchema,
+	getFieldStore,
+	INTERNAL,
+	type InternalArrayStore,
+	type RequiredPath,
+	untrack,
+	type ValidArrayPath,
+	validateIfRequired,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Remove array field config interface.
+ */
+export interface RemoveConfig<TSchema extends FormSchema, 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.
+ */
+export function remove<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>(
+	form: BaseFormStore<TSchema>,
+	config: RemoveConfig<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 specified index is valid
+	if (config.at >= 0 && config.at <= items.length - 1) {
+		batch(() => {
+			// Remove item ID from the items array
+			const newItems = [...items];
+			newItems.splice(config.at, 1);
+			internalArrayStore.items.value = newItems;
+
+			// Move all child stores after the removed item one index down
+			for (let index = config.at; index < items.length - 1; index++) {
+				copyItemState(
+					internalFormStore,
+					internalArrayStore.children[index + 1],
+					internalArrayStore.children[index],
+				);
+			}
+
+			// 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/replace/index.ts

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

package/src/methods/replace/replace.ts

@@ -0,0 +1,80 @@
+import {
+	type BaseFormStore,
+	batch,
+	createId,
+	type DeepPartial,
+	type FormSchema,
+	getFieldStore,
+	INTERNAL,
+	type InternalArrayStore,
+	type PathValue,
+	type RequiredPath,
+	resetItemState,
+	untrack,
+	type ValidArrayPath,
+	validateIfRequired,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Replace array field config interface.
+ */
+export interface ReplaceConfig<TSchema extends FormSchema, 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.
+ */
+export function replace<TSchema extends FormSchema, TFieldArrayPath extends RequiredPath>(
+	form: BaseFormStore<TSchema>,
+	config: ReplaceConfig<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 specified index is valid
+	if (config.at >= 0 && config.at <= items.length - 1) {
+		batch(() => {
+			// Replace item ID to trigger reactivity
+			const newItems = [...items];
+			newItems[config.at] = createId();
+			internalArrayStore.items.value = newItems;
+
+			// Replace input of field array item
+			resetItemState(
+				internalFormStore,
+				internalArrayStore.children[config.at],
+				config.initialInput,
+			);
+
+			// 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/reset/index.ts

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

package/src/methods/reset/reset.ts

@@ -0,0 +1,216 @@
+import {
+	type BaseFormStore,
+	batch,
+	type DeepPartial,
+	type FormSchema,
+	getFieldStore,
+	INTERNAL,
+	type PathValue,
+	type RequiredPath,
+	setInitialFieldInput,
+	untrack,
+	validateFormInput,
+	type ValidPath,
+	walkFieldStore,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * 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 edited state during reset. Defaults to false.
+	 */
+	readonly keepEdited?: boolean | undefined;
+	/**
+	 * Whether to keep the error messages during reset. Defaults to false.
+	 */
+	readonly keepErrors?: boolean | undefined;
+}
+
+/**
+ * Reset form config interface.
+ */
+export interface ResetFormConfig<TSchema extends FormSchema> 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;
+	/**
+	 * Whether to keep the submitted state during reset. Defaults to false.
+	 */
+	readonly keepSubmitted?: boolean | undefined;
+}
+
+/**
+ * Reset field config interface.
+ */
+export interface ResetFieldConfig<
+	TSchema extends FormSchema,
+	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>> | undefined;
+}
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export function reset<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? ResetFieldConfig<TSchema, TFieldPath>
+		: ResetFormConfig<TSchema>,
+): void;
+
+export function reset(
+	form: BaseFormStore,
+	config?: ResetFormConfig<FormSchema> | ResetFieldConfig<FormSchema, RequiredPath>,
+): void {
+	batch(() => {
+		untrack(() => {
+			// Get internal form and field store
+			const internalFormStore = form[INTERNAL];
+			const internalFieldStore = config?.path
+				? getFieldStore(internalFormStore, config.path)
+				: internalFormStore;
+
+			// If initial input is provided, set it
+			if (config && 'initialInput' in config) {
+				setInitialFieldInput(internalFormStore, internalFieldStore, config.initialInput);
+			}
+
+			// Reset state of fields by walking field store
+			walkFieldStore(internalFieldStore, (internalFieldStore) => {
+				// Reset elements to initial elements
+				// Hint: `copyItemState` and `swapItemState` move elements between field
+				// stores during array methods, so this restores each field's original
+				// element. Without it, focus and file reset target the wrong element
+				// after a reorder followed by a reset.
+				internalFieldStore.elements = internalFieldStore.initialElements;
+
+				// Reset errors if it is not to be kept
+				if (!config?.keepErrors) {
+					internalFieldStore.errors.value = null;
+				}
+
+				// Reset is touched if it is not to be kept
+				if (!config?.keepTouched) {
+					internalFieldStore.isTouched.value = false;
+				}
+
+				// Reset is edited if it is not to be kept
+				if (!config?.keepEdited) {
+					internalFieldStore.isEdited.value = false;
+				}
+
+				// Reset start input to initial input
+				internalFieldStore.startInput.value = internalFieldStore.initialInput.value;
+
+				// Reset input if it is not to be kept
+				if (!config?.keepInput) {
+					internalFieldStore.input.value = internalFieldStore.initialInput.value;
+				}
+
+				// If it is an array, reset array specific state
+				if (internalFieldStore.kind === 'array') {
+					// Reset start items to initial items
+					internalFieldStore.startItems.value = internalFieldStore.initialItems.value;
+
+					// Reset items if it is not to be kept
+					if (
+						!config?.keepInput ||
+						// Hint: The array items are just an internal concept used to
+						// store and track changes. We reset anyway if the lengths are
+						// equal because otherwise, the field may be in a dirty state
+						// even though there is no visible change for the end user.
+						internalFieldStore.startItems.value.length === internalFieldStore.items.value.length
+					) {
+						internalFieldStore.items.value = internalFieldStore.initialItems.value;
+					}
+
+					// Update is dirty to reflect changes
+					internalFieldStore.isDirty.value =
+						internalFieldStore.startInput.value !== internalFieldStore.input.value ||
+						internalFieldStore.startItems.value !== internalFieldStore.items.value;
+
+					// If it is an object, reset object specific state
+				} else if (internalFieldStore.kind === 'object') {
+					// Update is dirty to reflect changes
+					internalFieldStore.isDirty.value =
+						internalFieldStore.startInput.value !== internalFieldStore.input.value;
+
+					// If it is a value, reset value specific state
+				} else {
+					// Update is dirty to reflect changes
+					// TODO: Should we add support for Dates and Files?
+					const startInput = internalFieldStore.startInput.value;
+					const input = internalFieldStore.input.value;
+					internalFieldStore.isDirty.value =
+						startInput !== input &&
+						// Hint: This check ensures that an empty string or `NaN` does not mark
+						// the field as dirty if the start input was `undefined` or `null`.
+						(startInput != null || (input !== '' && !Number.isNaN(input)));
+
+					// Reset file inputs as they can't be controlled
+					for (const element of internalFieldStore.elements) {
+						if (element.type === 'file') {
+							element.value = '';
+						}
+					}
+				}
+			});
+
+			// If path is not defined, reset form specific state
+			if (!config?.path) {
+				// Reset is submitted if it is not to be kept
+				if (!config?.keepSubmitted) {
+					internalFormStore.isSubmitted.value = false;
+				}
+
+				// Validate form input if configured
+				if (internalFormStore.validate === 'initial') {
+					validateFormInput(internalFormStore);
+				}
+			}
+		});
+	});
+}

package/src/methods/setErrors/index.ts

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

package/src/methods/setErrors/setErrors.ts

@@ -0,0 +1,63 @@
+import {
+	type BaseFormStore,
+	type FormSchema,
+	getFieldStore,
+	INTERNAL,
+	type RequiredPath,
+	type ValidPath,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Set form errors config interface.
+ */
+export 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.
+ */
+export interface SetFieldErrorsConfig<TSchema extends FormSchema, 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.
+ */
+export function setErrors<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? SetFieldErrorsConfig<TSchema, TFieldPath>
+		: SetFormErrorsConfig,
+): void;
+
+export function setErrors(
+	form: BaseFormStore,
+	config: SetFormErrorsConfig | SetFieldErrorsConfig<FormSchema, RequiredPath>,
+): void {
+	(config.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL]).errors.value =
+		config.errors;
+}

package/src/methods/setInput/index.ts

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

package/src/methods/setInput/setInput.ts

@@ -0,0 +1,87 @@
+import {
+	type BaseFormStore,
+	batch,
+	type FormSchema,
+	getFieldStore,
+	INTERNAL,
+	type PathValue,
+	type RequiredPath,
+	setFieldInput,
+	validateIfRequired,
+	type ValidPath,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Set form input config interface.
+ */
+export interface SetFormInputConfig<TSchema extends FormSchema> {
+	/**
+	 * 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.
+ */
+export interface SetFieldInputConfig<TSchema extends FormSchema, 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.
+ */
+export function setInput<TSchema extends FormSchema>(
+	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.
+ */
+export function setInput<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? SetFieldInputConfig<TSchema, TFieldPath>
+		: SetFormInputConfig<TSchema>,
+): void;
+
+export function setInput(
+	form: BaseFormStore,
+	config: SetFormInputConfig<FormSchema> | SetFieldInputConfig<FormSchema, RequiredPath>,
+): void {
+	batch(() => {
+		const internalFormStore = form[INTERNAL];
+		setFieldInput(internalFormStore, config.path ?? [], config.input);
+		const fieldOrFormStore = config.path
+			? getFieldStore(internalFormStore, config.path)
+			: internalFormStore;
+		validateIfRequired(internalFormStore, fieldOrFormStore, 'input');
+		validateIfRequired(internalFormStore, fieldOrFormStore, 'change');
+	});
+}

package/src/methods/submit/index.ts

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

package/src/methods/submit/submit.ts

@@ -0,0 +1,11 @@
+import { type BaseFormStore, INTERNAL } from '../../core/index.ts';
+
+/**
+ * Programmatically requests form submission by calling the native
+ * `requestSubmit()` method on the underlying form element.
+ *
+ * @param form The form store to submit.
+ */
+export function submit(form: BaseFormStore): void {
+	form[INTERNAL].element?.requestSubmit();
+}

package/src/methods/swap/index.ts

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