@mihcm/ui 0.14.1 → 0.15.0

package/src/Form.tsx

@@ -3,1322 +3,105 @@
 /**
  * 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:
+ * Public barrel for the `@mihcm/ui/Form` subpath. The implementation is
+ * split into focused modules under `./Form/*` so each file stays under the
+ * 400-line rule (CLAUDE.md §6). The split is internal — every consumer-
+ * facing export below is unchanged.
  *
- *   1. **Building blocks** — FormItem, FormLabel, FormDescription,
- *      FormMessage. Layout and accessibility scaffolding you compose
+ * 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,
+ *   2. **Integrated fields** — `FormInput`, `FormSearchField`, `FormTextarea`,
+ *      `FormCheckbox`, `FormSwitch`, `FormSelect`, `FormCombobox`,
+ *      `FormRadioGroup`, `FormRadioCardGroup`, `FormDatePicker`,
+ *      `FormDateRangePicker`, `FormCheckboxGrid`, `FormDropzone`. Each wires
+ *      a TanStack `form.Field` to the matching UI primitive with label,
  *      description, and error display included.
  *
+ *   3. **Composition helpers** — `FormFieldArray`, `FormSubscribe`,
+ *      `FormListenEffect`, `FormActions`.
+ *
  * 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>
-  );
-}
+/* Shared types */
+export type { FormFieldValidators } from './Form/types.js';
+
+/* Building blocks */
+export {
+  FormDescription,
+  FormItem,
+  FormLabel,
+  FormMessage,
+  type FormDescriptionProps,
+  type FormItemProps,
+  type FormLabelProps,
+  type FormMessageProps,
+} from './Form/building-blocks.js';
+
+/* Text fields */
+export {
+  FormInput,
+  FormSearchField,
+  FormTextarea,
+  type FormInputProps,
+  type FormSearchFieldProps,
+  type FormTextareaProps,
+} from './Form/fields-text.js';
+
+/* Toggle fields */
+export {
+  FormCheckbox,
+  FormSwitch,
+  type FormCheckboxProps,
+  type FormSwitchProps,
+} from './Form/fields-toggle.js';
+
+/* Choice fields */
+export {
+  FormCombobox,
+  FormRadioCardGroup,
+  FormRadioGroup,
+  FormSelect,
+  type FormComboboxProps,
+  type FormRadioCardGroupProps,
+  type FormRadioGroupOption,
+  type FormRadioGroupProps,
+  type FormSelectOption,
+  type FormSelectProps,
+} from './Form/fields-choice.js';
+
+/* Date fields */
+export {
+  FormDatePicker,
+  FormDateRangePicker,
+  type FormDatePickerProps,
+  type FormDateRangePickerProps,
+} from './Form/fields-date.js';
+
+/* Complex fields */
+export {
+  FormCheckboxGrid,
+  FormDropzone,
+  type FormCheckboxGridProps,
+  type FormDropzoneProps,
+} from './Form/fields-complex.js';
+
+/* Composition helpers */
+export {
+  FormActions,
+  FormFieldArray,
+  FormListenEffect,
+  FormSubscribe,
+  type FieldArrayItemApi,
+  type FormActionsProps,
+  type FormFieldArrayProps,
+  type FormListenEffectProps,
+  type FormSubscribeProps,
+} from './Form/helpers.js';