@zeno-lib/forms 0.4.0 → 0.6.0

package/src/index.ts

@@ -18,6 +18,12 @@ export {
   type SubmitActionSchema,
   submitAction,
 } from "./lib/submit-action"
+export {
+  type FieldControl,
+  type FieldControlProps,
+  type UseFieldControlOptions,
+  useFieldControl,
+} from "./lib/use-field-control"
 export {
   useHideFieldErrors,
   useIsFieldRequired,

package/src/lib/focus-first-invalid.test.ts

@@ -0,0 +1,22 @@
+import { afterEach, describe, expect, test } from "vitest"
+import { focusFirstInvalid } from "./focus-first-invalid"
+
+afterEach(() => {
+  document.body.innerHTML = ""
+})
+
+describe("focusFirstInvalid", () => {
+  test("skips an invalid control that won't take focus", () => {
+    document.body.innerHTML = `
+      <form>
+        <input aria-invalid="true" disabled name="locked" />
+        <div aria-invalid="true" role="radiogroup">
+          <button disabled role="radio" type="button">A</button>
+          <button role="radio" type="button">B</button>
+        </div>
+      </form>`
+    const focused = focusFirstInvalid(document.querySelector("form"))
+    expect(focused?.textContent).toBe("B")
+    expect(document.activeElement).toBe(focused)
+  })
+})

package/src/lib/focus-first-invalid.ts

@@ -0,0 +1,52 @@
+/**
+ * Move focus to the first invalid control inside `root` (a `<form>`): the
+ * first element with `aria-invalid="true"`, or, for a group root that can't
+ * take focus itself (radio group, slider), its first tabbable descendant. An
+ * invalid control that won't take focus (disabled, hidden) is skipped for the
+ * next one. Call it after `await form.handleSubmit()` leaves the form invalid.
+ * Searching only `root` keeps focus inside the submitted form, so a dialog's
+ * form never sends it to the page behind. Returns the focused element, or
+ * `null`.
+ */
+function focusFirstInvalid(
+  root: ParentNode | null | undefined
+): HTMLElement | null {
+  const invalid = root?.querySelectorAll<HTMLElement>('[aria-invalid="true"]')
+  for (const element of invalid ?? []) {
+    for (const target of [
+      element,
+      ...element.querySelectorAll<HTMLElement>("*"),
+    ]) {
+      if (target.tabIndex < 0) {
+        continue
+      }
+      target.focus()
+      if (target.ownerDocument.activeElement === target) {
+        return target
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Give focus back to `element`, what had it when the submit started, if the
+ * submit dropped it to the body. A submit button that disables itself while
+ * submitting does that in browsers, so a failed submit with no invalid field
+ * to focus would otherwise leave the user nowhere. It doesn't scroll, so a
+ * user who scrolled away during a slow submit stays put. Returns whether it
+ * moved focus.
+ */
+function restoreFocus(element: Element | null): boolean {
+  if (!(element instanceof HTMLElement && element.isConnected)) {
+    return false
+  }
+  const active = element.ownerDocument.activeElement
+  if (active !== null && active !== element.ownerDocument.body) {
+    return false
+  }
+  element.focus({ preventScroll: true })
+  return element.ownerDocument.activeElement === element
+}
+
+export { focusFirstInvalid, restoreFocus }

package/src/lib/submit-action.ts

@@ -8,6 +8,7 @@ import {
 } from "./action-result"
 import { applyValidationError } from "./apply-validation-error"
 import { ValidationError } from "./validation-error"
+import { getFormSchema } from "./validation-modes"
 
 // Write an action's failure onto the form. Field messages go through
 // `applyValidationError`, so they live in `errorMap.onChange` and clear the
@@ -110,7 +111,9 @@ type SubmitActionSchemaOptions<TValues, TOutput, TData> = SubmitActionOptions<
   /**
    * 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>
 }
@@ -120,9 +123,13 @@ type SubmitActionSchemaOptions<TValues, TOutput, TData> = SubmitActionOptions<
  * 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
@@ -145,10 +152,17 @@ async function submitAction(
   options: { reset?: unknown; schema?: SubmitActionSchema<unknown> } = {}
 ): Promise<ActionResult<unknown>> {
   const { formApi, value } = props
+  // `useForm` types its schema as `StandardSchema<Values>`, so the output
+  // still fits the `TValues` the action is typed against.
+  const schema =
+    options.schema ??
+    (getFormSchema(formApi as AnyFormApi) as
+      | SubmitActionSchema<unknown>
+      | undefined)
   let input: unknown = 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/src/lib/submit-error.ts

@@ -0,0 +1,133 @@
+"use client"
+
+import { useCallback, useSyncExternalStore } from "react"
+
+// A submit whose handler threw (a network failure, an unexpected server
+// error), kept per form so `FormError` can show it.
+//
+// Not written to TanStack's `errorMap`: any entry there makes the form
+// invalid, which disables `SubmitButton`, and `handleSubmit` then skips
+// `onSubmit` until an edit clears the entry. The user couldn't retry a failed
+// save as is.
+
+type SubmitErrorState = {
+  readonly submissionAttempts: number
+  readonly values: unknown
+}
+
+// The slice of a form the helpers read. Keyed by `store`, as the per-form
+// Zeno state is (`validation-modes.ts`): it is the one reference shared by
+// the `useForm()` result and the form API that fields and context receive.
+type SubmitErrorForm = {
+  readonly state: SubmitErrorState
+  readonly store: {
+    subscribe: (listener: () => void) => { unsubscribe: () => void }
+  }
+}
+
+type SubmitError = {
+  /** What the submit handler threw. */
+  readonly error: unknown
+}
+
+type Entry = {
+  readonly submitError: SubmitError
+  readonly unsubscribe: () => void
+}
+
+const entries = new WeakMap<object, Entry>()
+const listeners = new WeakMap<object, Set<() => void>>()
+
+function notify(key: object): void {
+  for (const listener of listeners.get(key) ?? []) {
+    listener()
+  }
+}
+
+function clear(key: object): void {
+  const entry = entries.get(key)
+  if (entry) {
+    entry.unsubscribe()
+    entries.delete(key)
+    notify(key)
+  }
+}
+
+// Next.js `redirect()`, `notFound()`, `forbidden()` and `unauthorized()` throw
+// an error whose `digest` starts with `NEXT_`, and a server action that calls
+// one rejects with it on the client. Next navigates on its own: no failure.
+function isNavigationError(error: unknown): boolean {
+  if (typeof error !== "object" || error === null || !("digest" in error)) {
+    return false
+  }
+  return typeof error.digest === "string" && error.digest.startsWith("NEXT_")
+}
+
+/**
+ * Record that `form`'s submit threw `error`. `useForm` calls it for what
+ * `onSubmit` throws; call it for a failure your own submit code catches
+ * outside `onSubmit`. The error lasts until the values change or the next
+ * submit starts (`reset()` does both), so an edit or a retry clears it. A
+ * Next.js navigation (`redirect()`, `notFound()`) is ignored.
+ */
+function setSubmitError(form: SubmitErrorForm, error: unknown): void {
+  if (isNavigationError(error)) {
+    return
+  }
+  const key = form.store
+  entries.get(key)?.unsubscribe()
+  const { submissionAttempts, values } = form.state
+  // Dropped, not just hidden, once stale: a reset restores the attempt count
+  // and can restore the same values object, which would bring it back.
+  const subscription = form.store.subscribe(() => {
+    const { state } = form
+    if (
+      state.values !== values ||
+      state.submissionAttempts !== submissionAttempts
+    ) {
+      clear(key)
+    }
+  })
+  entries.set(key, {
+    submitError: { error },
+    unsubscribe: subscription.unsubscribe,
+  })
+  notify(key)
+}
+
+/**
+ * Report a submit rejection that is caught so the user can retry, as
+ * `<Form>` and `FormDialog` do: `reportError` logs it and passes it to the
+ * page's `error` listeners (where error monitoring hooks in), as if it were
+ * uncaught. A Next.js navigation is skipped.
+ */
+function reportSubmitError(error: unknown): void {
+  if (!isNavigationError(error)) {
+    // Missing in jsdom and older browsers.
+    globalThis.reportError?.(error)
+  }
+}
+
+/** The error `form`'s last submit threw, until it went stale. */
+function useSubmitError(form: SubmitErrorForm): SubmitError | undefined {
+  const key = form.store
+  const subscribe = useCallback(
+    (listener: () => void) => {
+      const set = listeners.get(key) ?? new Set()
+      listeners.set(key, set)
+      set.add(listener)
+      return () => {
+        set.delete(listener)
+      }
+    },
+    [key]
+  )
+  return useSyncExternalStore(
+    subscribe,
+    () => entries.get(key)?.submitError,
+    () => undefined
+  )
+}
+
+export type { SubmitError, SubmitErrorForm }
+export { reportSubmitError, setSubmitError, useSubmitError }

package/src/lib/use-field-control.ts

@@ -0,0 +1,181 @@
+"use client"
+
+import type { AnyFieldMeta } from "@tanstack/react-form"
+import { type ReactNode, useCallback, useId } from "react"
+
+import { describedBy } from "./aria"
+import { useFieldContext } from "./contexts"
+import { emptyValueFor } from "./empty-value"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsFieldRequiredBySchema,
+  useIsInvalid,
+} from "./use-is-invalid"
+import { getFormSchema } from "./validation-modes"
+
+type UseFieldControlOptions = {
+  /**
+   * The description the field renders, if any. The control is described by
+   * it, and by the error while one shows.
+   */
+  description?: ReactNode
+  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
+  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
+  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
+}
+
+function isEmpty(value: unknown): boolean {
+  return (
+    value === null ||
+    value === undefined ||
+    value === "" ||
+    Number.isNaN(value) ||
+    (Array.isArray(value) && value.length === 0)
+  )
+}
+
+// A React synthetic event, from spreading the control props on a native input
+// or an event-emitting component. Storing it would put the event in the form.
+function isSyntheticEvent(value: unknown): boolean {
+  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<TValue = unknown>({
+  description,
+  disabled,
+  label,
+  required,
+}: UseFieldControlOptions = {}): FieldControl<TValue> {
+  const field = useFieldContext<TValue>()
+  const id = useId()
+  const labelId = label ? `${id}-label` : undefined
+  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
+  // `field` is rebuilt on every value change; these members aren't, so a
+  // control that memoizes on `onChange` doesn't see a new one each render.
+  const { form, handleBlur, handleChange, name } = field
+  const onChange = useCallback(
+    (value: TValue) => {
+      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
+            ) as TValue)
+          : value
+      )
+    },
+    [form, handleChange, name]
+  )
+
+  return {
+    controlProps: {
+      "aria-describedby": describedBy(
+        [description, descriptionId],
+        [showError, errorId]
+      ),
+      "aria-invalid": isInvalid || undefined,
+      "aria-labelledby": labelId,
+      "aria-required": isRequired || undefined,
+      disabled,
+      id,
+      name,
+      onBlur: handleBlur,
+      onChange,
+      value: field.state.value,
+    },
+    descriptionId,
+    errorId,
+    errors: showError ? field.state.meta.errors : [],
+    id,
+    isInvalid,
+    isRequired,
+    labelId,
+    name,
+    showRequiredIndicator: required ?? schemaRequired,
+  }
+}
+
+export type { FieldControl, FieldControlProps, UseFieldControlOptions }
+export { useFieldControl }

package/src/lib/use-form-dialog.ts

@@ -97,6 +97,11 @@ function useFormDialog<TValues>(
 type UseLeaveGuardOptions = {
   /** Whether leaving now would lose changes. */
   hasUnsavedChanges: boolean
+  /**
+   * Save the changes and resolve whether that worked. Backs `saveAndLeave`,
+   * so the confirm UI can offer Save next to Discard.
+   */
+  onSave?: () => boolean | Promise<boolean>
 }
 
 type LeaveGuard = {
@@ -111,14 +116,25 @@ type LeaveGuard = {
   confirmLeave: () => void
   /** The user chose to stay: drop the held leave. */
   cancelLeave: () => void
+  /**
+   * The user chose to save: run `onSave`, then the held leave if it saved.
+   * Either way the confirm UI closes; after a failed save the user stays.
+   * Resolves whether it saved. A rejection from `onSave` keeps the leave held
+   * and propagates.
+   */
+  saveAndLeave: () => Promise<boolean>
+  /** Whether `saveAndLeave` is waiting on `onSave`. */
+  isSaving: boolean
 }
 
 /** Ask before a leave (close, navigate, switch record) drops unsaved changes. */
 function useLeaveGuard({
   hasUnsavedChanges,
+  onSave,
 }: UseLeaveGuardOptions): LeaveGuard {
   const pending = useRef<(() => void) | null>(null)
   const [isConfirming, setIsConfirming] = useState(false)
+  const [isSaving, setIsSaving] = useState(false)
 
   const requestLeave = useCallback(
     (proceed: () => void) => {
@@ -144,7 +160,39 @@ function useLeaveGuard({
     setIsConfirming(false)
   }, [])
 
-  return { cancelLeave, confirmLeave, isConfirming, requestLeave }
+  const saveAndLeave = useCallback(async () => {
+    const proceed = pending.current
+    if (!(proceed && onSave)) {
+      return false
+    }
+    setIsSaving(true)
+    let saved = false
+    try {
+      saved = await onSave()
+    } finally {
+      setIsSaving(false)
+    }
+    // Answered otherwise while saving (cancelled, or a newer leave replaced
+    // this one): leave that answer alone.
+    if (pending.current !== proceed) {
+      return saved
+    }
+    pending.current = null
+    setIsConfirming(false)
+    if (saved) {
+      proceed()
+    }
+    return saved
+  }, [onSave])
+
+  return {
+    cancelLeave,
+    confirmLeave,
+    isConfirming,
+    isSaving,
+    requestLeave,
+    saveAndLeave,
+  }
 }
 
 const FOCUSABLE =

package/src/submit-action.test.tsx

@@ -244,6 +244,109 @@ describe("submitAction — field errors from the action", () => {
 })
 
 describe("submitAction — schema", () => {
+  test("parses with the form's own schema, and reset: true rebases on what the action saved", async () => {
+    const user = userEvent.setup()
+    const schema = z.object({ age: z.coerce.number(), name: z.string().trim() })
+    type Values = z.input<typeof schema>
+    const action = vi.fn((input: Values) =>
+      Promise.resolve<ActionResult<Values>>({ data: input, ok: true })
+    )
+    const formRef: { current: unknown } = { current: undefined }
+    function Harness() {
+      const form = useForm({
+        defaultValues: { age: "42", name: " Ada " },
+        onSubmit: (submit) => submitAction(submit, action, { reset: true }),
+        schema,
+      })
+      formRef.current = form
+      const { InputField, SubmitButton } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField label="Name" name="name" />
+            <SubmitButton>Submit</SubmitButton>
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<Harness />)
+
+    await user.click(screen.getByRole("button", SUBMIT))
+
+    await vi.waitFor(() =>
+      expect(action).toHaveBeenCalledWith({ age: 42, name: "Ada" })
+    )
+    const form = formRef.current as {
+      state: { isDefaultValue: boolean; values: Values }
+    }
+    await vi.waitFor(() =>
+      expect(form.state.values).toEqual({ age: 42, name: "Ada" })
+    )
+    expect(form.state.isDefaultValue).toBe(true)
+  })
+
+  test("an explicit schema wins over the form's", async () => {
+    const user = userEvent.setup()
+    const action = vi.fn((_input: { name: string }) =>
+      Promise.resolve<ActionResult<null>>({ data: null, ok: true })
+    )
+    const actionSchema = z.object({ name: z.string().toUpperCase() })
+    function Harness() {
+      const form = useForm({
+        defaultValues: { name: " Ada " },
+        onSubmit: (submit) =>
+          submitAction(submit, action, { schema: actionSchema }),
+        schema: z.object({ name: z.string().trim() }),
+      })
+      const { InputField, SubmitButton } = form
+      return (
+        <FormProvider form={form}>
+          <Form>
+            <InputField label="Name" name="name" />
+            <SubmitButton>Submit</SubmitButton>
+          </Form>
+        </FormProvider>
+      )
+    }
+    render(<Harness />)
+
+    await user.click(screen.getByRole("button", SUBMIT))
+
+    await vi.waitFor(() =>
+      expect(action).toHaveBeenCalledWith({ name: " ADA " })
+    )
+  })
+
+  // A schema passed as a plain TanStack validator is not the form's schema:
+  // the action gets the values as they are, as before.
+  const trimmed = z.object({ name: z.string().trim() })
+
+  test("useForm without a schema sends the values as they are", async () => {
+    const user = userEvent.setup()
+    const action = vi.fn((_input: { name: string }) =>
+      Promise.resolve<ActionResult<null>>({ data: null, ok: true })
+    )
+    function Harness() {
+      const form = useForm({
+        defaultValues: { name: " Ada " },
+        onSubmit: (submit) => submitAction(submit, action),
+        validators: { onChange: trimmed },
+      })
+      return (
+        <button onClick={() => form.handleSubmit()} type="button">
+          Submit
+        </button>
+      )
+    }
+    render(<Harness />)
+
+    await user.click(screen.getByRole("button", SUBMIT))
+
+    await vi.waitFor(() =>
+      expect(action).toHaveBeenCalledWith({ name: " Ada " })
+    )
+  })
+
   test("passes the schema output to the action, not the input values", async () => {
     const user = userEvent.setup()
     const schema = z.object({