@zeno-lib/forms 0.0.0

package/src/fields/otp-field.tsx

@@ -0,0 +1,111 @@
+"use client"
+
+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"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "../lib/use-is-invalid"
+
+// Flat surface — `OTPInput`'s prop type is a discriminated union over
+// `render`/`children`, which doesn't compose cleanly with `Omit`. Listing the
+// knobs we forward keeps the field's typing flat and predictable.
+type OtpFieldProps = {
+  description?: ReactNode
+  label?: ReactNode
+  /** Number of digits/characters in the code. Defaults to 6. */
+  maxLength?: number
+  /** Regex applied to each keystroke (e.g. `^[0-9]+$` for digits-only). */
+  pattern?: string
+  autoFocus?: boolean
+  disabled?: boolean
+  className?: string
+  containerClassName?: string
+  /**
+   * Custom slot rendering. Overrides the default single-group layout when
+   * you need a separator between segments.
+   */
+  children?: ReactNode
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+}
+
+function OtpField({
+  autoFocus,
+  children,
+  className,
+  containerClassName,
+  description,
+  disabled,
+  label,
+  maxLength = 6,
+  pattern,
+  required,
+}: OtpFieldProps) {
+  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 schemaRequired = useIsFieldRequired(field)
+  const isRequired = required ?? schemaRequired
+
+  return (
+    <Field data-invalid={isInvalid}>
+      {label && (
+        <FieldLabel htmlFor={field.name}>
+          {label}
+          {isRequired && <RequiredIndicator />}
+        </FieldLabel>
+      )}
+      <InputOTP
+        aria-describedby={describedBy(
+          [description, descriptionId],
+          [showError, errorId]
+        )}
+        aria-invalid={isInvalid || undefined}
+        autoFocus={autoFocus}
+        className={className}
+        containerClassName={containerClassName}
+        disabled={disabled}
+        id={field.name}
+        maxLength={maxLength}
+        name={field.name}
+        onBlur={field.handleBlur}
+        onChange={(value) => field.handleChange(value)}
+        pattern={pattern}
+        value={field.state.value ?? ""}
+      >
+        {children ?? (
+          <InputOTPGroup>
+            {Array.from({ length: maxLength }, (_, index) => (
+              // biome-ignore lint/suspicious/noArrayIndexKey: OTP slots are a fixed-length ordered list — index *is* the stable identity.
+              <InputOTPSlot index={index} key={index} />
+            ))}
+          </InputOTPGroup>
+        )}
+      </InputOTP>
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {showError && (
+        <FieldError errors={field.state.meta.errors} id={errorId} />
+      )}
+    </Field>
+  )
+}
+
+export type { OtpFieldProps }
+export { OtpField }

package/src/fields/password-field.tsx

@@ -0,0 +1,20 @@
+import { InputField, type InputFieldProps } from "./input-field"
+
+type PasswordFieldProps = Omit<InputFieldProps, "type">
+
+function PasswordField({
+  autoComplete = "current-password",
+  label = "Password",
+  ...props
+}: PasswordFieldProps) {
+  return (
+    <InputField
+      autoComplete={autoComplete}
+      label={label}
+      type="password"
+      {...props}
+    />
+  )
+}
+
+export { PasswordField }

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

@@ -0,0 +1,105 @@
+"use client"
+
+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"
+import { RequiredIndicator } from "../lib/required-indicator"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "../lib/use-is-invalid"
+
+type RadioGroupFieldProps = Omit<
+  ComponentProps<typeof RadioGroup>,
+  "name" | "onValueChange" | "value"
+> & {
+  description?: ReactNode
+  label?: ReactNode
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+}
+
+function RadioGroupField({
+  children,
+  description,
+  label,
+  required,
+  ...props
+}: RadioGroupFieldProps) {
+  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 schemaRequired = useIsFieldRequired(field)
+  const isRequired = required ?? schemaRequired
+
+  return (
+    <Field data-invalid={isInvalid}>
+      {label && (
+        <FieldLabel>
+          {label}
+          {isRequired && <RequiredIndicator />}
+        </FieldLabel>
+      )}
+      <RadioGroup
+        aria-describedby={describedBy(
+          [description, descriptionId],
+          [showError, errorId]
+        )}
+        aria-invalid={isInvalid || undefined}
+        name={field.name}
+        onValueChange={(value) => field.handleChange(String(value))}
+        value={field.state.value ?? ""}
+        {...props}
+      >
+        {children}
+      </RadioGroup>
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {showError && (
+        <FieldError errors={field.state.meta.errors} id={errorId} />
+      )}
+    </Field>
+  )
+}
+
+type RadioGroupFieldItemProps = Omit<
+  ComponentProps<typeof RadioGroupItem>,
+  "id"
+> & {
+  children?: ReactNode
+  labelClassName?: string
+}
+
+function RadioGroupFieldItem({
+  children,
+  className,
+  labelClassName,
+  ...props
+}: RadioGroupFieldItemProps) {
+  const id = useId()
+  return (
+    <label
+      className={cn("flex items-center gap-2 text-sm", labelClassName)}
+      htmlFor={id}
+    >
+      <RadioGroupItem className={className} id={id} {...props} />
+      {children}
+    </label>
+  )
+}
+
+export { RadioGroupField, RadioGroupFieldItem }

