@algodomain/smart-forms 0.1.0 → 0.1.2

package/README.md

@@ -1,70 +1,119 @@
 # @algodomain/smart-forms
 
-A powerful, flexible React form framework with smart fields, multi-tab support, built-in validation, and seamless API integration. Built with TypeScript, Tailwind CSS, and shadcn/ui components.
+> A powerful, flexible React form framework with smart fields, multi-tab support, built-in validation, and seamless API integration.
 
-📚 **[Complete User Guide](./USER_GUIDE.md)** | 🚀 **[Quick Reference](./QUICK_REFERENCE.md)** | 📖 **[API Reference](./API_REFERENCE.md)**
+[![npm version](https://img.shields.io/npm/v/@algodomain/smart-forms.svg)](https://www.npmjs.com/package/@algodomain/smart-forms)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Features
+Built with TypeScript, Tailwind CSS, Zod validation, and shadcn/ui components.
 
-- 🎯 **Smart Fields**: Pre-built, validated form fields with consistent UX
-- 📑 **Multi-Tab Forms**: Create complex forms with tabbed navigation and progress tracking
-- ✅ **Built-in Validation**: Powered by Zod for type-safe validation
-- 🔄 **API Integration**: Automatic form submission with authentication support
-- 💾 **Auto-Save**: LocalStorage support for draft saving
-- 🎨 **Customizable**: Full theme control via CSS variables
-- 🌙 **Dark Mode**: Built-in support for light and dark themes
-- ♿ **Accessible**: Built on Radix UI primitives
-- 📦 **Tree-Shakeable**: Import only what you need
+---
 
-## Installation
+## 📋 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Form Components](#-form-components)
+- [Field Components](#-field-components)
+- [Opinionated Fields](#-opinionated-fields)
+- [Configuration Reference](#-configuration-reference)
+- [Advanced Features](#-advanced-features)
+- [Theming](#-theming--customization)
+- [Hooks & Context](#-hooks--context)
+- [Examples](#-examples)
+- [Troubleshooting](#-troubleshooting)
+- [Contributing](#-contributing)
+
+---
+
+## ✨ Features
+
+- 🎯 **Smart Fields** - Pre-built, validated form fields with consistent UX
+- 📑 **Multi-Tab Forms** - Create complex forms with tabbed navigation and progress tracking
+- ✅ **Built-in Validation** - Powered by Zod for type-safe validation
+- 🔄 **API Integration** - Automatic form submission with authentication support
+- 🔗 **Query Params** - Include URL query parameters in form submissions
+- 💾 **Auto-Save** - LocalStorage support for draft saving
+- 🎨 **Customizable** - Full theme control via CSS variables
+- 🌙 **Dark Mode** - Built-in support for light and dark themes
+- ♿ **Accessible** - Built on Radix UI primitives
+- 📦 **Tree-Shakeable** - Import only what you need
+- 🔒 **Type-Safe** - Full TypeScript support
+
+---
+
+## 📦 Installation
+
+### 1. Install the Package
 
 ```bash
 npm install @algodomain/smart-forms
 # or
-pnpm add @algodomain/smart-forms
-# or
 yarn add @algodomain/smart-forms
+# or
+pnpm add @algodomain/smart-forms
 ```
 
-### Peer Dependencies
-
-Make sure you have these installed:
+### 2. Install Peer Dependencies
 
 ```bash
 npm install react react-dom tailwindcss zod react-toastify date-fns lucide-react
 ```
 
-## Quick Start
-
-### 1. Import the CSS
+### 3. Import Styles
 
-Add this to your main entry file (e.g., `main.tsx` or `index.tsx`):
+Add to your main entry file (`main.tsx` or `index.tsx`):
 
 ```tsx
 import '@algodomain/smart-forms/style.css'
-import './index.css' // Your Tailwind CSS
+import 'react-toastify/dist/ReactToastify.css'
+```
+
+### 4. Configure Tailwind CSS (v4)
+
+Add `@source` directives to scan the package for Tailwind classes:
+
+```css
+/* src/index.css */
+@import "tailwindcss";
+
+@source "../node_modules/@algodomain/smart-forms/dist/index.js";
+@source "../node_modules/@algodomain/smart-forms/dist/index.cjs";
+
+@import "@algodomain/smart-forms/style.css";
 ```
 
-### 2. Create Your First Form
+---
+
+## 🚀 Quick Start
+
+### Basic Form Example
 
 ```tsx
 import { SmartForm } from '@algodomain/smart-forms'
-import { SmartInput } from '@algodomain/smart-forms/fields'
-import { FieldEmail, FieldPassword } from '@algodomain/smart-forms/opinionated'
+import { SmartInput, SmartSelect } from '@algodomain/smart-forms/fields'
+import { FieldEmail } from '@algodomain/smart-forms/opinionated'
+import { z } from 'zod'
 
 function RegistrationForm() {
   return (
     <SmartForm
-      api="/api/register"
+      api="https://api.example.com/register"
       method="POST"
       submitButtonText="Sign Up"
-      onSuccess={(data) => console.log('User created:', data)}
+      onSuccess={(data) => console.log('Success!', data)}
       onError={(error) => console.error('Error:', error)}
-      authentication={{ enable: true }}
     >
-      <SmartInput field="name" label="Full Name" required />
+      <SmartInput
+        field="name"
+        label="Full Name"
+        validation={z.string().min(3, 'Name must be at least 3 characters')}
+        required
+      />
+      
       <FieldEmail field="email" required />
-      <FieldPassword field="password" required />
+      
       <SmartSelect
         field="role"
         label="Role"
@@ -72,27 +121,27 @@ function RegistrationForm() {
           { value: 'user', label: 'User' },
           { value: 'admin', label: 'Admin' }
         ]}
+        required
       />
     </SmartForm>
   )
 }
 ```
 
-### 3. Multi-Tab Form Example
+### Multi-Tab Form Example
 
 ```tsx
 import { MultiTabSmartForm, Tab } from '@algodomain/smart-forms'
-import { SmartInput, SmartRadioGroup, SmartTags } from '@algodomain/smart-forms/fields'
+import { SmartInput, SmartTags } from '@algodomain/smart-forms/fields'
 import { z } from 'zod'
 
-function CreateJobForm() {
+function JobPostingForm() {
   return (
     <MultiTabSmartForm
       api="/api/jobs"
       method="POST"
       showProgressBar={true}
       showTabNumbers={true}
-      authentication={{ enable: true }}
       onSuccess={(data) => console.log('Job created:', data)}
     >
       <Tab title="Basic Info">
@@ -102,15 +151,6 @@ function CreateJobForm() {
           validation={z.string().min(3)}
           required 
         />
-        <SmartRadioGroup
-          field="jobType"
-          label="Job Type"
-          options={[
-            { value: 'FULL_TIME', label: 'Full Time' },
-            { value: 'PART_TIME', label: 'Part Time' }
-          ]}
-          required
-        />
       </Tab>
       
       <Tab title="Requirements">
@@ -120,194 +160,919 @@ function CreateJobForm() {
           validation={z.array(z.string()).min(1)}
           required 
         />
-        <SmartInput 
-          field="experience" 
-          label="Years of Experience"
-          type="number"
-        />
       </Tab>
     </MultiTabSmartForm>
   )
 }
 ```
 
-## Available Components
+---
+
+## 📝 Form Components
 
-### Core Forms
+### SmartForm
 
-- **SmartForm**: Single-page form with API integration
-- **MultiTabSmartForm**: Multi-step tabbed form with progress tracking
-- **BaseSmartForm**: Low-level form component for custom layouts
+Single-page form with automatic submission handling.
 
-### Smart Fields
+**Usage:**
 
-Import from `@algodomain/smart-forms/fields`:
+```tsx
+<SmartForm
+  api="/api/endpoint"
+  method="POST"
+  onSuccess={(data) => console.log(data)}
+  onError={(error) => console.error(error)}
+>
+  {/* Your fields here */}
+</SmartForm>
+```
 
-- `SmartInput` - Text, email, password, number, textarea inputs
-- `SmartSelect` - Dropdown select
-- `SmartCheckbox` - Checkbox with label
-- `SmartRadioGroup` - Radio button group
-- `SmartCombobox` - Searchable select
-- `SmartDatePicker` - Date picker with calendar
-- `SmartFileUpload` - File upload with preview
-- `SmartSlider` - Single value slider
-- `SmartDualRangeSlider` - Min/max range slider
-- `SmartTags` - Tag input field
-- `SmartAutoSuggestTags` - Tags with autocomplete
-- `SmartBasicRichTextbox` - Basic rich text editor
+### MultiTabSmartForm
 
-### Opinionated Fields
+Multi-step form with tabs and progress tracking.
 
-Import from `@algodomain/smart-forms/opinionated`:
+**Usage:**
 
-Pre-configured fields with built-in validation:
+```tsx
+<MultiTabSmartForm
+  api="/api/submit"
+  showProgressBar={true}
+  showTabNumbers={true}
+>
+  <Tab title="Step 1">
+    {/* Fields */}
+  </Tab>
+  <Tab title="Step 2">
+    {/* Fields */}
+  </Tab>
+</MultiTabSmartForm>
+```
 
-- `FieldEmail` - Email field with validation
-- `FieldPassword` / `FieldConfirmPassword` - Password fields
-- `FieldPhone` - Phone number field
-- `FieldFirstName` / `FieldLastName` / `FieldFullName` - Name fields
-- `FieldAge` - Age field with validation
-- `FieldStreetAddress` / `FieldCity` / `FieldZipCode` / `FieldState` - Address fields
-- `FieldMessage` / `FieldComments` - Message/comment fields
+### BaseSmartForm
 
-## Configuration
+Low-level form component for custom layouts.
 
-### Form Props
+**Usage:**
 
 ```tsx
-<SmartForm
-  api="/api/endpoint"                    // API endpoint
-  method="POST"                          // HTTP method (POST, PUT, PATCH)
-  submitButtonText="Submit"              // Custom button text
-  onSuccess={(data) => {}}               // Success callback
-  onError={(error) => {}}                // Error callback
-  authentication={{ enable: true }}      // Add Bearer token
-  enableLocalStorage={true}              // Enable draft saving
-  storageKey="my-form-draft"            // LocalStorage key
-  initialData={{ name: "John" }}        // Pre-fill data
-  transformData={(data) => data}         // Transform before submit
+<BaseSmartForm api="/api/submit">
+  <div className="custom-layout">
+    <SmartInput field="name" label="Name" />
+    <CustomSubmitButton />
+  </div>
+</BaseSmartForm>
+```
+
+---
+
+## 🎯 Field Components
+
+All field components are imported from `@algodomain/smart-forms/fields`:
+
+```tsx
+import {
+  SmartInput,
+  SmartSelect,
+  SmartCheckbox,
+  SmartRadioGroup,
+  SmartDatePicker,
+  SmartTags,
+  SmartSlider,
+  SmartDualRangeSlider,
+  SmartCombobox,
+  SmartBasicRichTextbox,
+  SmartFileUpload,
+  SmartAutoSuggestTags
+} from '@algodomain/smart-forms/fields'
+```
+
+### SmartInput
+
+Text input with support for multiple types.
+
+```tsx
+<SmartInput
+  field="username"
+  label="Username"
+  type="text"
+  placeholder="Enter username"
+  validation={z.string().min(3).max(20)}
+  required
 />
 ```
 
-### Field Props
+**Supported types:** `text`, `email`, `password`, `tel`, `number`, `textarea`
 
-All smart fields support these common props:
+### SmartSelect
 
-- `field` (required): Field name
-- `label`: Display label
-- `required`: Make field required
-- `validation`: Zod schema for validation
-- `defaultValue`: Initial value
-- `placeholder`: Placeholder text
-- `className`: Custom CSS class
-- `info`: Info tooltip text
-- `subLabel`: Additional label text
+Dropdown select field.
 
-## Theme Customization
+```tsx
+<SmartSelect
+  field="country"
+  label="Country"
+  options={[
+    { value: 'us', label: 'United States' },
+    { value: 'ca', label: 'Canada' }
+  ]}
+  required
+/>
+```
 
-### Override CSS Variables
+### SmartCheckbox
 
-Add this to your CSS file:
+Checkbox with label.
 
-```css
-:root {
-  --primary: oklch(0.5 0.2 250);        /* Custom primary color */
-  --radius: 1rem;                        /* Border radius */
-  --background: oklch(1 0 0);           /* Background color */
-  --foreground: oklch(0.145 0 0);       /* Text color */
-}
+```tsx
+<SmartCheckbox
+  field="terms"
+  label="I agree to terms"
+  validation={z.boolean().refine(val => val === true)}
+  required
+/>
+```
 
-/* Dark mode */
-.dark {
-  --background: oklch(0.145 0 0);
-  --foreground: oklch(0.985 0 0);
+### SmartRadioGroup
+
+Radio button group.
+
+```tsx
+<SmartRadioGroup
+  field="gender"
+  label="Gender"
+  options={[
+    { value: 'male', label: 'Male' },
+    { value: 'female', label: 'Female' }
+  ]}
+  alignment="horizontal"
+  required
+/>
+```
+
+### SmartDatePicker
+
+Date picker with calendar UI.
+
+```tsx
+<SmartDatePicker
+  field="birthDate"
+  label="Date of Birth"
+  validation={z.date()}
+  required
+/>
+```
+
+### SmartTags
+
+Tag input for multiple values.
+
+```tsx
+<SmartTags
+  field="skills"
+  label="Skills"
+  placeholder="Type and press Enter"
+  validation={z.array(z.string()).min(1)}
+  maxTags={10}
+  required
+/>
+```
+
+### SmartSlider
+
+Single value slider.
+
+```tsx
+<SmartSlider
+  field="experience"
+  label="Years of Experience"
+  min={0}
+  max={40}
+  step={1}
+  showValue={true}
+/>
+```
+
+### SmartDualRangeSlider
+
+Min/max range slider.
+
+```tsx
+<SmartDualRangeSlider
+  minField="minSalary"
+  maxField="maxSalary"
+  label="Salary Range"
+  min={0}
+  max={200000}
+  step={5000}
+/>
+```
+
+### SmartCombobox
+
+Searchable combo box.
+
+```tsx
+<SmartCombobox
+  field="technology"
+  label="Technology"
+  options={[
+    { value: 'react', label: 'React' },
+    { value: 'vue', label: 'Vue' }
+  ]}
+  allowCustom={true}
+/>
+```
+
+### SmartBasicRichTextbox
+
+Basic rich text editor.
+
+```tsx
+<SmartBasicRichTextbox
+  field="description"
+  label="Description"
+  minHeight="150px"
+  validation={z.string().min(50)}
+  required
+/>
+```
+
+### SmartFileUpload
+
+File upload field.
+
+```tsx
+<SmartFileUpload
+  field="resume"
+  label="Upload Resume"
+  accept=".pdf,.doc,.docx"
+  maxSize={5 * 1024 * 1024}
+  required
+/>
+```
+
+---
+
+## 🎨 Opinionated Fields
+
+Pre-configured fields with built-in validation. Import from `@algodomain/smart-forms/opinionated`:
+
+```tsx
+import {
+  FieldEmail,
+  FieldPassword,
+  FieldConfirmPassword,
+  FieldPhone,
+  FieldFirstName,
+  FieldLastName,
+  FieldFullName,
+  FieldAge,
+  FieldStreetAddress,
+  FieldCity,
+  FieldState,
+  FieldZipCode,
+  FieldMessage,
+  FieldComments
+} from '@algodomain/smart-forms/opinionated'
+```
+
+**Usage:**
+
+```tsx
+<FieldEmail field="email" required />
+<FieldPassword field="password" required />
+<FieldPhone field="phone" />
+<FieldFullName field="fullName" required />
+```
+
+---
+
+## ⚙️ Configuration Reference
+
+### Form Component Props
+
+All form components (`SmartForm`, `MultiTabSmartForm`, `BaseSmartForm`) support these props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `api` | `string` | - | API endpoint for form submission |
+| `method` | `'POST' \| 'PUT' \| 'PATCH'` | `'POST'` | HTTP method |
+| `submitButtonText` | `string` | `'Submit'` | Submit button text |
+| `submitButtonIcon` | `ReactNode` | - | Icon for submit button |
+| `allowSaveDraft` | `boolean` | `false` | Enable draft saving |
+| `saveDraftApi` | `string` | - | API endpoint for saving drafts |
+| `enableLocalStorage` | `boolean` | `false` | Save drafts to localStorage |
+| `storageKey` | `string` | `'smart-form-data'` | Key for localStorage |
+| `logFormData` | `boolean` | `false` | Log form data to console |
+| `onSuccess` | `(data: unknown) => void` | - | Success callback |
+| `onError` | `(error: unknown) => void` | - | Error callback |
+| `transformData` | `(data: any) => any` | - | Transform data before submission |
+| `className` | `string` | `'max-w-2xl mx-auto p-6 bg-white'` | Container CSS class |
+| `title` | `string` | - | Form title |
+| `subTitle` | `string` | - | Form subtitle |
+| `logo` | `ReactNode` | - | Logo to display |
+| `footer` | `ReactNode` | - | Footer content |
+| `initialData` | `Record<string, unknown>` | `{}` | Initial form values |
+| `showReset` | `boolean` | `false` | Show reset button |
+| `showProgressBar` | `boolean` | `true` | Display progress bar (MultiTab only) |
+| `showTabNumbers` | `boolean` | `true` | Show tab numbers (MultiTab only) |
+| `authentication` | `AuthenticationConfig` | - | Authentication configuration |
+| `includeQueryParams` | `boolean` | `false` | Include URL query parameters |
+| `queryParamsToInclude` | `string[]` | - | Filter specific query params |
+| `children` | `ReactNode` | - | Form content |
+
+### Authentication Configuration
+
+```typescript
+interface AuthenticationConfig {
+  enable: boolean                    // Enable authentication
+  refreshTokenEndpoint?: string      // Token refresh endpoint
+  accessTokenKey?: string            // localStorage key (default: 'accessToken')
+  refreshTokenKey?: string           // localStorage key (default: 'refreshToken')
 }
 ```
 
-### Full Tailwind Support (Optional)
+**Usage:**
 
-For complete Tailwind utility support, add to your `index.css`:
+```tsx
+<SmartForm
+  authentication={{
+    enable: true,
+    refreshTokenEndpoint: "/api/auth/refresh",
+    accessTokenKey: "accessToken",
+    refreshTokenKey: "refreshToken"
+  }}
+>
+  {/* Fields */}
+</SmartForm>
+```
 
-```css
-@source "../node_modules/@algodomain/smart-forms/dist/index.js";
-@source "../node_modules/@algodomain/smart-forms/dist/index.cjs";
+### Common Field Props
+
+All field components support these props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `field` | `string` | - | **Required.** Field identifier |
+| `label` | `string` | - | Field label |
+| `required` | `boolean` | `false` | Mark as required |
+| `validation` | `ZodSchema` | - | Zod validation schema |
+| `defaultValue` | `any` | - | Initial value |
+| `placeholder` | `string` | - | Placeholder text |
+| `className` | `string` | - | Custom CSS class |
+| `info` | `string` | - | Info tooltip text |
+| `subLabel` | `string` | - | Additional helper text |
+
+### Field-Specific Props
+
+#### SmartInput
+
+| Prop | Type | Default | Allowed Values |
+|------|------|---------|----------------|
+| `type` | `string` | `'text'` | `text`, `email`, `password`, `tel`, `number`, `textarea` |
+
+#### SmartSelect / SmartCombobox
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `Array<{value: string, label: string}>` | `[]` | Select options |
+| `allowCustom` | `boolean` | `false` | Allow custom values (Combobox only) |
+
+#### SmartRadioGroup
+
+| Prop | Type | Default | Allowed Values |
+|------|------|---------|----------------|
+| `options` | `Array<{value: string, label: string}>` | `[]` | Radio options |
+| `alignment` | `string` | `'vertical'` | `horizontal`, `vertical` |
+
+#### SmartTags
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `maxTags` | `number` | - | Maximum number of tags |
+| `maxLength` | `number` | - | Max length per tag |
+| `minLength` | `number` | - | Min length per tag |
+| `allowDuplicates` | `boolean` | `true` | Allow duplicate tags |
+
+#### SmartSlider
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `min` | `number` | `0` | Minimum value |
+| `max` | `number` | `100` | Maximum value |
+| `step` | `number` | `1` | Step increment |
+| `showValue` | `boolean` | `true` | Display current value |
+| `valueFormatter` | `(value: number) => string` | - | Format displayed value |
+
+#### SmartDualRangeSlider
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `minField` | `string` | - | **Required.** Field name for min value |
+| `maxField` | `string` | - | **Required.** Field name for max value |
+| `min` | `number` | `0` | Minimum value |
+| `max` | `number` | `100` | Maximum value |
+| `step` | `number` | `1` | Step increment |
+| `showValues` | `boolean` | `true` | Display values |
+| `valueFormatter` | `(value: number) => string` | - | Format displayed value |
+
+#### SmartBasicRichTextbox
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `minHeight` | `string` | `'150px'` | Minimum height |
+| `maxHeight` | `string` | `'400px'` | Maximum height |
+
+#### SmartFileUpload
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `accept` | `string` | - | Accepted file types |
+| `maxSize` | `number` | - | Max file size in bytes |
+
+---
+
+## 🚀 Advanced Features
+
+### Query Parameters
+
+Automatically include URL query parameters in form submissions.
+
+**Include ALL query parameters:**
+
+```tsx
+<SmartForm
+  api="/api/submit"
+  includeQueryParams={true}
+>
+  <SmartInput field="name" label="Name" />
+</SmartForm>
+```
+
+**Include SPECIFIC query parameters:**
+
+```tsx
+<SmartForm
+  api="/api/submit"
+  includeQueryParams={true}
+  queryParamsToInclude={['userId', 'companyId']}
+>
+  <SmartInput field="name" label="Name" />
+</SmartForm>
+```
+
+**Example:**
+- URL: `/form?userId=123&companyId=456`
+- Form data: `{ name: "John" }`
+- Submitted: `{ userId: "123", companyId: "456", name: "John" }`
+
+**Behavior:**
+- Form field values always override query params if names conflict
+- Works with both form submission and draft saving
+- If `queryParamsToInclude` is omitted, all query params are included
+
+### Draft Saving
+
+**Local Storage:**
+
+```tsx
+<SmartForm
+  enableLocalStorage={true}
+  storageKey="my-form-draft"
+  allowSaveDraft={true}
+>
+  {/* Fields */}
+</SmartForm>
+```
+
+**API-based Draft:**
+
+```tsx
+<SmartForm
+  allowSaveDraft={true}
+  saveDraftApi="/api/drafts"
+>
+  {/* Fields */}
+</SmartForm>
 ```
 
-This ensures Tailwind generates utilities used inside the library.
+### Data Transformation
+
+Transform form data before submission:
+
+```tsx
+<SmartForm
+  transformData={(data) => ({
+    ...data,
+    skills: data.skills?.join(','),
+    timestamp: new Date().toISOString()
+  })}
+>
+  {/* Fields */}
+</SmartForm>
+```
 
-## Authentication
+### Initial Values
 
-Enable authentication to automatically include Bearer tokens:
+Pre-populate form fields:
+
+```tsx
+<SmartForm
+  initialData={{
+    name: 'John Doe',
+    email: 'john@example.com',
+    country: 'us'
+  }}
+>
+  {/* Fields */}
+</SmartForm>
+```
+
+### Authentication
+
+Enable automatic Bearer token authentication:
 
 ```tsx
 <SmartForm
   authentication={{
     enable: true,
-    refreshTokenEndpoint: "/api/auth/refresh",  // Optional
-    accessTokenKey: "accessToken",              // Default
-    refreshTokenKey: "refreshToken"             // Default
+    refreshTokenEndpoint: "/api/auth/refresh"
   }}
-/>
+>
+  {/* Fields */}
+</SmartForm>
 ```
 
 The library will:
-1. Get the access token from localStorage
+1. Get access token from localStorage
 2. Include it as `Authorization: Bearer <token>`
-3. Automatically refresh if refresh endpoint is provided
-4. Retry the request with the new token
+3. Automatically refresh if token expires
+4. Retry the request with new token
+
+---
+
+## 🎨 Theming & Customization
+
+### CSS Variables
+
+Override the default theme by defining CSS variables:
+
+```css
+:root {
+  --radius: 0.5rem;
+  --background: white;
+  --foreground: black;
+  --primary: #3b82f6;
+  --primary-foreground: white;
+  --border: #e5e7eb;
+  --input: #e5e7eb;
+  --ring: #3b82f6;
+}
+
+.dark {
+  --background: #1f2937;
+  --foreground: white;
+  --primary: #60a5fa;
+}
+```
+
+### Tailwind Classes
+
+Customize using Tailwind utility classes:
+
+```tsx
+<SmartForm className="max-w-4xl mx-auto p-8 bg-gray-50 rounded-xl shadow-lg">
+  <SmartInput
+    field="name"
+    label="Name"
+    className="border-blue-500 focus:ring-blue-500"
+  />
+</SmartForm>
+```
+
+### Custom Submit Button
 
-## Validation
+Use `BaseSmartForm` with custom buttons:
 
-Use Zod schemas for validation:
+```tsx
+import { BaseSmartForm, useSmartForm } from '@algodomain/smart-forms'
+
+function CustomForm() {
+  return (
+    <BaseSmartForm api="/api/submit">
+      <SmartInput field="name" label="Name" />
+      <CustomSubmitButton />
+    </BaseSmartForm>
+  )
+}
+
+function CustomSubmitButton() {
+  const { submitForm, isLoading } = useSmartForm()
+  
+  return (
+    <button onClick={submitForm} disabled={isLoading}>
+      {isLoading ? 'Submitting...' : 'Submit'}
+    </button>
+  )
+}
+```
+
+---
+
+## 🪝 Hooks & Context
+
+### useSmartForm
+
+Access form context and methods.
 
 ```tsx
+import { useSmartForm } from '@algodomain/smart-forms'
+
+function MyComponent() {
+  const {
+    formData,        // Current form values
+    errors,          // Validation errors
+    isLoading,       // Submission loading state
+    isDraftSaving,   // Draft saving state
+    submitForm,      // Submit function
+    saveDraft,       // Save draft function
+    resetForm,       // Reset to initial values
+    updateField,     // Update specific field
+    config           // Form configuration
+  } = useSmartForm()
+  
+  return <button onClick={submitForm}>Submit</button>
+}
+```
+
+### useFormField
+
+Access individual field state (used internally by field components).
+
+```tsx
+import { useFormField } from '@algodomain/smart-forms'
+
+function CustomField({ field }) {
+  const { value, error, onChange } = useFormField(field)
+  
+  return (
+    <input
+      value={value || ''}
+      onChange={(e) => onChange(e.target.value)}
+    />
+  )
+}
+```
+
+---
+
+## 💡 Examples
+
+### Complete Registration Form
+
+```tsx
+import { SmartForm } from '@algodomain/smart-forms'
+import { SmartInput, SmartSelect, SmartCheckbox, SmartDatePicker } from '@algodomain/smart-forms/fields'
+import { FieldEmail, FieldPassword } from '@algodomain/smart-forms/opinionated'
 import { z } from 'zod'
+import { toast } from 'react-toastify'
 
-<SmartInput
-  field="email"
-  label="Email"
-  validation={z
-    .string()
-    .email("Invalid email")
-    .min(5, "Too short")
-  }
-  required
-/>
+export function RegistrationForm() {
+  return (
+    <SmartForm
+      api="https://api.example.com/register"
+      method="POST"
+      submitButtonText="Register"
+      onSuccess={(data) => {
+        toast.success('Account created successfully!')
+      }}
+      onError={(error) => {
+        toast.error('Registration failed.')
+      }}
+    >
+      <SmartInput
+        field="fullName"
+        label="Full Name"
+        validation={z.string().min(3)}
+        required
+      />
+      
+      <FieldEmail field="email" required />
+      <FieldPassword field="password" required />
+      
+      <SmartSelect
+        field="country"
+        label="Country"
+        options={[
+          { value: 'us', label: 'United States' },
+          { value: 'ca', label: 'Canada' },
+          { value: 'uk', label: 'United Kingdom' }
+        ]}
+        required
+      />
+      
+      <SmartDatePicker
+        field="birthDate"
+        label="Date of Birth"
+        validation={z.date().max(new Date())}
+        required
+      />
+      
+      <SmartCheckbox
+        field="terms"
+        label="I agree to the Terms and Conditions"
+        validation={z.boolean().refine(val => val === true)}
+        required
+      />
+    </SmartForm>
+  )
+}
+```
+
+### Multi-Tab Job Application
+
+```tsx
+import { MultiTabSmartForm, Tab } from '@algodomain/smart-forms'
+import { SmartInput, SmartTags, SmartDualRangeSlider } from '@algodomain/smart-forms/fields'
+import { FieldEmail, FieldPhone } from '@algodomain/smart-forms/opinionated'
+import { z } from 'zod'
+
+export function JobApplicationForm() {
+  return (
+    <MultiTabSmartForm
+      api="/api/applications"
+      method="POST"
+      showProgressBar={true}
+      showTabNumbers={true}
+      allowSaveDraft={true}
+      enableLocalStorage={true}
+      storageKey="job-application"
+    >
+      <Tab title="Personal Info">
+        <SmartInput
+          field="fullName"
+          label="Full Name"
+          validation={z.string().min(3)}
+          required
+        />
+        <FieldEmail field="email" required />
+        <FieldPhone field="phone" required />
+      </Tab>
+      
+      <Tab title="Experience">
+        <SmartDualRangeSlider
+          minField="minExperience"
+          maxField="maxExperience"
+          label="Years of Experience"
+          min={0}
+          max={40}
+          step={1}
+        />
+        <SmartTags
+          field="skills"
+          label="Skills"
+          validation={z.array(z.string()).min(3)}
+          required
+        />
+      </Tab>
+    </MultiTabSmartForm>
+  )
+}
+```
+
+### Form with Query Parameters
+
+```tsx
+// URL: /create-job?userId=123&companyId=456
+
+<SmartForm
+  api="/api/jobs"
+  includeQueryParams={true}
+  queryParamsToInclude={['userId', 'companyId']}
+>
+  <SmartInput field="jobTitle" label="Job Title" required />
+  <SmartInput field="location" label="Location" required />
+</SmartForm>
+
+// Submitted data will include:
+// { userId: "123", companyId: "456", jobTitle: "...", location: "..." }
 ```
 
-## TypeScript Support
+---
+
+## 🐛 Troubleshooting
+
+### Error: "useSmartForm must be used within a SmartFormProvider"
+
+**Cause:** Field components used outside a form wrapper.
+
+**Solution:** Wrap fields in a form component:
+
+```tsx
+// ❌ Wrong
+<SmartInput field="name" label="Name" />
+
+// ✅ Correct
+<SmartForm api="/api/submit">
+  <SmartInput field="name" label="Name" />
+</SmartForm>
+```
+
+### Styles Not Loading
+
+**Cause:** CSS not imported.
 
-Fully typed with TypeScript. Import types:
+**Solution:**
 
 ```tsx
-import type { 
-  SmartFormProps, 
-  FormConfig,
-  SmartInputProps 
-} from '@algodomain/smart-forms'
+import '@algodomain/smart-forms/style.css'
+import 'react-toastify/dist/ReactToastify.css'
+```
+
+For Tailwind v4, add `@source` directives:
+
+```css
+@source "../node_modules/@algodomain/smart-forms/dist/index.js";
 ```
 
-## Examples
+### Form Not Submitting
+
+**Cause:** Missing API endpoint or validation errors.
+
+**Solution:**
+
+1. Ensure `api` prop is set
+2. Check console for validation errors
+3. Use `logFormData={true}`:
+
+```tsx
+<SmartForm api="/api/submit" logFormData={true}>
+  {/* Fields */}
+</SmartForm>
+```
+
+### TypeScript Errors
+
+**Solution:** Install type definitions:
+
+```bash
+npm install @types/react @types/react-dom
+```
+
+---
+
+## 📖 Validation with Zod
+
+All fields support Zod schemas for validation:
+
+```tsx
+import { z } from 'zod'
+
+// String validation
+validation={z.string().min(3, "Too short").max(50, "Too long")}
+
+// Email
+validation={z.string().email("Invalid email")}
+
+// Number
+validation={z.number().min(0).max(100)}
+
+// Array
+validation={z.array(z.string()).min(1, "Required")}
+
+// Date
+validation={z.date().max(new Date(), "Cannot be future")}
+
+// Boolean
+validation={z.boolean().refine(val => val === true, {
+  message: "Must be true"
+})}
+
+// Enum
+validation={z.enum(['option1', 'option2'])}
+
+// Custom
+validation={z.string().refine(val => val.includes('@'), {
+  message: "Must contain @"
+})}
+```
 
-Check out the examples directory for more use cases:
+---
 
-- Simple contact form
-- Multi-step registration
-- Job posting form
-- User profile form
-- Complex validation scenarios
+## 🤝 Contributing
 
-## License
+Contributions welcome! Please visit our [GitHub repository](https://github.com/algodomain/smart-forms).
 
-MIT
+## 📄 License
 
-## Contributing
+MIT License - feel free to use in your projects!
 
-Contributions welcome! Please open an issue or PR on GitHub.
+## 🙋 Support
 
-## Support
+- **Issues:** [GitHub Issues](https://github.com/algodomain/smart-forms/issues)
+- **Email:** support@algodomain.com
+- **npm:** [@algodomain/smart-forms](https://www.npmjs.com/package/@algodomain/smart-forms)
 
-For issues and questions:
-- GitHub Issues: [github.com/algodomain/smart-forms](https://github.com/algodomain/smart-forms)
-- Documentation: [docs.algodomain.com](https://docs.algodomain.com)
+---
 
+**Built with ❤️ by AlgoDomain**