@mdxui/terminal 2.0.0

package/src/forms/converters.ts

@@ -0,0 +1,512 @@
+/**
+ * @mdxui/terminal Form Converters
+ *
+ * Utility functions for converting between React Hook Form state
+ * and terminal UINode props format.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  FormValues,
+  FieldConfig,
+  FieldGroup,
+  FormState,
+  RHFFormState,
+  RHFFormConfig,
+  SelectState,
+  SelectOption,
+  SearchState,
+  FieldValue,
+} from './types'
+import type { UINode } from '../core/types'
+
+// ============================================================================
+// Form State Converters
+// ============================================================================
+
+/**
+ * Converts RHF form state and field configurations to terminal FormState.
+ *
+ * @remarks
+ * This function bridges React Hook Form's state representation with
+ * the terminal form renderer's expected props format.
+ *
+ * @param rhfState - RHF form state from useForm hook
+ * @param fields - Array of field configurations
+ * @param options - Additional form options
+ * @returns FormState compatible with terminal Form renderer
+ *
+ * @example
+ * ```tsx
+ * const { formState, register, getValues } = useForm<LoginForm>()
+ *
+ * const terminalFormState = convertRHFToFormState(
+ *   formState,
+ *   [
+ *     { name: 'email', label: 'Email', type: 'email', required: true },
+ *     { name: 'password', label: 'Password', type: 'password', required: true },
+ *   ],
+ *   {
+ *     title: 'Login',
+ *     submitLabel: 'Sign In',
+ *     values: getValues(),
+ *   }
+ * )
+ * ```
+ */
+export function convertRHFToFormState<T extends FormValues>(
+  rhfState: RHFFormState,
+  fields: FieldConfig[],
+  options?: {
+    title?: string
+    description?: string
+    submitLabel?: string
+    cancelLabel?: string
+    submitHotkey?: string
+    border?: boolean
+    groups?: FieldGroup[]
+    values?: T
+  }
+): FormState<T> {
+  // Merge field configs with RHF errors and touched state
+  const enhancedFields = fields.map((field) => {
+    const error = rhfState.errors[field.name]
+    const isTouched = rhfState.touchedFields[field.name]
+    const isDirty = rhfState.dirtyFields[field.name]
+    const value = options?.values?.[field.name as keyof T] as FieldValue | undefined
+
+    return {
+      ...field,
+      value: value ?? field.value,
+      error: error?.message ?? field.error,
+      valid: isTouched && !error && field.required ? true : field.valid,
+      // Mark as valid if touched without error and was required
+    }
+  })
+
+  // Process groups if provided
+  const enhancedGroups = options?.groups?.map((group) => ({
+    ...group,
+    fields: group.fields.map((field) => {
+      const error = rhfState.errors[field.name]
+      const isTouched = rhfState.touchedFields[field.name]
+      const value = options?.values?.[field.name as keyof T] as FieldValue | undefined
+
+      return {
+        ...field,
+        value: value ?? field.value,
+        error: error?.message ?? field.error,
+        valid: isTouched && !error && field.required ? true : field.valid,
+      }
+    }),
+  }))
+
+  return {
+    title: options?.title,
+    description: options?.description,
+    fields: enhancedFields,
+    groups: enhancedGroups,
+    loading: rhfState.isSubmitting,
+    submitLabel: options?.submitLabel,
+    cancelLabel: options?.cancelLabel,
+    submitDisabled: !rhfState.isValid || rhfState.isSubmitting,
+    submitHotkey: options?.submitHotkey,
+    border: options?.border,
+    values: options?.values,
+  }
+}
+
+/**
+ * Converts field configurations to UINode format for Form renderer.
+ *
+ * @param formState - Terminal FormState configuration
+ * @returns UINode for Form component
+ *
+ * @example
+ * ```tsx
+ * const formNode = formStateToUINode({
+ *   title: 'Contact Us',
+ *   fields: [
+ *     { name: 'email', label: 'Email', type: 'email' },
+ *     { name: 'message', label: 'Message', type: 'textarea' },
+ *   ],
+ *   submitLabel: 'Send',
+ * })
+ *
+ * const rendered = renderForm(formNode, ctx)
+ * ```
+ */
+export function formStateToUINode<T extends FormValues>(
+  formState: FormState<T>
+): UINode {
+  return {
+    type: 'form',
+    props: {
+      title: formState.title,
+      description: formState.description,
+      fields: formState.fields,
+      groups: formState.groups,
+      error: formState.error,
+      success: formState.success,
+      loading: formState.loading,
+      submitLabel: formState.submitLabel,
+      cancelLabel: formState.cancelLabel,
+      submitDisabled: formState.submitDisabled,
+      submitHotkey: formState.submitHotkey,
+      border: formState.border,
+    },
+  }
+}
+
+// ============================================================================
+// Field Converters
+// ============================================================================
+
+/**
+ * Converts a single field configuration to UINode format.
+ *
+ * @param field - Field configuration
+ * @returns UINode for Field component
+ */
+export function fieldConfigToUINode(field: FieldConfig): UINode {
+  return {
+    type: 'field',
+    props: {
+      name: field.name,
+      label: field.label,
+      type: field.type,
+      value: field.value,
+      placeholder: field.placeholder,
+      required: field.required,
+      error: field.error,
+      valid: field.valid,
+      disabled: field.disabled,
+      readonly: field.readonly,
+      helperText: field.helperText,
+      focused: field.focused,
+      cursorPosition: field.cursorPosition,
+      selectionStart: field.selectionStart,
+      selectionEnd: field.selectionEnd,
+    },
+  }
+}
+
+/**
+ * Creates a field configuration from RHF register result.
+ *
+ * @param name - Field name
+ * @param registerResult - Result from RHF register function
+ * @param options - Additional field options
+ * @returns FieldConfig for terminal rendering
+ */
+export function createFieldFromRegister(
+  name: string,
+  registerResult: { name: string },
+  options?: Omit<FieldConfig, 'name'>
+): FieldConfig {
+  return {
+    name: registerResult.name,
+    label: options?.label ?? name.charAt(0).toUpperCase() + name.slice(1),
+    type: options?.type ?? 'text',
+    placeholder: options?.placeholder,
+    required: options?.required,
+    helperText: options?.helperText,
+    disabled: options?.disabled,
+    readonly: options?.readonly,
+  }
+}
+
+// ============================================================================
+// Select Converters
+// ============================================================================
+
+/**
+ * Converts select state to UINode format.
+ *
+ * @param selectState - Select component state
+ * @returns UINode for Select component
+ */
+export function selectStateToUINode<T = string>(
+  selectState: SelectState<T>
+): UINode {
+  return {
+    type: 'select',
+    props: {
+      options: selectState.options,
+      value: selectState.value,
+      label: selectState.label,
+      placeholder: selectState.placeholder,
+      required: selectState.required,
+      error: selectState.error,
+      valid: selectState.valid,
+      disabled: selectState.disabled,
+      open: selectState.open ?? true,
+      multiple: selectState.multiple,
+      highlightedIndex: selectState.highlightedIndex ?? -1,
+      searchable: selectState.searchable,
+      searchValue: selectState.searchValue,
+      filteredOptions: selectState.filteredOptions,
+      loading: selectState.loading,
+    },
+  }
+}
+
+/**
+ * Creates a select field configuration for RHF Controller integration.
+ *
+ * @param name - Field name
+ * @param options - Select options
+ * @param fieldOptions - Additional field options
+ * @returns SelectState for terminal rendering
+ *
+ * @example
+ * ```tsx
+ * // With RHF Controller
+ * <Controller
+ *   name="country"
+ *   control={control}
+ *   render={({ field, fieldState }) => {
+ *     const selectState = createSelectForController(
+ *       'country',
+ *       [
+ *         { label: 'United States', value: 'us' },
+ *         { label: 'Canada', value: 'ca' },
+ *       ],
+ *       {
+ *         value: field.value,
+ *         error: fieldState.error?.message,
+ *       }
+ *     )
+ *     const node = selectStateToUINode(selectState)
+ *     return renderSelect(node, ctx)
+ *   }}
+ * />
+ * ```
+ */
+export function createSelectForController<T = string>(
+  name: string,
+  options: SelectOption<T>[],
+  fieldOptions?: {
+    value?: T | T[]
+    error?: string
+    label?: string
+    placeholder?: string
+    required?: boolean
+    disabled?: boolean
+    multiple?: boolean
+    searchable?: boolean
+  }
+): SelectState<T> {
+  return {
+    options,
+    value: fieldOptions?.value,
+    label: fieldOptions?.label ?? name.charAt(0).toUpperCase() + name.slice(1),
+    placeholder: fieldOptions?.placeholder ?? `Select ${name}...`,
+    required: fieldOptions?.required,
+    error: fieldOptions?.error,
+    disabled: fieldOptions?.disabled,
+    multiple: fieldOptions?.multiple,
+    searchable: fieldOptions?.searchable,
+    open: true,
+    highlightedIndex: -1,
+  }
+}
+
+// ============================================================================
+// Search Converters
+// ============================================================================
+
+/**
+ * Converts search state to UINode format.
+ *
+ * @param searchState - Search component state
+ * @returns UINode for Search component
+ */
+export function searchStateToUINode(searchState: SearchState): UINode {
+  return {
+    type: 'search',
+    props: {
+      value: searchState.value,
+      placeholder: searchState.placeholder,
+      label: searchState.label,
+      disabled: searchState.disabled,
+      loading: searchState.loading,
+      error: searchState.error,
+      focused: searchState.focused,
+      cursorPosition: searchState.cursorPosition,
+      suggestions: searchState.suggestions,
+      showSuggestions: searchState.showSuggestions,
+      highlightedIndex: searchState.highlightedIndex ?? -1,
+      maxSuggestions: searchState.maxSuggestions ?? 10,
+      highlightMatches: searchState.highlightMatches,
+      isTyping: searchState.isTyping,
+    },
+  }
+}
+
+/**
+ * Creates a debounced search state handler.
+ *
+ * @param onSearch - Callback when search should be executed
+ * @param delay - Debounce delay in milliseconds (default: 300)
+ * @returns Object with handlers for search input
+ *
+ * @example
+ * ```tsx
+ * const { handleChange, handleFocus, handleBlur, state } = createDebouncedSearch(
+ *   async (query) => {
+ *     const results = await fetchSuggestions(query)
+ *     return results.map(r => ({ label: r.name, value: r.id }))
+ *   }
+ * )
+ *
+ * // Use with RHF Controller
+ * <Controller
+ *   name="search"
+ *   control={control}
+ *   render={({ field }) => {
+ *     const searchNode = searchStateToUINode({
+ *       value: field.value,
+ *       ...state,
+ *     })
+ *     return renderSearch(searchNode, ctx)
+ *   }}
+ * />
+ * ```
+ */
+export function createDebouncedSearch(
+  onSearch: (query: string) => Promise<{ label: string; value: string }[]> | { label: string; value: string }[],
+  delay: number = 300
+): {
+  handleChange: (value: string) => void
+  handleFocus: () => void
+  handleBlur: () => void
+  getState: () => Pick<SearchState, 'suggestions' | 'showSuggestions' | 'loading' | 'isTyping'>
+} {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null
+  let currentState: Pick<SearchState, 'suggestions' | 'showSuggestions' | 'loading' | 'isTyping'> = {
+    suggestions: null,
+    showSuggestions: false,
+    loading: false,
+    isTyping: false,
+  }
+
+  const handleChange = (value: string) => {
+    // Clear existing timeout
+    if (timeoutId) {
+      clearTimeout(timeoutId)
+    }
+
+    // Set typing state
+    currentState = {
+      ...currentState,
+      isTyping: true,
+      showSuggestions: true,
+    }
+
+    // Debounce the search
+    timeoutId = setTimeout(async () => {
+      currentState = {
+        ...currentState,
+        isTyping: false,
+        loading: true,
+      }
+
+      try {
+        const results = await onSearch(value)
+        currentState = {
+          ...currentState,
+          suggestions: results,
+          loading: false,
+        }
+      } catch {
+        currentState = {
+          ...currentState,
+          suggestions: [],
+          loading: false,
+        }
+      }
+    }, delay)
+  }
+
+  const handleFocus = () => {
+    currentState = {
+      ...currentState,
+      showSuggestions: true,
+    }
+  }
+
+  const handleBlur = () => {
+    // Delay hiding to allow click on suggestion
+    setTimeout(() => {
+      currentState = {
+        ...currentState,
+        showSuggestions: false,
+      }
+    }, 200)
+  }
+
+  const getState = () => ({ ...currentState })
+
+  return { handleChange, handleFocus, handleBlur, getState }
+}
+
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+
+/**
+ * Extracts field errors from RHF form state in a format suitable for rendering.
+ *
+ * @param errors - RHF errors object
+ * @param fieldNames - Optional list of field names to extract
+ * @returns Record of field names to error messages
+ */
+export function extractFieldErrors(
+  errors: Record<string, { message?: string }>,
+  fieldNames?: string[]
+): Record<string, string> {
+  const result: Record<string, string> = {}
+
+  const names = fieldNames ?? Object.keys(errors)
+  for (const name of names) {
+    const error = errors[name]
+    if (error?.message) {
+      result[name] = error.message
+    }
+  }
+
+  return result
+}
+
+/**
+ * Checks if a form has any errors.
+ *
+ * @param errors - RHF errors object
+ * @returns True if there are any errors
+ */
+export function hasFormErrors(errors: Record<string, unknown>): boolean {
+  return Object.keys(errors).length > 0
+}
+
+/**
+ * Gets the first field with an error.
+ *
+ * @param errors - RHF errors object
+ * @param fieldOrder - Optional field order to check
+ * @returns Name of first field with error, or undefined
+ */
+export function getFirstErrorField(
+  errors: Record<string, unknown>,
+  fieldOrder?: string[]
+): string | undefined {
+  if (fieldOrder) {
+    for (const name of fieldOrder) {
+      if (errors[name]) {
+        return name
+      }
+    }
+  }
+  return Object.keys(errors)[0]
+}

