@zeno-lib/forms 0.5.0 → 0.7.0

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;

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

@@ -40,7 +40,9 @@ type SubmitActionSchemaOptions<TValues, TOutput, TData> = SubmitActionOptions<TV
   /**
    * 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.
+   * applied to the form and the action is never called. Replaces the form's
+   * own `schema` for this call; pass one only when the action takes a
+   * different schema than the form.
    */
   schema: SubmitActionSchema<TOutput>;
 };
@@ -49,9 +51,13 @@ type SubmitActionSchemaOptions<TValues, TOutput, TData> = SubmitActionOptions<TV
  * form. Pass `onSubmit`'s own argument straight through:
  *
  * ```ts
- * onSubmit: (submit) => submitAction(submit, saveProfile, { reset: true, schema })
+ * onSubmit: (submit) => submitAction(submit, saveProfile, { reset: true })
  * ```
  *
+ * The values are parsed with `options.schema`, else with the form's own
+ * `useForm({ schema })`, and the action gets the schema's output. A form with
+ * no schema (`useForm` without one, `useAppForm`) sends its values as they are.
+ *
  * 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

package/dist/lib/submit-action.mjs

@@ -1,5 +1,6 @@
 import { applyValidationError } from "./apply-validation-error.mjs";
 import { toActionError } from "./action-result.mjs";
