react-formesh 0.1.4

package/README.md

@@ -0,0 +1,191 @@
+# ForMesh
+
+**Multi-section forms for React, without the re-render tax.**
+
+`@mhasansagor/formesh` is a small, framework-agnostic form state library built for forms that outgrow `useState` — long ERP/CRM-style forms made of independent sections, each merging into one plain JavaScript object, with validation, debounced sync, and derived fields as first-class primitives instead of hand-rolled hooks per component.
+
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](/LICENSE)
+[![Status](https://img.shields.io/badge/status-active%20development-orange.svg)]()
+[![Tests](https://img.shields.io/badge/tests-124%20passing-brightgreen.svg)]()
+[![Core size](https://img.shields.io/badge/core-3.4%20KB%20gzip-success.svg)]()
+
+---
+
+## Why ForMesh
+
+Most form libraries assume one flat form. Real enterprise forms rarely look like that — an employee record is Personal Info + Job Info + Bank Info + Documents, each built as its own component, all merging into one object to submit. Wiring that by hand means the same plumbing rewritten in every section: sync-to-parent, type-sniffing `onChange` handlers, visual-only validation, and re-renders that cascade across the whole form on every keystroke.
+
+ForMesh starts from that problem instead of retrofitting it:
+
+- **Sections are a first-class primitive**, not a convention you maintain yourself. Each section owns its slice; the parent always has the complete, merged object.
+- **Fine-grained by construction.** The store only clones the branch that changed (structural sharing), so a component subscribed to one field never re-renders when an unrelated field changes — no memoization, no selectors to get right.
+- **Debounced sync and derived fields are one primitive, not two.** The same `createDebouncedSync` wrapper fronts a whole store, a single section, or a future array row — and it composes straight into the same hooks as the un-wrapped target.
+- **Validation is a plain function, not a schema DSL.** `(value, context) => message | undefined`. Ship the built-ins, or write a domain rule in one line.
+- **Nearly zero dependencies.** No lodash, no schema-validation runtime baked into core. `~3.4 KB` gzip for the core, `~3.9 KB` for the React bindings — pay only for what you import.
+
+## Installation
+
+```bash
+npm install @mhasansagor/formesh
+# or
+pnpm add @mhasansagor/formesh
+```
+
+> **Status:** ForMesh is under active development and not yet published to the public npm registry. The API below reflects what's implemented and tested today; `/file` and `/array` entry points are reserved for upcoming phases (see [Roadmap](#roadmap)).
+
+## Quick start
+
+```tsx
+import { createFormStore } from "@mhasansagor/formesh";
+import { useForm } from "@mhasansagor/formesh/react";
+
+const store = createFormStore({ firstName: "", email: "" });
+
+function ProfileForm() {
+  const form = useForm(store);
+  const firstName = form.registerField("firstName");
+  const email = form.registerField("email");
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); console.log(form.values); }}>
+      <input {...firstName} />
+      <input {...email} />
+      <button type="submit" disabled={!form.isValid}>Save</button>
+    </form>
+  );
+}
+```
+
+## Multi-section forms
+
+Each section is built independently and reads/writes its own slice — the parent store ends up with the full merged object, with no manual wiring in between.
+
+```tsx
+const store = createFormStore({
+  employeeInfo: { firstName: "", lastName: "" },
+  jobInfo: { department: "", designation: "" },
+  bankInfo: { accountNumber: "", bankName: "" },
+});
+
+function EmployeeInfoSection() {
+  const form = useForm(store, { section: "employeeInfo" });
+  return <input {...form.registerField("firstName")} />;
+}
+
+function JobInfoSection() {
+  const form = useForm(store, { section: "jobInfo" });
+  return <input {...form.registerField("department")} />;
+}
+
+// store.getValues() → { employeeInfo: {...}, jobInfo: {...}, bankInfo: {...} }
+```
+
+## Validation
+
+Validators are plain functions — pure, synchronous, composable. Use the built-ins or write your own; both compose identically.
+
+```tsx
+import { required, email, minLength } from "@mhasansagor/formesh/validators";
+
+const form = useForm(store, {
+  validation: {
+    fields: {
+      firstName: required(),
+      email: [required(), email()],
+      sku: (value, { values }) =>
+        values.existingSkus.includes(value) ? "SKU already exists." : undefined,
+    },
+    form: (values) =>
+      values.endDate < values.startDate
+        ? { endDate: "End date must be after start date." }
+        : undefined,
+  },
+});
+
+form.errors;    // { email: "Enter a valid email address." }
+form.isValid;   // false
+```
+
+## Debounced sync & derived fields
+
+One wrapper, any target — a whole store, a section, or (soon) an array row. Writes batch and commit after a quiet period; reads stay live the whole time.
+
+```tsx
+import { useDebouncedSync } from "@mhasansagor/formesh/react";
+
+function EmployeeInfoSection() {
+  const section = useForm(store, { section: "employeeInfo" });
+  const sync = useDebouncedSync(section, { delay: 300 });
+  const form = useForm(sync); // composes straight in — same hooks, buffered target
+  return <input {...form.registerField("firstName")} />;
+}
+```
+
+Derived and cascading fields subscribe to one path and react to real changes only:
+
+```tsx
+import { useWatch } from "@mhasansagor/formesh/react";
+
+useWatch(store, "jobInfo.department", (department) => {
+  store.setValue("jobInfo.designation", "");
+});
+```
+
+## Why not just React Context?
+
+A Context-based form re-renders every consumer on every keystroke, regardless of which field they read. ForMesh instead exposes a subscribable store (`useSyncExternalStore` under the hood) where each write only touches the objects along its own path — so a field's re-render is gated by whether *its own* value actually changed, not by anything else in the form. No `Controller` ceremony required for third-party inputs that don't expose a ref.
+
+## Roadmap
+
+| Phase | Status |
+|---|---|
+| Core store, sections, `useForm` | ✅ Shipped |
+| Field registration & normalization | ✅ Shipped |
+| Debounced sync & `watch` | ✅ Shipped |
+| Validation (`/validators`) | ✅ Shipped |
+| File uploads (`/file`) | ✅ Shipped |
+| Field arrays (`/array`) | ✅ Shipped |
+| TypeScript path autocomplete, `FormDebugger` | 📋 Planned |
+
+## Repository structure
+
+This is a pnpm workspace. This file is the single source of truth for the library's documentation — it physically lives here, at `packages/formesh/README.md`, and the repo root's `README.md` is a **symlink** to this exact file, so both locations always show identical, up-to-date content with nothing to keep in sync manually.
+
+```
+formesh/
+├── README.md                → symlink → packages/formesh/README.md
+├── packages/
+│   └── formesh/
+│       ├── README.md        → the real file (this one)
+│       ├── src/
+│       └── tests/
+├── examples/
+│   └── basic-react/         → example app (planned)
+├── LICENSE
+├── .github/workflows/       → CI pipeline
+└── .changeset/               → versioning config
+```
+
+## Contributing
+
+From the repo root:
+
+```bash
+pnpm install     # install all workspace dependencies
+pnpm lint        # ESLint, across all packages
+pnpm typecheck   # tsc --noEmit, strict mode, across all packages
+pnpm test        # Vitest, across all packages
+pnpm build       # tsup, all entry points
+```
+
+Please run the full pipeline above before opening a pull request — CI runs the same commands and will fail on any regression.
+
+Edit this file directly (`packages/formesh/README.md`) — the root `README.md` is a symlink to it, so there is nothing separate to keep updated.
+
+## Author
+
+Built by **Mehedi Hasan** ([@mhasansagor](https://github.com/mhasansagor)), out of real multi-module ERP form work, and generalized to be useful well beyond it.
+
+## License
+
+Apache License, Version 2.0 — see the [`LICENSE`](/LICENSE) file, or the [official license text](https://www.apache.org/licenses/LICENSE-2.0).

package/dist/array.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=array.cjs.map
+//# sourceMappingURL=array.cjs.map

package/dist/array.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"array.cjs"}

package/dist/array.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/array.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/array.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=array.js.map
+//# sourceMappingURL=array.js.map

package/dist/array.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"array.js"}

package/dist/field-CLlwd7BC.d.ts

@@ -0,0 +1,134 @@
+import { F as FormValues, a as FieldPath, S as StoreListener, U as Unsubscribe, W as WatchListener } from './validation-gIT3Xn9h.js';
+
+/**
+ * The minimal read/write/subscribe surface `createDebouncedSync` (and the
+ * React hooks) need from whatever sits behind them.
+ *
+ * `FormStore`, `FormSection`, and `DebouncedSync` all satisfy this
+ * structurally — which is the whole point: there is exactly ONE
+ * debounced-sync wrapper, and whether it fronts a whole store, a section
+ * slice, or (via `createFormSection`) an array row's object slice is
+ * decided by the target handed to it, not by a second implementation.
+ * The same surface is what lets a wrapper be handed straight to
+ * `useForm`/`useFormField`/`useWatch` or wrapped in another
+ * `createDebouncedSync`.
+ *
+ * Members are declared with method syntax (see the note on `FormStore`
+ * for why — property-syntax function members break structural
+ * assignability of typed targets under `strictFunctionTypes`).
+ */
+interface SyncTarget<TValues extends FormValues = FormValues> {
+    getValues(): TValues;
+    getValue(path: FieldPath): unknown;
+    setValue(path: FieldPath, value: unknown): void;
+    setValues(partial: Partial<TValues>): void;
+    reset(nextInitialValues?: TValues): void;
+    /** The committed baseline (what `reset()` restores to), never buffered writes. */
+    getInitialValues(): TValues;
+    subscribe(listener: StoreListener): Unsubscribe;
+    /**
+     * Observes one path (including its subtree) across changes, firing the
+     * listener only when the value actually changed (deep equality). Present
+     * on all implementations (store, section, debounced sync), so `useWatch`
+     * and derived-field logic compose against any target the same way.
+     */
+    watch(path: FieldPath, listener: WatchListener): Unsubscribe;
+}
+interface DebouncedSyncOptions {
+    /**
+     * Milliseconds to wait after the last buffered write before committing to
+     * the target (trailing-edge debounce). Defaults to 300ms.
+     */
+    delay?: number;
+}
+/**
+ * A buffering layer in front of any SyncTarget. Writes land in a pending
+ * batch and commit to the target in ONE transactional write after `delay`
+ * ms of quiet; reads see the buffered writes immediately (read-through),
+ * so a UI rendering from the wrapper never lags behind typing even though
+ * the parent store updates on the debounce.
+ *
+ * It deliberately exposes the same surface shape as its target (members in
+ * method syntax, see `SyncTarget`), so it can itself be wrapped, watched,
+ * composed, and handed to the React hooks the same way.
+ */
+interface DebouncedSync<TValues extends FormValues = FormValues> {
+    /** The configured debounce delay in milliseconds. */
+    readonly delay: number;
+    /** How many writes are currently buffered and not yet committed. */
+    readonly pendingCount: number;
+    /**
+     * Current values including any buffered-but-uncommitted writes. The
+     * returned snapshot is cached between changes, making it safe as a
+     * `useSyncExternalStore` getSnapshot.
+     */
+    getValues(): TValues;
+    /** Reads a single value by path, including buffered writes. */
+    getValue(path: FieldPath): unknown;
+    /** Buffers a single write and (re)schedules the debounced commit. */
+    setValue(path: FieldPath, value: unknown): void;
+    /** Buffers a partial merge (same shallow-merge semantics as the target). */
+    setValues(partial: Partial<TValues>): void;
+    /** Drops all pending writes and forwards the reset to the target. */
+    reset(nextInitialValues?: TValues): void;
+    /**
+     * The target's committed baseline (what `reset()` restores to),
+     * delegated straight through to the wrapped target. Buffered writes are
+     * deliberately NOT part of the baseline — they are uncommitted edits.
+     */
+    getInitialValues(): TValues;
+    /**
+     * Subscribes to changes. Listeners fire immediately when writes are
+     * buffered (with the read-through changed paths) and when the target
+     * changes for reasons other than this wrapper's own flush.
+     */
+    subscribe(listener: StoreListener): Unsubscribe;
+    /** Observes one path (read-through) across buffered and committed changes. */
+    watch(path: FieldPath, listener: WatchListener): Unsubscribe;
+    /** Commits everything buffered right now and clears the timer. */
+    flush(): void;
+    /** Drops everything buffered and clears the timer. Target is untouched. */
+    cancel(): void;
+}
+
+/**
+ * Context passed to a normalizer alongside the raw input value.
+ * Kept intentionally small in Phase 1 — extend only when a real normalizer
+ * needs more (e.g. sibling values), not speculatively.
+ */
+interface NormalizeContext {
+    /** The dot-path of the field being normalized. */
+    path: string;
+}
+/**
+ * A normalizer takes whatever a UI component hands back (a DOM event, a
+ * Date, a react-select-style option object, a plain value...) and returns
+ * the value that should actually be stored.
+ *
+ * This is the single place that replaces the hand-written
+ * `handleFieldChange` type-sniffing function duplicated across form
+ * components in the reference application — implemented once here, with an
+ * escape hatch (a custom Normalizer) for shapes it doesn't know about.
+ */
+type Normalizer<TValue = unknown> = (input: unknown, context: NormalizeContext) => TValue;
+interface FieldOptions<TValue = unknown> {
+    /** Custom normalizer. Defaults to `defaultNormalize` when omitted. */
+    normalize?: Normalizer<TValue>;
+    /** Value to use when the field has never been set. */
+    defaultValue?: TValue;
+}
+/**
+ * The prop bag `registerField` hands back — deliberately shaped like the
+ * value/onChange/onBlur triplet every existing input component
+ * (native inputs, and the reference app's AppInput/AppDropdown/etc.)
+ * already expects, so adopting the library is a plumbing swap, not a
+ * component rewrite.
+ */
+interface RegisteredField<TValue = unknown> {
+    name: string;
+    value: TValue;
+    onChange: (input: unknown) => void;
+    onBlur: () => void;
+}
+
+export type { DebouncedSync as D, FieldOptions as F, Normalizer as N, RegisteredField as R, SyncTarget as S, DebouncedSyncOptions as a, NormalizeContext as b };

package/dist/field-DvWKUaTD.d.cts

@@ -0,0 +1,134 @@
+import { F as FormValues, a as FieldPath, S as StoreListener, U as Unsubscribe, W as WatchListener } from './validation-gIT3Xn9h.cjs';
+
+/**
+ * The minimal read/write/subscribe surface `createDebouncedSync` (and the
+ * React hooks) need from whatever sits behind them.
+ *
+ * `FormStore`, `FormSection`, and `DebouncedSync` all satisfy this
+ * structurally — which is the whole point: there is exactly ONE
+ * debounced-sync wrapper, and whether it fronts a whole store, a section
+ * slice, or (via `createFormSection`) an array row's object slice is
+ * decided by the target handed to it, not by a second implementation.
+ * The same surface is what lets a wrapper be handed straight to
+ * `useForm`/`useFormField`/`useWatch` or wrapped in another
+ * `createDebouncedSync`.
+ *
+ * Members are declared with method syntax (see the note on `FormStore`
+ * for why — property-syntax function members break structural
+ * assignability of typed targets under `strictFunctionTypes`).
+ */
+interface SyncTarget<TValues extends FormValues = FormValues> {
+    getValues(): TValues;
+    getValue(path: FieldPath): unknown;
+    setValue(path: FieldPath, value: unknown): void;
+    setValues(partial: Partial<TValues>): void;
+    reset(nextInitialValues?: TValues): void;
+    /** The committed baseline (what `reset()` restores to), never buffered writes. */
+    getInitialValues(): TValues;
+    subscribe(listener: StoreListener): Unsubscribe;
+    /**
+     * Observes one path (including its subtree) across changes, firing the
+     * listener only when the value actually changed (deep equality). Present
+     * on all implementations (store, section, debounced sync), so `useWatch`
+     * and derived-field logic compose against any target the same way.
+     */
+    watch(path: FieldPath, listener: WatchListener): Unsubscribe;
+}
+interface DebouncedSyncOptions {
+    /**
+     * Milliseconds to wait after the last buffered write before committing to
+     * the target (trailing-edge debounce). Defaults to 300ms.
+     */
+    delay?: number;
+}
+/**
+ * A buffering layer in front of any SyncTarget. Writes land in a pending
+ * batch and commit to the target in ONE transactional write after `delay`
+ * ms of quiet; reads see the buffered writes immediately (read-through),
+ * so a UI rendering from the wrapper never lags behind typing even though
+ * the parent store updates on the debounce.
+ *
+ * It deliberately exposes the same surface shape as its target (members in
+ * method syntax, see `SyncTarget`), so it can itself be wrapped, watched,
+ * composed, and handed to the React hooks the same way.
+ */
+interface DebouncedSync<TValues extends FormValues = FormValues> {
+    /** The configured debounce delay in milliseconds. */
+    readonly delay: number;
+    /** How many writes are currently buffered and not yet committed. */
+    readonly pendingCount: number;
+    /**
+     * Current values including any buffered-but-uncommitted writes. The
+     * returned snapshot is cached between changes, making it safe as a
+     * `useSyncExternalStore` getSnapshot.
+     */
+    getValues(): TValues;
+    /** Reads a single value by path, including buffered writes. */
+    getValue(path: FieldPath): unknown;
+    /** Buffers a single write and (re)schedules the debounced commit. */
+    setValue(path: FieldPath, value: unknown): void;
+    /** Buffers a partial merge (same shallow-merge semantics as the target). */
+    setValues(partial: Partial<TValues>): void;
+    /** Drops all pending writes and forwards the reset to the target. */
+    reset(nextInitialValues?: TValues): void;
+    /**
+     * The target's committed baseline (what `reset()` restores to),
+     * delegated straight through to the wrapped target. Buffered writes are
+     * deliberately NOT part of the baseline — they are uncommitted edits.
+     */
+    getInitialValues(): TValues;
+    /**
+     * Subscribes to changes. Listeners fire immediately when writes are
+     * buffered (with the read-through changed paths) and when the target
+     * changes for reasons other than this wrapper's own flush.
+     */
+    subscribe(listener: StoreListener): Unsubscribe;
+    /** Observes one path (read-through) across buffered and committed changes. */
+    watch(path: FieldPath, listener: WatchListener): Unsubscribe;
+    /** Commits everything buffered right now and clears the timer. */
+    flush(): void;
+    /** Drops everything buffered and clears the timer. Target is untouched. */
+    cancel(): void;
+}
+
+/**
+ * Context passed to a normalizer alongside the raw input value.
+ * Kept intentionally small in Phase 1 — extend only when a real normalizer
+ * needs more (e.g. sibling values), not speculatively.
+ */
+interface NormalizeContext {
+    /** The dot-path of the field being normalized. */
+    path: string;
+}
+/**
+ * A normalizer takes whatever a UI component hands back (a DOM event, a
+ * Date, a react-select-style option object, a plain value...) and returns
+ * the value that should actually be stored.
+ *
+ * This is the single place that replaces the hand-written
+ * `handleFieldChange` type-sniffing function duplicated across form
+ * components in the reference application — implemented once here, with an
+ * escape hatch (a custom Normalizer) for shapes it doesn't know about.
+ */
+type Normalizer<TValue = unknown> = (input: unknown, context: NormalizeContext) => TValue;
+interface FieldOptions<TValue = unknown> {
+    /** Custom normalizer. Defaults to `defaultNormalize` when omitted. */
+    normalize?: Normalizer<TValue>;
+    /** Value to use when the field has never been set. */
+    defaultValue?: TValue;
+}
+/**
+ * The prop bag `registerField` hands back — deliberately shaped like the
+ * value/onChange/onBlur triplet every existing input component
+ * (native inputs, and the reference app's AppInput/AppDropdown/etc.)
+ * already expects, so adopting the library is a plumbing swap, not a
+ * component rewrite.
+ */
+interface RegisteredField<TValue = unknown> {
+    name: string;
+    value: TValue;
+    onChange: (input: unknown) => void;
+    onBlur: () => void;
+}
+
+export type { DebouncedSync as D, FieldOptions as F, Normalizer as N, RegisteredField as R, SyncTarget as S, DebouncedSyncOptions as a, NormalizeContext as b };

package/dist/file.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=file.cjs.map
+//# sourceMappingURL=file.cjs.map

package/dist/file.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"file.cjs"}

package/dist/file.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/file.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/file.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=file.js.map
+//# sourceMappingURL=file.js.map

package/dist/file.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"file.js"}