@octanejs/formisch 0.0.1

package/src/core/array/resetItemState/resetItemState.ts

@@ -0,0 +1,172 @@
+import { initializeFieldStore } from '../../field/initializeFieldStore/index.ts';
+import { batch, createId } from '../../framework/index.ts';
+import type {
+	EmptyInput,
+	FieldElement,
+	InternalFieldStore,
+	InternalFormStore,
+} from '../../types/index.ts';
+
+/**
+ * Resets the state of a field store (signal values) deeply nested. Sets
+ * `elements` to empty array, `errors` to `null`, `isTouched`, `isEdited` 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 internalFormStore The form store providing the empty input config.
+ * @param internalFieldStore The field store to reset.
+ * @param input The new input value (can be any type including array or object).
+ * @param keepStart Whether to keep `startInput` and `startItems` as the dirty
+ * baseline instead of resetting them to the new input. Used when a field store
+ * is reused for an in-place edit so its dirty state is detected correctly.
+ */
+export function resetItemState(
+	internalFormStore: InternalFormStore,
+	internalFieldStore: InternalFieldStore,
+	input: unknown,
+	keepStart = false,
+): void {
+	// Batch all state updates for optimal reactivity performance
+	batch(() => {
+		// Clear elements array, keeping `initialElements` in sync while the store
+		// still owns it (not moved by a reorder) so a later `reset` restores the
+		// live element once the field remounts
+		const elements: FieldElement[] = [];
+		if (internalFieldStore.elements === internalFieldStore.initialElements) {
+			internalFieldStore.initialElements = elements;
+		}
+		internalFieldStore.elements = elements;
+
+		// Clear errors
+		internalFieldStore.errors.value = null;
+
+		// Reset touched to false
+		internalFieldStore.isTouched.value = false;
+
+		// Reset edited to false
+		internalFieldStore.isEdited.value = false;
+
+		// Reset dirty to false
+		internalFieldStore.isDirty.value = false;
+
+		// If field store is array or object, handle complex type reset
+		if (internalFieldStore.kind === 'array' || internalFieldStore.kind === 'object') {
+			// For arrays and objects, input is null/undefined or true (not actual
+			// value). Mirror `initializeFieldStore` so a missing input on a
+			// non-nullish array or object becomes a present empty container (`true`)
+			// instead of `undefined`, keeping reset consistent with the initial state.
+			const objectInput = internalFieldStore.isNullish && input == null ? input : true;
+
+			// Set start input unless it is kept as the dirty baseline
+			if (!keepStart) {
+				internalFieldStore.startInput.value = objectInput;
+			}
+
+			// Set current input
+			internalFieldStore.input.value = objectInput;
+
+			// If field store is array, handle array-specific reset
+			if (internalFieldStore.kind === 'array') {
+				// Tuples have a fixed number of children that the schema cannot
+				// recreate (no `item`), so they keep them even when the input is
+				// nullish, just like `initializeFieldStore`
+				const isTuple = internalFieldStore.schema.type !== 'array';
+
+				// If input is provided or store is a tuple, (re)create items with IDs
+				if (input || isTuple) {
+					// Dynamic arrays grow to the input length, while tuples keep their
+					// fixed number of children
+					const length = isTuple ? internalFieldStore.children.length : (input as unknown[]).length;
+
+					// Create new items array with unique IDs for each item
+					const newItems = Array.from({ length }, createId);
+
+					// Set start items unless they are kept as the dirty baseline
+					if (!keepStart) {
+						internalFieldStore.startItems.value = newItems;
+					}
+
+					// Set current items
+					internalFieldStore.items.value = newItems;
+
+					// Reset state for each array item
+					for (let index = 0; index < length; index++) {
+						// A tuple reset without input (or with nullish input) resets each
+						// child to undefined, mirroring `initializeFieldStore`
+						const itemInput = (input as unknown[] | null | undefined)?.[index];
+
+						// If child exists at this index, reset its state
+						if (internalFieldStore.children[index]) {
+							// Recursively reset child with corresponding input
+							resetItemState(
+								internalFormStore,
+								internalFieldStore.children[index],
+								itemInput,
+								keepStart,
+							);
+
+							// Otherwise, initialize a new child with the corresponding input
+						} 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,
+								itemInput,
+								[...internalFieldStore.path, index],
+							);
+						}
+					}
+
+					// Otherwise, clear items arrays
+				} else {
+					// Set start items to empty array unless kept as the dirty baseline
+					if (!keepStart) {
+						internalFieldStore.startItems.value = [];
+					}
+
+					// Set current items to empty array
+					internalFieldStore.items.value = [];
+				}
+
+				// Otherwise, if field store is object, handle object-specific reset
+			} else {
+				// Reset state for each object property
+				for (const key in internalFieldStore.children) {
+					// Recursively reset child with corresponding input
+					resetItemState(
+						internalFormStore,
+						internalFieldStore.children[key],
+						// @ts-expect-error
+						input?.[key],
+						keepStart,
+					);
+				}
+			}
+
+			// Otherwise, if field store is value, handle primitive type reset
+		} else {
+			// Fall back to the empty input for this field's type when no input is
+			// provided so the reset value stays consistent with the initial input.
+			// Optional and nullable fields stay `undefined` as they accept it.
+			const valueInput =
+				input === undefined && !internalFieldStore.isNullish
+					? internalFormStore.emptyInput[internalFieldStore.schema.type as keyof EmptyInput]
+					: input;
+
+			// Set start input unless it is kept as the dirty baseline
+			if (!keepStart) {
+				internalFieldStore.startInput.value = valueInput;
+			}
+
+			// Set current input
+			internalFieldStore.input.value = valueInput;
+		}
+	});
+}

