react-formesh 0.1.4

package/dist/react.d.cts

@@ -0,0 +1,144 @@
+import { F as FormValues, b as ValidationResult, c as ValidationSchema, W as WatchListener } from './validation-gIT3Xn9h.cjs';
+import { F as FieldOptions, R as RegisteredField, S as SyncTarget, D as DebouncedSync } from './field-DvWKUaTD.cjs';
+
+interface UseFormOptions {
+    /**
+     * Scopes this hook instance to a slice of the store (e.g. "employeeInfo"),
+     * mirroring how independent sections of a multi-section ERP form each own
+     * a key on the parent object. Omit to work with the whole store.
+     */
+    section?: string;
+    /**
+     * Validation schema (Phase 2): per-field rules keyed by scope-relative
+     * dot-path, and/or form-level validators receiving the whole values
+     * object in scope (for cross-field rules like date ranges and budget
+     * caps). Omit for no validation (`errors` stays `{}`, `isValid` stays
+     * `true`).
+     */
+    validation?: ValidationSchema;
+}
+interface FormApi<TValues extends FormValues = FormValues> {
+    /** Current values in scope (whole store, or just this section). */
+    values: TValues;
+    /** Which field paths (relative to scope) have been blurred at least once. */
+    touched: Record<string, boolean>;
+    /**
+     * Whether values in scope differ from their value when this hook instance
+     * first observed them. See the in-source note on `initialRef` below for
+     * the exact semantics.
+     */
+    isDirty: boolean;
+    /**
+     * Validation errors for the current values in scope, keyed by
+     * scope-relative field path. Recomputed on every values change against
+     * `options.validation` — and because validation runs over the values this
+     * hook renders from, a DebouncedSync target yields per-keystroke errors
+     * from its read-through values, not only after the debounced commit.
+     * All paths are exposed regardless of touched state; gate display with
+     * `touched` if you only want to show errors after a field was blurred.
+     */
+    errors: Record<string, string>;
+    /** Whether `errors` is currently empty. Always `true` without a schema. */
+    isValid: boolean;
+    /**
+     * Runs the validation schema against the target's CURRENT values (re-read
+     * live, not the render snapshot) and returns the full result — for
+     * submit-time checks or manual revalidation. Same computation
+     * `errors`/`isValid` already reflect.
+     */
+    validate: () => ValidationResult;
+    getValue: (path: string) => unknown;
+    setValue: (path: string, value: unknown) => void;
+    setValues: (partial: Partial<TValues>) => void;
+    /**
+     * Produces a `{ name, value, onChange, onBlur }` prop bag for a field,
+     * normalizing whatever the input hands back via `onChange`. This is the
+     * direct replacement for a hand-written `handleFieldChange` per component.
+     */
+    registerField: <TValue = unknown>(path: string, options?: FieldOptions<TValue>) => RegisteredField<TValue>;
+    /** Resets values in scope back to baseline and clears touched state. */
+    reset: () => void;
+}
+/**
+ * React binding over the shared structural target surface — a FormStore, a
+ * FormSection, or a DebouncedSync wrapper (all satisfy `SyncTarget`
+ * structurally; that is what makes debounced buffering compose straight
+ * into this hook).
+ *
+ * Subscribes via `useSyncExternalStore`, so this component re-renders on
+ * any change within its scope (whole store, a section slice, or the sync
+ * wrapper's read-through values). This
+ * is the "whole-section" usage pattern — the direct replacement for a
+ * component's local `useState` + manual sync-to-parent — where one
+ * component renders many fields together, same as most existing ERP form
+ * sections do today.
+ *
+ * For genuinely fine-grained, single-field re-render isolation (a separate
+ * component per field), see `useFormField` instead — this hook intentionally
+ * re-renders on any change in scope, matching how these forms are already
+ * structured, rather than forcing a per-field-component rewrite to adopt it.
+ */
+declare function useForm<TValues extends FormValues = FormValues>(target: SyncTarget<FormValues>, options?: UseFormOptions): FormApi<TValues>;
+
+/**
+ * Subscribes a component to exactly one field path.
+ *
+ * The target may be a FormStore, a FormSection, or a DebouncedSync wrapper
+ * — anything satisfying the shared structural SyncTarget surface, which is
+ * what lets debounced buffering compose into per-field subscriptions.
+ *
+ * The subscribe callback here ignores the changed-paths list and always
+ * asks React to re-check — but `useSyncExternalStore` only actually
+ * re-renders the component when `getSnapshot()`'s return value differs
+ * (via `Object.is`) from the last one. Because the store only clones
+ * objects along the path that changed (see `setAtPath`), an update to an
+ * unrelated field leaves this field's value referentially identical, so
+ * React bails out without rendering.
+ *
+ * This is the primitive to reach for when a form is large enough that
+ * isolating re-renders per field (rather than per section, via `useForm`)
+ * actually matters — e.g. a field array with hundreds of rows.
+ */
+declare function useFormField<TValue = unknown>(target: SyncTarget, path: string, options?: FieldOptions<TValue>): RegisteredField<TValue>;
+
+interface UseDebouncedSyncOptions {
+    /**
+     * Milliseconds to wait after the last buffered write before committing to
+     * the target. Defaults to 300ms.
+     */
+    delay?: number;
+    /**
+     * What happens to buffered-but-uncommitted writes when the component
+     * unmounts. Defaults to `true` (flush) so the last keystrokes before a
+     * navigation are never lost — the exact failure mode debounced sync
+     * would otherwise introduce. Set to `false` (cancel) when unmounting
+     * means "abandon this edit" rather than "the form went away".
+     */
+    flushOnUnmount?: boolean;
+}
+/**
+ * React binding over `createDebouncedSync`. The wrapper is memoized on
+ * `[target, delay]`, so passing it to `useForm`/`useFormField` (it exposes
+ * the same read/write/subscribe surface they expect) or rendering from its
+ * read-through values stays referentially stable across re-renders.
+ */
+declare function useDebouncedSync<TValues extends FormValues = FormValues>(target: SyncTarget<TValues>, options?: UseDebouncedSyncOptions): DebouncedSync<TValues>;
+
+/**
+ * Runs `listener(value, previousValue)` whenever the value at `path`
+ * actually changes (deep equality). This is the React entry to the store's
+ * `watch` primitive — the primitive derived fields (`qty × price =
+ * lineTotal`) and cascading selects (`Country` change clears `City`) are
+ * built on.
+ *
+ * The listener identity may change every render (it usually closes over
+ * props/state); the effect only re-subscribes when `target` or `path`
+ * changes, and always invokes the latest listener via a ref — so handlers
+ * never see stale closures, and no subscription churn happens per render.
+ *
+ * The listener does not fire on mount. Initial derivations belong in
+ * render (read the value directly) or in the code that sets up the form.
+ */
+declare function useWatch(target: SyncTarget, path: string, listener: WatchListener): void;
+
+export { type FormApi, type UseDebouncedSyncOptions, type UseFormOptions, useDebouncedSync, useForm, useFormField, useWatch };

