@octanejs/formisch 0.0.1

package/src/hooks/useSignals/useSignals.ts

@@ -0,0 +1,31 @@
+import { useEffect, useLayoutEffect, useMemo, useState } from 'octane';
+import { setListener, type Listener } from '../../core/index.ts';
+import { subSlot } from '../../internal.ts';
+
+export function useSignals(...rest: [slot?: symbol]): void {
+	const slot = typeof rest[0] === 'symbol' ? rest[0] : undefined;
+	const [, setVersion] = useState(0, subSlot(slot, 'version'));
+	const listener = useMemo<Listener>(
+		() => [() => setVersion((version) => version + 1), new Set()],
+		[],
+		subSlot(slot, 'listener'),
+	);
+	const cleanSubscribers = () => {
+		for (const subscriber of listener[1]) subscriber.delete(listener);
+		listener[1].clear();
+	};
+
+	cleanSubscribers();
+
+	const isServer = typeof document === 'undefined';
+	if (!isServer) setListener(listener);
+
+	useLayoutEffect(
+		() => {
+			if (!isServer) setListener(undefined);
+		},
+		null,
+		subSlot(slot, 'clear-listener'),
+	);
+	useEffect(() => cleanSubscribers, [listener], subSlot(slot, 'cleanup'));
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export type {
+	DeepPartial,
+	FieldElement,
+	FormConfig,
+	PartialValues,
+	PathValue,
+	RequiredPath,
+	FormSchema,
+	Schema,
+	SubmitEventHandler,
+	SubmitHandler,
+	ValidArrayPath,
+	ValidationMode,
+	ValidPath,
+} from './core/index.ts';
+export * from './components/index.ts';
+export * from './hooks/index.ts';
+export * from './methods/index.ts';
+export * from './types/index.ts';

package/src/internal.ts

@@ -0,0 +1,32 @@
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+const bareTagCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined) {
+			bare = Symbol.for(`@octanejs/formisch:${tag}`);
+			bareTagCache.set(tag, bare);
+		}
+		return bare;
+	}
+
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) {
+		byTag = new Map();
+		subSlotCache.set(slot, byTag);
+	}
+
+	let child = byTag.get(tag);
+	if (child === undefined) {
+		child = Symbol.for(`${slot.description ?? ''}:${tag}`);
+		byTag.set(tag, child);
+	}
+	return child;
+}
+
+export function splitSlot(args: unknown[]): [unknown[], symbol | undefined] {
+	const tail = args.at(-1);
+	const slot = typeof tail === 'symbol' ? tail : undefined;
+	return [slot === undefined ? args : args.slice(0, -1), slot];
+}

package/src/methods/focus/focus.ts

