@matthew.ngo/reform/src/docs/documentations.md

A flexible and powerful React form management library with advanced validation, state observation, and multi-group support

# Reform API Documentation

## Table of Contents
- [Introduction](#introduction)
- [Core Concepts](#core-concepts)
- [Getting Started](#getting-started)
- [API Reference](#api-reference)
  - [useReform Hook](#usereform-hook)
  - [Form Groups](#form-groups)
  - [Field Management](#field-management)
  - [Validation](#validation)
  - [Error Handling](#error-handling)
  - [Form State Management](#form-state-management)
  - [Advanced Features](#advanced-features)
- [Integration Guides](#integration-guides)
- [Examples](#examples)
- [Best Practices](#best-practices)

## Introduction

Reform is a powerful form management library for React applications that provides a flexible and type-safe way to handle complex forms with multiple groups, validation, and advanced features.

Reform simplifies the creation and management of complex forms by providing:
- Type-safe form handling with TypeScript
- Support for form groups and nested data structures
- Comprehensive validation system with Yup integration
- Advanced error handling and custom error renderers
- Form state persistence and auto-save functionality
- Multi-step form wizards with step validation
- Conditional fields and dynamic validation rules

## Core Concepts

### Form Groups

Reform organizes form data into groups, allowing you to manage collections of related data. Each group contains:
- A unique identifier
- Form data of type T
- Metadata for tracking state

### Field Paths

Reform uses a type-safe approach to field paths, ensuring that you can only reference valid fields in your form data structure.

### Validation

Reform provides multiple validation strategies:
- Schema-based validation with Yup
- Dynamic validation rules based on field values
- Context-aware validation that can access other form data

### Error Handling

Reform includes a comprehensive error handling system with:
- Custom error renderers
- Error transformation
- Error boundaries for form components

## Getting Started

### Installation

```bash
npm install @reform/core
# or
yarn add @reform/core
```

### Basic Usage

```tsx
import { useReform } from '@reform/core';
import * as yup from 'yup';

// Define your form data type
type UserForm = {
  name: string;
  email: string;
  age: number;
};

// Create a validation schema
const userSchema = yup.object({
  name: yup.string().required('Name is required'),
  email: yup.string().email('Invalid email').required('Email is required'),
  age: yup.number().min(18, 'Must be at least 18 years old')
});

// Use the Reform hook
const UserFormComponent = () => {
  const form = useReform<UserForm>({
    defaultData: { name: '', email: '', age: 0 },
    minGroups: 1,
    groupSchema: userSchema
  });

  const handleSubmit = form.formMethods.handleSubmit((data) => {
    console.log('Form submitted:', data);
  });

  return (
    <form onSubmit={handleSubmit}>
      {form.getGroups().map((group, index) => (
        <div key={group.id}>
          <input
            {...form.register(index, 'name')}
            placeholder="Name"
          />
          {form.getFieldError(index, 'name') && (
            <p>{form.getFieldError(index, 'name')}</p>
          )}
          
          <input
            {...form.register(index, 'email')}
            placeholder="Email"
          />
          {form.getFieldError(index, 'email') && (
            <p>{form.getFieldError(index, 'email')}</p>
          )}
          
          <input
            type="number"
            {...form.register(index, 'age')}
            placeholder="Age"
          />
          {form.getFieldError(index, 'age') && (
            <p>{form.getFieldError(index, 'age')}</p>
          )}
        </div>
      ))}
      
      <button type="submit">Submit</button>
    </form>
  );
};