@zeno-lib/forms 0.2.0 → 0.2.1

package/dist/lib/schema-defaults.d.mts

@@ -0,0 +1,17 @@
+//#region src/lib/schema-defaults.d.ts
+type SchemaNode = {
+  readonly _zod?: {
+    readonly def?: SchemaDef;
+  };
+};
+type SchemaDef = {
+  readonly type?: string;
+  readonly innerType?: SchemaNode;
+  readonly shape?: Record<string, SchemaNode>;
+  readonly in?: SchemaNode;
+  readonly defaultValue?: unknown;
+};
+declare function extractZodDefaults(schema: SchemaNode): Record<string, unknown>;
+declare function deepMergeDefaults(schemaDefaults: Record<string, unknown>, userDefaults: Record<string, unknown> | undefined): Record<string, unknown>;
+//#endregion
+export { deepMergeDefaults, extractZodDefaults };

package/dist/lib/schema-defaults.mjs

@@ -0,0 +1,75 @@
+//#region src/lib/schema-defaults.ts
+const MAX_WRAPPER_DEPTH = 16;
+function getDef(node) {
+	return node?._zod?.def;
+}
+function extractDefaultForField(node) {
+	let current = node;
+	for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth++) {
+		const def = getDef(current);
+		if (!def?.type) return { ok: false };
+		switch (def.type) {
+			case "default":
+			case "prefault": return {
+				ok: true,
+				value: def.defaultValue
+			};
+			case "optional":
+			case "nullable":
+			case "nonoptional":
+			case "readonly":
+				current = def.innerType;
+				continue;
+			case "pipe":
+				current = def.in;
+				continue;
+			case "string": return {
+				ok: true,
+				value: ""
+			};
+			case "array": return {
+				ok: true,
+				value: []
+			};
+			case "object": {
+				const nested = current ? extractZodDefaults(current) : {};
+				return Object.keys(nested).length > 0 ? {
+					ok: true,
+					value: nested
+				} : { ok: false };
+			}
+			default: return { ok: false };
+		}
+	}
+	return { ok: false };
+}
+function extractZodDefaults(schema) {
+	try {
+		const def = getDef(schema);
+		if (def?.type !== "object" || !def.shape) return {};
+		const result = {};
+		for (const [key, field] of Object.entries(def.shape)) {
+			const extracted = extractDefaultForField(field);
+			if (extracted.ok) result[key] = extracted.value;
+		}
+		return result;
+	} catch {
+		return {};
+	}
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+}
+function deepMergeDefaults(schemaDefaults, userDefaults) {
+	if (!userDefaults) return schemaDefaults;
+	const result = { ...schemaDefaults };
+	for (const key of Object.keys(userDefaults)) {
+		const userValue = userDefaults[key];
+		const schemaValue = schemaDefaults[key];
+		if (isPlainObject(schemaValue) && isPlainObject(userValue)) result[key] = deepMergeDefaults(schemaValue, userValue);
+		else result[key] = userValue;
+	}
+	return result;
+}
+//#endregion
+export { deepMergeDefaults, extractZodDefaults };

package/dist/lib/schema-required.d.mts

@@ -0,0 +1,25 @@
+//#region src/lib/schema-required.d.ts
+type PathPart = PropertyKey | {
+  readonly key: PropertyKey;
+};
+type StandardIssue = {
+  readonly path?: readonly PathPart[];
+  readonly expected?: unknown;
+};
+type StandardSchemaLike = {
+  readonly "~standard": {
+    readonly validate: (value: unknown) => {
+      readonly value: unknown;
+    } | {
+      readonly issues: readonly StandardIssue[];
+    } | Promise<unknown>;
+  };
+};
+/**
+ * Normalise a field name (`members[3].name` or `members.3.name`) to the key
+ * `getRequiredPaths` records (`members[0].name`).
+ */
+declare function toRequiredPathKey(name: string): string;
+declare function getRequiredPaths(schema: StandardSchemaLike): Set<string>;
+//#endregion
+export { type StandardSchemaLike, getRequiredPaths, toRequiredPathKey };

package/dist/lib/schema-required.mjs

