@zeno-lib/forms 0.0.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@zeno-lib/forms",
+  "version": "0.0.0",
+  "exports": {
+    ".": "./src/form.tsx",
+    "./addons": "./src/addons/index.ts",
+    "./fields": "./src/fields/index.ts",
+    "./tanstack": "./src/tanstack.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "url": "https://github.com/zeno-lib/zeno.git",
+    "directory": "packages/forms"
+  },
+  "peerDependencies": {
+    "@tanstack/react-devtools": ">=0.10",
+    "@tanstack/react-form-devtools": ">=0.2",
+    "next": ">=16",
+    "react": ">=19",
+    "react-dom": ">=19",
+    "zod": ">=4",
+    "@zeno-lib/ui": "^0.0.0"
+  },
+  "dependencies": {
+    "@tanstack/react-form": "1.29.1",
+    "@tanstack/react-form-nextjs": "1.29.1"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.0",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "typescript": "6.0.3",
+    "zod": "^4.3.6",
+    "@zeno-lib/typescript": "^1.0.0",
+    "@zeno-lib/vitest": "^0.0.0"
+  },
+  "scripts": {
+    "test": "vitest --run",
+    "test:watch": "vitest watch",
+    "types:check": "tsc --noEmit"
+  }
+}

package/src/addons/index.ts

@@ -0,0 +1,2 @@
+/** biome-ignore-all lint/performance/noBarrelFile: single import surface for all addon helpers */
+export * from "./validation-spinner"

package/src/addons/validation-spinner.tsx

@@ -0,0 +1,25 @@
+"use client"
+
+import { InputGroupAddon } from "@zeno-lib/ui/input-group"
+import { Spinner } from "@zeno-lib/ui/spinner"
+
+import { useFieldContext } from "../lib/contexts"
+
+type ValidationSpinnerProps = {
+  align?: "inline-start" | "inline-end"
+}
+
+function ValidationSpinner({ align = "inline-end" }: ValidationSpinnerProps) {
+  const field = useFieldContext()
+  if (!field.state.meta.isValidating) {
+    return null
+  }
+  return (
+    <InputGroupAddon align={align}>
+      <Spinner />
+    </InputGroupAddon>
+  )
+}
+
+export type { ValidationSpinnerProps }
+export { ValidationSpinner }

package/src/fields/checkbox-field.tsx