package/src/forms/index.ts

@@ -0,0 +1,133 @@
+/**
+ * @mdxui/terminal Forms Module
+ *
+ * React Hook Form integration for terminal form components.
+ *
+ * This module provides:
+ * - TypeScript types for form values and field configurations
+ * - Zod schemas for validation (compatible with @hookform/resolvers/zod)
+ * - Converters between RHF state and terminal UINode format
+ * - Helper utilities for form state management
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```tsx
+ * import { useForm } from 'react-hook-form'
+ * import { zodResolver } from '@hookform/resolvers/zod'
+ * import {
+ *   createLoginSchema,
+ *   convertRHFToFormState,
+ *   formStateToUINode,
+ * } from '@mdxui/terminal/forms'
+ * import { renderForm } from '@mdxui/terminal'
+ *
+ * // Create form with Zod validation
+ * const loginSchema = createLoginSchema({ rememberMe: true })
+ * type LoginForm = z.infer<typeof loginSchema>
+ *
+ * const { register, formState, getValues, handleSubmit } = useForm<LoginForm>({
+ *   resolver: zodResolver(loginSchema),
+ * })
+ *
+ * // Convert to terminal-renderable format
+ * const terminalState = convertRHFToFormState(
+ *   formState,
+ *   [
+ *     { name: 'email', label: 'Email', type: 'email', required: true },
+ *     { name: 'password', label: 'Password', type: 'password', required: true },
+ *     { name: 'rememberMe', label: 'Remember me', type: 'checkbox' },
+ *   ],
+ *   {
+ *     title: 'Sign In',
+ *     submitLabel: 'Login',
+ *     values: getValues(),
+ *   }
+ * )
+ *
+ * // Render to terminal
+ * const formNode = formStateToUINode(terminalState)
+ * const output = renderForm(formNode, ctx)
+ * ```
+ */
+
+// Types
+export type {
+  FieldValue,
+  FormValues,
+  FieldConfig,
+  FieldGroup,
+  FormState,
+  RegisterFn,
+  RHFFormState,
+  RHFFormConfig,
+  SelectOption,
+  SelectState,
+  SearchSuggestion,
+  SearchState,
+  InferFormValues,
+  FormStateConverter,
+  FieldRegistration,
+} from './types'
+
+// Schemas
+export {
+  // Base schemas
+  FieldValueSchema,
+  SelectOptionSchema,
+  SearchSuggestionSchema,
+  FieldTypeSchema,
+  FieldConfigSchema,
+  FieldGroupSchema,
+  FormStateSchema,
+  SelectStateSchema,
+  SearchStateSchema,
+
+  // Common validation schemas
+  EmailSchema,
+  PasswordSchema,
+  SimplePasswordSchema,
+  UsernameSchema,
+  UrlSchema,
+  PhoneSchema,
+
+  // Schema builders
+  createLoginSchema,
+  createRegistrationSchema,
+  createContactSchema,
+  createProfileSchema,
+  createSettingsSchema,
+} from './schemas'
+
+// Re-export schema-derived types (alternative import path)
+export type {
+  LoginFormValues,
+  RegistrationFormValues,
+  ContactFormValues,
+  ProfileFormValues,
+  SettingsFormValues,
+} from './schemas'
+
+// Converters
+export {
+  // Form converters
+  convertRHFToFormState,
+  formStateToUINode,
+
+  // Field converters
+  fieldConfigToUINode,
+  createFieldFromRegister,
+
+  // Select converters
+  selectStateToUINode,
+  createSelectForController,
+
+  // Search converters
+  searchStateToUINode,
+  createDebouncedSearch,
+
+  // Validation helpers
+  extractFieldErrors,
+  hasFormErrors,
+  getFirstErrorField,
+} from './converters'