+import { getFormSchema } from "./validation-modes.mjs";
 import { ValidationError } from "./validation-error.mjs";
 //#region src/lib/submit-action.ts
 function applyActionError(formApi, error) {
@@ -15,9 +16,10 @@ function applyActionError(formApi, error) {
 }
 async function submitAction(props, action, options = {}) {
 	const { formApi, value } = props;
+	const schema = options.schema ?? getFormSchema(formApi);
 	let input = value;
-	if (options.schema) {
-		const parsed = await options.schema["~standard"].validate(value);
+	if (schema) {
+		const parsed = await schema["~standard"].validate(value);
 		if (parsed.issues) {
 			const error = toActionError(parsed.issues);
 			applyActionError(formApi, error);

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

@@ -0,0 +1,83 @@
+import { AnyFieldMeta } from "@tanstack/react-form";
+import { ReactNode } from "react";
+//#region src/lib/use-field-control.d.ts
+type UseFieldControlOptions = {
+  /**
+   * The description the field renders, if any. The control is described by
+   * 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`,
+   * which names a control a `<label htmlFor>` can't, such as a
+   * `role="radiogroup"`.
+   */
+  label?: ReactNode;
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
+  required?: boolean;
+};
+/** The props that bind a control to its field. Spread them on the control. */
+type FieldControlProps<TValue = unknown> = {
+  "aria-describedby": string | undefined;
+  "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;
+  /** Marks the field touched. */
+  onBlur: () => void;
+  /**
+   * Stores `value`, not a change event: a control that reports one maps it
+   * (`onChange(event.target.value)`). An empty value (`null`, `undefined`,
+   * `""`, `NaN` or `[]`) stores the field's empty value instead, which its
+   * schema picks. Stable across renders.
+   */
+  onChange: (value: TValue) => void;
+  /**
+   * The value as stored, the field's empty value (`undefined` or `null`)
+   * included. A control that needs a defined value maps it
+   * (`value={value ?? ""}`), or it turns uncontrolled once the field empties.
+   */
+  value: TValue;
+};
+type FieldControl<TValue = unknown> = {
+  controlProps: FieldControlProps<TValue>;
+  descriptionId: string;
+  errorId: string;
+  /**
+   * The errors to render: none while the field's errors are hidden, by the
+   * form's validation mode or `hideFieldErrors`.
+   */
+  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;
+  /** The label's id, when `label` is passed. */
+  labelId: string | undefined;
+  name: string;
+  /** Show the `*`: as `isRequired`, but off under `requiredIndicator: false`. */
+  showRequiredIndicator: boolean;
+};
+/**
+ * Everything a control needs to act as a field of the form, inside a field
+ * component the form renders (`form.AppField`, or one registered with
+ * `createZenoForm`): the props to spread on the control, and the ids and
+ * state its label, description and error need.
+ */
+declare function useFieldControl<TValue = unknown>({ description, disabled, label, required }?: UseFieldControlOptions): FieldControl<TValue>;
+//#endregion
+export { type FieldControl, type FieldControlProps, type UseFieldControlOptions, useFieldControl };

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

@@ -0,0 +1,70 @@
+"use client";
+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";
+//#region src/lib/use-field-control.ts
+function isEmpty(value) {
+	return value === null || value === void 0 || value === "" || Number.isNaN(value) || Array.isArray(value) && value.length === 0;
+}
+function isSyntheticEvent(value) {
+	return typeof value === "object" && value !== null && "nativeEvent" in value && "target" in value;
+}
+/**
+* Everything a control needs to act as a field of the form, inside a field
+* component the form renders (`form.AppField`, or one registered with
+* `createZenoForm`): the props to spread on the control, and the ids and
+* state its label, description and error need.
+*/
+function useFieldControl({ description, disabled, label, required } = {}) {
+	const field = useFieldContext();
+	const id = useId();
+	const labelId = label ? `${id}-label` : void 0;
+	const descriptionId = `${id}-description`;
+	const errorId = `${id}-error`;
+	const isInvalid = useIsInvalid(field);
+	const hideErrors = useHideFieldErrors(field);
+	const showError = isInvalid && !hideErrors;
+	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).`);
+		handleChange(isEmpty(value) ? emptyValueFor(getFormSchema(form), form.state.values, name, value) : value);
+	}, [
+		form,
+		handleChange,
+		name
+	]);
+	return {
+		controlProps: {
+			"aria-describedby": describedBy([description, descriptionId], [showError, errorId]),
+			"aria-invalid": isInvalid || void 0,
+			"aria-labelledby": labelId,
+			"aria-required": isRequired || void 0,
+			disabled: isDisabled,
+			id,
+			name,
+			onBlur: handleBlur,
+			onChange,
+			value: field.state.value
+		},
+		descriptionId,
+		errorId,
+		errors: showError ? field.state.meta.errors : [],
+		id,
+		isDisabled,
+		isInvalid,
+		isRequired,
+		labelId,
+		name,
+		showRequiredIndicator: required ?? schemaRequired
+	};
+}
+//#endregion
+export { useFieldControl };

package/package.json

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

package/src/control-field.test.tsx

@@ -0,0 +1,338 @@
+import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import type { ComponentProps } from "react"
+import { afterEach, describe, expect, test, vi } from "vitest"
+import { z } from "zod"
+import { Form, FormProvider, useForm } from "./create-form"
+
+afterEach(() => {
+  cleanup()
+})
+
+const PHONE = /Phone/
+const SUBMIT = { name: "Submit" }
+
+// A control a `<label htmlFor>` can't name: only `aria-labelledby` does.
+function StarRating({
+  disabled,
+  name: _name,
+  onChange,
+  value,
+  ...props
+}: Omit<ComponentProps<"div">, "onChange"> & {
+  disabled?: boolean
+  name?: string
+  onChange: (value: number) => void
+  value?: number | null
+}) {
+  return (
+    <div role="radiogroup" {...props}>
+      {[1, 2, 3].map((star) => (
+        // biome-ignore lint/a11y/useSemanticElements: a custom radio group, as a star rating draws one.
+        <button
+          aria-checked={value === star}
+          disabled={disabled}
+          key={star}
+          onClick={() => onChange(star)}
+          role="radio"
+          type="button"
+        >
+          {star}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+// A text control that reports its value, not a change event.
+function PhoneInput({
+  onChange,
+  ...props
+}: Omit<ComponentProps<"input">, "onChange" | "value"> & {
+  onChange: (value: string) => void
+  value: string
+}) {
+  return (
+    <input
+      {...props}
+      onChange={(event) => onChange(event.target.value)}
+      type="tel"
+    />
+  )
+}
+
+describe("ControlField", () => {
+  test("names and describes its control, and flags it once invalid", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({ rating: z.number("Rate it") })
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { ControlField, SubmitButton } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ControlField
+              description="Out of three."
+              label="Rating"
+              name="rating"
+              render={(control) => <StarRating {...control} />}
+            />
+            <SubmitButton>Submit</SubmitButton>
+          </Form>
+        </FormProvider>
+      )
+    }
+    const { container } = render(<H />)
+    const group = screen.getByRole("radiogroup", { name: "Rating" })
+    const description = screen.getByText("Out of three.")
+    expect(group.getAttribute("aria-describedby")).toBe(description.id)
+    expect(group.hasAttribute("aria-invalid")).toBe(false)
+
+    await user.click(screen.getByRole("button", SUBMIT))
+    const error = await screen.findByRole("alert")
+    expect(error.textContent).toBe("Rate it")
+    expect(group.getAttribute("aria-invalid")).toBe("true")
+    expect(group.getAttribute("aria-describedby")).toBe(
+      `${description.id} ${error.id}`
+    )
+    expect(
+      container
+        .querySelector('[data-field="rating"]')
+        ?.getAttribute("data-invalid")
+    ).toBe("true")
+
+    await user.click(screen.getByRole("radio", { name: "2" }))
+    expect(screen.queryByRole("alert")).toBeNull()
+    expect(group.hasAttribute("aria-invalid")).toBe(false)
+  })
+
+  test("marks the field touched on blur, so its error shows", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({ phone: z.string().min(1, "Enter a phone") })
+    function H() {
+      const form = useForm({ onSubmit: vi.fn(), schema })
+      const { ControlField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ControlField
+              label="Phone"
+              name="phone"
+              render={(control) => <PhoneInput {...control} />}
+            />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.click(screen.getByLabelText(PHONE))
+    expect(screen.queryByRole("alert")).toBeNull()
+    await user.tab()
+    expect((await screen.findByRole("alert")).textContent).toBe("Enter a phone")
+  })
+
+  test("takes required from the schema unless `required` says otherwise", () => {
+    const schema = z.object({
+      forced: z.string().optional(),
+      kept: z.string().min(1),
+      lifted: z.string().min(1),
+      open: z.string().optional(),
+    })
+    const FIELDS = [
+      { name: "kept" },
+      { name: "open" },
+      { name: "forced", required: true },
+      { name: "lifted", required: false },
+    ] as const
+    function H({ requiredIndicator }: { requiredIndicator: boolean }) {
+      const form = useForm({ onSubmit: vi.fn(), requiredIndicator, schema })
+      const { ControlField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            {FIELDS.map((props) => (
+              <ControlField
+                key={props.name}
+                label={props.name}
+                render={(control) => (
+                  <PhoneInput {...control} value={control.value ?? ""} />
+                )}
+                {...props}
+              />
+            ))}
+          </Form>
+        </FormProvider>
+      )
+    }
+    for (const requiredIndicator of [true, false]) {
+      const { container, unmount } = render(
+        <H requiredIndicator={requiredIndicator} />
+      )
+      const required = screen
+        .getAllByRole("textbox")
+        .filter((input) => input.getAttribute("aria-required") === "true")
+        .map((input) => input.getAttribute("name"))
+      expect(required).toEqual(["kept", "forced"])
+      // `required` overrides `requiredIndicator: false` too.
+      expect(
+        container.querySelectorAll('[data-slot="required-indicator"]')
+      ).toHaveLength(requiredIndicator ? 2 : 1)
+      unmount()
+    }
+  })
+
+  test("clearing stores the value the schema accepts as empty", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({
+      count: z.number().nullable(),
+      nullable: z.string().min(1).nullable(),
+      optional: z.string().min(1).optional(),
+      tags: z.array(z.string()),
+      text: z.string(),
+    })
+    const captured: { values?: unknown } = {}
+    function H() {
+      const form = useForm({
+        defaultValues: {
+          count: 1,
+          nullable: "a",
+          optional: "b",
+          tags: ["c"],
+          text: "d",
+        },
+        onSubmit: vi.fn(),
+        schema,
+      })
+      const { ControlField, Subscribe } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            {(["nullable", "optional", "text"] as const).map((name) => (
+              <ControlField
+                key={name}
+                label={name}
+                name={name}
+                render={(control) => (
+                  <PhoneInput {...control} value={control.value ?? ""} />
+                )}
+              />
+            ))}
+            <ControlField
+              label="Tags"
+              name="tags"
+              render={({ onChange }) => (
+                <button onClick={() => onChange([])} type="button">
+                  Clear tags
+                </button>
+              )}
+            />
+            {/* A number control reports `NaN` once cleared. */}
+            <ControlField
+              label="Count"
+              name="count"
+              render={({ onChange }) => (
+                <button onClick={() => onChange(Number.NaN)} type="button">
+                  Clear count
+                </button>
+              )}
+            />
+            <Subscribe selector={(state) => state.values}>
+              {(values) => {
+                captured.values = values
+                return null
+              }}
+            </Subscribe>
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.clear(screen.getByLabelText("nullable"))
+    await user.clear(screen.getByLabelText("optional"))
+    await user.clear(screen.getByLabelText("text"))
+    await user.click(screen.getByRole("button", { name: "Clear tags" }))
+    await user.click(screen.getByRole("button", { name: "Clear count" }))
+    expect(captured.values).toStrictEqual({
+      count: null,
+      nullable: null,
+      optional: undefined,
+      tags: [],
+      text: "",
+    })
+    expect(schema.safeParse(captured.values).success).toBe(true)
+  })
+
+  test("keeps one `onChange` across renders, so a control can memoize on it", async () => {
+    const user = userEvent.setup()
+    const handlers = new Set<unknown>()
+    function H() {
+      const form = useForm({ defaultValues: { phone: "" }, onSubmit: vi.fn() })
+      const { ControlField } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ControlField
+              label="Phone"
+              name="phone"
+              render={(control) => {
+                handlers.add(control.onChange)
+                return <PhoneInput {...control} />
+              }}
+            />
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<H />)
+    await user.type(screen.getByLabelText(PHONE), "079")
+    expect(handlers.size).toBe(1)
+  })
+
+  test("refuses a change event, rather than storing it", async () => {
+    const user = userEvent.setup()
+    const errors: unknown[] = []
+    const onError = (event: ErrorEvent) => {
+      event.preventDefault()
+      errors.push(event.error)
+    }
+    window.addEventListener("error", onError)
+    const captured: { values?: unknown } = {}
+    function H() {
+      const form = useForm({ defaultValues: { phone: "" }, onSubmit: vi.fn() })
+      const { ControlField, Subscribe } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <ControlField
+              label="Phone"
+              name="phone"
+              render={({ onChange }) => (
+                // The mistake: an event handed to `onChange` as the value.
+                <button
+                  onClick={(event) => onChange(event as never)}
+                  type="button"
+                >
+                  Set
+                </button>
+              )}
+            />
+            <Subscribe selector={(state) => state.values}>
+              {(values) => {
+                captured.values = values
+                return null
+              }}
+            </Subscribe>
+          </Form>
+        </FormProvider>
+      )
+    }
+    try {
+      render(<H />)
+      await user.click(screen.getByRole("button", { name: "Set" }))
+    } finally {
+      window.removeEventListener("error", onError)
+    }
+    expect(errors).toEqual([expect.any(TypeError)])
+    expect(captured.values).toStrictEqual({ phone: "" })
+  })
+})

package/src/create-form.tsx

@@ -6,6 +6,7 @@ import { createZenoForm } from "@zeno-lib/forms"
 import { CheckboxField } from "./fields/checkbox-field"
 import { CheckboxGroupField } from "./fields/checkbox-group-field"
 import { ComboboxField } from "./fields/combobox-field"
+import { ControlField } from "./fields/control-field"
 import { DatePickerField } from "./fields/date-picker-field"
 import { EmailField } from "./fields/email-field"
 import { FormError } from "./fields/form-error"
@@ -27,35 +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,
-    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 }