@@ -0,0 +1,80 @@
+"use client"
+
+import { Checkbox } from "@zeno-lib/ui/checkbox"
+import {
+  Field,
+  FieldContent,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@zeno-lib/ui/field"
+import type { ComponentProps, ReactNode } from "react"
+
+import { describedBy } from "../lib/aria"
+import { useFieldContext } from "../lib/contexts"
+import { RequiredIndicator } from "../lib/required-indicator"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "../lib/use-is-invalid"
+
+type CheckboxFieldProps = Omit<
+  ComponentProps<typeof Checkbox>,
+  "checked" | "id" | "name" | "onBlur" | "onCheckedChange"
+> & {
+  description?: ReactNode
+  label?: ReactNode
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+}
+
+function CheckboxField({
+  description,
+  label,
+  required,
+  ...props
+}: CheckboxFieldProps) {
+  const field = useFieldContext<boolean>()
+  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
+
+  return (
+    <Field data-invalid={isInvalid} orientation="horizontal">
+      <Checkbox
+        aria-describedby={describedBy(
+          [description, descriptionId],
+          [showError, errorId]
+        )}
+        aria-invalid={isInvalid || undefined}
+        checked={field.state.value ?? false}
+        id={field.name}
+        name={field.name}
+        onBlur={field.handleBlur}
+        onCheckedChange={(value) => field.handleChange(value === true)}
+        {...props}
+      />
+      <FieldContent>
+        {label && (
+          <FieldLabel className="font-normal" htmlFor={field.name}>
+            {label}
+            {isRequired && <RequiredIndicator />}
+          </FieldLabel>
+        )}
+        {description && (
+          <FieldDescription id={descriptionId}>{description}</FieldDescription>
+        )}
+        {showError && (
+          <FieldError errors={field.state.meta.errors} id={errorId} />
+        )}
+      </FieldContent>
+    </Field>
+  )
+}
+
+export { CheckboxField }

package/src/fields/combobox-field.tsx

@@ -0,0 +1,189 @@
+"use client"
+
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxList,
+} from "@zeno-lib/ui/combobox"
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@zeno-lib/ui/field"
+import { InputGroupAddon } from "@zeno-lib/ui/input-group"
+import { Spinner } from "@zeno-lib/ui/spinner"
+import type { ReactNode } from "react"
+
+import { describedBy } from "../lib/aria"
+import { useFieldContext } from "../lib/contexts"
+import { RequiredIndicator } from "../lib/required-indicator"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "../lib/use-is-invalid"
+
+type ComboboxItemObject<V> = { value: V; label: string }
+
+type ComboboxFieldProps<T = string> = {
+  /**
+   * Items shown in the dropdown. Pass plain strings (value === label) or
+   * `{ value, label }` objects when the value isn't a string (e.g. numeric
+   * database IDs).
+   */
+  items: readonly T[]
+  description?: ReactNode
+  label?: ReactNode
+  placeholder?: string
+  /** Message shown when filtering produces zero matches. */
+  emptyMessage?: ReactNode
+  /** Override per-row rendering. Default: plain `<ComboboxItem>{label}</ComboboxItem>`. */
+  renderItem?: (item: T) => ReactNode
+  /**
+   * If `true`, show the clear button when a value is selected. Defaults to
+   * `true` — pass `false` for required-style comboboxes where clearing is
+   * disallowed.
+   */
+  showClear?: boolean
+  className?: string
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+  /**
+   * Controlled input text — pair with `onInputValueChange` for server-side
+   * search. When omitted, Base UI manages the input value internally.
+   */
+  inputValue?: string
+  /** Fires on every keystroke in the search input. */
+  onInputValueChange?: (value: string) => void
+  /**
+   * Replace Base UI's built-in client-side filter. Pass `null` for
+   * server-driven search where `items` is already filtered by the consumer.
+   */
+  filter?: ((item: T, query: string) => boolean) | null
+  /**
+   * Show a spinner addon inside the input while options are being fetched.
+   * Pair with `onInputValueChange` to drive a debounced server query.
+   */
+  loading?: boolean
+}
+
+function isItemObject(item: unknown): item is ComboboxItemObject<unknown> {
+  return (
+    typeof item === "object" &&
+    item !== null &&
+    "value" in item &&
+    "label" in item
+  )
+}
+
+function ComboboxField<T = string>({
+  className,
+  description,
+  emptyMessage = "No results.",
+  filter,
+  inputValue,
+  items,
+  label,
+  loading,
+  onInputValueChange,
+  placeholder,
+  renderItem,
+  required,
+  showClear = true,
+}: ComboboxFieldProps<T>) {
+  const field = useFieldContext()
+  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 fieldValue = field.state.value
+  const hasObjectItems = items.some(isItemObject)
+  const value = hasObjectItems
+    ? ((items.find((item) => isItemObject(item) && item.value === fieldValue) ??
+        null) as T | null)
+    : ((fieldValue ?? null) as T | null)
+
+  return (
+    <Field data-invalid={isInvalid}>
+      {label && (
+        <FieldLabel htmlFor={field.name}>
+          {label}
+          {isRequired && <RequiredIndicator />}
+        </FieldLabel>
+      )}
+      <Combobox
+        filter={filter}
+        inputValue={inputValue}
+        items={items}
+        onInputValueChange={onInputValueChange}
+        onValueChange={(next) => {
+          if (next == null) {
+            field.handleChange(undefined)
+            return
+          }
+          field.handleChange(isItemObject(next) ? next.value : next)
+        }}
+        value={value}
+      >
+        <ComboboxInput
+          aria-describedby={describedBy(
+            [description, descriptionId],
+            [showError, errorId]
+          )}
+          aria-invalid={isInvalid || undefined}
+          className={className}
+          id={field.name}
+          name={field.name}
+          onBlur={field.handleBlur}
+          placeholder={placeholder}
+          showClear={showClear && value != null && value !== "" && !loading}
+        >
+          {loading && (
+            <InputGroupAddon align="inline-end">
+              <Spinner />
+            </InputGroupAddon>
+          )}
+        </ComboboxInput>
+        <ComboboxContent>
+          <ComboboxEmpty>{emptyMessage}</ComboboxEmpty>
+          <ComboboxList>
+            {(item: T) => {
+              if (renderItem) {
+                return renderItem(item)
+              }
+              if (isItemObject(item)) {
+                return (
+                  <ComboboxItem key={String(item.value)} value={item}>
+                    {item.label}
+                  </ComboboxItem>
+                )
+              }
+              return (
+                <ComboboxItem key={String(item)} value={item}>
+                  {String(item)}
+                </ComboboxItem>
+              )
+            }}
+          </ComboboxList>
+        </ComboboxContent>
+      </Combobox>
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {showError && (
+        <FieldError errors={field.state.meta.errors} id={errorId} />
+      )}
+    </Field>
+  )
+}
+
+export type { ComboboxFieldProps, ComboboxItemObject }
+export { ComboboxField }

