@zeno-lib/forms 0.9.1 → 0.10.1

package/src/lib/field-hints.ts

@@ -0,0 +1,64 @@
+import type { AnyFieldApi } from "@tanstack/react-form"
+import { toPathKeys } from "./empty-value"
+import { findZodSchemaAt } from "./schema-defaults"
+import { getFormSchema } from "./validation-modes"
+
+/**
+ * What a field reads from the column its schema comes from, when the column's
+ * hint names it. The `percentage()` and `year()` columns of
+ * `@zeno-lib/db/schema` give one, so `PercentageField` and `YearField` show
+ * and clamp what the column accepts with no props: the scale from the hint,
+ * the bounds from the schema's own `.min()` and `.max()`, a caller's
+ * narrowing included. A prop the field is given wins.
+ */
+type FieldHints = {
+  readonly max?: number | undefined
+  readonly min?: number | undefined
+  readonly scale?: "fraction" | "percent" | undefined
+}
+
+// The registry `@zeno-lib/schema` puts each column's hint in, under a
+// `globalThis` symbol both packages name, so this one reads it without
+// importing that one. Absent until `@zeno-lib/schema` loads, and then no
+// field has a hint.
+const FIELD_HINTS_KEY = Symbol.for("@zeno-lib/field-hints")
+
+type HintRegistry = { readonly get: (schema: object) => unknown }
+
+type Bounded = { readonly maxValue?: unknown; readonly minValue?: unknown }
+
+const readHint = (node: object) => {
+  const registry = (globalThis as { [FIELD_HINTS_KEY]?: HintRegistry })[
+    FIELD_HINTS_KEY
+  ]
+  const hint = registry?.get(node) as { field?: unknown } | undefined
+  return typeof hint?.field === "string" ? hint : undefined
+}
+
+// A schema with no `.min()` or `.max()` reports `null` or an infinity.
+const toBound = (value: unknown) =>
+  typeof value === "number" && Number.isFinite(value) ? value : undefined
+
+function getFieldHints(field: AnyFieldApi, kind: string): FieldHints {
+  const schema = getFormSchema(field.form)
+  const found = schema
+    ? findZodSchemaAt(
+        schema as Parameters<typeof findZodSchemaAt>[0],
+        toPathKeys(field.name),
+        readHint
+      )
+    : undefined
+  if (found?.value.field !== kind) {
+    return {}
+  }
+  const { scale } = found.value as { scale?: unknown }
+  const { maxValue, minValue } = found.node as Bounded
+  return {
+    max: toBound(maxValue),
+    min: toBound(minValue),
+    scale: scale === "fraction" || scale === "percent" ? scale : undefined,
+  }
+}
+
+export type { FieldHints }
+export { getFieldHints }

package/src/lib/formatted-number.ts

@@ -43,15 +43,15 @@ const separatorCache = new Map<string, NumberSeparators>()
 
 // Minus signs a user may type or paste: ASCII hyphen-minus, U+2212 (what Intl
 // emits for some locales), and the en dash.
