@zeno-lib/forms 0.0.0

package/src/lib/schema-required.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, test } from "@zeno-lib/vitest"
+import { z } from "zod"
+
+import { getRequiredPaths, type StandardSchemaLike } from "./schema-required"
+
+describe("getRequiredPaths", () => {
+  test("plain required fields appear in the set", () => {
+    const schema = z.object({
+      email: z.email(),
+      name: z.string().min(1),
+    })
+    const required = getRequiredPaths(schema)
+    expect(required.has("email")).toBe(true)
+    expect(required.has("name")).toBe(true)
+  })
+
+  test(".optional() fields do not appear", () => {
+    const schema = z.object({
+      email: z.email(),
+      nickname: z.string().optional(),
+    })
+    const required = getRequiredPaths(schema)
+    expect(required.has("email")).toBe(true)
+    expect(required.has("nickname")).toBe(false)
+  })
+
+  test(".default(...) fields do not appear", () => {
+    const schema = z.object({
+      email: z.email(),
+      role: z.string().default("member"),
+    })
+    const required = getRequiredPaths(schema)
+    expect(required.has("email")).toBe(true)
+    expect(required.has("role")).toBe(false)
+  })
+
+  test("nested z.object reports the top-level key when missing", () => {
+    // Probing with `{}` only reveals the top-level required key; Zod never
+    // recurses past a missing parent.
+    const schema = z.object({
+      profile: z.object({
+        email: z.email(),
+      }),
+    })
+    const required = getRequiredPaths(schema)
+    expect(required.has("profile")).toBe(true)
+    expect(required.has("profile.email")).toBe(false)
+  })
+
+  test("dot-joined path is built when issues carry multi-segment paths", () => {
+    // Whether Zod surfaces nested paths depends on schema shape (defaults,
+    // refine targets, etc.). We exercise the path-joining itself via a
+    // stand-in schema that emits a multi-segment issue path.
+    const schema = {
+      "~standard": {
+        validate: () => ({
+          issues: [{ path: ["profile", "email"] }],
+        }),
+      },
+    }
+    const required = getRequiredPaths(schema)
+    expect(required.has("profile.email")).toBe(true)
+  })
+
+  test(".refine() cross-field issues are tolerated (do not crash)", () => {
+    const schema = z
+      .object({
+        confirm: z.string().min(8),
+        password: z.string().min(8),
+      })
+      .refine((value) => value.password === value.confirm, {
+        message: "Passwords must match",
+        path: ["confirm"],
+      })
+    expect(() => getRequiredPaths(schema)).not.toThrow()
+  })
+
+  test("async schema returns empty set", () => {
+    const asyncSchema: StandardSchemaLike = {
+      "~standard": {
+        validate: (_: unknown) =>
+          Promise.resolve({ value: undefined } as { value: unknown }),
+      },
+    }
+    expect(getRequiredPaths(asyncSchema).size).toBe(0)
+  })
+
+  test("throwing schema returns empty set", () => {
+    const throwing: StandardSchemaLike = {
+      "~standard": {
+        validate: () => {
+          throw new Error("boom")
+        },
+      },
+    }
+    expect(getRequiredPaths(throwing).size).toBe(0)
+  })
+
+  test("schema returning no issues returns empty set", () => {
+    const empty: StandardSchemaLike = {
+      "~standard": {
+        validate: () => ({ value: undefined }),
+      },
+    }
+    expect(getRequiredPaths(empty).size).toBe(0)
+  })
+
+  test("path entries shaped like { key } (Valibot) are normalised", () => {
+    const valibotStyle: StandardSchemaLike = {
+      "~standard": {
+        validate: () => ({
+          issues: [
+            { path: [{ key: "profile" }, { key: "email" }] },
+            { path: ["plain"] },
+          ],
+        }),
+      },
+    }
+    const required = getRequiredPaths(valibotStyle)
+    expect(required.has("profile.email")).toBe(true)
+    expect(required.has("plain")).toBe(true)
+  })
+
+  test("issues with empty path are skipped (form-level only)", () => {
+    const formLevelOnly: StandardSchemaLike = {
+      "~standard": {
+        validate: () => ({ issues: [{ path: [] }] }),
+      },
+    }
+    expect(getRequiredPaths(formLevelOnly).size).toBe(0)
+  })
+})

