@algodomain/smart-forms 0.1.8 → 0.1.10

package/README.md

@@ -19,8 +19,11 @@ Built with TypeScript, Tailwind CSS, Zod validation, and shadcn/ui components.
 - [Opinionated Fields](#-opinionated-fields)
 - [Configuration Reference](#-configuration-reference)
 - [Advanced Features](#-advanced-features)
+- [UI Components](#-ui-components)
+- [Button Components](#-button-components)
 - [Theming](#-theming--customization)
 - [Hooks & Context](#-hooks--context)
+- [Context Providers](#-context-providers)
 - [Examples](#-examples)
 - [Troubleshooting](#-troubleshooting)
 - [Contributing](#-contributing)
@@ -199,16 +202,35 @@ Multi-step form with tabs and progress tracking.
   api="/api/submit"
   showProgressBar={true}
   showTabNumbers={true}
+  animateTabs={false}
+  tabType="default"
 >
-  <Tab title="Step 1">
+  <Tab title="Step 1" onNext={async () => { /* custom logic */ }}>
     {/* Fields */}
   </Tab>
-  <Tab title="Step 2">
+  <Tab title="Step 2" processingOverlay={<LoadingSpinner />}>
     {/* Fields */}
   </Tab>
 </MultiTabSmartForm>
 ```
 
+**Additional Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `animateTabs` | `boolean` | `false` | Enable tab transition animations |
+| `tabType` | `'underline' \| 'default'` | `'default'` | Tab styling variant |
+| `disableManualTabSwitch` | `boolean` | `false` | Prevent manual clicking on future tabs. Users can still navigate forward via Next button and go back to previous tabs. |
+
+**Tab Component Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `string` | **Required.** Tab title |
+| `children` | `ReactNode` | Tab content |
+| `onNext` | `() => Promise<void> \| void` | Callback executed before moving to next tab. Can be async. If it throws, navigation is prevented. |
+| `processingOverlay` | `ReactNode` | Overlay shown while `onNext` is processing |
+
 ### BaseSmartForm
 
 Low-level form component for custom layouts.
@@ -224,6 +246,63 @@ Low-level form component for custom layouts.
 </BaseSmartForm>
 ```
 
+### FormFieldGroup
+
+A layout component for grouping form fields horizontally with responsive spacing. Fields automatically wrap to multiple rows on smaller screens.
+
+**Usage:**
+
+```tsx
+import { FormFieldGroup } from '@algodomain/smart-forms'
+import { SmartInput, SmartSelect } from '@algodomain/smart-forms/fields'
+
+<SmartForm api="/api/submit">
+  <FormFieldGroup>
+    <SmartInput field="firstName" label="First Name" />
+    <SmartInput field="lastName" label="Last Name" />
+  </FormFieldGroup>
+  
+  <FormFieldGroup>
+    <SmartInput field="city" label="City" />
+    <SmartSelect field="state" label="State" options={stateOptions} />
+    <SmartInput field="zipCode" label="Zip Code" />
+  </FormFieldGroup>
+</SmartForm>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | **Required.** Form field components to group |
+| `className` | `string` | `''` | Additional CSS classes to apply |
+
+**Features:**
+- Responsive flex layout with automatic wrapping
+- Spacing: `gap-2` on mobile, `gap-4` on medium screens and above
+- Bottom margin: `mb-4` for consistent spacing between groups
+
+**Example: Address Form with Grouped Fields**
+
+```tsx
+<SmartForm api="/api/submit">
+  <FormFieldGroup>
+    <SmartInput field="streetAddress" label="Street Address" required />
+  </FormFieldGroup>
+  
+  <FormFieldGroup>
+    <SmartInput field="city" label="City" required />
+    <SmartSelect field="state" label="State" options={states} required />
+    <SmartInput field="zipCode" label="Zip Code" required />
+  </FormFieldGroup>
+  
+  <FormFieldGroup className="gap-6">
+    <SmartInput field="country" label="Country" required />
+    <SmartSelect field="phoneCode" label="Phone Code" options={phoneCodes} />
+  </FormFieldGroup>
+</SmartForm>
+```
+
 ---
 
 ## 🎯 Field Components
@@ -477,6 +556,9 @@ All form components (`SmartForm`, `MultiTabSmartForm`, `BaseSmartForm`) support
 | `showReset` | `boolean` | `false` | Show reset button |
 | `showProgressBar` | `boolean` | `true` | Display progress bar (MultiTab only) |
 | `showTabNumbers` | `boolean` | `true` | Show tab numbers (MultiTab only) |
+| `animateTabs` | `boolean` | `false` | Enable tab animations (MultiTab only) |
+| `tabType` | `'underline' \| 'default'` | `'default'` | Tab styling variant (MultiTab only) |
+| `disableManualTabSwitch` | `boolean` | `false` | Prevent manual clicking on future tabs (MultiTab only) |
 | `authentication` | `AuthenticationConfig` | - | Authentication configuration |
 | `includeQueryParams` | `boolean` | `false` | Include URL query parameters |
 | `queryParamsToInclude` | `string[]` | - | Filter specific query params |
@@ -598,6 +680,214 @@ All field components support these props:
 
 ## 🚀 Advanced Features
 
+### Disable Manual Tab Switching
+
+Control whether users can manually click on future tabs. When enabled, users must complete each step sequentially using the Next button, but can still go back to previous tabs.
+
+**Usage:**
+
+```tsx
+<MultiTabSmartForm
+  api="/api/submit"
+  disableManualTabSwitch={true}
+>
+  <Tab title="Step 1">
+    <SmartInput field="name" label="Name" required />
+  </Tab>
+  
+  <Tab title="Step 2">
+    <SmartInput field="email" label="Email" required />
+  </Tab>
+  
+  <Tab title="Step 3">
+    <SmartInput field="phone" label="Phone" required />
+  </Tab>
+</MultiTabSmartForm>
+```
+
+**Behavior:**
+- When `disableManualTabSwitch={true}`:
+  - Users **cannot** click on tabs ahead of the current tab
+  - Future tabs appear disabled (grayed out)
+  - Users **can** click on previous tabs to go back
+  - Users **can** navigate forward using the Next button (after validation)
+- When `disableManualTabSwitch={false}` (default):
+  - Users can freely click on any tab
+  - All tabs are clickable
+
+**Use Cases:**
+- Enforce sequential completion of multi-step forms
+- Ensure users complete each step before proceeding
+- Prevent skipping validation steps
+- Guide users through a structured workflow
+
+### Tab Callbacks and Processing Overlays
+
+In MultiTabSmartForm, you can add custom logic before moving to the next tab using the `onNext` callback. This is useful for async operations like API calls or data processing.
+
+**Basic Usage:**
+
+```tsx
+<MultiTabSmartForm api="/api/submit">
+  <Tab 
+    title="Step 1"
+    onNext={async () => {
+      // Custom validation or API call
+      const response = await fetch('/api/validate-step1')
+      if (!response.ok) {
+        throw new Error('Validation failed')
+      }
+    }}
+  >
+    <SmartInput field="name" label="Name" required />
+  </Tab>
+  
+  <Tab title="Step 2">
+    <SmartInput field="email" label="Email" required />
+  </Tab>
+</MultiTabSmartForm>
+```
+
+**With Processing Overlay:**
+
+```tsx
+import { LoadingSpinner } from '@algodomain/smart-forms'
+
+<MultiTabSmartForm api="/api/submit">
+  <Tab 
+    title="Processing Step"
+    onNext={async () => {
+      // Long-running operation
+      await processData()
+    }}
+    processingOverlay={
+      <div className="flex flex-col items-center gap-2">
+        <LoadingSpinner className="h-8 w-8" />
+        <p>Processing your data...</p>
+      </div>
+    }
+  >
+    <SmartInput field="data" label="Data" required />
+  </Tab>
+</MultiTabSmartForm>
+```
+
+**Error Handling:**
+
+If `onNext` throws an error, navigation to the next tab is prevented and the error message is displayed:
+
+```tsx
+<Tab 
+  title="Step 1"
+  onNext={async () => {
+    const result = await validateData()
+    if (!result.valid) {
+      throw new Error(result.message) // Navigation prevented, error shown
+    }
+  }}
+>
+  {/* Fields */}
+</Tab>
+```
+
+### External Forms Integration
+
+You can integrate external forms (forms outside the MultiTabSmartForm component) with the tab system for validation and navigation.
+
+**Method 1: Manual Registration (Recommended for known fields)**
+
+```tsx
+import { useExternalFormFields } from '@algodomain/smart-forms'
+
+function ExternalForm() {
+  // Register fields for tab index 0
+  useExternalFormFields(['name', 'email', 'phone'], 0)
+  
+  return (
+    <div>
+      <input name="name" />
+      <input name="email" />
+      <input name="phone" />
+    </div>
+  )
+}
+
+// In your MultiTabSmartForm
+<MultiTabSmartForm api="/api/submit">
+  <Tab title="Step 1">
+    <ExternalForm />
+  </Tab>
+</MultiTabSmartForm>
+```
+
+**Method 2: Auto-Detection (Recommended for dynamic fields)**
+
+```tsx
+import { useExternalTab, ExternalFieldProvider } from '@algodomain/smart-forms'
+import { SmartInput } from '@algodomain/smart-forms/fields'
+
+function ExternalForm() {
+  const { registerField, ExternalFieldProvider } = useExternalTab()
+  
+  return (
+    <ExternalFieldProvider registerField={registerField}>
+      <SmartInput field="name" label="Name" />
+      <SmartInput field="email" label="Email" />
+    </ExternalFieldProvider>
+  )
+}
+```
+
+**Method 3: Using TabIndexProvider**
+
+```tsx
+import { TabIndexProvider, useExternalFormFields } from '@algodomain/smart-forms'
+
+function ExternalForm() {
+  const tabIndexContext = useTabIndex()
+  const tabIndex = tabIndexContext?.tabIndex ?? 0
+  
+  useExternalFormFields(['field1', 'field2'], tabIndex)
+  
+  return <div>{/* Your form */}</div>
+}
+
+// Wrap with TabIndexProvider
+<TabIndexProvider tabIndex={0}>
+  <ExternalForm />
+</TabIndexProvider>
+```
+
+### Submit Hooks
+
+Register custom hooks to execute before form submission. Useful for file uploads or other async operations.
+
+```tsx
+import { useSmartForm } from '@algodomain/smart-forms'
+
+function FileUploadField() {
+  const { registerSubmitHook, unregisterSubmitHook } = useSmartForm()
+  const field = 'resume'
+  
+  useEffect(() => {
+    const key = `upload-${field}`
+    
+    const uploadHook = async () => {
+      // Upload file before form submission
+      await uploadFile(file)
+    }
+    
+    registerSubmitHook(key, uploadHook)
+    
+    return () => {
+      unregisterSubmitHook(key)
+    }
+  }, [field, file])
+  
+  return <input type="file" />
+}
+```
+
 ### Conditional Field Disabling
 
 Disable fields or submit buttons based on form data values. Supports both static boolean values and dynamic functions.
@@ -946,6 +1236,146 @@ The library will:
 
 ---
 
+## 🧩 UI Components
+
+### FormHeader
+
+Display form title, subtitle, and logo.
+
+```tsx
+import { FormHeader } from '@algodomain/smart-forms'
+
+<FormHeader 
+  title="Registration Form"
+  subTitle="Please fill in your details"
+  logo={<img src="/logo.png" alt="Logo" />}
+/>
+```
+
+### Section
+
+Section divider with optional text.
+
+```tsx
+import { Section } from '@algodomain/smart-forms'
+
+<Section text="Personal Information" />
+```
+
+### Footer
+
+Footer component for form content.
+
+```tsx
+import { Footer } from '@algodomain/smart-forms'
+
+<Footer>
+  <p className="text-sm text-gray-500">
+    By submitting, you agree to our terms and conditions.
+  </p>
+</Footer>
+```
+
+### ToastContainerWrapper
+
+Toast notification container (automatically included in forms).
+
+```tsx
+import { ToastContainerWrapper } from '@algodomain/smart-forms'
+
+<ToastContainerWrapper />
+```
+
+## 🔘 Button Components
+
+### LoadingSpinner
+
+Loading spinner component.
+
+```tsx
+import { LoadingSpinner } from '@algodomain/smart-forms'
+
+<LoadingSpinner className="h-6 w-6" />
+```
+
+### SubmitButton
+
+Submit button with loading state.
+
+```tsx
+import { SubmitButton } from '@algodomain/smart-forms'
+
+<SubmitButton
+  onClick={handleSubmit}
+  disabled={isLoading}
+  isLoading={isLoading}
+>
+  Submit Form
+</SubmitButton>
+```
+
+### DraftSaveButton
+
+Draft save button.
+
+```tsx
+import { DraftSaveButton } from '@algodomain/smart-forms'
+
+<DraftSaveButton
+  onClick={handleSaveDraft}
+  disabled={isDraftSaving}
+/>
+```
+
+### ResetButton
+
+Reset form button.
+
+```tsx
+import { ResetButton } from '@algodomain/smart-forms'
+
+<ResetButton onClick={handleReset} />
+```
+
+### NavigationButtons
+
+Navigation buttons for multi-tab forms.
+
+```tsx
+import { NavigationButtons } from '@algodomain/smart-forms'
+
+<NavigationButtons
+  onPrevious={handlePrevious}
+  onNext={handleNext}
+  onSubmit={handleSubmit}
+  onSaveDraft={handleSaveDraft}
+  onReset={handleReset}
+  isLoading={isLoading}
+  isDraftSaving={isDraftSaving}
+  config={config}
+  isFirstTab={false}
+  isLastTab={false}
+  disabled={false}
+/>
+```
+
+### SimpleFormButtons
+
+Simple button group for single-page forms.
+
+```tsx
+import { SimpleFormButtons } from '@algodomain/smart-forms'
+
+<SimpleFormButtons
+  onSubmit={handleSubmit}
+  onSaveDraft={handleSaveDraft}
+  onReset={handleReset}
+  isLoading={isLoading}
+  isDraftSaving={isDraftSaving}
+  config={config}
+/>
+```
+
 ## 🎨 Theming & Customization
 
 ### CSS Variables
@@ -1025,21 +1455,36 @@ 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
+    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
+    validateField,         // Validate a single field
+    validateFields,        // Validate multiple fields
+    validateFormAndGetResult, // Validate entire form and return boolean
+    registerSubmitHook,    // Register a hook to run before submission
+    unregisterSubmitHook,  // Unregister a submit hook
+    setErrors,             // Manually set validation errors
+    config                 // Form configuration
   } = useSmartForm()
   
   return <button onClick={submitForm}>Submit</button>
 }
 ```
 
+**Methods:**
+
+- `validateField(field: string, value: any): boolean` - Validate a single field
+- `validateFields(fields: string[]): boolean` - Validate multiple fields
+- `validateFormAndGetResult(): boolean` - Validate entire form and return result
+- `registerSubmitHook(key: string, hook: () => Promise<void>): void` - Register a hook to execute before form submission
+- `unregisterSubmitHook(key: string): void` - Unregister a submit hook
+- `setErrors(errors: Record<string, string>): void` - Manually set validation errors
+
 ### useFormField
 
 Access individual field state (used internally by field components).
@@ -1059,6 +1504,170 @@ function CustomField({ field }) {
 }
 ```
 
+### useFormWrapper
+
+Alias for `useSmartForm` (for convenience).
+
+```tsx
+import { useFormWrapper } from '@algodomain/smart-forms'
+
+function MyComponent() {
+  const { formData, submitForm } = useFormWrapper()
+  // Same as useSmartForm
+}
+```
+
+### useTabIndex
+
+Get the current tab index in a MultiTabSmartForm.
+
+```tsx
+import { useTabIndex } from '@algodomain/smart-forms'
+
+function MyComponent() {
+  const tabIndexContext = useTabIndex()
+  const tabIndex = tabIndexContext?.tabIndex ?? 0
+  
+  return <div>Current tab: {tabIndex + 1}</div>
+}
+```
+
+### useExternalFormRegistration
+
+Register external forms with MultiTabSmartForm for validation and tab navigation.
+
+```tsx
+import { useExternalFormRegistration } from '@algodomain/smart-forms'
+
+function ExternalForm() {
+  const { registerTabFields, currentTabIndex } = useExternalFormRegistration()
+  
+  useEffect(() => {
+    registerTabFields(currentTabIndex, ['field1', 'field2'])
+  }, [])
+  
+  return <div>{/* Your form fields */}</div>
+}
+```
+
+### useExternalFormFields
+
+Register fields from external forms with a specific tab index.
+
+```tsx
+import { useExternalFormFields } from '@algodomain/smart-forms'
+
+function ExternalForm() {
+  useExternalFormFields(['field1', 'field2'], 0) // Register fields for tab 0
+  
+  return <div>{/* Your form fields */}</div>
+}
+```
+
+### useAutoDetectFields
+
+Automatically detect and register fields in external forms.
+
+```tsx
+import { useAutoDetectFields, ExternalFieldProvider } from '@algodomain/smart-forms'
+
+function ExternalForm() {
+  const { registerField, ExternalFieldProvider } = useAutoDetectFields(0)
+  
+  return (
+    <ExternalFieldProvider registerField={registerField}>
+      <SmartInput field="name" label="Name" />
+      <SmartInput field="email" label="Email" />
+    </ExternalFieldProvider>
+  )
+}
+```
+
+### useExternalTab
+
+Automatically detect both tab index and fields in external forms (recommended).
+
+```tsx
+import { useExternalTab, ExternalFieldProvider } from '@algodomain/smart-forms'
+
+function ExternalForm() {
+  const { registerField, ExternalFieldProvider } = useExternalTab()
+  
+  return (
+    <ExternalFieldProvider registerField={registerField}>
+      <SmartInput field="name" label="Name" />
+      <SmartInput field="email" label="Email" />
+    </ExternalFieldProvider>
+  )
+}
+```
+
+### useFieldDetection
+
+Access field detection context (used internally by field components).
+
+```tsx
+import { useFieldDetection } from '@algodomain/smart-forms'
+
+function CustomField({ field }) {
+  const context = useFieldDetection()
+  
+  useEffect(() => {
+    if (context) {
+      context.registerField(field)
+    }
+  }, [field, context])
+  
+  return <input />
+}
+```
+
+## 🔌 Context Providers
+
+### TabIndexProvider
+
+Provide tab index context to child components.
+
+```tsx
+import { TabIndexProvider, useTabIndex } from '@algodomain/smart-forms'
+
+function MyComponent() {
+  return (
+    <TabIndexProvider tabIndex={0}>
+      <ChildComponent />
+    </TabIndexProvider>
+  )
+}
+
+function ChildComponent() {
+  const context = useTabIndex()
+  const tabIndex = context?.tabIndex ?? 0
+  return <div>Tab: {tabIndex}</div>
+}
+```
+
+### ExternalFieldProvider
+
+Provider for automatic field detection in external forms.
+
+```tsx
+import { ExternalFieldProvider } from '@algodomain/smart-forms'
+
+function ExternalForm() {
+  const registerField = (fieldName: string) => {
+    // Register field with parent form
+    console.log('Registering field:', fieldName)
+  }
+  
+  return (
+    <ExternalFieldProvider registerField={registerField}>
+      <SmartInput field="name" label="Name" />
+      <SmartInput field="email" label="Email" />
+    </ExternalFieldProvider>
+  )
+}
+```
+
 ---
 
 ## 💡 Examples
@@ -1066,7 +1675,7 @@ function CustomField({ field }) {
 ### Complete Registration Form
 
 ```tsx
-import { SmartForm } from '@algodomain/smart-forms'
+import { SmartForm, FormHeader, Section, Footer } 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'
@@ -1086,6 +1695,13 @@ export function RegistrationForm() {
         toast.error('Registration failed.')
       }}
     >
+      <FormHeader 
+        title="Create Your Account"
+        subTitle="Join us today and get started"
+      />
+      
+      <Section text="Personal Information" />
+      
       <SmartInput
         field="fullName"
         label="Full Name"
@@ -1096,6 +1712,8 @@ export function RegistrationForm() {
       <FieldEmail field="email" required />
       <FieldPassword field="password" required />
       
+      <Section text="Location" />
+      
       <SmartSelect
         field="country"
         label="Country"
@@ -1121,12 +1739,20 @@ export function RegistrationForm() {
         required
       />
       
+      <Section text="Agreements" />
+      
       <SmartCheckbox
         field="terms"
         label="I agree to the Terms and Conditions"
         validation={z.boolean().refine(val => val === true)}
         required
       />
+      
+      <Footer>
+        <p className="text-sm text-gray-500 text-center">
+          By submitting, you agree to our terms and conditions.
+        </p>
+      </Footer>
     </SmartForm>
   )
 }
@@ -1135,7 +1761,7 @@ export function RegistrationForm() {
 ### Multi-Tab Job Application
 
 ```tsx
-import { MultiTabSmartForm, Tab } from '@algodomain/smart-forms'
+import { MultiTabSmartForm, Tab, LoadingSpinner } 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'
@@ -1147,11 +1773,23 @@ export function JobApplicationForm() {
       method="POST"
       showProgressBar={true}
       showTabNumbers={true}
+      animateTabs={true}
+      tabType="underline"
+      disableManualTabSwitch={true}
       allowSaveDraft={true}
       enableLocalStorage={true}
       storageKey="job-application"
     >
-      <Tab title="Personal Info">
+      <Tab 
+        title="Personal Info"
+        onNext={async () => {
+          // Validate with external API before proceeding
+          const response = await fetch('/api/validate-personal-info')
+          if (!response.ok) {
+            throw new Error('Personal information validation failed')
+          }
+        }}
+      >
         <SmartInput
           field="fullName"
           label="Full Name"
@@ -1162,7 +1800,15 @@ export function JobApplicationForm() {
         <FieldPhone field="phone" required />
       </Tab>
       
-      <Tab title="Experience">
+      <Tab 
+        title="Experience"
+        processingOverlay={
+          <div className="flex flex-col items-center gap-2">
+            <LoadingSpinner className="h-8 w-8" />
+            <p>Processing experience data...</p>
+          </div>
+        }
+      >
         <SmartDualRangeSlider
           minField="minExperience"
           maxField="maxExperience"
@@ -1183,6 +1829,41 @@ export function JobApplicationForm() {
 }
 ```
 
+### Form with External Components
+
+```tsx
+import { MultiTabSmartForm, Tab, useExternalTab, ExternalFieldProvider } from '@algodomain/smart-forms'
+import { SmartInput } from '@algodomain/smart-forms/fields'
+
+// External form component
+function ExternalAddressForm() {
+  const { registerField, ExternalFieldProvider } = useExternalTab()
+  
+  return (
+    <ExternalFieldProvider registerField={registerField}>
+      <SmartInput field="street" label="Street" required />
+      <SmartInput field="city" label="City" required />
+      <SmartInput field="zipCode" label="Zip Code" required />
+    </ExternalFieldProvider>
+  )
+}
+
+// Main form
+export function FormWithExternalComponents() {
+  return (
+    <MultiTabSmartForm api="/api/submit">
+      <Tab title="Basic Info">
+        <SmartInput field="name" label="Name" required />
+      </Tab>
+      
+      <Tab title="Address">
+        <ExternalAddressForm />
+      </Tab>
+    </MultiTabSmartForm>
+  )
+}
+```
+
 ### Form with Query Parameters
 
 ```tsx