@@ -0,0 +1,72 @@
+//#region src/lib/schema-required.ts
+const MAX_PROBE_DEPTH = 8;
+const INDEX_SEGMENT = /^\d+$/;
+const INDEX_IN_NAME = /\[\d+\]|\.(\d+)(?=\.|\[|$)/g;
+function pathKey(part) {
+	if (typeof part === "object" && part !== null && "key" in part) return part.key;
+	return part;
+}
+function isIndex(key) {
+	return typeof key === "number" || typeof key === "string" && INDEX_SEGMENT.test(key);
+}
+function joinPath(keys) {
+	let out = "";
+	for (const key of keys) if (isIndex(key)) out += "[0]";
+	else out += out === "" ? String(key) : `.${String(key)}`;
+	return out;
+}
+/**
+* Normalise a field name (`members[3].name` or `members.3.name`) to the key
+* `getRequiredPaths` records (`members[0].name`).
+*/
+function toRequiredPathKey(name) {
+	return name.replace(INDEX_IN_NAME, "[0]");
+}
+function probeContainer(expected) {
+	if (typeof expected !== "string") return;
+	const kind = expected.toLowerCase();
+	if (kind === "object") return {};
+	if (kind === "array") return [{}];
+}
+function fillAt(root, keys, value) {
+	let node = root;
+	for (const key of keys.slice(0, -1)) {
+		const next = node[key];
+		if (typeof next !== "object" || next === null) return false;
+		node = next;
+	}
+	const last = keys.at(-1);
+	if (node[last] !== void 0) return false;
+	node[last] = value;
+	return true;
+}
+function validateSync(schema, value) {
+	let result;
+	try {
+		result = schema["~standard"].validate(value);
+	} catch {
+		return;
+	}
+	if (result instanceof Promise) return;
+	return "issues" in result && result.issues ? result.issues : [];
+}
+function getRequiredPaths(schema) {
+	const required = /* @__PURE__ */ new Set();
+	const probe = {};
+	for (let depth = 0; depth < MAX_PROBE_DEPTH; depth++) {
+		const issues = validateSync(schema, probe);
+		if (!issues) return required;
+		let descended = false;
+		for (const issue of issues) {
+			const keys = issue.path?.map(pathKey) ?? [];
+			if (keys.length === 0) continue;
+			required.add(joinPath(keys));
+			const container = probeContainer(issue.expected);
+			if (container !== void 0 && fillAt(probe, keys, container)) descended = true;
+		}
+		if (!descended) break;
+	}
+	return required;
+}
+//#endregion
+export { getRequiredPaths, toRequiredPathKey };

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

@@ -0,0 +1,64 @@
+import { ActionError, ActionIssue, ActionResult } from "./action-result.mjs";
+import { AnyFormApi } from "@tanstack/react-form";
+//#region src/lib/submit-action.d.ts
+declare function applyActionError(formApi: FormApiLike, error: ActionError): void;
+type SchemaResult<TOutput> = {
+  readonly value: TOutput;
+  readonly issues?: undefined;
+} | {
+  readonly issues: readonly ActionIssue[];
+};
+type SubmitActionSchema<TOutput> = {
+  readonly "~standard": {
+    readonly validate: (value: unknown) => SchemaResult<TOutput> | Promise<SchemaResult<TOutput>>;
+    readonly types?: {
+      readonly input: unknown;
+      readonly output: TOutput;
+    } | undefined;
+  };
+};
+type FormApiLike = Pick<AnyFormApi, "fieldInfo" | "getFieldMeta" | "getFieldValue" | "setErrorMap" | "setFieldMeta" | "store">;
+type SubmitProps<TValues> = {
+  readonly value: TValues;
+  readonly formApi: FormApiLike & {
+    reset: (values?: TValues, opts?: {
+      keepDefaultValues?: boolean;
+    }) => void;
+  };
+};
+type Action<TInput, TData> = (input: TInput) => Promise<ActionResult<TData>>;
+type ResetOption<TValues, TData> = "values" | ((data: TData) => TValues) | ([TData] extends [TValues] ? true : never);
+type SubmitActionOptions<TValues, TData> = {
+  /**
+   * After a successful action, `formApi.reset(...)` so the saved values
+   * become the pristine baseline (clears `isDirty` and the unsaved-changes
+   * warning). Off by default.
+   */
+  reset?: ResetOption<TValues, TData>;
+};
+type SubmitActionSchemaOptions<TValues, TOutput, TData> = SubmitActionOptions<TValues, TData> & {
+  /**
+   * Parsed on the client before the call: `onSubmit` receives the form's
+   * input values, and the action gets the schema's output. A failure is
+   * applied to the form and the action is never called.
+   */
+  schema: SubmitActionSchema<TOutput>;
+};
+/**
+ * Call a server action from `onSubmit` and route its result back into the
+ * form. Pass `onSubmit`'s own argument straight through:
+ *
+ * ```ts
+ * onSubmit: (submit) => submitAction(submit, saveProfile, { reset: true, schema })
+ * ```
+ *
+ * On `{ ok: false }` the field errors land on their fields (array paths like
+ * `owners[0].percentage` included) and clear as each field is edited. On
+ * `{ ok: true }` the form is optionally reset. Either way the result is
+ * returned, so the caller can redirect or toast on `result.ok`. A thrown
+ * error (network, auth, a bug) propagates unchanged.
+ */
+declare function submitAction<TValues, TOutput, TData>(props: SubmitProps<TValues>, action: Action<TOutput, TData>, options: SubmitActionSchemaOptions<TValues, TOutput, TData>): Promise<ActionResult<TData>>;
+declare function submitAction<TValues, TData>(props: SubmitProps<TValues>, action: Action<NoInfer<TValues>, TData>, options?: SubmitActionOptions<TValues, TData>): Promise<ActionResult<TData>>;
+//#endregion
+export { type FormApiLike, type SubmitActionOptions, type SubmitActionSchema, applyActionError, submitAction };

package/dist/lib/submit-action.mjs

@@ -0,0 +1,43 @@
+import { applyValidationError } from "./apply-validation-error.mjs";
+import { ValidationError } from "./validation-error.mjs";
+import { toActionError } from "./action-result.mjs";
+//#region src/lib/submit-action.ts
+function applyActionError(formApi, error) {
+	const fields = {};
+	const formErrors = [...error.formErrors];
+	const fieldInfo = formApi.fieldInfo;
+	for (const [name, messages] of Object.entries(error.fieldErrors)) {
+		if (messages.length === 0) continue;
+		if (fieldInfo[name]?.instance) fields[name] = messages;
+		else formErrors.push(...messages);
+	}
+	applyValidationError(formApi, new ValidationError(fields, formErrors.length > 0 ? { formError: formErrors.join("\n") } : {}));
+}
+async function submitAction(props, action, options = {}) {
+	const { formApi, value } = props;
+	let input = value;
+	if (options.schema) {
+		const parsed = await options.schema["~standard"].validate(value);
+		if (parsed.issues) {
+			const error = toActionError(parsed.issues);
+			applyActionError(formApi, error);
+			return {
+				error,
+				ok: false
+			};
+		}
+		input = parsed.value;
+	}
+	const result = await action(input);
+	if (!result.ok) {
+		applyActionError(formApi, result.error);
+		return result;
+	}
+	const { reset } = options;
+	if (reset === true) formApi.reset(result.data);
+	else if (reset === "values") formApi.reset(value);
+	else if (typeof reset === "function") formApi.reset(reset(result.data));
+	return result;
+}
+//#endregion
+export { applyActionError, submitAction };

package/dist/lib/use-form-dialog.d.mts

@@ -0,0 +1,73 @@
+//#region src/lib/use-form-dialog.d.ts
+type FormDialogOpenOptions<TValues> = {
+  /**
+   * Values to edit in this session. Omit to start from the hook's
+   * `defaultValues` (a blank "create" form).
+   */
+  defaultValues?: TValues;
+  /** Field `name` to focus once the dialog opens, e.g. `"email"`. */
+  focus?: string;
+};
+type UseFormDialogOptions<TValues> = {
+  /** Values a session starts from when `open()` gets none. */
+  defaultValues?: TValues;
+};
+type FormDialogController<TValues> = {
+  /** Whether the dialog is open. */
+  isOpen: boolean;
+  /** Open a new editing session, optionally with its own values and focus. */
+  open: (options?: FormDialogOpenOptions<TValues>) => void;
+  /**
+   * Close without the unsaved-changes prompt. Close affordances inside the
+   * dialog (Cancel, ×, Escape, outside press) go through the guard instead.
+   */
+  close: () => void;
+  /**
+   * The current session's defaults. Pass them to `useForm({ defaultValues })`
+   * so the form's defaults follow the session (see the pitfall below).
+   */
+  defaultValues: TValues | undefined;
+  /** Field to focus when the current session opened. */
+  focus: string | undefined;
+  /** Increments on every `open()`; lets the dialog reset once per session. */
+  session: number;
+};
+/**
+ * Open/close state for a dialog-hosted form, one "session" per `open()`.
+ *
+ * Why the hook owns the defaults: TanStack Form ignores new `defaultValues`
+ * once the form is touched, and a `form.reset(values)` is undone on the next
+ * render when `useForm` still receives the old `defaultValues` (the form is
+ * untouched again after the reset, so TanStack re-applies its options).
+ * Passing `dialog.defaultValues` to `useForm` keeps the two in agreement;
+ * the `FormDialog` component then calls `form.reset(defaults)` at the start
+ * of every session.
+ */
+declare function useFormDialog<TValues>(options?: UseFormDialogOptions<TValues>): FormDialogController<TValues>;
+type UseLeaveGuardOptions = {
+  /** Whether leaving now would lose changes. */
+  hasUnsavedChanges: boolean;
+};
+type LeaveGuard = {
+  /**
+   * Run `proceed` now when there's nothing to lose, otherwise hold it until
+   * the user confirms. A newer request replaces a held one.
+   */
+  requestLeave: (proceed: () => void) => void;
+  /** Whether a leave is waiting on the user's answer (show your confirm UI). */
+  isConfirming: boolean;
+  /** The user chose to discard: run the held leave. */
+  confirmLeave: () => void;
+  /** The user chose to stay: drop the held leave. */
+  cancelLeave: () => void;
+};
+/** Ask before a leave (close, navigate, switch record) drops unsaved changes. */
+declare function useLeaveGuard({ hasUnsavedChanges }: UseLeaveGuardOptions): LeaveGuard;
+/**
+ * Find the element to focus for field `name` inside `root`: the control with
+ * `id={name}` (what the shipped fields render), else the first focusable
+ * element inside the field root marked `data-field={name}`.
+ */
+declare function findFieldElement(root: ParentNode | null | undefined, name: string): HTMLElement | null;
+//#endregion
+export { type FormDialogController, type FormDialogOpenOptions, type LeaveGuard, type UseFormDialogOptions, type UseLeaveGuardOptions, findFieldElement, useFormDialog, useLeaveGuard };

package/dist/lib/use-form-dialog.mjs

@@ -0,0 +1,90 @@
+"use client";
+import { useCallback, useRef, useState } from "react";
+//#region src/lib/use-form-dialog.ts
+/**
+* Open/close state for a dialog-hosted form, one "session" per `open()`.
+*
+* Why the hook owns the defaults: TanStack Form ignores new `defaultValues`
+* once the form is touched, and a `form.reset(values)` is undone on the next
+* render when `useForm` still receives the old `defaultValues` (the form is
+* untouched again after the reset, so TanStack re-applies its options).
+* Passing `dialog.defaultValues` to `useForm` keeps the two in agreement;
+* the `FormDialog` component then calls `form.reset(defaults)` at the start
+* of every session.
+*/
+function useFormDialog(options = {}) {
+	const latestDefaults = useRef(options.defaultValues);
+	latestDefaults.current = options.defaultValues;
+	const [state, setState] = useState(() => ({
+		defaultValues: options.defaultValues,
+		focus: void 0,
+		isOpen: false,
+		session: 0
+	}));
+	const open = useCallback((openOptions) => {
+		setState((previous) => ({
+			defaultValues: openOptions?.defaultValues ?? latestDefaults.current,
+			focus: openOptions?.focus,
+			isOpen: true,
+			session: previous.session + 1
+		}));
+	}, []);
+	return {
+		close: useCallback(() => {
+			setState((previous) => previous.isOpen ? {
+				...previous,
+				isOpen: false
+			} : previous);
+		}, []),
+		defaultValues: state.defaultValues,
+		focus: state.focus,
+		isOpen: state.isOpen,
+		open,
+		session: state.session
+	};
+}
+/** Ask before a leave (close, navigate, switch record) drops unsaved changes. */
+function useLeaveGuard({ hasUnsavedChanges }) {
+	const pending = useRef(null);
+	const [isConfirming, setIsConfirming] = useState(false);
+	const requestLeave = useCallback((proceed) => {
+		if (!hasUnsavedChanges) {
+			proceed();
+			return;
+		}
+		pending.current = proceed;
+		setIsConfirming(true);
+	}, [hasUnsavedChanges]);
+	const confirmLeave = useCallback(() => {
+		const proceed = pending.current;
+		pending.current = null;
+		setIsConfirming(false);
+		proceed?.();
+	}, []);
+	return {
+		cancelLeave: useCallback(() => {
+			pending.current = null;
+			setIsConfirming(false);
+		}, []),
+		confirmLeave,
+		isConfirming,
+		requestLeave
+	};
+}
+const FOCUSABLE = "input:not([type=\"hidden\"]):not([disabled]), textarea:not([disabled]), select:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";
+function attributeSelector(attribute, value) {
+	return `[${attribute}="${value.replace(/["\\]/g, "\\$&")}"]`;
+}
+/**
+* Find the element to focus for field `name` inside `root`: the control with
+* `id={name}` (what the shipped fields render), else the first focusable
+* element inside the field root marked `data-field={name}`.
+*/
+function findFieldElement(root, name) {
+	if (!root) return null;
+	const byId = root.querySelector(attributeSelector("id", name));
+	if (byId) return byId;
+	return root.querySelector(attributeSelector("data-field", name))?.querySelector(FOCUSABLE) ?? null;
+}
+//#endregion
+export { findFieldElement, useFormDialog, useLeaveGuard };

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

@@ -0,0 +1,61 @@
+import { ChangeEvent, ClipboardEvent } from "react";
+//#region src/lib/use-formatted-number.d.ts
+type UseFormattedNumberOptions = {
+  /** The stored value. `null`/`undefined` renders an empty input. */
+  value: number | null | undefined;
+  /** Called with the parsed value when the user types, pastes, or blurs. */
+  onValueChange: (value: number | null) => void;
+  /** Called after the blur re-format (wire the field's `handleBlur` here). */
+  onBlur?: () => void;
+  /** BCP 47 locale for separators. Defaults to the runtime locale. */
+  locale?: string;
+  /** Digits allowed after the decimal separator. Defaults to `2`. */
+  maximumFractionDigits?: number;
+  /**
+   * Pad a non-integer value to `maximumFractionDigits` on blur (`12.5` →
+   * `12.50`). Integers stay bare (`12`). Defaults to `false`.
+   */
+  padFraction?: boolean;
+  /** Insert thousands separators. Defaults to `true`. */
+  useGrouping?: boolean;
+  /** Accept a leading minus. Defaults to `true`. */
+  allowNegative?: boolean;
+  /** Drop integer digits beyond this count while typing. */
+  maxIntegerDigits?: number;
+  /** Clamp the stored value on blur. */
+  min?: number;
+  /** Clamp the stored value on blur. */
+  max?: number;
+  /**
+   * Map the stored value to the number shown in the input, e.g.
+   * `(v) => v * 100` to edit a `0–1` fraction as a percentage. Pair with
+   * `fromDisplay`.
+   */
+  toDisplay?: (value: number) => number;
+  /** Inverse of `toDisplay`. */
+  fromDisplay?: (display: number) => number;
+};
+type FormattedNumberInputProps = {
+  inputMode: "decimal" | "numeric";
+  onBlur: () => void;
+  onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+  onPaste: (event: ClipboardEvent<HTMLInputElement>) => void;
+  type: "text";
+  value: string;
+};
+/**
+ * Headless, locale-aware formatted number input.
+ *
+ * Keeps the input's text in local state so the user can type freely
+ * (`"1’2"`, `"12."`), re-inserting group separators as they type while
+ * holding the caret in place, and parses the text into a `number | null`
+ * for the form. Pasted text is parsed leniently (`"CHF 1'234.50"`,
+ * `"1.234,50"`). On blur the value is clamped to `min`/`max` and the text
+ * re-formatted. External value changes (e.g. `form.reset`) re-sync the text.
+ *
+ * Returns props to spread on an `<input>`; UI-free, so any input component
+ * can use it.
+ */
+declare function useFormattedNumber({ value, onValueChange, onBlur, locale, maximumFractionDigits, padFraction, useGrouping, allowNegative, maxIntegerDigits, min, max, toDisplay, fromDisplay }: UseFormattedNumberOptions): FormattedNumberInputProps;
+//#endregion
+export { type FormattedNumberInputProps, type UseFormattedNumberOptions, useFormattedNumber };

package/dist/lib/use-formatted-number.mjs

@@ -0,0 +1,104 @@
+"use client";
+import { formatNumber, mapCaret, parseLocaleNumber, parseTypedNumber, roundTo } from "./formatted-number.mjs";
+import { useLayoutEffect, useReducer, useRef, useState } from "react";
+//#region src/lib/use-formatted-number.ts
+const identity = (value) => value;
+function clamp(value, min, max) {
+	let next = value;
+	if (min !== void 0 && next < min) next = min;
+	if (max !== void 0 && next > max) next = max;
+	return next;
+}
+/**
+* Headless, locale-aware formatted number input.
+*
+* Keeps the input's text in local state so the user can type freely
+* (`"1’2"`, `"12."`), re-inserting group separators as they type while
+* holding the caret in place, and parses the text into a `number | null`
+* for the form. Pasted text is parsed leniently (`"CHF 1'234.50"`,
+* `"1.234,50"`). On blur the value is clamped to `min`/`max` and the text
+* re-formatted. External value changes (e.g. `form.reset`) re-sync the text.
+*
+* Returns props to spread on an `<input>`; UI-free, so any input component
+* can use it.
+*/
+function useFormattedNumber({ value, onValueChange, onBlur, locale, maximumFractionDigits = 2, padFraction = false, useGrouping = true, allowNegative = true, maxIntegerDigits, min, max, toDisplay = identity, fromDisplay = identity }) {
+	const current = value ?? null;
+	const display = (stored) => {
+		if (stored === null) return "";
+		const shown = roundTo(toDisplay(stored), maximumFractionDigits);
+		return formatNumber(shown, {
+			locale,
+			maximumFractionDigits,
+			minimumFractionDigits: padFraction && !Number.isInteger(shown) ? maximumFractionDigits : 0,
+			useGrouping
+		});
+	};
+	const [text, setText] = useState(() => display(current));
+	const [synced, setSynced] = useState(current);
+	if (!Object.is(current, synced)) {
+		setSynced(current);
+		setText(display(current));
+	}
+	const [, forceRender] = useReducer((n) => n + 1, 0);
+	const pendingCaret = useRef(null);
+	useLayoutEffect(() => {
+		const pending = pendingCaret.current;
+		if (!pending) return;
+		pendingCaret.current = null;
+		if (pending.input.ownerDocument.activeElement === pending.input) pending.input.setSelectionRange(pending.at, pending.at);
+	});
+	const fromDisplayRounded = (shown) => fromDisplay === identity ? shown : roundTo(fromDisplay(shown), maximumFractionDigits + 4);
+	const commit = (nextText, nextValue) => {
+		setText(nextText);
+		setSynced(nextValue);
+		if (!Object.is(nextValue, current)) onValueChange(nextValue);
+	};
+	const onChange = (event) => {
+		const input = event.target;
+		const raw = input.value;
+		const typed = parseTypedNumber(raw, {
+			allowNegative,
+			locale,
+			maxIntegerDigits,
+			maximumFractionDigits,
+			useGrouping
+		});
+		const caret = input.selectionStart ?? raw.length;
+		pendingCaret.current = {
+			at: mapCaret(raw, caret, typed.text, locale),
+			input
+		};
+		commit(typed.text, typed.value === null ? null : fromDisplayRounded(typed.value));
+		forceRender();
+	};
+	const onPaste = (event) => {
+		const input = event.currentTarget;
+		if (!(input.value === "" || input.selectionStart === 0 && input.selectionEnd === input.value.length)) return;
+		const parsed = parseLocaleNumber(event.clipboardData.getData("text"), locale);
+		if (parsed === null) return;
+		const shown = roundTo(allowNegative ? parsed : Math.abs(parsed), maximumFractionDigits);
+		if (maxIntegerDigits !== void 0 && Math.abs(Math.trunc(shown)) >= 10 ** maxIntegerDigits) return;
+		event.preventDefault();
+		const stored = fromDisplayRounded(shown);
+		commit(display(stored), stored);
+	};
+	const handleBlur = () => {
+		if (current === null) setText("");
+		else {
+			const clamped = clamp(current, min, max);
+			commit(display(clamped), clamped);
+		}
+		onBlur?.();
+	};
+	return {
+		inputMode: maximumFractionDigits > 0 ? "decimal" : "numeric",
+		onBlur: handleBlur,
+		onChange,
+		onPaste,
+		type: "text",
+		value: text
+	};
+}
+//#endregion
+export { useFormattedNumber };

package/dist/lib/use-is-invalid.d.mts

@@ -0,0 +1,7 @@
+import { AnyFieldApi } from "@tanstack/react-form";
+//#region src/lib/use-is-invalid.d.ts
+declare function useIsInvalid(field: AnyFieldApi): boolean;
+declare function useHideFieldErrors(field: AnyFieldApi): boolean;
+declare function useIsFieldRequired(field: AnyFieldApi): boolean;
+//#endregion
+export { useHideFieldErrors, useIsFieldRequired, useIsInvalid };

package/dist/lib/use-is-invalid.mjs

@@ -0,0 +1,31 @@
+"use client";
+import { getFormHideFieldErrors, getFormValidationMode, isFieldRequired } from "./validation-modes.mjs";
+import { useSelector } from "@tanstack/react-form";
+//#region src/lib/use-is-invalid.ts
+function hasFieldLevelError(errorMap, errorSourceMap, cause) {
+	if (!(errorMap && errorSourceMap)) return false;
+	return errorSourceMap[cause] === "field" && errorMap[cause] !== void 0;
+}
+function modeAllowsDisplay(mode, isDirty, isBlurred, wasSubmitted) {
+	if (mode === "change") return isDirty || wasSubmitted;
+	if (mode === "submit") return wasSubmitted;
+	return isBlurred || wasSubmitted;
+}
+function useIsInvalid(field) {
+	const wasSubmitted = useSelector(field.form.store, (state) => state.submissionAttempts > 0);
+	if (field.state.meta.isValid) return false;
+	const { isDirty, isBlurred, errorMap, errorSourceMap } = field.state.meta;
+	const sourceMap = errorSourceMap;
+	if (hasFieldLevelError(errorMap, sourceMap, "onChange")) return isDirty || wasSubmitted;
+	if (hasFieldLevelError(errorMap, sourceMap, "onBlur")) return isBlurred || wasSubmitted;
+	if (hasFieldLevelError(errorMap, sourceMap, "onSubmit")) return wasSubmitted;
+	return modeAllowsDisplay(getFormValidationMode(field.form), isDirty, isBlurred, wasSubmitted);
+}
+function useHideFieldErrors(field) {
+	return getFormHideFieldErrors(field.form);
+}
+function useIsFieldRequired(field) {
+	return isFieldRequired(field.form, field.name);
+}
+//#endregion
+export { useHideFieldErrors, useIsFieldRequired, useIsInvalid };

package/dist/lib/use-rebased-default-values.d.mts

@@ -0,0 +1,10 @@
+import { AnyFormApi } from "@tanstack/react-form";
+//#region src/lib/use-rebased-default-values.d.ts
+declare function useRebasedDefaultValues<T>(callerDefaults: T): {
+  defaultValues: T;
+  onMount: (props: {
+    formApi: AnyFormApi;
+  }) => void;
+};
+//#endregion
+export { useRebasedDefaultValues };