package/src/lib/schema-required.ts

@@ -0,0 +1,64 @@
+// Inspect a Standard Schema to discover which field paths it treats as required.
+//
+// Standard Schema (Zod, Valibot, ArkType, …) doesn't expose introspection — only
+// a `validate(value)` function. We probe by validating an empty object: every
+// field that is *required* (i.e. not optional, nullable, or defaulted) emits an
+// issue with a `path` we can record. Fields with defaults or `.optional()` stay
+// silent because the schema considers them satisfied.
+//
+// Limitations:
+//   - Async schemas are skipped (returns an empty set). Required-ness is a
+//     visual hint; the validator itself still runs at submit time.
+//   - Cross-field refinements that fail on `{}` may flag fields that aren't
+//     intrinsically required. In practice this is the same heuristic users
+//     would apply by eye.
+
+type StandardIssue = {
+  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>
+}
+
+type StandardSchemaLike = {
+  readonly "~standard": {
+    readonly validate: (
+      value: unknown
+    ) =>
+      | { readonly value: unknown }
+      | { readonly issues: readonly StandardIssue[] }
+      | Promise<unknown>
+  }
+}
+
+function pathSegment(
+  part: PropertyKey | { readonly key: PropertyKey }
+): string {
+  if (typeof part === "object" && part !== null && "key" in part) {
+    return String(part.key)
+  }
+  return String(part)
+}
+
+function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
+  const required = new Set<string>()
+  let result: ReturnType<StandardSchemaLike["~standard"]["validate"]>
+  try {
+    result = schema["~standard"].validate({})
+  } catch {
+    return required
+  }
+  if (result instanceof Promise) {
+    return required
+  }
+  if (!("issues" in result && result.issues)) {
+    return required
+  }
+  for (const issue of result.issues) {
+    const segments = issue.path?.map(pathSegment) ?? []
+    if (segments.length > 0) {
+      required.add(segments.join("."))
+    }
+  }
+  return required
+}
+
+export type { StandardSchemaLike }
+export { getRequiredPaths }

package/src/lib/use-is-invalid.ts

