@octanejs/formisch 0.0.1

package/src/core/field/initializeFieldStore/initializeFieldStore.ts

@@ -0,0 +1,325 @@
+import * as v from 'valibot';
+import { createId, createSignal, framework } from '../../framework/index.ts';
+import type {
+	EmptyInput,
+	FieldElement,
+	InternalFieldStore,
+	InternalFormStore,
+	Path,
+} from '../../types/index.ts';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export type FieldSchema =
+	| v.ArraySchema<
+			v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>,
+			v.ErrorMessage<v.ArrayIssue> | undefined
+	  >
+	| v.BooleanSchema<any>
+	| v.DateSchema<any>
+	| 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.NumberSchema<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.StringSchema<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>;
+
+/**
+ * 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 internalFormStore The form store providing the empty input config.
+ * @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.
+ */
+export function initializeFieldStore(
+	internalFormStore: InternalFormStore,
+	internalFieldStore: Partial<InternalFieldStore>,
+	schema: FieldSchema,
+	initialInput: unknown,
+	path: Path,
+	nullish = false,
+): void {
+	// If schema is unsupported, throw error
+	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`);
+
+		// Otherwise, if schema is lazy, unwrap and initialize
+	} else if (schema.type === 'lazy') {
+		initializeFieldStore(
+			internalFormStore,
+			internalFieldStore,
+			schema.getter(undefined),
+			initialInput,
+			path,
+			nullish,
+		);
+
+		// Otherwise, if schema is nullish wrapper, unwrap and initialize
+	} else if (
+		schema.type === 'exact_optional' ||
+		schema.type === 'nullable' ||
+		schema.type === 'nullish' ||
+		schema.type === 'optional' ||
+		schema.type === 'undefinedable'
+	) {
+		initializeFieldStore(
+			internalFormStore,
+			internalFieldStore,
+			schema.wrapped,
+			initialInput === undefined ? v.getDefault(schema) : initialInput,
+			path,
+			true,
+		);
+
+		// Otherwise, if schema is non-nullish wrapper, unwrap and initialize
+	} else if (
+		schema.type === 'non_nullable' ||
+		schema.type === 'non_nullish' ||
+		schema.type === 'non_optional'
+	) {
+		// Forward the nullish flag so an outer optional or nullable wrapper still
+		// keeps the field at `undefined`/`null` instead of its empty input (e.g.
+		// `v.optional(v.nonOptional(v.string()))`)
+		initializeFieldStore(
+			internalFormStore,
+			internalFieldStore,
+			schema.wrapped,
+			initialInput,
+			path,
+			nullish,
+		);
+
+		// Otherwise, if schema has options, initialize for each option
+	} else if (schema.type === 'intersect' || schema.type === 'union' || schema.type === 'variant') {
+		// Initialize field store for each schema option
+		// Hint: Options share a single field store per key, so per-branch metadata
+		// (`schema`, `kind`, `isNullish`) is approximated last-write-wins. A key
+		// that differs across branches (e.g. nullish in one, required in another)
+		// is therefore not fully represented. See #95 for the long-term fix.
+		for (const schemaOption of schema.options) {
+			initializeFieldStore(
+				internalFormStore,
+				internalFieldStore,
+				schemaOption,
+				initialInput,
+				path,
+				nullish,
+			);
+		}
+
+		// Otherwise, initialize as concrete schema
+	} else {
+		// Set basic properties
+		internalFieldStore.schema = schema;
+		internalFieldStore.name = JSON.stringify(path);
+		// Hint: Each field store receives its own freshly built path array (see the
+		// `[...path, key]` calls below), so it can be stored directly.
+		internalFieldStore.path = path;
+
+		// Store whether property is nullish so resetting can stay consistent
+		internalFieldStore.isNullish = nullish;
+
+		// Initialize elements array
+		// Hint: `initialElements` and `elements` start as the same array so that
+		// `reset` can restore elements that array methods move between field stores
+		// (see `initialElements` in the `InternalBaseStore` interface).
+		const initialElements: FieldElement[] = [];
+		internalFieldStore.initialElements = initialElements;
+		internalFieldStore.elements = initialElements;
+
+		// Initialize common signals
+		internalFieldStore.errors = createSignal(null);
+		internalFieldStore.isTouched = createSignal(false);
+		internalFieldStore.isEdited = createSignal(false);
+		internalFieldStore.isDirty = createSignal(false);
+
+		// If schema is array or tuple, initialize as array field
+		if (
+			schema.type === 'array' ||
+			schema.type === 'loose_tuple' ||
+			schema.type === 'strict_tuple' ||
+			schema.type === 'tuple'
+		) {
+			// If already initialized as different kind, throw error
+			if (internalFieldStore.kind && internalFieldStore.kind !== 'array') {
+				throw new Error(
+					`Store initialized as "${internalFieldStore.kind}" cannot be reinitialized as "array"`,
+				);
+			}
+
+			// Set kind to array
+			internalFieldStore.kind = 'array';
+
+			// Initialize array-specific properties
+			if (internalFieldStore.kind === 'array') {
+				// Initialize children array if not exists
+				internalFieldStore.children ??= [];
+
+				// If schema is dynamic array, initialize children from input
+				if (schema.type === 'array') {
+					// If initial input provided, initialize children
+					if (initialInput) {
+						// Initialize child for each input item
+						for (
+							let index = 0;
+							// @ts-expect-error
+							index < initialInput.length;
+							index++
+						) {
+							// Create empty child object
+							// @ts-expect-error
+							internalFieldStore.children[index] = {};
+
+							// Initialize field store for child
+							initializeFieldStore(
+								internalFormStore,
+								internalFieldStore.children[index],
+								schema.item as FieldSchema,
+								// @ts-expect-error
+								initialInput[index],
+								[...path, index],
+							);
+						}
+					}
+
+					// Otherwise, if schema is fixed tuple, initialize children from schema
+				} else {
+					// Initialize child for each tuple item
+					for (let index = 0; index < schema.items.length; index++) {
+						// Create empty child object
+						// @ts-expect-error
+						internalFieldStore.children[index] = {};
+
+						// Initialize field store for child
+						initializeFieldStore(
+							internalFormStore,
+							internalFieldStore.children[index],
+							schema.items[index] as FieldSchema,
+							// @ts-expect-error
+							initialInput?.[index],
+							[...path, index],
+						);
+					}
+				}
+
+				// Set array input (nullish or true)
+				const arrayInput = nullish && initialInput == null ? initialInput : true;
+				internalFieldStore.initialInput = createSignal(arrayInput);
+				internalFieldStore.startInput = createSignal(arrayInput);
+				internalFieldStore.input = createSignal(arrayInput);
+
+				// Set items with unique IDs for each child
+				const initialItems = internalFieldStore.children.map(createId);
+				internalFieldStore.initialItems = createSignal(initialItems);
+				internalFieldStore.startItems = createSignal(initialItems);
+				internalFieldStore.items = createSignal(initialItems);
+			}
+
+			// Otherwise, if schema is object, initialize as object field
+		} else if (
+			schema.type === 'loose_object' ||
+			schema.type === 'object' ||
+			schema.type === 'strict_object'
+		) {
+			// If already initialized as different kind, throw error
+			if (internalFieldStore.kind && internalFieldStore.kind !== 'object') {
+				throw new Error(
+					`Store initialized as "${internalFieldStore.kind}" cannot be reinitialized as "object"`,
+				);
+			}
+
+			// Set kind to object
+			internalFieldStore.kind = 'object';
+
+			// Initialize object-specific properties
+			if (internalFieldStore.kind === 'object') {
+				// Initialize children object if not exists
+				internalFieldStore.children ??= {};
+
+				// Initialize child for each object entry
+				for (const key in schema.entries) {
+					// Create empty child object if not exists
+					// @ts-expect-error
+					internalFieldStore.children[key] ??= {};
+
+					// Initialize field store for child
+					initializeFieldStore(
+						internalFormStore,
+						internalFieldStore.children[key],
+						schema.entries[key] as FieldSchema,
+						// @ts-expect-error
+						initialInput?.[key],
+						[...path, key],
+					);
+				}
+
+				// Set object input (nullish or true)
+				const objectInput = nullish && initialInput == null ? initialInput : true;
+				internalFieldStore.initialInput = createSignal(objectInput);
+				internalFieldStore.startInput = createSignal(objectInput);
+				internalFieldStore.input = createSignal(objectInput);
+			}
+
+			// Otherwise, initialize as value field (leaf node)
+		} else {
+			// If already initialized as different kind, throw error
+			if (internalFieldStore.kind && internalFieldStore.kind !== 'value') {
+				throw new Error(
+					`Store initialized as "${internalFieldStore.kind}" cannot be reinitialized as "value"`,
+				);
+			}
+
+			// Set kind to value
+			internalFieldStore.kind = 'value';
+
+			// Initialize value-specific properties
+			if (internalFieldStore.kind === 'value') {
+				// Resolve the empty input for this field's type from the configured map
+				// (e.g. `''` for a string), so an untouched empty field matches the DOM
+				// and validates with its own message instead of a type mismatch.
+				// Optional and nullable fields stay `undefined` as they accept it.
+				const valueInput =
+					initialInput === undefined && !nullish
+						? internalFormStore.emptyInput[schema.type as keyof EmptyInput]
+						: initialInput;
+
+				// Set initial, start and current input
+				internalFieldStore.initialInput = createSignal(valueInput);
+				internalFieldStore.startInput = createSignal(valueInput);
+				internalFieldStore.input = createSignal(valueInput);
+			}
+		}
+	}
+}

package/src/core/field/setFieldBool/index.ts

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

package/src/core/field/setFieldBool/setFieldBool.ts

@@ -0,0 +1,29 @@
+import { batch, untrack } from '../../framework/index.ts';
+import type { InternalFieldStore } from '../../types/index.ts';
+import { walkFieldStore } from '../walkFieldStore/index.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.
+ */
+export function setFieldBool(
+	internalFieldStore: InternalFieldStore,
+	type: 'isTouched' | 'isDirty',
+	bool: boolean,
+): void {
+	// Batch all state updates for optimal reactivity performance
+	batch(() => {
+		// Untracked to avoid subscribing a surrounding reactive scope to the
+		// form structure
+		untrack(() => {
+			// Set property on each field store
+			walkFieldStore(internalFieldStore, (internalFieldStore) => {
+				internalFieldStore[type].value = bool;
+			});
+		});
+	});
+}

package/src/core/field/setFieldInput/index.ts

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

package/src/core/field/setFieldInput/setFieldInput.ts

@@ -0,0 +1,180 @@
+import { resetItemState } from '../../array/resetItemState/index.ts';
+import { batch, createId, untrack } from '../../framework/index.ts';
+import type { InternalFieldStore, InternalFormStore, Path } from '../../types/index.ts';
+import { initializeFieldStore } from '../initializeFieldStore/index.ts';
+
+/**
+ * Sets the input for a nested field store and all its children, updating
+ * touched and dirty states accordingly. Handles dynamic array resizing.
+ *
+ * @param internalFormStore The form store providing the empty input config.
+ * @param internalFieldStore The field store to update.
+ * @param input The new input value.
+ */
+function setNestedInput(
+	internalFormStore: InternalFormStore,
+	internalFieldStore: InternalFieldStore,
+	input: unknown,
+): void {
+	// Mark field as touched and edited
+	internalFieldStore.isTouched.value = true;
+	internalFieldStore.isEdited.value = true;
+
+	// If field store is array, handle array input
+	if (internalFieldStore.kind === 'array') {
+		// Normalize input to empty array if nullish
+		const arrayInput = input ?? [];
+		const items = internalFieldStore.items.value;
+
+		// Tuples have a fixed number of children, so ignore any extra input items
+		// instead of growing them (they have no `item` schema to initialize
+		// additional children, unlike dynamic arrays)
+		const length =
+			internalFieldStore.schema.type === 'array'
+				? (arrayInput as unknown[]).length
+				: internalFieldStore.children.length;
+
+		// If new array is shorter, truncate items
+		if (length < items.length) {
+			internalFieldStore.items.value = items.slice(0, length);
+
+			// Otherwise, if new array is longer, extend items
+		} else if (length > items.length) {
+			// Initialize or reset each newly visible child
+			for (let index = items.length; index < length; index++) {
+				// Reset the reused stale child but keep its start input as baseline
+				// Hint: A child store from a previously longer array still holds stale
+				// errors and nested values that must be cleared, but its `startInput`
+				// and `startItems` are the dirty baseline. Passing `keepStart`
+				// preserves them so editing a regrown index is detected as dirty, just
+				// like a direct edit on a never-shrunk array would be.
+				if (internalFieldStore.children[index]) {
+					resetItemState(
+						internalFormStore,
+						internalFieldStore.children[index],
+						// @ts-expect-error
+						arrayInput[index],
+						true,
+					);
+
+					// Otherwise, create and initialize a brand-new child
+				} else {
+					// Create empty child object
+					// @ts-expect-error
+					internalFieldStore.children[index] = {};
+
+					// Initialize field store for new child
+					initializeFieldStore(
+						internalFormStore,
+						internalFieldStore.children[index],
+						// @ts-expect-error
+						internalFieldStore.schema.item,
+						// @ts-expect-error
+						arrayInput[index],
+						[...internalFieldStore.path, index],
+					);
+				}
+			}
+
+			// Extend items array with new items, capped to the clamped length so a
+			// tuple never grows beyond its fixed number of children
+			internalFieldStore.items.value = [
+				...items,
+				...Array.from({ length: length - items.length }, createId),
+			];
+		}
+
+		// Set input for each array item
+		for (let index = 0; index < length; index++) {
+			// Recursively set nested input
+			setNestedInput(
+				internalFormStore,
+				internalFieldStore.children[index],
+				// @ts-expect-error
+				arrayInput[index],
+			);
+		}
+
+		// Set array input
+		internalFieldStore.input.value = input == null ? input : true;
+
+		// Update dirty state based on input or items length change
+		internalFieldStore.isDirty.value =
+			internalFieldStore.startInput.value !== internalFieldStore.input.value ||
+			internalFieldStore.startItems.value.length !== internalFieldStore.items.value.length;
+
+		// Otherwise, if field store is object, handle object input
+	} else if (internalFieldStore.kind === 'object') {
+		// Set input for each object property
+		for (const key in internalFieldStore.children) {
+			// Recursively set nested input
+			setNestedInput(
+				internalFormStore,
+				internalFieldStore.children[key],
+				// @ts-expect-error
+				input?.[key],
+			);
+		}
+
+		// Set object input
+		internalFieldStore.input.value = input == null ? input : true;
+
+		// Update dirty state based on input change
+		internalFieldStore.isDirty.value =
+			internalFieldStore.startInput.value !== internalFieldStore.input.value;
+
+		// Otherwise, handle value field input
+	} else {
+		// Set value input
+		internalFieldStore.input.value = input;
+
+		// TODO: Should we add support for Dates and Files?
+		// Get start input for comparison
+		const startInput = internalFieldStore.startInput.value;
+
+		// Update dirty state with special handling for empty string and NaN
+		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)));
+	}
+}
+
+/**
+ * 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.
+ */
+export function setFieldInput(
+	internalFormStore: InternalFormStore,
+	path: Path,
+	input: unknown,
+): void {
+	// Batch all state updates for optimal reactivity performance
+	batch(() => {
+		// Untrack to avoid creating reactive dependencies during update
+		untrack(() => {
+			// Start at form store root
+			let internalFieldStore: InternalFieldStore = internalFormStore;
+
+			// Traverse path to target field
+			for (let index = 0; index < path.length; index++) {
+				// Navigate to child at current path key
+				// @ts-expect-error
+				internalFieldStore = internalFieldStore.children[path[index]];
+
+				// If not at target field, mark parent input as truthy
+				if (index < path.length - 1) {
+					internalFieldStore.input.value = true;
+				}
+			}
+
+			// Set nested input on target field
+			setNestedInput(internalFormStore, internalFieldStore, input);
+		});
+	});
+}

package/src/core/field/setInitialFieldInput/index.ts

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

package/src/core/field/setInitialFieldInput/setInitialFieldInput.ts

@@ -0,0 +1,99 @@
+import { batch, createId } from '../../framework/index.ts';
+import type { EmptyInput, InternalFieldStore, InternalFormStore } from '../../types/index.ts';
+import { initializeFieldStore } from '../initializeFieldStore/index.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 internalFormStore The form store providing the empty input config.
+ * @param internalFieldStore The field store to update.
+ * @param initialInput The initial input value.
+ */
+export function setInitialFieldInput(
+	internalFormStore: InternalFormStore,
+	internalFieldStore: InternalFieldStore,
+	initialInput: unknown,
+): void {
+	// Batch all state updates for optimal reactivity performance
+	batch(() => {
+		// If field store is array, handle array initial input
+		if (internalFieldStore.kind === 'array') {
+			// Set initial array input
+			internalFieldStore.initialInput.value = initialInput == null ? initialInput : true;
+
+			// Normalize input to empty array if nullish
+			const initialArrayInput = initialInput ?? [];
+
+			// Tuples have a fixed number of children, so ignore any extra input items
+			// instead of growing them (they have no `item` schema to initialize
+			// additional children, unlike dynamic arrays)
+			const length =
+				internalFieldStore.schema.type === 'array'
+					? (initialArrayInput as unknown[]).length
+					: internalFieldStore.children.length;
+
+			// If initial input exceeds children capacity, initialize new children
+			if (length > internalFieldStore.children.length) {
+				// Initialize missing children
+				for (let index = internalFieldStore.children.length; index < length; index++) {
+					// Create empty child object
+					// @ts-expect-error
+					internalFieldStore.children[index] = {};
+
+					// Initialize field store for new child
+					initializeFieldStore(
+						internalFormStore,
+						internalFieldStore.children[index],
+						// @ts-expect-error
+						internalFieldStore.schema.item,
+						// @ts-expect-error
+						initialArrayInput[index],
+						[...internalFieldStore.path, index],
+					);
+				}
+			}
+
+			// Set initial items with unique IDs
+			internalFieldStore.initialItems.value = Array.from({ length }, createId);
+
+			// Set initial input for each array item
+			for (let index = 0; index < internalFieldStore.children.length; index++) {
+				// Recursively set initial input for child
+				setInitialFieldInput(
+					internalFormStore,
+					internalFieldStore.children[index],
+					// @ts-expect-error
+					initialArrayInput[index],
+				);
+			}
+
+			// Otherwise, if field store is object, handle object initial input
+		} else if (internalFieldStore.kind === 'object') {
+			// Set initial object input
+			internalFieldStore.initialInput.value = initialInput == null ? initialInput : true;
+
+			// Set initial input for each object property
+			for (const key in internalFieldStore.children) {
+				// Recursively set initial input for child
+				setInitialFieldInput(
+					internalFormStore,
+					internalFieldStore.children[key],
+					// @ts-expect-error
+					initialInput?.[key],
+				);
+			}
+
+			// Otherwise, handle value field initial input
+		} else {
+			// Fall back to the empty input for this field's type when no input is
+			// provided so the initial input stays consistent with form
+			// initialization. Optional and nullable fields stay `undefined`.
+			internalFieldStore.initialInput.value =
+				initialInput === undefined && !internalFieldStore.isNullish
+					? internalFormStore.emptyInput[internalFieldStore.schema.type as keyof EmptyInput]
+					: initialInput;
+		}
+	});
+}

package/src/core/field/walkFieldStore/index.ts

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

package/src/core/field/walkFieldStore/walkFieldStore.ts

@@ -0,0 +1,49 @@
+import type { InternalFieldStore } from '../../types/index.ts';
+
+/**
+ * Walks through the field store and all nested children, calling the callback
+ * for each field store in depth-first order. The callback may return `true` to
+ * stop the walk early, in which case `walkFieldStore` returns `true` as well.
+ *
+ * The walk reads array `items` reactively, so a reactive caller subscribes to
+ * structural changes naturally. Imperative callers that must not subscribe
+ * (e.g. when invoked inside an effect) should wrap the call in `untrack`.
+ *
+ * @param internalFieldStore The field store to walk.
+ * @param callback The callback to invoke for each field store. Return `true` to stop the walk early.
+ *
+ * @returns Whether the walk was stopped early by the callback.
+ */
+export function walkFieldStore(
+	internalFieldStore: InternalFieldStore,
+	callback: (internalFieldStore: InternalFieldStore) => boolean | void,
+): boolean {
+	// Invoke callback for current field store and stop early if requested
+	if (callback(internalFieldStore)) {
+		return true;
+	}
+
+	// If field store is array, walk all children
+	if (internalFieldStore.kind === 'array') {
+		// Walk each array item
+		for (let index = 0; index < internalFieldStore.items.value.length; index++) {
+			// Recursively walk child and stop early if requested
+			if (walkFieldStore(internalFieldStore.children[index], callback)) {
+				return true;
+			}
+		}
+
+		// Otherwise, if field store is object, walk all children
+	} else if (internalFieldStore.kind === 'object') {
+		// Walk each object property
+		for (const key in internalFieldStore.children) {
+			// Recursively walk child and stop early if requested
+			if (walkFieldStore(internalFieldStore.children[key], callback)) {
+				return true;
+			}
+		}
+	}
+
+	// Otherwise, return that the walk completed without stopping early
+	return false;
+}