npm package: @forgedevstack/forge-form
Description: Lightweight form management with built-in validation and DevTools for React, Vue, and Angular
Author: ForgeDevStack
Latest version: 1.0.0

# Forge Form

<p align="center">
  <strong>Lightweight form management with built-in validation and DevTools</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@forgedevstack/forge-form">
    <img src="https://img.shields.io/npm/v/@forgedevstack/forge-form.svg" alt="npm version" />
  </a>
  <a href="https://github.com/forgedevstack/forge-form/blob/main/LICENSE">
    <img src="https://img.shields.io/npm/l/@forgedevstack/forge-form.svg" alt="license" />
  </a>
</p>

---

## Features

- **Lightweight** — Under 4KB gzipped
- **Type-safe** — Full TypeScript support
- **Built-in Validators** — 15+ validators, no external dependencies
- **DevTools** — Inspect fields, validation, and logs in real-time
- **Framework Support** — React (Vue & Angular coming soon)
- **Zero Config** — Works out of the box

## Installation

```bash
npm install @forgedevstack/forge-form
```

## Quick Start

### 1. Wrap your form with FormProvider

```tsx
import { FormProvider } from '@forgedevstack/forge-form';

function App() {
  return (
    <FormProvider
      initialValues={{ email: '', password: '' }}
      onSubmit={(values) => console.log(values)}
    >
      <LoginForm />
    </FormProvider>
  );
}
```

### 2. Use fields with useField

```tsx
import { useField, useForm, Validators } from '@forgedevstack/forge-form';

function LoginForm() {
  const { handleSubmit } = useForm();
  
  const email = useField('email', {
    validators: [Validators.required(), Validators.email()],
  });
  
  const password = useField('password', {
    validators: [Validators.required(), Validators.minLength(8)],
  });

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <input {...email.inputProps} placeholder="Email" />
        {email.field.touched && !email.field.valid && (
          <span>{email.field.errors[0]?.message}</span>
        )}
      </div>
      
      <div>
        <input {...password.inputProps} type="password" placeholder="Password" />
        {password.field.touched && !password.field.valid && (
          <span>{password.field.errors[0]?.message}</span>
        )}
      </div>
      
      <button type="submit">Login</button>
    </form>
  );
}
```

### 3. Add DevTools (optional)

```tsx
import { ForgeFormDevTools } from '@forgedevstack/forge-form/devtools';

function App() {
  return (
    <FormProvider {...config}>
      <MyForm />
      <ForgeFormDevTools />
    </FormProvider>
  );
}
```

## Validators

All validators are built-in — no external dependencies:

```tsx
import { Validators } from '@forgedevstack/forge-form';

// Basic
Validators.required('Custom message')
Validators.email()
Validators.url()
Validators.phone()

// Numbers
Validators.number()
Validators.integer()
Validators.positive()
Validators.min(5)
Validators.max(100)

// Strings
Validators.minLength(3)
Validators.maxLength(50)
Validators.pattern(/^[A-Z]/)

// Advanced
Validators.match('confirmPassword')
Validators.oneOf(['admin', 'user'])
Validators.custom((value) => value !== 'forbidden')
Validators.compose(Validators.required(), Validators.email())
Validators.when((value) => value.length > 0, Validators.email())
```

## API Reference

### FormProvider Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `initialValues` | `object` | `{}` | Initial form values |
| `validateOnChange` | `boolean` | `true` | Validate on input change |
| `validateOnBlur` | `boolean` | `true` | Validate on field blur |
| `validateOnSubmit` | `boolean` | `true` | Validate before submit |
| `onSubmit` | `function` | - | Submit handler |
| `onError` | `function` | - | Error handler |
| `onReset` | `function` | - | Reset handler |

### useForm Return

```tsx
const { form, handleSubmit, handleReset } = useForm();

// form contains:
form.values        // Current values
form.errors        // Validation errors
form.valid         // Is form valid
form.dirty         // Has any field changed
form.touched       // Has any field been touched
form.submitting    // Is submitting
form.submitted     // Was submitted
form.submitCount   // Number of submit attempts
```

### useField Return

```tsx
const { field, actions, inputProps } = useField('email', options);

// field contains:
field.value        // Current value
field.valid        // Is valid
field.errors       // Validation errors
field.touched      // Has been touched
field.dirty        // Has changed
field.validating   // Is validating

// actions:
actions.setValue(value)
actions.setTouched(true)
actions.setError({ valid: false, message: 'Error' })
actions.clearErrors()
actions.validate()
actions.reset()

// inputProps for native inputs:
<input {...inputProps} />
```

## DevTools

The DevTools panel shows:

- **Fields tab** — All fields with their state (valid, touched, dirty)
- **Logs tab** — Real-time activity log (register, change, validate, submit)
- **Form stats** — Total fields, validity, submit count

```tsx
<ForgeFormDevTools
  enabled={true}
  position="bottom-right"
  maxLogs={100}
/>
```

## TypeScript

Full type inference:

```tsx
interface LoginForm {
  email: string;
  password: string;
}

const { form } = useForm<LoginForm>();
form.values.email // typed as string
```

## Part of ForgeStack

Forge Form is part of the [ForgeStack](https://forgedevstack.com) ecosystem:

- **Harbor** — Node.js backend framework
- **Synapse** — State management
- **Bear** — UI components
- **Forge Query** — Data fetching
- **Forge Form** — Form management

## License

MIT © [ForgeDevStack](https://forgedevstack.com)