package/src/fields/date-picker-field.tsx

@@ -0,0 +1,141 @@
+"use client"
+
+import { buttonVariants } from "@zeno-lib/ui/button"
+import { Calendar } from "@zeno-lib/ui/calendar"
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@zeno-lib/ui/field"
+import { cn } from "@zeno-lib/ui/lib/utils"
+import { Popover, PopoverContent, PopoverTrigger } from "@zeno-lib/ui/popover"
+import type { ComponentProps, ReactNode } from "react"
+
+import { describedBy } from "../lib/aria"
+import { useFieldContext } from "../lib/contexts"
+import { RequiredIndicator } from "../lib/required-indicator"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "../lib/use-is-invalid"
+
+type CalendarProps = ComponentProps<typeof Calendar>
+
+type DatePickerFieldProps = {
+  description?: ReactNode
+  label?: ReactNode
+  /** Trigger placeholder when the value is empty. */
+  placeholder?: ReactNode
+  /** Override the default `toLocaleDateString()` formatter. */
+  formatValue?: (date: Date) => string
+  triggerClassName?: string
+  /** Pass-through to the underlying `<Calendar>` (e.g. `disabled`, `locale`). */
+  calendarProps?: Omit<CalendarProps, "mode" | "onSelect" | "selected">
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+}
+
+const FALLBACK_PLACEHOLDER = "Pick a date"
+
+function defaultFormat(date: Date): string {
+  return date.toLocaleDateString(undefined, {
+    day: "numeric",
+    month: "long",
+    year: "numeric",
+  })
+}
+
+function DatePickerField({
+  calendarProps,
+  description,
+  formatValue = defaultFormat,
+  label,
+  placeholder = FALLBACK_PLACEHOLDER,
+  required,
+  triggerClassName,
+}: DatePickerFieldProps) {
+  const field = useFieldContext<Date | undefined>()
+  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 value = field.state.value
+  const empty = !value
+
+  return (
+    <Field data-invalid={isInvalid}>
+      {label && (
+        <FieldLabel htmlFor={field.name}>
+          {label}
+          {isRequired && <RequiredIndicator />}
+        </FieldLabel>
+      )}
+      <Popover>
+        <PopoverTrigger
+          aria-describedby={describedBy(
+            [description, descriptionId],
+            [showError, errorId]
+          )}
+          aria-invalid={isInvalid || undefined}
+          className={cn(
+            buttonVariants({ variant: "outline" }),
+            "w-full justify-start text-left font-normal data-[empty=true]:text-muted-foreground",
+            triggerClassName
+          )}
+          data-empty={empty || undefined}
+          id={field.name}
+          // Base UI's Popover handles open state — we still need blur on the
+          // form's reactive store. Passing onBlur here mirrors how `<select>`
+          // commits on close.
+          onBlur={field.handleBlur}
+        >
+          <CalendarIcon />
+          {empty ? <span>{placeholder}</span> : formatValue(value)}
+        </PopoverTrigger>
+        <PopoverContent className="w-auto p-0">
+          <Calendar
+            mode="single"
+            onSelect={(next) => field.handleChange(next)}
+            selected={value}
+            {...calendarProps}
+          />
+        </PopoverContent>
+      </Popover>
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {showError && (
+        <FieldError errors={field.state.meta.errors} id={errorId} />
+      )}
+    </Field>
+  )
+}
+
+function CalendarIcon() {
+  return (
+    <svg
+      aria-hidden
+      className="size-4 shrink-0 opacity-60"
+      fill="none"
+      role="img"
+      stroke="currentColor"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      strokeWidth="2"
+      viewBox="0 0 24 24"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <title>Calendar</title>
+      <path d="M8 2v3M16 2v3M3 10h18M5 4h14a2 2 0 012 2v14a2 2 0 01-2 2H5a2 2 0 01-2-2V6a2 2 0 012-2z" />
+    </svg>
+  )
+}
+
+export type { DatePickerFieldProps }
+export { DatePickerField }

package/src/fields/email-field.tsx