package/src/fields/reset-button.tsx

@@ -0,0 +1,29 @@
+"use client"
+
+import { Button } from "@zeno-lib/ui/button"
+import type { ComponentProps, ReactNode } from "react"
+
+import { useFormContext } from "../lib/contexts"
+
+type ResetButtonProps = Omit<ComponentProps<typeof Button>, "onClick" | "type">
+
+function ResetButton({
+  children,
+  variant = "outline",
+  ...props
+}: ResetButtonProps) {
+  const form = useFormContext()
+  return (
+    <Button
+      onClick={() => form.reset()}
+      type="button"
+      variant={variant}
+      {...props}
+    >
+      {(children ?? "Reset") as ReactNode}
+    </Button>
+  )
+}
+
+export type { ResetButtonProps }
+export { ResetButton }

package/src/fields/select-field.tsx

@@ -0,0 +1,113 @@
+"use client"
+
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@zeno-lib/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"
+import { RequiredIndicator } from "../lib/required-indicator"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "../lib/use-is-invalid"
+
+type SelectFieldProps = Omit<
+  ComponentProps<typeof Select>,
+  "name" | "onValueChange" | "value" | "items"
+> & {
+  children: ReactNode
+  description?: ReactNode
+  label?: ReactNode
+  placeholder?: string
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+  triggerClassName?: string
+  triggerSize?: ComponentProps<typeof SelectTrigger>["size"]
+}
+
+function SelectField({
+  children,
+  description,
+  label,
+  placeholder,
+  required,
+  triggerClassName,
+  triggerSize,
+  ...props
+}: SelectFieldProps) {
+  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 items = useMemo(() => {
+    const map: Record<string, ReactNode> = {}
+    Children.forEach(children, (child) => {
+      if (isValidElement(child)) {
+        const p = child.props as { value?: unknown; children?: ReactNode }
+        if (p.value !== undefined) {
+          map[String(p.value)] = p.children
+        }
+      }
+    })
+    return map
+  }, [children])
+
+  return (
+    <Field data-invalid={isInvalid}>
+      {label && (
+        <FieldLabel htmlFor={field.name}>
+          {label}
+          {isRequired && <RequiredIndicator />}
+        </FieldLabel>
+      )}
+      <Select
+        items={items}
+        name={field.name}
+        onValueChange={(value) => field.handleChange(value)}
+        value={field.state.value ?? null}
+        {...props}
+      >
+        <SelectTrigger
+          aria-describedby={describedBy(
+            [description, descriptionId],
+            [showError, errorId]
+          )}
+          aria-invalid={isInvalid || undefined}
+          className={triggerClassName}
+          id={field.name}
+          onBlur={field.handleBlur}
+          size={triggerSize}
+        >
+          <SelectValue placeholder={placeholder} />
+        </SelectTrigger>
+        <SelectContent>{children}</SelectContent>
+      </Select>
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {showError && (
+        <FieldError errors={field.state.meta.errors} id={errorId} />
+      )}
+    </Field>
+  )
+}
+
+export { SelectField }

package/src/fields/slider-field.tsx

