@zeno-lib/forms 0.0.1 → 0.2.0

package/src/lib/use-formatted-number.ts

@@ -0,0 +1,235 @@
+"use client"
+
+import {
+  type ChangeEvent,
+  type ClipboardEvent,
+  useLayoutEffect,
+  useReducer,
+  useRef,
+  useState,
+} from "react"
+
+import {
+  formatNumber,
+  mapCaret,
+  parseLocaleNumber,
+  parseTypedNumber,
+  roundTo,
+} from "./formatted-number"
+
+type UseFormattedNumberOptions = {
+  /** The stored value. `null`/`undefined` renders an empty input. */
+  value: number | null | undefined
+  /** Called with the parsed value when the user types, pastes, or blurs. */
+  onValueChange: (value: number | null) => void
+  /** Called after the blur re-format (wire the field's `handleBlur` here). */
+  onBlur?: () => void
+  /** BCP 47 locale for separators. Defaults to the runtime locale. */
+  locale?: string
+  /** Digits allowed after the decimal separator. Defaults to `2`. */
+  maximumFractionDigits?: number
+  /**
+   * Pad a non-integer value to `maximumFractionDigits` on blur (`12.5` →
+   * `12.50`). Integers stay bare (`12`). Defaults to `false`.
+   */
+  padFraction?: boolean
+  /** Insert thousands separators. Defaults to `true`. */
+  useGrouping?: boolean
+  /** Accept a leading minus. Defaults to `true`. */
+  allowNegative?: boolean
+  /** Drop integer digits beyond this count while typing. */
+  maxIntegerDigits?: number
+  /** Clamp the stored value on blur. */
+  min?: number
+  /** Clamp the stored value on blur. */
+  max?: number
+  /**
+   * Map the stored value to the number shown in the input, e.g.
+   * `(v) => v * 100` to edit a `0–1` fraction as a percentage. Pair with
+   * `fromDisplay`.
+   */
+  toDisplay?: (value: number) => number
+  /** Inverse of `toDisplay`. */
+  fromDisplay?: (display: number) => number
+}
+
+type FormattedNumberInputProps = {
+  inputMode: "decimal" | "numeric"
+  onBlur: () => void
+  onChange: (event: ChangeEvent<HTMLInputElement>) => void
+  onPaste: (event: ClipboardEvent<HTMLInputElement>) => void
+  type: "text"
+  value: string
+}
+
+const identity = (value: number) => value
+
+function clamp(value: number, min?: number, max?: number): number {
+  let next = value
+  if (min !== undefined && next < min) {
+    next = min
+  }
+  if (max !== undefined && next > max) {
+    next = max
+  }
+  return next
+}
+
+/**
+ * Headless, locale-aware formatted number input.
+ *
+ * Keeps the input's text in local state so the user can type freely
+ * (`"1’2"`, `"12."`), re-inserting group separators as they type while
+ * holding the caret in place, and parses the text into a `number | null`
+ * for the form. Pasted text is parsed leniently (`"CHF 1'234.50"`,
+ * `"1.234,50"`). On blur the value is clamped to `min`/`max` and the text
+ * re-formatted. External value changes (e.g. `form.reset`) re-sync the text.
+ *
+ * Returns props to spread on an `<input>`; UI-free, so any input component
+ * can use it.
+ */
+function useFormattedNumber({
+  value,
+  onValueChange,
+  onBlur,
+  locale,
+  maximumFractionDigits = 2,
+  padFraction = false,
+  useGrouping = true,
+  allowNegative = true,
+  maxIntegerDigits,
+  min,
+  max,
+  toDisplay = identity,
+  fromDisplay = identity,
+}: UseFormattedNumberOptions): FormattedNumberInputProps {
+  const current = value ?? null
+
+  const display = (stored: number | null): string => {
+    if (stored === null) {
+      return ""
+    }
+    const shown = roundTo(toDisplay(stored), maximumFractionDigits)
+    return formatNumber(shown, {
+      locale,
+      maximumFractionDigits,
+      minimumFractionDigits:
+        padFraction && !Number.isInteger(shown) ? maximumFractionDigits : 0,
+      useGrouping,
+    })
+  }
+
+  const [text, setText] = useState(() => display(current))
+  // The value the text was last derived from or parsed into. When the prop
+  // drifts from it, something outside the input changed the value.
+  const [synced, setSynced] = useState<number | null>(current)
+  if (!Object.is(current, synced)) {
+    setSynced(current)
+    setText(display(current))
+  }
+
+  // Re-render even when the re-formatted text is unchanged (a rejected
+  // keystroke), so the layout effect can put the caret back after React
+  // restores the controlled value.
+  const [, forceRender] = useReducer((n: number) => n + 1, 0)
+  const pendingCaret = useRef<{ input: HTMLInputElement; at: number } | null>(
+    null
+  )
+  useLayoutEffect(() => {
+    const pending = pendingCaret.current
+    if (!pending) {
+      return
+    }
+    pendingCaret.current = null
+    if (pending.input.ownerDocument.activeElement === pending.input) {
+      pending.input.setSelectionRange(pending.at, pending.at)
+    }
+  })
+
+  const fromDisplayRounded = (shown: number) =>
+    fromDisplay === identity
+      ? shown
+      : roundTo(fromDisplay(shown), maximumFractionDigits + 4)
+
+  const commit = (nextText: string, nextValue: number | null) => {
+    setText(nextText)
+    setSynced(nextValue)
+    if (!Object.is(nextValue, current)) {
+      onValueChange(nextValue)
+    }
+  }
+
+  const onChange = (event: ChangeEvent<HTMLInputElement>) => {
+    const input = event.target
+    const raw = input.value
+    const typed = parseTypedNumber(raw, {
+      allowNegative,
+      locale,
+      maxIntegerDigits,
+      maximumFractionDigits,
+      useGrouping,
+    })
+    const caret = input.selectionStart ?? raw.length
+    pendingCaret.current = {
+      at: mapCaret(raw, caret, typed.text, locale),
+      input,
+    }
+    commit(
+      typed.text,
+      typed.value === null ? null : fromDisplayRounded(typed.value)
+    )
+    forceRender()
+  }
+
+  const onPaste = (event: ClipboardEvent<HTMLInputElement>) => {
+    const input = event.currentTarget
+    const replacesAll =
+      input.value === "" ||
+      (input.selectionStart === 0 && input.selectionEnd === input.value.length)
+    if (!replacesAll) {
+      return // partial paste: let the change handler re-format the result
+    }
+    const parsed = parseLocaleNumber(
+      event.clipboardData.getData("text"),
+      locale
+    )
+    if (parsed === null) {
+      return
+    }
+    const shown = roundTo(
+      allowNegative ? parsed : Math.abs(parsed),
+      maximumFractionDigits
+    )
+    if (
+      maxIntegerDigits !== undefined &&
+      Math.abs(Math.trunc(shown)) >= 10 ** maxIntegerDigits
+    ) {
+      return // too long: the change handler truncates the pasted digits
+    }
+    event.preventDefault()
+    const stored = fromDisplayRounded(shown)
+    commit(display(stored), stored)
+  }
+
+  const handleBlur = () => {
+    if (current === null) {
+      setText("")
+    } else {
+      const clamped = clamp(current, min, max)
+      commit(display(clamped), clamped)
+    }
+    onBlur?.()
+  }
+
+  return {
+    inputMode: maximumFractionDigits > 0 ? "decimal" : "numeric",
+    onBlur: handleBlur,
+    onChange,
+    onPaste,
+    type: "text",
+    value: text,
+  }
+}
+
+export type { FormattedNumberInputProps, UseFormattedNumberOptions }
+export { useFormattedNumber }

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/multi-value-fields.test.tsx

