form-hook-kit 1.2.0

package/README.md

@@ -0,0 +1,753 @@
+# form-hook-kit
+
+A lightweight, flexible form management library for React and React Native with a hooks-based API and Yup validation.
+
+**Author:** bc-bane  
+**License:** MIT  
+**Platform tested:** React 18+ & React Native
+
+---
+
+## Features
+
+- **Type-safe** - Full TypeScript support with 100% type coverage
+- **Cross-platform** - Works with React and React Native
+- **React Native Compatible** - No native iOS/Android code - works with legacy architecture, new architecture, and Android 16KB page size
+- **Validation** - Powered by Yup for robust schema validation
+- **Hooks-based** - Modern React hooks API
+- **Context-based** - Efficient state management with React Context
+- **Performant** - Memoized functions, optional debounced validation, minimal re-renders
+- **Developer Tools** - Built-in DevTools component for debugging (development only)
+- **Flexible** - Works with any UI component library
+- **Well-tested** - 100% test coverage
+- **Production-ready** - Comprehensive documentation and examples
+
+---
+
+## Why form-hook-kit?
+
+### Comparison with Other Form Libraries
+
+#### vs. Formik
+
+**Key Differences:**
+- **API Style** - form-hook-kit is hooks-only, Formik supports both hooks and render props
+- **React Native** - Both support React Native with different approaches
+- **Yup Integration** - Both have built-in Yup support
+- **Community** - Formik has larger community and more plugins
+
+**When to use Formik instead:**
+- You need a battle-tested library with years of production use
+- You want access to a larger ecosystem of community plugins
+- Your project already uses Formik
+
+#### vs. React Hook Form
+
+**Key Differences:**
+- **State Management** - form-hook-kit uses Context, React Hook Form uses refs
+- **Input Style** - form-hook-kit uses controlled inputs, React Hook Form uses uncontrolled
+- **Yup Integration** - form-hook-kit has built-in support, React Hook Form requires resolver
+- **Performance** - React Hook Form may be faster for very large forms
+- **Popularity** - React Hook Form has larger user base
+
+**When to use React Hook Form instead:**
+- You need uncontrolled inputs for maximum performance
+- You prefer ref-based form tracking
+- You have very large forms (100+ fields)
+
+#### vs. Final Form
+
+**Key Differences:**
+- **API Style** - form-hook-kit is hooks-only, Final Form uses subscriptions
+- **TypeScript** - form-hook-kit is TypeScript-first, Final Form has TypeScript support
+- **React Version** - form-hook-kit requires React 16.8+, Final Form supports older versions
+- **Maturity** - Final Form is more established
+
+**When to use Final Form instead:**
+- You need field-level subscriptions for complex performance optimization
+- You're migrating from Redux Form
+- You need to support older React versions
+
+#### vs. Custom Solutions
+
+**Advantages over rolling your own:**
+- **Well-tested** - 100% test coverage with comprehensive test suite
+- **Edge cases handled** - Validation, error handling, field refs all included
+- **TypeScript support** - Full type safety out of the box
+- **Ready to use** - No need to build and maintain form infrastructure
+- **Documentation** - Complete docs and examples
+
+### Feature Comparison Table
+
+| Feature | form-hook-kit | Formik | React Hook Form | Final Form |
+|---------|-------------------|--------|-----------------|------------|
+| React Native Support | ✓ Native | ✓ Supported | ✓ Supported | ✓ Supported |
+| TypeScript | ✓ First-class | ✓ Supported | ✓ First-class | ✓ Supported |
+| Yup Integration | ✓ Built-in | ✓ Built-in | Via resolver | Via plugin |
+| API Style | Context + Hooks | Context + Hooks | Refs + Hooks | Subscriptions |
+| Hooks-only API | ✓ Yes | Mixed | ✓ Yes | Mixed |
+| Built-in Field Refs | ✓ Yes | ✓ Yes | ✓ Yes | ✓ Yes |
+| Learning Curve | Low | Low-Medium | Medium | Medium-High |
+
+### When to Choose form-hook-kit
+
+Choose `form-hook-kit` if you:
+- Are building a React or React Native app
+- Need React Native new architecture compatibility (no native code dependencies)
+- Want a simple, hooks-based API
+- Prefer context-based state management
+- Need TypeScript support with 100% type coverage
+- Use Yup for validation
+- Want built-in Yup integration without extra packages
+- Prefer controlled inputs over uncontrolled
+- Need compatibility with Android 16KB page size
+
+---
+
+## Installation
+
+```bash
+npm install form-hook-kit yup
+# or
+yarn add form-hook-kit yup
+# or
+pnpm add form-hook-kit yup
+```
+
+---
+
+## Quick Start
+
+### Basic Example (React Web)
+
+```tsx
+import React from 'react';
+import * as yup from 'yup';
+import {FormProvider, useForm, useFormField} from 'form-hook-kit';
+
+// Define your validation schema
+const schema = yup.object({
+  email: yup.string().email('Invalid email').required('Email is required'),
+  password: yup
+    .string()
+    .min(8, 'Password must be at least 8 characters')
+    .required('Password is required'),
+});
+
+// Create form fields
+function EmailField() {
+  const {value, error, onChange, onBlur} = useFormField('email');
+
+  return (
+    <div>
+      <input
+        type="email"
+        value={value || ''}
+        onChange={onChange}
+        onBlur={onBlur}
+        placeholder="Email"
+      />
+      {error && <span className="error">{error}</span>}
+    </div>
+  );
+}
+
+function PasswordField() {
+  const {value, error, onChange, onBlur} = useFormField('password');
+
+  return (
+    <div>
+      <input
+        type="password"
+        value={value || ''}
+        onChange={onChange}
+        onBlur={onBlur}
+        placeholder="Password"
+      />
+      {error && <span className="error">{error}</span>}
+    </div>
+  );
+}
+
+// Create your form
+function LoginForm() {
+  const {validateForm, values} = useForm();
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    const errors = validateForm();
+
+    if (Object.values(errors).every(error => !error)) {
+      // Form is valid, submit it
+      console.log('Form submitted:', values);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <EmailField />
+      <PasswordField />
+      <button type="submit">Login</button>
+    </form>
+  );
+}
+
+// Wrap with FormProvider
+export default function App() {
+  return (
+    <FormProvider
+      schema={schema}
+      initialValues={{email: '', password: ''}}
+    >
+      <LoginForm />
+    </FormProvider>
+  );
+}
+```
+
+### React Native Example
+
+> **Note:** form-hook-kit has **zero native dependencies** - it's pure JavaScript/TypeScript. This means it's fully compatible with:
+> - ✅ React Native legacy architecture
+> - ✅ React Native new architecture (Fabric & TurboModules)
+> - ✅ Android 16KB page size requirement
+> - ✅ Expo (including Expo Go)
+>
+> **📱 For detailed React Native usage and platform-specific features, see [REACT_NATIVE.md](REACT_NATIVE.md)**
+
+```tsx
+import React from 'react';
+import {View, TextInput, Text, Button} from 'react-native';
+import * as yup from 'yup';
+import {FormProvider, useFormField, useForm} from 'form-hook-kit';
+
+const schema = yup.object({
+  username: yup.string().required('Username is required'),
+  email: yup.string().email('Invalid email').required('Email is required'),
+});
+
+function UsernameField() {
+  const {value, error, onChangeValue, onBlur, setRef} = useFormField('username');
+
+  return (
+    <View>
+      <TextInput
+        ref={setRef}
+        value={value || ''}
+        onChangeText={onChangeValue}
+        onBlur={onBlur}
+        placeholder="Username"
+      />
+      {error && <Text style={{color: 'red'}}>{error}</Text>}
+    </View>
+  );
+}
+
+function EmailField() {
+  const {value, error, onChangeValue, onBlur, setRef} = useFormField('email');
+
+  return (
+    <View>
+      <TextInput
+        ref={setRef}
+        value={value || ''}
+        onChangeText={onChangeValue}
+        onBlur={onBlur}
+        placeholder="Email"
+        keyboardType="email-address"
+      />
+      {error && <Text style={{color: 'red'}}>{error}</Text>}
+    </View>
+  );
+}
+
+function SignupForm() {
+  const {validateForm, values} = useForm();
+
+  const handleSubmit = () => {
+    const errors = validateForm();
+
+    if (Object.values(errors).every(error => !error)) {
+      console.log('Form submitted:', values);
+    }
+  };
+
+  return (
+    <View>
+      <UsernameField />
+      <EmailField />
+      <Button title="Sign Up" onPress={handleSubmit} />
+    </View>
+  );
+}
+
+export default function App() {
+  return (
+    <FormProvider
+      schema={schema}
+      initialValues={{username: '', email: ''}}
+    >
+      <SignupForm />
+    </FormProvider>
+  );
+}
+```
+
+---
+
+## API Reference
+
+For advanced usage including custom form implementations and direct access to utility functions, see [ADVANCED_USAGE.md](./ADVANCED_USAGE.md).
+
+### `FormProvider`
+
+The main component that wraps your form and provides context.
+
+**Props:**
+
+- `schema` (required): Yup validation schema
+- `initialValues` (optional): Initial form values (default: `{}`)
+- `initialErrors` (optional): Initial error state (default: `{}`)
+- `validationDebounce` (optional): Debounce validation in milliseconds for performance optimization (default: `0`)
+- `children` (required): Form components
+
+```tsx
+<FormProvider
+  schema={yupSchema}
+  initialValues={{email: '', password: ''}}
+  initialErrors={{}}
+  validationDebounce={300} // Optional: debounce validation for better performance
+>
+  {children}
+</FormProvider>
+```
+
+### `useForm()`
+
+Hook to access the form context. Must be used within a `FormProvider`.
+
+**Returns:**
+
+- `values`: Object containing all form values
+- `errors`: Object containing all form errors
+- `fieldRefs`: Ref object for managing field focus
+- `changeValue(params)`: Function to update a single field
+- `changeValues(values)`: Function to update multiple fields
+- `clearError(name)`: Function to clear error for a field
+- `setError(params)`: Function to set error for a field
+- `validateField(name, value?)`: Function to validate a single field
+- `validateForm()`: Function to validate entire form
+
+```tsx
+const {
+  values,
+  errors,
+  changeValue,
+  validateForm,
+  fieldRefs,
+} = useForm();
+```
+
+### `useFormField(name)`
+
+Convenient hook for managing a single form field. Provides pre-configured handlers.
+
+**Parameters:**
+
+- `name` (string): The field name
+
+**Returns:**
+
+- `value`: Current field value
+- `error`: Current field error
+- `name`: Field name
+- `onChange`: Handler for React web inputs (e.target.value)
+- `onChangeValue`: Handler for React Native or custom value changes
+- `onBlur`: Handler for field blur (triggers validation)
+- `onFocus`: Handler for field focus (clears errors)
+- `setRef`: Function to set field ref for focus management
+
+```tsx
+const {value, error, onChange, onBlur} = useFormField('email');
+```
+
+### `useFormPerformance()`
+
+**NEW in v1.2.0** - Hook to monitor form performance metrics. Useful for debugging and optimization.
+
+**Returns:**
+
+- `renderCount`: Number of times the component has rendered
+- `lastRenderTime`: Time taken for the last render (ms)
+- `validationCount`: Number of validations performed
+- `averageValidationTime`: Average validation time (ms)
+- `fieldChangeCount`: Number of field changes
+
+```tsx
+import {useFormPerformance} from 'form-hook-kit';
+
+function MyForm() {
+  const metrics = useFormPerformance();
+  
+  console.log('Renders:', metrics.renderCount);
+  console.log('Avg validation time:', metrics.averageValidationTime);
+  
+  return <div>...</div>;
+}
+```
+
+### `useValidationPerformance()`
+
+**NEW in v1.2.0** - Hook to track validation performance with timing metrics.
+
+```tsx
+import {useValidationPerformance} from 'form-hook-kit';
+
+function MyForm() {
+  const {validateField, validateForm, metrics} = useValidationPerformance();
+  
+  const handleSubmit = () => {
+    validateForm();
+    console.log('Validation took:', metrics.lastValidationTime, 'ms');
+  };
+  
+  return <button onClick={handleSubmit}>Submit</button>;
+}
+```
+
+### `FormDevTools`
+
+**NEW in v1.2.0** - Cross-platform development tool for inspecting form state and performance.
+
+**Platform Support:**
+- **Web**: Visual UI panel (default)
+- **React Native**: Console logging mode (works with React Native Debugger, Flipper, or Metro logs)
+
+**Import from separate entry point:**
+
+```tsx
+import {FormDevTools} from 'form-hook-kit/devtools';
+
+// Web - shows UI panel
+function WebForm() {
+  return (
+    <FormProvider schema={schema}>
+      <MyFormFields />
+      {process.env.NODE_ENV === 'development' && <FormDevTools />}
+    </FormProvider>
+  );
+}
+
+// React Native - logs to console
+function MobileForm() {
+  return (
+    <FormProvider schema={schema}>
+      <MyFormFields />
+      {__DEV__ && <FormDevTools mode="console" autoLog />}
+    </FormProvider>
+  );
+}
+```
+
+**Props:**
+- `mode?: 'ui' | 'console' | 'none'` - Display mode (auto-detects platform by default)
+- `autoLog?: boolean` - Auto-log changes in console mode (default: `false`)
+- `logPrefix?: string` - Custom log prefix (default: `'[FormDevTools]'`)
+- `position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'` - UI panel position (default: `'bottom-right'`)
+- `defaultOpen?: boolean` - UI panel open by default (default: `true`)
+
+**Console Mode (React Native):**
+
+When using `mode="console"`, you can manually inspect form state:
+
+```tsx
+// In React Native Debugger or browser console:
+global.formDevTools.logValues()   // Log current values
+global.formDevTools.logErrors()   // Log current errors
+global.formDevTools.logMetrics()  // Log performance metrics
+global.formDevTools.logAll()      // Log everything
+```
+
+**Props:**
+
+- `position` (optional): `'top-left'` | `'top-right'` | `'bottom-left'` | `'bottom-right'` (default: `'bottom-right'`)
+- `defaultOpen` (optional): Whether to show by default (default: `false`)
+
+---
+
+## Advanced Usage
+
+### Performance Optimization
+
+**Debounced Validation:**
+
+For forms with real-time validation, you can debounce validation to improve performance:
+
+```tsx
+<FormProvider
+  schema={schema}
+  validationDebounce={300} // Wait 300ms after user stops typing
+>
+  <MyForm />
+</FormProvider>
+```
+
+**Performance Monitoring:**
+
+Track and optimize your form's performance:
+
+```tsx
+import {useFormPerformance} from 'form-hook-kit';
+
+function MyForm() {
+  const metrics = useFormPerformance();
+  
+  // Log performance in development
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'development') {
+      console.log('Form Performance:', metrics);
+    }
+  }, [metrics]);
+  
+  return <div>...</div>;
+}
+```
+
+### Custom Validation
+
+```tsx
+import * as yup from 'yup';
+
+const schema = yup.object({
+  password: yup.string().required('Password is required'),
+  confirmPassword: yup
+    .string()
+    .oneOf([yup.ref('password')], 'Passwords must match')
+    .required('Confirm password is required'),
+});
+```
+
+### Manual Field Validation
+
+```tsx
+function MyField() {
+  const {values, errors, changeValue, validateField} = useForm();
+
+  const handleChange = (value: string) => {
+    changeValue({name: 'email', value});
+    // Validate immediately on change
+    validateField('email', value);
+  };
+
+  return (
+    <input
+      value={values.email || ''}
+      onChange={(e) => handleChange(e.target.value)}
+    />
+  );
+}
+```
+
+### Setting Errors Manually
+
+```tsx
+function MyForm() {
+  const {setError, clearError} = useForm();
+
+  const handleCustomValidation = () => {
+    if (someCondition) {
+      setError({name: 'email', error: 'Custom error message'});
+    } else {
+      clearError('email');
+    }
+  };
+
+  return (
+    // ...
+  );
+}
+```
+
+### Focus Management (React Native)
+
+```tsx
+function MyForm() {
+  const {fieldRefs} = useForm();
+
+  const focusNextField = () => {
+    // Focus the email field
+    fieldRefs.current.email?.focus();
+  };
+
+  return (
+    <View>
+      <TextInput
+        ref={(ref) => (fieldRefs.current.username = ref)}
+        onSubmitEditing={() => fieldRefs.current.email?.focus()}
+        returnKeyType="next"
+      />
+      <TextInput
+        ref={(ref) => (fieldRefs.current.email = ref)}
+        returnKeyType="done"
+      />
+    </View>
+  );
+}
+```
+
+### Updating Multiple Values
+
+```tsx
+function MyForm() {
+  const {changeValues} = useForm();
+
+  const resetForm = () => {
+    changeValues({
+      email: '',
+      password: '',
+      username: '',
+    });
+  };
+
+  return (
+    <button onClick={resetForm}>Reset</button>
+  );
+}
+```
+
+### Custom Formatters
+
+```tsx
+function PhoneField() {
+  const {value, error, onChangeValue, onBlur} = useFormField('phone');
+
+  const formatPhone = (text: string) => {
+    // Remove non-digits
+    const digits = text.replace(/\D/g, '');
+    // Format as (XXX) XXX-XXXX
+    if (digits.length <= 3) return digits;
+    if (digits.length <= 6) return `(${digits.slice(0, 3)}) ${digits.slice(3)}`;
+    return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6, 10)}`;
+  };
+
+  return (
+    <input
+      value={value || ''}
+      onChange={(e) => onChangeValue(formatPhone(e.target.value))}
+      onBlur={onBlur}
+    />
+  );
+}
+```
+
+---
+
+## TypeScript Support
+
+Full TypeScript support with type inference:
+
+```tsx
+import {FormProvider, useForm, useFormField} from 'form-hook-kit';
+import * as yup from 'yup';
+
+interface FormValues {
+  email: string;
+  password: string;
+}
+
+const schema = yup.object({
+  email: yup.string().email().required(),
+  password: yup.string().min(8).required(),
+});
+
+function MyForm() {
+  const {values, errors} = useForm();
+  // values and errors are properly typed based on schema
+}
+```
+
+---
+
+## Testing
+
+Example test using React Testing Library:
+
+```tsx
+import {render, screen, fireEvent} from '@testing-library/react';
+import * as yup from 'yup';
+import {FormProvider, useForm} from 'form-hook-kit';
+
+const schema = yup.object({
+  email: yup.string().email().required(),
+});
+
+test('validates email field', async () => {
+  function TestForm() {
+    const {values, errors, changeValue, validateField} = useForm();
+
+    return (
+      <div>
+        <input
+          data-testid="email"
+          value={values.email || ''}
+          onChange={(e) => changeValue({name: 'email', value: e.target.value})}
+          onBlur={() => validateField('email')}
+        />
+        {errors.email && <span data-testid="error">{errors.email}</span>}
+      </div>
+    );
+  }
+
+  render(
+    <FormProvider schema={schema} initialValues={{email: ''}}>
+      <TestForm />
+    </FormProvider>
+  );
+
+  const input = screen.getByTestId('email');
+  fireEvent.change(input, {target: {value: 'invalid'}});
+  fireEvent.blur(input);
+
+  expect(await screen.findByTestId('error')).toBeInTheDocument();
+});
+```
+
+---
+
+## Performance Tips
+
+1. **Memoize handlers**: Use `useCallback` for event handlers if needed
+2. **Split forms**: Break large forms into smaller sub-forms
+3. **Lazy validation**: Validate on blur instead of on every keystroke
+4. **Schema optimization**: Keep Yup schemas simple and efficient
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Validation not working | Ensure your Yup schema is properly defined and passed to FormProvider |
+| Field not updating | Check that you're using the correct field name and onChange handler |
+| TypeScript errors | Make sure your form values interface matches your Yup schema |
+| React Native TextInput issues | Use `onChangeText` with `onChangeValue` instead of `onChange` |
+
+---
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details
+
+---
+
+## Credits
+
+**Author:** bc-bane  
+Built for production use in React and React Native applications.  
+Designed to be simple, performant, and flexible.