fieldwise 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artem Kuzko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,474 @@
+# Fieldwise
+
+**Type-safe, reactive form management for React with fine-grained field subscriptions.**
+
+Fieldwise is a lightweight, event-driven form library that provides precise control over component re-renders through field-level subscriptions. No more unnecessary re-renders from unrelated field changes.
+
+## Features
+
+- ✨ **Fine-grained reactivity** - Subscribe to specific fields, not entire form state
+- 🎯 **Type-safe** - Full TypeScript support with type inference
+- 🪶 **Lightweight** - Event-driven architecture with no state in React components
+- 🔌 **Plugin system** - Extensible with custom validation and behavior
+- ⚡ **Performance** - Automatic microtask batching for synchronous updates
+- 🛡️ **Zod validation** - Built-in Zod schema validation
+
+## Installation
+
+```bash
+npm install fieldwise zod
+# or
+yarn add fieldwise zod
+# or
+pnpm add fieldwise zod
+```
+
+**Peer dependencies:**
+
+- React 18+ or React 19+
+- Zod 3.x (optional, only if using validation)
+
+## Quick Start
+
+```typescript
+import { fieldwise, validateZodSchema } from 'fieldwise';
+import { z } from 'zod';
+
+// Define your schema
+const userSchema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  email: z.string().email('Invalid email address')
+});
+
+// Infer Form values type
+type UserFormValues = z.infer<typeof schema>;
+
+// Define initial values
+const emptyUser: UserFormValues = { name: '', email: '' };
+
+// Create form hooks
+const { useForm, useSlice } = fieldwise(emptyUser)
+  .use(validateZodSchema(userSchema))
+  .hooks();
+
+// Export for use in components
+export { useForm as useUserForm, useSlice as useUserSlice };
+```
+
+```typescript
+// In your component
+import { useUserForm } from './userForm';
+
+function UserForm() {
+  const { fields, emit, once, i } = useUserForm();
+
+  const handleSubmit = (e) => {
+    e.preventDefault();
+
+    emit.later('validate'); // Defer validation to microtask
+
+    once('validated', ({ values, errors }) => {
+      if (errors) return; // Validation failed
+
+      // Submit the form
+      console.log('Submitting:', values);
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input {...i('name')} placeholder="Name" />
+      {fields.name.error && <span>{fields.name.error}</span>}
+
+      <input {...i('email')} type="email" placeholder="Email" />
+      {fields.email.error && <span>{fields.email.error}</span>}
+
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+## Core Concepts
+
+### Fine-Grained Subscriptions
+
+Unlike traditional form libraries, Fieldwise allows you to subscribe to specific fields:
+
+```typescript
+// Subscribe to ALL fields (re-renders on any change)
+const { fields } = useUserForm();
+
+// Subscribe to SPECIFIC fields only (re-renders only when email changes)
+const { fields } = useUserSlice(['email']);
+```
+
+### Event-Driven Architecture
+
+Fieldwise uses an event system for all state changes:
+
+```typescript
+const { emit, once, fields } = useUserForm();
+
+// Update a field
+emit('change', 'name', 'John Doe');
+
+// Trigger validation
+emit.later('validate');
+
+// Listen for validation results (one-time)
+once('validated', ({ values, errors }) => {
+  // Handle result
+});
+
+// Reset form
+emit('reset'); // to initial values
+emit('reset', newValues); // to specific values
+```
+
+### Input Helper
+
+The `i()` function generates all necessary props for controlled inputs:
+
+```typescript
+<input {...i('email')} />
+
+// Expands to:
+{
+  name: 'email',
+  value: fields.email.value,
+  onChange: (value) => emit('change', 'email', value),
+  error: fields.email.error
+}
+```
+
+## API Reference
+
+### `fieldwise(initialValues)`
+
+Creates a form builder with the specified initial values.
+
+```typescript
+const builder = fieldwise({ name: '', email: '' });
+```
+
+### `.use(plugin)`
+
+Applies a plugin to the form. Plugins can add validation, logging, or custom behavior.
+
+```typescript
+builder.use(validateZodSchema(schema)).use(myEventHandler); // Chain multiple plugins
+```
+
+### `.hooks()`
+
+Generates React hooks for the form.
+
+```typescript
+const { useForm, useSlice } = builder.hooks();
+```
+
+### `useForm()`
+
+Hook that subscribes to all form fields.
+
+**Returns:**
+
+- `fields: FieldSet<T>` - Object containing all fields with `{ value, error, isTouched }`
+- `emit: EmitFn` - Function to trigger events
+- `once: OneTimeFn` - Function to listen to events once
+- `isTouched: boolean` - Whether any field has been modified
+- `i: InputHelper` - Function to generate input props
+
+### `useSlice(keys)`
+
+Hook that subscribes to specific form fields.
+
+```typescript
+const { fields, emit, i } = useUserSlice(['email', 'name']);
+// Only re-renders when email or name changes
+```
+
+### Events
+
+Available events:
+
+- `change` - Field value changed: `emit('change', key, value)`
+- `changeSome` - Multiple fields changed: `emit('changeSome', { field1: value1, field2: value2 })`
+- `touch` - Mark field as touched: `emit('touch', key)`
+- `touchSome` - Mark multiple fields as touched: `emit('touchSome', [key1, key2])`
+- `validate` - Validation requested: `emit('validate')`
+- `validated` - Validation completed: `once('validated', ({ values, errors }) => {})`
+- `reset` - Form reset: `emit('reset', snapshot?)`
+
+## Validation
+
+### Zod Schema Validation
+
+```typescript
+import { validateZodSchema } from 'fieldwise';
+import { z } from 'zod';
+
+const schema = z
+  .object({
+    email: z.email(),
+    password: z.string().min(8, 'Must be at least 8 characters'),
+    confirmPassword: z.string()
+  })
+  .refine((data) => data.password === data.confirmPassword, {
+    message: 'Passwords must match',
+    path: ['confirmPassword']
+  });
+type UserValues = z.infer<typeof schema>;
+
+const emptyUser: UserValues = { email: '', password: '', confirmPassword: '' };
+const { useForm } = fieldwise(emptyUser).use(validateZodSchema(schema)).hooks();
+```
+
+The validation plugin:
+
+- Handles schema refinements with custom paths
+- Returns errors as strings (can be integrated with i18n libraries if needed)
+- Supports `z.coerce` for HTML input type coercion
+- Error format: `{ field: 'error message' }` as `Record<keyof T, string | null>`
+
+### Custom Validation Plugin
+
+```typescript
+const customValidation = (form) => {
+  form.on('validate', async () => {
+    const values = form.getValues();
+
+    // Your validation logic
+    const errors = await validateAsync(values);
+
+    form.emit('validated', { values, errors });
+  });
+};
+
+fieldwise(initialValues).use(customValidation).hooks();
+```
+
+## Advanced Usage
+
+### Conditional Fields
+
+```typescript
+function RegistrationForm() {
+  const { fields, emit, i } = useForm();
+
+  // Show/hide based on field value
+  return (
+    <form>
+      <select {...i('accountType')}>
+        <option value="personal">Personal</option>
+        <option value="business">Business</option>
+      </select>
+
+      {fields.accountType.value === 'business' && (
+        <input {...i('companyName')} placeholder="Company Name" />
+      )}
+    </form>
+  );
+}
+```
+
+### Async Validation
+
+```typescript
+const asyncValidation = (form) => {
+  form.on('validate', async () => {
+    const values = form.getValues();
+
+    // Async check (e.g., username availability)
+    const isAvailable = await checkUsernameAvailability(values.username);
+
+    const errors = isAvailable
+      ? null
+      : { username: 'Username is already taken' };
+
+    form.emit('validated', { values, errors });
+  });
+};
+```
+
+### Debug Mode
+
+Enable debug logging by setting `Form.debugMode`:
+
+```typescript
+import { Form } from 'fieldwise';
+
+// Log all events
+Form.debugMode = true;
+
+// Log only specific events
+Form.debugMode = { only: ['reset', 'validate', 'validated'] };
+```
+
+Debug plugin is attached automatically when debug mode is enabled.
+
+### Material-UI Integration
+
+**Note**: Material-UI inputs require custom wrappers since their API differs from standard HTML inputs. You'll need to create wrapper components that adapt the `i()` helper props to Material-UI's expected props.
+
+```typescript
+import TextField from '@mui/material/TextField';
+
+const TextFieldWrapper = ({ name, value, onChange, error }) => (
+  <TextField
+    name={name}
+    value={value}
+    onChange={(e) => onChange(e.target.value)}
+    label={name}
+    helperText={error}
+    error={!!error}
+  />
+);
+
+function MyForm() {
+  const { i } = useMyForm();
+
+  return <TextFieldWrapper {...i('email')} />;
+}
+```
+
+## Performance Optimization
+
+### Prevent Unnecessary Re-renders
+
+```typescript
+// ❌ Bad: Re-renders on ANY field change
+const { fields } = useUserForm();
+
+// ✅ Good: Only re-renders when email or password changes
+const { fields } = useUserSlice(['email', 'password']);
+```
+
+### Microtask Batching
+
+Fieldwise automatically batches synchronous updates:
+
+```typescript
+emit('change', 'name', 'John');
+emit('change', 'email', 'john@example.com');
+// Both updates trigger only ONE re-render
+```
+
+### Validation Deferral
+
+Use `emit.later()` to defer validation to the microtask queue:
+
+```typescript
+const handleSubmit = () => {
+  emit.later('validate'); // Defers to microtask
+
+  once('validated', ({ values, errors }) => {
+    // Runs after all synchronous updates complete
+  });
+};
+```
+
+## TypeScript Support
+
+Fieldwise is written in TypeScript and provides full type inference:
+
+```typescript
+type User = {
+  name: string;
+  email: string;
+  age: number;
+};
+
+const { useForm } = fieldwise<User>({
+  name: '',
+  email: '',
+  age: 0
+}).hooks();
+
+const { fields, emit, i } = useForm();
+
+// ✅ Type-safe
+emit('change', 'name', 'John');
+fields.name.value; // string
+
+// ❌ Type errors
+emit('change', 'invalid', 'value'); // Error: 'invalid' is not a valid key
+emit('change', 'age', 'not a number'); // Error: expected number
+```
+
+## Migration Guide
+
+### From Formik
+
+```typescript
+// Formik
+const formik = useFormik({
+  initialValues: { email: '' },
+  validationSchema: schema,
+  onSubmit: (values) => { ... }
+});
+
+// Fieldwise
+const { fields, emit, once, i } = useForm();
+const handleSubmit = () => {
+  emit.later('validate');
+  once('validated', ({ values, errors }) => {
+    if (!errors) onSubmit(values);
+  });
+};
+```
+
+### From React Hook Form
+
+```typescript
+// React Hook Form
+const {
+  register,
+  handleSubmit,
+  formState: { errors }
+} = useForm();
+
+// Fieldwise
+const { i, emit, once, fields } = useForm();
+// Errors available at fields.fieldName.error
+```
+
+## Plugin Development
+
+Create custom plugins to extend Fieldwise:
+
+```typescript
+const myPlugin = (form) => {
+  // Listen to events
+  form.on('change', (key, value) => {
+    console.log(`${key} changed to ${value}`);
+  });
+
+  // Emit events
+  form.on('validate', () => {
+    const values = form.getValues();
+    // Custom validation logic
+    form.emit('validated', { values, errors: null });
+  });
+};
+
+fieldwise(initialValues).use(myPlugin).hooks();
+```
+
+## Contributing
+
+Contributions are welcome! Please follow these guidelines:
+
+- Maintain zero React state in Form class
+- Keep plugins composable and single-responsibility
+- Add tests for new features
+- Document all public API changes
+
+## License
+
+MIT
+
+## Credits
+
+Extracted from a production application managing 15+ complex forms with dynamic validation, conditional fields, and multi-step flows.

package/dist/Form.d.ts

@@ -0,0 +1,63 @@
+export type Field<T> = {
+    value: T;
+    error: string | null;
+    isTouched: boolean;
+};
+export type FieldSet<T extends Values> = {
+    [K in keyof T]: Field<T[K]>;
+};
+export type FieldSubscriber<T> = (field: Field<T>) => void;
+export type FieldUnsubscribeFn = () => void;
+export type EventHandler<TArgs extends unknown[] = []> = (...args: TArgs) => void;
+export type EventUnsubscribeFn = () => void;
+export type Values = Record<string, unknown>;
+export type Errors<T extends Values> = Partial<Record<keyof T, string>>;
+export type EventMap<T extends Values> = {
+    change: [key: keyof T, value: T[keyof T]];
+    changeSome: [payload: Partial<T>];
+    touch: [key: keyof T];
+    touchSome: [keys: (keyof T)[]];
+    reset: [snapshot?: T];
+    errors: [errors: Errors<T>];
+    validate: [];
+    validated: [
+        payload: {
+            values: T;
+            errors: Errors<T> | null;
+        }
+    ];
+};
+export type EmitFn<T extends Values> = <K extends keyof EventMap<T>>(event: K, ...args: EventMap<T>[K]) => void;
+export type DebugMode = boolean | DebugModeConfig;
+export type DebugModeConfig = {
+    only: (keyof EventMap<Values>)[];
+};
+export declare class Form<T extends Values> {
+    static debugMode: DebugMode;
+    initialValues: T;
+    private fields;
+    private fieldSubscribers;
+    private eventHandlers;
+    private eventQueue;
+    constructor(initialValues: T);
+    getValue<K extends keyof T>(key: K): T[K];
+    getValues(): T;
+    get<K extends keyof T>(key: K): Field<T[K]>;
+    setValue<K extends keyof T>(key: K, value: T[K]): void;
+    setValues(newValues: Partial<T>): void;
+    touch<K extends keyof T>(key: K): void;
+    setError<K extends keyof T>(key: K, error: string | null): void;
+    setErrors(newErrors: Partial<Record<keyof T, string>>): void;
+    reset(snapshot: T): void;
+    getSlice<K extends keyof T>(keys: readonly K[]): Pick<FieldSet<T>, K>;
+    subscribeField<K extends keyof T>(key: K, callback: FieldSubscriber<T[K]>): FieldUnsubscribeFn;
+    on<E extends keyof EventMap<T>>(event: E, handler: EventHandler<EventMap<T>[E]>): EventUnsubscribeFn;
+    once<E extends keyof EventMap<T>>(event: E, handler: EventHandler<EventMap<T>[E]>): void;
+    emit: EmitFn<T>;
+    emitLater: EmitFn<T>;
+    private doEmit;
+    private processQueuedEvents;
+    private notify;
+    private valuesToFields;
+}
+//# sourceMappingURL=Form.d.ts.map

package/dist/Form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Form.d.ts","sourceRoot":"","sources":["../src/Form.ts"],"names":[],"mappings":"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"}