-const MINUS_SIGNS = /[-−–]/
-const LEADING_MINUS = /^[^\d]*[-−–]/
-const NON_DIGIT = /\D/g
-const LEADING_ZEROS = /^0+(?=\d)/
-const DIGIT = /\d/
-const DIGITS = /\d/g
-const PARENTHESIZED = /^\s*\(.*\)\s*$/
-const NOT_NUMERIC = /[^\d.,]/g
-const UNICODE_MINUS = /\u2212/g
+const MINUS_SIGNS = /[-−–]/u
+const LEADING_MINUS = /^[^\d]*[-−–]/u
+const NON_DIGIT = /\D/gu
+const LEADING_ZEROS = /^0+(?=\d)/u
+const DIGIT = /\d/u
+const DIGITS = /\d/gu
+const PARENTHESIZED = /^\s*\(.*\)\s*$/u
+const NOT_NUMERIC = /[^\d.,]/gu
+const UNICODE_MINUS = /\u2212/gu
 
 function getNumberSeparators(locale?: string): NumberSeparators {
   const key = locale ?? ""

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

@@ -65,9 +65,12 @@ describe("extractZodDefaults — wrappers", () => {
     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(".nullable() starts a string at null, which a nullable column stores", () => {
+    const schema = z.object({
+      x: z.string().nullable(),
+      y: z.string().nullable().optional(),
+    })
+    expect(extractZodDefaults(schema)).toEqual({ x: null, y: null })
   })
 
   test(".readonly() unwraps to inner string → ''", () => {

package/src/lib/schema-defaults.ts

@@ -4,7 +4,8 @@
 // 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.
+//     a default fall back to `""` so React inputs render controlled, or to
+//     `null` under `.nullable()`, which the fields render as no text.
 //   - Arrays without a default fall back to `[]`.
 //   - Nested `z.object(...)` recurses; emits a sub-record only if at least one
 //     leaf produced a value.
@@ -26,6 +27,7 @@ type SchemaDef = {
   readonly shape?: Record<string, SchemaNode>
   readonly catchall?: SchemaNode
   readonly in?: SchemaNode
+  readonly out?: SchemaNode
   readonly element?: SchemaNode
   readonly defaultValue?: unknown
 }
@@ -40,6 +42,7 @@ function getDef(node: SchemaNode | undefined): SchemaDef | undefined {
 
 function extractDefaultForField(node: SchemaNode): ExtractResult {
   let current: SchemaNode | undefined = node
+  let isNullable = false
   for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth += 1) {
     const def: SchemaDef | undefined = getDef(current)
     if (!def?.type) {
@@ -49,8 +52,11 @@ function extractDefaultForField(node: SchemaNode): ExtractResult {
       case "default":
       case "prefault":
         return { ok: true, value: def.defaultValue }
-      case "optional":
       case "nullable":
+        isNullable = true
+        current = def.innerType
+        continue
+      case "optional":
       case "nonoptional":
       case "readonly":
         current = def.innerType
@@ -58,8 +64,10 @@ function extractDefaultForField(node: SchemaNode): ExtractResult {
       case "pipe":
         current = def.in
         continue
+      // No text is `null` where the schema takes it, as a nullable column
+      // stores it, so a field left blank saves as none rather than as `""`.
       case "string":
-        return { ok: true, value: "" }
+        return { ok: true, value: isNullable ? null : "" }
       case "array":
         return { ok: true, value: [] }
       case "object": {
@@ -142,6 +150,54 @@ function extractZodDefaultAt(
   }
 }
 
+// The schema inside a wrapper, or `undefined` past the last one.
+function unwrapped(node: SchemaNode): SchemaNode | undefined {
+  const def: SchemaDef | undefined = getDef(node)
+  switch (def?.type) {
+    case "catch":
+    case "default":
+    case "nonoptional":
+    case "nullable":
+    case "optional":
+    case "prefault":
+    case "readonly":
+      return def.innerType
+    // `z.preprocess` pipes a transform into the schema it feeds.
+    case "pipe":
+      return getDef(def.in)?.type === "transform" ? def.out : def.in
+    default:
+      return undefined
+  }
+}
+
+// The schema at `keys`, or inside one of its wrappers, that `read` finds a
+// value on, with that value. A Zod registry keeps an entry on the schema it
+// was set on, not on the `.optional()` or `.nullable()` around it.
+function findZodSchemaAt<T>(
+  schema: SchemaNode,
+  keys: readonly PropertyKey[],
+  read: (node: SchemaNode) => T | undefined
+): { node: SchemaNode; value: T } | undefined {
+  try {
+    let node: SchemaNode | null = schema
+    for (const key of keys) {
+      node = node && childAt(node, key)
+    }
+    let current: SchemaNode | undefined =
+      node && keys.length > 0 ? node : undefined
+    for (let depth = 0; current && depth < MAX_WRAPPER_DEPTH; depth += 1) {
+      const value = read(current)
+      if (value !== undefined) {
+        return { node: current, value }
+      }
+      current = unwrapped(current)
+    }
+  } catch {
+    // An unrecognised schema has nothing to offer.
+  }
+  return undefined
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return (
     typeof value === "object" &&
@@ -244,5 +300,6 @@ export {
   deepMergeDefaults,
   extractZodDefaultAt,
   extractZodDefaults,
+  findZodSchemaAt,
   pickSchemaShape,
 }

package/src/lib/schema-required.ts

@@ -53,10 +53,10 @@ type StandardSchemaLike = {
 // Each level can take two passes: the empty value, then the descent.
 const MAX_PROBE_DEPTH = 16
 
-const INDEX_SEGMENT = /^\d+$/
+const INDEX_SEGMENT = /^\d+$/u
 
 // Matches `[3]` and `.3` index segments in a field name.
-const INDEX_IN_NAME = /\[\d+\]|\.(\d+)(?=\.|\[|$)/g
+const INDEX_IN_NAME = /\[\d+\]|\.\d+(?=\.|\[|$)/gu
 
 function pathKey(part: PathPart): PropertyKey {
   // biome-ignore lint/suspicious/noUnnecessaryConditions: issue paths come from third-party validators at runtime, and a non-conforming `null` segment would make `in` throw.

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

@@ -199,7 +199,7 @@ const FOCUSABLE =
   'input:not([type="hidden"]):not([disabled]), textarea:not([disabled]), select:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex="-1"])'
 
 function attributeSelector(attribute: string, value: string): string {
-  return `[${attribute}="${value.replace(/["\\]/g, "\\$&")}"]`
+  return `[${attribute}="${value.replace(/["\\]/gu, "\\$&")}"]`
 }
 
 /**

package/src/multi-value-fields.test.tsx

@@ -3,8 +3,8 @@ import userEvent from "@zeno-lib/test/user-event"
 import { afterEach, describe, expect, test, vi } from "vitest"
 import { Form, FormProvider, useForm } from "./create-form"
 
-const TAGS = /Tags/
-const CLEAR = /Clear/
+const TAGS = /Tags/u
+const CLEAR = /Clear/u
 
 afterEach(() => {
   cleanup()

package/src/nullable-text.test.tsx

@@ -0,0 +1,80 @@
+import { cleanup, render, screen } from "@zeno-lib/test/testing-library"
+import userEvent from "@zeno-lib/test/user-event"
+import { afterEach, expect, test, vi } from "vitest"
+import { z } from "zod"
+import { Form, FormProvider, useForm } from "./create-form"
+
+afterEach(cleanup)
+
+test("a nullable text field holds null for no text, from the start and once emptied", async () => {
+  const user = userEvent.setup()
+  const schema = z.object({
+    note: z.string().nullable(),
+    optional: z.string().optional(),
+    title: z.string(),
+  })
+  const captured: { values?: unknown } = {}
+  function H() {
+    const form = useForm({ onSubmit: vi.fn(), schema })
+    const { InputField, Subscribe, TextAreaField } = form
+    return (
+      <FormProvider form={form}>
+        <Form>
+          <TextAreaField label="Note" name="note" />
+          <InputField label="Optional" name="optional" />
+          <InputField label="Title" name="title" />
+          <Subscribe selector={(state) => state.values}>
+            {(values) => {
+              captured.values = values
+              return null
+            }}
+          </Subscribe>
+        </Form>
+      </FormProvider>
+    )
+  }
+  render(<H />)
+  // An optional field keeps `""`: an update skips an `undefined` column, so
+  // emptying it would keep the stored text.
+  const empty = { note: null, optional: "", title: "" }
+  expect(captured.values).toStrictEqual(empty)
+
+  for (const label of ["Note", "Optional", "Title"]) {
+    // biome-ignore lint/performance/noAwaitInLoops: one field after another, as a user types
+    await user.type(screen.getByLabelText(label), "x")
+    await user.clear(screen.getByLabelText(label))
+  }
+  expect(captured.values).toStrictEqual(empty)
+})
+
+test("an emptied nullable text field holds null whatever the other fields hold", async () => {
+  const user = userEvent.setup()
+  // Once every field passes, the async refinement keeps the form from being
+  // checked synchronously.
+  const schema = z
+    .object({ note: z.string().nullable() })
+    .refine(async () => await Promise.resolve(true))
+  const captured: { values?: unknown } = {}
+  function H() {
+    const form = useForm({ onSubmit: vi.fn(), schema })
+    const { InputField, Subscribe } = form
+    return (
+      <FormProvider form={form}>
+        <Form>
+          <InputField label="Note" name="note" />
+          <Subscribe selector={(state) => state.values}>
+            {(values) => {
+              captured.values = values
+              return null
+            }}
+          </Subscribe>
+        </Form>
+      </FormProvider>
+    )
+  }
+  render(<H />)
+
+  await user.type(screen.getByRole("textbox"), "x")
+  await user.clear(screen.getByRole("textbox"))
+  expect(captured.values).toStrictEqual({ note: null })
+})

package/src/submit-action.test.tsx

@@ -14,10 +14,10 @@ afterEach(() => {
 })
 
 const SUBMIT = { name: "Submit" }
-const EMAIL_LABEL = /Email/
-const NAME_LABEL = /Name/
-const OWNER_1_SHARE_LABEL = /^Owner 1 share/
-const OWNER_2_SHARE_LABEL = /^Owner 2 share/
+const EMAIL_LABEL = /Email/u
+const NAME_LABEL = /Name/u
+const OWNER_1_SHARE_LABEL = /^Owner 1 share/u
+const OWNER_2_SHARE_LABEL = /^Owner 2 share/u
 
 function failure(
   fieldErrors: Record<string, string[]>,

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

@@ -12,16 +12,16 @@ import { z } from "zod"
 import { SelectItem } from "@/components/ui/select"
 import { Form, FormProvider, RadioGroupFieldItem, useForm } from "./create-form"
 
-const CONTACT_EMAIL_LABEL = /Contact email/
-const PASSWORD_LABEL = /Password/
-const NAME_LABEL = /Name/
-const ACCEPT_NAME = /Accept/
-const TITLE_LABEL = /Title/
-const NOTE_LABEL = /Note/
-const DAY_LABEL = /Day/
-const PICKED_DAY = /October 9/
-const ROLE_LABEL = /Role/
-const OWNER_LABEL = /Owner/
+const CONTACT_EMAIL_LABEL = /Contact email/u
+const PASSWORD_LABEL = /Password/u
+const NAME_LABEL = /Name/u
+const ACCEPT_NAME = /Accept/u
+const TITLE_LABEL = /Title/u
+const NOTE_LABEL = /Note/u
+const DAY_LABEL = /Day/u
+const PICKED_DAY = /October 9/u
+const ROLE_LABEL = /Role/u
+const OWNER_LABEL = /Owner/u
 const PICK_A_ROLE = "Pick a role"
 const PICK_A_DAY = "Pick a day"
 

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

@@ -4,8 +4,8 @@ import { afterEach, describe, expect, test, vi } from "vitest"
 import { z } from "zod"
 import { Form, FormProvider, useForm } from "./create-form"
 
-const DIET_LABEL = /Diet/
-const SAUSAGE_LABEL = /Sausage/
+const DIET_LABEL = /Diet/u
+const SAUSAGE_LABEL = /Sausage/u
 
 afterEach(() => {
   cleanup()

package/src/use-form.reset-defaults.test.tsx

@@ -14,8 +14,8 @@ afterEach(() => {
   cleanup()
 })
 
-const TITLE = /Title/
-const SAVE = /Save/
+const TITLE = /Title/u
+const SAVE = /Save/u
 
 const schema = z.object({ title: z.string().min(1) })
 

package/src/use-form.test.tsx

@@ -6,9 +6,9 @@ import { z } from "zod"
 import { Form, FormProvider, useForm } from "./create-form"
 import { ValidationError } from "./lib/validation-error"
 
-const EMAIL_LABEL = /Email/
-const VALID_EMAIL_MSG = /Enter a valid email/i
-const SUBMIT_NAME = /Submit/
+const EMAIL_LABEL = /Email/u
+const VALID_EMAIL_MSG = /Enter a valid email/iu
+const SUBMIT_NAME = /Submit/u
 
 // @testing-library auto-cleanup only runs with `globals: true`. Our vitest
 // config keeps globals off (we import test helpers explicitly), so add the

package/src/use-form.unsaved-warning.test.tsx

@@ -4,7 +4,7 @@ import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"
 import { z } from "zod"
 import { Form, FormProvider, useForm } from "./create-form"
 
-const NAME_LABEL = /Name/
+const NAME_LABEL = /Name/u
 
 let addSpy: ReturnType<typeof vi.spyOn>
 let removeSpy: ReturnType<typeof vi.spyOn>

package/src/use-form.validation-modes.test.tsx

@@ -30,8 +30,8 @@ function Harness({ mode }: { mode?: ValidationMode }) {
   )
 }
 
-const ERROR = /Enter a valid email/i
-const EMAIL_LABEL = /Email/
+const ERROR = /Enter a valid email/iu
+const EMAIL_LABEL = /Email/u
 
 function getInput() {
   return screen.getByLabelText(EMAIL_LABEL) as HTMLInputElement

package/src/with-form.test.tsx

@@ -4,7 +4,7 @@ import { afterEach, expect, test, vi } from "vitest"
 import { z } from "zod"
 import { Form, FormProvider, useForm, withForm } from "./create-form"
 
-const CITY = /City/
+const CITY = /City/u
 
 afterEach(() => {
   cleanup()