🛠 Bit-Form

Agnostic and performant form state management.

Bit-Form is a powerful, framework-agnostic library designed to handle complex validations, dynamic masks, and conditional logic seamlessly across modern frontend ecosystems. Build your logic once, use it anywhere.

✨ Key Features

• Framework Agnostic Core: Dedicated bindings for React, Vue, and Angular.
• First-Class Validation: Built-in schema resolvers for Zod, Yup, and Joi. Includes native support for debounced asynchronous validation.
• Advanced Masking System: Extensive list of presets including Currency (BRL, USD, EUR), Documents (CPF, CNPJ, SSN), Dates, and Credit Cards.
• Smart Dependencies: Built-in dependency manager to conditionally hide or require fields using showIf, requiredIf, and dependsOn.
• Computed Fields: Automatically calculate and update form values in real-time based on other field changes.
• Field Arrays: First-class support for dynamic lists with native methods to append, prepend, move, and swap items.
• Time-Travel DevTools: Full history support with Undo/Redo capabilities and a Remote Inspector CLI via WebSocket.

🏎 Performance & Comparison

Bit-Form was built to solve the "heavy form" problem. While most libraries re-render the entire form or require complex memoization to handle dynamic masks and deep validations, Bit-Form uses a subscription-based model that updates only the specific field being touched.

Comparison Table

React Ecosystem

| Feature | Bit-Form | React Hook Form | Formik | TanStack Form | | :-------------------------- | :----------: | :-------------: | :-------: | :-----------: | | Framework Agnostic | ✅ Yes | ❌ No | ❌ No | ✅ Yes | | Built-in Masking | ✅ Advanced | ❌ No | ❌ No | ❌ No | | Re-renders | ⚡ Minimal | ⚡ Minimal | 🐢 High | ⚡ Minimal | | Conditional Logic | ✅ Native | ⚠️ Manual | ⚠️ Manual | ✅ Native | | Time-Travel (Undo/Redo) | ✅ Native | ❌ No | ❌ No | ❌ No | | Remote DevTools | ✅ Yes | ❌ No | ❌ No | ❌ No | | Computed Fields | ✅ Native | ❌ No | ❌ No | ⚠️ Manual |

Vue Ecosystem

| Feature | Bit-Form | VeeValidate | FormKit | | :-------------------------- | :----------: | :---------: | :--------: | | Framework Agnostic | ✅ Yes | ❌ No | ❌ No | | Built-in Masking | ✅ Advanced | ❌ No | ⚠️ Plugins | | Re-renders | ⚡ Minimal | ⚡ Minimal | ⚡ Minimal | | Conditional Logic | ✅ Native | ⚠️ Manual | ✅ Native | | Time-Travel (Undo/Redo) | ✅ Native | ❌ No | ❌ No | | Remote DevTools | ✅ Yes | ❌ No | ❌ No | | Computed Fields | ✅ Native | ❌ No | ⚠️ Manual |

Angular Ecosystem

| Feature | Bit-Form | Angular Reactive Forms | ngx-formly | | :-------------------------- | :----------: | :--------------------: | :--------: | | Framework Agnostic | ✅ Yes | ❌ No | ❌ No | | Built-in Masking | ✅ Advanced | ❌ No | ❌ No | | Re-renders | ⚡ Minimal | ⚡ Minimal | ⚡ Minimal | | Conditional Logic | ✅ Native | ⚠️ Manual | ✅ Native | | Time-Travel (Undo/Redo) | ✅ Native | ❌ No | ❌ No | | Remote DevTools | ✅ Yes | ❌ No | ❌ No | | Computed Fields | ✅ Native | ⚠️ Manual | ⚠️ Manual |

Benchmark Results

Tests performed with a form containing 100 inputs, measuring the "Time to Interaction" (TTI) during a single keystroke on a mid-range device.

React Ecosystem

| Metric (lower is better) | Bit-Form | React Hook Form | Formik | | :------------------------ | :----------- | :-------------- | :----- | | Keystroke Latency | 1.2ms | 1.8ms | 14.5ms | | Validation Overhead | 0.8ms | 1.2ms | 5.4ms | | Bundle Size (Gzipped) | ~12kb | ~9kb | ~15kb |

Vue Ecosystem

| Metric (lower is better) | Bit-Form | VeeValidate | FormKit | | :------------------------ | :----------- | :---------- | :------ | | Keystroke Latency | ~1.2ms | ~2.0ms | ~2.5ms | | Validation Overhead | ~0.8ms | ~1.0ms | ~1.5ms | | Bundle Size (Gzipped) | ~12kb | ~8kb | ~25kb |

Angular Ecosystem

| Metric (lower is better) | Bit-Form | Angular Reactive Forms | ngx-formly | | :------------------------ | :----------- | :--------------------: | :--------- | | Keystroke Latency | ~1.2ms | ~1.5ms | ~2.2ms | | Validation Overhead | ~0.8ms | ~1.0ms | ~1.4ms | | Bundle Size (Gzipped) | ~12kb | ~0kb (built-in) | ~15kb |

Note: Bit-Form's slightly larger bundle size (vs. minimal libraries) is due to the included agnostic core and built-in masking engine, which saves you from installing secondary libraries like imask or cleave.js. Vue and Angular benchmarks use the same methodology as React; actual numbers may vary by form complexity and device.

Why Bit-Form?

1. Zero-Reflow Masking: Unlike other libs where masking causes a double-render (one for the raw value, one for the mask), Bit-Form handles masks at the store level before the UI even knows about it.
2. Logic Portability: You can share the exact same BitStore instance (including validations and masks) between a React web app and an Angular admin dashboard.
3. Predictable State: With the History Manager, you can track exactly how the form state evolved, making it the best choice for complex, multi-step financial or insurance forms.

📦 Installation

npm install @lehnihon/bit-form

📚 Documentation

The complete documentation is available in the /docs folder. Explore the guides below to get started:

🚀 Getting Started

• Introduction & Installation: Overview and basic setup.
• Core Concepts: Understanding the BitStore and state lifecycle.

🖼 Framework Guides

• React: Using hooks and Context Provider.
• React Native: Mobile specifics and onChangeText mapping.
• Vue: Using composables and InjectionKeys.
• Angular: Reactive forms via Signals.

🛠 Features

• Validation & Resolvers: Integrating Zod, Yup, and Joi.
• Masks & Formatting: Using and creating input masks.
• Conditional Logic: Managing field dependencies.
• Computed Fields: Handling derived form values.
• Field Arrays: Managing dynamic lists of fields.
• Scopes: Per-step validation and status for wizard forms (useBitScope, injectBitScope).
• History & Time Travel: Using Undo/Redo features.

📖 Guides & Examples

• When to Use What: Quick reference for resolver vs asyncValidate vs setServerErrors, computed vs transform, and conditional fields.
• Complete Form Example: End-to-end example with masks, asyncValidate, conditional logic, scopes, history, and DevTools.
• Server Errors: Client validation (resolver/asyncValidate) vs API 422 handling (setServerErrors, onSubmit).

🔍 DevTools

• DevTools Overview: Configuration (devTools: true or { mode: "remote" }).
• Floating Panel: In-app inspector (local mode).
• CLI & Remote Dashboard: bit-form devtools + WebSocket for React Native / remote debugging.

📑 Reference

• API Reference: Full BitStore class documentation.
• Type Definitions: Core TypeScript interfaces and types.

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

📄 License

MIT