@zeno-lib/forms 0.1.0 → 0.2.0

package/src/form-dialog.test.tsx

@@ -0,0 +1,161 @@
+import {
+  cleanup,
+  render,
+  screen,
+  waitFor,
+} 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 { useForm } from "./create-form"
+import { FormDialog } from "./form-dialog"
+import { useFormDialog } from "./lib/use-form-dialog"
+
+const NAME = /Name/
+const EMAIL = /Email/
+
+afterEach(() => {
+  cleanup()
+})
+
+const schema = z.object({
+  email: z.string(),
+  name: z.string().min(1, "Required"),
+})
+type Values = z.infer<typeof schema>
+const BLANK: Values = { email: "", name: "" }
+const ROW: Values = { email: "ada@example.com", name: "Ada" }
+
+function Harness({
+  onSubmit = vi.fn(),
+  closeOnSubmit,
+}: {
+  onSubmit?: (values: Values) => unknown
+  closeOnSubmit?: boolean
+}) {
+  const dialog = useFormDialog({ defaultValues: BLANK })
+  const form = useForm({
+    defaultValues: dialog.defaultValues,
+    onSubmit: ({ value }) => onSubmit(value),
+    schema,
+  })
+  const { InputField } = form
+  return (
+    <>
+      <button onClick={() => dialog.open()} type="button">
+        New
+      </button>
+      <button
+        onClick={() => dialog.open({ defaultValues: ROW, focus: "email" })}
+        type="button"
+      >
+        Edit
+      </button>
+      <FormDialog
+        closeOnSubmit={closeOnSubmit}
+        dialog={dialog}
+        form={form}
+        title="Person"
+      >
+        <InputField label="Name" name="name" />
+        <InputField label="Email" name="email" />
+      </FormDialog>
+    </>
+  )
+}
+
+// Open the "Edit" session and wait for its initial focus (on Email) to land,
+// so later typing isn't raced by the dialog's focus management.
+async function openEdit(user: ReturnType<typeof userEvent.setup>) {
+  await user.click(screen.getByRole("button", { name: "Edit" }))
+  const email = await screen.findByLabelText(EMAIL)
+  await waitFor(() => expect(document.activeElement).toBe(email))
+  return screen.getByLabelText(NAME) as HTMLInputElement
+}
+
+describe("FormDialog", () => {
+  test("opens with per-session defaults and focuses the requested field", async () => {
+    const user = userEvent.setup()
+    render(<Harness />)
+    const name = await openEdit(user)
+    expect(name.value).toBe("Ada")
+  })
+
+  test("closes without asking when nothing changed", async () => {
+    const user = userEvent.setup()
+    render(<Harness />)
+    await openEdit(user)
+    await user.click(screen.getByRole("button", { name: "Cancel" }))
+    await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull())
+  })
+
+  test("asks before discarding, keeps editing on cancel, resets on discard", async () => {
+    const user = userEvent.setup()
+    render(<Harness />)
+    const name = await openEdit(user)
+    await user.type(name, "!")
+    await user.keyboard("{Escape}")
+
+    await screen.findByRole("alertdialog")
+    await user.click(screen.getByRole("button", { name: "Keep editing" }))
+    await waitFor(() => expect(screen.queryByRole("alertdialog")).toBeNull())
+    expect((screen.getByLabelText(NAME) as HTMLInputElement).value).toBe("Ada!")
+
+    await user.click(screen.getByRole("button", { name: "Cancel" }))
+    await user.click(await screen.findByRole("button", { name: "Discard" }))
+    await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull())
+
+    // Reopening a blank session shows the blank defaults, not the old edit.
+    await user.click(screen.getByRole("button", { name: "New" }))
+    expect(
+      ((await screen.findByLabelText(NAME)) as HTMLInputElement).value
+    ).toBe("")
+  })
+
+  test("reverting an edit counts as unchanged (isDefaultValue, not isDirty)", async () => {
+    const user = userEvent.setup()
+    render(<Harness />)
+    const name = await openEdit(user)
+    await user.type(name, "x{Backspace}")
+    await user.click(screen.getByRole("button", { name: "Cancel" }))
+    await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull())
+    expect(screen.queryByRole("alertdialog")).toBeNull()
+  })
+
+  test("submits from the footer button and closes on success", async () => {
+    const user = userEvent.setup()
+    const onSubmit = vi.fn()
+    render(<Harness onSubmit={onSubmit} />)
+    const name = await openEdit(user)
+    await user.type(name, "!")
+    const save = screen.getByRole("button", { name: "Save" })
+    expect(save.closest("form")).toBeNull()
+    await user.click(save)
+    await waitFor(() =>
+      expect(onSubmit).toHaveBeenCalledWith({
+        email: "ada@example.com",
+        name: "Ada!",
+      })
+    )
+    await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull())
+    expect(screen.queryByRole("alertdialog")).toBeNull()
+  })
+
+  test("stays open when validation fails or the submit throws", async () => {
+    const user = userEvent.setup()
+    const onSubmit = vi.fn(() => {
+      throw new Error("nope")
+    })
+    render(<Harness onSubmit={onSubmit} />)
+    await user.click(screen.getByRole("button", { name: "New" }))
+    await screen.findByLabelText(NAME)
+    await user.click(screen.getByRole("button", { name: "Save" }))
+    expect(onSubmit).not.toHaveBeenCalled()
+    expect(await screen.findByText("Required")).toBeTruthy()
+
+    await user.type(screen.getByLabelText(NAME), "Bob")
+    await user.click(screen.getByRole("button", { name: "Save" }))
+    await waitFor(() => expect(onSubmit).toHaveBeenCalled())
+    expect(screen.getByRole("dialog")).toBeTruthy()
+  })
+})

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/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

@@ -2,8 +2,21 @@
 
 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,