metabuilder/hooks/EXPORT_GUIDE.md

Form Validation Hooks - Export & Usage Guide

Location

All hooks are located in /hooks/ directory at project root.

Available Hooks

1. useValidation.ts - Schema-based form validation
2. useInput.ts - Text input state management
3. useCheckbox.ts - Checkbox state management (single/multi)
4. useSelect.ts - Select dropdown state (single/multi)
5. useFieldArray.ts - Dynamic form field arrays

Import Methods

Method 1: Direct Imports (Recommended)

import { useValidation } from '@/hooks/useValidation'
import { useInput } from '@/hooks/useInput'
import { useCheckbox } from '@/hooks/useCheckbox'
import { useSelect } from '@/hooks/useSelect'
import { useFieldArray } from '@/hooks/useFieldArray'

Method 2: Named Exports (if configured in index)

import {
  useValidation,
  useInput,
  useCheckbox,
  useSelect,
  useFieldArray,
  type ValidationSchema,
  type ValidationErrors,
  type SelectOption,
  type FormField
} from '@/hooks'

Method 3: Wildcard Import

import * as hooks from '@/hooks/useValidation'
const { useValidation } = hooks

Type Exports

Each hook also exports its types:

// useValidation
export type ValidationSchema<T>
export type ValidationErrors<T>

// useSelect
export interface SelectOption<T>

// useFieldArray
export interface FormField<T>

Module Resolution

The hooks work with TypeScript path aliases:

• @/hooks/useValidation - Full path import
• @/hooks/useInput - Full path import
• etc.

Ensure your tsconfig.json or jsconfig.json has:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

React Requirements

All hooks require:

• React 16.8+ (for hooks support)
• React 18+ (recommended for concurrent features)

Dependencies:

• react - Core
• react-redux (optional) - For integration with Redux
• nanoid - Required by useFieldArray for unique IDs

File Summary

File	Size	Status	Exports
useValidation.ts	5.6 KB	Production	useValidation, ValidationSchema, ValidationErrors
useInput.ts	4.6 KB	Production	useInput, UseInputReturn
useCheckbox.ts	9.9 KB	Production	useCheckbox, UseCheckboxSingleReturn, UseCheckboxMultiReturn
useSelect.ts	11.2 KB	Production	useSelect, SelectOption, UseSelectSingleReturn, UseSelectMultiReturn
useFieldArray.ts	10.6 KB	Production	useFieldArray, FormField, UseFieldArrayReturn

Feature Matrix

Feature	useValidation	useInput	useCheckbox	useSelect	useFieldArray
State tracking	✓	✓	✓	✓	✓
Dirty tracking	-	✓	✓	✓	✓
Touched tracking	-	✓	✓	✓	✓
Error handling	✓	✓	✓	✓	✓
Validation	✓	✓	✓	✓	✓
Search filtering	-	-	-	✓	-
Multi-value support	-	-	✓	✓	✓
Array operations	-	-	-	-	✓
Min/Max constraints	-	-	-	-	✓
Group state	-	-	✓	✓	✓

Usage in Next.js

For Next.js projects, use 'use client' directive:

'use client'

import { useInput } from '@/hooks/useInput'

export const MyComponent = () => {
  const email = useInput('')
  return <input {...email.handlers.onChange} />
}

API Stability

All hooks follow semantic versioning:

• Stable: All 5 hooks are production-ready
• API version: 1.0.0+
• Breaking changes: Will bump major version

Documentation

• FORM_VALIDATION_HOOKS.md - Complete API reference
• QUICK_REFERENCE.md - Quick start guide with examples
• EXPORT_GUIDE.md - This file

Common Issues

Issue: Import path not found

Solution: Check tsconfig paths configuration

Issue: Type errors with generics

Solution: Explicitly type the hook:

const input = useInput<string>('', options)

Issue: nanoid not installed

Solution: npm install nanoid (required by useFieldArray)

Testing

All hooks are designed to be testable:

import { render, screen, fireEvent } from '@testing-library/react'
import { useInput } from '@/hooks/useInput'

const TestComponent = () => {
  const input = useInput('')
  return <input {...input.handlers.onChange} />
}

test('tracks dirty state', () => {
  const { rerender } = render(<TestComponent />)
  const input = screen.getByRole('textbox')
  
  fireEvent.change(input, { target: { value: 'test' } })
  // Test isDirty state
})

Performance Notes

All hooks are optimized with:

• useCallback for handler memoization
• Conditional state updates
• Efficient error state management
• No unnecessary re-renders

Browser Support

All hooks work in:

• Chrome 70+
• Firefox 63+
• Safari 12+
• Edge 79+

Future Enhancements

Potential additions:

• Async validation support
• Debounced validation
• Cross-field validation helpers
• Form context provider
• Redux integration helpers

Contributing

When modifying hooks:

1. Update types in the hook file
2. Update tests
3. Update documentation
4. Maintain backward compatibility
5. Follow existing code style

License

Same as main project