@zeno-lib/forms 0.0.1 → 0.2.0

package/src/fields/number-field.tsx

@@ -1,8 +1,7 @@
 "use client"
 
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
 import type { ChangeEvent } from "react"
-
-import { useFieldContext } from "../lib/contexts"
 import { InputField, type InputFieldProps } from "./input-field"
 
 type NumberFieldProps = Omit<

package/src/fields/otp-field.tsx

@@ -1,22 +1,25 @@
 "use client"
 
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import type { ReactNode } from "react"
 import {
   Field,
   FieldDescription,
   FieldError,
   FieldLabel,
-} from "@zeno-lib/ui/field"
-import { InputOTP, InputOTPGroup, InputOTPSlot } from "@zeno-lib/ui/input-otp"
-import type { ReactNode } from "react"
-
-import { describedBy } from "../lib/aria"
-import { useFieldContext } from "../lib/contexts"
-import { RequiredIndicator } from "../lib/required-indicator"
+} from "@/components/ui/field"
 import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsInvalid,
-} from "../lib/use-is-invalid"
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSlot,
+} from "@/components/ui/input-otp"
+import { RequiredIndicator } from "../lib/required-indicator"
 
 // Flat surface — `OTPInput`'s prop type is a discriminated union over
 // `render`/`children`, which doesn't compose cleanly with `Omit`. Listing the
