@zeno-lib/forms 0.2.2 → 0.4.0

package/src/fields/slider-field.tsx

@@ -7,7 +7,7 @@ import {
   useIsFieldRequired,
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
-import type { ComponentProps, ReactNode } from "react"
+import { type ComponentProps, type ReactNode, useId } from "react"
 import {
   Field,
   FieldContent,
@@ -43,8 +43,9 @@ function SliderField({
   ...props
 }: SliderFieldProps) {
   const field = useFieldContext<SliderValue>()
-  const errorId = `${field.name}-error`
-  const descriptionId = `${field.name}-description`
+  const id = useId()
+  const errorId = `${id}-error`
+  const descriptionId = `${id}-description`
   const isInvalid = useIsInvalid(field)
   const hideErrors = useHideFieldErrors(field)
   const showError = isInvalid && !hideErrors
@@ -61,7 +62,7 @@ function SliderField({
       {(label || hasReadout) && (
         <FieldContent className="flex-row items-center justify-between">
           {label && (
-            <FieldLabel htmlFor={field.name}>
+            <FieldLabel htmlFor={id}>
               {label}
               {isRequired && <RequiredIndicator />}
             </FieldLabel>
@@ -79,7 +80,7 @@ function SliderField({
           [showError, errorId]
         )}
         aria-invalid={isInvalid || undefined}
-        id={field.name}
+        id={id}
         name={field.name}
         onBlur={field.handleBlur}
         onValueChange={(next) => {

package/src/fields/switch-field.tsx

@@ -5,9 +5,10 @@ import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
+  useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
-import type { ComponentProps, ReactNode } from "react"
+import { type ComponentProps, type ReactNode, useId } from "react"
 import {
   Field,
   FieldContent,
@@ -24,7 +25,10 @@ type SwitchFieldProps = Omit<
 > & {
   description?: ReactNode
   label?: ReactNode
-  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
   required?: boolean
 }
 
@@ -35,13 +39,16 @@ function SwitchField({
   ...props
 }: SwitchFieldProps) {
   const field = useFieldContext<boolean>()
-  const errorId = `${field.name}-error`
-  const descriptionId = `${field.name}-description`
+  const id = useId()
+  const errorId = `${id}-error`
+  const descriptionId = `${id}-description`
   const isInvalid = useIsInvalid(field)
   const hideErrors = useHideFieldErrors(field)
   const showError = isInvalid && !hideErrors
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
 
   return (
     <Field
@@ -51,7 +58,7 @@ function SwitchField({
     >
       <FieldContent>
         {label && (
-          <FieldLabel htmlFor={field.name}>
+          <FieldLabel htmlFor={id}>
             {label}
             {isRequired && <RequiredIndicator />}
           </FieldLabel>
@@ -69,8 +76,9 @@ function SwitchField({
           [showError, errorId]
         )}
         aria-invalid={isInvalid || undefined}
+        aria-required={requiresValue || undefined}
         checked={field.state.value ?? false}
-        id={field.name}
+        id={id}
         name={field.name}
         onBlur={field.handleBlur}
         onCheckedChange={(value) => field.handleChange(value)}

package/src/fields/textarea-field.tsx

@@ -5,9 +5,10 @@ import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
 import {
   useHideFieldErrors,
   useIsFieldRequired,
+  useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "@zeno-lib/forms/lib/use-is-invalid"
-import { Children, type ComponentProps, type ReactNode } from "react"
+import { Children, type ComponentProps, type ReactNode, useId } from "react"
 import {
   Field,
   FieldDescription,
@@ -25,7 +26,10 @@ type TextAreaFieldProps = Omit<
   children?: ReactNode
   description?: ReactNode
   label?: ReactNode
-  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  /**
+   * Mark the field required, or not, over the schema. Drives the `*` and
+   * `aria-required`.
+   */
   required?: boolean
 }
 
@@ -37,14 +41,17 @@ function TextAreaField({
   ...props
 }: TextAreaFieldProps) {
   const field = useFieldContext<string>()
-  const errorId = `${field.name}-error`
-  const descriptionId = `${field.name}-description`
+  const id = useId()
+  const errorId = `${id}-error`
+  const descriptionId = `${id}-description`
   const isInvalid = useIsInvalid(field)
   const hideErrors = useHideFieldErrors(field)
   const showError = isInvalid && !hideErrors
   const hasAddons = Children.count(children) > 0
   const schemaRequired = useIsFieldRequired(field)
   const isRequired = required ?? schemaRequired
+  const schemaRequiresValue = useIsFieldRequiredBySchema(field)
+  const requiresValue = required ?? schemaRequiresValue
 
   const textareaProps = {
     "aria-describedby": describedBy(
@@ -52,7 +59,8 @@ function TextAreaField({
       [showError, errorId]
     ),
     "aria-invalid": isInvalid || undefined,
-    id: field.name,
+    "aria-required": requiresValue || undefined,
+    id,
     name: field.name,
     onBlur: field.handleBlur,
     onChange: (event: React.ChangeEvent<HTMLTextAreaElement>) =>
@@ -64,7 +72,7 @@ function TextAreaField({
   return (
     <Field data-field={field.name} data-invalid={isInvalid}>
       {label && (
-        <FieldLabel htmlFor={field.name}>
+        <FieldLabel htmlFor={id}>
           {label}
           {isRequired && <RequiredIndicator />}
         </FieldLabel>

package/src/fields/year-field.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { getEmptyValue } from "@zeno-lib/forms/lib/empty-value"
 import { useFormattedNumber } from "@zeno-lib/forms/lib/use-formatted-number"
 import { InputField, type InputFieldProps } from "./input-field"
 
@@ -36,7 +37,8 @@ function YearField({ max, min, ...props }: YearFieldProps) {
     maximumFractionDigits: 0,
     min,
     onBlur: field.handleBlur,
-    onValueChange: (next) => field.handleChange(next),
+    onValueChange: (next) =>
+      field.handleChange(next ?? getEmptyValue(field, null)),
     useGrouping: false,
     value: field.state.value,
   })

package/src/index.ts

@@ -1,5 +1,6 @@
 /* biome-ignore-all lint/performance/noBarrelFile: single npm entry for the headless form API. */
 
+export { useSelector } from "@tanstack/react-form"
 export { createZenoForm } from "./create-zeno-form"
 export { Form, FormProvider } from "./form-element"
 export {
@@ -20,6 +21,7 @@ export {
 export {
   useHideFieldErrors,
   useIsFieldRequired,
+  useIsFieldRequiredBySchema,
   useIsInvalid,
 } from "./lib/use-is-invalid"
 export { type FieldMessage, ValidationError } from "./lib/validation-error"

package/src/lib/empty-value.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "vitest"
+import { z } from "zod"
+
+import { emptyValueFor, withEmptyStartValues } from "./empty-value"
+import { extractZodDefaults } from "./schema-defaults"
+
+const FALLBACK = Symbol("fallback")
+
+function cleared(field: z.ZodType, name = "field", values: unknown = {}) {
+  return emptyValueFor(z.object({ field }), values, name, FALLBACK)
+}
+
+describe("emptyValueFor", () => {
+  test("null, then undefined, then the type's own empty value", () => {
+    expect(cleared(z.string().nullable())).toBeNull()
+    expect(cleared(z.string().optional())).toBeUndefined()
+    expect(cleared(z.string())).toBe("")
+    expect(cleared(z.array(z.string()))).toEqual([])
+    expect(cleared(z.uuid().nullable())).toBeNull()
+    expect(cleared(z.enum(["a", "b"]).optional())).toBeUndefined()
+    expect(cleared(z.number().nullable())).toBeNull()
+    expect(cleared(z.date().nullish())).toBeNull()
+  })
+
+  test("a field that accepts no empty value keeps the field's own fallback", () => {
+    expect(cleared(z.string().min(1))).toBe(FALLBACK)
+    expect(cleared(z.number())).toBe(FALLBACK)
+  })
+
+  test("array rows follow the row schema", () => {
+    const schema = z.object({
+      members: z.array(
+        z.object({
+          id: z.uuid().nullable(),
+          name: z.string(),
+          note: z.string().optional(),
+        })
+      ),
+    })
+    const values = { members: [{ id: "x" }, { id: "y" }] }
+    const at = (name: string) => emptyValueFor(schema, values, name, FALLBACK)
+    expect(at("members[1].id")).toBeNull()
+    expect(at("members[1].name")).toBe("")
+    expect(at("members[1].note")).toBeUndefined()
+  })
+
+  test("without a schema, or with an async one, the fallback stands", () => {
+    expect(emptyValueFor(undefined, {}, "field", FALLBACK)).toBe(FALLBACK)
+    const asyncSchema = z.object({
+      field: z.string().refine(async () => true),
+    })
+    expect(emptyValueFor(asyncSchema, {}, "field", FALLBACK)).toBe(FALLBACK)
+  })
+})
+
+describe("withEmptyStartValues", () => {
+  test('starts a field whose schema rejects `""` at its empty value', () => {
+    const schema = z.object({
+      email: z.email().optional(),
+      name: z.string().min(1),
+      note: z.string(),
+      ownerId: z.uuid().nullable(),
+    })
+    const start = withEmptyStartValues(schema, extractZodDefaults(schema))
+    expect(start).toEqual({
+      email: undefined,
+      name: "",
+      note: "",
+      ownerId: null,
+    })
+  })
+})

package/src/lib/empty-value.ts

@@ -0,0 +1,130 @@
+import type { AnyFieldApi } from "@tanstack/react-form"
+
+import { toFieldName } from "./action-result"
+import { extractZodDefaultAt } from "./schema-defaults"
+import { type StandardSchemaLike, validateSync } from "./schema-required"
+import { getFormSchema } from "./validation-modes"
+
+// A field's empty value is the first one its schema accepts of `null`,
+// `undefined` and the type's own empty value (`""` for a string, `[]` for an
+// array, through `extractZodDefaults`). So `.nullable()` empties to `null`,
+// `.optional()` to `undefined`, and a bare `z.string()` to `""`. A field that
+// accepts none of them is required. A cleared field holds its empty value,
+// and so does an untouched one whose schema rejects `""` or `[]`.
+
+const NAME_SEGMENT = /[^.[\]]+/g
+const INDEX = /^\d+$/
+
+// `members[2].name` (or `members.2.name`) → `["members", 2, "name"]`.
+function toPathKeys(name: string): PropertyKey[] {
+  return (name.match(NAME_SEGMENT) ?? []).map((part) =>
+    INDEX.test(part) ? Number(part) : part
+  )
+}
+
+function valueAt(root: unknown, keys: readonly PropertyKey[]): unknown {
+  let node = root
+  for (const key of keys) {
+    if (typeof node !== "object" || node === null) {
+      return
+    }
+    node = (node as Record<PropertyKey, unknown>)[key]
+  }
+  return node
+}
+
+// A copy of `root` with `value` at `keys`, copying only the nodes on the way.
+function withValueAt(
+  root: unknown,
+  keys: readonly PropertyKey[],
+  value: unknown
+): unknown {
+  const [key, ...rest] = keys
+  if (key === undefined) {
+    return value
+  }
+  const node = (root ?? (typeof key === "number" ? [] : {})) as Record<
+    PropertyKey,
+    unknown
+  >
+  const copy = (Array.isArray(node) ? [...node] : { ...node }) as Record<
+    PropertyKey,
+    unknown
+  >
+  copy[key] = withValueAt(node[key], rest, value)
+  return copy
+}
+
+function emptyValueFor(
+  schema: StandardSchemaLike | undefined,
+  values: unknown,
+  name: string,
+  fallback: unknown
+): unknown {
+  if (!schema) {
+    return fallback
+  }
+  const keys = toPathKeys(name)
+  const fieldName = toFieldName(keys)
+  const typeEmpty = extractZodDefaultAt(
+    schema as Parameters<typeof extractZodDefaultAt>[0],
+    keys
+  )
+  const candidates = typeEmpty.ok
+    ? [null, undefined, typeEmpty.value]
+    : [null, undefined]
+  for (const candidate of candidates) {
+    const issues = validateSync(schema, withValueAt(values, keys, candidate))
+    if (!issues) {
+      return fallback
+    }
+    if (!issues.some((issue) => toFieldName(issue.path) === fieldName)) {
+      return candidate
+    }
+  }
+  return fallback
+}
+
+function isTypeEmpty(value: unknown): boolean {
+  return value === "" || (Array.isArray(value) && value.length === 0)
+}
+
+// `extractZodDefaults` starts every string at `""` and every array at `[]`.
+// Where the schema rejects that (`z.uuid().nullable()`,
+// `z.email().optional()`), start the field at its empty value instead, so an
+// untouched optional field passes. A required one keeps `""` or `[]`.
+function withEmptyStartValues(
+  schema: StandardSchemaLike,
+  defaults: Record<string, unknown>
+): Record<string, unknown> {
+  const issues = validateSync(schema, defaults)
+  let result: unknown = defaults
+  for (const issue of issues ?? []) {
+    const name = toFieldName(issue.path)
+    const keys = toPathKeys(name)
+    const start = valueAt(defaults, keys)
+    if (keys.length === 0 || !isTypeEmpty(start)) {
+      continue
+    }
+    const empty = emptyValueFor(schema, result, name, start)
+    if (empty !== start) {
+      result = withValueAt(result, keys, empty)
+    }
+  }
+  return result as Record<string, unknown>
+}
+
+/**
+ * The value `field` takes when the user clears it, by the rule above. Typed as
+ * the field's value, since the same schema decides both.
+ */
+function getEmptyValue<T>(field: AnyFieldApi, fallback: T): T {
+  return emptyValueFor(
+    getFormSchema(field.form),
+    field.form.state.values,
+    field.name,
+    fallback
+  ) as T
+}
+
+export { emptyValueFor, getEmptyValue, withEmptyStartValues }

package/src/lib/schema-defaults.ts

@@ -24,6 +24,7 @@ type SchemaDef = {
   readonly innerType?: SchemaNode
   readonly shape?: Record<string, SchemaNode>
   readonly in?: SchemaNode
+  readonly element?: SchemaNode
   readonly defaultValue?: unknown
 }
 
@@ -91,6 +92,54 @@ function extractZodDefaults(schema: SchemaNode): Record<string, unknown> {
   }
 }
 
+// Step from an object or array schema into its `key` child, through any
+// wrapper around it. `null` when there is none.
+function childAt(node: SchemaNode, key: PropertyKey): SchemaNode | null {
+  let current: SchemaNode | undefined = node
+  for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth += 1) {
+    const def: SchemaDef | undefined = getDef(current)
+    switch (def?.type) {
+      case "object":
+        return (typeof key === "string" && def.shape?.[key]) || null
+      case "array":
+        return (typeof key === "number" && def.element) || null
+      case "default":
+      case "nonoptional":
+      case "nullable":
+      case "optional":
+      case "prefault":
+      case "readonly":
+        current = def.innerType
+        continue
+      case "pipe":
+        current = def.in
+        continue
+      default:
+        return null
+    }
+  }
+  return null
+}
+
+// The value `extractZodDefaults` starts the field at `keys` at, array rows
+// included (`["members", 2, "name"]`). `{ ok: false }` when it gives none.
+function extractZodDefaultAt(
+  schema: SchemaNode,
+  keys: readonly PropertyKey[]
+): ExtractResult {
+  try {
+    let node: SchemaNode | null = schema
+    for (const key of keys) {
+      node = node && childAt(node, key)
+    }
+    return node && keys.length > 0
+      ? extractDefaultForField(node)
+      : { ok: false }
+  } catch {
+    return { ok: false }
+  }
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return (
     typeof value === "object" &&
@@ -124,4 +173,4 @@ function deepMergeDefaults(
   return result
 }
 
-export { deepMergeDefaults, extractZodDefaults }
+export { deepMergeDefaults, extractZodDefaultAt, extractZodDefaults }

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

@@ -38,6 +38,42 @@ describe("getRequiredPaths", () => {
     expect(required.has("role")).toBe(false)
   })
 
+  test("a string that accepts the empty value it starts at is not required", () => {
+    const schema = z.object({
+      email: z.email(),
+      members: z.array(z.object({ name: z.string().min(1), note: z.string() })),
+      name: z.string().trim().min(1),
+      notes: z.string(),
+      profile: z.object({ bio: z.string(), title: z.string().min(1) }),
+      subtitle: z.string().nullable(),
+    })
+    const required = getRequiredPaths(schema)
+    expect(required.has("notes")).toBe(false)
+    expect(required.has("subtitle")).toBe(false)
+    expect(required.has("profile.bio")).toBe(false)
+    expect(required.has("members[0].note")).toBe(false)
+    expect(required.has("email")).toBe(true)
+    expect(required.has("name")).toBe(true)
+    expect(required.has("profile.title")).toBe(true)
+    expect(required.has("members[0].name")).toBe(true)
+  })
+
+  test("a field that accepts null is not required", () => {
+    const schema = z.object({
+      count: z.number(),
+      day: z.date().nullable(),
+      kind: z.enum(["a", "b"]).nullable(),
+      ownerId: z.uuid().nullable(),
+      total: z.number().nullable(),
+    })
+    const required = getRequiredPaths(schema)
+    expect(required.has("count")).toBe(true)
+    expect(required.has("day")).toBe(false)
+    expect(required.has("kind")).toBe(false)
+    expect(required.has("ownerId")).toBe(false)
+    expect(required.has("total")).toBe(false)
+  })
+
   test("nested z.object reports the parent and its required children", () => {
     const schema = z.object({
       profile: z.object({
@@ -60,26 +96,32 @@ describe("getRequiredPaths", () => {
 
   test("array rows are reported with TanStack bracket syntax", () => {
     const schema = z.object({
+      emails: z.array(z.email()),
       members: z.array(
         z.object({
           name: z.string().min(1),
           note: z.string().optional(),
         })
       ),
+      picked: z.array(z.string()).min(1),
       tags: z.array(z.string()),
     })
     const required = getRequiredPaths(schema)
-    expect(required.has("members")).toBe(true)
     expect(required.has("members[0].name")).toBe(true)
     expect(required.has("members.0.name")).toBe(false)
     expect(required.has("members[0].note")).toBe(false)
-    expect(required.has("tags[0]")).toBe(true)
+    expect(required.has("emails[0]")).toBe(true)
+    expect(required.has("picked")).toBe(true)
+    // `[]` and `""` are what the form starts them at, and both pass.
+    expect(required.has("members")).toBe(false)
+    expect(required.has("tags")).toBe(false)
+    expect(required.has("tags[0]")).toBe(false)
   })
 
   test("nested arrays descend through every level", () => {
     const schema = z.object({
       groups: z.array(
-        z.object({ members: z.array(z.object({ name: z.string() })) })
+        z.object({ members: z.array(z.object({ name: z.string().min(1) })) })
       ),
     })
     const required = getRequiredPaths(schema)