@zeno-lib/forms 0.0.1 → 0.2.0

package/src/form-dialog.tsx

@@ -0,0 +1,253 @@
+"use client"
+
+import { FormProvider } from "@zeno-lib/forms"
+import {
+  type FormDialogController,
+  findFieldElement,
+  useLeaveGuard,
+} from "@zeno-lib/forms/lib/use-form-dialog"
+import { useUnsavedChangesWarning } from "@zeno-lib/forms/lib/use-unsaved-changes-warning"
+import { type AnyFormApi, useSelector } from "@zeno-lib/forms/tanstack"
+import {
+  type FormEvent,
+  type ReactElement,
+  type ReactNode,
+  useId,
+  useLayoutEffect,
+  useRef,
+} from "react"
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog"
+import { Button } from "@/components/ui/button"
+import {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog"
+import { Spinner } from "@/components/ui/spinner"
+
+type DiscardPromptText = {
+  title?: ReactNode
+  description?: ReactNode
+  confirmLabel?: ReactNode
+  cancelLabel?: ReactNode
+}
+
+// The slice of the `useForm()` API the dialog uses. Structural, so any Zeno /
+// TanStack form fits whatever its validator and submit-meta generics are.
+type DialogFormState = {
+  isDefaultValue: boolean
+  isSubmitSuccessful: boolean
+  isSubmitting: boolean
+  isValid: boolean
+}
+
+type DialogForm<TValues> = {
+  store: {
+    get: () => DialogFormState
+    subscribe: (listener: (state: DialogFormState) => void) => {
+      unsubscribe: () => void
+    }
+  }
+  readonly state: DialogFormState
+  handleSubmit(): unknown
+  reset(values?: TValues): void
+}
+
+type FormDialogProps<TValues> = {
+  /** The controller from `useFormDialog()`. */
+  dialog: FormDialogController<TValues>
+  /** The form from `useForm()`; its `onSubmit` runs on Save. */
+  form: DialogForm<TValues>
+  title: ReactNode
+  description?: ReactNode
+  /** The fields. Rendered inside the `<form>`. */
+  children: ReactNode
+  /** Element that opens the dialog (with the hook's defaults) on click. */
+  trigger?: ReactElement
+  /** Defaults to `"Save"`. */
+  submitLabel?: ReactNode
+  /** Defaults to `"Cancel"`. */
+  cancelLabel?: ReactNode
+  /** Extra footer content, rendered before Cancel / Save. */
+  footer?: ReactNode
+  /** Close after a successful submit. Defaults to `true`. */
+  closeOnSubmit?: boolean
+  /**
+   * Ask before closing with unsaved changes, and warn on page unload while
+   * open. Defaults to `true`.
+   */
+  guard?: boolean
+  /** Copy for the discard prompt. */
+  discardPrompt?: DiscardPromptText
+  /** Class for the dialog popup (e.g. a wider `sm:max-w-lg`). */
+  className?: string
+  /** Class for the `<form>` element. */
+  formClassName?: string
+}
+
+/**
+ * A dialog-hosted form: opens with fresh values per session, submits from a
+ * footer button outside the `<form>` (via `form="id"`), shows a spinner while
+ * submitting, closes on success, and asks before discarding unsaved changes
+ * (Cancel, ×, Escape, outside press) or leaving the page.
+ */
+function FormDialog<TValues>({
+  cancelLabel = "Cancel",
+  children,
+  className,
+  closeOnSubmit = true,
+  description,
+  dialog,
+  discardPrompt,
+  footer,
+  form,
+  formClassName,
+  guard = true,
+  submitLabel = "Save",
+  title,
+  trigger,
+}: FormDialogProps<TValues>) {
+  const formId = useId()
+  const popupRef = useRef<HTMLDivElement>(null)
+  const { close, defaultValues, focus, isOpen, open, session } = dialog
+
+  // `isDefaultValue`, not `isDirty`: `isDirty` stays true after the user
+  // reverts an edit, `isDefaultValue` compares the values themselves.
+  const hasChanges = useSelector(form.store, (state) => !state.isDefaultValue)
+  const isSubmitting = useSelector(form.store, (state) => state.isSubmitting)
+  const { cancelLeave, confirmLeave, isConfirming, requestLeave } =
+    useLeaveGuard({ hasUnsavedChanges: guard && hasChanges })
+  useUnsavedChangesWarning(
+    form as unknown as AnyFormApi,
+    guard && isOpen ? "if-changed" : false
+  )
+
+  // Start every session from its own defaults. `reset(values)` also rebases
+  // the form's defaults, so the session's values count as "unchanged".
+  // biome-ignore lint/correctness/useExhaustiveDependencies: once per session.
+  useLayoutEffect(() => {
+    if (session > 0) {
+      form.reset(defaultValues)
+    }
+  }, [session])
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault()
+    event.stopPropagation()
+    try {
+      await form.handleSubmit()
+    } catch {
+      return // the submit handler threw; keep the dialog open
+    }
+    const { isSubmitSuccessful, isValid } = form.state
+    if (closeOnSubmit && isSubmitSuccessful && isValid) {
+      // Close directly, past the guard: the changes are saved. The form is
+      // reset once the exit animation completes (see `onOpenChangeComplete`).
+      close()
+    }
+  }
+
+  return (
+    <Dialog
+      onOpenChange={(next) => {
+        if (next) {
+          open()
+        } else {
+          requestLeave(close)
+        }
+      }}
+      onOpenChangeComplete={(opened) => {
+        // Drop abandoned edits once the close animation is done, so the
+        // fields don't visibly snap back while fading out.
+        if (!opened) {
+          form.reset()
+        }
+      }}
+      open={isOpen}
+    >
+      {trigger && <DialogTrigger render={trigger} />}
+      <DialogContent
+        className={className}
+        initialFocus={() => {
+          const target = focus
+            ? findFieldElement(popupRef.current, focus)
+            : null
+          return target ?? true
+        }}
+        ref={popupRef}
+      >
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+          {description && <DialogDescription>{description}</DialogDescription>}
+        </DialogHeader>
+        <FormProvider form={form}>
+          <form
+            className={formClassName}
+            id={formId}
+            noValidate
+            onSubmit={handleSubmit}
+          >
+            {children}
+          </form>
+        </FormProvider>
+        <DialogFooter>
+          {footer}
+          <DialogClose render={<Button type="button" variant="outline" />}>
+            {cancelLabel}
+          </DialogClose>
+          <Button disabled={isSubmitting} form={formId} type="submit">
+            {isSubmitting && <Spinner />}
+            {submitLabel}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+      {/* Inside the Dialog root (so it nests over the form) but outside the
+          popup (so it can finish its own exit animation). */}
+      <AlertDialog
+        onOpenChange={(next) => {
+          if (!next) {
+            cancelLeave()
+          }
+        }}
+        open={isConfirming}
+      >
+        <AlertDialogContent size="sm">
+          <AlertDialogHeader>
+            <AlertDialogTitle>
+              {discardPrompt?.title ?? "Discard changes?"}
+            </AlertDialogTitle>
+            <AlertDialogDescription>
+              {discardPrompt?.description ??
+                "Your unsaved changes will be lost."}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>
+              {discardPrompt?.cancelLabel ?? "Keep editing"}
+            </AlertDialogCancel>
+            <AlertDialogAction onClick={confirmLeave} variant="destructive">
+              {discardPrompt?.confirmLabel ?? "Discard"}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </Dialog>
+  )
+}
+
+export type { DialogForm, DiscardPromptText, FormDialogProps }
+export { FormDialog }