package/src/core/array/swapItemState/index.ts

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

package/src/core/array/swapItemState/swapItemState.ts

@@ -0,0 +1,138 @@
+import { initializeFieldStore } from '../../field/initializeFieldStore/index.ts';
+import { batch, untrack } from '../../framework/index.ts';
+import type { InternalFieldStore, InternalFormStore } from '../../types/index.ts';
+
+/**
+ * Swaps the deeply nested state (signal values) between two field stores. This
+ * includes the `elements`, `errors`, `startInput`, `input`, `isTouched`,
+ * `isEdited`, `isDirty`, and for arrays `startItems` and `items` properties.
+ * Recursively walks through the field stores and swaps all signal values.
+ *
+ * @param internalFormStore The form store providing the empty input config.
+ * @param firstInternalFieldStore The first field store to swap.
+ * @param secondInternalFieldStore The second field store to swap.
+ */
+export function swapItemState(
+	internalFormStore: InternalFormStore,
+	firstInternalFieldStore: InternalFieldStore,
+	secondInternalFieldStore: InternalFieldStore,
+): void {
+	// Batch all state updates for optimal reactivity performance
+	batch(() => {
+		// Untrack to avoid creating reactive dependencies during swap operation
+		untrack(() => {
+			// Swap elements references
+			const tempElements = firstInternalFieldStore.elements;
+			firstInternalFieldStore.elements = secondInternalFieldStore.elements;
+			secondInternalFieldStore.elements = tempElements;
+
+			// Swap errors
+			const tempErrors = firstInternalFieldStore.errors.value;
+			firstInternalFieldStore.errors.value = secondInternalFieldStore.errors.value;
+			secondInternalFieldStore.errors.value = tempErrors;
+
+			// Swap start input
+			const tempStartInput = firstInternalFieldStore.startInput.value;
+			firstInternalFieldStore.startInput.value = secondInternalFieldStore.startInput.value;
+			secondInternalFieldStore.startInput.value = tempStartInput;
+
+			// Swap current input
+			const tempInput = firstInternalFieldStore.input.value;
+			firstInternalFieldStore.input.value = secondInternalFieldStore.input.value;
+			secondInternalFieldStore.input.value = tempInput;
+
+			// Swap touched state
+			const tempIsTouched = firstInternalFieldStore.isTouched.value;
+			firstInternalFieldStore.isTouched.value = secondInternalFieldStore.isTouched.value;
+			secondInternalFieldStore.isTouched.value = tempIsTouched;
+
+			// Swap edited state
+			const tempIsEdited = firstInternalFieldStore.isEdited.value;
+			firstInternalFieldStore.isEdited.value = secondInternalFieldStore.isEdited.value;
+			secondInternalFieldStore.isEdited.value = tempIsEdited;
+
+			// Swap dirty state
+			const tempIsDirty = firstInternalFieldStore.isDirty.value;
+			firstInternalFieldStore.isDirty.value = secondInternalFieldStore.isDirty.value;
+			secondInternalFieldStore.isDirty.value = tempIsDirty;
+
+			// If both stores are arrays, swap array-specific state
+			if (firstInternalFieldStore.kind === 'array' && secondInternalFieldStore.kind === 'array') {
+				// Get current items arrays for later use
+				const firstItems = firstInternalFieldStore.items.value;
+				const secondItems = secondInternalFieldStore.items.value;
+
+				// Swap start items
+				const tempStartItems = firstInternalFieldStore.startItems.value;
+				firstInternalFieldStore.startItems.value = secondInternalFieldStore.startItems.value;
+				secondInternalFieldStore.startItems.value = tempStartItems;
+
+				// Swap current items
+				firstInternalFieldStore.items.value = secondItems;
+				secondInternalFieldStore.items.value = firstItems;
+
+				// Calculate maximum length to ensure all children are swapped
+				const maxLength = Math.max(firstItems.length, secondItems.length);
+
+				// Swap state for each array item
+				for (let index = 0; index < maxLength; index++) {
+					// If first store child doesn't exist, initialize it
+					if (!firstInternalFieldStore.children[index]) {
+						// Create empty child object
+						// @ts-expect-error
+						firstInternalFieldStore.children[index] = {};
+
+						// Initialize field store for new child
+						initializeFieldStore(
+							internalFormStore,
+							firstInternalFieldStore.children[index],
+							// @ts-expect-error
+							firstInternalFieldStore.schema.item,
+							undefined,
+							[...firstInternalFieldStore.path, index],
+						);
+					}
+
+					// If second store child doesn't exist, initialize it
+					if (!secondInternalFieldStore.children[index]) {
+						// Create empty child object
+						// @ts-expect-error
+						secondInternalFieldStore.children[index] = {};
+
+						// Initialize field store for new child
+						initializeFieldStore(
+							internalFormStore,
+							secondInternalFieldStore.children[index],
+							// @ts-expect-error
+							secondInternalFieldStore.schema.item,
+							undefined,
+							[...secondInternalFieldStore.path, index],
+						);
+					}
+
+					// Recursively swap children
+					swapItemState(
+						internalFormStore,
+						firstInternalFieldStore.children[index],
+						secondInternalFieldStore.children[index],
+					);
+				}
+
+				// Otherwise, if both stores are objects, swap object children
+			} else if (
+				firstInternalFieldStore.kind === 'object' &&
+				secondInternalFieldStore.kind === 'object'
+			) {
+				// Swap state for each object property
+				for (const key in firstInternalFieldStore.children) {
+					// Recursively swap children
+					swapItemState(
+						internalFormStore,
+						firstInternalFieldStore.children[key],
+						secondInternalFieldStore.children[key],
+					);
+				}
+			}
+		});
+	});
+}

