@mdxui/terminal 2.0.0

package/src/forms/types.ts

@@ -0,0 +1,476 @@
+/**
+ * @mdxui/terminal Form Integration Types
+ *
+ * TypeScript types for React Hook Form integration with terminal renderers.
+ * These types provide a bridge between RHF's form state management and the
+ * UINode-based rendering system.
+ *
+ * @packageDocumentation
+ */
+
+import type { z } from 'zod'
+
+// ============================================================================
+// Core Form Value Types
+// ============================================================================
+
+/**
+ * Base field value types supported by terminal form components.
+ *
+ * @remarks
+ * These represent the primitive values that can be stored in form fields.
+ * Compatible with RHF's FieldValues constraint.
+ */
+export type FieldValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | string[]
+  | FieldValue[]
+
+/**
+ * Generic form values type compatible with React Hook Form.
+ *
+ * @remarks
+ * This is the base constraint for all form value types.
+ * Equivalent to RHF's FieldValues type.
+ *
+ * @example
+ * ```tsx
+ * interface LoginFormValues extends FormValues {
+ *   email: string
+ *   password: string
+ *   rememberMe: boolean
+ * }
+ * ```
+ */
+export interface FormValues {
+  [key: string]: FieldValue | FormValues
+}
+
+// ============================================================================
+// Field Configuration Types
+// ============================================================================
+
+/**
+ * Configuration for a single form field.
+ *
+ * @remarks
+ * This interface represents the complete state and configuration of a form field,
+ * including validation state, UI state, and metadata. This maps directly to
+ * the props expected by the Field renderer.
+ *
+ * @typeParam T - The value type for this field (defaults to FieldValue)
+ */
+export interface FieldConfig<T extends FieldValue = FieldValue> {
+  /** Unique field name (used as form key) */
+  name: string
+
+  /** Display label for the field */
+  label?: string
+
+  /** Field input type */
+  type?: 'text' | 'email' | 'password' | 'number' | 'checkbox' | 'textarea' | 'select'
+
+  /** Current field value */
+  value?: T
+
+  /** Placeholder text when empty */
+  placeholder?: string
+
+  /** Whether the field is required */
+  required?: boolean
+
+  /** Validation error message */
+  error?: string
+
+  /** Whether the field has passed validation */
+  valid?: boolean
+
+  /** Whether the field is disabled */
+  disabled?: boolean
+
+  /** Whether the field is read-only */
+  readonly?: boolean
+
+  /** Helper text displayed below the field */
+  helperText?: string
+
+  /** Whether the field is currently focused */
+  focused?: boolean
+
+  /** Cursor position for text inputs (interactive tier) */
+  cursorPosition?: number
+
+  /** Selection start for text inputs (interactive tier) */
+  selectionStart?: number
+
+  /** Selection end for text inputs (interactive tier) */
+  selectionEnd?: number
+
+  /** Options for select fields */
+  options?: Array<{ label: string; value: string; disabled?: boolean }>
+}
+
+/**
+ * Form group configuration for organizing related fields.
+ *
+ * @remarks
+ * Groups allow organizing fields into logical sections with
+ * optional collapse functionality.
+ */
+export interface FieldGroup {
+  /** Group title */
+  title: string
+
+  /** Fields in this group */
+  fields: FieldConfig[]
+
+  /** Whether the group can be collapsed */
+  collapsible?: boolean
+
+  /** Whether the group is currently collapsed */
+  collapsed?: boolean
+}
+
+// ============================================================================
+// Form State Types
+// ============================================================================
+
+/**
+ * Complete form state configuration.
+ *
+ * @remarks
+ * This represents the full state of a form, including all fields,
+ * groups, validation state, and submission state. This maps directly
+ * to the props expected by the Form renderer.
+ *
+ * @typeParam T - The form values type
+ */
+export interface FormState<T extends FormValues = FormValues> {
+  /** Form title */
+  title?: string
+
+  /** Form description */
+  description?: string
+
+  /** Standalone fields (not in groups) */
+  fields?: FieldConfig[]
+
+  /** Grouped fields */
+  groups?: FieldGroup[]
+
+  /** Form-level error message */
+  error?: string
+
+  /** Form-level success message */
+  success?: string
+
+  /** Whether the form is currently loading/submitting */
+  loading?: boolean
+
+  /** Submit button label */
+  submitLabel?: string
+
+  /** Cancel button label */
+  cancelLabel?: string
+
+  /** Whether the submit button is disabled */
+  submitDisabled?: boolean
+
+  /** Submit button hotkey (interactive tier) */
+  submitHotkey?: string
+
+  /** Whether to show a border around the form */
+  border?: boolean
+
+  /** The current form values (for RHF integration) */
+  values?: T
+}
+
+// ============================================================================
+// React Hook Form Integration Types
+// ============================================================================
+
+/**
+ * RHF register function signature.
+ *
+ * @remarks
+ * This is a simplified version of RHF's UseFormRegister type,
+ * designed to work with the terminal renderer system.
+ */
+export type RegisterFn = (name: string, options?: {
+  required?: boolean | string
+  min?: number | { value: number; message: string }
+  max?: number | { value: number; message: string }
+  minLength?: number | { value: number; message: string }
+  maxLength?: number | { value: number; message: string }
+  pattern?: RegExp | { value: RegExp; message: string }
+  validate?: (value: FieldValue) => boolean | string | Promise<boolean | string>
+}) => {
+  name: string
+  onChange: (event: { target: { value: FieldValue } }) => void
+  onBlur: () => void
+  ref: (element: unknown) => void
+}
+
+/**
+ * RHF form state subset relevant to terminal rendering.
+ *
+ * @remarks
+ * This represents the subset of RHF's FormState that is relevant
+ * for rendering form UI in the terminal.
+ */
+export interface RHFFormState {
+  /** Whether the form is currently submitting */
+  isSubmitting: boolean
+
+  /** Whether the form has been submitted at least once */
+  isSubmitted: boolean
+
+  /** Whether the form is valid */
+  isValid: boolean
+
+  /** Whether any field has been modified */
+  isDirty: boolean
+
+  /** Field-level errors */
+  errors: Record<string, { message?: string; type?: string }>
+
+  /** Fields that have been touched (focused and blurred) */
+  touchedFields: Record<string, boolean>
+
+  /** Fields that have been modified */
+  dirtyFields: Record<string, boolean>
+}
+
+/**
+ * Configuration for connecting RHF to terminal form renderer.
+ *
+ * @remarks
+ * This interface provides the bridge between RHF's hooks and
+ * the terminal form rendering system.
+ *
+ * @typeParam T - The form values type
+ */
+export interface RHFFormConfig<T extends FormValues = FormValues> {
+  /** RHF register function */
+  register: RegisterFn
+
+  /** RHF form state */
+  formState: RHFFormState
+
+  /** RHF getValues function */
+  getValues: () => T
+
+  /** RHF setValue function */
+  setValue: (name: keyof T, value: FieldValue) => void
+
+  /** RHF trigger function (validate field) */
+  trigger: (name?: keyof T | (keyof T)[]) => Promise<boolean>
+
+  /** RHF handleSubmit function */
+  handleSubmit: (onSubmit: (data: T) => void | Promise<void>) => (e?: Event) => Promise<void>
+
+  /** RHF reset function */
+  reset: (values?: Partial<T>) => void
+}
+
+// ============================================================================
+// Select/Search Component Types
+// ============================================================================
+
+/**
+ * Select field option configuration.
+ */
+export interface SelectOption<T = string> {
+  /** Display label */
+  label: string
+
+  /** Value when selected */
+  value: T
+
+  /** Whether the option is disabled */
+  disabled?: boolean
+
+  /** Optional description */
+  description?: string
+}
+
+/**
+ * Select field state configuration.
+ *
+ * @remarks
+ * This maps to the props expected by the Select renderer.
+ */
+export interface SelectState<T = string> {
+  /** Available options */
+  options: SelectOption<T>[]
+
+  /** Currently selected value(s) */
+  value?: T | T[]
+
+  /** Field label */
+  label?: string
+
+  /** Placeholder text */
+  placeholder?: string
+
+  /** Whether the field is required */
+  required?: boolean
+
+  /** Validation error message */
+  error?: string
+
+  /** Whether the field has passed validation */
+  valid?: boolean
+
+  /** Whether the field is disabled */
+  disabled?: boolean
+
+  /** Whether the dropdown is open */
+  open?: boolean
+
+  /** Whether multiple selection is allowed */
+  multiple?: boolean
+
+  /** Currently highlighted option index */
+  highlightedIndex?: number
+
+  /** Whether the select is searchable */
+  searchable?: boolean
+
+  /** Current search query */
+  searchValue?: string
+
+  /** Filtered options (when searchable) */
+  filteredOptions?: SelectOption<T>[]
+
+  /** Whether options are loading */
+  loading?: boolean
+}
+
+/**
+ * Search field suggestion configuration.
+ */
+export interface SearchSuggestion {
+  /** Display label */
+  label: string
+
+  /** Value when selected */
+  value: string
+
+  /** Optional description */
+  description?: string
+
+  /** Optional icon identifier */
+  icon?: string
+}
+
+/**
+ * Search field state configuration.
+ *
+ * @remarks
+ * This maps to the props expected by the Search renderer.
+ */
+export interface SearchState {
+  /** Current search query */
+  value: string
+
+  /** Placeholder text */
+  placeholder?: string
+
+  /** Field label */
+  label?: string
+
+  /** Whether the field is disabled */
+  disabled?: boolean
+
+  /** Whether results are loading */
+  loading?: boolean
+
+  /** Validation error message */
+  error?: string
+
+  /** Whether the field is focused */
+  focused?: boolean
+
+  /** Cursor position (interactive tier) */
+  cursorPosition?: number
+
+  /** Available suggestions */
+  suggestions?: SearchSuggestion[] | null
+
+  /** Whether to show suggestions dropdown */
+  showSuggestions?: boolean
+
+  /** Currently highlighted suggestion index */
+  highlightedIndex?: number
+
+  /** Maximum suggestions to show */
+  maxSuggestions?: number
+
+  /** Whether to highlight matching text */
+  highlightMatches?: boolean
+
+  /** Whether user is currently typing (debounce indicator) */
+  isTyping?: boolean
+}
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+/**
+ * Extracts the inferred type from a Zod schema.
+ *
+ * @remarks
+ * Use this to derive TypeScript types from your Zod validation schemas.
+ *
+ * @example
+ * ```tsx
+ * const loginSchema = z.object({
+ *   email: z.string().email(),
+ *   password: z.string().min(8),
+ * })
+ *
+ * type LoginForm = InferFormValues<typeof loginSchema>
+ * // { email: string; password: string }
+ * ```
+ */
+export type InferFormValues<T extends z.ZodType> = z.infer<T>
+
+/**
+ * Converts RHF form state to terminal FormState format.
+ *
+ * @remarks
+ * This type represents a function that transforms RHF's internal
+ * state representation to the format expected by terminal renderers.
+ */
+export type FormStateConverter<T extends FormValues = FormValues> = (
+  rhfConfig: RHFFormConfig<T>,
+  fieldConfigs: FieldConfig[]
+) => FormState<T>
+
+/**
+ * Field registration options for RHF integration.
+ */
+export interface FieldRegistration {
+  /** Field name */
+  name: string
+
+  /** Validation rules */
+  rules?: {
+    required?: boolean | string
+    min?: number | { value: number; message: string }
+    max?: number | { value: number; message: string }
+    minLength?: number | { value: number; message: string }
+    maxLength?: number | { value: number; message: string }
+    pattern?: RegExp | { value: RegExp; message: string }
+  }
+
+  /** Default value */
+  defaultValue?: FieldValue
+}