@@ -0,0 +1,21 @@
+import { InputField, type InputFieldProps } from "./input-field"
+
+type EmailFieldProps = Omit<InputFieldProps, "inputMode" | "type">
+
+function EmailField({
+  autoComplete = "email",
+  label = "Email",
+  ...props
+}: EmailFieldProps) {
+  return (
+    <InputField
+      autoComplete={autoComplete}
+      inputMode="email"
+      label={label}
+      type="email"
+      {...props}
+    />
+  )
+}
+
+export { EmailField }

package/src/fields/index.ts

@@ -0,0 +1,16 @@
+/** biome-ignore-all lint/performance/noBarrelFile: single import surface for all field components */
+export * from "./checkbox-field"
+export * from "./combobox-field"
+export * from "./date-picker-field"
+export * from "./email-field"
+export * from "./input-field"
+export * from "./number-field"
+export * from "./otp-field"
+export * from "./password-field"
+export * from "./radio-group-field"
+export * from "./reset-button"
+export * from "./select-field"
+export * from "./slider-field"
+export * from "./submit-button"
+export * from "./switch-field"
+export * from "./textarea-field"

package/src/fields/input-field.tsx

@@ -0,0 +1,95 @@
+"use client"
+
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@zeno-lib/ui/field"
+import { Input } from "@zeno-lib/ui/input"
+import { InputGroup, InputGroupInput } from "@zeno-lib/ui/input-group"
+import { Children, type ComponentProps, type ReactNode } from "react"
+
+import { describedBy } from "../lib/aria"
+import { useFieldContext } from "../lib/contexts"
+import { RequiredIndicator } from "../lib/required-indicator"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "../lib/use-is-invalid"
+
+type InputFieldProps = Omit<
+  ComponentProps<typeof Input>,
+  "children" | "id" | "name" | "onBlur"
+> & {
+  children?: ReactNode
+  description?: ReactNode
+  label?: ReactNode
+  /**
+   * Force the required `*` indicator on or off for this field. When omitted,
+   * the value is derived from the form's schema.
+   */
+  required?: boolean
+}
+
+function InputField({
+  children,
+  description,
+  label,
+  required,
+  ...props
+}: InputFieldProps) {
+  const field = useFieldContext<string>()
+  const errorId = `${field.name}-error`
+  const descriptionId = `${field.name}-description`
+  const isInvalid = useIsInvalid(field)
+  const hideErrors = useHideFieldErrors(field)
+  const showError = isInvalid && !hideErrors
+  const hasAddons = Children.count(children) > 0
+  const schemaRequired = useIsFieldRequired(field)
+  const isRequired = required ?? schemaRequired
+
+  const inputProps = {
+    "aria-describedby": describedBy(
+      [description, descriptionId],
+      [showError, errorId]
+    ),
+    "aria-invalid": isInvalid || undefined,
+    id: field.name,
+    name: field.name,
+    onBlur: field.handleBlur,
+    onChange: (event: React.ChangeEvent<HTMLInputElement>) =>
+      field.handleChange(event.target.value),
+    value: field.state.value ?? "",
+    ...props,
+  }
+
+  return (
+    <Field data-invalid={isInvalid}>
+      {label && (
+        <FieldLabel htmlFor={field.name}>
+          {label}
+          {isRequired && <RequiredIndicator />}
+        </FieldLabel>
+      )}
+      {hasAddons ? (
+        <InputGroup>
+          <InputGroupInput {...inputProps} />
+          {children}
+        </InputGroup>
+      ) : (
+        <Input {...inputProps} />
+      )}
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {showError && (
+        <FieldError errors={field.state.meta.errors} id={errorId} />
+      )}
+    </Field>
+  )
+}
+
+export type { InputFieldProps }
+export { InputField }

package/src/fields/number-field.tsx

@@ -0,0 +1,33 @@
+"use client"
+
+import type { ChangeEvent } from "react"
+
+import { useFieldContext } from "../lib/contexts"
+import { InputField, type InputFieldProps } from "./input-field"
+
+type NumberFieldProps = Omit<
+  InputFieldProps,
+  "inputMode" | "onChange" | "type" | "value"
+>
+
+function NumberField(props: NumberFieldProps) {
+  const field = useFieldContext<number | undefined>()
+  const value = field.state.value
+  const inputValue =
+    typeof value === "number" && !Number.isNaN(value) ? value : ""
+
+  return (
+    <InputField
+      {...props}
+      inputMode="numeric"
+      onChange={(event: ChangeEvent<HTMLInputElement>) => {
+        const next = event.target.valueAsNumber
+        field.handleChange(Number.isNaN(next) ? undefined : next)
+      }}
+      type="number"
+      value={inputValue}
+    />
+  )
+}
+
+export { NumberField }