@n8x/react-form-utils 1.0.0

package/README.md

@@ -0,0 +1,1238 @@
+# n8x-form-utils
+
+A powerful React form library that simplifies form creation with instant JavaScript object-to-form generation, Zod validation, controlled form submission events, and state management using React Hook Form. <b>A fastest way to create and manage forms in react</b>.
+
+**Features:**
+- Rapid form generation from simple field configuration
+- Built-in Zod validation with type safety
+- Multiple pre-built styling themes
+- Grouped form support for complex layouts
+- Controlled form submission handling
+- Query hooks for API integration
+- Support for 10+ field types
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Setup](#setup)
+- [Quick Start](#quick-start)
+- [Field Types](#field-types)
+- [Validation](#validation)
+- [Styling Themes](#styling-themes)
+- [Grouped Forms](#grouped-forms)
+- [Form Submission](#form-submission)
+- [Data Fetching Hooks](#data-fetching-hooks)
+- [Error Handling](#error-handling)
+- [API Reference](#api-reference)
+- [Contribution](#Contributing)
+
+---
+
+## Installation
+
+```bash
+npm install n8x-form-utils
+```
+
+**Dependencies (auto-installed):**
+- React 18+
+- React Hook Form 7+
+- Zod 4+
+- Tailwind CSS 4+
+- Axios
+
+---
+
+## Setup
+
+### 1. Wrap Your App with FormContextProvider
+
+```tsx
+import { ReactNode } from 'react'
+import { FormContext } from 'n8x-form-utils'
+import FormContextProvider from 'n8x-form-utils'
+
+export default function App() {
+  return (
+    <FormContextProvider>
+      {/* Your routes and components */}
+    </FormContextProvider>
+  )
+}
+```
+
+The `FormContextProvider` manages the global form state and validation schema. It should wrap your entire application or at least the components using N8xForm.
+
+---
+
+## Quick Start
+
+### Create a Simple Login Form
+
+**Step 1: Define your form fields**
+
+```tsx
+// forms/login.ts
+import { z } from 'n8x-form-utils'
+import { FormFieldTypes, FormFieldWidth, type FormFields } from 'n8x-form-utils'
+
+export const loginForm: FormFields[] = [
+  {
+    name: 'email',
+    type: FormFieldTypes.EMAIL,
+    label: 'Email',
+    placeholder: 'hello@example.com',
+    required: true,
+    width: FormFieldWidth.FULL,
+    validationScheme: z.string().email('Please enter a valid email')
+  },
+  {
+    name: 'password',
+    type: FormFieldTypes.PASSWORD,
+    label: 'Password',
+    placeholder: 'Enter your password',
+    required: true,
+    width: FormFieldWidth.FULL,
+    validationScheme: z.string().min(6, 'Password must be at least 6 characters')
+  }
+]
+```
+
+**Step 2: Use the form in your component**
+
+```tsx
+// pages/auth/Login.tsx
+import { useContext } from 'react'
+import { N8xForm, useN8xFormQuery, EDefaultFieldStyles } from 'n8x-form-utils'
+import { loginForm } from '../../forms/login'
+import { login } from '../../service/auth-service'
+
+export default function LoginPage() {
+  const { data, execute, error, isLoading } = useN8xFormQuery(login)
+
+  const handleLoginSubmit = async (formData: any) => {
+    execute(formData)
+  }
+
+  return (
+    <div className="w-full min-h-screen flex justify-center items-center">
+      <div className="md:w-[600px] w-full sm:p-6 p-3">
+        <h1 className="text-4xl tracking-tighter">Account Login</h1>
+        
+        <N8xForm 
+          fields={loginForm} 
+          onShubmit={handleLoginSubmit}
+          defaultFieldStyles={EDefaultFieldStyles.FLOATING_LABEL}
+        >
+          <button 
+            disabled={isLoading} 
+            type="submit" 
+            className="col-span-4 bg-blue-500 disabled:bg-zinc-400 text-white py-2 px-4 rounded font-medium"
+          >
+            {isLoading ? 'Logging in...' : 'Login'}
+          </button>
+        </N8xForm>
+
+        {error && <p className="text-red-500 text-center mt-4">{error}</p>}
+      </div>
+    </div>
+  )
+}
+```
+
+---
+
+## Field Types
+
+N8x Form Utils supports 10+ field types. Here's a comprehensive example showing all available field types:
+
+### Basic Fields
+
+#### TEXT Field
+```tsx
+{
+  name: 'username',
+  type: FormFieldTypes.TEXT,
+  label: 'Username',
+  placeholder: 'Enter your username',
+  required: true,
+  width: FormFieldWidth.FULL,
+  validationScheme: z.string().min(3, 'Username must be at least 3 characters')
+}
+```
+
+#### EMAIL Field
+```tsx
+{
+  name: 'email',
+  type: FormFieldTypes.EMAIL,
+  label: 'Email Address',
+  placeholder: 'you@example.com',
+  required: true,
+  width: FormFieldWidth.FULL,
+  validationScheme: z.string().email('Invalid email address')
+}
+```
+
+#### PASSWORD Field
+```tsx
+{
+  name: 'password',
+  type: FormFieldTypes.PASSWORD,
+  label: 'Password',
+  placeholder: 'Create a strong password',
+  required: true,
+  width: FormFieldWidth.FULL,
+  validationScheme: z.string()
+    .min(6, 'Password must be at least 6 characters')
+    .max(36, 'Password too long')
+}
+```
+
+#### NUMBER Field
+```tsx
+{
+  name: 'age',
+  type: FormFieldTypes.NUMBER,
+  label: 'Age',
+  placeholder: 'Enter your age',
+  min: 18,
+  max: 100,
+  required: true,
+  width: FormFieldWidth.HALF,
+  validationScheme: z.number().min(18, 'Must be 18 or older')
+}
+```
+
+#### DATE Field
+```tsx
+{
+  name: 'birthDate',
+  type: FormFieldTypes.DATE,
+  label: 'Date of Birth',
+  required: true,
+  width: FormFieldWidth.HALF,
+  validationScheme: z.string().refine(
+    (date) => new Date(date) < new Date(),
+    'Date must be in the past'
+  )
+}
+```
+
+### Composite Fields
+
+#### SELECT Field
+```tsx
+{
+  name: 'country',
+  type: FormFieldTypes.SELECT,
+  label: 'Country',
+  required: true,
+  width: FormFieldWidth.FULL,
+  options: [
+    { label: 'United States', value: 'US' },
+    { label: 'Canada', value: 'CA' },
+    { label: 'United Kingdom', value: 'GB' },
+    { label: 'Australia', value: 'AU' }
+  ],
+  validationScheme: z.string().min(1, 'Please select a country')
+}
+```
+
+#### RADIO Field
+```tsx
+{
+  name: 'accountType',
+  type: FormFieldTypes.RADIO,
+  label: 'Account Type',
+  required: true,
+  width: FormFieldWidth.FULL,
+  options: [
+    { label: 'Personal', value: 'personal' },
+    { label: 'Business', value: 'business' },
+    { label: 'Enterprise', value: 'enterprise' }
+  ],
+  validationScheme: z.string().min(1, 'Please select an account type')
+}
+```
+
+#### CHECKBOX Field
+```tsx
+{
+  name: 'interests',
+  type: FormFieldTypes.CHECKBOX,
+  label: 'Interests',
+  width: FormFieldWidth.FULL,
+  options: [
+    { label: 'Technology', value: 'tech' },
+    { label: 'Finance', value: 'finance' },
+    { label: 'Health', value: 'health' },
+    { label: 'Travel', value: 'travel' }
+  ],
+  validationScheme: z.array(z.string()).min(1, 'Select at least one interest')
+}
+```
+
+#### TEXTAREA Field
+```tsx
+{
+  name: 'bio',
+  type: FormFieldTypes.TEXTAREA,
+  label: 'Bio',
+  placeholder: 'Tell us about yourself',
+  width: FormFieldWidth.FULL,
+  validationScheme: z.string()
+    .min(10, 'Bio must be at least 10 characters')
+    .max(500, 'Bio must not exceed 500 characters')
+}
+```
+
+#### FILE Field
+```tsx
+{
+  name: 'profilePhoto',
+  type: FormFieldTypes.FILE,
+  label: 'Profile Photo',
+  width: FormFieldWidth.FULL,
+  validationScheme: z.any()
+}
+```
+
+---
+
+## Validation
+
+N8x Form Utils uses **Zod** for type-safe schema validation. All fields support a `validationScheme` property where you define your validation rules.
+
+### Basic Validation Examples
+
+```tsx
+import { z } from 'n8x-form-utils'
+
+// Email validation
+validationScheme: z.string().email('Invalid email address')
+
+// Required string with minimum length
+validationScheme: z.string().min(3, 'Minimum 3 characters required')
+
+// Number with range
+validationScheme: z.number().min(0).max(100, 'Value must be between 0 and 100')
+
+// Custom refine validation
+validationScheme: z.string().refine(
+  (value) => value !== 'admin',
+  'Username cannot be "admin"'
+)
+
+// Conditional validation
+validationScheme: z.string().or(z.number())
+
+// Array validation
+validationScheme: z.array(z.string()).min(1, 'Select at least one option')
+```
+
+### Complete Registration Form with Validation
+
+```tsx
+// forms/register.ts
+import { z } from 'n8x-form-utils'
+import { FormFieldTypes, FormFieldWidth, type FormFields } from 'n8x-form-utils'
+
+export const registerForm: FormFields[] = [
+  {
+    name: 'email',
+    type: FormFieldTypes.EMAIL,
+    label: 'Email',
+    placeholder: 'hello@example.com',
+    required: true,
+    width: FormFieldWidth.FULL,
+    validationScheme: z.string().email('Please enter a valid email')
+  },
+  {
+    name: 'password',
+    type: FormFieldTypes.PASSWORD,
+    label: 'Password',
+    placeholder: 'Create a strong password',
+    required: true,
+    width: FormFieldWidth.FULL,
+    validationScheme: z.string()
+      .min(6, 'Password must be at least 6 characters')
+      .max(36, 'Password too long')
+  },
+  {
+    name: 'confirmPassword',
+    type: FormFieldTypes.PASSWORD,
+    label: 'Confirm Password',
+    placeholder: 'Re-enter your password',
+    required: true,
+    width: FormFieldWidth.FULL,
+    validationScheme: z.string().min(6, 'Password must be at least 6 characters')
+  },
+  {
+    name: 'fullName',
+    type: FormFieldTypes.TEXT,
+    label: 'Full Name',
+    placeholder: 'John Doe',
+    required: true,
+    width: FormFieldWidth.FULL,
+    validationScheme: z.string().min(2, 'Name must be at least 2 characters')
+  },
+  {
+    name: 'agreeToTerms',
+    type: FormFieldTypes.CHECKBOX,
+    label: 'Terms',
+    width: FormFieldWidth.FULL,
+    options: [
+      { label: 'I agree to the Terms and Conditions', value: 'agree' }
+    ],
+    validationScheme: z.array(z.string()).min(1, 'You must agree to the terms')
+  }
+]
+```
+
+---
+
+## Styling Themes
+
+N8x Form Utils provides 4 pre-built styling themes via `EDefaultFieldStyles`. You can apply a theme through the `defaultFieldStyles` prop in the N8xForm component.
+
+### Available Themes
+
+#### CLEAN (Minimal, professional)
+```tsx
+<N8xForm 
+  fields={loginForm}
+  defaultFieldStyles={EDefaultFieldStyles.CLEAN}
+  onShubmit={handleSubmit}
+/>
+```
+Clean white inputs with thin borders, subtle focus effects, and a professional appearance.
+
+#### SOFT_GLASS (Modern, glassmorphism)
+```tsx
+<N8xForm 
+  fields={loginForm}
+  defaultFieldStyles={EDefaultFieldStyles.SOFT_GLASS}
+  onShubmit={handleSubmit}
+/>
+```
+Soft, frosted appearance with light background and smooth transitions. Default theme.
+
+#### DARK (Dark mode)
+```tsx
+<N8xForm 
+  fields={loginForm}
+  defaultFieldStyles={EDefaultFieldStyles.DARK}
+  onShubmit={handleSubmit}
+/>
+```
+Dark background inputs suitable for dark mode interfaces.
+
+#### FLOATING_LABEL (Material Design)
+```tsx
+<N8xForm 
+  fields={loginForm}
+  defaultFieldStyles={EDefaultFieldStyles.FLOATING_LABEL}
+  onShubmit={handleSubmit}
+/>
+```
+Floating label style with animated labels on focus/input. Material Design inspired.
+
+### Custom Styling
+
+You can also apply custom Tailwind CSS classes to individual fields:
+
+```tsx
+{
+  name: 'customField',
+  type: FormFieldTypes.TEXT,
+  label: 'Custom Styled',
+  _className: 'bg-gradient-to-r from-blue-400 to-blue-600 text-white rounded-xl'
+}
+```
+
+Or pass a custom string:
+
+```tsx
+<N8xForm 
+  fields={loginForm}
+  defaultFieldStyles="custom-class-string"
+  onShubmit={handleSubmit}
+/>
+```
+
+---
+
+## Grouped Forms
+
+For complex forms with multiple sections, organize fields into logical groups. Grouped forms automatically render section headers.
+
+### Example: User Profile Form with Groups
+
+```tsx
+// forms/userProfile.ts
+import { z } from 'n8x-form-utils'
+import { FormFieldTypes, FormFieldWidth, type FormFields } from 'n8x-form-utils'
+
+export const userProfileForm = {
+  'Personal Information': [
+    {
+      name: 'firstName',
+      type: FormFieldTypes.TEXT,
+      label: 'First Name',
+      required: true,
+      width: FormFieldWidth.HALF,
+      validationScheme: z.string().min(2, 'First name is required')
+    },
+    {
+      name: 'lastName',
+      type: FormFieldTypes.TEXT,
+      label: 'Last Name',
+      required: true,
+      width: FormFieldWidth.HALF,
+      validationScheme: z.string().min(2, 'Last name is required')
+    },
+    {
+      name: 'email',
+      type: FormFieldTypes.EMAIL,
+      label: 'Email Address',
+      required: true,
+      width: FormFieldWidth.FULL,
+      validationScheme: z.string().email('Invalid email')
+    },
+    {
+      name: 'birthDate',
+      type: FormFieldTypes.DATE,
+      label: 'Date of Birth',
+      required: false,
+      width: FormFieldWidth.HALF,
+      validationScheme: z.string().optional()
+    }
+  ],
+  'Contact Information': [
+    {
+      name: 'phone',
+      type: FormFieldTypes.TEXT,
+      label: 'Phone Number',
+      placeholder: '+1 (555) 123-4567',
+      width: FormFieldWidth.FULL,
+      validationScheme: z.string().optional()
+    },
+    {
+      name: 'country',
+      type: FormFieldTypes.SELECT,
+      label: 'Country',
+      required: true,
+      width: FormFieldWidth.HALF,
+      options: [
+        { label: 'United States', value: 'US' },
+        { label: 'Canada', value: 'CA' },
+        { label: 'United Kingdom', value: 'GB' }
+      ],
+      validationScheme: z.string().min(1, 'Select a country')
+    },
+    {
+      name: 'city',
+      type: FormFieldTypes.TEXT,
+      label: 'City',
+      required: true,
+      width: FormFieldWidth.HALF,
+      validationScheme: z.string().min(2, 'City is required')
+    }
+  ],
+  'Preferences': [
+    {
+      name: 'language',
+      type: FormFieldTypes.SELECT,
+      label: 'Preferred Language',
+      width: FormFieldWidth.FULL,
+      options: [
+        { label: 'English', value: 'en' },
+        { label: 'Spanish', value: 'es' },
+        { label: 'French', value: 'fr' },
+        { label: 'German', value: 'de' }
+      ],
+      validationScheme: z.string().optional()
+    },
+    {
+      name: 'newsletter',
+      type: FormFieldTypes.CHECKBOX,
+      label: 'Email Preferences',
+      width: FormFieldWidth.FULL,
+      options: [
+        { label: 'Subscribe to newsletter', value: 'newsletter' },
+        { label: 'Receive promotional emails', value: 'promo' }
+      ],
+      validationScheme: z.array(z.string()).optional()
+    }
+  ]
+}
+```
+
+### Using Grouped Forms
+
+```tsx
+// pages/profile/UserProfile.tsx
+import { useContext } from 'react'
+import { N8xForm, useN8xFormQuery, EDefaultFieldStyles } from 'n8x-form-utils'
+import { userProfileForm } from '../../forms/userProfile'
+import { updateUserProfile } from '../../service/user-service'
+
+export default function UserProfilePage() {
+  const { data, execute, error, isLoading } = useN8xFormQuery(updateUserProfile)
+
+  const handleProfileUpdate = async (formData: any) => {
+    execute(formData)
+  }
+
+  return (
+    <div className="w-full p-6">
+      <h1 className="text-3xl font-bold mb-6">Edit Profile</h1>
+      
+      <N8xForm 
+        fields={userProfileForm}
+        onShubmit={handleProfileUpdate}
+        defaultFieldStyles={EDefaultFieldStyles.SOFT_GLASS}
+      >
+        <button 
+          disabled={isLoading} 
+          type="submit"
+          className="col-span-4 bg-blue-500 disabled:bg-zinc-400 text-white py-2 px-4 rounded font-medium"
+        >
+          {isLoading ? 'Saving...' : 'Save Changes'}
+        </button>
+      </N8xForm>
+
+      {error && <p className="text-red-500 mt-4">{error}</p>}
+    </div>
+  )
+}
+```
+
+---
+
+## Form Submission
+
+### useN8xFormQuery Hook
+
+Execute async operations when the form is submitted. Perfect for API calls.
+
+```tsx
+import { useN8xFormQuery } from 'n8x-form-utils'
+import { login } from '../service/auth-service'
+
+export default function LoginComponent() {
+  const { data, execute, error, isLoading } = useN8xFormQuery(login)
+
+  const handleSubmit = async (formData: any) => {
+    execute(formData) // Calls the login service
+  }
+
+  return (
+    <N8xForm 
+      fields={loginForm}
+      onShubmit={handleSubmit}
+    >
+      <button disabled={isLoading} type="submit">
+        {isLoading ? 'Loading...' : 'Login'}
+      </button>
+    </N8xForm>
+  )
+}
+```
+
+### Hook Signature
+
+```tsx
+const { data, execute, error, isLoading } = useN8xFormQuery(
+  queryService: (payload: any, signal?: AbortSignal) => Promise<any>
+)
+```
+
+**Properties:**
+- `data`: Response data from the service after successful execution
+- `execute`: Function to call the service with form payload
+- `error`: Error message if the request fails
+- `isLoading`: Boolean indicating if the request is in progress
+
+### Service Function Example
+
+```tsx
+// service/auth-service.ts
+import axios from 'axios'
+
+export const login = async (payload: any, signal?: AbortSignal) => {
+  return axios.post('/api/auth/login', payload, { signal })
+}
+
+export const register = async (payload: any, signal?: AbortSignal) => {
+  return axios.post('/api/auth/register', payload, { signal })
+}
+```
+
+### Complete Submission Example with Side Effects
+
+```tsx
+import { useContext, useEffect } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { N8xForm, useN8xFormQuery, EDefaultFieldStyles } from 'n8x-form-utils'
+import { AuthContext } from '../context/AuthContext'
+import { loginForm } from '../forms/login'
+import { login } from '../service/auth-service'
+
+export default function LoginPage() {
+  const { setUser } = useContext(AuthContext)
+  const navigate = useNavigate()
+  const { data, execute, error, isLoading } = useN8xFormQuery(login)
+
+  const handleLoginSubmit = async (formData: any) => {
+    execute(formData)
+  }
+
+  // Handle successful login
+  useEffect(() => {
+    if (data) {
+      setUser(data)
+      navigate('/home')
+    }
+  }, [data, setUser, navigate])
+
+  return (
+    <div className="min-h-screen flex items-center justify-center">
+      <div className="w-full max-w-md">
+        <h1 className="text-4xl font-bold mb-6">Login</h1>
+        
+        <N8xForm 
+          fields={loginForm}
+          onShubmit={handleLoginSubmit}
+          defaultFieldStyles={EDefaultFieldStyles.FLOATING_LABEL}
+        >
+          <button 
+            disabled={isLoading}
+            type="submit"
+            className="col-span-4 bg-blue-500 hover:bg-blue-600 disabled:bg-zinc-400 text-white py-2 rounded font-medium transition"
+          >
+            {isLoading ? 'Logging in...' : 'Login'}
+          </button>
+        </N8xForm>
+
+        {error && <p className="text-red-500 text-center mt-4">{error}</p>}
+      </div>
+    </div>
+  )
+}
+```
+
+---
+
+## Data Fetching Hooks
+
+### useN8xQuery Hook
+
+Auto-execute queries on component mount. Use this for fetching initial data to populate forms.
+
+```tsx
+import { useN8xQuery } from 'n8x-form-utils'
+import { fetchUserProfile } from '../service/user-service'
+
+export default function ProfilePage() {
+  const { data: profile, error, isLoading } = useN8xQuery(fetchUserProfile, userId)
+
+  if (isLoading) return <div>Loading profile...</div>
+  if (error) return <div>Error: {error}</div>
+
+  return (
+    <N8xForm 
+      fields={userProfileForm}
+      onShubmit={handleProfileUpdate}
+    />
+  )
+}
+```
+
+### Hook Signature
+
+```tsx
+const { data, error, isLoading } = useN8xQuery(
+  queryService: (payload: any, signal?: AbortSignal) => Promise<any>,
+  ...queryParams: any[]
+)
+```
+
+**Properties:**
+- `data`: Response data from the service
+- `error`: Error message if the request fails
+- `isLoading`: Boolean indicating if the request is loading
+
+### Key Differences
+
+| Feature | useN8xFormQuery | useN8xQuery |
+|---------|-----------------|------------|
+| Runs on mount | ❌ No | ✅ Yes |
+| Triggered by | Manual call | Auto on mount |
+| Return state | `data, error, isLoading, execute` | `data, error, isLoading` |
+| Use case | Form submissions | Initial data fetch |
+
+---
+
+## Error Handling
+
+### Display Validation Errors
+
+Validation errors from Zod are automatically displayed below each field with error styling.
+
+```tsx
+<N8xForm 
+  fields={loginForm}
+  onShubmit={handleSubmit}
+/>
+// Errors appear in real-time as user types (default: "onChange" mode)
+```
+
+### Display API Errors
+
+Handle errors returned from `useN8xFormQuery`:
+
+```tsx
+const { data, execute, error, isLoading } = useN8xFormQuery(login)
+
+return (
+  <>
+    <N8xForm 
+      fields={loginForm}
+      onShubmit={handleSubmit}
+    />
+    
+    {error && (
+      <div className="mt-4 p-4 bg-red-50 border border-red-200 rounded">
+        <p className="text-red-700 font-semibold">Login failed</p>
+        <p className="text-red-600 text-sm">{error}</p>
+      </div>
+    )}
+  </>
+)
+```
+
+### Custom Error Component
+
+```tsx
+interface ErrorProps {
+  message: string
+  onDismiss?: () => void
+}
+
+function ErrorAlert({ message, onDismiss }: ErrorProps) {
+  return (
+    <div className="p-4 bg-red-50 border-l-4 border-red-500 rounded">
+      <p className="text-red-700">{message}</p>
+      {onDismiss && (
+        <button onClick={onDismiss} className="mt-2 text-sm text-red-600">
+          Dismiss
+        </button>
+      )}
+    </div>
+  )
+}
+
+export default function LoginPage() {
+  const { data, execute, error, isLoading } = useN8xFormQuery(login)
+  const [dismissError, setDismissError] = React.useState(false)
+
+  return (
+    <>
+      {error && !dismissError && (
+        <ErrorAlert 
+          message={error}
+          onDismiss={() => setDismissError(true)}
+        />
+      )}
+      <N8xForm 
+        fields={loginForm}
+        onShubmit={(data) => {
+          setDismissError(false)
+          execute(data)
+        }}
+      />
+    </>
+  )
+}
+```
+
+### Error Recovery
+
+```tsx
+const [errorKey, setErrorKey] = React.useState(0)
+
+const handleRetry = () => {
+  setErrorKey(prev => prev + 1) // Force form re-render
+}
+
+return (
+  <>
+    {error && (
+      <button onClick={handleRetry} className="text-blue-600">
+        Retry
+      </button>
+    )}
+    <N8xForm 
+      key={errorKey}
+      fields={loginForm}
+      onShubmit={handleSubmit}
+    />
+  </>
+)
+```
+
+---
+
+## API Reference
+
+### N8xForm Component
+
+The main form component that renders fields and handles submission.
+
+```tsx
+interface FormProps {
+  fields?: FormFields[] | GroupedFormFields
+  defaultFieldStyles?: EDefaultFieldStyles | string
+  onShubmit: (data: any) => void
+  mode?: Mode
+  children?: React.ReactNode
+}
+
+<N8xForm 
+  fields={loginForm}
+  defaultFieldStyles={EDefaultFieldStyles.FLOATING_LABEL}
+  onShubmit={handleSubmit}
+  mode="onBlur"
+>
+  <button type="submit">Submit</button>
+</N8xForm>
+```
+
+**Props:**
+- `fields`: Array or object of FormFields to render
+- `defaultFieldStyles`: Theme from EDefaultFieldStyles or custom Tailwind string
+- `onShubmit`: Callback when form is successfully submitted
+- `mode`: React Hook Form validation mode ('onChange', 'onBlur', 'onTouched', 'onSubmit', 'all')
+- `children`: Additional JSX elements (e.g., submit button, custom elements)
+
+### FormFields Type
+
+Configuration for a single form field.
+
+```tsx
+type FormFields = {
+  name: string                                    // Unique field identifier
+  type: FormFieldTypes                           // Input type
+  validationScheme?: ZodTypeAny                 // Zod validation schema
+  label?: string                                 // Display label
+  placeholder?: string                          // Input placeholder
+  options?: { label: string; value: string }[]  // For select/radio/checkbox
+  min?: number                                  // Min value for number fields
+  max?: number                                  // Max value for number fields
+  required?: boolean                            // Is field required?
+  width?: FormFieldWidth                        // Grid column span
+  watch?: boolean                               // Watch for changes
+  default?: string                              // Default value
+  _className?: string                           // Custom Tailwind classes
+}
+```
+
+### FormFieldTypes Enum
+
+```tsx
+enum FormFieldTypes {
+  TEXT = 'text'
+  NUMBER = 'number'
+  EMAIL = 'email'
+  PASSWORD = 'password'
+  SELECT = 'select'
+  RADIO = 'radio'
+  CHECKBOX = 'checkbox'
+  TEXTAREA = 'textarea'
+  DATE = 'date'
+  FILE = 'file'
+  SUBMIT = 'submit'
+}
+```
+
+### FormFieldWidth Enum
+
+```tsx
+enum FormFieldWidth {
+  FULL = 'col-span-4'    // 100% width
+  HALF = 'col-span-2'    // 50% width
+  THIRD = 'col-span-3'   // 75% width
+  QUARTER = 'col-span-1' // 25% width
+}
+```
+
+### EDefaultFieldStyles Enum
+
+```tsx
+enum EDefaultFieldStyles {
+  CLEAN        // Minimal white inputs
+  SOFT_GLASS   // Glassmorphism (default)
+  DARK         // Dark mode inputs
+  FLOATING_LABEL // Material Design floating labels
+}
+```
+
+### useN8xFormQuery Hook
+
+```tsx
+const {
+  data,      // Response data after successful request
+  execute,   // Function to execute the query
+  error,     // Error message string or null
+  isLoading  // Boolean loading state
+} = useN8xFormQuery(
+  queryService: (payload: any, signal?: AbortSignal) => Promise<any>
+)
+```
+
+**Example:**
+```tsx
+const { data, execute, error, isLoading } = useN8xFormQuery(login)
+
+// Later in form submission:
+const handleSubmit = (formData: any) => {
+  execute(formData)
+}
+```
+
+### useN8xQuery Hook
+
+```tsx
+const {
+  data,      // Response data after successful request
+  error,     // Error message string or null
+  isLoading  // Boolean loading state
+} = useN8xQuery(
+  queryService: (payload: any, signal?: AbortSignal) => Promise<any>,
+  ...queryParams: any[]
+)
+```
+
+**Example:**
+```tsx
+const { data, error, isLoading } = useN8xQuery(fetchUserProfile, userId)
+```
+
+### FormContextType Interface
+
+```tsx
+interface FormContextType {
+  formUtils: ReturnType<typeof useForm>        // React Hook Form utilities
+  setValidationSchema: (props: ZodSchema) => void // Update validation schema
+  setMode: (props: Mode) => void                // Update validation mode
+}
+```
+
+---
+
+## Complete Real-World Example
+
+Here's a complete registration flow combining everything:
+
+```tsx
+// forms/registration.ts
+import { z } from 'n8x-form-utils'
+import { FormFieldTypes, FormFieldWidth, type FormFields } from 'n8x-form-utils'
+
+export const registrationForm: FormFields[] = [
+  {
+    name: 'email',
+    type: FormFieldTypes.EMAIL,
+    label: 'Email Address',
+    placeholder: 'hello@example.com',
+    required: true,
+    width: FormFieldWidth.FULL,
+    validationScheme: z.string().email('Invalid email address')
+  },
+  {
+    name: 'password',
+    type: FormFieldTypes.PASSWORD,
+    label: 'Password',
+    placeholder: 'Create a strong password',
+    required: true,
+    width: FormFieldWidth.FULL,
+    validationScheme: z.string()
+      .min(6, 'Password must be at least 6 characters')
+      .max(36, 'Password too long')
+  },
+  {
+    name: 'confirmPassword',
+    type: FormFieldTypes.PASSWORD,
+    label: 'Confirm Password',
+    placeholder: 'Re-enter your password',
+    required: true,
+    width: FormFieldWidth.FULL,
+    validationScheme: z.string()
+      .min(6, 'Password must match')
+  },
+  {
+    name: 'fullName',
+    type: FormFieldTypes.TEXT,
+    label: 'Full Name',
+    placeholder: 'John Doe',
+    required: true,
+    width: FormFieldWidth.FULL,
+    validationScheme: z.string().min(2, 'Name too short')
+  },
+  {
+    name: 'accountType',
+    type: FormFieldTypes.RADIO,
+    label: 'Account Type',
+    required: true,
+    width: FormFieldWidth.FULL,
+    options: [
+      { label: 'Personal', value: 'personal' },
+      { label: 'Business', value: 'business' }
+    ],
+    validationScheme: z.string()
+  },
+  {
+    name: 'interests',
+    type: FormFieldTypes.CHECKBOX,
+    label: 'Select Your Interests',
+    width: FormFieldWidth.FULL,
+    options: [
+      { label: 'Technology', value: 'tech' },
+      { label: 'Finance', value: 'finance' },
+      { label: 'Health', value: 'health' }
+    ],
+    validationScheme: z.array(z.string()).min(1, 'Select at least one interest')
+  },
+  {
+    name: 'terms',
+    type: FormFieldTypes.CHECKBOX,
+    label: 'Agreement',
+    required: true,
+    width: FormFieldWidth.FULL,
+    options: [
+      { label: 'I agree to Terms and Conditions', value: 'agreed' }
+    ],
+    validationScheme: z.array(z.string()).min(1, 'You must agree to terms')
+  }
+]
+
+// pages/auth/Register.tsx
+import { useContext, useEffect, useState } from 'react'
+import { Link, useNavigate } from 'react-router-dom'
+import { N8xForm, useN8xFormQuery, EDefaultFieldStyles } from 'n8x-form-utils'
+import { AuthContext, type IAuthContext } from '../../context/AuthContext/context'
+import { registrationForm } from '../../forms/registration'
+import { register } from '../../service/auth-service'
+
+export default function RegisterPage() {
+  const { user, setUser } = useContext(AuthContext) as IAuthContext
+  const navigate = useNavigate()
+  const [dismissError, setDismissError] = useState(false)
+  const { data, execute, error, isLoading } = useN8xFormQuery(register)
+
+  const handleRegisterSubmit = async (formData: any) => {
+    // Validate passwords match
+    if (formData.password !== formData.confirmPassword) {
+      // You could set a custom error here or let Zod handle it
+      return
+    }
+    setDismissError(false)
+    execute(formData)
+  }
+
+  // Handle successful registration
+  useEffect(() => {
+    if (data) {
+      setUser(data)
+      navigate('/home')
+    }
+  }, [data, setUser, navigate])
+
+  // Redirect if already logged in
+  useEffect(() => {
+    if (user) {
+      navigate('/home')
+    }
+  }, [user, navigate])
+
+  return (
+    <div className="w-full min-h-screen flex justify-center items-center bg-gradient-to-br from-zinc-50 to-zinc-100 p-4">
+      <div className="md:w-[600px] w-full">
+        <div className="mb-8">
+          <h1 className="text-4xl font-bold tracking-tight mb-2">Create Your Account</h1>
+          <p className="text-zinc-600">Join us today and get started</p>
+        </div>
+
+        {error && !dismissError && (
+          <div className="mb-4 p-4 bg-red-50 border border-red-200 rounded-lg">
+            <p className="text-red-700 font-semibold">Registration failed</p>
+            <p className="text-red-600 text-sm mt-1">{error}</p>
+            <button 
+              onClick={() => setDismissError(true)}
+              className="mt-2 text-xs text-red-600 hover:text-red-700"
+            >
+              Dismiss
+            </button>
+          </div>
+        )}
+
+        <N8xForm 
+          fields={registrationForm}
+          onShubmit={handleRegisterSubmit}
+          defaultFieldStyles={EDefaultFieldStyles.FLOATING_LABEL}
+        >
+          <button 
+            disabled={isLoading}
+            type="submit"
+            className={`col-span-4 py-3 px-4 rounded-lg font-semibold text-white transition-all ${
+              isLoading 
+                ? 'bg-zinc-400 cursor-not-allowed' 
+                : 'bg-blue-500 hover:bg-blue-600 active:bg-blue-700'
+            }`}
+          >
+            {isLoading ? (
+              <span className="inline-flex items-center gap-2">
+                <svg className="w-4 h-4 animate-spin" fill="none" viewBox="0 0 24 24">
+                  <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+                  <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+                </svg>
+                Creating account...
+              </span>
+            ) : (
+              'Create Account'
+            )}
+          </button>
+        </N8xForm>
+
+        <p className="text-center text-sm text-zinc-600 mt-6">
+          Already have an account?{' '}
+          <Link to="/login" className="text-blue-500 hover:text-blue-600 font-semibold">
+            Login here
+          </Link>
+        </p>
+      </div>
+    </div>
+  )
+}
+```
+
+---
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## License
+
+ISC License - Created by Syed Shayan Ali
+
+## Contributing
+
+This project is currently not open for external contributions. It will be made open source very soon in the future once it has matured and gained wider adoption.