@zeno-lib/forms 0.0.0 → 0.1.0

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

@@ -1,7 +1,11 @@
-import { describe, expect, test } from "@zeno-lib/vitest"
+import { describe, expect, test } from "vitest"
 import { z } from "zod"
 
-import { getRequiredPaths, type StandardSchemaLike } from "./schema-required"
+import {
+  getRequiredPaths,
+  type StandardSchemaLike,
+  toRequiredPathKey,
+} from "./schema-required"
 
 describe("getRequiredPaths", () => {
   test("plain required fields appear in the set", () => {
@@ -34,17 +38,52 @@ describe("getRequiredPaths", () => {
     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.
+  test("nested z.object reports the parent and its required children", () => {
     const schema = z.object({
       profile: z.object({
+        bio: z.string().optional(),
         email: z.email(),
       }),
     })
     const required = getRequiredPaths(schema)
     expect(required.has("profile")).toBe(true)
-    expect(required.has("profile.email")).toBe(false)
+    expect(required.has("profile.email")).toBe(true)
+    expect(required.has("profile.bio")).toBe(false)
+  })
+
+  test("optional nested object is not descended into", () => {
+    const schema = z.object({
+      profile: z.object({ email: z.email() }).optional(),
+    })
+    expect(getRequiredPaths(schema).size).toBe(0)
+  })
+
+  test("array rows are reported with TanStack bracket syntax", () => {
+    const schema = z.object({
+      members: z.array(
+        z.object({
+          name: z.string().min(1),
+          note: z.string().optional(),
+        })
+      ),
+      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)
+  })
+
+  test("nested arrays descend through every level", () => {
+    const schema = z.object({
+      groups: z.array(
+        z.object({ members: z.array(z.object({ name: z.string() })) })
+      ),
+    })
+    const required = getRequiredPaths(schema)
+    expect(required.has("groups[0].members[0].name")).toBe(true)
   })
 
   test("dot-joined path is built when issues carry multi-segment paths", () => {
@@ -105,6 +144,47 @@ describe("getRequiredPaths", () => {
     expect(getRequiredPaths(empty).size).toBe(0)
   })
 
+  test("numeric path segments render as bracket indices, normalised to 0", () => {
+    const schema: StandardSchemaLike = {
+      "~standard": {
+        validate: () => ({
+          issues: [
+            { path: ["members", 2, "name"] },
+            { path: ["rows", "1", "value"] },
+            { path: [{ key: "items" }, { key: 3 }] },
+          ],
+        }),
+      },
+    }
+    const required = getRequiredPaths(schema)
+    expect(required.has("members[0].name")).toBe(true)
+    expect(required.has("rows[0].value")).toBe(true)
+    expect(required.has("items[0]")).toBe(true)
+  })
+
+  test("Valibot-style capitalised `expected` hints are descended", () => {
+    const schema: StandardSchemaLike = {
+      "~standard": {
+        validate: (value) => {
+          const profile = (value as { profile?: unknown }).profile
+          return profile === undefined
+            ? { issues: [{ expected: "Object", path: [{ key: "profile" }] }] }
+            : {
+                issues: [
+                  {
+                    expected: "string",
+                    path: [{ key: "profile" }, { key: "email" }],
+                  },
+                ],
+              }
+        },
+      },
+    }
+    const required = getRequiredPaths(schema)
+    expect(required.has("profile")).toBe(true)
+    expect(required.has("profile.email")).toBe(true)
+  })
+
   test("path entries shaped like { key } (Valibot) are normalised", () => {
     const valibotStyle: StandardSchemaLike = {
       "~standard": {
@@ -130,3 +210,15 @@ describe("getRequiredPaths", () => {
     expect(getRequiredPaths(formLevelOnly).size).toBe(0)
   })
 })
+
+describe("toRequiredPathKey", () => {
+  test("normalises bracket and dotted indices to [0]", () => {
+    expect(toRequiredPathKey("members[3].name")).toBe("members[0].name")
+    expect(toRequiredPathKey("members.3.name")).toBe("members[0].name")
+    expect(toRequiredPathKey("groups[1].members[12]")).toBe(
+      "groups[0].members[0]"
+    )
+    expect(toRequiredPathKey("email")).toBe("email")
+    expect(toRequiredPathKey("line2")).toBe("line2")
+  })
+})

package/src/lib/schema-required.ts

@@ -6,15 +6,29 @@
 // issue with a `path` we can record. Fields with defaults or `.optional()` stay
 // silent because the schema considers them satisfied.
 //
+// A missing parent hides its children (the schema stops at the missing key), so
+// the probe descends: when an issue says it expected an object or an array
+// (Zod and Valibot both put that on `issue.expected`), the next pass fills that
+// path with `{}` / `[{}]` and validates again. Array rows are probed through
+// index `0` and recorded index-agnostically, so `members[0].name` in the set
+// matches every row's `members[3].name` via `toRequiredPathKey`.
+//
+// Paths use TanStack Form's field-name syntax: dots for object keys, brackets
+// for array indices (`members[0].name`, not `members.0.name`).
+//
 // 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.
+//   - Cross-field refinements that fail on the probe value may flag fields that
+//     aren't intrinsically required. In practice this is the same heuristic
+//     users would apply by eye.
+//   - Schemas whose issues carry no `expected` hint stop at the top level.
+
+type PathPart = PropertyKey | { readonly key: PropertyKey }
 
 type StandardIssue = {
-  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>
+  readonly path?: readonly PathPart[]
+  readonly expected?: unknown
 }
 
 type StandardSchemaLike = {
@@ -28,37 +42,127 @@ type StandardSchemaLike = {
   }
 }
 
-function pathSegment(
-  part: PropertyKey | { readonly key: PropertyKey }
-): string {
+const MAX_PROBE_DEPTH = 8
+
+const INDEX_SEGMENT = /^\d+$/
+
+// Matches `[3]` and `.3` index segments in a field name.
+const INDEX_IN_NAME = /\[\d+\]|\.(\d+)(?=\.|\[|$)/g
+
+function pathKey(part: PathPart): PropertyKey {
   if (typeof part === "object" && part !== null && "key" in part) {
-    return String(part.key)
+    return part.key
   }
-  return String(part)
+  return part
 }
 
-function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
-  const required = new Set<string>()
+function isIndex(key: PropertyKey): boolean {
+  return (
+    typeof key === "number" ||
+    (typeof key === "string" && INDEX_SEGMENT.test(key))
+  )
+}
+
+// Render issue path segments as a TanStack field name, with every array index
+// normalised to `0` so one entry covers all rows.
+function joinPath(keys: readonly PropertyKey[]): string {
+  let out = ""
+  for (const key of keys) {
+    if (isIndex(key)) {
+      out += "[0]"
+    } else {
+      out += out === "" ? String(key) : `.${String(key)}`
+    }
+  }
+  return out
+}
+
+/**
+ * Normalise a field name (`members[3].name` or `members.3.name`) to the key
+ * `getRequiredPaths` records (`members[0].name`).
+ */
+function toRequiredPathKey(name: string): string {
+  return name.replace(INDEX_IN_NAME, "[0]")
+}
+
+function probeContainer(expected: unknown): unknown {
+  if (typeof expected !== "string") {
+    return
+  }
+  const kind = expected.toLowerCase()
+  if (kind === "object") {
+    return {}
+  }
+  if (kind === "array") {
+    return [{}]
+  }
+  return
+}
+
+// Write `value` at `keys` inside `root`, only where nothing is set yet.
+function fillAt(
+  root: Record<PropertyKey, unknown>,
+  keys: readonly PropertyKey[],
+  value: unknown
+): boolean {
+  let node: Record<PropertyKey, unknown> = root
+  for (const key of keys.slice(0, -1)) {
+    const next = node[key]
+    if (typeof next !== "object" || next === null) {
+      return false
+    }
+    node = next as Record<PropertyKey, unknown>
+  }
+  const last = keys.at(-1) as PropertyKey
+  if (node[last] !== undefined) {
+    return false
+  }
+  node[last] = value
+  return true
+}
+
+function validateSync(
+  schema: StandardSchemaLike,
+  value: unknown
+): readonly StandardIssue[] | undefined {
   let result: ReturnType<StandardSchemaLike["~standard"]["validate"]>
   try {
-    result = schema["~standard"].validate({})
+    result = schema["~standard"].validate(value)
   } catch {
-    return required
+    return
   }
   if (result instanceof Promise) {
-    return required
-  }
-  if (!("issues" in result && result.issues)) {
-    return required
+    return
   }
-  for (const issue of result.issues) {
-    const segments = issue.path?.map(pathSegment) ?? []
-    if (segments.length > 0) {
-      required.add(segments.join("."))
+  return "issues" in result && result.issues ? result.issues : []
+}
+
+function getRequiredPaths(schema: StandardSchemaLike): Set<string> {
+  const required = new Set<string>()
+  const probe: Record<PropertyKey, unknown> = {}
+  for (let depth = 0; depth < MAX_PROBE_DEPTH; depth++) {
+    const issues = validateSync(schema, probe)
+    if (!issues) {
+      return required
+    }
+    let descended = false
+    for (const issue of issues) {
+      const keys = issue.path?.map(pathKey) ?? []
+      if (keys.length === 0) {
+        continue
+      }
+      required.add(joinPath(keys))
+      const container = probeContainer(issue.expected)
+      if (container !== undefined && fillAt(probe, keys, container)) {
+        descended = true
+      }
+    }
+    if (!descended) {
+      break
     }
   }
   return required
 }
 
 export type { StandardSchemaLike }
-export { getRequiredPaths }
+export { getRequiredPaths, toRequiredPathKey }

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

@@ -1,6 +1,6 @@
 "use client"
 
-import { type AnyFieldApi, useStore } from "@tanstack/react-form"
+import { type AnyFieldApi, useSelector } from "@tanstack/react-form"
 
 import {
   getFormHideFieldErrors,
@@ -15,7 +15,7 @@ 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
+// the form's `validators` 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(
@@ -46,7 +46,7 @@ function modeAllowsDisplay(
 }
 
 // Returns the "should we display errors?" gate for a field. The gate matches
-// the form's `validation` mode (set via `useForm({ validation })`):
+// the form's `validators` mode (set via `useForm({ validators })`):
 //
 //   - `change`           → show as soon as the user has typed (live)
 //   - `blur`             → show after first blur
@@ -60,7 +60,7 @@ function modeAllowsDisplay(
 // `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(
+  const wasSubmitted = useSelector(
     field.form.store,
     (state) => state.submissionAttempts > 0
   )

package/src/lib/use-rebased-default-values.ts

@@ -0,0 +1,42 @@
+"use client"
+
+import { type AnyFormApi, evaluate } from "@tanstack/react-form"
+import { useCallback, useRef } from "react"
+
+// TanStack's `useForm` calls `formApi.update(options)` after every render. While
+// the form is untouched, `update` re-applies `options.defaultValues` whenever it
+// deep-differs from the form's live defaults. `formApi.reset(values)` rebases
+// those live defaults, so a caller that keeps passing the same `defaultValues`
+// literal would see the reset undone on the next render (the classic "reset to
+// the saved record after submit" flow).
+//
+// This hook forwards the caller's defaults only when *they* change (deep
+// compare, the same `evaluate` TanStack's `update` uses). Otherwise it forwards
+// the form's live defaults back, so `update` sees no change and a reset sticks.
+// The live FormApi instance comes from the form-level `listeners.onMount`
+// callback: the object `useForm` returns is a spread snapshot whose `options`
+// never updates.
+function useRebasedDefaultValues<T>(callerDefaults: T): {
+  defaultValues: T
+  onMount: (props: { formApi: AnyFormApi }) => void
+} {
+  const liveForm = useRef<AnyFormApi | null>(null)
+  const lastCallerDefaults = useRef(callerDefaults)
+
+  let defaultValues = callerDefaults
+  if (evaluate(lastCallerDefaults.current, callerDefaults)) {
+    if (liveForm.current) {
+      defaultValues = liveForm.current.options.defaultValues as T
+    }
+  } else {
+    lastCallerDefaults.current = callerDefaults
+  }
+
+  const onMount = useCallback((props: { formApi: AnyFormApi }) => {
+    liveForm.current = props.formApi
+  }, [])
+
+  return { defaultValues, onMount }
+}
+
+export { useRebasedDefaultValues }

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

@@ -1,6 +1,6 @@
 "use client"
 
-import { type AnyFormApi, useStore } from "@tanstack/react-form"
+import { type AnyFormApi, useSelector } from "@tanstack/react-form"
 import { useEffect } from "react"
 
 type UnsavedChangesMode = "if-changed" | "if-touched"
@@ -34,10 +34,10 @@ function useUnsavedChangesWarning(
   } else {
     mode = enabled
   }
-  const dirty = useStore(form.store, (state) =>
+  const dirty = useSelector(form.store, (state) =>
     mode === "if-touched" ? state.isDirty : !state.isDefaultValue
   )
-  const isSubmitting = useStore(form.store, (state) => state.isSubmitting)
+  const isSubmitting = useSelector(form.store, (state) => state.isSubmitting)
   const active = mode !== null && dirty && !isSubmitting
 
   useEffect(() => {

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

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "@zeno-lib/vitest"
+import { describe, expect, test } from "vitest"
 
 import { ValidationError } from "./validation-error"
 

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

@@ -1,5 +1,5 @@
 import type { AnyFormApi, ValidationLogicFn } from "@tanstack/react-form"
-import { describe, expect, test, vi } from "@zeno-lib/vitest"
+import { describe, expect, test, vi } from "vitest"
 
 import { blurThenChangeLogic } from "./validation-logic"
 

package/src/lib/validation-modes.test-d.ts

@@ -1,4 +1,4 @@
-import { expectTypeOf, test } from "@zeno-lib/vitest"
+import { expectTypeOf, test } from "vitest"
 
 import type { ValidationMode } from "./validation-modes"
 

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

@@ -1,6 +1,5 @@
 import type { AnyFormApi } from "@tanstack/react-form"
-import { describe, expect, test } from "@zeno-lib/vitest"
-
+import { describe, expect, test } from "vitest"
 import {
   DEFAULT_VALIDATION_MODE,
   getFormHideFieldErrors,
@@ -50,6 +49,17 @@ describe("validation-modes WeakMap state", () => {
     expect(isFieldRequired(form, "email")).toBe(false)
   })
 
+  test("isFieldRequired matches array rows by TanStack field name", () => {
+    const form = makeFormStub()
+    setFormZenoState(form, {
+      requiredFields: new Set(["members[0].name"]),
+      requiredIndicator: true,
+    })
+    expect(isFieldRequired(form, "members[0].name")).toBe(true)
+    expect(isFieldRequired(form, "members[4].name")).toBe(true)
+    expect(isFieldRequired(form, "members[4].note")).toBe(false)
+  })
+
   test("two forms keyed on different store references are independent", () => {
     const a = makeFormStub()
     const b = makeFormStub()

package/src/lib/validation-modes.ts

@@ -2,6 +2,8 @@
 
 import type { AnyFormApi } from "@tanstack/react-form"
 
+import { toRequiredPathKey } from "./schema-required"
+
 type ValidationMode = "change" | "blur" | "submit" | "blur-then-change"
 
 const DEFAULT_VALIDATION_MODE: ValidationMode = "blur-then-change"
@@ -60,7 +62,7 @@ function isFieldRequired(form: AnyFormApi, name: string): boolean {
   if (!state.requiredIndicator) {
     return false
   }
-  return state.requiredFields.has(name)
+  return state.requiredFields.has(toRequiredPathKey(name))
 }
 
 export {

package/src/use-app-fields.test-d.ts

@@ -1,7 +1,6 @@
-import { test } from "@zeno-lib/vitest"
+import { test } from "vitest"
 import { z } from "zod"
-
-import { useForm } from "./use-form"
+import { useForm } from "./create-form"
 
 const schema = z.object({
   accept: z.boolean(),
@@ -14,10 +13,6 @@ const schema = z.object({
   size: z.string(),
 })
 
-const schemaNoEmail = z.object({
-  contact: z.string(),
-})
-
 test("InputField.name is constrained to DeepKeys<T>", () => {
   const form = useForm({ onSubmit: () => undefined, schema })
   const { InputField } = form
@@ -57,36 +52,24 @@ test("TextAreaField.name is constrained to DeepKeys<T>", () => {
   form.TextAreaField({ name: "nonexistent" })
 })
 
-test("EmailField.name is optional when T has an `email` field", () => {
+test("EmailField.name is required and constrained to DeepKeys<T>", () => {
   const form = useForm({ onSubmit: () => undefined, schema })
   const { EmailField } = form
-  // No `name` required.
+  // @ts-expect-error — name is required
   EmailField({})
-  EmailField({ label: "Email" })
   EmailField({ name: "email" })
+  // @ts-expect-error — not a valid path
+  EmailField({ name: "nonexistent" })
 })
 
-test("EmailField.name is required when T has no `email` field", () => {
-  const form = useForm({ onSubmit: () => undefined, schema: schemaNoEmail })
-  // @ts-expect-error — name becomes required without an "email" key on T
-  form.EmailField({})
-  form.EmailField({ name: "contact" })
-})
-
-test("PasswordField.name is optional when T has a `password` field", () => {
+test("PasswordField.name is required and constrained to DeepKeys<T>", () => {
   const form = useForm({ onSubmit: () => undefined, schema })
   const { PasswordField } = form
+  // @ts-expect-error — name is required
   PasswordField({})
   PasswordField({ name: "password" })
 })
 
-test("PasswordField.name is required when T has no `password` field", () => {
-  const form = useForm({ onSubmit: () => undefined, schema: schemaNoEmail })
-  // @ts-expect-error — name becomes required without a "password" key on T
-  form.PasswordField({})
-  form.PasswordField({ name: "contact" })
-})
-
 test("validators prop is accepted on every field wrapper", () => {
   const form = useForm({ onSubmit: () => undefined, schema })
   form.InputField({

package/src/use-app-fields.test.tsx

@@ -1,12 +1,9 @@
-import { afterEach, describe, expect, test, vi } from "@zeno-lib/vitest"
-import { cleanup, render, screen } from "@zeno-lib/vitest/testing-library"
-import userEvent from "@zeno-lib/vitest/user-event"
+import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { afterEach, describe, expect, test, vi } from "vitest"
 import { z } from "zod"
+import { Form, FormProvider, useForm } from "./create-form"
 
-import { Form, FormProvider } from "./form"
-import { useForm } from "./use-form"
-
-const EMAIL_LABEL = /Email/
 const CONTACT_EMAIL_LABEL = /Contact email/
 const PASSWORD_LABEL = /Password/
 const NAME_LABEL = /Name/
@@ -16,27 +13,7 @@ afterEach(() => {
   cleanup()
 })
 
-describe("EmailField / PasswordField — default name", () => {
-  test("EmailField with no `name` renders an input with id='email'", () => {
-    const schema = z.object({ email: z.email() })
-    function H() {
-      const form = useForm({ onSubmit: vi.fn(), schema })
-      const { EmailField } = form
-      return (
-        <FormProvider form={form}>
-          <Form>
-            <EmailField label="Email" />
-          </Form>
-        </FormProvider>
-      )
-    }
-    render(<H />)
-    const input = screen.getByLabelText(EMAIL_LABEL) as HTMLInputElement
-    expect(input.id).toBe("email")
-    expect(input.name).toBe("email")
-    expect(input.type).toBe("email")
-  })
-
+describe("EmailField / PasswordField", () => {
   test("EmailField with an explicit `name` binds to that field", async () => {
     const user = userEvent.setup()
     const schema = z.object({ contactEmail: z.email() })
@@ -59,19 +36,18 @@ describe("EmailField / PasswordField — default name", () => {
     expect(input.value).toBe("u@example.com")
   })
 
-  test("PasswordField with no `name` renders an input with id='password'", () => {
+  test("PasswordField with an explicit `name` renders a password input", () => {
     const schema = z.object({
       email: z.email(),
       password: z.string().min(1),
     })
     function H() {
       const form = useForm({ onSubmit: vi.fn(), schema })
-      const { EmailField, PasswordField } = form
+      const { PasswordField } = form
       return (
         <FormProvider form={form}>
           <Form>
-            <EmailField />
-            <PasswordField label="Password" />
+            <PasswordField label="Password" name="password" />
           </Form>
         </FormProvider>
       )

package/src/use-form.cascade.test.tsx

@@ -1,10 +1,8 @@
-import { afterEach, describe, expect, test, vi } from "@zeno-lib/vitest"
-import { cleanup, render, screen } from "@zeno-lib/vitest/testing-library"
-import userEvent from "@zeno-lib/vitest/user-event"
+import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { afterEach, describe, expect, test, vi } from "vitest"
 import { z } from "zod"
-
-import { Form, FormProvider } from "./form"
-import { useForm } from "./use-form"
+import { Form, FormProvider, useForm } from "./create-form"
 
 const DIET_LABEL = /Diet/
 const SAUSAGE_LABEL = /Sausage/