@@ -0,0 +1,103 @@
+"use client"
+
+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"
+import { RequiredIndicator } from "../lib/required-indicator"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "../lib/use-is-invalid"
+
+type SliderValue = number | number[]
+
+type SliderFieldProps = Omit<
+  ComponentProps<typeof Slider>,
+  "name" | "onBlur" | "onValueChange" | "value"
+> & {
+  description?: ReactNode
+  label?: ReactNode
+  /**
+   * Render a live numeric readout next to the label. Accepts the current
+   * value(s) so callers can format units (e.g. `${v}%`, `$${a}-$${b}`).
+   */
+  formatValue?: (value: SliderValue) => ReactNode
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+}
+
+function SliderField({
+  description,
+  formatValue,
+  label,
+  required,
+  ...props
+}: SliderFieldProps) {
+  const field = useFieldContext<SliderValue>()
+  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 readout = formatValue && value !== undefined ? formatValue(value) : null
+
+  return (
+    <Field data-invalid={isInvalid}>
+      {(label || readout) && (
+        <FieldContent className="flex-row items-center justify-between">
+          {label && (
+            <FieldLabel htmlFor={field.name}>
+              {label}
+              {isRequired && <RequiredIndicator />}
+            </FieldLabel>
+          )}
+          {readout && (
+            <span className="text-muted-foreground text-sm tabular-nums">
+              {readout}
+            </span>
+          )}
+        </FieldContent>
+      )}
+      <Slider
+        aria-describedby={describedBy(
+          [description, descriptionId],
+          [showError, errorId]
+        )}
+        aria-invalid={isInvalid || undefined}
+        id={field.name}
+        name={field.name}
+        onBlur={field.handleBlur}
+        onValueChange={(next) => {
+          const value: SliderValue =
+            typeof next === "number" ? next : Array.from(next)
+          field.handleChange(value)
+        }}
+        value={value}
+        {...props}
+      />
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {showError && (
+        <FieldError errors={field.state.meta.errors} id={errorId} />
+      )}
+    </Field>
+  )
+}
+
+export type { SliderFieldProps }
+export { SliderField }

package/src/fields/submit-button.tsx

@@ -0,0 +1,31 @@
+"use client"
+
+import { Button } from "@zeno-lib/ui/button"
+import { Spinner } from "@zeno-lib/ui/spinner"
+import type { ComponentProps } from "react"
+
+import { useFormContext } from "../lib/contexts"
+
+type SubmitButtonProps = Omit<ComponentProps<typeof Button>, "type">
+
+function SubmitButton({ children, disabled, ...props }: SubmitButtonProps) {
+  const form = useFormContext()
+  return (
+    <form.Subscribe
+      selector={(state) => [state.canSubmit, state.isSubmitting] as const}
+    >
+      {([canSubmit, isSubmitting]) => (
+        <Button
+          disabled={disabled || !canSubmit || isSubmitting}
+          type="submit"
+          {...props}
+        >
+          {isSubmitting && <Spinner />}
+          {children}
+        </Button>
+      )}
+    </form.Subscribe>
+  )
+}
+
+export { SubmitButton }

package/src/fields/switch-field.tsx

@@ -0,0 +1,80 @@
+"use client"
+
+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"
+import { RequiredIndicator } from "../lib/required-indicator"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "../lib/use-is-invalid"
+
+type SwitchFieldProps = Omit<
+  ComponentProps<typeof Switch>,
+  "checked" | "id" | "name" | "onBlur" | "onCheckedChange"
+> & {
+  description?: ReactNode
+  label?: ReactNode
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+}
+
+function SwitchField({
+  description,
+  label,
+  required,
+  ...props
+}: SwitchFieldProps) {
+  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">
+      <FieldContent>
+        {label && (
+          <FieldLabel htmlFor={field.name}>
+            {label}
+            {isRequired && <RequiredIndicator />}
+          </FieldLabel>
+        )}
+        {description && (
+          <FieldDescription id={descriptionId}>{description}</FieldDescription>
+        )}
+        {showError && (
+          <FieldError errors={field.state.meta.errors} id={errorId} />
+        )}
+      </FieldContent>
+      <Switch
+        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)}
+        {...props}
+      />
+    </Field>
+  )
+}
+
+export { SwitchField }

package/src/fields/textarea-field.tsx

@@ -0,0 +1,91 @@
+"use client"
+
+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"
+import { RequiredIndicator } from "../lib/required-indicator"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "../lib/use-is-invalid"
+
+type TextAreaFieldProps = Omit<
+  ComponentProps<typeof Textarea>,
+  "children" | "id" | "name" | "onBlur" | "onChange" | "value"
+> & {
+  children?: ReactNode
+  description?: ReactNode
+  label?: ReactNode
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+}
+
+function TextAreaField({
+  children,
+  description,
+  label,
+  required,
+  ...props
+}: TextAreaFieldProps) {
+  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 textareaProps = {
+    "aria-describedby": describedBy(
+      [description, descriptionId],
+      [showError, errorId]
+    ),
+    "aria-invalid": isInvalid || undefined,
+    id: field.name,
+    name: field.name,
+    onBlur: field.handleBlur,
+    onChange: (event: React.ChangeEvent<HTMLTextAreaElement>) =>
+      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>
+          <InputGroupTextarea {...textareaProps} />
+          {children}
+        </InputGroup>
+      ) : (
+        <Textarea {...textareaProps} />
+      )}
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {showError && (
+        <FieldError errors={field.state.meta.errors} id={errorId} />
+      )}
+    </Field>
+  )
+}
+
+export { TextAreaField }