react-formesh 0.1.4

package/dist/validation-gIT3Xn9h.d.cts

@@ -0,0 +1,125 @@
+/**
+ * A form's values are always a plain, serializable-shaped JS object.
+ * Nesting is allowed (and is how multi-section forms compose), but every
+ * leaf is a value the consumer owns — the store never wraps values in
+ * framework-specific containers.
+ */
+type FormValues = Record<string, unknown>;
+/**
+ * A dot-separated path into a (possibly nested) FormValues object.
+ * e.g. "employeeInfo.firstName"
+ *
+ * Kept as a plain `string` (not a template-literal-typed path) in Phase 1.
+ * Full compile-time path inference is a Phase 6 (DX) concern — see the
+ * project roadmap's note on avoiding excessive type complexity before the
+ * runtime behavior it would describe actually exists.
+ */
+type FieldPath = string;
+/**
+ * A listener is notified after a change with the fields that actually
+ * changed (as dot-paths), so subscribers can decide for themselves whether
+ * a change is relevant to them. The store computes this list; individual
+ * hooks decide what to do with it (this is what makes fine-grained
+ * subscription possible without the store knowing about React).
+ */
+type StoreListener = (changedPaths: readonly FieldPath[]) => void;
+type Unsubscribe = () => void;
+/**
+ * Callback for `watch(path, listener)`. Fires only when the value at the
+ * watched path actually changed (by deep equality, matching `deepEqual`),
+ * receiving the new value and the value immediately before the change. It
+ * deliberately does NOT fire on subscribe — consumers who need an initial
+ * derivation can compute it during render from `getValues()`.
+ */
+type WatchListener = (value: unknown, previousValue: unknown) => void;
+interface FormStore<TValues extends FormValues = FormValues> {
+    /**
+     * Returns the current values object. Never mutated in place.
+     *
+     * NOTE: the members of this interface are deliberately declared with
+     * *method syntax* (`getValues()`, not `getValues: () => ...`). Under
+     * `strictFunctionTypes`, property-syntax function members are checked
+     * contravariantly, which makes `FormStore<SomeTypedShape>` NOT assignable
+     * to `FormStore<FormValues>` — silently breaking every composition that
+     * hands a typed store/section/sync wrapper to something expecting the
+     * loose `FormValues` shape (hooks, `createFormSection`,
+     * `createDebouncedSync`). Method syntax restores bivariance for these
+     * members, which is exactly what the structural composability story
+     * (store → section → debounced sync → React hooks) relies on.
+     */
+    getValues(): TValues;
+    /** Reads a single value by dot-path. Returns `undefined` if not present. */
+    getValue(path: FieldPath): unknown;
+    /** Writes a single value by dot-path, notifying relevant subscribers. */
+    setValue(path: FieldPath, value: unknown): void;
+    /**
+     * Merges a partial values object into the store (shallow per top-level
+     * key, matching how independent sections merge into a parent form).
+     */
+    setValues(partial: Partial<TValues>): void;
+    /** Restores the store to its initial values (or a new baseline, if given). */
+    reset(nextInitialValues?: TValues): void;
+    /**
+     * Subscribes to store changes. The listener fires after every commit with
+     * the list of dot-paths that changed. Returns an unsubscribe function.
+     */
+    subscribe(listener: StoreListener): Unsubscribe;
+    /**
+     * Observes one path (including its whole subtree) across commits,
+     * invoking `listener(value, previousValue)` only when the value actually
+     * changed (deep equality). Returns an unsubscribe function.
+     */
+    watch(path: FieldPath, listener: WatchListener): Unsubscribe;
+    /** The values the store was created with, or last reset to. */
+    getInitialValues(): TValues;
+}
+
+/**
+ * Context handed to every validator alongside the value being checked.
+ * `values` is the complete values object in scope (whole store or section),
+ * which is what cross-field rules compare against — e.g. `matches`
+ * (confirm-password) or a form-level date-range check.
+ */
+interface ValidationContext {
+    /** The dot-path of the field being validated (scope-relative). */
+    path: FieldPath;
+    /** The complete values object in scope at validation time. */
+    values: FormValues;
+}
+/**
+ * A validator returns an error message string when the value is invalid,
+ * and `undefined`/`null`/nothing when it is valid. Pure functions of
+ * (value, context) — no side effects, no async (debounced async validation
+ * is a later-phase concern built on top of this).
+ */
+type Validator = (value: unknown, context: ValidationContext) => string | null | undefined | void;
+/** One field's rules: a single validator or a list (first failure wins). */
+type FieldRules = Validator | readonly Validator[];
+/**
+ * A form-level validator receives the whole values object in scope and
+ * returns a partial errors map (paths → messages) — for rules no single
+ * field can express: date ranges, start ≤ end, budget caps, etc.
+ */
+type FormLevelValidator = (values: FormValues) => Record<string, string> | null | undefined | void;
+interface ValidationSchema {
+    /**
+     * Per-field rules, keyed by dot-path (scope-relative; nested paths like
+     * "employee.firstName" work). A path may map to one validator or a list —
+     * for lists, the first failing rule's message is used.
+     */
+    fields?: Record<string, FieldRules>;
+    /**
+     * Form-level validator(s) run after field rules. Their errors are merged
+     * in for paths that don't already have a field-level error, so the more
+     * specific per-field message wins.
+     */
+    form?: FormLevelValidator | readonly FormLevelValidator[];
+}
+interface ValidationResult {
+    /** Errors keyed by field path; empty object when everything validates. */
+    errors: Record<string, string>;
+    /** `true` when `errors` is empty. */
+    isValid: boolean;
+}
+
+export type { FormValues as F, StoreListener as S, Unsubscribe as U, Validator as V, WatchListener as W, FieldPath as a, ValidationResult as b, ValidationSchema as c, FormStore as d, FieldRules as e, FormLevelValidator as f, ValidationContext as g };

