@zeno-lib/forms 0.0.0

package/src/form.tsx

@@ -0,0 +1,105 @@
+/* biome-ignore-all lint/performance/noBarrelFile: so consumers depend only on `@zeno-lib/forms`. */
+"use client"
+
+import { type AnyFormApi, createFormHook } from "@tanstack/react-form"
+import type { ComponentProps, FormEvent, ReactNode } from "react"
+
+import { CheckboxField } from "./fields/checkbox-field"
+import { ComboboxField } from "./fields/combobox-field"
+import { DatePickerField } from "./fields/date-picker-field"
+import { EmailField } from "./fields/email-field"
+import { InputField } from "./fields/input-field"
+import { NumberField } from "./fields/number-field"
+import { OtpField } from "./fields/otp-field"
+import { PasswordField } from "./fields/password-field"
+import { RadioGroupField } from "./fields/radio-group-field"
+import { ResetButton } from "./fields/reset-button"
+import { SelectField } from "./fields/select-field"
+import { SliderField } from "./fields/slider-field"
+import { SubmitButton } from "./fields/submit-button"
+import { SwitchField } from "./fields/switch-field"
+import { TextAreaField } from "./fields/textarea-field"
+import {
+  fieldContext,
+  formContext,
+  FormProvider as RawFormProvider,
+  useFormContext,
+} from "./lib/contexts"
+
+export * from "./addons"
+export { RadioGroupFieldItem } from "./fields/radio-group-field"
+export { applyValidationError } from "./lib/apply-validation-error"
+export { useFieldContext, useFormContext } from "./lib/contexts"
+export {
+  RequiredIndicator,
+  type RequiredIndicatorProps,
+} from "./lib/required-indicator"
+export {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "./lib/use-is-invalid"
+export { type FieldMessage, ValidationError } from "./lib/validation-error"
+export { blurThenChangeLogic } from "./lib/validation-logic"
+export type { ValidationMode } from "./lib/validation-modes"
+export { useAppFields } from "./use-app-fields"
+export { useForm } from "./use-form"
+
+const { useAppForm, withFieldGroup, withForm } = createFormHook({
+  fieldComponents: {
+    CheckboxField,
+    ComboboxField,
+    DatePickerField,
+    EmailField,
+    InputField,
+    NumberField,
+    OtpField,
+    PasswordField,
+    RadioGroupField,
+    SelectField,
+    SliderField,
+    SwitchField,
+    TextAreaField,
+  },
+  fieldContext,
+  formComponents: {
+    ResetButton,
+    SubmitButton,
+  },
+  formContext,
+})
+
+export { useAppForm, withFieldGroup, withForm }
+
+type FormProviderProps = {
+  children: ReactNode
+  form: { handleSubmit: () => unknown }
+}
+
+function FormProvider({ children, form }: FormProviderProps) {
+  return (
+    <RawFormProvider value={form as AnyFormApi}>{children}</RawFormProvider>
+  )
+}
+
+type FormProps = Omit<ComponentProps<"form">, "onSubmit">
+
+function Form({ children, className, ...props }: FormProps) {
+  const form = useFormContext()
+  return (
+    <form
+      className={className}
+      noValidate
+      onSubmit={(event: FormEvent<HTMLFormElement>) => {
+        event.preventDefault()
+        event.stopPropagation()
+        Promise.resolve(form.handleSubmit()).catch(() => undefined)
+      }}
+      {...props}
+    >
+      {children}
+    </form>
+  )
+}
+
+export { Form, FormProvider }

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

@@ -0,0 +1,97 @@
+import type { AnyFormApi } from "@tanstack/react-form"
+import { describe, expect, test, vi } from "@zeno-lib/vitest"
+
+import { applyValidationError } from "./apply-validation-error"
+import { ValidationError } from "./validation-error"
+
+type FieldMetaUpdater = (prev: {
+  errorMap?: Record<string, unknown>
+  errors?: unknown[]
+}) => unknown
+
+function makeFormStub() {
+  const setFieldMeta = vi.fn(
+    (_name: string, _updater: FieldMetaUpdater) => undefined
+  )
+  const setErrorMap = vi.fn((_map: unknown) => undefined)
+  return {
+    api: { setErrorMap, setFieldMeta } as unknown as AnyFormApi,
+    setErrorMap,
+    setFieldMeta,
+  }
+}
+
+describe("applyValidationError", () => {
+  test("writes single string message to errorMap.onChange and errors array", () => {
+    const { api, setFieldMeta } = makeFormStub()
+    applyValidationError(api, new ValidationError({ email: "Taken" }))
+    expect(setFieldMeta).toHaveBeenCalledTimes(1)
+    const [name, updater] = setFieldMeta.mock.calls[0] as [
+      string,
+      FieldMetaUpdater,
+    ]
+    expect(name).toBe("email")
+    const next = updater({}) as {
+      errors: { message: string }[]
+      errorMap: { onChange: { message: string } }
+      isValid: boolean
+    }
+    expect(next.errors).toEqual([{ message: "Taken" }])
+    expect(next.errorMap.onChange).toEqual({ message: "Taken" })
+    expect(next.isValid).toBe(false)
+  })
+
+  test("array of messages forwards all entries; errorMap.onChange gets first", () => {
+    const { api, setFieldMeta } = makeFormStub()
+    applyValidationError(
+      api,
+      new ValidationError({ password: ["short", "no digit"] })
+    )
+    const updater = setFieldMeta.mock.calls[0]?.[1] as FieldMetaUpdater
+    const next = updater({}) as {
+      errors: { message: string }[]
+      errorMap: { onChange: { message: string } }
+    }
+    expect(next.errors).toEqual([{ message: "short" }, { message: "no digit" }])
+    expect(next.errorMap.onChange).toEqual({ message: "short" })
+  })
+
+  test("preserves existing errorMap keys via spread", () => {
+    const { api, setFieldMeta } = makeFormStub()
+    applyValidationError(api, new ValidationError({ email: "Taken" }))
+    const updater = setFieldMeta.mock.calls[0]?.[1] as FieldMetaUpdater
+    const next = updater({ errorMap: { onBlur: { message: "Old" } } }) as {
+      errorMap: { onBlur: { message: string }; onChange: { message: string } }
+    }
+    expect(next.errorMap.onBlur).toEqual({ message: "Old" })
+    expect(next.errorMap.onChange).toEqual({ message: "Taken" })
+  })
+
+  test("formError populates form-level error map via setErrorMap", () => {
+    const { api, setErrorMap } = makeFormStub()
+    applyValidationError(
+      api,
+      new ValidationError({ email: "Taken" }, { formError: "Server down" })
+    )
+    expect(setErrorMap).toHaveBeenCalledWith({
+      onSubmit: { fields: {}, form: "Server down" },
+    })
+  })
+
+  test("no formError → setErrorMap not called", () => {
+    const { api, setErrorMap } = makeFormStub()
+    applyValidationError(api, new ValidationError({ email: "Taken" }))
+    expect(setErrorMap).not.toHaveBeenCalled()
+  })
+
+  test("multiple fields → setFieldMeta called per field", () => {
+    const { api, setFieldMeta } = makeFormStub()
+    applyValidationError(
+      api,
+      new ValidationError({ email: "Taken", name: "Required" })
+    )
+    expect(setFieldMeta).toHaveBeenCalledTimes(2)
+    const names = setFieldMeta.mock.calls.map((c) => c[0])
+    expect(names).toEqual(expect.arrayContaining(["email", "name"]))
+  })
+})

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

@@ -0,0 +1,31 @@
+import type { AnyFormApi } from "@tanstack/react-form"
+
+import type { ValidationError } from "./validation-error"
+
+// Write per-field messages from a `ValidationError` onto the form. We target
+// `errorMap.onChange` so the form-level schema overwrites the message as
+// soon as the user edits the field; the error clears automatically the
+// moment the value passes validation. Form-level error message is written
+// to the form's overall error map under the `onSubmit` cause.
+function applyValidationError(
+  formApi: AnyFormApi,
+  error: ValidationError
+): void {
+  for (const [name, message] of Object.entries(error.fields)) {
+    const messages = Array.isArray(message) ? message : [message]
+    const errors = messages.map((m) => ({ message: m }))
+    formApi.setFieldMeta(name, (prev) => ({
+      ...prev,
+      errorMap: { ...prev.errorMap, onChange: errors[0] },
+      errors,
+      isValid: false,
+    }))
+  }
+  if (error.formError) {
+    formApi.setErrorMap({
+      onSubmit: { fields: {}, form: error.formError },
+    })
+  }
+}
+
+export { applyValidationError }

package/src/lib/aria.ts

@@ -0,0 +1,7 @@
+// Builds an aria-describedby string from [condition, id] pairs; only ids with a truthy condition are included.
+export function describedBy(
+  ...entries: [unknown, string][]
+): string | undefined {
+  const ids = entries.filter(([show]) => Boolean(show)).map(([, id]) => id)
+  return ids.length > 0 ? ids.join(" ") : undefined
+}

package/src/lib/contexts.ts

@@ -0,0 +1,9 @@
+"use client"
+
+import { createFormHookContexts } from "@tanstack/react-form"
+
+const { fieldContext, formContext, useFieldContext, useFormContext } =
+  createFormHookContexts()
+
+export { fieldContext, formContext, useFieldContext, useFormContext }
+export const FormProvider = formContext.Provider

package/src/lib/required-indicator.tsx

@@ -0,0 +1,22 @@
+"use client"
+
+import { cn } from "@zeno-lib/ui/lib/utils"
+import type { ComponentProps } from "react"
+
+type RequiredIndicatorProps = ComponentProps<"span">
+
+function RequiredIndicator({ className, ...props }: RequiredIndicatorProps) {
+  return (
+    <span
+      aria-hidden="true"
+      className={cn("text-destructive", className)}
+      data-slot="required-indicator"
+      {...props}
+    >
+      *
+    </span>
+  )
+}
+
+export type { RequiredIndicatorProps }
+export { RequiredIndicator }

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

@@ -0,0 +1,195 @@
+import { describe, expect, test } from "@zeno-lib/vitest"
+import { z } from "zod"
+
+import { deepMergeDefaults, extractZodDefaults } from "./schema-defaults"
+
+describe("extractZodDefaults — primitives", () => {
+  test("z.string() → ''", () => {
+    expect(extractZodDefaults(z.object({ x: z.string() }))).toEqual({ x: "" })
+  })
+
+  test("z.email() / z.url() / z.uuid() → ''", () => {
+    const schema = z.object({
+      email: z.email(),
+      id: z.uuid(),
+      url: z.url(),
+    })
+    expect(extractZodDefaults(schema)).toEqual({ email: "", id: "", url: "" })
+  })
+
+  test("z.array(...) → []", () => {
+    expect(extractZodDefaults(z.object({ tags: z.array(z.string()) }))).toEqual(
+      { tags: [] }
+    )
+  })
+
+  test("z.number() / z.boolean() / z.date() are skipped", () => {
+    const schema = z.object({
+      active: z.boolean(),
+      age: z.number(),
+      created: z.date(),
+    })
+    expect(extractZodDefaults(schema)).toEqual({})
+  })
+
+  test("z.enum / z.literal are skipped", () => {
+    const schema = z.object({
+      kind: z.literal("a"),
+      role: z.enum(["admin", "user"]),
+    })
+    expect(extractZodDefaults(schema)).toEqual({})
+  })
+})
+
+describe("extractZodDefaults — wrappers", () => {
+  test(".default(value) flows through", () => {
+    const schema = z.object({
+      n: z.number().default(7),
+      role: z.string().default("member"),
+    })
+    expect(extractZodDefaults(schema)).toEqual({ n: 7, role: "member" })
+  })
+
+  test(".prefault(value) flows through", () => {
+    const schema = z.object({
+      role: z.prefault(z.string(), "guest"),
+    })
+    expect(extractZodDefaults(schema)).toEqual({ role: "guest" })
+  })
+
+  test(".optional() unwraps to inner string → ''", () => {
+    const schema = z.object({ x: z.string().optional() })
+    expect(extractZodDefaults(schema)).toEqual({ x: "" })
+  })
+
+  test(".nullable() unwraps to inner string → ''", () => {
+    const schema = z.object({ x: z.string().nullable() })
+    expect(extractZodDefaults(schema)).toEqual({ x: "" })
+  })
+
+  test(".readonly() unwraps to inner string → ''", () => {
+    const schema = z.object({ x: z.string().readonly() })
+    expect(extractZodDefaults(schema)).toEqual({ x: "" })
+  })
+
+  test("z.pipe uses the in side", () => {
+    const schema = z.object({
+      n: z.string().pipe(z.coerce.number()),
+    })
+    // The `in` side is z.string() → ''
+    expect(extractZodDefaults(schema)).toEqual({ n: "" })
+  })
+
+  test(".optional() over a number is skipped", () => {
+    const schema = z.object({ x: z.number().optional() })
+    expect(extractZodDefaults(schema)).toEqual({})
+  })
+})
+
+describe("extractZodDefaults — nested objects", () => {
+  test("nested z.object recurses", () => {
+    const schema = z.object({
+      profile: z.object({
+        email: z.email(),
+        nick: z.string(),
+      }),
+    })
+    expect(extractZodDefaults(schema)).toEqual({
+      profile: { email: "", nick: "" },
+    })
+  })
+
+  test("empty nested object is skipped", () => {
+    const schema = z.object({
+      meta: z.object({
+        active: z.boolean(),
+        age: z.number(),
+      }),
+    })
+    expect(extractZodDefaults(schema)).toEqual({})
+  })
+
+  test("partial nested object produced when at least one leaf survives", () => {
+    const schema = z.object({
+      profile: z.object({
+        age: z.number(),
+        name: z.string(),
+      }),
+    })
+    expect(extractZodDefaults(schema)).toEqual({ profile: { name: "" } })
+  })
+})
+
+describe("extractZodDefaults — degrades safely", () => {
+  test("non-object root returns {}", () => {
+    expect(extractZodDefaults(z.string() as never)).toEqual({})
+  })
+
+  test("non-Zod schema returns {}", () => {
+    expect(
+      extractZodDefaults({} as Parameters<typeof extractZodDefaults>[0])
+    ).toEqual({})
+  })
+
+  test("MAX_WRAPPER_DEPTH=16 does not loop on adversarial chains", () => {
+    // Build a cyclic wrapper chain (innerType points back at itself).
+    const cyclic: { _zod: { def: unknown } } = {
+      _zod: { def: { innerType: null as unknown, type: "optional" } },
+    }
+    ;(cyclic._zod.def as { innerType: unknown }).innerType = cyclic
+    const root = {
+      _zod: { def: { shape: { x: cyclic }, type: "object" } },
+    } as unknown as Parameters<typeof extractZodDefaults>[0]
+    // Should bail out at MAX_WRAPPER_DEPTH and skip the field — not hang.
+    expect(extractZodDefaults(root)).toEqual({})
+  })
+})
+
+describe("deepMergeDefaults", () => {
+  test("undefined user defaults returns schema defaults reference", () => {
+    const schema = { a: 1, nested: { b: 2 } }
+    expect(deepMergeDefaults(schema, undefined)).toBe(schema)
+  })
+
+  test("scalar user value wins over schema scalar", () => {
+    expect(deepMergeDefaults({ a: 1, b: "x" }, { a: 5 })).toEqual({
+      a: 5,
+      b: "x",
+    })
+  })
+
+  test("plain object on both sides recurses", () => {
+    expect(
+      deepMergeDefaults({ nested: { a: 1, b: 2 } }, { nested: { b: 99 } })
+    ).toEqual({ nested: { a: 1, b: 99 } })
+  })
+
+  test("array is treated atomically (user replaces schema)", () => {
+    expect(deepMergeDefaults({ tags: ["a", "b"] }, { tags: ["c"] })).toEqual({
+      tags: ["c"],
+    })
+  })
+
+  test("Date is treated atomically", () => {
+    const schemaDate = new Date("2020-01-01")
+    const userDate = new Date("2030-01-01")
+    expect(deepMergeDefaults({ when: schemaDate }, { when: userDate })).toEqual(
+      { when: userDate }
+    )
+  })
+
+  test("user explicit undefined preserved (intentional reset)", () => {
+    expect(deepMergeDefaults({ a: 1, b: 2 }, { a: undefined })).toEqual({
+      a: undefined,
+      b: 2,
+    })
+  })
+
+  test("key only present in user value flows through", () => {
+    expect(deepMergeDefaults({ a: 1 }, { b: 2 })).toEqual({ a: 1, b: 2 })
+  })
+
+  test("schema object + user scalar → user wins (no merge attempt)", () => {
+    expect(deepMergeDefaults({ x: { a: 1 } }, { x: null })).toEqual({ x: null })
+  })
+})

package/src/lib/schema-defaults.ts

@@ -0,0 +1,127 @@
+// Extract default values from a Zod schema for `useForm`.
+//
+// Tier A+ semantics:
+//   - `.default(...)` / `.prefault(...)` values flow through.
+//   - Strings (and string-format subtypes — email, url, uuid, regex, …) without
+//     a default fall back to `""` so React inputs render controlled.
+//   - Arrays without a default fall back to `[]`.
+//   - Nested `z.object(...)` recurses; emits a sub-record only if at least one
+//     leaf produced a value.
+//   - Numbers, booleans, dates, enums, unions, intersections, files, literals,
+//     etc. are skipped — those carry domain meaning and the user supplies them
+//     explicitly via `defaultValues`.
+//
+// Standard Schema doesn't expose introspection; this is Zod-only and reads
+// `_zod.def` (Zod v4). For non-Zod schemas (or unrecognised shapes) every entry
+// silently degrades to "skip", and the user's `defaultValues` flows through
+// untouched. Async schemas, lazy schemas, and any throw inside the walk also
+// degrade to "skip" — never bring the form down.
+
+type SchemaNode = { readonly _zod?: { readonly def?: SchemaDef } }
+
+type SchemaDef = {
+  readonly type?: string
+  readonly innerType?: SchemaNode
+  readonly shape?: Record<string, SchemaNode>
+  readonly in?: SchemaNode
+  readonly defaultValue?: unknown
+}
+
+const MAX_WRAPPER_DEPTH = 16
+
+type ExtractResult = { ok: true; value: unknown } | { ok: false }
+
+function getDef(node: SchemaNode | undefined): SchemaDef | undefined {
+  return node?._zod?.def
+}
+
+function extractDefaultForField(node: SchemaNode): ExtractResult {
+  let current: SchemaNode | undefined = node
+  for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth++) {
+    const def: SchemaDef | undefined = getDef(current)
+    if (!def?.type) {
+      return { ok: false }
+    }
+    switch (def.type) {
+      case "default":
+      case "prefault":
+        return { ok: true, value: def.defaultValue }
+      case "optional":
+      case "nullable":
+      case "nonoptional":
+      case "readonly":
+        current = def.innerType
+        continue
+      case "pipe":
+        current = def.in
+        continue
+      case "string":
+        return { ok: true, value: "" }
+      case "array":
+        return { ok: true, value: [] }
+      case "object": {
+        const nested = current ? extractZodDefaults(current) : {}
+        return Object.keys(nested).length > 0
+          ? { ok: true, value: nested }
+          : { ok: false }
+      }
+      default:
+        return { ok: false }
+    }
+  }
+  return { ok: false }
+}
+
+function extractZodDefaults(schema: SchemaNode): Record<string, unknown> {
+  try {
+    const def: SchemaDef | undefined = getDef(schema)
+    if (def?.type !== "object" || !def.shape) {
+      return {}
+    }
+    const result: Record<string, unknown> = {}
+    for (const [key, field] of Object.entries(def.shape)) {
+      const extracted = extractDefaultForField(field)
+      if (extracted.ok) {
+        result[key] = extracted.value
+      }
+    }
+    return result
+  } catch {
+    return {}
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.getPrototypeOf(value) === Object.prototype
+  )
+}
+
+// User-supplied values always win on conflict. Plain objects on both sides
+// recurse so nested `z.object(...)` defaults aren't clobbered by partial user
+// objects. Arrays, dates, class instances are treated atomically (user value
+// replaces schema value wholesale). User-explicit `undefined` is preserved as
+// an intentional reset.
+function deepMergeDefaults(
+  schemaDefaults: Record<string, unknown>,
+  userDefaults: Record<string, unknown> | undefined
+): Record<string, unknown> {
+  if (!userDefaults) {
+    return schemaDefaults
+  }
+  const result: Record<string, unknown> = { ...schemaDefaults }
+  for (const key of Object.keys(userDefaults)) {
+    const userValue = userDefaults[key]
+    const schemaValue = schemaDefaults[key]
+    if (isPlainObject(schemaValue) && isPlainObject(userValue)) {
+      result[key] = deepMergeDefaults(schemaValue, userValue)
+    } else {
+      result[key] = userValue
+    }
+  }
+  return result
+}
+
+export { deepMergeDefaults, extractZodDefaults }