@zeno-lib/forms 0.2.0 → 0.2.1

package/dist/create-zeno-form.d.mts

@@ -0,0 +1,118 @@
+import { ValidationMode } from "./lib/validation-modes.mjs";
+import { DeepKeys, FormAsyncValidateOrFn, FormOptions, FormValidateOrFn } from "@tanstack/react-form";
+import { ComponentProps, ReactNode } from "react";
+//#region src/create-zeno-form.d.ts
+type StandardSchema<T> = {
+  readonly "~standard": {
+    readonly validate: (value: unknown) => unknown;
+    readonly types?: {
+      readonly input: T;
+      readonly output: T;
+    };
+  };
+};
+type PartialFormData<T> = T extends readonly unknown[] ? T : T extends Date | RegExp | ((...args: never[]) => unknown) ? T : T extends object ? { [K in keyof T]?: PartialFormData<T[K]>; } : T;
+type ZenoFormExtras<TFormData> = {
+  /**
+   * If `true`, shipped fields skip rendering their inline `<FieldError>`
+   * message. Fields still flip `data-invalid` / `aria-invalid`.
+   */
+  hideFieldErrors?: boolean;
+  /**
+   * Show a `*` next to the label of every field the schema treats as required.
+   * Defaults to `true`. Required-ness is detected by probing the schema.
+   */
+  requiredIndicator?: boolean;
+  /**
+   * Warn the user before they navigate away with unsaved changes.
+   * `"if-changed"` (or `true`) warns while values differ from defaults;
+   * `"if-touched"` warns after any edit.
+   */
+  unsavedChangesWarning?: boolean | "if-changed" | "if-touched";
+  /**
+   * Initial values, relaxed to a deep partial so schema-provided defaults can
+   * be omitted. See `lib/schema-defaults.ts`.
+   */
+  defaultValues?: PartialFormData<TFormData>;
+};
+type SchemaPathExtras<TFormData> = {
+  schema: StandardSchema<TFormData>;
+  validators?: ValidationMode;
+  validationLogic?: never;
+};
+type ManualPathExtras = {
+  schema?: never;
+};
+type SchemaFormOptions<TFormData, TOnMount extends undefined | FormValidateOrFn<TFormData>, TOnChange extends undefined | FormValidateOrFn<TFormData>, TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnBlur extends undefined | FormValidateOrFn<TFormData>, TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnSubmit extends undefined | FormValidateOrFn<TFormData>, TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnDynamic extends undefined | FormValidateOrFn<TFormData>, TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>, TSubmitMeta> = Omit<FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>, "defaultValues" | "validators" | "validationLogic"> & SchemaPathExtras<TFormData> & ZenoFormExtras<TFormData>;
+type ManualFormOptions<TFormData, TOnMount extends undefined | FormValidateOrFn<TFormData>, TOnChange extends undefined | FormValidateOrFn<TFormData>, TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnBlur extends undefined | FormValidateOrFn<TFormData>, TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnSubmit extends undefined | FormValidateOrFn<TFormData>, TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnDynamic extends undefined | FormValidateOrFn<TFormData>, TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>, TSubmitMeta> = Omit<FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>, "defaultValues"> & ManualPathExtras & ZenoFormExtras<TFormData>;
+type UseFormOptions<TFormData, TOnMount extends undefined | FormValidateOrFn<TFormData>, TOnChange extends undefined | FormValidateOrFn<TFormData>, TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnBlur extends undefined | FormValidateOrFn<TFormData>, TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnSubmit extends undefined | FormValidateOrFn<TFormData>, TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnDynamic extends undefined | FormValidateOrFn<TFormData>, TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>, TSubmitMeta> = SchemaFormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta> | ManualFormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>;
+type FormDataOf<F> = F extends {
+  state: {
+    values: infer V;
+  };
+} ? V : never;
+type AnyAppForm = {
+  AppField: unknown;
+  state: {
+    values: unknown;
+  };
+};
+type AnyFieldValidators = {
+  onMount?: unknown;
+  onChange?: unknown;
+  onChangeAsync?: unknown;
+  onChangeAsyncDebounceMs?: number;
+  onBlur?: unknown;
+  onBlurAsync?: unknown;
+  onBlurAsyncDebounceMs?: number;
+  onSubmit?: unknown;
+  onSubmitAsync?: unknown;
+  onSubmitAsyncDebounceMs?: number;
+  onDynamic?: unknown;
+  onDynamicAsync?: unknown;
+};
+type AnyFieldListeners = {
+  onChange?: unknown;
+  onChangeDebounceMs?: number;
+  onBlur?: unknown;
+  onBlurDebounceMs?: number;
+  onMount?: unknown;
+  onSubmit?: unknown;
+};
+type WithValidators = {
+  validators?: AnyFieldValidators;
+  listeners?: AnyFieldListeners;
+};
+type AnyComponent = React.ComponentType<any>;
+type FieldWrappers<FC extends Record<string, AnyComponent>, T> = { [K in keyof FC]: <N extends DeepKeys<T>>(props: ComponentProps<FC[K]> & {
+  name: N;
+} & WithValidators) => ReactNode; };
+type CreateZenoFormConfig<FC extends Record<string, AnyComponent>, FMC extends Record<string, AnyComponent>> = {
+  fieldComponents: FC;
+  formComponents: FMC;
+};
+/**
+ * Build the wired Zeno form API from the caller's field + form components.
+ *
+ * The shadcn-style field components are dropped into the consumer's repo via the
+ * registry and injected here, so `@zeno-lib/forms` (npm) stays UI-free. Returns
+ * the `createFormHook` primitives plus the schema-aware `useForm` and the typed
+ * `useAppFields` wrappers (prop types are inferred from the injected components).
+ */
+declare function createZenoForm<FC extends Record<string, AnyComponent>, FMC extends Record<string, AnyComponent>>(config: CreateZenoFormConfig<FC, FMC>): {
+  useAppFields: <TForm extends AnyAppForm>(form: TForm) => FieldWrappers<FC, FormDataOf<TForm>>;
+  useAppForm: <TFormData, TOnMount extends undefined | FormValidateOrFn<TFormData>, TOnChange extends undefined | FormValidateOrFn<TFormData>, TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnBlur extends undefined | FormValidateOrFn<TFormData>, TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnSubmit extends undefined | FormValidateOrFn<TFormData>, TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnDynamic extends undefined | FormValidateOrFn<TFormData>, TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>, TSubmitMeta>(props: FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>) => import("@tanstack/react-form").AppFieldExtendedReactFormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta, FC, FMC>;
+  useForm: <TFormData, TOnMount extends undefined | FormValidateOrFn<TFormData> = undefined, TOnChange extends undefined | FormValidateOrFn<TFormData> = undefined, TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData> = undefined, TOnBlur extends undefined | FormValidateOrFn<TFormData> = undefined, TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData> = undefined, TOnSubmit extends undefined | FormValidateOrFn<TFormData> = undefined, TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData> = undefined, TOnDynamic extends undefined | FormValidateOrFn<TFormData> = undefined, TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData> = undefined, TOnServer extends undefined | FormAsyncValidateOrFn<TFormData> = undefined, TSubmitMeta = never>(options: UseFormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>) => import("@tanstack/react-form").FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta> & import("@tanstack/react-form").ReactFormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta> & NoInfer<FMC> & {
+    AppField: import("@tanstack/react-form").FieldComponent<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta, NoInfer<FC>>;
+    AppForm: import("react").ComponentType<import("react").PropsWithChildren<{}>>;
+  } & FieldWrappers<FC, FormDataOf<import("@tanstack/react-form").AppFieldExtendedReactFormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta, FC, FMC>>> & FMC;
+  withFieldGroup: <TFieldGroupData, TSubmitMeta, TRenderProps extends object = {}>({ render, props, defaultValues }: import("@tanstack/react-form").WithFieldGroupProps<TFieldGroupData, FC, FMC, TSubmitMeta, TRenderProps>) => <TFormData, TFields extends import("@tanstack/react-form").DeepKeysOfType<TFormData, TFieldGroupData | null | undefined> | import("@tanstack/react-form").FieldsMap<TFormData, TFieldGroupData>, TOnMount extends undefined | FormValidateOrFn<TFormData>, TOnChange extends undefined | FormValidateOrFn<TFormData>, TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnBlur extends undefined | FormValidateOrFn<TFormData>, TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnSubmit extends undefined | FormValidateOrFn<TFormData>, TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnDynamic extends undefined | FormValidateOrFn<TFormData>, TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>, TFormSubmitMeta>(params: import("react").PropsWithChildren<NoInfer<TRenderProps> & {
+    form: import("@tanstack/react-form").AppFieldExtendedReactFieldGroupApi<unknown, TFormData, string | import("@tanstack/react-form").FieldsMap<unknown, TFormData>, any, any, any, any, any, any, any, any, any, any, unknown extends TSubmitMeta ? TFormSubmitMeta : TSubmitMeta, FC, FMC> | import("@tanstack/react-form").AppFieldExtendedReactFormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, unknown extends TSubmitMeta ? TFormSubmitMeta : TSubmitMeta, FC, FMC>;
+    fields: TFields;
+  }>) => ReturnType<import("react").FunctionComponent>;
+  withForm: <TFormData, TOnMount extends undefined | FormValidateOrFn<TFormData>, TOnChange extends undefined | FormValidateOrFn<TFormData>, TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnBlur extends undefined | FormValidateOrFn<TFormData>, TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnSubmit extends undefined | FormValidateOrFn<TFormData>, TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnDynamic extends undefined | FormValidateOrFn<TFormData>, TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>, TSubmitMeta, TRenderProps extends object = {}>({ render, props }: import("@tanstack/react-form").WithFormProps<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta, FC, FMC, TRenderProps>) => import("react").FunctionComponent<import("react").PropsWithChildren<NoInfer<[unknown] extends [TRenderProps] ? any : TRenderProps> & {
+    form: import("@tanstack/react-form").AppFieldExtendedReactFormApi<[unknown] extends [TFormData] ? any : TFormData, [FormValidateOrFn<TFormData> | undefined] extends [TOnMount] ? [TOnMount] extends [TOnMount & (FormValidateOrFn<TFormData> | undefined)] ? any : TOnMount : TOnMount, [FormValidateOrFn<TFormData> | undefined] extends [TOnChange] ? [TOnChange] extends [TOnChange & (FormValidateOrFn<TFormData> | undefined)] ? any : TOnChange : TOnChange, [FormValidateOrFn<TFormData> | undefined] extends [TOnChangeAsync] ? [TOnChangeAsync] extends [TOnChangeAsync & (FormValidateOrFn<TFormData> | undefined)] ? any : TOnChangeAsync : TOnChangeAsync, [FormValidateOrFn<TFormData> | undefined] extends [TOnBlur] ? [TOnBlur] extends [TOnBlur & (FormValidateOrFn<TFormData> | undefined)] ? any : TOnBlur : TOnBlur, [FormValidateOrFn<TFormData> | undefined] extends [TOnBlurAsync] ? [TOnBlurAsync] extends [TOnBlurAsync & (FormValidateOrFn<TFormData> | undefined)] ? any : TOnBlurAsync : TOnBlurAsync, [FormValidateOrFn<TFormData> | undefined] extends [TOnSubmit] ? [TOnSubmit] extends [TOnSubmit & (FormValidateOrFn<TFormData> | undefined)] ? any : TOnSubmit : TOnSubmit, [FormValidateOrFn<TFormData> | undefined] extends [TOnSubmitAsync] ? [TOnSubmitAsync] extends [TOnSubmitAsync & (FormValidateOrFn<TFormData> | undefined)] ? any : TOnSubmitAsync : TOnSubmitAsync, [FormValidateOrFn<TFormData> | undefined] extends [TOnDynamic] ? [TOnDynamic] extends [TOnDynamic & (FormValidateOrFn<TFormData> | undefined)] ? any : TOnDynamic : TOnDynamic, [FormValidateOrFn<TFormData> | undefined] extends [TOnDynamicAsync] ? [TOnDynamicAsync] extends [TOnDynamicAsync & (FormValidateOrFn<TFormData> | undefined)] ? any : TOnDynamicAsync : TOnDynamicAsync, [FormValidateOrFn<TFormData> | undefined] extends [TOnServer] ? [TOnServer] extends [TOnServer & (FormValidateOrFn<TFormData> | undefined)] ? any : TOnServer : TOnServer, [unknown] extends [TSubmitMeta] ? any : TSubmitMeta, [unknown] extends [FC] ? any : FC, [unknown] extends [FMC] ? any : FMC>;
+  }>>;
+};
+//#endregion
+export { createZenoForm };