package/src/core/field/focusFieldElement/focusFieldElement.ts

@@ -0,0 +1,32 @@
+import type { InternalFieldStore } from '../../types/index.ts';
+
+/**
+ * Focuses the first focusable element of a field store. The elements are tried
+ * in order and the first one that actually receives focus wins, so detached,
+ * disabled or hidden elements are skipped. The browser decides focusability,
+ * which is read back via the element's root `activeElement` so elements in a
+ * shadow root or another document are handled correctly.
+ *
+ * Hint: A `display: none` or `hidden` element is correctly skipped in real
+ * browsers, but jsdom has no layout and focuses it anyway, so that case cannot
+ * be covered by unit tests.
+ *
+ * @param internalFieldStore The field store to focus.
+ *
+ * @returns Whether an element was focused.
+ */
+export function focusFieldElement(internalFieldStore: InternalFieldStore): boolean {
+	// Try to focus each element and stop at the first that actually receives
+	// focus, so the focus is not consumed by an element that cannot be focused
+	for (const element of internalFieldStore.elements) {
+		element.focus();
+		// Read focus back from the element's own root (shadow root or document)
+		// so elements in a shadow DOM or another document are handled correctly
+		if ((element.getRootNode() as Document | ShadowRoot).activeElement === element) {
+			return true;
+		}
+	}
+
+	// Otherwise, no element could be focused
+	return false;
+}

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

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