package/dist/validation-gIT3Xn9h.d.ts

@@ -0,0 +1,125 @@
+/**
+ * A form's values are always a plain, serializable-shaped JS object.
+ * Nesting is allowed (and is how multi-section forms compose), but every
+ * leaf is a value the consumer owns — the store never wraps values in
+ * framework-specific containers.
+ */
+type FormValues = Record<string, unknown>;
+/**
+ * A dot-separated path into a (possibly nested) FormValues object.
+ * e.g. "employeeInfo.firstName"
+ *
+ * Kept as a plain `string` (not a template-literal-typed path) in Phase 1.
+ * Full compile-time path inference is a Phase 6 (DX) concern — see the
+ * project roadmap's note on avoiding excessive type complexity before the
+ * runtime behavior it would describe actually exists.
+ */
+type FieldPath = string;
+/**
+ * A listener is notified after a change with the fields that actually
+ * changed (as dot-paths), so subscribers can decide for themselves whether
+ * a change is relevant to them. The store computes this list; individual
+ * hooks decide what to do with it (this is what makes fine-grained
+ * subscription possible without the store knowing about React).
+ */
+type StoreListener = (changedPaths: readonly FieldPath[]) => void;
+type Unsubscribe = () => void;
+/**
+ * Callback for `watch(path, listener)`. Fires only when the value at the
+ * watched path actually changed (by deep equality, matching `deepEqual`),
+ * receiving the new value and the value immediately before the change. It
+ * deliberately does NOT fire on subscribe — consumers who need an initial
+ * derivation can compute it during render from `getValues()`.
+ */
+type WatchListener = (value: unknown, previousValue: unknown) => void;
+interface FormStore<TValues extends FormValues = FormValues> {
+    /**
+     * Returns the current values object. Never mutated in place.
+     *
+     * NOTE: the members of this interface are deliberately declared with
+     * *method syntax* (`getValues()`, not `getValues: () => ...`). Under
+     * `strictFunctionTypes`, property-syntax function members are checked
+     * contravariantly, which makes `FormStore<SomeTypedShape>` NOT assignable
+     * to `FormStore<FormValues>` — silently breaking every composition that
+     * hands a typed store/section/sync wrapper to something expecting the
+     * loose `FormValues` shape (hooks, `createFormSection`,
+     * `createDebouncedSync`). Method syntax restores bivariance for these
+     * members, which is exactly what the structural composability story
+     * (store → section → debounced sync → React hooks) relies on.
+     */
+    getValues(): TValues;
+    /** Reads a single value by dot-path. Returns `undefined` if not present. */
+    getValue(path: FieldPath): unknown;
+    /** Writes a single value by dot-path, notifying relevant subscribers. */
+    setValue(path: FieldPath, value: unknown): void;
+    /**
+     * Merges a partial values object into the store (shallow per top-level
+     * key, matching how independent sections merge into a parent form).
+     */
+    setValues(partial: Partial<TValues>): void;
+    /** Restores the store to its initial values (or a new baseline, if given). */
+    reset(nextInitialValues?: TValues): void;
+    /**
+     * Subscribes to store changes. The listener fires after every commit with
+     * the list of dot-paths that changed. Returns an unsubscribe function.
+     */
+    subscribe(listener: StoreListener): Unsubscribe;
+    /**
+     * Observes one path (including its whole subtree) across commits,
+     * invoking `listener(value, previousValue)` only when the value actually
+     * changed (deep equality). Returns an unsubscribe function.
+     */
+    watch(path: FieldPath, listener: WatchListener): Unsubscribe;
+    /** The values the store was created with, or last reset to. */
+    getInitialValues(): TValues;
+}
+
+/**
+ * Context handed to every validator alongside the value being checked.
+ * `values` is the complete values object in scope (whole store or section),
+ * which is what cross-field rules compare against — e.g. `matches`
+ * (confirm-password) or a form-level date-range check.
+ */
+interface ValidationContext {
+    /** The dot-path of the field being validated (scope-relative). */
+    path: FieldPath;
+    /** The complete values object in scope at validation time. */
+    values: FormValues;
+}
+/**
+ * A validator returns an error message string when the value is invalid,
+ * and `undefined`/`null`/nothing when it is valid. Pure functions of
+ * (value, context) — no side effects, no async (debounced async validation
+ * is a later-phase concern built on top of this).
+ */
+type Validator = (value: unknown, context: ValidationContext) => string | null | undefined | void;
+/** One field's rules: a single validator or a list (first failure wins). */
+type FieldRules = Validator | readonly Validator[];
+/**
+ * A form-level validator receives the whole values object in scope and
+ * returns a partial errors map (paths → messages) — for rules no single
+ * field can express: date ranges, start ≤ end, budget caps, etc.
+ */
+type FormLevelValidator = (values: FormValues) => Record<string, string> | null | undefined | void;
+interface ValidationSchema {
+    /**
+     * Per-field rules, keyed by dot-path (scope-relative; nested paths like
+     * "employee.firstName" work). A path may map to one validator or a list —
+     * for lists, the first failing rule's message is used.
+     */
+    fields?: Record<string, FieldRules>;
+    /**
+     * Form-level validator(s) run after field rules. Their errors are merged
+     * in for paths that don't already have a field-level error, so the more
+     * specific per-field message wins.
+     */
+    form?: FormLevelValidator | readonly FormLevelValidator[];
+}
+interface ValidationResult {
+    /** Errors keyed by field path; empty object when everything validates. */
+    errors: Record<string, string>;
+    /** `true` when `errors` is empty. */
+    isValid: boolean;
+}
+
+export type { FormValues as F, StoreListener as S, Unsubscribe as U, Validator as V, WatchListener as W, FieldPath as a, ValidationResult as b, ValidationSchema as c, FormStore as d, FieldRules as e, FormLevelValidator as f, ValidationContext as g };