package/dist/create-zeno-form.mjs

@@ -0,0 +1,121 @@
+"use client";
+import { applyValidationError } from "./lib/apply-validation-error.mjs";
+import { fieldContext, formContext } from "./lib/contexts.mjs";
+import { deepMergeDefaults, extractZodDefaults } from "./lib/schema-defaults.mjs";
+import { getRequiredPaths } from "./lib/schema-required.mjs";
+import { useRebasedDefaultValues } from "./lib/use-rebased-default-values.mjs";
+import { useUnsavedChangesWarning } from "./lib/use-unsaved-changes-warning.mjs";
+import { ValidationError } from "./lib/validation-error.mjs";
+import { blurThenChangeLogic } from "./lib/validation-logic.mjs";
+import { DEFAULT_VALIDATION_MODE, setFormZenoState } from "./lib/validation-modes.mjs";
+import { createFormHook } from "@tanstack/react-form";
+import { useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/create-zeno-form.tsx
+function buildValidatorsFromSchema(schema, mode) {
+	switch (mode) {
+		case "blur": return { onBlur: schema };
+		case "submit": return { onSubmit: schema };
+		default: return { onChange: schema };
+	}
+}
+function withMountListener(listeners, onMount) {
+	const user = listeners?.onMount;
+	return {
+		...listeners,
+		onMount: (props) => {
+			onMount(props);
+			user?.(props);
+		}
+	};
+}
+/**
+* Build the wired Zeno form API from the caller's field + form components.
+*
+* The shadcn-style field components are dropped into the consumer's repo via the
+* registry and injected here, so `@zeno-lib/forms` (npm) stays UI-free. Returns
+* the `createFormHook` primitives plus the schema-aware `useForm` and the typed
+* `useAppFields` wrappers (prop types are inferred from the injected components).
+*/
+function createZenoForm(config) {
+	const { useAppForm, withFieldGroup, withForm } = createFormHook({
+		fieldComponents: config.fieldComponents,
+		fieldContext,
+		formComponents: config.formComponents,
+		formContext
+	});
+	function useAppFields(form) {
+		return useMemo(() => {
+			const Field = form.AppField;
+			const wrappers = {};
+			for (const key of Object.keys(config.fieldComponents)) {
+				const Impl = config.fieldComponents[key];
+				wrappers[key] = ({ name, validators, listeners, ...props }) => /* @__PURE__ */ jsx(Field, {
+					listeners,
+					name,
+					validators,
+					children: () => /* @__PURE__ */ jsx(Impl, { ...props })
+				});
+			}
+			return wrappers;
+		}, [form]);
+	}
+	function useForm(options) {
+		const { schema, validators: validatorsInput, validationLogic: userValidationLogic, hideFieldErrors = false, requiredIndicator = true, unsavedChangesWarning = false, defaultValues: userDefaultValues, onSubmit: userOnSubmit, ...rest } = options;
+		let schemaMode;
+		let resolvedValidators;
+		let resolvedValidationLogic;
+		if (schema === void 0) {
+			schemaMode = void 0;
+			resolvedValidators = typeof validatorsInput === "object" && validatorsInput !== null ? validatorsInput : void 0;
+			resolvedValidationLogic = userValidationLogic;
+		} else {
+			const mode = typeof validatorsInput === "string" ? validatorsInput : DEFAULT_VALIDATION_MODE;
+			schemaMode = mode;
+			resolvedValidators = buildValidatorsFromSchema(schema, mode);
+			resolvedValidationLogic = mode === "blur-then-change" ? blurThenChangeLogic : void 0;
+		}
+		const wrappedOnSubmit = userOnSubmit ? (async (props) => {
+			try {
+				await userOnSubmit(props);
+			} catch (error) {
+				if (error instanceof ValidationError) {
+					applyValidationError(props.formApi, error);
+					return;
+				}
+				throw error;
+			}
+		}) : void 0;
+		const requiredFields = useMemo(() => schema && requiredIndicator ? getRequiredPaths(schema) : /* @__PURE__ */ new Set(), [schema, requiredIndicator]);
+		const schemaDefaults = useMemo(() => schema ? extractZodDefaults(schema) : void 0, [schema]);
+		const mergedDefaultValues = useMemo(() => schemaDefaults ? deepMergeDefaults(schemaDefaults, userDefaultValues) : userDefaultValues, [schemaDefaults, userDefaultValues]);
+		const rebased = useRebasedDefaultValues(mergedDefaultValues);
+		const listeners = withMountListener(rest.listeners, rebased.onMount);
+		const form = useAppForm({
+			...rest,
+			listeners,
+			...rebased.defaultValues === void 0 ? {} : { defaultValues: rebased.defaultValues },
+			...wrappedOnSubmit ? { onSubmit: wrappedOnSubmit } : {},
+			...resolvedValidators ? { validators: resolvedValidators } : {},
+			...resolvedValidationLogic ? { validationLogic: resolvedValidationLogic } : {}
+		});
+		setFormZenoState(form, {
+			hideFieldErrors,
+			requiredFields,
+			requiredIndicator,
+			...schemaMode === void 0 ? {} : { validation: schemaMode }
+		});
+		useUnsavedChangesWarning(form, unsavedChangesWarning);
+		const fields = useAppFields(form);
+		return useMemo(() => Object.assign(form, fields, config.formComponents), [form, fields]);
+	}
+	return {
+		useAppFields,
+		useAppForm,
+		useForm,
+		withFieldGroup,
+		withForm
+	};
+}
+//#endregion
+export { createZenoForm };

package/dist/form-element.d.mts

@@ -0,0 +1,13 @@
+import { ComponentProps, ReactNode } from "react";
+//#region src/form-element.d.ts
+type FormProviderProps = {
+  children: ReactNode;
+  form: {
+    handleSubmit: () => unknown;
+  };
+};
+declare function FormProvider({ children, form }: FormProviderProps): import("react/jsx-runtime").JSX.Element;
+type FormProps = Omit<ComponentProps<"form">, "onSubmit">;
+declare function Form({ children, className, ...props }: FormProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
+export { Form, FormProvider };

package/dist/form-element.mjs

@@ -0,0 +1,31 @@
+"use client";
+import { FormProvider as FormProvider$1, useFormContext } from "./lib/contexts.mjs";
+import { jsx } from "react/jsx-runtime";
+//#region src/form-element.tsx
+function FormProvider({ children, form }) {
+	return /* @__PURE__ */ jsx(FormProvider$1, {
+		value: form,
+		children
+	});
+}
+function Form({ children, className, ...props }) {
+	const form = useFormContext();
+	return /* @__PURE__ */ jsx("form", {
+		className,
+		noValidate: true,
+		onSubmit: async (event) => {
+			event.preventDefault();
+			event.stopPropagation();
+			const node = event.currentTarget;
+			await Promise.resolve(form.handleSubmit()).catch(() => void 0);
+			if (!form.state.isValid) {
+				const invalid = node.querySelector("[aria-invalid=\"true\"]");
+				(invalid ? [invalid, ...invalid.querySelectorAll("*")] : []).find((el) => el.tabIndex >= 0)?.focus();
+			}
+		},
+		...props,
+		children
+	});
+}
+//#endregion
+export { Form, FormProvider };

package/dist/index.d.mts

@@ -0,0 +1,11 @@
+import { ValidationMode } from "./lib/validation-modes.mjs";
+import { createZenoForm } from "./create-zeno-form.mjs";
+import { Form, FormProvider } from "./form-element.mjs";
+import { ActionError, ActionIssue, ActionResult, toActionError, toFieldName } from "./lib/action-result.mjs";
+import { FieldMessage, ValidationError } from "./lib/validation-error.mjs";
+import { applyValidationError } from "./lib/apply-validation-error.mjs";
+import { useFieldContext, useFormContext } from "./lib/contexts.mjs";
+import { SubmitActionOptions, SubmitActionSchema, applyActionError, submitAction } from "./lib/submit-action.mjs";
+import { useHideFieldErrors, useIsFieldRequired, useIsInvalid } from "./lib/use-is-invalid.mjs";
+import { blurThenChangeLogic } from "./lib/validation-logic.mjs";
+export { type ActionError, type ActionIssue, type ActionResult, type FieldMessage, Form, FormProvider, type SubmitActionOptions, type SubmitActionSchema, ValidationError, type ValidationMode, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsInvalid };

package/dist/index.mjs

@@ -0,0 +1,10 @@
+import { applyValidationError } from "./lib/apply-validation-error.mjs";
+import { useFieldContext, useFormContext } from "./lib/contexts.mjs";
+import { ValidationError } from "./lib/validation-error.mjs";
+import { blurThenChangeLogic } from "./lib/validation-logic.mjs";
+import { createZenoForm } from "./create-zeno-form.mjs";
+import { Form, FormProvider } from "./form-element.mjs";
+import { toActionError, toFieldName } from "./lib/action-result.mjs";
+import { applyActionError, submitAction } from "./lib/submit-action.mjs";
+import { useHideFieldErrors, useIsFieldRequired, useIsInvalid } from "./lib/use-is-invalid.mjs";
+export { Form, FormProvider, ValidationError, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsInvalid };

package/dist/lib/action-result.d.mts

@@ -0,0 +1,22 @@
+//#region src/lib/action-result.d.ts
+type ActionError = {
+  readonly fieldErrors: Readonly<Record<string, readonly string[]>>;
+  readonly formErrors: readonly string[];
+};
+type ActionResult<TData> = {
+  readonly ok: true;
+  readonly data: TData;
+} | {
+  readonly ok: false;
+  readonly error: ActionError;
+};
+type ActionIssue = {
+  readonly message: string;
+  readonly path?: ReadonlyArray<PropertyKey | {
+    readonly key: PropertyKey;
+  }> | undefined;
+};
+declare function toFieldName(path: ActionIssue["path"]): string;
+declare function toActionError(issues: readonly ActionIssue[]): ActionError;
+//#endregion
+export { type ActionError, type ActionIssue, type ActionResult, toActionError, toFieldName };

package/dist/lib/action-result.mjs

@@ -0,0 +1,32 @@
+//#region src/lib/action-result.ts
+function toFieldName(path) {
+	let name = "";
+	for (const segment of path ?? []) {
+		const key = typeof segment === "object" ? segment.key : segment;
+		if (typeof key === "number") name += `[${key}]`;
+		else {
+			const part = typeof key === "symbol" ? key.description ?? "" : key;
+			name += name === "" ? part : `.${part}`;
+		}
+	}
+	return name;
+}
+function toActionError(issues) {
+	const fieldErrors = {};
+	const formErrors = [];
+	for (const issue of issues) {
+		const name = toFieldName(issue.path);
+		if (name === "") formErrors.push(issue.message);
+		else {
+			const messages = fieldErrors[name] ?? [];
+			messages.push(issue.message);
+			fieldErrors[name] = messages;
+		}
+	}
+	return {
+		fieldErrors,
+		formErrors
+	};
+}
+//#endregion
+export { toActionError, toFieldName };

package/dist/lib/apply-validation-error.d.mts

@@ -0,0 +1,6 @@
+import { ValidationError } from "./validation-error.mjs";
+import { AnyFormApi } from "@tanstack/react-form";
+//#region src/lib/apply-validation-error.d.ts
+declare function applyValidationError(formApi: AnyFormApi, error: ValidationError): void;
+//#endregion
+export { applyValidationError };

package/dist/lib/apply-validation-error.mjs

@@ -0,0 +1,41 @@
+//#region src/lib/apply-validation-error.ts
+function clearWhenEdited(formApi, name, entry) {
+	const rejected = formApi.getFieldValue(name);
+	const subscription = formApi.store.subscribe(() => {
+		if (formApi.getFieldMeta(name)?.errorMap?.onChange !== entry) {
+			subscription.unsubscribe();
+			return;
+		}
+		if (Object.is(formApi.getFieldValue(name), rejected)) return;
+		subscription.unsubscribe();
+		formApi.setFieldMeta(name, (prev) => ({
+			...prev,
+			errorMap: {
+				...prev.errorMap,
+				onChange: void 0
+			}
+		}));
+	});
+}
+function applyValidationError(formApi, error) {
+	for (const [name, message] of Object.entries(error.fields)) {
+		const errors = (Array.isArray(message) ? message : [message]).map((m) => ({ message: m }));
+		const entry = errors.length === 1 ? errors[0] : errors;
+		formApi.setFieldMeta(name, (prev) => ({
+			...prev,
+			errorMap: {
+				...prev.errorMap,
+				onChange: entry
+			},
+			errors,
+			isValid: false
+		}));
+		clearWhenEdited(formApi, name, entry);
+	}
+	if (error.formError) formApi.setErrorMap({ onSubmit: {
+		fields: {},
+		form: error.formError
+	} });
+}
+//#endregion
+export { applyValidationError };

package/dist/lib/aria.d.mts

@@ -0,0 +1,4 @@
+//#region src/lib/aria.d.ts
+declare function describedBy(...entries: [unknown, string][]): string | undefined;
+//#endregion
+export { describedBy };

package/dist/lib/aria.mjs

@@ -0,0 +1,7 @@
+//#region src/lib/aria.ts
+function describedBy(...entries) {
+	const ids = entries.filter(([show]) => Boolean(show)).map(([, id]) => id);
+	return ids.length > 0 ? ids.join(" ") : void 0;
+}
+//#endregion
+export { describedBy };

package/dist/lib/contexts.d.mts

@@ -0,0 +1,5 @@
+//#region src/lib/contexts.d.ts
+declare const fieldContext: import("react").Context<import("@tanstack/react-form").AnyFieldApi>, formContext: import("react").Context<import("@tanstack/react-form").AnyFormApi>, useFieldContext: <TData>() => import("@tanstack/react-form").FieldApi<any, string, TData, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any>, useFormContext: () => import("@tanstack/react-form").ReactFormExtendedApi<Record<string, never>, any, any, any, any, any, any, any, any, any, any, any>;
+declare const FormProvider: import("react").Provider<import("@tanstack/react-form").AnyFormApi>;
+//#endregion
+export { FormProvider, fieldContext, formContext, useFieldContext, useFormContext };

package/dist/lib/contexts.mjs

@@ -0,0 +1,7 @@
+"use client";
+import { createFormHookContexts } from "@tanstack/react-form";
+//#region src/lib/contexts.ts
+const { fieldContext, formContext, useFieldContext, useFormContext } = createFormHookContexts();
+const FormProvider = formContext.Provider;
+//#endregion
+export { FormProvider, fieldContext, formContext, useFieldContext, useFormContext };

package/dist/lib/formatted-number.d.mts

@@ -0,0 +1,56 @@
+//#region src/lib/formatted-number.d.ts
+type NumberSeparators = {
+  /** Thousands separator, e.g. `’` for `de-CH`, `,` for `en-US`. */
+  group: string;
+  /** Decimal separator, e.g. `.` for `de-CH`, `,` for `de-DE`. */
+  decimal: string;
+};
+type FormatNumberOptions = {
+  locale?: string;
+  /** Maximum digits after the decimal separator. `0` means integers only. */
+  maximumFractionDigits: number;
+  /** Minimum digits after the decimal separator (pads with zeros). */
+  minimumFractionDigits?: number;
+  /** Insert group (thousands) separators. Defaults to `true`. */
+  useGrouping?: boolean;
+};
+type TypedNumber = {
+  /** The re-formatted text to show in the input. */
+  text: string;
+  /** The parsed number, or `null` when the text holds no digits. */
+  value: number | null;
+};
+type ParseTypedOptions = {
+  locale?: string;
+  maximumFractionDigits: number;
+  useGrouping?: boolean;
+  allowNegative?: boolean;
+  /** Drop integer digits beyond this count (e.g. `4` for a year). */
+  maxIntegerDigits?: number;
+};
+declare function getNumberSeparators(locale?: string): NumberSeparators;
+/** Format a number for display (on blur, on reset, on first render). */
+declare function formatNumber(value: number | null | undefined, { locale, maximumFractionDigits, minimumFractionDigits, useGrouping }: FormatNumberOptions): string;
+/**
+ * Re-format what the user is typing. Only the locale's decimal separator
+ * starts the fraction; every other non-digit is dropped and group separators
+ * are re-inserted. Keeps a trailing decimal separator (`"12."`) so typing
+ * isn't fought, and truncates fraction digits beyond `maximumFractionDigits`.
+ */
+declare function parseTypedNumber(raw: string, { locale, maximumFractionDigits, useGrouping, allowNegative, maxIntegerDigits }: ParseTypedOptions): TypedNumber;
+/**
+ * Parse free-form text (pasted, or a value from another system) into a
+ * number. Tolerates currency codes and symbols, any whitespace or apostrophe
+ * as grouping, `.` or `,` as the decimal separator, and `−`/`-` for negatives.
+ * Returns `null` when no digits are found.
+ */
+declare function parseLocaleNumber(text: string, locale?: string): number | null;
+/**
+ * Where the caret should land in `next` after the user edited `raw` with the
+ * caret at `caret`.
+ */
+declare function mapCaret(raw: string, caret: number, next: string, locale?: string): number;
+/** Round to `digits` decimals without the `1.005 → 1.00` float surprise. */
+declare function roundTo(value: number, digits: number): number;
+//#endregion
+export { type FormatNumberOptions, type NumberSeparators, type ParseTypedOptions, type TypedNumber, formatNumber, getNumberSeparators, mapCaret, parseLocaleNumber, parseTypedNumber, roundTo };

package/dist/lib/formatted-number.mjs

@@ -0,0 +1,138 @@
+//#region src/lib/formatted-number.ts
+const separatorCache = /* @__PURE__ */ new Map();
+const MINUS_SIGNS = /[-−–]/;
+const LEADING_MINUS = /^[^\d]*[-−–]/;
+const NON_DIGIT = /\D/g;
+const LEADING_ZEROS = /^0+(?=\d)/;
+const DIGIT = /\d/;
+const DIGITS = /\d/g;
+const PARENTHESIZED = /^\s*\(.*\)\s*$/;
+const NOT_NUMERIC = /[^\d.,]/g;
+const UNICODE_MINUS = /\u2212/g;
+function getNumberSeparators(locale) {
+	const key = locale ?? "";
+	const cached = separatorCache.get(key);
+	if (cached) return cached;
+	const parts = new Intl.NumberFormat(locale, { numberingSystem: "latn" }).formatToParts(1234567.5);
+	const separators = {
+		decimal: parts.find((p) => p.type === "decimal")?.value ?? ".",
+		group: parts.find((p) => p.type === "group")?.value ?? ","
+	};
+	separatorCache.set(key, separators);
+	return separators;
+}
+function normalizeMinus(text) {
+	return text.replace(UNICODE_MINUS, "-");
+}
+/** Format a number for display (on blur, on reset, on first render). */
+function formatNumber(value, { locale, maximumFractionDigits, minimumFractionDigits = 0, useGrouping = true }) {
+	if (value == null || !Number.isFinite(value)) return "";
+	return normalizeMinus(new Intl.NumberFormat(locale, {
+		maximumFractionDigits,
+		minimumFractionDigits: Math.min(minimumFractionDigits, maximumFractionDigits),
+		numberingSystem: "latn",
+		useGrouping
+	}).format(value));
+}
+function groupIntegerDigits(digits, locale, useGrouping) {
+	if (!useGrouping || digits.length <= 3) return digits;
+	return new Intl.NumberFormat(locale, {
+		numberingSystem: "latn",
+		useGrouping: true
+	}).format(BigInt(digits));
+}
+function toNumber(negative, intDigits, fracDigits) {
+	if (intDigits === "" && fracDigits === "") return null;
+	const value = Number(`${intDigits || "0"}.${fracDigits || "0"}`);
+	return negative && value !== 0 ? -value : value;
+}
+/**
+* Re-format what the user is typing. Only the locale's decimal separator
+* starts the fraction; every other non-digit is dropped and group separators
+* are re-inserted. Keeps a trailing decimal separator (`"12."`) so typing
+* isn't fought, and truncates fraction digits beyond `maximumFractionDigits`.
+*/
+function parseTypedNumber(raw, { locale, maximumFractionDigits, useGrouping = true, allowNegative = true, maxIntegerDigits }) {
+	const { decimal } = getNumberSeparators(locale);
+	const negative = allowNegative && LEADING_MINUS.test(raw);
+	const decimalIndex = maximumFractionDigits > 0 ? raw.indexOf(decimal) : -1;
+	const intRaw = decimalIndex === -1 ? raw : raw.slice(0, decimalIndex);
+	const fracRaw = decimalIndex === -1 ? "" : raw.slice(decimalIndex + 1);
+	let intDigits = intRaw.replace(NON_DIGIT, "").replace(LEADING_ZEROS, "");
+	if (maxIntegerDigits !== void 0) intDigits = intDigits.slice(0, maxIntegerDigits);
+	const fracDigits = fracRaw.replace(NON_DIGIT, "").slice(0, maximumFractionDigits);
+	const hasDecimal = decimalIndex !== -1;
+	return {
+		text: `${negative ? "-" : ""}${intDigits === "" && hasDecimal ? "0" : groupIntegerDigits(intDigits, locale, useGrouping)}${hasDecimal ? `${decimal}${fracDigits}` : ""}`,
+		value: toNumber(negative, intDigits, fracDigits)
+	};
+}
+function detectDecimalSeparator(text, localeDecimal) {
+	const lastDot = text.lastIndexOf(".");
+	const lastComma = text.lastIndexOf(",");
+	if (lastDot !== -1 && lastComma !== -1) return lastDot > lastComma ? "." : ",";
+	let candidate = null;
+	if (lastDot !== -1) candidate = ".";
+	else if (lastComma !== -1) candidate = ",";
+	if (candidate === null) return null;
+	if (text.split(candidate).length - 1 > 1) return null;
+	if (candidate === localeDecimal) return candidate;
+	return (text.slice(text.lastIndexOf(candidate) + 1).match(DIGITS)?.length ?? 0) === 3 ? null : candidate;
+}
+/**
+* Parse free-form text (pasted, or a value from another system) into a
+* number. Tolerates currency codes and symbols, any whitespace or apostrophe
+* as grouping, `.` or `,` as the decimal separator, and `−`/`-` for negatives.
+* Returns `null` when no digits are found.
+*/
+function parseLocaleNumber(text, locale) {
+	if (!DIGIT.test(text)) return null;
+	const { decimal } = getNumberSeparators(locale);
+	const negative = LEADING_MINUS.test(text) || PARENTHESIZED.test(text);
+	const kept = text.replace(NOT_NUMERIC, "");
+	const decimalSeparator = detectDecimalSeparator(kept, decimal);
+	let intPart = kept;
+	let fracPart = "";
+	if (decimalSeparator) {
+		const index = kept.lastIndexOf(decimalSeparator);
+		intPart = kept.slice(0, index);
+		fracPart = kept.slice(index + 1);
+	}
+	return toNumber(negative, intPart.replace(NON_DIGIT, ""), fracPart.replace(NON_DIGIT, ""));
+}
+function countSignificant(text, end, decimal) {
+	let count = 0;
+	for (let i = 0; i < end && i < text.length; i++) {
+		const char = text[i];
+		if (DIGIT.test(char) || char === decimal || MINUS_SIGNS.test(char)) count++;
+	}
+	return count;
+}
+function caretForSignificant(text, significant, decimal) {
+	if (significant <= 0) return 0;
+	let count = 0;
+	for (let i = 0; i < text.length; i++) {
+		const char = text[i];
+		if (DIGIT.test(char) || char === decimal || char === "-") {
+			count++;
+			if (count === significant) return i + 1;
+		}
+	}
+	return text.length;
+}
+/**
+* Where the caret should land in `next` after the user edited `raw` with the
+* caret at `caret`.
+*/
+function mapCaret(raw, caret, next, locale) {
+	const { decimal } = getNumberSeparators(locale);
+	return caretForSignificant(next, countSignificant(raw, caret, decimal), decimal);
+}
+/** Round to `digits` decimals without the `1.005 → 1.00` float surprise. */
+function roundTo(value, digits) {
+	const factor = 10 ** digits;
+	const rounded = Math.round((Math.abs(value) + Number.EPSILON) * factor);
+	return Math.sign(value) * rounded / factor;
+}
+//#endregion
+export { formatNumber, getNumberSeparators, mapCaret, parseLocaleNumber, parseTypedNumber, roundTo };