@@ -0,0 +1,109 @@
+"use client"
+
+import { type AnyFieldApi, useStore } from "@tanstack/react-form"
+
+import {
+  getFormHideFieldErrors,
+  getFormValidationMode,
+  isFieldRequired,
+  type ValidationMode,
+} from "./validation-modes"
+
+type ErrorSourceMap = Record<string, "field" | "form" | undefined>
+
+const FIELD_LEVEL_CAUSES = ["onChange", "onBlur", "onSubmit"] as const
+
+// Has the user explicitly opted into a `validators={{ onChange | onBlur |
+// onSubmit }}` cause on this field? If yes, we honour the cause directly —
+// the form's `validation` mode does not gate per-field validators (a user
+// who wrote `onChange` expects live feedback, even if the form is in
+// `blur-then-change` mode).
+function hasFieldLevelError(
+  errorMap: Record<string, unknown> | undefined,
+  errorSourceMap: ErrorSourceMap | undefined,
+  cause: (typeof FIELD_LEVEL_CAUSES)[number]
+): boolean {
+  if (!(errorMap && errorSourceMap)) {
+    return false
+  }
+  return errorSourceMap[cause] === "field" && errorMap[cause] !== undefined
+}
+
+function modeAllowsDisplay(
+  mode: ValidationMode,
+  isDirty: boolean,
+  isBlurred: boolean,
+  wasSubmitted: boolean
+): boolean {
+  if (mode === "change") {
+    return isDirty || wasSubmitted
+  }
+  if (mode === "submit") {
+    return wasSubmitted
+  }
+  // 'blur' and 'blur-then-change'
+  return isBlurred || wasSubmitted
+}
+
+// Returns the "should we display errors?" gate for a field. The gate matches
+// the form's `validation` mode (set via `useForm({ validation })`):
+//
+//   - `change`           → show as soon as the user has typed (live)
+//   - `blur`             → show after first blur
+//   - `submit`           → show after first submit attempt
+//   - `blur-then-change` → show after first blur (default)
+//
+// All modes also show errors after a submit attempt, so a user who clicks
+// submit without ever interacting with required fields still sees them.
+//
+// Per-field validators bypass the form's mode entirely: an error written by
+// `validators={{ onChange }}` shows live (after first keystroke) regardless
+// of the form's gating, because the user explicitly opted into that cause.
+function useIsInvalid(field: AnyFieldApi): boolean {
+  const wasSubmitted = useStore(
+    field.form.store,
+    (state) => state.submissionAttempts > 0
+  )
+
+  if (field.state.meta.isValid) {
+    return false
+  }
+
+  const { isDirty, isBlurred, errorMap, errorSourceMap } = field.state.meta
+  const sourceMap = errorSourceMap as ErrorSourceMap | undefined
+
+  if (hasFieldLevelError(errorMap, sourceMap, "onChange")) {
+    return isDirty || wasSubmitted
+  }
+  if (hasFieldLevelError(errorMap, sourceMap, "onBlur")) {
+    return isBlurred || wasSubmitted
+  }
+  if (hasFieldLevelError(errorMap, sourceMap, "onSubmit")) {
+    return wasSubmitted
+  }
+
+  return modeAllowsDisplay(
+    getFormValidationMode(field.form),
+    isDirty,
+    isBlurred,
+    wasSubmitted
+  )
+}
+
+// Returns whether the form was configured to hide inline field errors via
+// `useForm({ hideFieldErrors: true })`. The shipped fields read this to
+// skip rendering their inline `<FieldError>` while still flipping
+// `data-invalid` / `aria-invalid` for invalid styling.
+function useHideFieldErrors(field: AnyFieldApi): boolean {
+  return getFormHideFieldErrors(field.form)
+}
+
+// Returns whether the form's schema marks this field as required. Drives the
+// inline `*` indicator next to field labels. Returns `false` when the form
+// has no schema, was constructed with `requiredIndicator: false`, or the
+// schema doesn't mark this field's path as required.
+function useIsFieldRequired(field: AnyFieldApi): boolean {
+  return isFieldRequired(field.form, field.name)
+}
+
+export { useHideFieldErrors, useIsFieldRequired, useIsInvalid }

package/src/lib/use-unsaved-changes-warning.ts

@@ -0,0 +1,57 @@
+"use client"
+
+import { type AnyFormApi, useStore } from "@tanstack/react-form"
+import { useEffect } from "react"
+
+type UnsavedChangesMode = "if-changed" | "if-touched"
+
+// Warn the user before they leave the page with unsaved changes.
+//
+// Two trigger modes, selected by the caller:
+//   - "if-changed" (default) — fires while current values differ from
+//     defaults (`!state.isDefaultValue`). Clears when the user restores
+//     the originals, or after `formApi.reset(value)` rebases defaults.
+//   - "if-touched" — fires after the user has edited any field, even if
+//     they reverted (`state.isDirty`, sticky once edited until reset).
+//
+// `isSubmitting` is always read so the listener detaches during the
+// submit round-trip — a successful submit transitions through
+// `isSubmitting=true` before the parent typically resets/navigates, and
+// we don't want a stale warning to fire in that window.
+//
+// Modern browsers ignore custom strings on `beforeunload` and show their
+// own generic prompt; we still set `returnValue` because some older
+// browsers and embedded webviews honour it.
+function useUnsavedChangesWarning(
+  form: AnyFormApi,
+  enabled: boolean | UnsavedChangesMode
+): void {
+  let mode: UnsavedChangesMode | null
+  if (enabled === false) {
+    mode = null
+  } else if (enabled === true) {
+    mode = "if-changed"
+  } else {
+    mode = enabled
+  }
+  const dirty = useStore(form.store, (state) =>
+    mode === "if-touched" ? state.isDirty : !state.isDefaultValue
+  )
+  const isSubmitting = useStore(form.store, (state) => state.isSubmitting)
+  const active = mode !== null && dirty && !isSubmitting
+
+  useEffect(() => {
+    if (!active) {
+      return
+    }
+    const handler = (event: BeforeUnloadEvent) => {
+      event.preventDefault()
+      event.returnValue = ""
+    }
+    window.addEventListener("beforeunload", handler)
+    return () => window.removeEventListener("beforeunload", handler)
+  }, [active])
+}
+
+export type { UnsavedChangesMode }
+export { useUnsavedChangesWarning }