package/dist/validators.cjs

@@ -0,0 +1,99 @@
+'use strict';
+
+// src/core/utils/deepEqual.ts
+function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((item, index) => deepEqual(item, b[index]));
+  }
+  const aIsPlainObject = typeof a === "object" && a !== null && !Array.isArray(a) && a.constructor === Object;
+  const bIsPlainObject = typeof b === "object" && b !== null && !Array.isArray(b) && b.constructor === Object;
+  if (aIsPlainObject && bIsPlainObject) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) return false;
+    return aKeys.every(
+      (key) => deepEqual(a[key], b[key])
+    );
+  }
+  return false;
+}
+
+// src/core/utils/paths.ts
+function splitPath(path) {
+  return path.split(".").filter(Boolean);
+}
+function getAtPath(source, path) {
+  const segments = splitPath(path);
+  let current = source;
+  for (const segment of segments) {
+    if (current === null || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
+// src/validators.ts
+function required(message = "This field is required.") {
+  return (value) => {
+    if (value === void 0 || value === null) return message;
+    if (typeof value === "string" && value.trim() === "") return message;
+    if (Array.isArray(value) && value.length === 0) return message;
+    return void 0;
+  };
+}
+function minLength(limit, message) {
+  const msg = message ?? `Must be at least ${limit} characters.`;
+  return (value) => {
+    if (value === void 0 || value === null) return void 0;
+    const length = typeof value === "string" || Array.isArray(value) ? value.length : void 0;
+    return length !== void 0 && length < limit ? msg : void 0;
+  };
+}
+function maxLength(limit, message) {
+  const msg = message ?? `Must be at most ${limit} characters.`;
+  return (value) => {
+    if (value === void 0 || value === null) return void 0;
+    const length = typeof value === "string" || Array.isArray(value) ? value.length : void 0;
+    return length !== void 0 && length > limit ? msg : void 0;
+  };
+}
+function pattern(regex, message = "Invalid format.") {
+  return (value) => typeof value === "string" && value !== "" && !regex.test(value) ? message : void 0;
+}
+function email(message = "Enter a valid email address.") {
+  return pattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, message);
+}
+function min(bound, message) {
+  const msg = message ?? `Must be ${bound} or more.`;
+  return (value) => typeof value === "number" && Number.isFinite(value) && value < bound ? msg : void 0;
+}
+function max(bound, message) {
+  const msg = message ?? `Must be ${bound} or less.`;
+  return (value) => typeof value === "number" && Number.isFinite(value) && value > bound ? msg : void 0;
+}
+function oneOf(allowed, message = "Invalid selection.") {
+  return (value) => {
+    if (value === void 0 || value === null || value === "") return void 0;
+    return allowed.includes(value) ? void 0 : message;
+  };
+}
+function matches(otherPath, message) {
+  const msg = message ?? `Must match ${otherPath}.`;
+  return (value, { values }) => deepEqual(value, getAtPath(values, otherPath)) ? void 0 : msg;
+}
+
+exports.email = email;
+exports.matches = matches;
+exports.max = max;
+exports.maxLength = maxLength;
+exports.min = min;
+exports.minLength = minLength;
+exports.oneOf = oneOf;
+exports.pattern = pattern;
+exports.required = required;
+//# sourceMappingURL=validators.cjs.map
+//# sourceMappingURL=validators.cjs.map

package/dist/validators.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/utils/deepEqual.ts","../src/core/utils/paths.ts","../src/validators.ts"],"names":[],"mappings":"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","file":"validators.cjs","sourcesContent":["/**\r\n * Structural equality for plain JSON-like form values (objects, arrays,\r\n * primitives). Non-plain values (Date, File, custom classes) fall back to\r\n * `Object.is` rather than field-by-field inspection — sufficient for dirty\r\n * tracking, since those values are typically replaced wholesale rather than\r\n * mutated in place. Revisit only if a real use case needs otherwise.\r\n */\r\nexport function deepEqual(a: unknown, b: unknown): boolean {\r\n  if (Object.is(a, b)) return true;\r\n\r\n  if (Array.isArray(a) && Array.isArray(b)) {\r\n    if (a.length !== b.length) return false;\r\n    return a.every((item, index) => deepEqual(item, b[index]));\r\n  }\r\n\r\n  const aIsPlainObject =\r\n    typeof a === \"object\" && a !== null && !Array.isArray(a) && a.constructor === Object;\r\n  const bIsPlainObject =\r\n    typeof b === \"object\" && b !== null && !Array.isArray(b) && b.constructor === Object;\r\n\r\n  if (aIsPlainObject && bIsPlainObject) {\r\n    const aKeys = Object.keys(a as Record<string, unknown>);\r\n    const bKeys = Object.keys(b as Record<string, unknown>);\r\n    if (aKeys.length !== bKeys.length) return false;\r\n    return aKeys.every((key) =>\r\n      deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]),\r\n    );\r\n  }\r\n\r\n  return false;\r\n}\r\n","/**\r\n * Minimal, dependency-free dot-path helpers.\r\n *\r\n * Deliberately not using lodash here (get/set/isEqual) even though the\r\n * reference application relies on it — the whole store is small enough that\r\n * shipping ~30 lines here beats pulling in a runtime dependency for a\r\n * library meant to stay near-zero-dependency (see roadmap: \"Dependency\r\n * Philosophy\").\r\n */\r\n\r\nexport function splitPath(path: string): string[] {\r\n  return path.split(\".\").filter(Boolean);\r\n}\r\n\r\nexport function getAtPath(source: unknown, path: string): unknown {\r\n  const segments = splitPath(path);\r\n  let current: unknown = source;\r\n  for (const segment of segments) {\r\n    if (current === null || typeof current !== \"object\") {\r\n      return undefined;\r\n    }\r\n    current = (current as Record<string, unknown>)[segment];\r\n  }\r\n  return current;\r\n}\r\n\r\n/**\r\n * Returns a new object with `value` written at `path`, cloning only the\r\n * objects along the path (structural sharing everywhere else). This is what\r\n * lets subscribers cheaply detect \"did the branch I care about change?\" via\r\n * reference equality, without deep-cloning the whole form on every keystroke.\r\n */\r\nexport function setAtPath<T extends Record<string, unknown>>(\r\n  source: T,\r\n  path: string,\r\n  value: unknown,\r\n): T {\r\n  const segments = splitPath(path);\r\n  if (segments.length === 0) return source;\r\n\r\n  const [head, ...rest] = segments as [string, ...string[]];\r\n\r\n  if (rest.length === 0) {\r\n    if (Object.is((source as Record<string, unknown>)[head], value)) {\r\n      return source;\r\n    }\r\n    return { ...source, [head]: value };\r\n  }\r\n\r\n  const currentChild = (source as Record<string, unknown>)[head];\r\n  const childSource =\r\n    currentChild !== null && typeof currentChild === \"object\"\r\n      ? (currentChild as Record<string, unknown>)\r\n      : {};\r\n\r\n  const nextChild = setAtPath(childSource, rest.join(\".\"), value);\r\n\r\n  if (Object.is(currentChild, nextChild)) {\r\n    return source;\r\n  }\r\n\r\n  return { ...source, [head]: nextChild };\r\n}\r\n\r\n/**\r\n * Shallow-merges `partial` into `source` at the top level, one key at a\r\n * time, reusing setAtPath so each key's structural-sharing behavior stays\r\n * consistent with single-field writes.\r\n */\r\nexport function mergeAtRoot<T extends Record<string, unknown>>(\r\n  source: T,\r\n  partial: Partial<T>,\r\n): T {\r\n  let next: T = source;\r\n  for (const key of Object.keys(partial)) {\r\n    next = setAtPath(next, key, (partial as Record<string, unknown>)[key]);\r\n  }\r\n  return next;\r\n}\r\n\r\n/**\r\n * Returns every dot-path whose leaf value differs (by reference, via\r\n * Object.is) between `prev` and `next`, walking both objects together.\r\n * Used to compute exactly which paths to notify subscribers about.\r\n */\r\nexport function diffPaths(\r\n  prev: unknown,\r\n  next: unknown,\r\n  basePath = \"\",\r\n  seen: Set<string> = new Set(),\r\n): string[] {\r\n  if (Object.is(prev, next)) {\r\n    return [];\r\n  }\r\n\r\n  const prevIsObject = prev !== null && typeof prev === \"object\" && !Array.isArray(prev);\r\n  const nextIsObject = next !== null && typeof next === \"object\" && !Array.isArray(next);\r\n\r\n  if (!prevIsObject || !nextIsObject) {\r\n    return basePath ? [basePath] : [];\r\n  }\r\n\r\n  const keys = new Set([\r\n    ...Object.keys(prev as Record<string, unknown>),\r\n    ...Object.keys(next as Record<string, unknown>),\r\n  ]);\r\n\r\n  const changed: string[] = [];\r\n  for (const key of keys) {\r\n    const childPath = basePath ? `${basePath}.${key}` : key;\r\n    if (seen.has(childPath)) continue;\r\n    seen.add(childPath);\r\n    changed.push(\r\n      ...diffPaths(\r\n        (prev as Record<string, unknown>)[key],\r\n        (next as Record<string, unknown>)[key],\r\n        childPath,\r\n        seen,\r\n      ),\r\n    );\r\n  }\r\n  return changed;\r\n}\r\n","// Phase 2: ready-made validators for the validation schema consumed by\r\n// `useForm({ validation })` / `validateValues`. Every factory returns a\r\n// pure `Validator` — (value, context) => message | undefined — so custom\r\n// rules compose with these on equal footing.\r\n//\r\n// Conventions shared by all of them:\r\n// - An ABSENT value (undefined/null) is only `required()`'s concern; every\r\n//   other rule passes absent values through so \"optional but validated\"\r\n//   fields work (e.g. optional email that must be well-formed if given).\r\n// - Rules that don't apply to a value's type pass (e.g. `min` ignores\r\n//   strings) — type enforcement belongs to the field's normalizer.\r\n// - Messages are plain English defaults; every factory accepts an override\r\n//   (i18n/error-message catalogs are a later-phase concern).\r\n\r\nimport type { Validator } from \"./core/types/validation\";\r\nimport { deepEqual } from \"./core/utils/deepEqual\";\r\nimport { getAtPath } from \"./core/utils/paths\";\r\n\r\n/** Fails on undefined, null, empty string, whitespace-only string, empty array. */\r\nexport function required(message = \"This field is required.\"): Validator {\r\n  return (value) => {\r\n    if (value === undefined || value === null) return message;\r\n    if (typeof value === \"string\" && value.trim() === \"\") return message;\r\n    if (Array.isArray(value) && value.length === 0) return message;\r\n    return undefined;\r\n  };\r\n}\r\n\r\nexport function minLength(limit: number, message?: string): Validator {\r\n  const msg = message ?? `Must be at least ${limit} characters.`;\r\n  return (value) => {\r\n    if (value === undefined || value === null) return undefined;\r\n    const length = typeof value === \"string\" || Array.isArray(value) ? value.length : undefined;\r\n    return length !== undefined && length < limit ? msg : undefined;\r\n  };\r\n}\r\n\r\nexport function maxLength(limit: number, message?: string): Validator {\r\n  const msg = message ?? `Must be at most ${limit} characters.`;\r\n  return (value) => {\r\n    if (value === undefined || value === null) return undefined;\r\n    const length = typeof value === \"string\" || Array.isArray(value) ? value.length : undefined;\r\n    return length !== undefined && length > limit ? msg : undefined;\r\n  };\r\n}\r\n\r\nexport function pattern(regex: RegExp, message = \"Invalid format.\"): Validator {\r\n  return (value) =>\r\n    typeof value === \"string\" && value !== \"\" && !regex.test(value) ? message : undefined;\r\n}\r\n\r\nexport function email(message = \"Enter a valid email address.\"): Validator {\r\n  return pattern(/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/, message);\r\n}\r\n\r\nexport function min(bound: number, message?: string): Validator {\r\n  const msg = message ?? `Must be ${bound} or more.`;\r\n  return (value) =>\r\n    typeof value === \"number\" && Number.isFinite(value) && value < bound ? msg : undefined;\r\n}\r\n\r\nexport function max(bound: number, message?: string): Validator {\r\n  const msg = message ?? `Must be ${bound} or less.`;\r\n  return (value) =>\r\n    typeof value === \"number\" && Number.isFinite(value) && value > bound ? msg : undefined;\r\n}\r\n\r\n/** Value must be one of the given options (selects, dropdowns). */\r\nexport function oneOf(allowed: readonly unknown[], message = \"Invalid selection.\"): Validator {\r\n  return (value) => {\r\n    if (value === undefined || value === null || value === \"\") return undefined;\r\n    return allowed.includes(value) ? undefined : message;\r\n  };\r\n}\r\n\r\n/**\r\n * Cross-field equality: the field's value must deeply equal the value at\r\n * `otherPath` (scope-relative) — confirm-password, confirm-email, and the\r\n * equality flavor of date-range checks.\r\n */\r\nexport function matches(otherPath: string, message?: string): Validator {\r\n  const msg = message ?? `Must match ${otherPath}.`;\r\n  return (value, { values }) =>\r\n    deepEqual(value, getAtPath(values, otherPath)) ? undefined : msg;\r\n}\r\n"]}

package/dist/validators.d.cts

@@ -0,0 +1,20 @@
+import { V as Validator } from './validation-gIT3Xn9h.cjs';
+
+/** Fails on undefined, null, empty string, whitespace-only string, empty array. */
+declare function required(message?: string): Validator;
+declare function minLength(limit: number, message?: string): Validator;
+declare function maxLength(limit: number, message?: string): Validator;
+declare function pattern(regex: RegExp, message?: string): Validator;
+declare function email(message?: string): Validator;
+declare function min(bound: number, message?: string): Validator;
+declare function max(bound: number, message?: string): Validator;
+/** Value must be one of the given options (selects, dropdowns). */
+declare function oneOf(allowed: readonly unknown[], message?: string): Validator;
+/**
+ * Cross-field equality: the field's value must deeply equal the value at
+ * `otherPath` (scope-relative) — confirm-password, confirm-email, and the
+ * equality flavor of date-range checks.
+ */
+declare function matches(otherPath: string, message?: string): Validator;
+
+export { email, matches, max, maxLength, min, minLength, oneOf, pattern, required };

package/dist/validators.d.ts

@@ -0,0 +1,20 @@
+import { V as Validator } from './validation-gIT3Xn9h.js';
+
+/** Fails on undefined, null, empty string, whitespace-only string, empty array. */
+declare function required(message?: string): Validator;
+declare function minLength(limit: number, message?: string): Validator;
+declare function maxLength(limit: number, message?: string): Validator;
+declare function pattern(regex: RegExp, message?: string): Validator;
+declare function email(message?: string): Validator;
+declare function min(bound: number, message?: string): Validator;
+declare function max(bound: number, message?: string): Validator;
+/** Value must be one of the given options (selects, dropdowns). */
+declare function oneOf(allowed: readonly unknown[], message?: string): Validator;
+/**
+ * Cross-field equality: the field's value must deeply equal the value at
+ * `otherPath` (scope-relative) — confirm-password, confirm-email, and the
+ * equality flavor of date-range checks.
+ */
+declare function matches(otherPath: string, message?: string): Validator;
+
+export { email, matches, max, maxLength, min, minLength, oneOf, pattern, required };

package/dist/validators.js

@@ -0,0 +1,89 @@
+// src/core/utils/deepEqual.ts
+function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((item, index) => deepEqual(item, b[index]));
+  }
+  const aIsPlainObject = typeof a === "object" && a !== null && !Array.isArray(a) && a.constructor === Object;
+  const bIsPlainObject = typeof b === "object" && b !== null && !Array.isArray(b) && b.constructor === Object;
+  if (aIsPlainObject && bIsPlainObject) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) return false;
+    return aKeys.every(
+      (key) => deepEqual(a[key], b[key])
+    );
+  }
+  return false;
+}
+
+// src/core/utils/paths.ts
+function splitPath(path) {
+  return path.split(".").filter(Boolean);
+}
+function getAtPath(source, path) {
+  const segments = splitPath(path);
+  let current = source;
+  for (const segment of segments) {
+    if (current === null || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
+// src/validators.ts
+function required(message = "This field is required.") {
+  return (value) => {
+    if (value === void 0 || value === null) return message;
+    if (typeof value === "string" && value.trim() === "") return message;
+    if (Array.isArray(value) && value.length === 0) return message;
+    return void 0;
+  };
+}
+function minLength(limit, message) {
+  const msg = message ?? `Must be at least ${limit} characters.`;
+  return (value) => {
+    if (value === void 0 || value === null) return void 0;
+    const length = typeof value === "string" || Array.isArray(value) ? value.length : void 0;
+    return length !== void 0 && length < limit ? msg : void 0;
+  };
+}
+function maxLength(limit, message) {
+  const msg = message ?? `Must be at most ${limit} characters.`;
+  return (value) => {
+    if (value === void 0 || value === null) return void 0;
+    const length = typeof value === "string" || Array.isArray(value) ? value.length : void 0;
+    return length !== void 0 && length > limit ? msg : void 0;
+  };
+}
+function pattern(regex, message = "Invalid format.") {
+  return (value) => typeof value === "string" && value !== "" && !regex.test(value) ? message : void 0;
+}
+function email(message = "Enter a valid email address.") {
+  return pattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, message);
+}
+function min(bound, message) {
+  const msg = message ?? `Must be ${bound} or more.`;
+  return (value) => typeof value === "number" && Number.isFinite(value) && value < bound ? msg : void 0;
+}
+function max(bound, message) {
+  const msg = message ?? `Must be ${bound} or less.`;
+  return (value) => typeof value === "number" && Number.isFinite(value) && value > bound ? msg : void 0;
+}
+function oneOf(allowed, message = "Invalid selection.") {
+  return (value) => {
+    if (value === void 0 || value === null || value === "") return void 0;
+    return allowed.includes(value) ? void 0 : message;
+  };
+}
+function matches(otherPath, message) {
+  const msg = message ?? `Must match ${otherPath}.`;
+  return (value, { values }) => deepEqual(value, getAtPath(values, otherPath)) ? void 0 : msg;
+}
+
+export { email, matches, max, maxLength, min, minLength, oneOf, pattern, required };
+//# sourceMappingURL=validators.js.map
+//# sourceMappingURL=validators.js.map

package/dist/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/utils/deepEqual.ts","../src/core/utils/paths.ts","../src/validators.ts"],"names":[],"mappings":"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","file":"validators.js","sourcesContent":["/**\r\n * Structural equality for plain JSON-like form values (objects, arrays,\r\n * primitives). Non-plain values (Date, File, custom classes) fall back to\r\n * `Object.is` rather than field-by-field inspection — sufficient for dirty\r\n * tracking, since those values are typically replaced wholesale rather than\r\n * mutated in place. Revisit only if a real use case needs otherwise.\r\n */\r\nexport function deepEqual(a: unknown, b: unknown): boolean {\r\n  if (Object.is(a, b)) return true;\r\n\r\n  if (Array.isArray(a) && Array.isArray(b)) {\r\n    if (a.length !== b.length) return false;\r\n    return a.every((item, index) => deepEqual(item, b[index]));\r\n  }\r\n\r\n  const aIsPlainObject =\r\n    typeof a === \"object\" && a !== null && !Array.isArray(a) && a.constructor === Object;\r\n  const bIsPlainObject =\r\n    typeof b === \"object\" && b !== null && !Array.isArray(b) && b.constructor === Object;\r\n\r\n  if (aIsPlainObject && bIsPlainObject) {\r\n    const aKeys = Object.keys(a as Record<string, unknown>);\r\n    const bKeys = Object.keys(b as Record<string, unknown>);\r\n    if (aKeys.length !== bKeys.length) return false;\r\n    return aKeys.every((key) =>\r\n      deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]),\r\n    );\r\n  }\r\n\r\n  return false;\r\n}\r\n","/**\r\n * Minimal, dependency-free dot-path helpers.\r\n *\r\n * Deliberately not using lodash here (get/set/isEqual) even though the\r\n * reference application relies on it — the whole store is small enough that\r\n * shipping ~30 lines here beats pulling in a runtime dependency for a\r\n * library meant to stay near-zero-dependency (see roadmap: \"Dependency\r\n * Philosophy\").\r\n */\r\n\r\nexport function splitPath(path: string): string[] {\r\n  return path.split(\".\").filter(Boolean);\r\n}\r\n\r\nexport function getAtPath(source: unknown, path: string): unknown {\r\n  const segments = splitPath(path);\r\n  let current: unknown = source;\r\n  for (const segment of segments) {\r\n    if (current === null || typeof current !== \"object\") {\r\n      return undefined;\r\n    }\r\n    current = (current as Record<string, unknown>)[segment];\r\n  }\r\n  return current;\r\n}\r\n\r\n/**\r\n * Returns a new object with `value` written at `path`, cloning only the\r\n * objects along the path (structural sharing everywhere else). This is what\r\n * lets subscribers cheaply detect \"did the branch I care about change?\" via\r\n * reference equality, without deep-cloning the whole form on every keystroke.\r\n */\r\nexport function setAtPath<T extends Record<string, unknown>>(\r\n  source: T,\r\n  path: string,\r\n  value: unknown,\r\n): T {\r\n  const segments = splitPath(path);\r\n  if (segments.length === 0) return source;\r\n\r\n  const [head, ...rest] = segments as [string, ...string[]];\r\n\r\n  if (rest.length === 0) {\r\n    if (Object.is((source as Record<string, unknown>)[head], value)) {\r\n      return source;\r\n    }\r\n    return { ...source, [head]: value };\r\n  }\r\n\r\n  const currentChild = (source as Record<string, unknown>)[head];\r\n  const childSource =\r\n    currentChild !== null && typeof currentChild === \"object\"\r\n      ? (currentChild as Record<string, unknown>)\r\n      : {};\r\n\r\n  const nextChild = setAtPath(childSource, rest.join(\".\"), value);\r\n\r\n  if (Object.is(currentChild, nextChild)) {\r\n    return source;\r\n  }\r\n\r\n  return { ...source, [head]: nextChild };\r\n}\r\n\r\n/**\r\n * Shallow-merges `partial` into `source` at the top level, one key at a\r\n * time, reusing setAtPath so each key's structural-sharing behavior stays\r\n * consistent with single-field writes.\r\n */\r\nexport function mergeAtRoot<T extends Record<string, unknown>>(\r\n  source: T,\r\n  partial: Partial<T>,\r\n): T {\r\n  let next: T = source;\r\n  for (const key of Object.keys(partial)) {\r\n    next = setAtPath(next, key, (partial as Record<string, unknown>)[key]);\r\n  }\r\n  return next;\r\n}\r\n\r\n/**\r\n * Returns every dot-path whose leaf value differs (by reference, via\r\n * Object.is) between `prev` and `next`, walking both objects together.\r\n * Used to compute exactly which paths to notify subscribers about.\r\n */\r\nexport function diffPaths(\r\n  prev: unknown,\r\n  next: unknown,\r\n  basePath = \"\",\r\n  seen: Set<string> = new Set(),\r\n): string[] {\r\n  if (Object.is(prev, next)) {\r\n    return [];\r\n  }\r\n\r\n  const prevIsObject = prev !== null && typeof prev === \"object\" && !Array.isArray(prev);\r\n  const nextIsObject = next !== null && typeof next === \"object\" && !Array.isArray(next);\r\n\r\n  if (!prevIsObject || !nextIsObject) {\r\n    return basePath ? [basePath] : [];\r\n  }\r\n\r\n  const keys = new Set([\r\n    ...Object.keys(prev as Record<string, unknown>),\r\n    ...Object.keys(next as Record<string, unknown>),\r\n  ]);\r\n\r\n  const changed: string[] = [];\r\n  for (const key of keys) {\r\n    const childPath = basePath ? `${basePath}.${key}` : key;\r\n    if (seen.has(childPath)) continue;\r\n    seen.add(childPath);\r\n    changed.push(\r\n      ...diffPaths(\r\n        (prev as Record<string, unknown>)[key],\r\n        (next as Record<string, unknown>)[key],\r\n        childPath,\r\n        seen,\r\n      ),\r\n    );\r\n  }\r\n  return changed;\r\n}\r\n","// Phase 2: ready-made validators for the validation schema consumed by\r\n// `useForm({ validation })` / `validateValues`. Every factory returns a\r\n// pure `Validator` — (value, context) => message | undefined — so custom\r\n// rules compose with these on equal footing.\r\n//\r\n// Conventions shared by all of them:\r\n// - An ABSENT value (undefined/null) is only `required()`'s concern; every\r\n//   other rule passes absent values through so \"optional but validated\"\r\n//   fields work (e.g. optional email that must be well-formed if given).\r\n// - Rules that don't apply to a value's type pass (e.g. `min` ignores\r\n//   strings) — type enforcement belongs to the field's normalizer.\r\n// - Messages are plain English defaults; every factory accepts an override\r\n//   (i18n/error-message catalogs are a later-phase concern).\r\n\r\nimport type { Validator } from \"./core/types/validation\";\r\nimport { deepEqual } from \"./core/utils/deepEqual\";\r\nimport { getAtPath } from \"./core/utils/paths\";\r\n\r\n/** Fails on undefined, null, empty string, whitespace-only string, empty array. */\r\nexport function required(message = \"This field is required.\"): Validator {\r\n  return (value) => {\r\n    if (value === undefined || value === null) return message;\r\n    if (typeof value === \"string\" && value.trim() === \"\") return message;\r\n    if (Array.isArray(value) && value.length === 0) return message;\r\n    return undefined;\r\n  };\r\n}\r\n\r\nexport function minLength(limit: number, message?: string): Validator {\r\n  const msg = message ?? `Must be at least ${limit} characters.`;\r\n  return (value) => {\r\n    if (value === undefined || value === null) return undefined;\r\n    const length = typeof value === \"string\" || Array.isArray(value) ? value.length : undefined;\r\n    return length !== undefined && length < limit ? msg : undefined;\r\n  };\r\n}\r\n\r\nexport function maxLength(limit: number, message?: string): Validator {\r\n  const msg = message ?? `Must be at most ${limit} characters.`;\r\n  return (value) => {\r\n    if (value === undefined || value === null) return undefined;\r\n    const length = typeof value === \"string\" || Array.isArray(value) ? value.length : undefined;\r\n    return length !== undefined && length > limit ? msg : undefined;\r\n  };\r\n}\r\n\r\nexport function pattern(regex: RegExp, message = \"Invalid format.\"): Validator {\r\n  return (value) =>\r\n    typeof value === \"string\" && value !== \"\" && !regex.test(value) ? message : undefined;\r\n}\r\n\r\nexport function email(message = \"Enter a valid email address.\"): Validator {\r\n  return pattern(/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/, message);\r\n}\r\n\r\nexport function min(bound: number, message?: string): Validator {\r\n  const msg = message ?? `Must be ${bound} or more.`;\r\n  return (value) =>\r\n    typeof value === \"number\" && Number.isFinite(value) && value < bound ? msg : undefined;\r\n}\r\n\r\nexport function max(bound: number, message?: string): Validator {\r\n  const msg = message ?? `Must be ${bound} or less.`;\r\n  return (value) =>\r\n    typeof value === \"number\" && Number.isFinite(value) && value > bound ? msg : undefined;\r\n}\r\n\r\n/** Value must be one of the given options (selects, dropdowns). */\r\nexport function oneOf(allowed: readonly unknown[], message = \"Invalid selection.\"): Validator {\r\n  return (value) => {\r\n    if (value === undefined || value === null || value === \"\") return undefined;\r\n    return allowed.includes(value) ? undefined : message;\r\n  };\r\n}\r\n\r\n/**\r\n * Cross-field equality: the field's value must deeply equal the value at\r\n * `otherPath` (scope-relative) — confirm-password, confirm-email, and the\r\n * equality flavor of date-range checks.\r\n */\r\nexport function matches(otherPath: string, message?: string): Validator {\r\n  const msg = message ?? `Must match ${otherPath}.`;\r\n  return (value, { values }) =>\r\n    deepEqual(value, getAtPath(values, otherPath)) ? undefined : msg;\r\n}\r\n"]}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "react-formesh",
+  "version": "0.1.4",
+  "description": "Framework-agnostic, fine-grained form state for complex multi-section forms.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "require": "./dist/react.cjs"
+    },
+    "./validators": {
+      "types": "./dist/validators.d.ts",
+      "import": "./dist/validators.js",
+      "require": "./dist/validators.cjs"
+    },
+    "./file": {
+      "types": "./dist/file.d.ts",
+      "import": "./dist/file.js",
+      "require": "./dist/file.cjs"
+    },
+    "./array": {
+      "types": "./dist/array.d.ts",
+      "import": "./dist/array.js",
+      "require": "./dist/array.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest",
+    "clean": "rimraf dist"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@testing-library/react": "^15.0.0",
+    "@types/react": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "jsdom": "^24.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.5.0"
+  }
+}