@@ -63,7 +66,7 @@ function OtpField({
   const isRequired = required ?? schemaRequired
 
   return (
-    <Field data-invalid={isInvalid}>
+    <Field data-field={field.name} data-invalid={isInvalid}>
       {label && (
         <FieldLabel htmlFor={field.name}>
           {label}

package/src/fields/percentage-field.tsx

@@ -0,0 +1,73 @@
+"use client"
+
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { useFormattedNumber } from "@zeno-lib/forms/lib/use-formatted-number"
+import { InputGroupAddon, InputGroupText } from "@/components/ui/input-group"
+import { InputField, type InputFieldProps } from "./input-field"
+
+type PercentageFieldProps = Omit<
+  InputFieldProps,
+  "defaultValue" | "inputMode" | "onChange" | "onPaste" | "type" | "value"
+> & {
+  /**
+   * How the form value relates to what the user types:
+   * - `"percent"` (default): the value is the number shown, `12.5` ↔ `12.5 %`.
+   * - `"fraction"`: the value is a ratio, `0.125` ↔ `12.5 %`.
+   */
+  scale?: "fraction" | "percent"
+  /** BCP 47 locale driving the decimal separator. Defaults to the runtime locale. */
+  locale?: string
+  /** Digits allowed after the decimal separator (of the shown percentage). Defaults to `2`. */
+  fractionDigits?: number
+  /** Accept negative percentages. Defaults to `false`. */
+  allowNegative?: boolean
+  /** Clamp on blur, in the form value's scale. */
+  min?: number
+  /** Clamp on blur, in the form value's scale. */
+  max?: number
+}
+
+const toPercent = (value: number) => value * 100
+const fromPercent = (value: number) => value / 100
+
+/**
+ * Percentage input with a `%` add-on. The form value is `number | null`, on
+ * the `scale` you pick (`0–100` by default, `0–1` with `scale="fraction"`).
+ */
+function PercentageField({
+  allowNegative = false,
+  children,
+  fractionDigits = 2,
+  locale,
+  max,
+  min,
+  scale = "percent",
+  ...props
+}: PercentageFieldProps) {
+  const field = useFieldContext<number | null | undefined>()
+  const isFraction = scale === "fraction"
+
+  const inputProps = useFormattedNumber({
+    allowNegative,
+    locale,
+    max,
+    maximumFractionDigits: fractionDigits,
+    min,
+    onBlur: field.handleBlur,
+    onValueChange: (next) => field.handleChange(next),
+    value: field.state.value,
+    ...(isFraction ? { fromDisplay: fromPercent, toDisplay: toPercent } : {}),
+  })
+
+  return (
+    <InputField {...props} {...inputProps}>
+      <InputGroupAddon align="inline-end">
+        <InputGroupText>%</InputGroupText>
+      </InputGroupAddon>
+      {children}
+    </InputField>
+  )
+}
+
+export type { PercentageFieldProps }
+export { PercentageField }

package/src/fields/radio-group-field.tsx

@@ -1,23 +1,22 @@
 "use client"
 
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import { type ComponentProps, type ReactNode, useId } from "react"
 import {
   Field,
   FieldDescription,
   FieldError,
   FieldLabel,
-} from "@zeno-lib/ui/field"
-import { cn } from "@zeno-lib/ui/lib/utils"
-import { RadioGroup, RadioGroupItem } from "@zeno-lib/ui/radio-group"
-import { type ComponentProps, type ReactNode, useId } from "react"
-
-import { describedBy } from "../lib/aria"
-import { useFieldContext } from "../lib/contexts"
+} from "@/components/ui/field"
+import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
+import { cn } from "@/lib/utils"
 import { RequiredIndicator } from "../lib/required-indicator"
-import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsInvalid,
-} from "../lib/use-is-invalid"
 
 type RadioGroupFieldProps = Omit<
   ComponentProps<typeof RadioGroup>,
@@ -46,7 +45,7 @@ function RadioGroupField({
   const isRequired = required ?? schemaRequired
 
   return (
-    <Field data-invalid={isInvalid}>
+    <Field data-field={field.name} data-invalid={isInvalid}>
       {label && (
         <FieldLabel>
           {label}

package/src/fields/reset-button.tsx

@@ -1,9 +1,8 @@
 "use client"
 
-import { Button } from "@zeno-lib/ui/button"
+import { useFormContext } from "@zeno-lib/forms/lib/contexts"
 import type { ComponentProps, ReactNode } from "react"
-
-import { useFormContext } from "../lib/contexts"
+import { Button } from "@/components/ui/button"
 
 type ResetButtonProps = Omit<ComponentProps<typeof Button>, "onClick" | "type">
 

package/src/fields/select-field.tsx

@@ -1,28 +1,27 @@
 "use client"
 
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import type { ComponentProps, ReactNode } from "react"
+import { Children, isValidElement, useMemo } from "react"
 import {
   Field,
   FieldDescription,
   FieldError,
   FieldLabel,
-} from "@zeno-lib/ui/field"
+} from "@/components/ui/field"
 import {
   Select,
   SelectContent,
   SelectTrigger,
   SelectValue,
-} from "@zeno-lib/ui/select"
-import type { ComponentProps, ReactNode } from "react"
-import { Children, isValidElement, useMemo } from "react"
-
-import { describedBy } from "../lib/aria"
-import { useFieldContext } from "../lib/contexts"
+} from "@/components/ui/select"
 import { RequiredIndicator } from "../lib/required-indicator"
-import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsInvalid,
-} from "../lib/use-is-invalid"
 
 type SelectFieldProps = Omit<
   ComponentProps<typeof Select>,
@@ -71,7 +70,7 @@ function SelectField({
   }, [children])
 
   return (
-    <Field data-invalid={isInvalid}>
+    <Field data-field={field.name} data-invalid={isInvalid}>
       {label && (
         <FieldLabel htmlFor={field.name}>
           {label}

package/src/fields/slider-field.tsx

@@ -1,23 +1,22 @@
 "use client"
 
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import type { ComponentProps, ReactNode } from "react"
 import {
   Field,
   FieldContent,
   FieldDescription,
   FieldError,
   FieldLabel,
-} from "@zeno-lib/ui/field"
-import { Slider } from "@zeno-lib/ui/slider"
-import type { ComponentProps, ReactNode } from "react"
-
-import { describedBy } from "../lib/aria"
-import { useFieldContext } from "../lib/contexts"
+} from "@/components/ui/field"
+import { Slider } from "@/components/ui/slider"
 import { RequiredIndicator } from "../lib/required-indicator"
-import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsInvalid,
-} from "../lib/use-is-invalid"
 
 type SliderValue = number | number[]
 
@@ -56,7 +55,7 @@ function SliderField({
   const readout = formatValue && value !== undefined ? formatValue(value) : null
 
   return (
-    <Field data-invalid={isInvalid}>
+    <Field data-field={field.name} data-invalid={isInvalid}>
       {(label || readout) && (
         <FieldContent className="flex-row items-center justify-between">
           {label && (

package/src/fields/submit-button.tsx

@@ -1,10 +1,9 @@
 "use client"
 
-import { Button } from "@zeno-lib/ui/button"
-import { Spinner } from "@zeno-lib/ui/spinner"
+import { useFormContext } from "@zeno-lib/forms/lib/contexts"
 import type { ComponentProps } from "react"
-
-import { useFormContext } from "../lib/contexts"
+import { Button } from "@/components/ui/button"
+import { Spinner } from "@/components/ui/spinner"
 
 type SubmitButtonProps = Omit<ComponentProps<typeof Button>, "type">
 

package/src/fields/switch-field.tsx

@@ -1,23 +1,22 @@
 "use client"
 
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import type { ComponentProps, ReactNode } from "react"
 import {
   Field,
   FieldContent,
   FieldDescription,
   FieldError,
   FieldLabel,
-} from "@zeno-lib/ui/field"
-import { Switch } from "@zeno-lib/ui/switch"
-import type { ComponentProps, ReactNode } from "react"
-
-import { describedBy } from "../lib/aria"
-import { useFieldContext } from "../lib/contexts"
+} from "@/components/ui/field"
+import { Switch } from "@/components/ui/switch"
 import { RequiredIndicator } from "../lib/required-indicator"
-import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsInvalid,
-} from "../lib/use-is-invalid"
 
 type SwitchFieldProps = Omit<
   ComponentProps<typeof Switch>,
@@ -45,7 +44,11 @@ function SwitchField({
   const isRequired = required ?? schemaRequired
 
   return (
-    <Field data-invalid={isInvalid} orientation="horizontal">
+    <Field
+      data-field={field.name}
+      data-invalid={isInvalid}
+      orientation="horizontal"
+    >
       <FieldContent>
         {label && (
           <FieldLabel htmlFor={field.name}>

package/src/fields/textarea-field.tsx

@@ -1,23 +1,22 @@
 "use client"
 
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import { Children, type ComponentProps, type ReactNode } from "react"
 import {
   Field,
   FieldDescription,
   FieldError,
   FieldLabel,
-} from "@zeno-lib/ui/field"
-import { InputGroup, InputGroupTextarea } from "@zeno-lib/ui/input-group"
-import { Textarea } from "@zeno-lib/ui/textarea"
-import { Children, type ComponentProps, type ReactNode } from "react"
-
-import { describedBy } from "../lib/aria"
-import { useFieldContext } from "../lib/contexts"
+} from "@/components/ui/field"
+import { InputGroup, InputGroupTextarea } from "@/components/ui/input-group"
+import { Textarea } from "@/components/ui/textarea"
 import { RequiredIndicator } from "../lib/required-indicator"
-import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsInvalid,
-} from "../lib/use-is-invalid"
 
 type TextAreaFieldProps = Omit<
   ComponentProps<typeof Textarea>,
@@ -63,7 +62,7 @@ function TextAreaField({
   }
 
   return (
-    <Field data-invalid={isInvalid}>
+    <Field data-field={field.name} data-invalid={isInvalid}>
       {label && (
         <FieldLabel htmlFor={field.name}>
           {label}

package/src/fields/year-field.tsx

@@ -0,0 +1,56 @@
+"use client"
+
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { useFormattedNumber } from "@zeno-lib/forms/lib/use-formatted-number"
+import { InputField, type InputFieldProps } from "./input-field"
+
+type YearFieldProps = Omit<
+  InputFieldProps,
+  | "defaultValue"
+  | "inputMode"
+  | "max"
+  | "maxLength"
+  | "min"
+  | "onChange"
+  | "onPaste"
+  | "type"
+  | "value"
+> & {
+  /** Earliest accepted year. The value is clamped to it on blur. */
+  min?: number
+  /** Latest accepted year. The value is clamped to it on blur. */
+  max?: number
+}
+
+/**
+ * Four-digit year input. The form value is an integer year or `null`. No
+ * thousands separator, digits only, clamped to `min`/`max` on blur.
+ */
+function YearField({ max, min, ...props }: YearFieldProps) {
+  const field = useFieldContext<number | null | undefined>()
+
+  const inputProps = useFormattedNumber({
+    allowNegative: false,
+    max,
+    maxIntegerDigits: 4,
+    maximumFractionDigits: 0,
+    min,
+    onBlur: field.handleBlur,
+    onValueChange: (next) => field.handleChange(next),
+    useGrouping: false,
+    value: field.state.value,
+  })
+
+  return (
+    <InputField
+      autoComplete="off"
+      maxLength={4}
+      placeholder="YYYY"
+      {...props}
+      {...inputProps}
+    />
+  )
+}
+
+export type { YearFieldProps }
+export { YearField }

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()
+  })
+})