@mihcm/ui 0.14.1 → 0.15.0

package/src/Form/fields-text.tsx

@@ -0,0 +1,218 @@
+'use client';
+
+/**
+ * Text-style fields integrated with TanStack Form: FormInput, FormSearchField,
+ * FormTextarea. Each wires `form.Field` to the matching UI primitive with
+ * label, description, and error display included.
+ */
+import { useId } from 'react';
+import { Input } from '../Input.js';
+import { SearchField, type SearchFieldProps } from '../SearchField.js';
+import { Textarea } from '../Textarea.js';
+import {
+  FormDescription,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from './building-blocks.js';
+import type { AnyFormApi, FieldRenderProps, FormFieldValidators } from './types.js';
+
+/* ── 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>
+  );
+}

package/src/Form/fields-toggle.tsx

@@ -0,0 +1,123 @@
+'use client';
+
+/**
+ * Boolean / toggle fields integrated with TanStack Form: FormCheckbox, FormSwitch.
+ */
+import { useId } from 'react';
+import { Checkbox } from '../Checkbox.js';
+import { Switch } from '../Switch.js';
+import {
+  FormDescription,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from './building-blocks.js';
+import type { AnyFormApi, FieldRenderProps, FormFieldValidators } from './types.js';
+
+/* ── 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>
+  );
+}

package/src/Form/helpers.tsx

@@ -0,0 +1,189 @@
+'use client';
+
+/**
+ * Form composition helpers: FormFieldArray, FormSubscribe, FormListenEffect,
+ * FormActions. These wire common TanStack Form patterns to MiHCM primitives.
+ */
+import { useId, type ReactNode } from 'react';
+import { cn } from '../internal/cn.js';
+import { Button } from '../Button.js';
+import {
+  FormDescription,
+  FormItem,
+  FormLabel,
+} from './building-blocks.js';
+import type { AnyFormApi, FormFieldValidators } from './types.js';
+
+/* ── 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>
+  );
+}

package/src/Form/types.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared Form types.
+ *
+ * Wraps TanStack React Form's internals at the boundary so the rest of the
+ * field components can stay strongly typed without leaking 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
+export type AnyFormApi = any;
+
+/**
+ * Field render-prop shape — kept minimal to avoid coupling to TanStack
+ * internals that change across minor versions.
+ */
+export interface FieldRenderProps<T> {
+  state: {
+    value: T;
+    meta: { errors: string[]; isTouched: boolean };
+  };
+  handleChange: (v: T) => void;
+  handleBlur: () => void;
+}