@mihcm/ui 0.14.1

package/src/Form.tsx

@@ -0,0 +1,1324 @@
+'use client';
+
+/**
+ * Form field building blocks (web variant — React DOM).
+ *
+ * Composable primitives that integrate TanStack React Form v1 with
+ * the existing MiHCM UI primitives (Input, Label, Textarea, Select,
+ * Checkbox, RadioGroup, Switch). Two layers:
+ *
+ *   1. **Building blocks** — FormItem, FormLabel, FormDescription,
+ *      FormMessage. Layout and accessibility scaffolding you compose
+ *      freely around any control.
+ *
+ *   2. **Integrated fields** — FormInput, FormTextarea, FormCheckbox,
+ *      FormSwitch, FormSelect, FormRadioGroup. Each one wires a
+ *      TanStack `form.Field` to the matching UI primitive with label,
+ *      description, and error display included.
+ *
+ * Wiki: docs/components/Form.md
+ */
+import { useId, type HTMLAttributes, type ReactNode } from 'react';
+import { cn } from './internal/cn.js';
+import { Label } from './Label.js';
+import { Input } from './Input.js';
+import { SearchField, type SearchFieldProps } from './SearchField.js';
+import { Textarea } from './Textarea.js';
+import { Checkbox } from './Checkbox.js';
+import {
+  CheckboxGrid,
+  type CheckboxGridProps,
+  type CheckboxGridSelection,
+} from './CheckboxGrid.js';
+import { Switch } from './Switch.js';
+import { Button } from './Button.js';
+import { DatePicker, type DatePickerProps } from './DatePicker.js';
+import { Dropzone, type DropzoneProps } from './Dropzone.js';
+import { Combobox, type ComboboxOption } from './Combobox.js';
+import { RadioCardGroup, type RadioCardOption } from './RadioCardGroup.js';
+import { Select, SelectTrigger, SelectContent, SelectItem } from './Select.js';
+import { RadioGroup, RadioGroupItem } from './RadioGroup.js';
+
+/* Re-export useForm for consumer convenience */
+export { useForm } from '@tanstack/react-form';
+
+/* ------------------------------------------------------------------ */
+/*  Validator type — kept loose so consumers can pass onChange, onBlur */
+/*  etc. without fighting 12-param generics.                          */
+/* ------------------------------------------------------------------ */
+
+/** Validator config passed through to TanStack Form's `form.Field`. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type FormFieldValidators = Record<string, any>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyFormApi = any;
+
+/* Field render-prop shape — kept minimal to avoid coupling to
+   TanStack internals that change across minor versions. */
+interface FieldRenderProps<T> {
+  state: {
+    value: T;
+    meta: { errors: string[]; isTouched: boolean };
+  };
+  handleChange: (v: T) => void;
+  handleBlur: () => void;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Building blocks                                                   */
+/* ------------------------------------------------------------------ */
+
+/* ── FormItem ─────────────────────────────────────────────────────── */
+
+export interface FormItemProps extends HTMLAttributes<HTMLDivElement> {}
+
+/** Vertical stack container for label + control + description + error. */
+export function FormItem({ className, children, ...props }: FormItemProps) {
+  return (
+    <div className={cn('flex flex-col gap-1.5', className)} {...props}>
+      {children}
+    </div>
+  );
+}
+
+/* ── FormLabel ────────────────────────────────────────────────────── */
+
+export interface FormLabelProps extends HTMLAttributes<HTMLLabelElement> {
+  htmlFor?: string;
+  required?: boolean;
+}
+
+/** Styled label with optional required asterisk. Delegates to the existing Label primitive. */
+export function FormLabel({ htmlFor, required, className, children, ...props }: FormLabelProps) {
+  return (
+    <Label
+      {...(htmlFor !== undefined && { htmlFor })}
+      {...(required !== undefined && { required })}
+      {...(className !== undefined && { className })}
+      {...props}
+    >
+      {children}
+    </Label>
+  );
+}
+
+/* ── FormDescription ──────────────────────────────────────────────── */
+
+export interface FormDescriptionProps extends HTMLAttributes<HTMLParagraphElement> {}
+
+/** Muted helper text rendered below the control. */
+export function FormDescription({ className, children, ...props }: FormDescriptionProps) {
+  return (
+    <p className={cn('text-xs text-muted-foreground', className)} {...props}>
+      {children}
+    </p>
+  );
+}
+
+/* ── FormMessage ──────────────────────────────────────────────────── */
+
+export interface FormMessageProps extends HTMLAttributes<HTMLParagraphElement> {
+  /** Array of error strings — only the first is displayed. */
+  errors?: string[];
+}
+
+/** Error message display with warning icon. Transitions in/out smoothly. */
+export function FormMessage({ errors, className, ...props }: FormMessageProps) {
+  const firstError = errors?.filter(Boolean)[0];
+  if (!firstError) return null;
+
+  return (
+    <p
+      role="alert"
+      className={cn(
+        'flex items-center gap-1 text-xs text-destructive',
+        'transition-all duration-150',
+        className,
+      )}
+      {...props}
+    >
+      {/* Warning triangle icon */}
+      <svg
+        aria-hidden
+        viewBox="0 0 16 16"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={1.5}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        className="h-3.5 w-3.5 shrink-0"
+      >
+        <path d="M8 2L1.5 13h13L8 2z" />
+        <path d="M8 6v3" />
+        <circle cx="8" cy="11" r="0.5" fill="currentColor" stroke="none" />
+      </svg>
+      {firstError}
+    </p>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormInput                                                         */
+/* ------------------------------------------------------------------ */
+
+export interface FormInputProps {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  description?: string;
+  required?: boolean;
+  placeholder?: string;
+  type?: string;
+  disabled?: boolean;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** Input field integrated with TanStack Form. */
+export function FormInput({
+  form,
+  name,
+  label,
+  description,
+  required,
+  placeholder,
+  type,
+  disabled,
+  className,
+  validators,
+}: FormInputProps) {
+  const id = useId();
+  const descId = `${id}-desc`;
+  const msgId = `${id}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<string>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <FormLabel htmlFor={id} {...(required !== undefined && { required })}>
+              {label}
+            </FormLabel>
+            <Input
+              id={id}
+              {...(type !== undefined && { type })}
+              {...(placeholder !== undefined && { placeholder })}
+              {...(disabled !== undefined && { disabled })}
+              {...(required !== undefined && { required })}
+              invalid={hasError}
+              value={field.state.value ?? ''}
+              onChange={(e) => field.handleChange(e.target.value)}
+              onBlur={field.handleBlur}
+              aria-describedby={hasError ? msgId : description !== undefined ? descId : undefined}
+            />
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormSearchField                                                   */
+/* ------------------------------------------------------------------ */
+
+export interface FormSearchFieldProps {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  description?: string;
+  required?: boolean;
+  placeholder?: string;
+  disabled?: boolean;
+  size?: SearchFieldProps['size'];
+  noClear?: boolean;
+  className?: string;
+  inputClassName?: string;
+  validators?: FormFieldValidators;
+}
+
+/** Search field integrated with TanStack Form. */
+export function FormSearchField({
+  form,
+  name,
+  label,
+  description,
+  required,
+  placeholder,
+  disabled,
+  size,
+  noClear,
+  className,
+  inputClassName,
+  validators,
+}: FormSearchFieldProps) {
+  const id = useId();
+  const descId = `${id}-desc`;
+  const msgId = `${id}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<string>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <FormLabel htmlFor={id} {...(required !== undefined && { required })}>
+              {label}
+            </FormLabel>
+            <SearchField
+              id={id}
+              value={field.state.value ?? ''}
+              onValueChange={field.handleChange}
+              onBlur={field.handleBlur}
+              {...(placeholder !== undefined && { placeholder })}
+              {...(disabled !== undefined && { disabled })}
+              {...(size !== undefined && { size })}
+              {...(noClear !== undefined && { noClear })}
+              {...(inputClassName !== undefined && { inputClassName })}
+              aria-describedby={hasError ? msgId : description !== undefined ? descId : undefined}
+              aria-invalid={hasError}
+            />
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormTextarea                                                      */
+/* ------------------------------------------------------------------ */
+
+export interface FormTextareaProps {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  description?: string;
+  required?: boolean;
+  placeholder?: string;
+  rows?: number;
+  disabled?: boolean;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** Textarea field integrated with TanStack Form. */
+export function FormTextarea({
+  form,
+  name,
+  label,
+  description,
+  required,
+  placeholder,
+  rows,
+  disabled,
+  className,
+  validators,
+}: FormTextareaProps) {
+  const id = useId();
+  const descId = `${id}-desc`;
+  const msgId = `${id}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<string>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <FormLabel htmlFor={id} {...(required !== undefined && { required })}>
+              {label}
+            </FormLabel>
+            <Textarea
+              id={id}
+              {...(placeholder !== undefined && { placeholder })}
+              {...(disabled !== undefined && { disabled })}
+              {...(required !== undefined && { required })}
+              {...(rows !== undefined && { rows })}
+              invalid={hasError}
+              value={field.state.value ?? ''}
+              onChange={(e) => field.handleChange(e.target.value)}
+              onBlur={field.handleBlur}
+              aria-describedby={hasError ? msgId : description !== undefined ? descId : undefined}
+            />
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormCheckbox                                                      */
+/* ------------------------------------------------------------------ */
+
+export interface FormCheckboxProps {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** Checkbox field integrated with TanStack Form. */
+export function FormCheckbox({
+  form,
+  name,
+  label,
+  description,
+  disabled,
+  className,
+  validators,
+}: FormCheckboxProps) {
+  const id = useId();
+  const descId = `${id}-desc`;
+  const msgId = `${id}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<boolean>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <div className="flex items-center gap-2">
+              <Checkbox
+                id={id}
+                checked={!!field.state.value}
+                onCheckedChange={(checked) => field.handleChange(checked === true)}
+                {...(disabled !== undefined && { disabled })}
+                aria-describedby={hasError ? msgId : description !== undefined ? descId : undefined}
+              />
+              <FormLabel htmlFor={id}>{label}</FormLabel>
+            </div>
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormSwitch                                                        */
+/* ------------------------------------------------------------------ */
+
+export interface FormSwitchProps {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** Switch field integrated with TanStack Form. */
+export function FormSwitch({
+  form,
+  name,
+  label,
+  description,
+  disabled,
+  className,
+  validators,
+}: FormSwitchProps) {
+  const id = useId();
+  const descId = `${id}-desc`;
+  const msgId = `${id}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<boolean>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <div className="flex items-center gap-3">
+              <Switch
+                id={id}
+                checked={!!field.state.value}
+                onCheckedChange={(checked) => field.handleChange(checked)}
+                {...(disabled !== undefined && { disabled })}
+                aria-describedby={hasError ? msgId : description !== undefined ? descId : undefined}
+              />
+              <FormLabel htmlFor={id}>{label}</FormLabel>
+            </div>
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormSelect                                                        */
+/* ------------------------------------------------------------------ */
+
+export interface FormSelectOption {
+  value: string;
+  label: string;
+}
+
+export interface FormSelectProps {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  options: FormSelectOption[];
+  description?: string;
+  required?: boolean;
+  placeholder?: string;
+  disabled?: boolean;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** Select dropdown field integrated with TanStack Form. */
+export function FormSelect({
+  form,
+  name,
+  label,
+  options,
+  description,
+  required,
+  placeholder,
+  disabled,
+  className,
+  validators,
+}: FormSelectProps) {
+  const id = useId();
+  const descId = `${id}-desc`;
+  const msgId = `${id}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<string>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <FormLabel htmlFor={id} {...(required !== undefined && { required })}>
+              {label}
+            </FormLabel>
+            <Select
+              value={field.state.value ?? ''}
+              onValueChange={(v) => {
+                field.handleChange(v);
+                field.handleBlur();
+              }}
+            >
+              <SelectTrigger
+                id={id}
+                {...(placeholder !== undefined && { placeholder })}
+                {...(disabled !== undefined && { disabled })}
+                variant={hasError ? 'destructive' : 'default'}
+                aria-describedby={hasError ? msgId : description !== undefined ? descId : undefined}
+              />
+              <SelectContent>
+                {options.map((opt) => (
+                  <SelectItem key={opt.value} value={opt.value}>
+                    {opt.label}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormRadioGroup                                                    */
+/* ------------------------------------------------------------------ */
+
+export interface FormRadioGroupOption {
+  value: string;
+  label: string;
+}
+
+export interface FormRadioGroupProps {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  options: FormRadioGroupOption[];
+  description?: string;
+  required?: boolean;
+  orientation?: 'horizontal' | 'vertical';
+  disabled?: boolean;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** RadioGroup field integrated with TanStack Form. */
+export function FormRadioGroup({
+  form,
+  name,
+  label,
+  options,
+  description,
+  required,
+  orientation,
+  disabled,
+  className,
+  validators,
+}: FormRadioGroupProps) {
+  const id = useId();
+  const descId = `${id}-desc`;
+  const msgId = `${id}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<string>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <FormLabel {...(required !== undefined && { required })}>{label}</FormLabel>
+            <RadioGroup
+              value={field.state.value ?? ''}
+              onValueChange={(v) => {
+                field.handleChange(v);
+                field.handleBlur();
+              }}
+              {...(orientation !== undefined && { orientation })}
+              {...(disabled !== undefined && { disabled })}
+              aria-describedby={hasError ? msgId : description !== undefined ? descId : undefined}
+            >
+              {options.map((opt) => (
+                <RadioGroupItem key={opt.value} value={opt.value}>
+                  {opt.label}
+                </RadioGroupItem>
+              ))}
+            </RadioGroup>
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormRadioCardGroup                                                */
+/* ------------------------------------------------------------------ */
+
+export interface FormRadioCardGroupProps {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  options: RadioCardOption[];
+  description?: string;
+  required?: boolean;
+  orientation?: 'horizontal' | 'vertical';
+  columns?: 1 | 2 | 3 | 4;
+  tone?: 'primary' | 'accent';
+  disabled?: boolean;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** Card-style radio group integrated with TanStack Form. */
+export function FormRadioCardGroup({
+  form,
+  name,
+  label,
+  options,
+  description,
+  required,
+  orientation,
+  columns,
+  tone,
+  disabled,
+  className,
+  validators,
+}: FormRadioCardGroupProps) {
+  const id = useId();
+  const descId = `${id}-desc`;
+  const msgId = `${id}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<string>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <FormLabel {...(required !== undefined && { required })}>{label}</FormLabel>
+            <RadioCardGroup
+              options={options}
+              value={field.state.value ?? ''}
+              onValueChange={(value) => {
+                field.handleChange(value);
+                field.handleBlur();
+              }}
+              {...(orientation !== undefined && { orientation })}
+              {...(columns !== undefined && { columns })}
+              {...(tone !== undefined && { tone })}
+              {...(disabled !== undefined && { disabled })}
+              aria-describedby={hasError ? msgId : description !== undefined ? descId : undefined}
+              aria-invalid={hasError}
+            />
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormCombobox                                                      */
+/* ------------------------------------------------------------------ */
+
+export interface FormComboboxProps {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  options: ComboboxOption[];
+  description?: string;
+  required?: boolean;
+  placeholder?: string;
+  searchPlaceholder?: string;
+  emptyText?: string;
+  disabled?: boolean;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** Combobox field integrated with TanStack Form. */
+export function FormCombobox({
+  form,
+  name,
+  label,
+  options,
+  description,
+  required,
+  placeholder,
+  searchPlaceholder,
+  emptyText,
+  disabled,
+  className,
+  validators,
+}: FormComboboxProps) {
+  const id = useId();
+  const descId = `${id}-desc`;
+  const msgId = `${id}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<string>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <FormLabel htmlFor={id} {...(required !== undefined && { required })}>
+              {label}
+            </FormLabel>
+            <Combobox
+              id={id}
+              aria-label={label}
+              options={options}
+              value={field.state.value ?? ''}
+              onValueChange={(value) => {
+                field.handleChange(value);
+                field.handleBlur();
+              }}
+              {...(placeholder !== undefined && { placeholder })}
+              {...(searchPlaceholder !== undefined && { searchPlaceholder })}
+              {...(emptyText !== undefined && { emptyText })}
+              {...(disabled !== undefined && { disabled })}
+              aria-describedby={hasError ? msgId : description !== undefined ? descId : undefined}
+              aria-invalid={hasError}
+            />
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormDatePicker                                                     */
+/* ------------------------------------------------------------------ */
+
+export interface FormDatePickerProps {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  description?: string;
+  required?: boolean;
+  placeholder?: string;
+  disabled?: boolean;
+  /** Show time selection alongside date. */
+  showTimeSelect?: boolean;
+  /** Date format string (default: "MM/dd/yyyy"). */
+  dateFormat?: string;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** DatePicker field integrated with TanStack Form. Uses the mihcm DatePicker primitive. */
+export function FormDatePicker({
+  form,
+  name,
+  label,
+  description,
+  required,
+  placeholder,
+  disabled,
+  showTimeSelect,
+  dateFormat,
+  className,
+  validators,
+}: FormDatePickerProps) {
+  const id = useId();
+  const descId = `${id}-desc`;
+  const msgId = `${id}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<Date | null>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <FormLabel htmlFor={id} {...(required !== undefined && { required })}>
+              {label}
+            </FormLabel>
+            <DatePicker
+              id={id}
+              selected={field.state.value}
+              onChange={(date: Date | null) => field.handleChange(date)}
+              onBlur={field.handleBlur}
+              {...(placeholder !== undefined && { placeholderText: placeholder })}
+              {...(disabled !== undefined && { disabled })}
+              {...(showTimeSelect !== undefined && { showTimeSelect })}
+              {...(dateFormat !== undefined && { dateFormat })}
+              className={cn(hasError && 'border-destructive focus:ring-destructive')}
+              {...(hasError
+                ? { 'aria-describedby': msgId }
+                : description !== undefined
+                  ? { 'aria-describedby': descId }
+                  : {})}
+            />
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormDateRangePicker                                                */
+/* ------------------------------------------------------------------ */
+
+export interface FormDateRangePickerProps {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  description?: string;
+  required?: boolean;
+  placeholder?: string;
+  disabled?: boolean;
+  isClearable?: boolean;
+  align?: DatePickerProps['align'];
+  showTimeSelect?: boolean;
+  showWeekNumbers?: boolean;
+  monthsShown?: number;
+  minDate?: Date;
+  maxDate?: Date;
+  disabledDays?: DatePickerProps['disabledDays'];
+  dateFormat?: string;
+  calendarProps?: DatePickerProps['calendarProps'];
+  triggerWidth?: 'auto' | 'full';
+  triggerClassName?: string;
+  closeOnRangeComplete?: boolean;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** Date range picker integrated with TanStack Form. Field value is `[start, end]`. */
+export function FormDateRangePicker({
+  form,
+  name,
+  label,
+  description,
+  required,
+  placeholder,
+  disabled,
+  isClearable,
+  align,
+  showTimeSelect,
+  showWeekNumbers,
+  monthsShown,
+  minDate,
+  maxDate,
+  disabledDays,
+  dateFormat,
+  calendarProps,
+  triggerWidth,
+  triggerClassName,
+  closeOnRangeComplete,
+  className,
+  validators,
+}: FormDateRangePickerProps) {
+  const id = useId();
+  const descId = `${id}-desc`;
+  const msgId = `${id}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<[Date | null, Date | null]>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        const [startDate, endDate] = field.state.value ?? [null, null];
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <FormLabel htmlFor={id} {...(required !== undefined && { required })}>
+              {label}
+            </FormLabel>
+            <DatePicker
+              id={id}
+              selectsRange
+              startDate={startDate}
+              endDate={endDate}
+              onChange={(range) => field.handleChange(range)}
+              onBlur={field.handleBlur}
+              {...(placeholder !== undefined && { placeholderText: placeholder })}
+              {...(disabled !== undefined && { disabled })}
+              {...(isClearable !== undefined && { isClearable })}
+              {...(align !== undefined && { align })}
+              {...(showTimeSelect !== undefined && { showTimeSelect })}
+              {...(showWeekNumbers !== undefined && { showWeekNumbers })}
+              {...(monthsShown !== undefined && { monthsShown })}
+              {...(minDate !== undefined && { minDate })}
+              {...(maxDate !== undefined && { maxDate })}
+              {...(disabledDays !== undefined && { disabledDays })}
+              {...(dateFormat !== undefined && { dateFormat })}
+              {...(calendarProps !== undefined && { calendarProps })}
+              {...(triggerWidth !== undefined && { triggerWidth })}
+              {...(triggerClassName !== undefined && { triggerClassName })}
+              {...(closeOnRangeComplete !== undefined && { closeOnRangeComplete })}
+              className={cn(hasError && 'border-destructive focus:ring-destructive')}
+              {...(hasError
+                ? { 'aria-describedby': msgId }
+                : description !== undefined
+                  ? { 'aria-describedby': descId }
+                  : {})}
+            />
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormCheckboxGrid                                                   */
+/* ------------------------------------------------------------------ */
+
+export interface FormCheckboxGridProps extends Pick<
+  CheckboxGridProps,
+  | 'items'
+  | 'columns'
+  | 'layout'
+  | 'density'
+  | 'showToolbar'
+  | 'searchPlaceholder'
+  | 'maxHeight'
+  | 'emptyState'
+  | 'getItemClassName'
+> {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  description?: string;
+  required?: boolean;
+  disabled?: boolean;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** Multi-select CheckboxGrid integrated with TanStack Form. */
+export function FormCheckboxGrid({
+  form,
+  name,
+  label,
+  description,
+  required,
+  disabled,
+  className,
+  validators,
+  items,
+  columns,
+  layout,
+  density,
+  showToolbar,
+  searchPlaceholder,
+  maxHeight,
+  emptyState,
+  getItemClassName,
+}: FormCheckboxGridProps) {
+  const descId = useId();
+  const msgId = `${descId}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<CheckboxGridSelection>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <FormLabel {...(required !== undefined && { required })}>{label}</FormLabel>
+            <CheckboxGrid
+              items={items}
+              selected={field.state.value ?? {}}
+              onSelectedChange={(next) => {
+                if (!disabled) field.handleChange(next);
+                field.handleBlur();
+              }}
+              {...(columns !== undefined && { columns })}
+              {...(layout !== undefined && { layout })}
+              {...(density !== undefined && { density })}
+              {...(showToolbar !== undefined && { showToolbar })}
+              {...(searchPlaceholder !== undefined && { searchPlaceholder })}
+              {...(maxHeight !== undefined && { maxHeight })}
+              {...(emptyState !== undefined && { emptyState })}
+              {...(getItemClassName !== undefined && { getItemClassName })}
+              aria-disabled={disabled}
+              aria-describedby={hasError ? msgId : description !== undefined ? descId : undefined}
+              aria-invalid={hasError}
+            />
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormDropzone                                                       */
+/* ------------------------------------------------------------------ */
+
+export interface FormDropzoneProps extends Pick<
+  DropzoneProps,
+  | 'accept'
+  | 'maxFiles'
+  | 'maxSize'
+  | 'minSize'
+  | 'multiple'
+  | 'validator'
+  | 'heading'
+  | 'description'
+  | 'browseLabel'
+  | 'children'
+> {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  fieldDescription?: string;
+  required?: boolean;
+  disabled?: boolean;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** File-list Dropzone integrated with TanStack Form. Field value is `File[]`. */
+export function FormDropzone({
+  form,
+  name,
+  label,
+  fieldDescription,
+  required,
+  disabled,
+  className,
+  validators,
+  accept,
+  maxFiles,
+  maxSize,
+  minSize,
+  multiple,
+  validator,
+  heading,
+  description,
+  browseLabel,
+  children,
+}: FormDropzoneProps) {
+  const descId = useId();
+  const msgId = `${descId}-msg`;
+
+  return (
+    <form.Field name={name} {...(validators !== undefined && { validators })}>
+      {(field: FieldRenderProps<File[]>) => {
+        const errors = field.state.meta.isTouched ? field.state.meta.errors : [];
+        const hasError = errors.length > 0;
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <FormLabel {...(required !== undefined && { required })}>{label}</FormLabel>
+            <Dropzone
+              {...(accept !== undefined && { accept })}
+              {...(maxFiles !== undefined && { maxFiles })}
+              {...(maxSize !== undefined && { maxSize })}
+              {...(minSize !== undefined && { minSize })}
+              {...(multiple !== undefined && { multiple })}
+              {...(validator !== undefined && { validator })}
+              {...(heading !== undefined && { heading })}
+              {...(description !== undefined && { description })}
+              {...(browseLabel !== undefined && { browseLabel })}
+              {...(children !== undefined && { children })}
+              {...(disabled !== undefined && { disabled })}
+              onFilesAccepted={(files) => {
+                field.handleChange(files);
+                field.handleBlur();
+              }}
+              onFilesRejected={() => field.handleBlur()}
+              aria-describedby={
+                hasError ? msgId : fieldDescription !== undefined ? descId : undefined
+              }
+              aria-invalid={hasError}
+            />
+            {fieldDescription !== undefined ? (
+              <FormDescription id={descId}>{fieldDescription}</FormDescription>
+            ) : null}
+            {hasError ? <FormMessage id={msgId} errors={errors} /> : null}
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormFieldArray                                                     */
+/* ------------------------------------------------------------------ */
+
+/** Render props supplied to each array item's `renderField` callback. */
+export interface FieldArrayItemApi {
+  /** Index of this item within the array. */
+  index: number;
+  /** Total number of items currently in the array. */
+  total: number;
+  /** Remove this item from the array. */
+  remove: () => void;
+}
+
+export interface FormFieldArrayProps {
+  form: AnyFormApi;
+  name: string;
+  label: string;
+  description?: string;
+  /** Render function called for each array item. */
+  renderField: (item: FieldArrayItemApi) => ReactNode;
+  /** Label text for the add button. Default: "Add item". */
+  addLabel?: string;
+  className?: string;
+  validators?: FormFieldValidators;
+}
+
+/** Field array integrated with TanStack Form. Provides add/remove buttons. */
+export function FormFieldArray({
+  form,
+  name,
+  label,
+  description,
+  renderField,
+  addLabel = 'Add item',
+  className,
+  validators,
+}: FormFieldArrayProps) {
+  const id = useId();
+  const descId = `${id}-desc`;
+
+  return (
+    <form.Field name={name} mode="array" {...(validators !== undefined && { validators })}>
+      {/* eslint-disable-next-line @typescript-eslint/no-explicit-any */}
+      {(field: any) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const items = (field.state.value ?? []) as any[];
+        return (
+          <FormItem {...(className !== undefined && { className })}>
+            <div className="flex items-center justify-between">
+              <FormLabel>{label}</FormLabel>
+              <Button type="button" variant="outline" size="sm" onClick={() => field.pushValue({})}>
+                + {addLabel}
+              </Button>
+            </div>
+            {description !== undefined ? (
+              <FormDescription id={descId}>{description}</FormDescription>
+            ) : null}
+            <div className="space-y-3">
+              {items.map((_: unknown, i: number) => (
+                <div
+                  key={i}
+                  className="rounded-lg border border-border p-3 transition-all duration-150"
+                >
+                  {renderField({
+                    index: i,
+                    total: items.length,
+                    remove: () => field.removeValue(i),
+                  })}
+                </div>
+              ))}
+            </div>
+          </FormItem>
+        );
+      }}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormSubscribe                                                      */
+/* ------------------------------------------------------------------ */
+
+export interface FormSubscribeProps<TSelected> {
+  form: AnyFormApi;
+  /** Selector function that picks values from form state. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  selector: (state: any) => TSelected;
+  /** Render function receiving the selected state. */
+  children: (selected: TSelected) => ReactNode;
+}
+
+/** Convenience wrapper around `form.Subscribe` for reactive state display. */
+export function FormSubscribe<TSelected>({
+  form,
+  selector,
+  children,
+}: FormSubscribeProps<TSelected>) {
+  return <form.Subscribe selector={selector}>{children}</form.Subscribe>;
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormListenEffect                                                   */
+/* ------------------------------------------------------------------ */
+
+export interface FormListenEffectProps {
+  form: AnyFormApi;
+  /** Field name to listen to. */
+  name: string;
+  /** Listener callbacks (onChange, onBlur, etc.) for side effects. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  listeners: Record<string, any>;
+}
+
+/**
+ * Invisible field that fires side effects when another field changes.
+ * Useful for dependent field updates (e.g. country changes → reset city).
+ * Renders nothing visually.
+ */
+export function FormListenEffect({ form, name, listeners }: FormListenEffectProps) {
+  return (
+    <form.Field name={name} listeners={listeners}>
+      {() => null}
+    </form.Field>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  FormActions                                                        */
+/* ------------------------------------------------------------------ */
+
+export interface FormActionsProps {
+  form: AnyFormApi;
+  /** Label for the submit button. Default: "Submit". */
+  submitLabel?: string;
+  /** Label for the reset button. Default: "Reset". */
+  resetLabel?: string;
+  /** Whether to show the reset button. Default: true. */
+  showReset?: boolean;
+  /** Disable both buttons externally. */
+  disabled?: boolean;
+  className?: string;
+}
+
+/** Footer with submit and reset buttons. Reacts to form submitting state. */
+export function FormActions({
+  form,
+  submitLabel = 'Submit',
+  resetLabel = 'Reset',
+  showReset = true,
+  disabled,
+  className,
+}: FormActionsProps) {
+  return (
+    <form.Subscribe
+      selector={(s: { canSubmit: boolean; isSubmitting: boolean }) => ({
+        canSubmit: s.canSubmit,
+        isSubmitting: s.isSubmitting,
+      })}
+    >
+      {/* eslint-disable-next-line @typescript-eslint/no-explicit-any */}
+      {(state: any) => (
+        <div className={cn('flex items-center gap-3 pt-2', className)}>
+          <Button type="submit" disabled={disabled || !state.canSubmit}>
+            {state.isSubmitting ? 'Submitting...' : submitLabel}
+          </Button>
+          {showReset ? (
+            <Button
+              type="button"
+              variant="outline"
+              disabled={disabled || state.isSubmitting}
+              onClick={() => form.reset()}
+            >
+              {resetLabel}
+            </Button>
+          ) : null}
+        </div>
+      )}
+    </form.Subscribe>
+  );
+}