@@ -0,0 +1,116 @@
+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 { Form, FormProvider, useForm } from "./create-form"
+
+const TAGS = /Tags/
+const CLEAR = /Clear/
+
+afterEach(() => {
+  cleanup()
+})
+
+type Box<T> = { current: T | undefined }
+
+describe("MultiSelectField", () => {
+  const ITEMS = [
+    { label: "One", value: 1 },
+    { label: "Two", value: 2 },
+    { label: "Three", value: 3 },
+  ]
+  const DEFAULTS = { ids: [3] as number[] }
+
+  function Harness({ captured }: { captured: Box<number[]> }) {
+    const form = useForm({ defaultValues: DEFAULTS, onSubmit: vi.fn() })
+    const { MultiSelectField, Subscribe } = form
+    return (
+      <FormProvider form={form}>
+        <Form>
+          <MultiSelectField
+            items={ITEMS}
+            label="Tags"
+            name="ids"
+            placeholder="Pick"
+          />
+          <Subscribe selector={(state) => state.values.ids}>
+            {(ids) => {
+              captured.current = ids
+              return null
+            }}
+          </Subscribe>
+        </Form>
+      </FormProvider>
+    )
+  }
+
+  test("renders selected values as chips and appends picks as numbers", async () => {
+    const user = userEvent.setup()
+    const captured: Box<number[]> = { current: undefined }
+    const { container } = render(<Harness captured={captured} />)
+    expect(container.querySelector("[data-field=ids]")?.textContent).toContain(
+      "Three"
+    )
+
+    await user.click(screen.getByLabelText(TAGS))
+    await user.click(await screen.findByRole("option", { name: "One" }))
+    expect(captured.current).toEqual([3, 1])
+  })
+
+  test("the clear button empties the selection", async () => {
+    const user = userEvent.setup()
+    const captured: Box<number[]> = { current: undefined }
+    render(<Harness captured={captured} />)
+    await user.click(screen.getByRole("button", { name: CLEAR }))
+    expect(captured.current).toEqual([])
+  })
+})
+
+describe("CheckboxGroupField", () => {
+  const DEFAULTS = { days: [] as string[] }
+
+  function Harness({ captured }: { captured: Box<string[]> }) {
+    const form = useForm({ defaultValues: DEFAULTS, onSubmit: vi.fn() })
+    const { CheckboxGroupField, Subscribe } = form
+    return (
+      <FormProvider form={form}>
+        <Form>
+          <CheckboxGroupField
+            items={[
+              "mon",
+              "tue",
+              { disabled: true, label: "Wednesday", value: "wed" },
+            ]}
+            label="Days"
+            name="days"
+          />
+          <Subscribe selector={(state) => state.values.days}>
+            {(days) => {
+              captured.current = days
+              return null
+            }}
+          </Subscribe>
+        </Form>
+      </FormProvider>
+    )
+  }
+
+  test("toggles values and keeps the order of items", async () => {
+    const user = userEvent.setup()
+    const captured: Box<string[]> = { current: undefined }
+    render(<Harness captured={captured} />)
+    await user.click(screen.getByRole("checkbox", { name: "tue" }))
+    await user.click(screen.getByRole("checkbox", { name: "mon" }))
+    expect(captured.current).toEqual(["mon", "tue"])
+    await user.click(screen.getByRole("checkbox", { name: "tue" }))
+    expect(captured.current).toEqual(["mon"])
+  })
+
+  test("renders a labelled group and honours per-option disabled", () => {
+    render(<Harness captured={{ current: undefined }} />)
+    expect(screen.getByRole("group", { name: "Days" })).toBeTruthy()
+    const wed = screen.getByRole("checkbox", { name: "Wednesday" })
+    expect(
+      wed.getAttribute("aria-disabled") ?? wed.getAttribute("data-disabled")
+    ).not.toBeNull()
+  })
+})