@native-form/core 0.1.1 → 0.1.3

package/README.md

@@ -160,19 +160,76 @@ Attach `@native-form/core` via Svelte's `onMount` or action directive:
 
 ---
 
+### 4. React (React 18 & 19)
+
+For React applications, use the official [`@native-form/react`](../react/README.md) package:
+
+```bash
+npm install @native-form/react
+```
+
+```tsx
+import React from "react";
+import { useForm } from "@native-form/react";
+import { zodResolver } from "@native-form/zod";
+import { z } from "zod";
+
+const schema = z.object({
+  email: z.string().email("Enter a valid email"),
+  age: z.number().min(18, "Must be at least 18"),
+});
+
+export function LoginForm() {
+  const { formRef, formState } = useForm({
+    schema: zodResolver(schema),
+    serializationMode: "typed", // automatically coerces type="number" and range to numbers
+    onSubmit: (values) => console.log("Submitted:", values),
+  });
+
+  return (
+    <form ref={formRef} noValidate>
+      <div>
+        <label>Email</label>
+        <input name="email" type="email" placeholder="jane@example.com" />
+        {formState.errors.email && (
+          <p style={{ color: "red" }}>{formState.errors.email}</p>
+        )}
+      </div>
+
+      <div>
+        <label>Age</label>
+        <input name="age" type="number" placeholder="25" />
+        {formState.errors.age && (
+          <p style={{ color: "red" }}>{formState.errors.age}</p>
+        )}
+      </div>
+
+      <button type="submit" disabled={formState.submitting}>
+        {formState.submitting ? "Submitting..." : "Submit"}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
 ## Configuration Options
 
 When instantiating `new Runtime(options)`, the following options are available:
 
 | Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `mode` | `"onSubmit" \| "onBlur" \| "onChange" \| "onTouched" \| "all"` | `"onSubmit"` | Validation trigger strategy. |
-| `serializationMode` | `"native" \| "typed"` | `"native"` | Whether values are serialized as raw strings/FormData or coerced typed values (numbers, booleans). |
+| `mode` | `"onSubmit" \| "onBlur" \| "onChange" \| "onTouched" \| "all"` | `"onSubmit"` | Initial validation trigger strategy. |
+| `reValidateMode` | `"onChange" \| "onBlur" \| "onSubmit"` | `"onChange"` | Re-validation strategy for fields with active errors. Automatically re-validates discrete controls (`checkbox`, `radio`, `select`) on change. |
+| `renderDomErrors` | `boolean` | `true` | Whether the runtime automatically injects DOM `<div data-native-form-error="true">` elements next to invalid inputs. Set to `false` when rendering custom UI errors (defaults to `false` in `@native-form/react`). |
+| `serializationMode` | `"native" \| "typed"` | `"native"` | Whether values are serialized as raw strings/FormData or coerced typed values (numbers, booleans, arrays). |
 | `nesting` | `"flat" \| "nested"` | `"flat"` | Whether dot/bracket notation paths are converted into deep nested objects (e.g. `user.email` -> `{ user: { email } }`). |
 | `preserveUnmountedValues` | `boolean` | `false` | When true, caches values from fields that unmount from the DOM (e.g. multi-step wizard views). |
-| `debounceMs` | `number` | `300` | Debounce delay for async field validators. |
+| `debounceMs` | `number` | `300` | Debounce delay in milliseconds for async field validators. |
 | `asyncValidators` | `Record<string, AsyncValidator>` | `undefined` | Key-value mapping of field names to asynchronous validation functions with `AbortSignal` cancellation. |
 | `schema` | `SchemaLike` | `undefined` | Schema adapter (e.g. from `@native-form/zod`, `@native-form/yup`, `@native-form/valibot`). |
+| `validator` | `Validator` | `undefined` | Custom validator object with a `validate(values, context)` method. |
 | `onSubmit` | `(values, event?) => void` | `undefined` | Callback invoked when submission succeeds and passes validation. |
 | `onInvalid` | `(errors, values, event?) => void` | `undefined` | Callback invoked when submission is blocked due to validation failures. |
 

package/dist/index.cjs

@@ -329,7 +329,8 @@ var FieldNode = class {
         case "radio":
           return this.element.checked ? this.element.value : void 0;
         case "number":
-          return this.element.value === "" ? void 0 : this.element.valueAsNumber;
+        case "range":
+          return this.element.value === "" || Number.isNaN(this.element.valueAsNumber) ? void 0 : this.element.valueAsNumber;
         case "file":
           return this.element.files;
         default:
@@ -489,9 +490,9 @@ var FieldErrorRenderer = class _FieldErrorRenderer {
   static nextErrorId = 0;
   errorIds = /* @__PURE__ */ new WeakMap();
   errorElements = /* @__PURE__ */ new WeakMap();
-  applyErrors(fields, errors) {
+  applyErrors(fields, errors, renderDomErrors = true) {
     for (const field of fields) {
-      this.applyFieldError(field, errors[field.name]);
+      this.applyFieldError(field, errors[field.name], renderDomErrors);
     }
   }
   normalizeFields(fields) {
@@ -499,12 +500,17 @@ var FieldErrorRenderer = class _FieldErrorRenderer {
       this.normalizeField(field);
     }
   }
-  applyFieldError(field, message) {
+  applyFieldError(field, message, renderDomErrors = true) {
     const element = field.element;
     try {
       element.setCustomValidity(message ?? "");
     } catch (_e) {
     }
+    if (!renderDomErrors) {
+      this.removeErrorElements(this.findExistingErrorElements(element));
+      this.errorElements.delete(element);
+      return;
+    }
     if (!message) {
       this.removeErrorElements(this.findExistingErrorElements(element));
       this.errorElements.delete(element);
@@ -1283,7 +1289,11 @@ var Runtime = class {
     const { node, values, value } = snapshot;
     node.handleInput(value);
     const mode = this.options.mode ?? "onChange";
-    const shouldValidate = mode === "onChange" || mode === "all" || mode === "onTouched" && node.isTouched;
+    const reValidateMode = this.options.reValidateMode ?? "onChange";
+    const hasExistingError = Boolean(
+      resolveFieldError(this.errors, element.name)
+    );
+    const shouldValidate = mode === "onChange" || mode === "all" || hasExistingError && reValidateMode === "onChange" || mode === "onTouched" && node.isTouched;
     if (shouldValidate) {
       this.triggerFieldValidation(node, values);
     }
@@ -1308,7 +1318,12 @@ var Runtime = class {
     const { node, values, value } = snapshot;
     node.handleChange(value);
     const mode = this.options.mode ?? "onChange";
-    const shouldValidate = mode === "onChange" || mode === "all" || mode === "onTouched" && node.isTouched;
+    const reValidateMode = this.options.reValidateMode ?? "onChange";
+    const hasExistingError = Boolean(
+      resolveFieldError(this.errors, element.name)
+    );
+    const isDiscreteControl = element instanceof HTMLSelectElement || element instanceof HTMLInputElement && (element.type === "checkbox" || element.type === "radio");
+    const shouldValidate = mode === "onChange" || mode === "all" || isDiscreteControl || hasExistingError && reValidateMode === "onChange" || mode === "onTouched" && node.isTouched;
     if (shouldValidate) {
       this.triggerFieldValidation(node, values);
     }
@@ -1470,8 +1485,12 @@ var Runtime = class {
     const node = this.registry.get(element.name);
     node?.handleBlur();
     const mode = this.options.mode ?? "onChange";
+    const reValidateMode = this.options.reValidateMode ?? "onChange";
+    const hasExistingError = Boolean(
+      resolveFieldError(this.errors, element.name)
+    );
     const hasPendingDebounce = this.debounceTimers.has(element.name);
-    const shouldValidate = mode === "onBlur" || mode === "onTouched" || mode === "all" || hasPendingDebounce;
+    const shouldValidate = mode === "onBlur" || mode === "onTouched" || mode === "all" || hasExistingError && reValidateMode === "onBlur" || hasPendingDebounce;
     if (shouldValidate && node) {
       this.triggerFieldValidation(node, values, true);
     }
@@ -2017,7 +2036,12 @@ var Runtime = class {
     if (observer) {
       observer.disconnect();
     }
-    this.fieldErrorRenderer.applyErrors(this.registry.values(), this.errors);
+    const renderDomErrors = this.options.renderDomErrors ?? true;
+    this.fieldErrorRenderer.applyErrors(
+      this.registry.values(),
+      this.errors,
+      renderDomErrors
+    );
     if (observer && this.form) {
       observer.observe(this.form, runtimeMutationObserverOptions);
     }

package/dist/index.d.cts

@@ -8,6 +8,14 @@
  * @public
  */
 type ValidationMode = "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all";
+/**
+ * Supported re-validation modes for fields that currently contain errors.
+ * - onChange: re-validates on every input/change event once an error is present
+ * - onBlur: re-validates only when the input loses focus
+ * - onSubmit: re-validates only on subsequent form submissions
+ * @public
+ */
+type ReValidateMode = "onChange" | "onBlur" | "onSubmit";
 /** @public */
 type NativeFormElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
 /**
@@ -284,6 +292,20 @@ declare function createValidationPipeline<TValues extends NativeFormValues = Nat
 /** @public */
 interface RuntimeOptions<TValues extends NativeFormValues = NativeFormValues> {
     mode?: ValidationMode;
+    /**
+     * Validation strategy used after the form has encountered errors.
+     * - "onChange": field re-validates immediately on input/change when it has an error
+     * - "onBlur": field re-validates when blurred
+     * - "onSubmit": field re-validates only on subsequent submits
+     * @defaultValue "onChange"
+     */
+    reValidateMode?: ReValidateMode;
+    /**
+     * Whether to inject native DOM error elements after inputs.
+     * Defaults to `true` in core, but `false` in `@native-form/react`.
+     * @defaultValue true
+     */
+    renderDomErrors?: boolean;
     serializationMode?: SerializationMode;
     serializeFieldsOptions?: SerializeFieldsOptions;
     nesting?: "flat" | "nested";
@@ -492,4 +514,4 @@ declare function setByPath(target: Record<string, unknown>, path: string | reado
 declare function toNestedValues<TOutput extends Record<string, unknown> = Record<string, unknown>>(flatValues: Record<string, unknown>): TOutput;
 
 export { FieldNode, Runtime, Serializer, arrayItemPath, createValidationPipeline, createValidator, formPath, getByPath, isArrayItemPath, matchArrayItemPath, normalizePath, parseArrayItemPath, remapArrayItemIndex, setByPath, shiftArrayItemIndex, splitPath, toNestedValues };
-export type { ArrayItemPathInfo, AsyncFieldValidator, FieldEvents, FieldPathSegment, FieldState, FormEvents, InferSchemaOutput, NativeFormElement, NativeFormFlatValues, NativeFormNestedValue, NativeFormValue, NativeFormValues, RuntimeEvent, RuntimeEventType, RuntimeFormState, RuntimeListener, RuntimeOptions, RuntimePublicApi, SchemaLike, SerializationMode, SerializeFieldsOptions, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, ValidationContext, ValidationEvents, ValidationFieldMeta, ValidationIssue, ValidationMode, ValidationPipeline, ValidationPipelineCapabilities, ValidationPipelineContext, ValidationPipelineOptions, ValidationResult, Validator };
+export type { ArrayItemPathInfo, AsyncFieldValidator, FieldEvents, FieldPathSegment, FieldState, FormEvents, InferSchemaOutput, NativeFormElement, NativeFormFlatValues, NativeFormNestedValue, NativeFormValue, NativeFormValues, ReValidateMode, RuntimeEvent, RuntimeEventType, RuntimeFormState, RuntimeListener, RuntimeOptions, RuntimePublicApi, SchemaLike, SerializationMode, SerializeFieldsOptions, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, ValidationContext, ValidationEvents, ValidationFieldMeta, ValidationIssue, ValidationMode, ValidationPipeline, ValidationPipelineCapabilities, ValidationPipelineContext, ValidationPipelineOptions, ValidationResult, Validator };

package/dist/index.d.ts

@@ -8,6 +8,14 @@
  * @public
  */
 type ValidationMode = "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all";
+/**
+ * Supported re-validation modes for fields that currently contain errors.
+ * - onChange: re-validates on every input/change event once an error is present
+ * - onBlur: re-validates only when the input loses focus
+ * - onSubmit: re-validates only on subsequent form submissions
+ * @public
+ */
+type ReValidateMode = "onChange" | "onBlur" | "onSubmit";
 /** @public */
 type NativeFormElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
 /**
@@ -284,6 +292,20 @@ declare function createValidationPipeline<TValues extends NativeFormValues = Nat
 /** @public */
 interface RuntimeOptions<TValues extends NativeFormValues = NativeFormValues> {
     mode?: ValidationMode;
+    /**
+     * Validation strategy used after the form has encountered errors.
+     * - "onChange": field re-validates immediately on input/change when it has an error
+     * - "onBlur": field re-validates when blurred
+     * - "onSubmit": field re-validates only on subsequent submits
+     * @defaultValue "onChange"
+     */
+    reValidateMode?: ReValidateMode;
+    /**
+     * Whether to inject native DOM error elements after inputs.
+     * Defaults to `true` in core, but `false` in `@native-form/react`.
+     * @defaultValue true
+     */
+    renderDomErrors?: boolean;
     serializationMode?: SerializationMode;
     serializeFieldsOptions?: SerializeFieldsOptions;
     nesting?: "flat" | "nested";
@@ -492,4 +514,4 @@ declare function setByPath(target: Record<string, unknown>, path: string | reado
 declare function toNestedValues<TOutput extends Record<string, unknown> = Record<string, unknown>>(flatValues: Record<string, unknown>): TOutput;
 
 export { FieldNode, Runtime, Serializer, arrayItemPath, createValidationPipeline, createValidator, formPath, getByPath, isArrayItemPath, matchArrayItemPath, normalizePath, parseArrayItemPath, remapArrayItemIndex, setByPath, shiftArrayItemIndex, splitPath, toNestedValues };
-export type { ArrayItemPathInfo, AsyncFieldValidator, FieldEvents, FieldPathSegment, FieldState, FormEvents, InferSchemaOutput, NativeFormElement, NativeFormFlatValues, NativeFormNestedValue, NativeFormValue, NativeFormValues, RuntimeEvent, RuntimeEventType, RuntimeFormState, RuntimeListener, RuntimeOptions, RuntimePublicApi, SchemaLike, SerializationMode, SerializeFieldsOptions, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, ValidationContext, ValidationEvents, ValidationFieldMeta, ValidationIssue, ValidationMode, ValidationPipeline, ValidationPipelineCapabilities, ValidationPipelineContext, ValidationPipelineOptions, ValidationResult, Validator };
+export type { ArrayItemPathInfo, AsyncFieldValidator, FieldEvents, FieldPathSegment, FieldState, FormEvents, InferSchemaOutput, NativeFormElement, NativeFormFlatValues, NativeFormNestedValue, NativeFormValue, NativeFormValues, ReValidateMode, RuntimeEvent, RuntimeEventType, RuntimeFormState, RuntimeListener, RuntimeOptions, RuntimePublicApi, SchemaLike, SerializationMode, SerializeFieldsOptions, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, ValidationContext, ValidationEvents, ValidationFieldMeta, ValidationIssue, ValidationMode, ValidationPipeline, ValidationPipelineCapabilities, ValidationPipelineContext, ValidationPipelineOptions, ValidationResult, Validator };

package/dist/index.js

@@ -287,7 +287,8 @@ var FieldNode = class {
         case "radio":
           return this.element.checked ? this.element.value : void 0;
         case "number":
-          return this.element.value === "" ? void 0 : this.element.valueAsNumber;
+        case "range":
+          return this.element.value === "" || Number.isNaN(this.element.valueAsNumber) ? void 0 : this.element.valueAsNumber;
         case "file":
           return this.element.files;
         default:
@@ -447,9 +448,9 @@ var FieldErrorRenderer = class _FieldErrorRenderer {
   static nextErrorId = 0;
   errorIds = /* @__PURE__ */ new WeakMap();
   errorElements = /* @__PURE__ */ new WeakMap();
-  applyErrors(fields, errors) {
+  applyErrors(fields, errors, renderDomErrors = true) {
     for (const field of fields) {
-      this.applyFieldError(field, errors[field.name]);
+      this.applyFieldError(field, errors[field.name], renderDomErrors);
     }
   }
   normalizeFields(fields) {
@@ -457,12 +458,17 @@ var FieldErrorRenderer = class _FieldErrorRenderer {
       this.normalizeField(field);
     }
   }
-  applyFieldError(field, message) {
+  applyFieldError(field, message, renderDomErrors = true) {
     const element = field.element;
     try {
       element.setCustomValidity(message ?? "");
     } catch (_e) {
     }
+    if (!renderDomErrors) {
+      this.removeErrorElements(this.findExistingErrorElements(element));
+      this.errorElements.delete(element);
+      return;
+    }
     if (!message) {
       this.removeErrorElements(this.findExistingErrorElements(element));
       this.errorElements.delete(element);
@@ -1241,7 +1247,11 @@ var Runtime = class {
     const { node, values, value } = snapshot;
     node.handleInput(value);
     const mode = this.options.mode ?? "onChange";
-    const shouldValidate = mode === "onChange" || mode === "all" || mode === "onTouched" && node.isTouched;
+    const reValidateMode = this.options.reValidateMode ?? "onChange";
+    const hasExistingError = Boolean(
+      resolveFieldError(this.errors, element.name)
+    );
+    const shouldValidate = mode === "onChange" || mode === "all" || hasExistingError && reValidateMode === "onChange" || mode === "onTouched" && node.isTouched;
     if (shouldValidate) {
       this.triggerFieldValidation(node, values);
     }
@@ -1266,7 +1276,12 @@ var Runtime = class {
     const { node, values, value } = snapshot;
     node.handleChange(value);
     const mode = this.options.mode ?? "onChange";
-    const shouldValidate = mode === "onChange" || mode === "all" || mode === "onTouched" && node.isTouched;
+    const reValidateMode = this.options.reValidateMode ?? "onChange";
+    const hasExistingError = Boolean(
+      resolveFieldError(this.errors, element.name)
+    );
+    const isDiscreteControl = element instanceof HTMLSelectElement || element instanceof HTMLInputElement && (element.type === "checkbox" || element.type === "radio");
+    const shouldValidate = mode === "onChange" || mode === "all" || isDiscreteControl || hasExistingError && reValidateMode === "onChange" || mode === "onTouched" && node.isTouched;
     if (shouldValidate) {
       this.triggerFieldValidation(node, values);
     }
@@ -1428,8 +1443,12 @@ var Runtime = class {
     const node = this.registry.get(element.name);
     node?.handleBlur();
     const mode = this.options.mode ?? "onChange";
+    const reValidateMode = this.options.reValidateMode ?? "onChange";
+    const hasExistingError = Boolean(
+      resolveFieldError(this.errors, element.name)
+    );
     const hasPendingDebounce = this.debounceTimers.has(element.name);
-    const shouldValidate = mode === "onBlur" || mode === "onTouched" || mode === "all" || hasPendingDebounce;
+    const shouldValidate = mode === "onBlur" || mode === "onTouched" || mode === "all" || hasExistingError && reValidateMode === "onBlur" || hasPendingDebounce;
     if (shouldValidate && node) {
       this.triggerFieldValidation(node, values, true);
     }
@@ -1975,7 +1994,12 @@ var Runtime = class {
     if (observer) {
       observer.disconnect();
     }
-    this.fieldErrorRenderer.applyErrors(this.registry.values(), this.errors);
+    const renderDomErrors = this.options.renderDomErrors ?? true;
+    this.fieldErrorRenderer.applyErrors(
+      this.registry.values(),
+      this.errors,
+      renderDomErrors
+    );
     if (observer && this.form) {
       observer.observe(this.form, runtimeMutationObserverOptions);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@native-form/core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Framework-agnostic native HTML-first form runtime, discovery, and validation contracts.",
   "license": "MIT",
   "type": "module",