@@ -0,0 +1,35 @@
+import {
+	type BaseFormStore,
+	focusFieldElement,
+	type FormSchema,
+	getFieldStore,
+	INTERNAL,
+	type RequiredPath,
+	type ValidPath,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Focus field config interface.
+ */
+export interface FocusFieldConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+	/**
+	 * The path to the field to focus.
+	 */
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+
+/**
+ * Focuses the first focusable input element of a field. This is useful for
+ * programmatically setting focus to a specific field, such as after
+ * validation errors or user interactions.
+ *
+ * @param form The form store containing the field.
+ * @param config The focus field configuration.
+ */
+export function focus<TSchema extends FormSchema, TFieldPath extends RequiredPath>(
+	form: BaseFormStore<TSchema>,
+	config: FocusFieldConfig<TSchema, TFieldPath>,
+): void {
+	focusFieldElement(getFieldStore(form[INTERNAL], config.path));
+}

package/src/methods/focus/index.ts

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

package/src/methods/getDeepErrorEntries/getDeepErrorEntries.ts

@@ -0,0 +1,108 @@
+import {
+	type BaseFormStore,
+	type FieldPath,
+	type FormSchema,
+	getFieldStore,
+	INTERNAL,
+	type Path,
+	type RequiredPath,
+	type ValidPath,
+	walkFieldStore,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Deep error entry interface.
+ */
+export interface DeepErrorEntry<TValue = unknown> {
+	/**
+	 * The path to the field with errors, or an empty path for form-level errors.
+	 */
+	readonly path: unknown extends TValue ? Path : readonly [] | FieldPath<TValue>;
+	/**
+	 * The error messages of the field.
+	 */
+	readonly errors: [string, ...string[]];
+}
+
+/**
+ * Get form deep error entries config interface.
+ */
+export interface GetFormDeepErrorEntriesConfig {
+	/**
+	 * The path to a field. Leave undefined to get the entries of the entire form.
+	 */
+	readonly path?: undefined;
+}
+
+/**
+ * Get field deep error entries config interface.
+ */
+export interface GetFieldDeepErrorEntriesConfig<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath,
+> {
+	/**
+	 * The path to the field to retrieve the entries from.
+	 */
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+
+/**
+ * Retrieves the errors of a specific field or the entire form as a list of
+ * entries, each pairing the path to a field with its error messages. This is
+ * useful for building custom error summaries that link each message back to
+ * its field. Form-level errors are included with an empty path.
+ *
+ * @param form The form store to retrieve error entries from.
+ *
+ * @returns A list of path and error message entries.
+ */
+export function getDeepErrorEntries<TSchema extends FormSchema>(
+	form: BaseFormStore<TSchema>,
+): DeepErrorEntry<v.InferInput<TSchema>>[];
+
+/**
+ * Retrieves the errors of a specific field or the entire form as a list of
+ * entries, each pairing the path to a field with its error messages. This is
+ * useful for building custom error summaries that link each message back to
+ * its field. Form-level errors are included with an empty path.
+ *
+ * @param form The form store to retrieve error entries from.
+ * @param config The get deep error entries configuration.
+ *
+ * @returns A list of path and error message entries.
+ */
+export function getDeepErrorEntries<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? GetFieldDeepErrorEntriesConfig<TSchema, TFieldPath>
+		: GetFormDeepErrorEntriesConfig,
+): DeepErrorEntry<v.InferInput<TSchema>>[];
+
+// @__NO_SIDE_EFFECTS__
+export function getDeepErrorEntries(
+	form: BaseFormStore,
+	config?: GetFormDeepErrorEntriesConfig | GetFieldDeepErrorEntriesConfig<FormSchema, RequiredPath>,
+): DeepErrorEntry[] {
+	// Collect entries of errored fields by walking the field store tree, reading
+	// each field's own path instead of reconstructing it during the walk
+	const entries: DeepErrorEntry[] = [];
+	walkFieldStore(
+		config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL],
+		(internalFieldStore) => {
+			// Emit an entry if field has errors; form-level errors are emitted
+			const errors = internalFieldStore.errors.value;
+			if (errors) {
+				entries.push({
+					path: internalFieldStore.path,
+					errors,
+				});
+			}
+		},
+	);
+	return entries;
+}

package/src/methods/getDeepErrorEntries/index.ts

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

package/src/methods/getDeepErrors/getDeepErrors.ts

@@ -0,0 +1,90 @@
+import {
+	type BaseFormStore,
+	type FormSchema,
+	getFieldStore,
+	INTERNAL,
+	type RequiredPath,
+	type ValidPath,
+	walkFieldStore,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Get form deep errors config interface.
+ */
+export interface GetFormDeepErrorsConfig {
+	/**
+	 * The path to a field. Leave undefined to get the errors of the entire form.
+	 */
+	readonly path?: undefined;
+}
+
+/**
+ * Get field deep errors config interface.
+ */
+export interface GetFieldDeepErrorsConfig<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath,
+> {
+	/**
+	 * The path to the field to retrieve the errors from.
+	 */
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+
+/**
+ * Retrieves all error messages of a specific field or the entire form by
+ * walking through the field store and all its descendants. This is useful for
+ * displaying a summary of all validation errors within a section or the whole
+ * form. Form-level errors are included.
+ *
+ * @param form The form store to retrieve errors from.
+ *
+ * @returns A non-empty array of error messages, or null if no errors exist.
+ */
+export function getDeepErrors<TSchema extends FormSchema>(
+	form: BaseFormStore<TSchema>,
+): [string, ...string[]] | null;
+
+/**
+ * Retrieves all error messages of a specific field or the entire form by
+ * walking through the field store and all its descendants. This is useful for
+ * displaying a summary of all validation errors within a section or the whole
+ * form. Form-level errors are included.
+ *
+ * @param form The form store to retrieve errors from.
+ * @param config The get deep errors configuration.
+ *
+ * @returns A non-empty array of error messages, or null if no errors exist.
+ */
+export function getDeepErrors<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? GetFieldDeepErrorsConfig<TSchema, TFieldPath>
+		: GetFormDeepErrorsConfig,
+): [string, ...string[]] | null;
+
+// @__NO_SIDE_EFFECTS__
+export function getDeepErrors(
+	form: BaseFormStore,
+	config?: GetFormDeepErrorsConfig | GetFieldDeepErrorsConfig<FormSchema, RequiredPath>,
+): [string, ...string[]] | null {
+	let deepErrors: [string, ...string[]] | null = null;
+	walkFieldStore(
+		config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL],
+		(internalFieldStore) => {
+			const errors = internalFieldStore.errors.value;
+			if (errors) {
+				if (deepErrors) {
+					deepErrors.push(...errors);
+				} else {
+					deepErrors = [...errors];
+				}
+			}
+		},
+	);
+	return deepErrors;
+}

package/src/methods/getDeepErrors/index.ts

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

package/src/methods/getDirtyInput/getDirtyInput.ts

@@ -0,0 +1,87 @@
+import {
+	type BaseFormStore,
+	type DeepPartial,
+	type FormSchema,
+	getDirtyFieldInput,
+	getFieldStore,
+	INTERNAL,
+	type PathValue,
+	type RequiredPath,
+	type ValidPath,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Get form dirty input config interface.
+ */
+export interface GetFormDirtyInputConfig {
+	/**
+	 * The path to a field. Leave undefined to get the dirty input of the entire
+	 * form.
+	 */
+	readonly path?: undefined;
+}
+
+/**
+ * Get field dirty input config interface.
+ */
+export interface GetFieldDirtyInputConfig<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath,
+> {
+	/**
+	 * The path to the field to retrieve the dirty input from.
+	 */
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+
+/**
+ * Retrieves only the dirty input values of a specific field or the entire
+ * form. 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 field in the inspected subtree is dirty.
+ *
+ * @param form The form store to retrieve dirty input from.
+ *
+ * @returns The dirty input of the form or specified field, or `undefined`.
+ */
+export function getDirtyInput<TSchema extends FormSchema>(
+	form: BaseFormStore<TSchema>,
+): DeepPartial<v.InferInput<TSchema>> | undefined;
+
+/**
+ * Retrieves only the dirty input values of a specific field or the entire
+ * form. 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 field in the inspected subtree is dirty.
+ *
+ * @param form The form store to retrieve dirty input from.
+ * @param config The get dirty input configuration.
+ *
+ * @returns The dirty input of the form or specified field, or `undefined`.
+ */
+export function getDirtyInput<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? GetFieldDirtyInputConfig<TSchema, TFieldPath>
+		: GetFormDirtyInputConfig,
+):
+	| DeepPartial<
+			TFieldPath extends RequiredPath
+				? PathValue<v.InferInput<TSchema>, TFieldPath>
+				: v.InferInput<TSchema>
+	  >
+	| undefined;
+
+// @__NO_SIDE_EFFECTS__
+export function getDirtyInput(
+	form: BaseFormStore,
+	config?: GetFormDirtyInputConfig | GetFieldDirtyInputConfig<FormSchema, RequiredPath>,
+): unknown {
+	return getDirtyFieldInput(
+		config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL],
+	);
+}

package/src/methods/getDirtyInput/index.ts

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

package/src/methods/getDirtyPaths/getDirtyPaths.ts

@@ -0,0 +1,123 @@
+import {
+	type BaseFormStore,
+	type DirtyPath,
+	type FormSchema,
+	getFieldBool,
+	getFieldStore,
+	INTERNAL,
+	type InternalFieldStore,
+	type RequiredPath,
+	type ValidPath,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Get form dirty paths config interface.
+ */
+export interface GetFormDirtyPathsConfig {
+	/**
+	 * The path to a field. Leave undefined to inspect the entire form.
+	 */
+	readonly path?: undefined;
+}
+
+/**
+ * Get field dirty paths config interface.
+ */
+export interface GetFieldDirtyPathsConfig<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath,
+> {
+	/**
+	 * The path to the field to inspect.
+	 */
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+
+/**
+ * Returns a list of paths to the dirty fields of a specific field or the
+ * entire form. Arrays are treated as atomic and contribute only their own
+ * path if any item is dirty, while object branches are recursed into. Returns
+ * an empty list if no field in the inspected subtree is dirty.
+ *
+ * @param form The form store to inspect.
+ *
+ * @returns The list of paths to the dirty fields.
+ */
+export function getDirtyPaths<TSchema extends FormSchema>(
+	form: BaseFormStore<TSchema>,
+): DirtyPath<v.InferInput<TSchema>>[];
+
+/**
+ * Returns a list of paths to the dirty fields of a specific field or the
+ * entire form. Arrays are treated as atomic and contribute only their own
+ * path if any item is dirty, while object branches are recursed into. Returns
+ * an empty list if no field in the inspected subtree is dirty.
+ *
+ * @param form The form store to inspect.
+ * @param config The get dirty paths configuration.
+ *
+ * @returns The list of paths to the dirty fields.
+ */
+export function getDirtyPaths<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? GetFieldDirtyPathsConfig<TSchema, TFieldPath>
+		: GetFormDirtyPathsConfig,
+): DirtyPath<v.InferInput<TSchema>>[];
+
+// @__NO_SIDE_EFFECTS__
+export function getDirtyPaths(
+	form: BaseFormStore,
+	config?: GetFormDirtyPathsConfig | GetFieldDirtyPathsConfig<FormSchema, RequiredPath>,
+): RequiredPath[] {
+	// Collect paths of dirty fields via a single recursive walk, reading each
+	// field's own path instead of reconstructing it during the walk
+	const paths: RequiredPath[] = [];
+	collectDirtyPaths(
+		config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL],
+		paths,
+	);
+
+	// Return collected paths
+	return paths;
+}
+
+// @__NO_SIDE_EFFECTS__
+function collectDirtyPaths(internalFieldStore: InternalFieldStore, paths: RequiredPath[]): void {
+	// If field store is object with non-nullish input, recurse into children
+	if (internalFieldStore.kind === 'object' && internalFieldStore.input.value) {
+		// Hint: We skip a per-child `getFieldBool` pre-check because the
+		// recursion already prunes clean subtrees. Pre-checking would walk
+		// every dirty subtree twice.
+		const lengthBefore = paths.length;
+		for (const key in internalFieldStore.children) {
+			collectDirtyPaths(internalFieldStore.children[key], paths);
+		}
+
+		// If no descendant emitted a path but the object itself flipped dirty
+		// (e.g. transitioned from nullish to a non-nullish object), emit the
+		// object's own path so the change isn't silently dropped.
+		if (
+			paths.length === lengthBefore &&
+			internalFieldStore.isDirty.value &&
+			internalFieldStore.path.length > 0
+		) {
+			paths.push([...internalFieldStore.path] as unknown as RequiredPath);
+		}
+
+		// Otherwise, if field store is a value, emit its path if dirty
+	} else if (internalFieldStore.kind === 'value') {
+		if (internalFieldStore.isDirty.value && internalFieldStore.path.length > 0) {
+			paths.push([...internalFieldStore.path] as unknown as RequiredPath);
+		}
+
+		// Otherwise, field is atomic (array or cleared object) — emit its path
+		// if any dirty content exists
+	} else if (getFieldBool(internalFieldStore, 'isDirty') && internalFieldStore.path.length > 0) {
+		paths.push([...internalFieldStore.path] as unknown as RequiredPath);
+	}
+}

package/src/methods/getDirtyPaths/index.ts

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

package/src/methods/getErrors/getErrors.ts

@@ -0,0 +1,70 @@
+import {
+	type BaseFormStore,
+	type FormSchema,
+	getFieldStore,
+	INTERNAL,
+	type RequiredPath,
+	type ValidPath,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Get form errors config interface.
+ */
+export interface GetFormErrorsConfig {
+	/**
+	 * The path to a field. Leave undefined to get form-level errors.
+	 */
+	readonly path?: undefined;
+}
+
+/**
+ * Get field errors config interface.
+ */
+export interface GetFieldErrorsConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+	/**
+	 * The path to the field to retrieve errors from.
+	 */
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+
+/**
+ * Retrieves error messages from the form. When called without a config,
+ * returns form-level errors. When called with a path, returns errors for
+ * that specific field.
+ *
+ * @param form The form store to retrieve errors from.
+ *
+ * @returns A non-empty array of error messages, or null if no errors exist.
+ */
+export function getErrors<TSchema extends FormSchema>(
+	form: BaseFormStore<TSchema>,
+): [string, ...string[]] | null;
+
+/**
+ * Retrieves error messages from the form. When called without a config,
+ * returns form-level errors. When called with a path, returns errors for
+ * that specific field.
+ *
+ * @param form The form store to retrieve errors from.
+ * @param config The get errors configuration.
+ *
+ * @returns A non-empty array of error messages, or null if no errors exist.
+ */
+export function getErrors<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? GetFieldErrorsConfig<TSchema, TFieldPath>
+		: GetFormErrorsConfig,
+): [string, ...string[]] | null;
+
+// @__NO_SIDE_EFFECTS__
+export function getErrors(
+	form: BaseFormStore,
+	config?: GetFormErrorsConfig | GetFieldErrorsConfig<FormSchema, RequiredPath>,
+): [string, ...string[]] | null {
+	return (config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL]).errors.value;
+}