package/src/core/field/getDirtyFieldInput/getDirtyFieldInput.ts

@@ -0,0 +1,66 @@
+import type { InternalFieldStore } from '../../types/index.ts';
+import { getFieldBool } from '../getFieldBool/getFieldBool.ts';
+
+/**
+ * Returns only the dirty input of the field store. Arrays are treated as
+ * atomic and returned in full if any item is dirty, while object keys without
+ * a dirty descendant are omitted. Returns `undefined` if no descendant is
+ * dirty.
+ *
+ * @param internalFieldStore The field store to get dirty input from.
+ * @param dirtyOnly Whether to only include dirty fields. Defaults to `true`.
+ *
+ * @returns The dirty input, or `undefined` if no descendant is dirty.
+ */
+// @__NO_SIDE_EFFECTS__
+export function getDirtyFieldInput(
+	internalFieldStore: InternalFieldStore,
+	dirtyOnly: boolean = true,
+): unknown {
+	// If field has no dirty descendant, return undefined
+	if (dirtyOnly && !getFieldBool(internalFieldStore, 'isDirty')) {
+		return undefined;
+	}
+
+	// If field store is array, collect input from children
+	if (internalFieldStore.kind === 'array') {
+		// If array input is not nullish, build full array from children
+		if (internalFieldStore.input.value) {
+			// Create output array
+			const value = [];
+
+			// Collect input from each array item
+			for (let index = 0; index < internalFieldStore.items.value.length; index++) {
+				value[index] = getDirtyFieldInput(internalFieldStore.children[index], false);
+			}
+			return value;
+		}
+
+		// Otherwise, return nullish input as-is
+		return internalFieldStore.input.value;
+	}
+
+	// If field store is object, recurse only into dirty children
+	if (internalFieldStore.kind === 'object') {
+		// If object input is not nullish, build object from children
+		if (internalFieldStore.input.value) {
+			// Create output object
+			const value: Record<string, unknown> = {};
+
+			// Collect input from each dirty object property
+			for (const key in internalFieldStore.children) {
+				const child = internalFieldStore.children[key];
+				if (!dirtyOnly || getFieldBool(child, 'isDirty')) {
+					value[key] = getDirtyFieldInput(child, dirtyOnly);
+				}
+			}
+			return value;
+		}
+
+		// Otherwise, return nullish input as-is
+		return internalFieldStore.input.value;
+	}
+
+	// Return primitive value input
+	return internalFieldStore.input.value;
+}

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

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

package/src/core/field/getElementInput/getElementInput.ts

@@ -0,0 +1,78 @@
+import { untrack } from '../../framework/index.ts';
+import type { FieldElement, InternalFieldStore } from '../../types/index.ts';
+import { getFieldInput } from '../getFieldInput/index.ts';
+
+/**
+ * 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 internalFieldStore The internal field store.
+ *
+ * @returns The element input.
+ */
+// @__NO_SIDE_EFFECTS__
+export function getElementInput(
+	element: FieldElement,
+	internalFieldStore: InternalFieldStore,
+): unknown {
+	// If element is select with multiple option, return selected values
+	// @ts-expect-error
+	if (element.options && element.multiple) {
+		// @ts-expect-error
+		return [...element.options]
+			.filter((option) => option.selected && !option.disabled)
+			.map((option) => option.value);
+	}
+
+	// If element is checkbox, handle single or group
+	if (element.type === 'checkbox') {
+		// Get all checkboxes with same name
+		const options = document.getElementsByName(element.name);
+
+		// If checkbox group, return array of checked values
+		if (options.length > 1) {
+			return [...options]
+				.filter(
+					(option): option is HTMLInputElement =>
+						option instanceof HTMLInputElement && option.checked,
+				)
+				.map((option) => option.value);
+		}
+
+		// Return single checkbox checked state
+		// @ts-expect-error
+		return element.checked;
+	}
+
+	// If element is radio, handle as string
+	if (element.type === 'radio') {
+		// If radio is checked, return its value
+		// @ts-expect-error
+		if (element.checked) {
+			return element.value;
+		}
+
+		// Otherwise, return previous value
+		return untrack(() => getFieldInput(internalFieldStore));
+	}
+
+	// If element is file input, handle single or multiple
+	if (element.type === 'file') {
+		// If multiple files allowed, return files array
+		// @ts-expect-error
+		if (element.multiple) {
+			return [
+				// @ts-expect-error
+				...element.files,
+			];
+		}
+
+		// Return single file
+		// @ts-expect-error
+		return element.files[0];
+	}
+
+	// Return element value for all other input types
+	return element.value;
+}

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

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

