react-formesh 0.1.4

package/dist/index.d.cts

@@ -0,0 +1,209 @@
+import { F as FormValues, d as FormStore, a as FieldPath, U as Unsubscribe, W as WatchListener, c as ValidationSchema, b as ValidationResult } from './validation-gIT3Xn9h.cjs';
+export { e as FieldRules, f as FormLevelValidator, S as StoreListener, g as ValidationContext, V as Validator } from './validation-gIT3Xn9h.cjs';
+import { S as SyncTarget, a as DebouncedSyncOptions, D as DebouncedSync, N as Normalizer } from './field-DvWKUaTD.cjs';
+export { F as FieldOptions, b as NormalizeContext, R as RegisteredField } from './field-DvWKUaTD.cjs';
+
+/**
+ * Creates a framework-agnostic form store.
+ *
+ * This file must never import React. It's the piece every other package
+ * (react, validators, file, array) builds on top of, and it needs to stay
+ * independently unit-testable and usable outside React entirely (see
+ * roadmap section 7).
+ *
+ * Design notes (documented here because the "why" matters for anyone
+ * extending this later):
+ *
+ * - Values are plain objects, updated immutably (see `paths.ts`), so
+ *   `getValues()` always returns a plain, serializable snapshot — no
+ *   proxies, no framework-specific wrappers.
+ * - The store does not itself decide who re-renders. It just computes
+ *   *which dot-paths changed* on every commit and hands that list to every
+ *   subscriber. The React binding (`useForm`, in the `react` entry point)
+ *   is what turns "did my path change?" into a re-render decision, via
+ *   `useSyncExternalStore`. This split is what avoids a Context-based
+ *   design, where every consumer re-renders on every change regardless of
+ *   which field they read.
+ */
+declare function createFormStore<TValues extends FormValues = FormValues>(initialValues: TValues): FormStore<TValues>;
+
+/**
+ * A section-scoped listener receives dot-paths already relative to the
+ * section (the section's own key prefix is stripped before delivery).
+ */
+type SectionListener = (changedPaths: readonly FieldPath[]) => void;
+/**
+ * Members are declared with method syntax (see the note on `FormStore` for
+ * why — property-syntax function members break structural assignability of
+ * typed sections under `strictFunctionTypes`).
+ */
+interface FormSection<TSectionValues extends FormValues = FormValues> {
+    /** The dot-path key this section is scoped to on the parent store. */
+    readonly key: string;
+    /** Current values for just this section, as a plain object. */
+    getValues(): TSectionValues;
+    /** Reads a value at a path relative to this section. */
+    getValue(relativePath: FieldPath): unknown;
+    /** Writes a value at a path relative to this section. */
+    setValue(relativePath: FieldPath, value: unknown): void;
+    /** Shallow-merges a partial object into this section's values. */
+    setValues(partial: Partial<TSectionValues>): void;
+    /** Resets this section back to its slice of the store's initial values. */
+    reset(): void;
+    /**
+     * The slice of the parent store's initial values this section owns (i.e.
+     * what `reset()` restores to). Present so a section satisfies the same
+     * structural surface as a store — required for `SyncTarget` composition
+     * (`createDebouncedSync(section)`, `useForm(section)`, ...).
+     */
+    getInitialValues(): TSectionValues;
+    /** Subscribes to changes within this section only (paths are relative). */
+    subscribe(listener: SectionListener): Unsubscribe;
+    /**
+     * Observes one section-relative path (including its subtree) across
+     * changes, invoking `listener(value, previousValue)` only when the value
+     * actually changed (deep equality). Returns an unsubscribe function.
+     */
+    watch(relativePath: FieldPath, listener: WatchListener): Unsubscribe;
+}
+
+/**
+ * Wraps a slice of a FormStore (identified by a top-level or dot-path key)
+ * as an independently usable FormSection.
+ *
+ * This is the primitive behind multi-section ERP-style forms: each section
+ * of a form (e.g. "employeeInfo", "jobInfo", "bankInfo") can be built,
+ * tested, and reasoned about as if it owned its own store, while every
+ * write actually lands on the shared parent store — so the parent always
+ * has the complete, merged plain object (see roadmap section 8).
+ *
+ * Framework-agnostic: no React import here either. `useForm(store, {
+ * section })` (in the react entry point) is a thin hook wrapper around this.
+ */
+declare function createFormSection<TSectionValues extends FormValues = FormValues>(store: FormStore<FormValues>, key: string): FormSection<TSectionValues>;
+
+/**
+ * One debounced-sync wrapper for ANY target — a whole FormStore, a section
+ * slice, or an array row's object slice (all are SyncTargets, so there is
+ * deliberately no separate "array" vs "object" implementation).
+ *
+ * Why this exists (the gap it closes):
+ *
+ * - Phase 1's store commits synchronously on every `setValue` — during fast
+ *   typing that is one diff+notify per keystroke hitting the parent store
+ *   and every subscriber of it. With this wrapper in front, the target sees
+ *   exactly ONE commit per quiet period, no matter how many writes happened.
+ * - The commit itself is transactional: the whole pending batch is applied
+ *   to a staged copy of the target's values and handed over via a single
+ *   `setValues`, which the store turns into one diff + one notify. Multiple
+ *   sections syncing through their own wrappers therefore also stop
+ *   fighting over the parent on every keystroke.
+ * - Reads are read-through and cached: `getValues`/`getValue` include the
+ *   buffered writes, so a UI rendering from the wrapper shows what the user
+ *   typed immediately — the debounce only delays the *parent commit*, not
+ *   the visible state. The snapshot caching also makes the wrapper safe to
+ *   hand to `useSyncExternalStore` directly.
+ *
+ * Semantics worth knowing:
+ *
+ * - Trailing-edge debounce: each buffered write restarts the timer.
+ * - Last write per path wins (a Map keyed by path).
+ * - `flush()` commits immediately (use on blur/submit); `cancel()` drops.
+ * - Writes arriving while a flush is in flight commit straight through, so
+ *   nothing triggered synchronously by the flush notification is ever lost.
+ * - Wrapper subscribers hear about buffered writes immediately and about
+ *   external target changes as they happen; the wrapper's own flush is NOT
+ *   re-announced (it was already announced when buffered, and the values
+ *   did not change at that point).
+ */
+declare function createDebouncedSync<TValues extends FormValues = FormValues>(target: SyncTarget<TValues>, options?: DebouncedSyncOptions): DebouncedSync<TValues>;
+
+/**
+ * Runs a validation schema against a values object and returns every
+ * error, keyed by field path.
+ *
+ * Framework-agnostic and pure: no store, no React, no timers. `useForm`
+ * calls this on every values change; anything else (a submit handler, a
+ * draft-save guard, a section component) can call it directly with the
+ * same schema.
+ *
+ * Semantics:
+ * - Field rules run first, per path, in schema key order; the first
+ *   failing rule's message wins for that path.
+ * - Form-level validators run after, and their errors only fill paths
+ *   that don't already have a field-level error (the per-field message is
+ *   the more specific one).
+ * - Nested paths ("employee.firstName") are resolved with `getAtPath`,
+ *   consistent with how the store reads values.
+ */
+declare function validateValues<TValues extends FormValues = FormValues>(values: TValues, schema: ValidationSchema): ValidationResult;
+
+/**
+ * The default normalizer. Covers the shapes that come up repeatedly across
+ * hand-written ERP form components:
+ *
+ *  - native DOM change events (checkbox vs. everything else)
+ *  - `Date` objects (from date pickers) — passed through as-is; callers who
+ *    need a serialized string should supply a custom normalizer, since the
+ *    right format is app-specific (see roadmap section 13: normalization
+ *    decisions must be explicit, not silently opinionated)
+ *  - arrays of `{ value }` option objects (multi-selects)
+ *  - single `{ value }` option objects (single-selects)
+ *  - plain primitives, passed through unchanged
+ *
+ * This intentionally does not know about any specific UI library. A
+ * component whose change shape doesn't match one of the above should be
+ * wired with a custom `normalize` function via `FieldOptions`.
+ */
+declare const defaultNormalize: Normalizer;
+
+/**
+ * Structural equality for plain JSON-like form values (objects, arrays,
+ * primitives). Non-plain values (Date, File, custom classes) fall back to
+ * `Object.is` rather than field-by-field inspection — sufficient for dirty
+ * tracking, since those values are typically replaced wholesale rather than
+ * mutated in place. Revisit only if a real use case needs otherwise.
+ */
+declare function deepEqual(a: unknown, b: unknown): boolean;
+
+declare function getAtPath(source: unknown, path: string): unknown;
+/**
+ * Returns a new object with `value` written at `path`, cloning only the
+ * objects along the path (structural sharing everywhere else). This is what
+ * lets subscribers cheaply detect "did the branch I care about change?" via
+ * reference equality, without deep-cloning the whole form on every keystroke.
+ */
+declare function setAtPath<T extends Record<string, unknown>>(source: T, path: string, value: unknown): T;
+/**
+ * Shallow-merges `partial` into `source` at the top level, one key at a
+ * time, reusing setAtPath so each key's structural-sharing behavior stays
+ * consistent with single-field writes.
+ */
+declare function mergeAtRoot<T extends Record<string, unknown>>(source: T, partial: Partial<T>): T;
+/**
+ * Returns every dot-path whose leaf value differs (by reference, via
+ * Object.is) between `prev` and `next`, walking both objects together.
+ * Used to compute exactly which paths to notify subscribers about.
+ */
+declare function diffPaths(prev: unknown, next: unknown, basePath?: string, seen?: Set<string>): string[];
+
+/**
+ * Whether a change reported at `changedPath` could have affected the value
+ * at `watchedPath`. Three cases matter:
+ *
+ *  - exact match (`changedPath === watchedPath`)
+ *  - the change is *inside* the watched subtree (`employee.name` changes
+ *    when watching `employee`)
+ *  - the watched path sits *inside* the changed subtree — an ancestor was
+ *    replaced wholesale (e.g. `store.setValue("employee", {...})`), so the
+ *    value at the watched path may or may not have changed; the watcher
+ *    still needs to check
+ *
+ * An empty changed path means "everything under here was replaced" (how a
+ * section sees `store.setValue(sectionKey, {...})`), so it matches any
+ * watch. An empty watched path is a whole-scope watch and matches every
+ * change.
+ */
+declare function isPathWithin(changedPath: string, watchedPath: string): boolean;
+
+export { DebouncedSync, DebouncedSyncOptions, FieldPath, type FormSection, FormStore, FormValues, Normalizer, type SectionListener, SyncTarget, Unsubscribe, ValidationResult, ValidationSchema, WatchListener, createDebouncedSync, createFormSection, createFormStore, deepEqual, defaultNormalize, diffPaths, getAtPath, isPathWithin, mergeAtRoot, setAtPath, validateValues };

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+import { F as FormValues, d as FormStore, a as FieldPath, U as Unsubscribe, W as WatchListener, c as ValidationSchema, b as ValidationResult } from './validation-gIT3Xn9h.js';
+export { e as FieldRules, f as FormLevelValidator, S as StoreListener, g as ValidationContext, V as Validator } from './validation-gIT3Xn9h.js';
+import { S as SyncTarget, a as DebouncedSyncOptions, D as DebouncedSync, N as Normalizer } from './field-CLlwd7BC.js';
+export { F as FieldOptions, b as NormalizeContext, R as RegisteredField } from './field-CLlwd7BC.js';
+
+/**
+ * Creates a framework-agnostic form store.
+ *
+ * This file must never import React. It's the piece every other package
+ * (react, validators, file, array) builds on top of, and it needs to stay
+ * independently unit-testable and usable outside React entirely (see
+ * roadmap section 7).
+ *
+ * Design notes (documented here because the "why" matters for anyone
+ * extending this later):
+ *
+ * - Values are plain objects, updated immutably (see `paths.ts`), so
+ *   `getValues()` always returns a plain, serializable snapshot — no
+ *   proxies, no framework-specific wrappers.
+ * - The store does not itself decide who re-renders. It just computes
+ *   *which dot-paths changed* on every commit and hands that list to every
+ *   subscriber. The React binding (`useForm`, in the `react` entry point)
+ *   is what turns "did my path change?" into a re-render decision, via
+ *   `useSyncExternalStore`. This split is what avoids a Context-based
+ *   design, where every consumer re-renders on every change regardless of
+ *   which field they read.
+ */
+declare function createFormStore<TValues extends FormValues = FormValues>(initialValues: TValues): FormStore<TValues>;
+
+/**
+ * A section-scoped listener receives dot-paths already relative to the
+ * section (the section's own key prefix is stripped before delivery).
+ */
+type SectionListener = (changedPaths: readonly FieldPath[]) => void;
+/**
+ * Members are declared with method syntax (see the note on `FormStore` for
+ * why — property-syntax function members break structural assignability of
+ * typed sections under `strictFunctionTypes`).
+ */
+interface FormSection<TSectionValues extends FormValues = FormValues> {
+    /** The dot-path key this section is scoped to on the parent store. */
+    readonly key: string;
+    /** Current values for just this section, as a plain object. */
+    getValues(): TSectionValues;
+    /** Reads a value at a path relative to this section. */
+    getValue(relativePath: FieldPath): unknown;
+    /** Writes a value at a path relative to this section. */
+    setValue(relativePath: FieldPath, value: unknown): void;
+    /** Shallow-merges a partial object into this section's values. */
+    setValues(partial: Partial<TSectionValues>): void;
+    /** Resets this section back to its slice of the store's initial values. */
+    reset(): void;
+    /**
+     * The slice of the parent store's initial values this section owns (i.e.
+     * what `reset()` restores to). Present so a section satisfies the same
+     * structural surface as a store — required for `SyncTarget` composition
+     * (`createDebouncedSync(section)`, `useForm(section)`, ...).
+     */
+    getInitialValues(): TSectionValues;
+    /** Subscribes to changes within this section only (paths are relative). */
+    subscribe(listener: SectionListener): Unsubscribe;
+    /**
+     * Observes one section-relative path (including its subtree) across
+     * changes, invoking `listener(value, previousValue)` only when the value
+     * actually changed (deep equality). Returns an unsubscribe function.
+     */
+    watch(relativePath: FieldPath, listener: WatchListener): Unsubscribe;
+}
+
+/**
+ * Wraps a slice of a FormStore (identified by a top-level or dot-path key)
+ * as an independently usable FormSection.
+ *
+ * This is the primitive behind multi-section ERP-style forms: each section
+ * of a form (e.g. "employeeInfo", "jobInfo", "bankInfo") can be built,
+ * tested, and reasoned about as if it owned its own store, while every
+ * write actually lands on the shared parent store — so the parent always
+ * has the complete, merged plain object (see roadmap section 8).
+ *
+ * Framework-agnostic: no React import here either. `useForm(store, {
+ * section })` (in the react entry point) is a thin hook wrapper around this.
+ */
+declare function createFormSection<TSectionValues extends FormValues = FormValues>(store: FormStore<FormValues>, key: string): FormSection<TSectionValues>;
+
+/**
+ * One debounced-sync wrapper for ANY target — a whole FormStore, a section
+ * slice, or an array row's object slice (all are SyncTargets, so there is
+ * deliberately no separate "array" vs "object" implementation).
+ *
+ * Why this exists (the gap it closes):
+ *
+ * - Phase 1's store commits synchronously on every `setValue` — during fast
+ *   typing that is one diff+notify per keystroke hitting the parent store
+ *   and every subscriber of it. With this wrapper in front, the target sees
+ *   exactly ONE commit per quiet period, no matter how many writes happened.
+ * - The commit itself is transactional: the whole pending batch is applied
+ *   to a staged copy of the target's values and handed over via a single
+ *   `setValues`, which the store turns into one diff + one notify. Multiple
+ *   sections syncing through their own wrappers therefore also stop
+ *   fighting over the parent on every keystroke.
+ * - Reads are read-through and cached: `getValues`/`getValue` include the
+ *   buffered writes, so a UI rendering from the wrapper shows what the user
+ *   typed immediately — the debounce only delays the *parent commit*, not
+ *   the visible state. The snapshot caching also makes the wrapper safe to
+ *   hand to `useSyncExternalStore` directly.
+ *
+ * Semantics worth knowing:
+ *
+ * - Trailing-edge debounce: each buffered write restarts the timer.
+ * - Last write per path wins (a Map keyed by path).
+ * - `flush()` commits immediately (use on blur/submit); `cancel()` drops.
+ * - Writes arriving while a flush is in flight commit straight through, so
+ *   nothing triggered synchronously by the flush notification is ever lost.
+ * - Wrapper subscribers hear about buffered writes immediately and about
+ *   external target changes as they happen; the wrapper's own flush is NOT
+ *   re-announced (it was already announced when buffered, and the values
+ *   did not change at that point).
+ */
+declare function createDebouncedSync<TValues extends FormValues = FormValues>(target: SyncTarget<TValues>, options?: DebouncedSyncOptions): DebouncedSync<TValues>;
+
+/**
+ * Runs a validation schema against a values object and returns every
+ * error, keyed by field path.
+ *
+ * Framework-agnostic and pure: no store, no React, no timers. `useForm`
+ * calls this on every values change; anything else (a submit handler, a
+ * draft-save guard, a section component) can call it directly with the
+ * same schema.
+ *
+ * Semantics:
+ * - Field rules run first, per path, in schema key order; the first
+ *   failing rule's message wins for that path.
+ * - Form-level validators run after, and their errors only fill paths
+ *   that don't already have a field-level error (the per-field message is
+ *   the more specific one).
+ * - Nested paths ("employee.firstName") are resolved with `getAtPath`,
+ *   consistent with how the store reads values.
+ */
+declare function validateValues<TValues extends FormValues = FormValues>(values: TValues, schema: ValidationSchema): ValidationResult;
+
+/**
+ * The default normalizer. Covers the shapes that come up repeatedly across
+ * hand-written ERP form components:
+ *
+ *  - native DOM change events (checkbox vs. everything else)
+ *  - `Date` objects (from date pickers) — passed through as-is; callers who
+ *    need a serialized string should supply a custom normalizer, since the
+ *    right format is app-specific (see roadmap section 13: normalization
+ *    decisions must be explicit, not silently opinionated)
+ *  - arrays of `{ value }` option objects (multi-selects)
+ *  - single `{ value }` option objects (single-selects)
+ *  - plain primitives, passed through unchanged
+ *
+ * This intentionally does not know about any specific UI library. A
+ * component whose change shape doesn't match one of the above should be
+ * wired with a custom `normalize` function via `FieldOptions`.
+ */
+declare const defaultNormalize: Normalizer;
+
+/**
+ * Structural equality for plain JSON-like form values (objects, arrays,
+ * primitives). Non-plain values (Date, File, custom classes) fall back to
+ * `Object.is` rather than field-by-field inspection — sufficient for dirty
+ * tracking, since those values are typically replaced wholesale rather than
+ * mutated in place. Revisit only if a real use case needs otherwise.
+ */
+declare function deepEqual(a: unknown, b: unknown): boolean;
+
+declare function getAtPath(source: unknown, path: string): unknown;
+/**
+ * Returns a new object with `value` written at `path`, cloning only the
+ * objects along the path (structural sharing everywhere else). This is what
+ * lets subscribers cheaply detect "did the branch I care about change?" via
+ * reference equality, without deep-cloning the whole form on every keystroke.
+ */
+declare function setAtPath<T extends Record<string, unknown>>(source: T, path: string, value: unknown): T;
+/**
+ * Shallow-merges `partial` into `source` at the top level, one key at a
+ * time, reusing setAtPath so each key's structural-sharing behavior stays
+ * consistent with single-field writes.
+ */
+declare function mergeAtRoot<T extends Record<string, unknown>>(source: T, partial: Partial<T>): T;
+/**
+ * Returns every dot-path whose leaf value differs (by reference, via
+ * Object.is) between `prev` and `next`, walking both objects together.
+ * Used to compute exactly which paths to notify subscribers about.
+ */
+declare function diffPaths(prev: unknown, next: unknown, basePath?: string, seen?: Set<string>): string[];
+
+/**
+ * Whether a change reported at `changedPath` could have affected the value
+ * at `watchedPath`. Three cases matter:
+ *
+ *  - exact match (`changedPath === watchedPath`)
+ *  - the change is *inside* the watched subtree (`employee.name` changes
+ *    when watching `employee`)
+ *  - the watched path sits *inside* the changed subtree — an ancestor was
+ *    replaced wholesale (e.g. `store.setValue("employee", {...})`), so the
+ *    value at the watched path may or may not have changed; the watcher
+ *    still needs to check
+ *
+ * An empty changed path means "everything under here was replaced" (how a
+ * section sees `store.setValue(sectionKey, {...})`), so it matches any
+ * watch. An empty watched path is a whole-scope watch and matches every
+ * change.
+ */
+declare function isPathWithin(changedPath: string, watchedPath: string): boolean;
+
+export { DebouncedSync, DebouncedSyncOptions, FieldPath, type FormSection, FormStore, FormValues, Normalizer, type SectionListener, SyncTarget, Unsubscribe, ValidationResult, ValidationSchema, WatchListener, createDebouncedSync, createFormSection, createFormStore, deepEqual, defaultNormalize, diffPaths, getAtPath, isPathWithin, mergeAtRoot, setAtPath, validateValues };