@zeno-lib/forms 0.1.0 → 0.2.1

package/src/fields/multi-select-field.tsx

@@ -0,0 +1,193 @@
+"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 { XIcon } from "lucide-react"
+import type { ReactNode } from "react"
+import { Button } from "@/components/ui/button"
+import {
+  Combobox,
+  ComboboxChip,
+  ComboboxChips,
+  ComboboxChipsInput,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxValue,
+  useComboboxAnchor,
+} from "@/components/ui/combobox"
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@/components/ui/field"
+import { RequiredIndicator } from "../lib/required-indicator"
+
+type MultiSelectItemObject<V> = { value: V; label: string }
+
+/** The value stored per selected item: `item.value` for objects, else the item. */
+type MultiSelectValue<T> = T extends MultiSelectItemObject<infer V> ? V : T
+
+type MultiSelectFieldProps<T = string> = {
+  /**
+   * Options shown in the dropdown. Pass plain strings or numbers (value ===
+   * label), or `{ value, label }` objects. The form value is an array of the
+   * selected values (`item.value` for objects).
+   */
+  items: readonly T[]
+  description?: ReactNode
+  label?: ReactNode
+  /** Shown in the search input while nothing is selected. */
+  placeholder?: string
+  /** Message shown when filtering produces zero matches. */
+  emptyMessage?: ReactNode
+  /** Override per-row rendering. Default: the item's label. */
+  renderItem?: (item: T) => ReactNode
+  /** Show a button that clears every selection. Defaults to `true`. */
+  showClear?: boolean
+  /** Accessible label of the clear button. Defaults to `"Clear"`. */
+  clearLabel?: string
+  disabled?: boolean
+  className?: string
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+}
+
+function isItemObject(item: unknown): item is MultiSelectItemObject<unknown> {
+  return (
+    typeof item === "object" &&
+    item !== null &&
+    "value" in item &&
+    "label" in item
+  )
+}
+
+function itemValue(item: unknown): unknown {
+  return isItemObject(item) ? item.value : item
+}
+
+function itemLabel(item: unknown): string {
+  return isItemObject(item) ? item.label : String(item)
+}
+
+/**
+ * Multi-value combobox: the selection renders as removable chips and the form
+ * value is an array (`[]` when empty).
+ */
+function MultiSelectField<T = string>({
+  className,
+  clearLabel = "Clear",
+  description,
+  disabled,
+  emptyMessage = "No results.",
+  items,
+  label,
+  placeholder,
+  renderItem,
+  required,
+  showClear = true,
+}: MultiSelectFieldProps<T>) {
+  const field = useFieldContext<MultiSelectValue<T>[] | null | undefined>()
+  const anchor = useComboboxAnchor()
+  const errorId = `${field.name}-error`
+  const descriptionId = `${field.name}-description`
+  const isInvalid = useIsInvalid(field)
+  const hideErrors = useHideFieldErrors(field)
+  const showError = isInvalid && !hideErrors
+  const schemaRequired = useIsFieldRequired(field)
+  const isRequired = required ?? schemaRequired
+
+  const values = field.state.value ?? []
+  // Map stored values back to item identities, in selection order, so Base UI
+  // compares by reference and the chips keep the order the user picked.
+  const selected = values
+    .map((value) => items.find((item) => Object.is(itemValue(item), value)))
+    .filter((item): item is T => item !== undefined)
+
+  return (
+    <Field data-field={field.name} data-invalid={isInvalid}>
+      {label && (
+        <FieldLabel htmlFor={field.name}>
+          {label}
+          {isRequired && <RequiredIndicator />}
+        </FieldLabel>
+      )}
+      <Combobox
+        disabled={disabled}
+        items={items}
+        multiple
+        onValueChange={(next: T[]) =>
+          field.handleChange(next.map(itemValue) as MultiSelectValue<T>[])
+        }
+        value={selected}
+      >
+        <ComboboxChips className={className} ref={anchor}>
+          <ComboboxValue>
+            {(chips: T[]) => (
+              <>
+                {chips.map((item) => (
+                  <ComboboxChip key={String(itemValue(item))}>
+                    {itemLabel(item)}
+                  </ComboboxChip>
+                ))}
+                <ComboboxChipsInput
+                  aria-describedby={describedBy(
+                    [description, descriptionId],
+                    [showError, errorId]
+                  )}
+                  aria-invalid={isInvalid || undefined}
+                  id={field.name}
+                  name={field.name}
+                  onBlur={field.handleBlur}
+                  placeholder={chips.length === 0 ? placeholder : undefined}
+                />
+              </>
+            )}
+          </ComboboxValue>
+          {showClear && selected.length > 0 && !disabled && (
+            <Button
+              aria-label={clearLabel}
+              className="ml-auto"
+              onClick={() => field.handleChange([])}
+              size="icon-xs"
+              type="button"
+              variant="ghost"
+            >
+              <XIcon />
+            </Button>
+          )}
+        </ComboboxChips>
+        <ComboboxContent anchor={anchor}>
+          <ComboboxEmpty>{emptyMessage}</ComboboxEmpty>
+          <ComboboxList>
+            {(item: T) =>
+              renderItem ? (
+                renderItem(item)
+              ) : (
+                <ComboboxItem key={String(itemValue(item))} value={item}>
+                  {itemLabel(item)}
+                </ComboboxItem>
+              )
+            }
+          </ComboboxList>
+        </ComboboxContent>
+      </Combobox>
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {showError && (
+        <FieldError errors={field.state.meta.errors} id={errorId} />
+      )}
+    </Field>
+  )
+}
+
+export type { MultiSelectFieldProps, MultiSelectItemObject, MultiSelectValue }
+export { MultiSelectField }

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