npm package: @akson/cortex-forms
Description: Reusable form state management library for React applications
Author: Akson
Latest version: 0.2.0
Deprecated: Deprecated: no consumers. No longer maintained.

# @akson/cortex-forms

A powerful and type-safe form management library for React applications.

## Features

- **Type-safe**: Full TypeScript support with intelligent type inference
- **Change tracking**: Automatic detection of form changes
- **State management**: Built-in loading, error, and validation states
- **Flexible**: Works with any form UI library or custom components
- **Validation**: Optional validation with custom validators
- **Context support**: Share form state across components
- **Lightweight**: Minimal dependencies

## Installation

```bash
npm install @akson/cortex-forms
```

## Quick Start

```tsx
import { useForm } from '@akson/cortex-forms'

interface UserProfile {
  name: string
  email: string
  age: number
}

function ProfileForm() {
  const form = useForm<UserProfile>({
    initialData: { name: '', email: '', age: 0 },
    onSave: async (data) => {
      // Save to API
      const response = await api.updateProfile(data)
      return response.data // Return updated data to sync state
    },
    onSuccess: (data) => console.log('Saved:', data),
    onError: (error) => console.error('Error:', error)
  })

  return (
    <div>
      <input
        value={form.state.data.name}
        onChange={(e) => form.actions.updateField('name', e.target.value)}
        placeholder="Name"
      />

      <input
        value={form.state.data.email}
        onChange={(e) => form.actions.updateField('email', e.target.value)}
        placeholder="Email"
      />

      <div>
        <button
          onClick={form.actions.save}
          disabled={!form.state.hasChanges || form.state.isLoading}
        >
          {form.state.isLoading ? 'Saving...' : 'Save'}
        </button>

        <button
          onClick={form.actions.cancel}
          disabled={!form.state.hasChanges}
        >
          Cancel
        </button>
      </div>

      {form.state.hasChanges && (
        <p>You have unsaved changes</p>
      )}
    </div>
  )
}
```

## API Reference

### `useForm<T>(options: FormOptions<T>)`

Creates a form instance with the given options.

#### Options

- `initialData: T` - Initial form data
- `onSave: (data: T) => Promise<T | void>` - Save handler
- `onCancel?: () => void` - Cancel handler
- `onError?: (error: Error) => void` - Error handler
- `onSuccess?: (data: T) => void` - Success handler
- `validator?: (data: T) => Record<keyof T, string | null> | null` - Validation function

#### Returns

```tsx
{
  state: {
    data: T                    // Current form data
    originalData: T           // Original data for comparison
    hasChanges: boolean       // Whether form has changes
    isLoading: boolean        // Whether save is in progress
    error: Error | null       // Last error
  },
  actions: {
    updateField: (field: keyof T, value: any) => void
    updateData: (data: Partial<T>) => void
    reset: () => void         // Reset to initial data
    resetToOriginal: () => void // Reset to original data
    save: () => Promise<void>
    cancel: () => void
  },
  validation: {
    errors: Record<keyof T, string | null> | null
    isValid: boolean
    validate: () => boolean
  }
}
```

## Advanced Usage

### With Validation

```tsx
const form = useForm({
  initialData: { email: '', password: '' },
  validator: (data) => {
    const errors = {} as any
    if (!data.email) errors.email = 'Email is required'
    if (data.password.length < 6) errors.password = 'Password must be at least 6 characters'
    return Object.keys(errors).length > 0 ? errors : null
  },
  onSave: async (data) => await api.login(data)
})
```

### With Context (for multi-component forms)

```tsx
import { FormProvider, useFormContext } from '@akson/cortex-forms'

function App() {
  const form = useForm({ /* options */ })

  return (
    <FormProvider form={form}>
      <PersonalInfo />
      <AddressInfo />
      <FormActions />
    </FormProvider>
  )
}

function PersonalInfo() {
  const { state, actions } = useFormContext()
  // Use form state and actions
}
```

### Built-in Components

```tsx
import { FormProvider, FormActions } from '@akson/cortex-forms'

function MyForm() {
  const form = useForm({ /* options */ })

  return (
    <FormProvider form={form}>
      {/* Your form fields */}

      <FormActions
        saveText="Update Profile"
        cancelText="Reset"
        showCancel={true}
      />
    </FormProvider>
  )
}
```

## License

MIT