@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

npm install @akson/cortex-forms

Quick Start

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

{
  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

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)

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

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