@mihcm/ui 0.14.1 → 0.15.0

package/src/Form/fields-choice.tsx

@@ -0,0 +1,312 @@
+'use client';
+
+/**
+ * Single-choice fields integrated with TanStack Form: FormSelect, FormCombobox,
+ * FormRadioGroup, FormRadioCardGroup.
+ */
+import { useId } from 'react';
+import { Combobox, type ComboboxOption } from '../Combobox.js';
+import { RadioCardGroup, type RadioCardOption } from '../RadioCardGroup.js';
+import { RadioGroup, RadioGroupItem } from '../RadioGroup.js';
+import { Select, SelectContent, SelectItem, SelectTrigger } from '../Select.js';
+import {
+  FormDescription,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from './building-blocks.js';
+import type { AnyFormApi, FieldRenderProps, FormFieldValidators } from './types.js';
+
+/* ── 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>
+  );
+}

package/src/Form/fields-complex.tsx

@@ -0,0 +1,195 @@
+'use client';
+
+/**
+ * Complex multi-value fields integrated with TanStack Form: FormCheckboxGrid,
+ * FormDropzone.
+ */
+import { useId } from 'react';
+import {
+  CheckboxGrid,
+  type CheckboxGridProps,
+  type CheckboxGridSelection,
+} from '../CheckboxGrid.js';
+import { Dropzone, type DropzoneProps } from '../Dropzone.js';
+import {
+  FormDescription,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from './building-blocks.js';
+import type { AnyFormApi, FieldRenderProps, FormFieldValidators } from './types.js';
+
+/* ── 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>
+  );
+}

package/src/Form/fields-date.tsx

@@ -0,0 +1,195 @@
+'use client';
+
+/**
+ * Date fields integrated with TanStack Form: FormDatePicker, FormDateRangePicker.
+ */
+import { useId } from 'react';
+import { cn } from '../internal/cn.js';
+import { DatePicker, type DatePickerProps } from '../DatePicker.js';
+import {
+  FormDescription,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from './building-blocks.js';
+import type { AnyFormApi, FieldRenderProps, FormFieldValidators } from './types.js';
+
+/* ── 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>
+  );
+}