@zeno-lib/forms 0.6.0 → 0.7.0

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

@@ -14,6 +14,11 @@ type StandardSchema<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> = {
+  /**
+   * Disable every field of the form, its submit button and `FormDialog`'s
+   * Save. A field's own `disabled` still applies.
+   */
+  disabled?: boolean;
   /**
    * If `true`, shipped fields skip rendering their inline `<FieldError>`
    * message. Fields still flip `data-invalid` / `aria-invalid`.
@@ -44,9 +49,11 @@ type SchemaPathExtras<TFormData> = {
 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 SyncValidator<TFormData> = undefined | FormValidateOrFn<TFormData>;
+type AsyncValidator<TFormData> = undefined | FormAsyncValidateOrFn<TFormData>;
+type SchemaFormOptions<TFormData, TOnMount extends SyncValidator<TFormData>, TOnChange extends SyncValidator<TFormData>, TOnChangeAsync extends AsyncValidator<TFormData>, TOnBlur extends SyncValidator<TFormData>, TOnBlurAsync extends AsyncValidator<TFormData>, TOnSubmit extends SyncValidator<TFormData>, TOnSubmitAsync extends AsyncValidator<TFormData>, TOnDynamic extends SyncValidator<TFormData>, TOnDynamicAsync extends AsyncValidator<TFormData>, TOnServer extends AsyncValidator<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 SyncValidator<TFormData>, TOnChange extends SyncValidator<TFormData>, TOnChangeAsync extends AsyncValidator<TFormData>, TOnBlur extends SyncValidator<TFormData>, TOnBlurAsync extends AsyncValidator<TFormData>, TOnSubmit extends SyncValidator<TFormData>, TOnSubmitAsync extends AsyncValidator<TFormData>, TOnDynamic extends SyncValidator<TFormData>, TOnDynamicAsync extends AsyncValidator<TFormData>, TOnServer extends AsyncValidator<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 SyncValidator<TFormData>, TOnChange extends SyncValidator<TFormData>, TOnChangeAsync extends AsyncValidator<TFormData>, TOnBlur extends SyncValidator<TFormData>, TOnBlurAsync extends AsyncValidator<TFormData>, TOnSubmit extends SyncValidator<TFormData>, TOnSubmitAsync extends AsyncValidator<TFormData>, TOnDynamic extends SyncValidator<TFormData>, TOnDynamicAsync extends AsyncValidator<TFormData>, TOnServer extends AsyncValidator<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;
@@ -93,9 +100,17 @@ type WithControlValue<P, V> = P extends {
 type FieldWrappers<FC extends Record<string, AnyComponent>, T> = { [K in keyof FC]: <N extends DeepKeys<T>>(props: WithControlValue<ComponentProps<FC[K]>, DeepValue<T, N>> & {
   name: N;
 } & WithValidators) => ReactNode; };
+type OptionalProps<P> = P extends unknown ? { [K in keyof P as Pick<P, K> extends Required<Pick<P, K>> ? never : K]?: P[K]; } : never;
+type DefaultProps<C extends Record<string, AnyComponent>> = { [K in keyof C]?: OptionalProps<ComponentProps<C[K]>>; };
 type CreateZenoFormConfig<FC extends Record<string, AnyComponent>, FMC extends Record<string, AnyComponent>> = {
   fieldComponents: FC;
   formComponents: FMC;
+  /**
+   * Default props for field and form components, keyed by component name,
+   * e.g. `{ MoneyField: { currency: "CHF", locale: "de-CH" } }`. A prop
+   * passed at the call site wins; one passed as `undefined` keeps the default.
+   */
+  defaultProps?: DefaultProps<NoInfer<FC> & NoInfer<FMC>>;
 };
 /**
  * Build the wired Zeno form API from the caller's field + form components.
@@ -108,7 +123,7 @@ type CreateZenoFormConfig<FC extends Record<string, AnyComponent>, FMC extends R
 export 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> & {
+  useForm: <TFormData, TOnMount extends SyncValidator<TFormData> = SyncValidator<TFormData>, TOnChange extends SyncValidator<TFormData> = SyncValidator<TFormData>, TOnChangeAsync extends AsyncValidator<TFormData> = AsyncValidator<TFormData>, TOnBlur extends SyncValidator<TFormData> = SyncValidator<TFormData>, TOnBlurAsync extends AsyncValidator<TFormData> = AsyncValidator<TFormData>, TOnSubmit extends SyncValidator<TFormData> = SyncValidator<TFormData>, TOnSubmitAsync extends AsyncValidator<TFormData> = AsyncValidator<TFormData>, TOnDynamic extends SyncValidator<TFormData> = SyncValidator<TFormData>, TOnDynamicAsync extends AsyncValidator<TFormData> = AsyncValidator<TFormData>, TOnServer extends AsyncValidator<TFormData> = AsyncValidator<TFormData>, TSubmitMeta = unknown>(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;

package/dist/create-zeno-form.mjs

@@ -1,10 +1,12 @@
 "use client";
 import { applyValidationError } from "./lib/apply-validation-error.mjs";
 import { fieldContext, formContext } from "./lib/contexts.mjs";
+import { withDefaultProps } from "./lib/default-props.mjs";
 import { deepMergeDefaults, extractZodDefaults } from "./lib/schema-defaults.mjs";
 import { getRequiredPaths } from "./lib/schema-required.mjs";
 import { DEFAULT_VALIDATION_MODE, setFormZenoState } from "./lib/validation-modes.mjs";
 import { withEmptyStartValues } from "./lib/empty-value.mjs";
+import { useDisabledOption } from "./lib/form-disabled.mjs";
 import { setSubmitError } from "./lib/submit-error.mjs";
 import { useRebasedDefaultValues } from "./lib/use-rebased-default-values.mjs";
 import { useUnsavedChangesWarning } from "./lib/use-unsaved-changes-warning.mjs";
@@ -31,6 +33,24 @@ function withMountListener(listeners, onMount) {
 		}
 	};
 }
+const REACT_TYPE_KEYS = /* @__PURE__ */ new Set([
+	"$$typeof",
+	"compare",
+	"render",
+	"type"
+]);
+function withComponentDefaults(components, defaultProps) {
+	const wrapped = { ...components };
+	for (const [name, defaults] of Object.entries(defaultProps ?? {})) {
+		const Component = components[name];
+		if (Component === void 0 || defaults === void 0) continue;
+		const Defaulted = (props) => /* @__PURE__ */ jsx(Component, { ...withDefaultProps(defaults, props) });
+		for (const [key, value] of Object.entries(Component)) if (!REACT_TYPE_KEYS.has(key)) Object.assign(Defaulted, { [key]: value });
+		Defaulted.displayName = name;
+		wrapped[name] = Defaulted;
+	}
+	return wrapped;
+}
 /**
 * Build the wired Zeno form API from the caller's field + form components.
 *
@@ -40,18 +60,20 @@ function withMountListener(listeners, onMount) {
 * `useAppFields` wrappers (prop types are inferred from the injected components).
 */
 function createZenoForm(config) {
+	const fieldComponents = withComponentDefaults(config.fieldComponents, config.defaultProps);
+	const formComponents = withComponentDefaults(config.formComponents, config.defaultProps);
 	const { useAppForm, withFieldGroup, withForm } = createFormHook({
-		fieldComponents: config.fieldComponents,
+		fieldComponents,
 		fieldContext,
-		formComponents: config.formComponents,
+		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];
+			for (const key of Object.keys(fieldComponents)) {
+				const Impl = fieldComponents[key];
 				wrappers[key] = ({ name, validators, listeners, ...props }) => /* @__PURE__ */ jsx(Field, {
 					listeners,
 					name,
@@ -63,7 +85,7 @@ function createZenoForm(config) {
 		}, [form]);
 	}
 	function useForm(options) {
-		const { schema, validators: validatorsInput, validationLogic: userValidationLogic, hideFieldErrors = false, requiredIndicator = true, unsavedChangesWarning = false, defaultValues: userDefaultValues, onSubmit: userOnSubmit, ...rest } = options;
+		const { schema, validators: validatorsInput, validationLogic: userValidationLogic, disabled = false, hideFieldErrors = false, requiredIndicator = true, unsavedChangesWarning = false, defaultValues: userDefaultValues, onSubmit: userOnSubmit, ...rest } = options;
 		let schemaMode;
 		let resolvedValidators;
 		let resolvedValidationLogic;
@@ -111,9 +133,10 @@ function createZenoForm(config) {
 			schema,
 			...schemaMode === void 0 ? {} : { validation: schemaMode }
 		});
+		useDisabledOption(form, disabled);
 		useUnsavedChangesWarning(form, unsavedChangesWarning);
 		const fields = useAppFields(form);
-		return useMemo(() => Object.assign(form, fields, config.formComponents), [form, fields]);
+		return useMemo(() => Object.assign(form, fields, formComponents), [form, fields]);
 	}
 	return {
 		useAppFields,

package/dist/form-element.d.mts

@@ -2,12 +2,25 @@ import { ComponentProps, ReactNode } from "react";
 //#region src/form-element.d.ts
 type FormProviderProps = {
   children: ReactNode;
+  /**
+   * Disable every field of the form and its submit button, as
+   * `useForm({ disabled })` does. A field's own `disabled` still applies.
+   */
+  disabled?: boolean;
   form: {
     handleSubmit: () => unknown;
   };
 };
-declare function FormProvider({ children, form }: FormProviderProps): import("react").JSX.Element;
-type FormProps = Omit<ComponentProps<"form">, "onSubmit">;
-declare function Form({ children, className, ...props }: FormProps): import("react").JSX.Element;
+declare function FormProvider({ children, disabled, form }: FormProviderProps): import("react").JSX.Element;
+type FormProps = Omit<ComponentProps<"form">, "onSubmit"> & {
+  /**
+   * Disable every field and button of the kit inside, and ignore a submit. A
+   * field's own `disabled` still applies. A button outside the `<form>`
+   * (`form="id"`) isn't inside: disable the form with `useForm({ disabled })`
+   * or `<FormProvider disabled>` to reach it.
+   */
+  disabled?: boolean;
+};
+declare function Form({ children, className, disabled, ...props }: FormProps): import("react").JSX.Element;
 //#endregion
 export { Form, FormProvider };

package/dist/form-element.mjs

@@ -1,32 +1,52 @@
 "use client";
 import { FormProvider as FormProvider$1, useFormContext } from "./lib/contexts.mjs";
+import { FormDisabledContext, useIsFormDisabled } from "./lib/form-disabled.mjs";
 import { reportSubmitError } from "./lib/submit-error.mjs";
 import { focusFirstInvalid, restoreFocus } from "./lib/focus-first-invalid.mjs";
+import { useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/form-element.tsx
-function FormProvider({ children, form }) {
+function FormProvider({ children, disabled = false, form }) {
+	const { store } = form;
+	const scope = useMemo(() => ({
+		disabled,
+		key: store
+	}), [disabled, store]);
 	return /* @__PURE__ */ jsx(FormProvider$1, {
 		value: form,
-		children
+		children: /* @__PURE__ */ jsx(FormDisabledContext, {
+			value: scope,
+			children
+		})
 	});
 }
-function Form({ children, className, ...props }) {
+function Form({ children, className, disabled = false, ...props }) {
 	const form = useFormContext();
-	return /* @__PURE__ */ jsx("form", {
-		className,
-		noValidate: true,
-		onSubmit: async (event) => {
-			event.preventDefault();
-			event.stopPropagation();
-			const node = event.currentTarget;
-			const focused = node.ownerDocument.activeElement;
-			await Promise.resolve(form.handleSubmit()).catch(reportSubmitError);
-			const { isSubmitSuccessful, isValid } = form.state;
-			if (!isValid && focusFirstInvalid(node)) return;
-			if (!(isValid && isSubmitSuccessful)) restoreFocus(focused);
-		},
-		...props,
-		children
+	const isDisabled = useIsFormDisabled(form) || disabled;
+	const { store } = form;
+	const scope = useMemo(() => ({
+		disabled: isDisabled,
+		key: store
+	}), [isDisabled, store]);
+	return /* @__PURE__ */ jsx(FormDisabledContext, {
+		value: scope,
+		children: /* @__PURE__ */ jsx("form", {
+			className,
+			noValidate: true,
+			onSubmit: async (event) => {
+				event.preventDefault();
+				event.stopPropagation();
+				if (isDisabled) return;
+				const node = event.currentTarget;
+				const focused = node.ownerDocument.activeElement;
+				await Promise.resolve(form.handleSubmit()).catch(reportSubmitError);
+				const { isSubmitSuccessful, isValid } = form.state;
+				if (!isValid && focusFirstInvalid(node)) return;
+				if (!(isValid && isSubmitSuccessful)) restoreFocus(focused);
+			},
+			...props,
+			children
+		})
 	});
 }
 //#endregion

package/dist/index.d.mts

@@ -6,8 +6,9 @@ import { ActionError, ActionIssue, ActionResult, toActionError, toFieldName } fr
 import { FieldMessage, ValidationError } from "./lib/validation-error.mjs";
 import { applyValidationError } from "./lib/apply-validation-error.mjs";
 import { useFieldContext, useFormContext } from "./lib/contexts.mjs";
+import { useIsFormDisabled } from "./lib/form-disabled.mjs";
 import { SubmitActionOptions, SubmitActionSchema, applyActionError, submitAction } from "./lib/submit-action.mjs";
 import { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid } from "./lib/use-is-invalid.mjs";
 import { blurThenChangeLogic } from "./lib/validation-logic.mjs";
 import { useSelector } from "@tanstack/react-form";
-export { type ActionError, type ActionIssue, type ActionResult, type FieldControl, type FieldControlProps, type FieldMessage, Form, FormProvider, type SubmitActionOptions, type SubmitActionSchema, type UseFieldControlOptions, ValidationError, type ValidationMode, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFieldControl, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid, useSelector };
+export { type ActionError, type ActionIssue, type ActionResult, type FieldControl, type FieldControlProps, type FieldMessage, Form, FormProvider, type SubmitActionOptions, type SubmitActionSchema, type UseFieldControlOptions, ValidationError, type ValidationMode, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFieldControl, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsFormDisabled, useIsInvalid, useSelector };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { applyValidationError } from "./lib/apply-validation-error.mjs";
 import { useFieldContext, useFormContext } from "./lib/contexts.mjs";
 import { toActionError, toFieldName } from "./lib/action-result.mjs";
+import { useIsFormDisabled } from "./lib/form-disabled.mjs";
 import { ValidationError } from "./lib/validation-error.mjs";
 import { blurThenChangeLogic } from "./lib/validation-logic.mjs";
 import { createZenoForm } from "./create-zeno-form.mjs";
@@ -9,4 +10,4 @@ import { applyActionError, submitAction } from "./lib/submit-action.mjs";
 import { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid } from "./lib/use-is-invalid.mjs";
 import { useFieldControl } from "./lib/use-field-control.mjs";
 import { useSelector } from "@tanstack/react-form";
-export { Form, FormProvider, ValidationError, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFieldControl, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid, useSelector };
+export { Form, FormProvider, ValidationError, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFieldControl, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsFormDisabled, useIsInvalid, useSelector };

package/dist/lib/date-value.d.mts

@@ -0,0 +1,24 @@
+//#region src/lib/date-value.d.ts
+/**
+ * What a date field stores for a picked day:
+ * - `"date"`: a `Date`, at local midnight.
+ * - `"iso-date"`: the day as `YYYY-MM-DD`, as `z.iso.date()` accepts and a
+ *   `date` column stores it.
+ * - `"iso-datetime"`: the day's local midnight as an ISO 8601 timestamp in
+ *   UTC (`toISOString()`), as `z.iso.datetime()` accepts and a timestamp
+ *   column takes it.
+ */
+type DateValueType = "date" | "iso-date" | "iso-datetime";
+/**
+ * The day a stored value stands for, as a local `Date`, or `undefined` for an
+ * empty or unreadable one. Reads a `Date`, a `YYYY-MM-DD` string as that day
+ * in local time, and any other string `Date` parses, such as an ISO 8601
+ * timestamp.
+ */
+declare function parseDateValue(value: unknown): Date | undefined;
+/** The day of a local `Date` as `YYYY-MM-DD`, without going through UTC. */
+declare function formatIsoDate(date: Date): string;
+/** The value to store for `date`, a day picked in local time. */
+declare function toDateValue(date: Date, type: DateValueType): Date | string;
+//#endregion
+export { type DateValueType, formatIsoDate, parseDateValue, toDateValue };

package/dist/lib/date-value.mjs

@@ -0,0 +1,37 @@
+//#region src/lib/date-value.ts
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+function pad(value, length) {
+	return String(value).padStart(length, "0");
+}
+function parseIsoDate(value) {
+	const match = ISO_DATE.exec(value);
+	if (!match) return;
+	const [year, month, day] = match.slice(1).map(Number);
+	const date = new Date(year, month - 1, day);
+	date.setFullYear(year, month - 1, day);
+	return date.getMonth() === month - 1 ? date : void 0;
+}
+/**
+* The day a stored value stands for, as a local `Date`, or `undefined` for an
+* empty or unreadable one. Reads a `Date`, a `YYYY-MM-DD` string as that day
+* in local time, and any other string `Date` parses, such as an ISO 8601
+* timestamp.
+*/
+function parseDateValue(value) {
+	let date;
+	if (value instanceof Date) date = value;
+	else if (typeof value === "string" && value !== "") date = ISO_DATE.test(value) ? parseIsoDate(value) : new Date(value);
+	return date && !Number.isNaN(date.getTime()) ? date : void 0;
+}
+/** The day of a local `Date` as `YYYY-MM-DD`, without going through UTC. */
+function formatIsoDate(date) {
+	return `${pad(date.getFullYear(), 4)}-${pad(date.getMonth() + 1, 2)}-${pad(date.getDate(), 2)}`;
+}
+/** The value to store for `date`, a day picked in local time. */
+function toDateValue(date, type) {
+	if (type === "iso-date") return formatIsoDate(date);
+	if (type === "iso-datetime") return date.toISOString();
+	return date;
+}
+//#endregion
+export { formatIsoDate, parseDateValue, toDateValue };

package/dist/lib/default-props.d.mts

@@ -0,0 +1,7 @@
+//#region src/lib/default-props.d.ts
+/**
+ * The props a component renders with: `props` over `defaults`. A prop passed
+ * as `undefined` keeps its default, as a destructuring default would.
+ */
+export declare function withDefaultProps<P extends object>(defaults: Partial<P> | undefined, props: P): P;
+//#endregion

package/dist/lib/default-props.mjs

@@ -0,0 +1,13 @@
+//#region src/lib/default-props.ts
+/**
+* The props a component renders with: `props` over `defaults`. A prop passed
+* as `undefined` keeps its default, as a destructuring default would.
+*/
+function withDefaultProps(defaults, props) {
+	if (defaults === void 0) return props;
+	const merged = { ...defaults };
+	for (const [key, value] of Object.entries(props)) if (value !== void 0) merged[key] = value;
+	return merged;
+}
+//#endregion
+export { withDefaultProps };

package/dist/lib/empty-value.mjs

@@ -44,14 +44,38 @@ function emptyValueFor(schema, values, name, fallback) {
 function isTypeEmpty(value) {
 	return value === "" || Array.isArray(value) && value.length === 0;
 }
+function isUnder(name, prefix) {
+	return name === prefix || name.startsWith(`${prefix}.`) || name.startsWith(`${prefix}[`);
+}
+function emptiableAncestor(schema, values, keys) {
+	for (let length = 1; length < keys.length; length += 1) {
+		const prefix = keys.slice(0, length);
+		const start = valueAt(values, prefix);
+		if (typeof start !== "object" || start === null || Array.isArray(start)) continue;
+		const empty = emptyValueFor(schema, values, toFieldName(prefix), start);
+		if (empty === null || empty === void 0) return {
+			keys: prefix,
+			value: empty
+		};
+	}
+	return null;
+}
 function withEmptyStartValues(schema, defaults) {
 	const issues = validateSync(schema, defaults);
 	let result = defaults;
+	const emptied = [];
 	for (const issue of issues ?? []) {
 		const name = toFieldName(issue.path);
 		const keys = toPathKeys(name);
+		if (keys.length === 0 || emptied.some((prefix) => isUnder(name, prefix))) continue;
+		const ancestor = emptiableAncestor(schema, result, keys);
+		if (ancestor) {
+			result = withValueAt(result, ancestor.keys, ancestor.value);
+			emptied.push(toFieldName(ancestor.keys));
+			continue;
+		}
 		const start = valueAt(defaults, keys);
-		if (keys.length === 0 || !isTypeEmpty(start)) continue;
+		if (!isTypeEmpty(start)) continue;
 		const empty = emptyValueFor(schema, result, name, start);
 		if (empty !== start) result = withValueAt(result, keys, empty);
 	}

package/dist/lib/form-disabled.d.mts

@@ -0,0 +1,28 @@
+import { AnyFormApi } from "@tanstack/react-form";
+//#region src/lib/form-disabled.d.ts
+/** Apply `useForm({ disabled })` to `form`. */
+declare function useDisabledOption(form: AnyFormApi, disabled: boolean): void;
+type FormDisabledScope = {
+  readonly disabled: boolean;
+  /** The `store` of the form it disables. */
+  readonly key: object;
+};
+/**
+ * The disabled state `FormProvider` and `<Form>` give what they wrap, for
+ * their own form only: a field of another form rendered inside (a quick-add
+ * popover) keeps that form's state.
+ */
+declare const FormDisabledContext: import("react").Context<FormDisabledScope | null>;
+/**
+ * Whether the form is disabled, by `useForm({ disabled })`,
+ * `<FormProvider disabled>`, `<Form disabled>` or `FormDialog`'s `disabled`.
+ * Every kit field reads it, so a control the fieldset of a disabled dialog
+ * can't reach (a checkbox, a switch, a radio, a slider) turns off too.
+ *
+ * Reads the form of the nearest provider; inside a field, pass `field.form`.
+ * `useForm({ disabled })` applies even where no provider of the form is
+ * mounted.
+ */
+declare function useIsFormDisabled(form?: AnyFormApi): boolean;
+//#endregion
+export { FormDisabledContext, useDisabledOption, useIsFormDisabled };

package/dist/lib/form-disabled.mjs

@@ -0,0 +1,54 @@
+"use client";
+import { formContext } from "./contexts.mjs";
+import { createContext, useCallback, useContext, useLayoutEffect, useSyncExternalStore } from "react";
+//#region src/lib/form-disabled.ts
+const disabledOption = /* @__PURE__ */ new WeakMap();
+const listeners = /* @__PURE__ */ new WeakMap();
+function subscribe(key, listener) {
+	let set = listeners.get(key);
+	if (!set) {
+		set = /* @__PURE__ */ new Set();
+		listeners.set(key, set);
+	}
+	set.add(listener);
+	return () => {
+		set.delete(listener);
+	};
+}
+/** Apply `useForm({ disabled })` to `form`. */
+function useDisabledOption(form, disabled) {
+	const key = form.store;
+	if (!disabledOption.has(key)) disabledOption.set(key, disabled);
+	useLayoutEffect(() => {
+		if (disabledOption.get(key) === disabled) return;
+		disabledOption.set(key, disabled);
+		for (const listener of listeners.get(key) ?? []) listener();
+	}, [key, disabled]);
+}
+/**
+* The disabled state `FormProvider` and `<Form>` give what they wrap, for
+* their own form only: a field of another form rendered inside (a quick-add
+* popover) keeps that form's state.
+*/
+const FormDisabledContext = createContext(null);
+/**
+* Whether the form is disabled, by `useForm({ disabled })`,
+* `<FormProvider disabled>`, `<Form disabled>` or `FormDialog`'s `disabled`.
+* Every kit field reads it, so a control the fieldset of a disabled dialog
+* can't reach (a checkbox, a switch, a radio, a slider) turns off too.
+*
+* Reads the form of the nearest provider; inside a field, pass `field.form`.
+* `useForm({ disabled })` applies even where no provider of the form is
+* mounted.
+*/
+function useIsFormDisabled(form) {
+	const scope = useContext(FormDisabledContext);
+	const contextForm = useContext(formContext);
+	const key = (form ?? contextForm)?.store;
+	const subscribeToKey = useCallback((listener) => key ? subscribe(key, listener) : () => null, [key]);
+	const getSnapshot = () => key ? disabledOption.get(key) ?? false : false;
+	const byOption = useSyncExternalStore(subscribeToKey, getSnapshot, getSnapshot);
+	return scope?.disabled === true && (key === void 0 || scope.key === key) || byOption;
+}
+//#endregion
+export { FormDisabledContext, useDisabledOption, useIsFormDisabled };

package/dist/lib/item-options.d.mts

@@ -0,0 +1,45 @@
+//#region src/lib/item-options.d.ts
+/** An item whose value isn't its label. */
+type ItemObject<V> = {
+  value: V;
+  label: string;
+};
+/** Items under a heading. */
+type ItemGroup<T> = {
+  label: string;
+  items: readonly T[];
+};
+/** An item of `items`, or of one of its groups. */
+type ItemOption<T> = T extends ItemGroup<infer I> ? I : T;
+/** What picking an item stores: `item.value` for an object, else the item. */
+type ItemValue<T> = T extends ItemGroup<infer I> ? ItemValue<I> : T extends ItemObject<infer V> ? V : T;
+/** Whether an item's value is a stored one, as `isItemEqualToValue` says. */
+type ValueComparator = (itemValue: unknown, value: unknown) => boolean;
+declare function isItemObject(item: unknown): item is ItemObject<unknown>;
+/** What Base UI takes for a group: an object with an `items` array. */
+declare function isItemGroup(item: unknown): item is ItemGroup<unknown>;
+declare function itemValue(item: unknown): unknown;
+declare function itemLabel(item: unknown): string;
+/** A React key per value: `1` and `"1"` get two, an object gets its JSON. */
+declare function valueKey(value: unknown): string;
+type ItemList<T> = {
+  /**
+   * `items` as Base UI takes them. It tells a grouped list by its first entry
+   * alone, so once there is a group, each run of plain items beside one goes
+   * under a group with no heading (`label: ""`).
+   */
+  readonly items: readonly T[];
+  /** Every option, the grouped ones included, in order. */
+  readonly options: readonly ItemOption<T>[];
+  /** The first option of each `valueKey`, so finding a value is no scan. */
+  readonly byKey: ReadonlyMap<string, ItemOption<T>>;
+};
+declare function toItemList<T>(items: readonly T[]): ItemList<T>;
+/**
+ * `Object.is`, then `isItemEqualToValue`, which never sees an empty value.
+ */
+declare function isSameValue(a: unknown, b: unknown, isItemEqualToValue: ValueComparator | undefined): boolean;
+/** The option whose value is `value`, if `items` has it. */
+declare function findOption<T>(list: ItemList<T>, value: unknown, isItemEqualToValue: ValueComparator | undefined): ItemOption<T> | undefined;
+//#endregion
+export { type ItemGroup, type ItemList, type ItemObject, type ItemOption, type ItemValue, type ValueComparator, findOption, isItemGroup, isItemObject, isSameValue, itemLabel, itemValue, toItemList, valueKey };

package/dist/lib/item-options.mjs

@@ -0,0 +1,70 @@
+//#region src/lib/item-options.ts
+function isItemObject(item) {
+	return typeof item === "object" && item !== null && "value" in item && "label" in item;
+}
+/** What Base UI takes for a group: an object with an `items` array. */
+function isItemGroup(item) {
+	return typeof item === "object" && item !== null && Array.isArray(item.items);
+}
+function itemValue(item) {
+	return isItemObject(item) ? item.value : item;
+}
+function itemLabel(item) {
+	return isItemObject(item) ? item.label : String(item);
+}
+/** A React key per value: `1` and `"1"` get two, an object gets its JSON. */
+function valueKey(value) {
+	if (typeof value !== "object" || value === null) return `${typeof value}:${String(value)}`;
+	try {
+		return `object:${JSON.stringify(value)}`;
+	} catch {
+		return `object:${String(value)}`;
+	}
+}
+function toItemList(items) {
+	const hasGroup = items.some(isItemGroup);
+	const options = [];
+	const groups = [];
+	let run;
+	for (const item of items) if (isItemGroup(item)) {
+		for (const option of item.items) options.push(option);
+		groups.push(item);
+		run = void 0;
+	} else {
+		options.push(item);
+		if (hasGroup && !run) {
+			run = [];
+			groups.push({
+				items: run,
+				label: ""
+			});
+		}
+		run?.push(item);
+	}
+	const byKey = /* @__PURE__ */ new Map();
+	for (const option of options) {
+		const key = valueKey(itemValue(option));
+		if (!byKey.has(key)) byKey.set(key, option);
+	}
+	return {
+		byKey,
+		items: hasGroup ? groups : items,
+		options
+	};
+}
+/**
+* `Object.is`, then `isItemEqualToValue`, which never sees an empty value.
+*/
+function isSameValue(a, b, isItemEqualToValue) {
+	if (Object.is(a, b)) return true;
+	if (a === null || a === void 0 || b === null || b === void 0) return false;
+	return isItemEqualToValue?.(a, b) ?? false;
+}
+/** The option whose value is `value`, if `items` has it. */
+function findOption(list, value, isItemEqualToValue) {
+	const hit = list.byKey.get(valueKey(value));
+	if (hit !== void 0 && isSameValue(itemValue(hit), value, isItemEqualToValue)) return hit;
+	return list.options.find((option) => isSameValue(itemValue(option), value, isItemEqualToValue));
+}
+//#endregion
+export { findOption, isItemGroup, isItemObject, isSameValue, itemLabel, itemValue, toItemList, valueKey };

package/dist/lib/schema-required.mjs

@@ -102,6 +102,22 @@ function settleEmptied(emptied, failing, probe, required, cleared) {
 		next
 	};
 }
+function clearNullableObjects(schema, filled, probe, required, cleared) {
+	for (const fill of filled) {
+		if (isEmptyProbe(fill.value) || cleared.has(fill.path)) continue;
+		fillAt(probe, fill.keys, null, true);
+		const issues = validateSync(schema, probe);
+		fillAt(probe, fill.keys, fill.value, true);
+		const rejected = issues?.some((issue) => {
+			const path = joinPath(issue.path?.map(pathKey) ?? []);
+			return path === fill.path || path.startsWith(`${fill.path}.`) || path.startsWith(`${fill.path}[`);
+		});
+		if (issues && !rejected) {
+			required.delete(fill.path);
+			cleared.add(fill.path);
+		}
+	}
+}
 function getRequiredPaths(schema) {
 	const required = /* @__PURE__ */ new Set();
 	const cleared = /* @__PURE__ */ new Set();
@@ -111,6 +127,7 @@ function getRequiredPaths(schema) {
 		const issues = validateSync(schema, probe);
 		if (!issues) return required;
 		const { failing, filled } = recordPass(issues, probe, required, cleared);
+		clearNullableObjects(schema, filled, probe, required, cleared);
 		const settled = settleEmptied(emptied, failing, probe, required, cleared);
 		emptied = [...filled.filter(({ value }) => isEmptyProbe(value)), ...settled.next];
 		if (filled.length === 0 && !settled.descended) break;