# react-component/field-form architecture

> Architecture diagram of the GitHub repository react-component/field-form, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/react-component/field-form
- Repository: https://github.com/react-component/field-form

## Overview

##### Project Type and Purpose
- This is an open‑source React form component library (`rc-field-form`) designed to provide a performant, hook‑based API for building and validating forms in React (and React Native). It is not a full‑stack app but a front‑end UI library distributed via npm.

##### File‑Structure Analysis
- Top‑level: configuration files (`.eslintrc.js`, `tsconfig.json`), build scripts (`.dumirc.ts`, `fatherrc.ts`), documentation (`docs/`), examples (`docs/examples/`), tests (`tests/`), source code (`src/`), and utility scripts.
- `src/`: the core modules:
- `Form.tsx` & `Field.tsx` & `List.tsx`: React components
- `useForm.ts` & `useWatch.ts`: custom hooks
- `*Context.tsx`: React Context providers for form state and field registration
- `utils/`: state‑ and validation‑helper functions (e.g., `validateUtil.ts`, `valueUtil.ts`, `asyncUtil.ts`)
- External dependency: `@rc-component/async-validator` for schema‑based validation.

##### Key Insights from README
- Emphasizes hook‑based form instance via `Form.useForm()`
- Context API under the hood to register fields, track state (touched, validating, errors)
- Validation orchestration returning Promises, removing legacy callback patterns
- Designed for React and React Native, with a small, focused API surface (`Form`, `Field`, `List`, `useForm`, `useWatch`)

##### Main Components
a. Form Instance & Hook Layer
- `useForm()` hook → returns `FormInstance` object (methods: getFieldsValue, validateFields, setFieldsValue, etc.)
b. Form Component Layer
- `<Form>` component wraps children in `<FormContext.Provider value={formInstance}>`
c. Field Component Layer
- `<Field>` registers itself on mount via `FormContext`
- Internally uses `<FieldContext.Provider>` to pass down meta (value, errors, onChange handlers)
d. Component Layer
- `<List>` builds on similar patterns to dynamically add/remove field arrays via `ListContext` and `ListOperations`
e. Watch Hook
- `useWatch()` consumes `FormContext` to subscribe to specific value changes
f. Utility Modules
- `validateUtil` & `asyncUtil`: validation orchestration
- `valueUtil` & `NameMap`: value access and manipulation by name paths

##### Relationships and Data Flow
- `useForm()` → initialises `FormInstance`
- `Form` consumes `FormInstance` → provides context to children
- `Field` reads context → calls `registerField()` → on events, calls `setFieldsValue()` on `FormInstance` → triggers context updates
- `validateFields()` uses `async-validator` via `validateUtil` → updates field errors in context → rerenders registered `Field` components
- `useWatch()` subscribes to context change events for specific field value(s)

##### Architectural Patterns and Principles
- Context + Hooks for decoupled state management
- Single source of truth (`FormInstance`)
- Declarative registration/unregistration of fields (mount/unmount)
- Promise‑based validation pipeline replacing callback patterns
- Separation of concerns: UI components (`Form`/`Field`), state orchestration (contexts/hooks), utilities (value, validation)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Public API Layer
    UF["useForm() Hook"]:::hook
    UW["useWatch() Hook"]:::hook
    FComp["<Form> Component"]:::component
    FieldComp["<Field> Component"]:::component
    ListComp["<List> Component"]:::component

    %% Instance & Context Layer
    FI["FormInstance"]:::instance
    FC["FormContext Provider"]:::component
    FdC["FieldContext Provider"]:::component
    LC["ListContext Provider"]:::component

    %% Utilities Layer
    VU["valueUtil"]:::util
    NM["NameMap"]:::util
    ValU["validateUtil"]:::util
    AU["asyncUtil"]:::util
    Msg["messages"]:::util
    TU["typeUtil"]:::util

    %% External Dependencies
    AsyncV["async-validator"]:::external

    %% Connections
    UF -->|"initializes"| FI
    FI -->|"provides instance to"| FC
    FComp -->|"consumes context"| FC
    FieldComp -->|"registerField()"| FC
    FieldComp -->|"wrapped by"| FdC
    ListComp -->|"wrapped by"| LC
    FC -->|"setFieldsValue()"| FI
    FI -->|"validateFields()"| ValU
    ValU -->|"uses schema from"| AsyncV
    FI -->|"async helpers"| AU
    FI -->|"value access"| VU
    FI -->|"name path management"| NM
    UW -->|"subscribes to"| FC
    Msg -->|"used by"| ValU
    TU -->|"TS helpers for"| VU

    %% Layer grouping
    subgraph "Public API"
      UF
      UW
      FComp
      FieldComp
      ListComp
    end

    subgraph "Instance & Context"
      FI
      FC
      FdC
      LC
    end

    subgraph "Utilities"
      VU
      NM
      ValU
      AU
      Msg
      TU
    end

    subgraph "External"
      AsyncV
    end

    %% Click Events
    click UF "https://github.com/react-component/field-form/blob/master/src/useForm.ts"
    click UW "https://github.com/react-component/field-form/blob/master/src/useWatch.ts"
    click FComp "https://github.com/react-component/field-form/blob/master/src/Form.tsx"
    click FieldComp "https://github.com/react-component/field-form/blob/master/src/Field.tsx"
    click ListComp "https://github.com/react-component/field-form/blob/master/src/List.tsx"
    click FC "https://github.com/react-component/field-form/blob/master/src/FormContext.tsx"
    click FdC "https://github.com/react-component/field-form/blob/master/src/FieldContext.ts"
    click LC "https://github.com/react-component/field-form/blob/master/src/ListContext.ts"
    click NM "https://github.com/react-component/field-form/blob/master/src/utils/NameMap.ts"
    click ValU "https://github.com/react-component/field-form/blob/master/src/utils/validateUtil.ts"
    click AU "https://github.com/react-component/field-form/blob/master/src/utils/asyncUtil.ts"
    click VU "https://github.com/react-component/field-form/blob/master/src/utils/valueUtil.ts"
    click Msg "https://github.com/react-component/field-form/blob/master/src/utils/messages.ts"
    click TU "https://github.com/react-component/field-form/blob/master/src/utils/typeUtil.ts"
    click FI "https://github.com/react-component/field-form/blob/master/src/interface.ts"

    %% Styles
    classDef hook fill:#e0f7fa,stroke:#00695c,stroke-width:1px
    classDef component fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef instance fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px
    classDef util fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#757575,stroke-width:1px
```