package/src/lib/validation-error.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "@zeno-lib/vitest"
+
+import { ValidationError } from "./validation-error"
+
+describe("ValidationError", () => {
+  test("extends Error and sets name", () => {
+    const err = new ValidationError({ email: "Taken" })
+    expect(err).toBeInstanceOf(Error)
+    expect(err.name).toBe("ValidationError")
+  })
+
+  test("default message is 'Validation failed'", () => {
+    const err = new ValidationError({ email: "Taken" })
+    expect(err.message).toBe("Validation failed")
+  })
+
+  test("custom message via options.message", () => {
+    const err = new ValidationError({ email: "Taken" }, { message: "Boom" })
+    expect(err.message).toBe("Boom")
+  })
+
+  test("exposes fields and formError", () => {
+    const err = new ValidationError(
+      { email: "Taken", name: ["A", "B"] },
+      { formError: "Server down" }
+    )
+    expect(err.fields).toEqual({ email: "Taken", name: ["A", "B"] })
+    expect(err.formError).toBe("Server down")
+  })
+
+  test("formError is undefined when not provided", () => {
+    const err = new ValidationError({ email: "Taken" })
+    expect(err.formError).toBeUndefined()
+  })
+
+  test("accepts readonly array of messages for a field", () => {
+    const messages = ["too short", "missing digit"] as const
+    const err = new ValidationError({ password: messages })
+    expect(err.fields.password).toEqual(messages)
+  })
+})

package/src/lib/validation-error.ts

@@ -0,0 +1,30 @@
+// Throwable error that carries per-field validation messages. `useForm`
+// catches this inside `onSubmit` and writes each entry onto the matching
+// field's meta, so callers can `throw new ValidationError({ email: '…' })`
+// from anywhere (server response handler, custom async check, etc.) and have
+// the messages land in the right place.
+//
+// Errors are written to `errorMap.onChange`, which means the form-level
+// schema overwrites them as soon as the user edits the field — the message
+// clears automatically once the value changes. Pass an array of messages to
+// surface multiple issues for the same field.
+
+type FieldMessage = string | readonly string[]
+
+class ValidationError extends Error {
+  readonly fields: Readonly<Record<string, FieldMessage>>
+  readonly formError?: string
+
+  constructor(
+    fields: Readonly<Record<string, FieldMessage>>,
+    options: { formError?: string; message?: string } = {}
+  ) {
+    super(options.message ?? "Validation failed")
+    this.name = "ValidationError"
+    this.fields = fields
+    this.formError = options.formError
+  }
+}
+
+export type { FieldMessage }
+export { ValidationError }

package/src/lib/validation-logic.test.ts

