Here is your complete, polished README.md content for your npm package @form-router, ready to place at the root of your package directory:

# 📦 @form-router

A **powerful**, schema-driven React form library built with **TypeScript**, **Zod**, and designed to integrate seamlessly with **Redux Toolkit**.

---

## ✨ Features

- 🧠 **Schema Inference**  
  Automatically build forms from your Zod schemas

- ⚙️ **RTK Integration**  
  Deep support for Redux Toolkit Query & Mutation APIs

- 🚀 **Smart Defaults**  
  Minimal config needed — works out of the box

- 🎨 **Custom Components**  
  Override any UI component with your own

- 🛡️ **TypeScript First**  
  Full IntelliSense and static type safety

- 🎛️ **Framework Agnostic**  
  Use with Tailwind, Bootstrap, or custom styles

---

## 📦 Installation

```bash
npm install @form-router zod @reduxjs/toolkit
# or
yarn add @form-router zod @reduxjs/toolkit

⚡ Quick Start

import React from 'react';
import { z } from 'zod';
import { SmartForm } from '@form-router';
import { useCreateUserMutation } from '@/services/api';

const userSchema = z.object({
  email: z.string().email(),
  age: z.number().min(18),
  country: z.enum(['US', 'UK', 'CA']),
  isAdmin: z.boolean().optional(),
});

const MyForm = () => {
  const [createUser] = useCreateUserMutation();

  return (
    <SmartForm
      schema={userSchema}
      rtkService={{ mutate: createUser }}
      onSuccess={(data) => console.log('✅ User created:', data)}
      onError={(err) => console.error('❌ Error:', err)}
    />
  );
};

🧩 Custom Components

You can override the default fields with your own:

import { InputProps, SmartForm } from '@form-router';

const CustomInput: React.FC<InputProps> = ({ name, value, onChange, error }) => (
  <div className="custom-input-wrapper">
    <input
      name={name}
      value={value}
      onChange={(e) => onChange(e.target.value)}
      className={`input ${error ? 'input-error' : ''}`}
    />
    {error && <span className="text-red-500">{error}</span>}
  </div>
);

<SmartForm
  schema={userSchema}
  rtkService={{ mutate: createUser }}
  components={{
    text: CustomInput,
    email: CustomInput,
  }}
/>

🧠 Using the Hook

import { useSmartForm } from '@form-router';
import { z } from 'zod';

const schema = z.object({
  username: z.string().min(3),
  password: z.string().min(6),
});

const LoginForm = () => {
  const {
    values,
    errors,
    isValid,
    isSubmitting,
    setValue,
    handleSubmit,
  } = useSmartForm({ schema });

  return (
    <form onSubmit={handleSubmit(async (formValues) => {
      await loginUser(formValues);
    })}>
      <input
        value={values.username}
        onChange={(e) => setValue('username', e.target.value)}
      />
      {errors.username && <p>{errors.username}</p>}
      <button type="submit" disabled={!isValid || isSubmitting}>Submit</button>
    </form>
  );
};

✅ Supported Zod Types

| Zod Type | Rendered Field | | -------------------- | ---------------- | | z.string() | Text input | | z.string().email() | Email input | | z.number() | Number input | | z.boolean() | Checkbox | | z.enum([...]) | Select dropdown | | .optional() | Optional field | | .default(value) | Default value | | .min(n), .max(n) | Validation rules |

⚙️ RTK Integration

Works seamlessly with RTK Query or custom dispatches:

RTK Query:

const [createUser] = useCreateUserMutation();

<SmartForm rtkService={{ mutate: createUser }} />

Manual Dispatch:

const dispatch = useAppDispatch();

<SmartForm
  rtkService={{
    mutate: (data) => dispatch(createUserThunk(data))
  }}
/>

🎨 Styling

The following class names are used by default:

.smart-form {}              /* Form container */
.smart-form-field {}        /* Wrapper around each field */
.smart-form-label {}        /* Field label */
.smart-form-input {}        /* Input/Select field */
.smart-form-error {}        /* Error messages */
.smart-form-submit {}       /* Submit button */

Override these or supply custom components for full control.

📘 SmartForm Props

| Prop | Type | Description | | ----------------------- | ---------------------- | --------------------------------- | | schema | ZodObject | Zod schema for form structure | | rtkService | RTKService | RTK mutation or service | | components | ComponentMap | Custom component overrides | | onSuccess | (data: any) => void | Callback on successful submission | | onError | (error: any) => void | Callback on error | | initialValues | Record<string, any> | Pre-fill form fields | | validateOnChange | boolean | Validate fields on change | | validateOnBlur | boolean | Validate fields on blur | | submitButtonText | string | Text for submit button | | submitButtonClassName | string | Custom class for submit button | | disabled | boolean | Disable the entire form |

📝 License

MIT License © 2025 Wazeer Ahmed