package/dist/react.d.ts

@@ -0,0 +1,144 @@
+import { F as FormValues, b as ValidationResult, c as ValidationSchema, W as WatchListener } from './validation-gIT3Xn9h.js';
+import { F as FieldOptions, R as RegisteredField, S as SyncTarget, D as DebouncedSync } from './field-CLlwd7BC.js';
+
+interface UseFormOptions {
+    /**
+     * Scopes this hook instance to a slice of the store (e.g. "employeeInfo"),
+     * mirroring how independent sections of a multi-section ERP form each own
+     * a key on the parent object. Omit to work with the whole store.
+     */
+    section?: string;
+    /**
+     * Validation schema (Phase 2): per-field rules keyed by scope-relative
+     * dot-path, and/or form-level validators receiving the whole values
+     * object in scope (for cross-field rules like date ranges and budget
+     * caps). Omit for no validation (`errors` stays `{}`, `isValid` stays
+     * `true`).
+     */
+    validation?: ValidationSchema;
+}
+interface FormApi<TValues extends FormValues = FormValues> {
+    /** Current values in scope (whole store, or just this section). */
+    values: TValues;
+    /** Which field paths (relative to scope) have been blurred at least once. */
+    touched: Record<string, boolean>;
+    /**
+     * Whether values in scope differ from their value when this hook instance
+     * first observed them. See the in-source note on `initialRef` below for
+     * the exact semantics.
+     */
+    isDirty: boolean;
+    /**
+     * Validation errors for the current values in scope, keyed by
+     * scope-relative field path. Recomputed on every values change against
+     * `options.validation` — and because validation runs over the values this
+     * hook renders from, a DebouncedSync target yields per-keystroke errors
+     * from its read-through values, not only after the debounced commit.
+     * All paths are exposed regardless of touched state; gate display with
+     * `touched` if you only want to show errors after a field was blurred.
+     */
+    errors: Record<string, string>;
+    /** Whether `errors` is currently empty. Always `true` without a schema. */
+    isValid: boolean;
+    /**
+     * Runs the validation schema against the target's CURRENT values (re-read
+     * live, not the render snapshot) and returns the full result — for
+     * submit-time checks or manual revalidation. Same computation
+     * `errors`/`isValid` already reflect.
+     */
+    validate: () => ValidationResult;
+    getValue: (path: string) => unknown;
+    setValue: (path: string, value: unknown) => void;
+    setValues: (partial: Partial<TValues>) => void;
+    /**
+     * Produces a `{ name, value, onChange, onBlur }` prop bag for a field,
+     * normalizing whatever the input hands back via `onChange`. This is the
+     * direct replacement for a hand-written `handleFieldChange` per component.
+     */
+    registerField: <TValue = unknown>(path: string, options?: FieldOptions<TValue>) => RegisteredField<TValue>;
+    /** Resets values in scope back to baseline and clears touched state. */
+    reset: () => void;
+}
+/**
+ * React binding over the shared structural target surface — a FormStore, a
+ * FormSection, or a DebouncedSync wrapper (all satisfy `SyncTarget`
+ * structurally; that is what makes debounced buffering compose straight
+ * into this hook).
+ *
+ * Subscribes via `useSyncExternalStore`, so this component re-renders on
+ * any change within its scope (whole store, a section slice, or the sync
+ * wrapper's read-through values). This
+ * is the "whole-section" usage pattern — the direct replacement for a
+ * component's local `useState` + manual sync-to-parent — where one
+ * component renders many fields together, same as most existing ERP form
+ * sections do today.
+ *
+ * For genuinely fine-grained, single-field re-render isolation (a separate
+ * component per field), see `useFormField` instead — this hook intentionally
+ * re-renders on any change in scope, matching how these forms are already
+ * structured, rather than forcing a per-field-component rewrite to adopt it.
+ */
+declare function useForm<TValues extends FormValues = FormValues>(target: SyncTarget<FormValues>, options?: UseFormOptions): FormApi<TValues>;
+
+/**
+ * Subscribes a component to exactly one field path.
+ *
+ * The target may be a FormStore, a FormSection, or a DebouncedSync wrapper
+ * — anything satisfying the shared structural SyncTarget surface, which is
+ * what lets debounced buffering compose into per-field subscriptions.
+ *
+ * The subscribe callback here ignores the changed-paths list and always
+ * asks React to re-check — but `useSyncExternalStore` only actually
+ * re-renders the component when `getSnapshot()`'s return value differs
+ * (via `Object.is`) from the last one. Because the store only clones
+ * objects along the path that changed (see `setAtPath`), an update to an
+ * unrelated field leaves this field's value referentially identical, so
+ * React bails out without rendering.
+ *
+ * This is the primitive to reach for when a form is large enough that
+ * isolating re-renders per field (rather than per section, via `useForm`)
+ * actually matters — e.g. a field array with hundreds of rows.
+ */
+declare function useFormField<TValue = unknown>(target: SyncTarget, path: string, options?: FieldOptions<TValue>): RegisteredField<TValue>;
+
+interface UseDebouncedSyncOptions {
+    /**
+     * Milliseconds to wait after the last buffered write before committing to
+     * the target. Defaults to 300ms.
+     */
+    delay?: number;
+    /**
+     * What happens to buffered-but-uncommitted writes when the component
+     * unmounts. Defaults to `true` (flush) so the last keystrokes before a
+     * navigation are never lost — the exact failure mode debounced sync
+     * would otherwise introduce. Set to `false` (cancel) when unmounting
+     * means "abandon this edit" rather than "the form went away".
+     */
+    flushOnUnmount?: boolean;
+}
+/**
+ * React binding over `createDebouncedSync`. The wrapper is memoized on
+ * `[target, delay]`, so passing it to `useForm`/`useFormField` (it exposes
+ * the same read/write/subscribe surface they expect) or rendering from its
+ * read-through values stays referentially stable across re-renders.
+ */
+declare function useDebouncedSync<TValues extends FormValues = FormValues>(target: SyncTarget<TValues>, options?: UseDebouncedSyncOptions): DebouncedSync<TValues>;
+
+/**
+ * Runs `listener(value, previousValue)` whenever the value at `path`
+ * actually changes (deep equality). This is the React entry to the store's
+ * `watch` primitive — the primitive derived fields (`qty × price =
+ * lineTotal`) and cascading selects (`Country` change clears `City`) are
+ * built on.
+ *
+ * The listener identity may change every render (it usually closes over
+ * props/state); the effect only re-subscribes when `target` or `path`
+ * changes, and always invokes the latest listener via a ref — so handlers
+ * never see stale closures, and no subscription churn happens per render.
+ *
+ * The listener does not fire on mount. Initial derivations belong in
+ * render (read the value directly) or in the code that sets up the form.
+ */
+declare function useWatch(target: SyncTarget, path: string, listener: WatchListener): void;
+
+export { type FormApi, type UseDebouncedSyncOptions, type UseFormOptions, useDebouncedSync, useForm, useFormField, useWatch };