package/src/core/field/getFieldBool/getFieldBool.ts

@@ -0,0 +1,22 @@
+import type { InternalFieldStore } from '../../types/index.ts';
+import { walkFieldStore } from '../walkFieldStore/index.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.
+ */
+// @__NO_SIDE_EFFECTS__
+export function getFieldBool(
+	internalFieldStore: InternalFieldStore,
+	type: 'errors' | 'isTouched' | 'isEdited' | 'isDirty',
+): boolean {
+	// Stop walking as soon as a field has the property set to true
+	return walkFieldStore(internalFieldStore, (internalFieldStore) =>
+		Boolean(internalFieldStore[type].value),
+	);
+}

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

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

package/src/core/field/getFieldInput/getFieldInput.ts

@@ -0,0 +1,52 @@
+import type { InternalFieldStore } from '../../types/index.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.
+ */
+// @__NO_SIDE_EFFECTS__
+export function getFieldInput(internalFieldStore: InternalFieldStore): unknown {
+	// If field store is array, collect input from children
+	if (internalFieldStore.kind === 'array') {
+		// If array input is not nullish, build array from children
+		if (internalFieldStore.input.value) {
+			// Create output array
+			const value = [];
+
+			// Collect input from each array item
+			for (let index = 0; index < internalFieldStore.items.value.length; index++) {
+				value[index] = getFieldInput(internalFieldStore.children[index]);
+			}
+			return value;
+		}
+
+		// Otherwise, return nullish input as-is
+		return internalFieldStore.input.value;
+	}
+
+	// If field store is object, collect input from children
+	if (internalFieldStore.kind === 'object') {
+		// If object input is not nullish, build object from children
+		if (internalFieldStore.input.value) {
+			// Create output object
+			const value: Record<string, unknown> = {};
+
+			// Collect input from each object property
+			for (const key in internalFieldStore.children) {
+				value[key] = getFieldInput(internalFieldStore.children[key]);
+			}
+			return value;
+		}
+
+		// Otherwise, return nullish input as-is
+		return internalFieldStore.input.value;
+	}
+
+	// Return primitive value input
+	return internalFieldStore.input.value;
+}

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

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

package/src/core/field/getFieldStore/getFieldStore.ts

@@ -0,0 +1,34 @@
+import type { InternalFieldStore, InternalFormStore, Path } from '../../types/index.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.
+ */
+// @__NO_SIDE_EFFECTS__
+export function getFieldStore(
+	internalFormStore: InternalFormStore,
+	path: Path,
+): InternalFieldStore {
+	// Start at form store root
+	let internalFieldStore: InternalFieldStore = internalFormStore;
+
+	// Traverse path to find target field store
+	// TODO: This does not guard against paths that exist in the type but not at
+	// runtime (e.g. a not-yet-created dynamic array index), so navigating into a
+	// missing child returns `undefined` and crashes consumers like the deep error
+	// methods. A clean fix likely throws an error or returns `undefined` here
+	// and handles it in all callers.
+	for (const key of path) {
+		// Navigate to child at current path key
+		// @ts-expect-error
+		internalFieldStore = internalFieldStore.children[key];
+	}
+
+	// Return found field store
+	return internalFieldStore;
+}

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

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

package/src/core/field/index.ts

@@ -0,0 +1,11 @@
+export * from './focusFieldElement/index.ts';
+export * from './getDirtyFieldInput/index.ts';
+export * from './getElementInput/index.ts';
+export * from './getFieldBool/index.ts';
+export * from './getFieldInput/index.ts';
+export * from './getFieldStore/index.ts';
+export * from './initializeFieldStore/index.ts';
+export * from './setFieldBool/index.ts';
+export * from './setFieldInput/index.ts';
+export * from './setInitialFieldInput/index.ts';
+export * from './walkFieldStore/index.ts';

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

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