# rn-form
URL: /docs/native/docyrus/form

Form-library-agnostic form wrapper that connects DocyField components to any state management library.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-form
```

## Overview

`DocyForm` is a form-library-agnostic wrapper that connects `DocyField*` components to any form state management library via the **adapter pattern**. You implement a `FormAdapter` interface for your chosen library (react-hook-form, TanStack Form, etc.), and `DocyForm` handles the wiring.

## Usage

### With react-hook-form

```tsx
import { DocyForm, DocyFormField } from '@/components/docyrus-native/form';
import { DocyFieldText } from '@/components/docyrus-native/form-fields/docy-field-text';
import { DocyFieldEmail } from '@/components/docyrus-native/form-fields/docy-field-email';

// Create adapter from your form library
const adapter = createReactHookFormAdapter({
  defaultValues: { name: '', email: '' },
  onSubmit: (data) => console.log(data),
});

      

      
    </>
  )}

```

### Compound Fields

For fields that manage multiple form values (e.g. `DocyFieldMoney` needs both amount and currency):

```tsx

```

## API Reference

### DocyForm

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `adapter` | `FormAdapter<T>` | — | **Required.** Form library adapter |
| `children` | `ReactNode \| (methods) => ReactNode` | — | Form content. Render-prop provides `handleSubmit` and `reset` |
| `className` | `string` | — | Container style |

### DocyFormField

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | — | **Required.** Field name in the form |
| `children` | `ReactElement` | — | **Required.** DocyField component to connect |
| `validations` | `DocyFieldValidationRule[]` | — | Additional validation rules |
| `defaultValue` | `unknown` | — | Default value for this field |
| `compoundFields` | `Record<string, string>` | — | Maps prop names to additional form field names |

### FormAdapter Interface

Implement this interface to plug in your form library:

| Method | Signature | Description |
|--------|-----------|-------------|
| `FormWrapper` | `(props: { children: ReactNode }) => ReactElement` | Wraps children with library-specific provider |
| `getValue` | `(name: string) => unknown` | Get current field value |
| `setValue` | `(name: string, value: unknown) => void` | Set field value programmatically |
| `getError` | `(name: string) => string \| undefined` | Get field error message |
| `getFieldProps` | `(name: string) => FormAdapterFieldProps` | Get props for a field (value, onChange, onBlur, error) |
| `handleSubmit` | `() => void \| Promise<void>` | Run validation and submit |
| `reset` | `(values?: Partial<T>) => void` | Reset form to defaults |
| `getValues` | `() => T` | Get all current form values |

## Hooks

| Hook | Returns | Description |
|------|---------|-------------|
| `useFormAdapter<T>()` | `FormAdapter<T>` | Access the form adapter from within DocyForm |
| `useSimpleFormAdapter<T>(options)` | `FormAdapter<T>` | Local-state adapter (no form library) |

### `useSimpleFormAdapter` options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `defaultValues` | `T` | required | Initial values |
| `onSubmit` | `(values: T) => void \| Promise<void>` | — | Called by `handleSubmit` once validation passes |
| `validations` | `Partial<Record<keyof T, string[]>>` | — | Validation tokens per field (`required`, `minLength:N`, `maxLength:N`, `pattern:RE`, `min:N`, `max:N`), enforced on submit with the shared token parser. Errors surface through `getError` / `getFieldProps().error` and clear when the field changes |
| `labels` | `Partial<Record<keyof T, string>>` | field name | Labels used in validation messages |

For schema-driven forms (layout sections, computed fields, actions) use [`useDynamicFormView`](/docs/native/hooks/use-dynamic-form-view) instead.

## Components

| Component | Description |
|-----------|-------------|
| `DocyForm` | Form wrapper with adapter context |
| `DocyFormField` | Connects a DocyField component to the form adapter |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyFormProps` | Props for DocyForm component |
| `DocyFormFieldProps` | Props for DocyFormField component |
| `FormAdapter` | Form library adapter interface |
| `FormAdapterFieldProps` | Field props returned by adapter (`{ name, value, onChange, onBlur, error }`) |