@@ -0,0 +1,261 @@
+import type { AnyFormApi, ValidationLogicFn } from "@tanstack/react-form"
+import { describe, expect, test, vi } from "@zeno-lib/vitest"
+
+import { blurThenChangeLogic } from "./validation-logic"
+
+type LogicArgs = Parameters<ValidationLogicFn>[0]
+type Validators = LogicArgs["validators"]
+
+type ObservedValidator = {
+  cause: string
+  fn: unknown
+}
+
+function makeForm(overrides?: {
+  submissionAttempts?: number
+  blurredFieldNames?: string[]
+}) {
+  const fieldMeta: Record<string, { isBlurred: boolean }> = {}
+  for (const name of overrides?.blurredFieldNames ?? []) {
+    fieldMeta[name] = { isBlurred: true }
+  }
+  return {
+    state: {
+      fieldMeta,
+      submissionAttempts: overrides?.submissionAttempts ?? 0,
+    },
+  } as unknown as AnyFormApi
+}
+
+function makeRun() {
+  const observed: ObservedValidator[][] = []
+  const runValidation = vi.fn(
+    (props: { form: AnyFormApi; validators: ObservedValidator[] }) => {
+      observed.push(props.validators)
+      return
+    }
+  )
+  return { observed, runValidation }
+}
+
+const SCHEMA_FN = () => undefined
+const ASYNC_SCHEMA_FN = async () => undefined
+
+const SCHEMA_VALIDATORS: Validators = {
+  onBlur: SCHEMA_FN,
+  onChange: SCHEMA_FN,
+  onSubmit: SCHEMA_FN,
+} as unknown as Validators
+
+const SCHEMA_VALIDATORS_BLUR_ONLY: Validators = {
+  onBlur: SCHEMA_FN,
+  onSubmit: SCHEMA_FN,
+} as unknown as Validators
+
+const SCHEMA_VALIDATORS_ASYNC: Validators = {
+  onBlurAsync: ASYNC_SCHEMA_FN,
+  onChangeAsync: ASYNC_SCHEMA_FN,
+  onSubmitAsync: ASYNC_SCHEMA_FN,
+} as unknown as Validators
+
+describe("blurThenChangeLogic — form-level path", () => {
+  test("missing validators yields []", () => {
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: { async: false, type: "change" } as LogicArgs["event"],
+      form: makeForm(),
+      runValidation,
+      validators: undefined,
+    } as LogicArgs)
+    expect(observed[0]).toEqual([])
+  })
+
+  test("mount fires onMount only (sync)", () => {
+    const onMount = vi.fn()
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: { async: false, type: "mount" } as LogicArgs["event"],
+      form: makeForm(),
+      runValidation,
+      validators: { onMount } as unknown as Validators,
+    } as LogicArgs)
+    expect(observed[0]).toHaveLength(1)
+    expect(observed[0]?.[0]).toEqual({ cause: "mount", fn: onMount })
+  })
+
+  test("mount with async event yields [] (no async mount)", () => {
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: { async: true, type: "mount" } as LogicArgs["event"],
+      form: makeForm(),
+      runValidation,
+      validators: SCHEMA_VALIDATORS,
+    } as LogicArgs)
+    expect(observed[0]).toEqual([])
+  })
+
+  test("blur fires the live validator regardless of state", () => {
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: { async: false, type: "blur" } as LogicArgs["event"],
+      form: makeForm(),
+      runValidation,
+      validators: SCHEMA_VALIDATORS,
+    } as LogicArgs)
+    expect(observed[0]).toEqual([{ cause: "change", fn: SCHEMA_FN }])
+  })
+
+  test("blur falls back to onBlur when onChange is absent", () => {
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: { async: false, type: "blur" } as LogicArgs["event"],
+      form: makeForm(),
+      runValidation,
+      validators: SCHEMA_VALIDATORS_BLUR_ONLY,
+    } as LogicArgs)
+    expect(observed[0]).toEqual([{ cause: "change", fn: SCHEMA_FN }])
+  })
+
+  test("change while pristine yields [] (no field blurred, no submit)", () => {
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: { async: false, type: "change" } as LogicArgs["event"],
+      form: makeForm(),
+      runValidation,
+      validators: SCHEMA_VALIDATORS,
+    } as LogicArgs)
+    expect(observed[0]).toEqual([])
+  })
+
+  test("change after a field was blurred runs the live validator", () => {
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: { async: false, type: "change" } as LogicArgs["event"],
+      form: makeForm({ blurredFieldNames: ["email"] }),
+      runValidation,
+      validators: SCHEMA_VALIDATORS,
+    } as LogicArgs)
+    expect(observed[0]).toEqual([{ cause: "change", fn: SCHEMA_FN }])
+  })
+
+  test("change after a submit attempt runs the live validator", () => {
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: { async: false, type: "change" } as LogicArgs["event"],
+      form: makeForm({ submissionAttempts: 1 }),
+      runValidation,
+      validators: SCHEMA_VALIDATORS,
+    } as LogicArgs)
+    expect(observed[0]).toEqual([{ cause: "change", fn: SCHEMA_FN }])
+  })
+
+  test("sync submit yields live + submit + server placeholder", () => {
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: { async: false, type: "submit" } as LogicArgs["event"],
+      form: makeForm(),
+      runValidation,
+      validators: SCHEMA_VALIDATORS,
+    } as LogicArgs)
+    expect(observed[0]?.map((v) => v.cause)).toEqual([
+      "change",
+      "submit",
+      "server",
+    ])
+  })
+
+  test("async submit yields live + submitAsync only (no server placeholder)", () => {
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: { async: true, type: "submit" } as LogicArgs["event"],
+      form: makeForm(),
+      runValidation,
+      validators: SCHEMA_VALIDATORS_ASYNC,
+    } as LogicArgs)
+    expect(observed[0]?.map((v) => v.cause)).toEqual(["change", "submit"])
+  })
+})
+
+describe("blurThenChangeLogic — field-level path", () => {
+  function fieldEvent(
+    type: "change" | "blur" | "submit" | "mount",
+    async = false
+  ): LogicArgs["event"] {
+    return { async, fieldName: "email", type } as LogicArgs["event"]
+  }
+
+  test("field-level change uses validators.onChange directly (no gating)", () => {
+    const onChange = vi.fn()
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: fieldEvent("change"),
+      form: makeForm(),
+      runValidation,
+      validators: { onChange } as unknown as Validators,
+    } as LogicArgs)
+    expect(observed[0]).toEqual([{ cause: "change", fn: onChange }])
+  })
+
+  test("field-level blur uses validators.onBlur directly", () => {
+    const onBlur = vi.fn()
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: fieldEvent("blur"),
+      form: makeForm(),
+      runValidation,
+      validators: { onBlur } as unknown as Validators,
+    } as LogicArgs)
+    expect(observed[0]).toEqual([{ cause: "blur", fn: onBlur }])
+  })
+
+  test("field-level submit runs change + blur + submit", () => {
+    const onChange = vi.fn()
+    const onBlur = vi.fn()
+    const onSubmit = vi.fn()
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: fieldEvent("submit"),
+      form: makeForm(),
+      runValidation,
+      validators: { onBlur, onChange, onSubmit } as unknown as Validators,
+    } as LogicArgs)
+    expect(observed[0]?.map((v) => v.cause)).toEqual([
+      "change",
+      "blur",
+      "submit",
+    ])
+  })
+
+  test("field-level no validators yields []", () => {
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: fieldEvent("change"),
+      form: makeForm(),
+      runValidation,
+      validators: undefined,
+    } as LogicArgs)
+    expect(observed[0]).toEqual([])
+  })
+
+  test("field-level async submit uses async slots", () => {
+    const onChangeAsync = vi.fn()
+    const onBlurAsync = vi.fn()
+    const onSubmitAsync = vi.fn()
+    const { observed, runValidation } = makeRun()
+    blurThenChangeLogic({
+      event: fieldEvent("submit", true),
+      form: makeForm(),
+      runValidation,
+      validators: {
+        onBlurAsync,
+        onChangeAsync,
+        onSubmitAsync,
+      } as unknown as Validators,
+    } as LogicArgs)
+    expect(observed[0]?.map((v) => v.fn)).toEqual([
+      onChangeAsync,
+      onBlurAsync,
+      onSubmitAsync,
+    ])
+  })
+})