npm package: @silentcoderhi/superform
Description: A lightning-fast, TypeScript-first validation and form state management library for React.
Author: Hussnain
Latest version: 1.1.0

# SuperForm 🚀

A lightning-fast, TypeScript-first validation and form state management library for React.

SuperForm provides a Zod-like schema builder with a powerful validation engine, seamlessly integrated with React hooks to manage form state, errors, and submission with ease.

## ✨ Features

- **TypeScript-First**: Full type inference from your schemas. No more manual type definitions.
- **Zod-Like Syntax**: Intuitive and chainable schema builder.
- **Comprehensive Validation**: Supports strings, numbers, booleans, objects, and arrays.
- **Async Validation**: Built-in support for asynchronous rules (e.g., checking if a username is taken).
- **React Integration**: Lightweight hooks (`useForm`, `useField`) for effortless form state management.
- **Zero Dependencies**: Lightweight and optimized for performance.

## 📦 Installation

```bash
# Using npm
npm install @silentcoderhi/superform

# Using yarn
yarn add @silentcoderhi/superform
```

## 🚀 Quick Start

### 1. Define your Schema

```typescript
import { superform } from "@silentcoderhi/superform/core";

const loginSchema = superform.object({
  email: superform.string().email().min(5),
  password: superform.string().min(8),
  rememberMe: superform.boolean().true(),
});

// Infer types automatically!
type LoginData = typeof loginSchema._type;
```

### 2. Use in React

```tsx
import { useForm } from "@silentcoderhi/superform/react";
import { loginSchema } from "./schema";

function LoginForm() {
  const { register, handleSubmit, errors, isSubmitting } = useForm(loginSchema);

  const onSubmit = (data) => {
    console.log("Form submitted:", data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <input {...register("email")} placeholder="Email" />
        {errors.email && <span>{errors.email}</span>}
      </div>

      <div>
        <input type="password" {...register("password")} placeholder="Password" />
        {errors.password && <span>{errors.password}</span>}
      </div>

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Logging in..." : "Login"}
      </button>
    </form>
  );
}
```

## 🛠 API Reference

### Schema Builder (`superform`)

#### String Schema
```typescript
superform.string()
  .email()           // Must be a valid email
  .min(length)       // Minimum characters
  .max(length)       // Maximum characters
  .async(asyncFn)    // Custom async validation
```

#### Number Schema
```typescript
superform.number()
  .min(value)        // Minimum value
  .max(value)        // Maximum value
  .async(asyncFn)    // Custom async validation
```

#### Modifier Methods (All Schemas)
```typescript
superform.string().optional() // Returns string | undefined
superform.number().nullable() // Returns number | null
superform.string().refine(v => v !== 'admin', { message: 'Reserved' })
superform.string().transform(v => v.trim().toLowerCase())
```

#### Enums, Literals, and Unions
```typescript
superform.enum(['draft', 'published']) // Inferred as 'draft' | 'published'
superform.literal('ADMIN')             // Strictly 'ADMIN'
superform.union(superform.string(), superform.number()) // string | number
```

#### Array Schema
```typescript
superform.array(superform.string())  // Array of strings
  .min(length)       // Minimum elements
  .max(length)       // Maximum elements
```

#### Object Schema
```typescript
superform.object({
  username: superform.string(),
  age: superform.number(),
})
```

### React Hooks

#### `useForm(schema)`
The primary hook for managing form state.
- `register(name)`: Returns props for input binding.
- `handleSubmit(onSubmit)`: Form submission handler with validation.
- `errors`: Object containing field errors.
- `values`: Current form values.
- `isSubmitting`: Boolean indicating submission status.

#### `useField(name)`
Access specific field state within a `FormContext`.

## 🧪 Testing

We use [Vitest](https://vitest.dev/) for unit testing.

```bash
npm test
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

Distributed under the MIT License. See `LICENSE` for more information.