@zeno-lib/forms 0.6.0 → 0.7.0

package/dist/lib/use-field-control.d.mts

@@ -7,6 +7,10 @@ type UseFieldControlOptions = {
    * it, and by the error while one shows.
    */
   description?: ReactNode;
+  /**
+   * Disable the control. A disabled form (`useForm({ disabled })`,
+   * `<Form disabled>`, `FormDialog`'s `disabled`) disables it either way.
+   */
   disabled?: boolean;
   /**
    * The label the field renders, if any. The control gets `aria-labelledby`,
@@ -26,6 +30,7 @@ type FieldControlProps<TValue = unknown> = {
   "aria-invalid": true | undefined;
   "aria-labelledby": string | undefined;
   "aria-required": true | undefined;
+  /** The field's own `disabled`, or the form's. */
   disabled: boolean | undefined;
   id: string;
   name: string;
@@ -56,6 +61,8 @@ type FieldControl<TValue = unknown> = {
   errors: AnyFieldMeta["errors"];
   /** The control's id, for the label's `htmlFor`. */
   id: string;
+  /** The field is disabled, by its own `disabled` or the form's. */
+  isDisabled: boolean;
   isInvalid: boolean;
   /** The field requires a value, by the schema or `required`. */
   isRequired: boolean;

package/dist/lib/use-field-control.mjs

@@ -2,6 +2,7 @@
 import { useFieldContext } from "./contexts.mjs";
 import { getFormSchema } from "./validation-modes.mjs";
 import { emptyValueFor } from "./empty-value.mjs";
+import { useIsFormDisabled } from "./form-disabled.mjs";
 import { describedBy } from "./aria.mjs";
 import { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid } from "./use-is-invalid.mjs";
 import { useCallback, useId } from "react";
@@ -30,6 +31,7 @@ function useFieldControl({ description, disabled, label, required } = {}) {
 	const schemaRequired = useIsFieldRequired(field);
 	const schemaRequiresValue = useIsFieldRequiredBySchema(field);
 	const isRequired = required ?? schemaRequiresValue;
+	const isDisabled = useIsFormDisabled(field.form) || Boolean(disabled);
 	const { form, handleBlur, handleChange, name } = field;
 	const onChange = useCallback((value) => {
 		if (isSyntheticEvent(value)) throw new TypeError(`Field "${name}" got a change event, not a value. Map it in the control: onChange(event.target.value).`);
@@ -45,7 +47,7 @@ function useFieldControl({ description, disabled, label, required } = {}) {
 			"aria-invalid": isInvalid || void 0,
 			"aria-labelledby": labelId,
 			"aria-required": isRequired || void 0,
-			disabled,
+			disabled: isDisabled,
 			id,
 			name,
 			onBlur: handleBlur,
@@ -56,6 +58,7 @@ function useFieldControl({ description, disabled, label, required } = {}) {
 		errorId,
 		errors: showError ? field.state.meta.errors : [],
 		id,
+		isDisabled,
 		isInvalid,
 		isRequired,
 		labelId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeno-lib/forms",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "repository": {
     "url": "https://github.com/zeno-lib/zeno.git",
     "directory": "packages/forms"

package/src/create-form.tsx

@@ -28,37 +28,42 @@ import { YearField } from "./fields/year-field"
 
 // Wire the dropped-in field components into the headless factory. Edit the
 // field files under `./fields` freely — they use your own shadcn primitives.
-const { useAppForm, useForm, withFieldGroup, withForm } = createZenoForm({
-  fieldComponents: {
-    CheckboxField,
-    CheckboxGroupField,
-    ComboboxField,
-    ControlField,
-    DatePickerField,
-    EmailField,
-    InputField,
-    MoneyField,
-    MultiSelectField,
-    NumberField,
-    OtpField,
-    PasswordField,
-    PercentageField,
-    RadioGroupField,
-    SelectField,
-    SliderField,
-    SwitchField,
-    TextAreaField,
-    YearField,
-  },
-  formComponents: {
-    FormError,
-    ResetButton,
-    SubmitButton,
-  },
-})
+const { useAppFields, useAppForm, useForm, withFieldGroup, withForm } =
+  createZenoForm({
+    // Your app's default props per component, e.g.
+    // `MoneyField: { currency: "CHF", locale: "de-CH" }`. A prop passed at the
+    // call site wins.
+    defaultProps: {},
+    fieldComponents: {
+      CheckboxField,
+      CheckboxGroupField,
+      ComboboxField,
+      ControlField,
+      DatePickerField,
+      EmailField,
+      InputField,
+      MoneyField,
+      MultiSelectField,
+      NumberField,
+      OtpField,
+      PasswordField,
+      PercentageField,
+      RadioGroupField,
+      SelectField,
+      SliderField,
+      SwitchField,
+      TextAreaField,
+      YearField,
+    },
+    formComponents: {
+      FormError,
+      ResetButton,
+      SubmitButton,
+    },
+  })
 
 export * from "@zeno-lib/forms"
 export { ValidationSpinner } from "./addons/validation-spinner"
 export { FieldShell } from "./fields/field-shell"
 export { RadioGroupFieldItem } from "./fields/radio-group-field"
-export { useAppForm, useForm, withFieldGroup, withForm }
+export { useAppFields, useAppForm, useForm, withFieldGroup, withForm }

package/src/create-zeno-form.tsx

@@ -13,7 +13,9 @@ import { createFormHook } from "@tanstack/react-form"
 import { type ComponentProps, type ReactNode, useMemo } from "react"
 import { applyValidationError } from "./lib/apply-validation-error"
 import { fieldContext, formContext } from "./lib/contexts"
+import { withDefaultProps } from "./lib/default-props"
 import { withEmptyStartValues } from "./lib/empty-value"
+import { useDisabledOption } from "./lib/form-disabled"
 import { deepMergeDefaults, extractZodDefaults } from "./lib/schema-defaults"
 import {
   getRequiredPaths,
@@ -54,6 +56,11 @@ type PartialFormData<T> = T extends readonly unknown[]
       : 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`.
@@ -90,18 +97,21 @@ type ManualPathExtras = {
   schema?: never
 }
 
+type SyncValidator<TFormData> = undefined | FormValidateOrFn<TFormData>
+type AsyncValidator<TFormData> = undefined | FormAsyncValidateOrFn<TFormData>
+
 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>,
+  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<
@@ -125,16 +135,16 @@ type SchemaFormOptions<
 
 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>,
+  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<
@@ -158,16 +168,16 @@ type ManualFormOptions<
 
 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>,
+  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<
@@ -298,12 +308,66 @@ type FieldWrappers<FC extends Record<string, AnyComponent>, T> = {
   ) => ReactNode
 }
 
+// A component's optional props, per member of a union of props.
+type OptionalProps<P> = P extends unknown
+  ? {
+      [K in keyof P as Pick<P, K> extends Required<Pick<P, K>>
+        ? never
+        : K]?: P[K]
+    }
+  : never
+
+// Each component's defaults take only its own optional props: a required
+// one stays required at every call site, so its default would never apply.
+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>>
+}
+
+// What `memo` and `forwardRef` store on their component object, which a
+// function component must not take over.
+const REACT_TYPE_KEYS = new Set(["$$typeof", "compare", "render", "type"])
+
+// Wrap each component that has defaults, once, so they apply however it
+// renders: destructured from `useForm`, as `field.X` in `AppField`, or in
+// `withForm`.
+function withComponentDefaults<C extends Record<string, AnyComponent>>(
+  components: C,
+  defaultProps: Partial<Record<string, object>> | undefined
+): C {
+  const wrapped: Record<string, AnyComponent> = { ...components }
+  for (const [name, defaults] of Object.entries(defaultProps ?? {})) {
+    const Component = components[name]
+    if (Component === undefined || defaults === undefined) {
+      continue
+    }
+    const Defaulted = (props: object) => (
+      <Component {...withDefaultProps(defaults, props)} />
+    )
+    // Keep the component's statics (`AddressField.Row`): the wrapper is
+    // typed as the component.
+    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 as C
 }
 
 /**
@@ -318,10 +382,18 @@ export function createZenoForm<
   FC extends Record<string, AnyComponent>,
   FMC extends Record<string, AnyComponent>,
 >(config: CreateZenoFormConfig<FC, FMC>) {
+  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,
   })
 
@@ -335,8 +407,8 @@ export function createZenoForm<
         children: () => ReactNode
       }>
       const wrappers: Record<string, AnyComponent> = {}
-      for (const key of Object.keys(config.fieldComponents)) {
-        const Impl = config.fieldComponents[key] as AnyComponent
+      for (const key of Object.keys(fieldComponents)) {
+        const Impl = fieldComponents[key] as AnyComponent
         wrappers[key] = ({
           name,
           validators,
@@ -356,27 +428,25 @@ export function createZenoForm<
     }, [form])
   }
 
+  // An unset generic defaults to its constraint, which is what TanStack's own
+  // `useForm` infers, never to `undefined` or `never`: `withForm` rejects the
+  // form otherwise (`with-form.test-d.ts`).
   function useForm<
     TFormData,
-    TOnMount extends undefined | FormValidateOrFn<TFormData> = undefined,
-    TOnChange extends undefined | FormValidateOrFn<TFormData> = undefined,
+    TOnMount extends SyncValidator<TFormData> = SyncValidator<TFormData>,
+    TOnChange extends SyncValidator<TFormData> = SyncValidator<TFormData>,
     TOnChangeAsync extends
-      | undefined
-      | FormAsyncValidateOrFn<TFormData> = undefined,
-    TOnBlur extends undefined | FormValidateOrFn<TFormData> = undefined,
-    TOnBlurAsync extends
-      | undefined
-      | FormAsyncValidateOrFn<TFormData> = undefined,
-    TOnSubmit extends undefined | FormValidateOrFn<TFormData> = undefined,
+      AsyncValidator<TFormData> = AsyncValidator<TFormData>,
+    TOnBlur extends SyncValidator<TFormData> = SyncValidator<TFormData>,
+    TOnBlurAsync extends AsyncValidator<TFormData> = AsyncValidator<TFormData>,
+    TOnSubmit extends SyncValidator<TFormData> = SyncValidator<TFormData>,
     TOnSubmitAsync extends
-      | undefined
-      | FormAsyncValidateOrFn<TFormData> = undefined,
-    TOnDynamic extends undefined | FormValidateOrFn<TFormData> = undefined,
+      AsyncValidator<TFormData> = AsyncValidator<TFormData>,
+    TOnDynamic extends SyncValidator<TFormData> = SyncValidator<TFormData>,
     TOnDynamicAsync extends
-      | undefined
-      | FormAsyncValidateOrFn<TFormData> = undefined,
-    TOnServer extends undefined | FormAsyncValidateOrFn<TFormData> = undefined,
-    TSubmitMeta = never,
+      AsyncValidator<TFormData> = AsyncValidator<TFormData>,
+    TOnServer extends AsyncValidator<TFormData> = AsyncValidator<TFormData>,
+    TSubmitMeta = unknown,
   >(
     options: UseFormOptions<
       TFormData,
@@ -414,6 +484,7 @@ export function createZenoForm<
       schema,
       validators: validatorsInput,
       validationLogic: userValidationLogic,
+      disabled = false,
       hideFieldErrors = false,
       requiredIndicator = true,
       unsavedChangesWarning = false,
@@ -425,6 +496,7 @@ export function createZenoForm<
       validators?: ValidationMode | NativeValidators
       validationLogic?: NativeValidationLogic
       defaultValues?: PartialFormData<TFormData>
+      disabled?: boolean
       hideFieldErrors?: boolean
       requiredIndicator?: boolean
       unsavedChangesWarning?: boolean | "if-changed" | "if-touched"
@@ -557,11 +629,12 @@ export function createZenoForm<
       ...(schemaMode === undefined ? {} : { validation: schemaMode }),
     })
 
+    useDisabledOption(form, disabled)
     useUnsavedChangesWarning(form, unsavedChangesWarning)
 
     const fields = useAppFields(form)
     return useMemo(
-      () => Object.assign(form, fields, config.formComponents),
+      () => Object.assign(form, fields, formComponents),
       [form, fields]
     )
   }

package/src/date-picker-field.test.tsx

@@ -0,0 +1,108 @@
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+} from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"
+import { Form, FormProvider, useForm } from "./create-form"
+import type { DateValueType } from "./lib/date-value"
+
+const DAY_LABEL = /Day/
+const OCTOBER_9_SELECTED = /October 9th, 2026, selected/
+const OCTOBER_10 = /October 10th, 2026/
+
+afterEach(() => {
+  cleanup()
+  vi.unstubAllEnvs()
+})
+
+function Harness({
+  captured,
+  defaultValue,
+  valueType,
+}: {
+  captured: { day?: unknown }
+  defaultValue: string
+  valueType: DateValueType
+}) {
+  const form = useForm({
+    defaultValues: { day: defaultValue as string | undefined },
+    onSubmit: vi.fn(),
+  })
+  const { DatePickerField, Subscribe } = form
+  return (
+    <FormProvider form={form}>
+      <Form>
+        <DatePickerField
+          // `toDateString` doesn't depend on the runtime's locale.
+          formatValue={(date) => date.toDateString()}
+          label="Day"
+          name="day"
+          valueType={valueType}
+        />
+        <Subscribe selector={(state) => state.values.day}>
+          {(day) => {
+            captured.day = day
+            return null
+          }}
+        </Subscribe>
+      </Form>
+    </FormProvider>
+  )
+}
+
+// The day before UTC's date in the evening, and the day after in the morning:
+// a date read or written through UTC lands on the wrong day in one of them.
+describe.each(["Pacific/Kiritimati", "America/Los_Angeles"])(
+  "DatePickerField in %s",
+  (zone) => {
+    beforeEach(() => {
+      vi.stubEnv("TZ", zone)
+    })
+
+    test('valueType="iso-date" shows and stores the day itself', async () => {
+      const user = userEvent.setup()
+      const captured: { day?: unknown } = {}
+      render(
+        <Harness
+          captured={captured}
+          defaultValue="2026-10-09"
+          valueType="iso-date"
+        />
+      )
+      const trigger = screen.getByRole("button", { name: DAY_LABEL })
+      expect(trigger.textContent).toContain("Oct 09 2026")
+
+      fireEvent.click(trigger)
+      expect(await screen.findByRole("button", { name: OCTOBER_9_SELECTED }))
+      await user.click(screen.getByRole("button", { name: OCTOBER_10 }))
+      expect(captured.day).toBe("2026-10-10")
+      expect(trigger.textContent).toContain("Oct 10 2026")
+    })
+
+    test('valueType="iso-datetime" stores a timestamp that reads back as the picked day', async () => {
+      const user = userEvent.setup()
+      const captured: { day?: unknown } = {}
+      render(
+        <Harness
+          captured={captured}
+          // What the field stored for October 9 in this zone.
+          defaultValue={new Date(2026, 9, 9).toISOString()}
+          valueType="iso-datetime"
+        />
+      )
+      const trigger = screen.getByRole("button", { name: DAY_LABEL })
+      expect(trigger.textContent).toContain("Oct 09 2026")
+
+      fireEvent.click(trigger)
+      await user.click(await screen.findByRole("button", { name: OCTOBER_10 }))
+      expect(typeof captured.day).toBe("string")
+      expect(new Date(captured.day as string).toDateString()).toBe(
+        "Sat Oct 10 2026"
+      )
+      expect(trigger.textContent).toContain("Oct 10 2026")
+    })
+  }
+)

package/src/default-props.test-d.ts

@@ -0,0 +1,66 @@
+import { test } from "vitest"
+import { createZenoForm } from "./create-zeno-form"
+import { FormError } from "./fields/form-error"
+import { MoneyField } from "./fields/money-field"
+import { PercentageField } from "./fields/percentage-field"
+import { SelectField } from "./fields/select-field"
+import { FormDialogProvider } from "./form-dialog"
+
+const fieldComponents = { MoneyField, PercentageField, SelectField }
+const formComponents = { FormError }
+
+test("defaultProps takes each component's own props", () => {
+  createZenoForm({
+    defaultProps: {
+      FormError: { submitErrorMessage: "Try again later." },
+      MoneyField: { currency: "CHF", locale: "de-CH" },
+      PercentageField: { scale: "fraction" },
+    },
+    fieldComponents,
+    formComponents,
+  })
+})
+
+test("defaultProps rejects another component's prop", () => {
+  createZenoForm({
+    defaultProps: {
+      // @ts-expect-error — `scale` is PercentageField's
+      MoneyField: { scale: "fraction" },
+    },
+    fieldComponents,
+    formComponents,
+  })
+})
+
+test("defaultProps rejects a required prop, which every call site still passes", () => {
+  createZenoForm({
+    defaultProps: {
+      // @ts-expect-error — `children` is required
+      SelectField: { children: null },
+    },
+    fieldComponents,
+    formComponents,
+  })
+})
+
+test("defaultProps rejects a component the form doesn't have", () => {
+  createZenoForm({
+    defaultProps: {
+      // @ts-expect-error — no such component
+      YearField: { min: 1900 },
+    },
+    fieldComponents,
+    formComponents,
+  })
+})
+
+test("FormDialogProvider takes the options every dialog shares", () => {
+  FormDialogProvider({
+    children: null,
+    discardPrompt: { title: "Leave?" },
+    saveFromPrompt: true,
+    submitLabel: "Speichern",
+  })
+  // @ts-expect-error — a title belongs to one dialog
+  FormDialogProvider({ children: null, title: "Person" })
+})