package/src/methods/getErrors/index.ts

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

package/src/methods/getInput/getInput.ts

@@ -0,0 +1,75 @@
+import {
+	type BaseFormStore,
+	type FormSchema,
+	getFieldInput,
+	getFieldStore,
+	INTERNAL,
+	type PartialValues,
+	type PathValue,
+	type RequiredPath,
+	type ValidPath,
+} from '../../core/index.ts';
+import type * as v from 'valibot';
+
+/**
+ * Get form input config interface.
+ */
+export interface GetFormInputConfig {
+	/**
+	 * The path to a field. Leave undefined to get the entire form input.
+	 */
+	readonly path?: undefined;
+}
+
+/**
+ * Get field input config interface.
+ */
+export interface GetFieldInputConfig<TSchema extends FormSchema, TFieldPath extends RequiredPath> {
+	/**
+	 * The path to the field to retrieve input from.
+	 */
+	readonly path: ValidPath<v.InferInput<TSchema>, TFieldPath>;
+}
+
+/**
+ * Retrieves the current input value of a specific field or the entire form.
+ * Returns a partial object as not all fields may have been set.
+ *
+ * @param form The form store to retrieve input from.
+ *
+ * @returns The partial input values of the form or the specified field.
+ */
+export function getInput<TSchema extends FormSchema>(
+	form: BaseFormStore<TSchema>,
+): PartialValues<v.InferInput<TSchema>>;
+
+/**
+ * Retrieves the current input value of a specific field or the entire form.
+ * Returns a partial object as not all fields may have been set.
+ *
+ * @param form The form store to retrieve input from.
+ * @param config The get input configuration.
+ *
+ * @returns The partial input values of the form or the specified field.
+ */
+export function getInput<
+	TSchema extends FormSchema,
+	TFieldPath extends RequiredPath | undefined = undefined,
+>(
+	form: BaseFormStore<TSchema>,
+	config: TFieldPath extends RequiredPath
+		? GetFieldInputConfig<TSchema, TFieldPath>
+		: GetFormInputConfig,
+): PartialValues<
+	TFieldPath extends RequiredPath
+		? PathValue<v.InferInput<TSchema>, TFieldPath>
+		: v.InferInput<TSchema>
+>;
+
+// @__NO_SIDE_EFFECTS__
+export function getInput(
+	form: BaseFormStore,
+	config?: GetFormInputConfig | GetFieldInputConfig<FormSchema, RequiredPath>,
+): unknown {
+	return getFieldInput(config?.path ? getFieldStore(form[INTERNAL], config.path) : form[INTERNAL]);
+}