package/src/form-element.tsx

@@ -0,0 +1,51 @@
+"use client"
+
+import type { AnyFormApi } from "@tanstack/react-form"
+import type { ComponentProps, FormEvent, ReactNode } from "react"
+
+import { FormProvider as RawFormProvider, useFormContext } from "./lib/contexts"
+
+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={async (event: FormEvent<HTMLFormElement>) => {
+        event.preventDefault()
+        event.stopPropagation()
+        const node = event.currentTarget
+        await Promise.resolve(form.handleSubmit()).catch(() => undefined)
+        if (!form.state.isValid) {
+          // First invalid control in *this* form; a group root (radio group,
+          // slider) hands focus to its first tabbable child.
+          const invalid = node.querySelector<HTMLElement>(
+            '[aria-invalid="true"]'
+          )
+          const targets = invalid
+            ? [invalid, ...invalid.querySelectorAll<HTMLElement>("*")]
+            : []
+          targets.find((el) => el.tabIndex >= 0)?.focus()
+        }
+      }}
+      {...props}
+    >
+      {children}
+    </form>
+  )
+}
+
+export { Form, FormProvider }

package/src/formatted-number-fields.test.tsx

@@ -0,0 +1,236 @@
+import {
+  act,
+  cleanup,
+  fireEvent,
+  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 { getNumberSeparators } from "./lib/formatted-number"
+
+const AMOUNT = /Amount/
+const RATE = /Rate/
+const YEAR = /Year/
+const CH = getNumberSeparators("de-CH").group
+
+afterEach(() => {
+  cleanup()
+})
+
+type Captured = { current: ReturnType<typeof useAmountForm> | null }
+
+const AMOUNT_DEFAULTS = { amount: null as number | null }
+
+function useAmountForm(onSubmit = vi.fn()) {
+  return useForm({ defaultValues: AMOUNT_DEFAULTS, onSubmit })
+}
+
+function MoneyHarness({
+  captured,
+  locale = "de-CH",
+  currency = "CHF",
+}: {
+  captured?: Captured
+  locale?: string
+  currency?: string
+}) {
+  const form = useAmountForm()
+  if (captured) {
+    captured.current = form
+  }
+  const { MoneyField } = form
+  return (
+    <FormProvider form={form}>
+      <Form>
+        <MoneyField
+          currency={currency}
+          label="Amount"
+          locale={locale}
+          name="amount"
+        />
+      </Form>
+    </FormProvider>
+  )
+}
+
+describe("MoneyField", () => {
+  test("formats with thousands separators while typing and stores a number", async () => {
+    const user = userEvent.setup()
+    const captured: Captured = { current: null }
+    render(<MoneyHarness captured={captured} />)
+    const input = screen.getByLabelText(AMOUNT) as HTMLInputElement
+    expect(input.inputMode).toBe("decimal")
+    expect(input.type).toBe("text")
+
+    await user.type(input, "1234567.5")
+    expect(input.value).toBe(`1${CH}234${CH}567.5`)
+    expect(captured.current?.state.values.amount).toBe(1_234_567.5)
+
+    await user.tab()
+    expect(input.value).toBe(`1${CH}234${CH}567.50`)
+  })
+
+  test("shows the currency as an add-on on the locale's side", () => {
+    render(<MoneyHarness />)
+    const addon = screen.getByText("CHF")
+    const group = addon.closest("[data-slot=input-group-addon]")
+    expect(group?.getAttribute("data-align")).toBe("inline-start")
+  })
+
+  test("parses pasted text from another locale", () => {
+    const captured: Captured = { current: null }
+    render(<MoneyHarness captured={captured} />)
+    const input = screen.getByLabelText(AMOUNT) as HTMLInputElement
+    fireEvent.paste(input, {
+      clipboardData: { getData: () => "EUR 1.234,56" },
+    })
+    expect(captured.current?.state.values.amount).toBe(1234.56)
+    expect(input.value).toBe(`1${CH}234.56`)
+  })
+
+  test("clearing the input stores null", async () => {
+    const user = userEvent.setup()
+    const captured: Captured = { current: null }
+    render(<MoneyHarness captured={captured} />)
+    const input = screen.getByLabelText(AMOUNT) as HTMLInputElement
+    await user.type(input, "12")
+    await user.clear(input)
+    expect(captured.current?.state.values.amount).toBeNull()
+  })
+
+  test("re-syncs the text when the value changes from outside", async () => {
+    const user = userEvent.setup()
+    const captured: Captured = { current: null }
+    render(<MoneyHarness captured={captured} />)
+    const input = screen.getByLabelText(AMOUNT) as HTMLInputElement
+    await user.type(input, "5")
+    act(() => {
+      captured.current?.setFieldValue("amount", 9876)
+    })
+    console.log(
+      "VALS",
+      JSON.stringify(captured.current?.state.values),
+      input.value
+    )
+    expect(input.value).toBe(`9${CH}876`)
+  })
+
+  test("rejects letters and keeps integers bare on blur", async () => {
+    const user = userEvent.setup()
+    render(<MoneyHarness />)
+    const input = screen.getByLabelText(AMOUNT) as HTMLInputElement
+    await user.type(input, "12a3")
+    expect(input.value).toBe("123")
+    await user.tab()
+    expect(input.value).toBe("123")
+  })
+})
+
+describe("PercentageField", () => {
+  function PercentHarness({
+    captured,
+    scale,
+  }: {
+    captured: { current: number | null | undefined }
+    scale?: "fraction" | "percent"
+  }) {
+    const form = useForm({
+      defaultValues: { rate: 0.05 as number | null },
+      onSubmit: vi.fn(),
+    })
+    const { PercentageField, Subscribe } = form
+    return (
+      <FormProvider form={form}>
+        <Form>
+          <PercentageField
+            label="Rate"
+            locale="en-US"
+            name="rate"
+            scale={scale}
+          />
+          <Subscribe selector={(state) => state.values.rate}>
+            {(rate) => {
+              captured.current = rate
+              return null
+            }}
+          </Subscribe>
+        </Form>
+      </FormProvider>
+    )
+  }
+
+  test("edits a 0–1 fraction as a percentage with scale='fraction'", async () => {
+    const user = userEvent.setup()
+    const captured = { current: undefined as number | null | undefined }
+    render(<PercentHarness captured={captured} scale="fraction" />)
+    const input = screen.getByLabelText(RATE) as HTMLInputElement
+    expect(input.value).toBe("5")
+    expect(screen.getByText("%")).toBeTruthy()
+
+    await user.clear(input)
+    await user.type(input, "12.5")
+    expect(captured.current).toBe(0.125)
+  })
+
+  test("stores the typed number by default", async () => {
+    const user = userEvent.setup()
+    const captured = { current: undefined as number | null | undefined }
+    render(<PercentHarness captured={captured} />)
+    const input = screen.getByLabelText(RATE) as HTMLInputElement
+    await user.clear(input)
+    await user.type(input, "7.25")
+    expect(captured.current).toBe(7.25)
+  })
+})
+
+describe("YearField", () => {
+  function YearHarness({
+    captured,
+  }: {
+    captured: { current: number | null | undefined }
+  }) {
+    const form = useForm({
+      onSubmit: vi.fn(),
+      schema: z.object({ year: z.number().int().nullable() }),
+    })
+    const { Subscribe, YearField } = form
+    return (
+      <FormProvider form={form}>
+        <Form>
+          <YearField label="Year" max={2100} min={1900} name="year" />
+          <Subscribe selector={(state) => state.values.year}>
+            {(year) => {
+              captured.current = year
+              return null
+            }}
+          </Subscribe>
+        </Form>
+      </FormProvider>
+    )
+  }
+
+  test("caps at four digits without grouping", async () => {
+    const user = userEvent.setup()
+    const captured = { current: undefined as number | null | undefined }
+    render(<YearHarness captured={captured} />)
+    const input = screen.getByLabelText(YEAR) as HTMLInputElement
+    expect(input.inputMode).toBe("numeric")
+    await user.type(input, "20245")
+    expect(input.value).toBe("2024")
+    expect(captured.current).toBe(2024)
+  })
+
+  test("clamps to min/max on blur", async () => {
+    const user = userEvent.setup()
+    const captured = { current: undefined as number | null | undefined }
+    render(<YearHarness captured={captured} />)
+    const input = screen.getByLabelText(YEAR) as HTMLInputElement
+    await user.type(input, "1850")
+    await user.tab()
+    expect(input.value).toBe("1900")
+    expect(captured.current).toBe(1900)
+  })
+})

package/src/index.ts

@@ -0,0 +1,27 @@
+/* biome-ignore-all lint/performance/noBarrelFile: single npm entry for the headless form API. */
+
+export { createZenoForm } from "./create-zeno-form"
+export { Form, FormProvider } from "./form-element"
+export {
+  type ActionError,
+  type ActionIssue,
+  type ActionResult,
+  toActionError,
+  toFieldName,
+} from "./lib/action-result"
+export { applyValidationError } from "./lib/apply-validation-error"
+export { useFieldContext, useFormContext } from "./lib/contexts"
+export {
+  applyActionError,
+  type SubmitActionOptions,
+  type SubmitActionSchema,
+  submitAction,
+} from "./lib/submit-action"
+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"

package/src/lib/action-result.ts

@@ -0,0 +1,61 @@
+// The result shape a server action returns to a form. Declared here rather
+// than imported so `@zeno-lib/forms` has no dependency on a server package:
+// `defineFormAction` in `@zeno-lib/db/next` returns the same shape, and any
+// action that resolves to it (hand-written or from another library) works
+// with `submitAction`. The types are read-only so a producer's mutable arrays
+// are assignable.
+
+type ActionError = {
+  // Keyed by TanStack Form field name: `address.city`, `owners[0].percentage`.
+  readonly fieldErrors: Readonly<Record<string, readonly string[]>>
+  // Messages with no field (a whole-object refinement, a closed record).
+  readonly formErrors: readonly string[]
+}
+
+type ActionResult<TData> =
+  | { readonly ok: true; readonly data: TData }
+  | { readonly ok: false; readonly error: ActionError }
+
+// A Standard Schema issue, reduced to what the path mapping reads.
+type ActionIssue = {
+  readonly message: string
+  readonly path?:
+    | ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>
+    | undefined
+}
+
+// `["owners", 0, "percentage"]` → `owners[0].percentage`, the name the field
+// was registered under. An empty path yields `""`.
+function toFieldName(path: ActionIssue["path"]): string {
+  let name = ""
+  for (const segment of path ?? []) {
+    const key = typeof segment === "object" ? segment.key : segment
+    if (typeof key === "number") {
+      name += `[${key}]`
+    } else {
+      const part = typeof key === "symbol" ? (key.description ?? "") : key
+      name += name === "" ? part : `.${part}`
+    }
+  }
+  return name
+}
+
+// Group issues by field name; a path-less issue goes to `formErrors`.
+function toActionError(issues: readonly ActionIssue[]): ActionError {
+  const fieldErrors: Record<string, string[]> = {}
+  const formErrors: string[] = []
+  for (const issue of issues) {
+    const name = toFieldName(issue.path)
+    if (name === "") {
+      formErrors.push(issue.message)
+    } else {
+      const messages = fieldErrors[name] ?? []
+      messages.push(issue.message)
+      fieldErrors[name] = messages
+    }
+  }
+  return { fieldErrors, formErrors }
+}
+
+export type { ActionError, ActionIssue, ActionResult }
+export { toActionError, toFieldName }

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

@@ -1,6 +1,5 @@
 import type { AnyFormApi } from "@tanstack/react-form"
-import { describe, expect, test, vi } from "@zeno-lib/vitest"
-
+import { describe, expect, test, vi } from "vitest"
 import { applyValidationError } from "./apply-validation-error"
 import { ValidationError } from "./validation-error"
 
@@ -14,8 +13,15 @@ function makeFormStub() {
     (_name: string, _updater: FieldMetaUpdater) => undefined
   )
   const setErrorMap = vi.fn((_map: unknown) => undefined)
+  const store = { subscribe: vi.fn(() => ({ unsubscribe: vi.fn() })) }
   return {
-    api: { setErrorMap, setFieldMeta } as unknown as AnyFormApi,
+    api: {
+      getFieldMeta: vi.fn(() => undefined),
+      getFieldValue: vi.fn(() => undefined),
+      setErrorMap,
+      setFieldMeta,
+      store,
+    } as unknown as AnyFormApi,
     setErrorMap,
     setFieldMeta,
   }
@@ -41,7 +47,7 @@ describe("applyValidationError", () => {
     expect(next.isValid).toBe(false)
   })
 
-  test("array of messages forwards all entries; errorMap.onChange gets first", () => {
+  test("array of messages forwards all entries, errorMap.onChange included", () => {
     const { api, setFieldMeta } = makeFormStub()
     applyValidationError(
       api,
@@ -50,10 +56,14 @@ describe("applyValidationError", () => {
     const updater = setFieldMeta.mock.calls[0]?.[1] as FieldMetaUpdater
     const next = updater({}) as {
       errors: { message: string }[]
-      errorMap: { onChange: { message: string } }
+      errorMap: { onChange: { message: string }[] }
     }
     expect(next.errors).toEqual([{ message: "short" }, { message: "no digit" }])
-    expect(next.errorMap.onChange).toEqual({ message: "short" })
+    // TanStack flattens an array entry into `meta.errors`, so every message shows.
+    expect(next.errorMap.onChange).toEqual([
+      { message: "short" },
+      { message: "no digit" },
+    ])
   })
 
   test("preserves existing errorMap keys via spread", () => {