@samline/forms 2.6.0 → 2.7.0

package/README.md

@@ -42,10 +42,10 @@ Requires Node 20+ when bundling. Runtime target is ES2020.
 Use the browser build when you do not have a bundler and need to run the package directly in HTML, Shopify, WordPress, or any traditional template.
 
 ```html
-<script src="https://unpkg.com/@samline/forms@2.6.0/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/forms@2.7.0/dist/browser/global.global.js"></script>
 ```
 
-> Pin the version in production. Replace `2.6.0` with the version you ship.
+> Pin the version in production. Replace `2.7.0` with the version you ship.
 
 The browser bundle exposes a single global: `window.Forms`.
 
@@ -55,7 +55,7 @@ The browser bundle exposes a single global: `window.Forms`.
   <button type="submit">Send</button>
 </form>
 
-<script src="https://unpkg.com/@samline/forms@2.6.0/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/forms@2.7.0/dist/browser/global.global.js"></script>
 <script>
   const contactForm = window.Forms.newForm({ id: 'contact-form' })
 
@@ -134,7 +134,7 @@ The controller is built around one factory and a small set of focused methods. M
 
 | Group | Methods |
 | --- | --- |
-| Lifecycle | [`form`](docs/api/form.md) · [`destroy`](docs/api/destroy.md) · [`reset`](docs/api/reset.md) |
+| Lifecycle | [`form`](docs/api/form.md) · [`addCleanup`](docs/api/add-cleanup.md) · [`destroy`](docs/api/destroy.md) · [`reset`](docs/api/reset.md) |
 | Registry (vanilla) | [`browser`](docs/getting-started.md#browser-registry-helpers) — bundler-friendly `{ form, newForm, destroyForm, available }` singleton. |
 | Properties | [`element`](docs/api/element.md) · [`options`](docs/options.md) |
 | Submission | [`onSubmit`](docs/api/on-submit.md) · [`autoSubmit`](docs/api/auto-submit.md) · [`disableAutoSubmit`](docs/api/disable-auto-submit.md) |
@@ -144,6 +144,8 @@ The controller is built around one factory and a small set of focused methods. M
 | State and data | [`getData`](docs/api/get-data.md) · [`getState`](docs/api/get-state.md) · [`append`](docs/api/append.md) |
 | Pure helpers | [`parseFormData`](docs/api/parse-form-data.md) · [`validateValues`](docs/api/validate-values.md) · [`validateFieldValue`](docs/api/validate-field-value.md) |
 
+Validation supports explicit cross-field dependencies with `dependsOn`, per-member collection rules with `each`, and strict decimal `numeric` / inclusive `min` / `max` rules. Async `onSubmit` handlers are reflected by `getState().isSubmitting`, while `addCleanup()` lets integrations register controller-owned teardown work.
+
 See the full per-method reference in [`docs/api/`](docs/api/index.md).
 
 ---

package/dist/browser/global.d.ts

@@ -30,16 +30,29 @@ interface FieldValidationContext {
     field: string;
     value: FormFieldValue;
     values: FormValues;
+    /** Concrete control while validating one member through `each`. */
+    element?: FormFieldElement;
+    /** Zero-based member position while validating through `each`. */
+    index?: number;
 }
 type FieldValidator = (context: FieldValidationContext) => string | undefined | null | false | true;
-interface FieldValidationRules {
+interface ValueValidationRules {
     required?: RuleConfig<boolean>;
     minLength?: RuleConfig<number>;
     maxLength?: RuleConfig<number>;
     pattern?: RuleConfig<RegExp>;
+    numeric?: RuleConfig<boolean>;
+    min?: RuleConfig<number>;
+    max?: RuleConfig<number>;
+    validate?: FieldValidator | FieldValidator[];
+}
+interface FieldValidationRules extends ValueValidationRules {
     /** Field name whose non-empty value must equal this field's value. */
     sameAs?: RuleConfig<string>;
-    validate?: FieldValidator | FieldValidator[];
+    /** Fields whose changes should revalidate this field. */
+    dependsOn?: string | string[];
+    /** Rules applied independently to each collection member. */
+    each?: ValueValidationRules;
 }
 type ValidationSchema = Record<string, FieldValidationRules>;
 interface VisualAttributes {
@@ -79,6 +92,7 @@ interface FormStateSnapshot {
     isValid: boolean;
     isValidated: boolean;
     autoSubmit: boolean;
+    isSubmitting: boolean;
     submitCount: number;
 }
 type FormStateListener = (state: FormStateSnapshot) => void;
@@ -93,12 +107,14 @@ interface AppendContentOptions {
     atStart?: boolean;
 }
 type FormFieldWatcher = (value: FormFieldValue, field: FormFieldElement | FormFieldElement[] | null, form: HTMLFormElement, state: FormStateSnapshot) => void;
-type FormSubmitHandler = (form: HTMLFormElement, data: Record<string, SerializedFormValue>, formData: FormData, state: FormStateSnapshot) => void;
+type FormSubmitHandler = (form: HTMLFormElement, data: Record<string, SerializedFormValue>, formData: FormData, state: FormStateSnapshot) => void | Promise<void>;
+type FormCleanup = () => void;
 interface FormController {
     readonly element: HTMLFormElement | null;
     readonly f: HTMLFormElement | null;
     readonly options: FormControllerOptions;
     onSubmit: (callback: FormSubmitHandler, preventDefault?: boolean) => FormController;
+    addCleanup: (cleanup: FormCleanup) => () => void;
     watch: (field: string, callback: FormFieldWatcher) => FormController;
     observe: (field: string, callback: FormFieldWatcher) => () => void;
     unwatch: (field?: string, callback?: FormFieldWatcher) => FormController;

package/dist/browser/global.global.js

@@ -4788,6 +4788,22 @@ var Forms = (() => {
     return node;
   };
 
+  // src/api/add-cleanup.ts
+  var createAddCleanup = (state2, _helpers) => (cleanup) => {
+    if (state2.isDestroyed) {
+      cleanup();
+      return () => void 0;
+    }
+    const registration = () => cleanup();
+    state2.cleanups.add(registration);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      state2.cleanups.delete(registration);
+    };
+  };
+
   // src/api/auto-submit.ts
   var createAutoSubmit = (state2, helpers) => (next = true) => {
     state2.autoSubmitEnabled = next !== false;
@@ -5215,12 +5231,24 @@ var Forms = (() => {
     }
     state2.mutationObserver?.disconnect();
     state2.mutationObserver = null;
+    const cleanups = Array.from(state2.cleanups).reverse();
+    state2.cleanups.clear();
+    for (const cleanup of cleanups) {
+      try {
+        cleanup();
+      } catch (error) {
+        console.error("[forms] cleanup failed", error);
+      }
+    }
     state2.watchedFields.clear();
     state2.subscribers.clear();
     state2.submitHandlers.clear();
     state2.fieldCache.clear();
     state2.manualErrors = {};
     state2.validationErrors = {};
+    state2.validationGroupErrors = {};
+    state2.validationElementErrors.clear();
+    state2.pendingSubmitCount = 0;
     cleanupFormatRegistry(state2);
   };
 
@@ -5287,6 +5315,7 @@ var Forms = (() => {
     isValid: true,
     isValidated: false,
     autoSubmit: false,
+    isSubmitting: false,
     submitCount: 0
   });
   var cloneErrors = (errors) => Object.fromEntries(
@@ -5318,6 +5347,7 @@ var Forms = (() => {
       isValid: Object.keys(errors).length === 0,
       isValidated: state2.isValidated,
       autoSubmit: state2.autoSubmitEnabled,
+      isSubmitting: state2.pendingSubmitCount > 0,
       submitCount: state2.submitCount
     };
   };
@@ -5515,12 +5545,14 @@ var Forms = (() => {
     resetFormattedFields(state2);
     state2.manualErrors = {};
     state2.validationErrors = {};
+    state2.validationGroupErrors = {};
+    state2.validationElementErrors.clear();
     clearAttributes(state2.element, [
       state2.attributes.error,
       state2.attributes.filled,
       "aria-invalid"
     ]);
-    if (state2.isValidated) helpers.syncVisualState();
+    helpers.syncVisualState();
     helpers.notifySubscribers();
     return state2.api;
   };
@@ -5631,14 +5663,29 @@ var Forms = (() => {
     }
     return left === right;
   };
-  var validateFieldValue = (field, value, rules, values) => {
+  var DECIMAL_PATTERN = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/;
+  var parseStrictNumber = (value) => {
+    if (typeof value !== "string") return void 0;
+    const candidate = value.trim();
+    if (!DECIMAL_PATTERN.test(candidate)) return void 0;
+    const number = Number(candidate);
+    return Number.isFinite(number) ? number : void 0;
+  };
+  var validateValue = (field, value, rules, values, contextOverrides = {}) => {
     const errors = [];
-    const context = { field, value, values };
+    const context = {
+      field,
+      value,
+      values,
+      ...contextOverrides
+    };
     const required = resolveRule(rules.required);
     const minLength = resolveRule(rules.minLength);
     const maxLength = resolveRule(rules.maxLength);
     const pattern = resolveRule(rules.pattern);
-    const sameAs = resolveRule(rules.sameAs);
+    const numeric = resolveRule(rules.numeric);
+    const min = resolveRule(rules.min);
+    const max = resolveRule(rules.max);
     if (required.value && !hasValue(value)) {
       errors.push(required.message ?? "This field is required.");
     }
@@ -5656,10 +5703,17 @@ var Forms = (() => {
         errors.push(pattern.message ?? "Value does not match the required pattern.");
       }
     }
-    if (sameAs.value !== void 0) {
-      const otherValue = values[sameAs.value];
-      if (hasValue(value) && hasValue(otherValue) && !valuesAreEqual(value, otherValue)) {
-        errors.push(sameAs.message ?? `Value must match ${sameAs.value}.`);
+    if (hasValue(value) && (numeric.value || min.value !== void 0 || max.value !== void 0)) {
+      const number = parseStrictNumber(value);
+      if (number === void 0) {
+        errors.push(numeric.message ?? "Value must be a number.");
+      } else {
+        if (min.value !== void 0 && number < min.value) {
+          errors.push(min.message ?? `Minimum value is ${min.value}.`);
+        }
+        if (max.value !== void 0 && number > max.value) {
+          errors.push(max.message ?? `Maximum value is ${max.value}.`);
+        }
       }
     }
     const custom = rules.validate ? Array.isArray(rules.validate) ? rules.validate : [rules.validate] : [];
@@ -5670,6 +5724,37 @@ var Forms = (() => {
     }
     return errors;
   };
+  var validateFieldValueDetailed = (field, value, rules, values, items) => {
+    const groupErrors = validateValue(field, value, rules, values);
+    const sameAs = resolveRule(rules.sameAs);
+    if (sameAs.value !== void 0) {
+      const otherValue = values[sameAs.value];
+      if (hasValue(value) && hasValue(otherValue) && !valuesAreEqual(value, otherValue)) {
+        groupErrors.push(sameAs.message ?? `Value must match ${sameAs.value}.`);
+      }
+    }
+    const itemErrors = [];
+    if (rules.each) {
+      const sourceItems = items ?? (Array.isArray(value) ? value.map((entry) => ({
+        value: typeof entry === "string" ? entry : [entry]
+      })) : [{ value }]);
+      sourceItems.forEach((item, index) => {
+        const overrides = {
+          index
+        };
+        if (item.element) overrides.element = item.element;
+        const messages = validateValue(field, item.value, rules.each, values, overrides);
+        if (messages.length === 0) return;
+        const error = {
+          index,
+          messages
+        };
+        if (item.element) error.element = item.element;
+        itemErrors.push(error);
+      });
+    }
+    return { groupErrors, itemErrors };
+  };
 
   // src/core/controller.ts
   var DEFAULT_ATTRIBUTES = {
@@ -5700,25 +5785,35 @@ var Forms = (() => {
       fieldCache: /* @__PURE__ */ new Map(),
       manualErrors: {},
       validationErrors: {},
+      validationGroupErrors: {},
+      validationElementErrors: /* @__PURE__ */ new Map(),
       isValidated: Boolean(normalizedOptions.autoValidate),
       autoSubmitEnabled: false,
       autoSubmitDebounce: 0,
       submitCount: 0,
+      pendingSubmitCount: 0,
       autoSubmitTimer: null,
       isDestroyed: false,
       listeners: [],
       mutationObserver: null,
+      cleanups: /* @__PURE__ */ new Set(),
       formattedFields: /* @__PURE__ */ new Map(),
       api: null
     };
     const validationDependents = /* @__PURE__ */ new Map();
     for (const [field, rules] of Object.entries(state2.validators)) {
+      const sources = /* @__PURE__ */ new Set();
       const sameAs = rules.sameAs;
-      if (sameAs === void 0) continue;
-      const source = typeof sameAs === "string" ? sameAs : sameAs.value;
-      const dependents = validationDependents.get(source) ?? /* @__PURE__ */ new Set();
-      dependents.add(field);
-      validationDependents.set(source, dependents);
+      if (sameAs !== void 0) {
+        sources.add(typeof sameAs === "string" ? sameAs : sameAs.value);
+      }
+      if (typeof rules.dependsOn === "string") sources.add(rules.dependsOn);
+      else rules.dependsOn?.forEach((source) => sources.add(source));
+      for (const source of sources) {
+        const dependents = validationDependents.get(source) ?? /* @__PURE__ */ new Set();
+        dependents.add(field);
+        validationDependents.set(source, dependents);
+      }
     }
     const notifySubscribers = () => {
       if (!state2.api) return;
@@ -5767,18 +5862,21 @@ var Forms = (() => {
     const syncVisualState = (names) => {
       if (!state2.element) return;
       const sourceNames = names ?? getTrackedFieldNames();
-      const errors = getMergedErrors();
       for (const name of sourceNames) {
         const displayName = resolveDisplayNameForName(state2, name);
         const canonical = resolveCanonicalForName(state2, name) ?? name;
         const fields = getFieldsByName(displayName);
-        const hasError = Boolean(errors[canonical]?.length);
-        for (const field of fields) {
+        const hasGroupError = Boolean(
+          state2.validationGroupErrors[canonical]?.length || state2.manualErrors[canonical]?.length
+        );
+        const elementErrors = state2.validationElementErrors.get(canonical);
+        fields.forEach((field) => {
+          const hasError = hasGroupError || Boolean(elementErrors?.get(field)?.length);
           applyBooleanAttribute(field, attributes.filled, isFieldFilled(field));
           applyBooleanAttribute(field, attributes.error, hasError);
           if (hasError) field.setAttribute("aria-invalid", "true");
           else field.removeAttribute("aria-invalid");
-        }
+        });
       }
     };
     void readFieldValue;
@@ -5787,17 +5885,38 @@ var Forms = (() => {
       const targetNames = names ?? Object.keys(state2.validators);
       const values = getValues();
       const nextValidationErrors = names ? cloneErrors(state2.validationErrors) : {};
+      const nextGroupErrors = names ? cloneErrors(state2.validationGroupErrors) : {};
+      const nextElementErrors = names ? new Map(state2.validationElementErrors) : /* @__PURE__ */ new Map();
       for (const name of targetNames) {
         const rules = state2.validators[name];
         if (!rules) {
           delete nextValidationErrors[name];
+          delete nextGroupErrors[name];
+          nextElementErrors.delete(name);
           continue;
         }
-        const messages = validateFieldValue(name, values[name], rules, values);
+        const fields = getFieldsByName(name);
+        const displayFields = getFieldsByName(resolveDisplayNameForName(state2, name));
+        const items = fields.map((field, index) => ({
+          value: readFieldValue([field]),
+          element: displayFields[index] ?? field
+        }));
+        const result = validateFieldValueDetailed(name, values[name], rules, values, items);
+        const messages = [...result.groupErrors, ...result.itemErrors.flatMap((item) => item.messages)];
         if (messages.length > 0) nextValidationErrors[name] = messages;
         else delete nextValidationErrors[name];
+        if (result.groupErrors.length > 0) nextGroupErrors[name] = result.groupErrors;
+        else delete nextGroupErrors[name];
+        const perElement = /* @__PURE__ */ new Map();
+        result.itemErrors.forEach((item) => {
+          if (item.element) perElement.set(item.element, item.messages);
+        });
+        if (perElement.size > 0) nextElementErrors.set(name, perElement);
+        else nextElementErrors.delete(name);
       }
       state2.validationErrors = nextValidationErrors;
+      state2.validationGroupErrors = nextGroupErrors;
+      state2.validationElementErrors = nextElementErrors;
       syncVisualState(names);
       return {
         isValid: Object.keys(getMergedErrors()).length === 0,
@@ -5891,7 +6010,13 @@ var Forms = (() => {
       if (!validation.isValid) {
         for (const name of Object.keys(validation.errors)) {
           const displayName = resolveDisplayNameForName(state2, name);
-          const field = getFieldsByName(displayName).find((candidate2) => {
+          const fields = getFieldsByName(displayName);
+          const elementErrors = state2.validationElementErrors.get(name);
+          const field = fields.find((candidate2) => {
+            if (!candidate2.isConnected || candidate2.disabled || candidate2.hidden) return false;
+            if (candidate2 instanceof HTMLInputElement && candidate2.type === "hidden") return false;
+            return elementErrors?.has(candidate2);
+          }) ?? fields.find((candidate2) => {
             if (!candidate2.isConnected || candidate2.disabled || candidate2.hidden) return false;
             return !(candidate2 instanceof HTMLInputElement && candidate2.type === "hidden");
           });
@@ -5906,18 +6031,35 @@ var Forms = (() => {
       const submitter = candidate.submitter instanceof HTMLElement ? candidate.submitter : null;
       const { data, formData } = parseFormData(state2.element, submitter);
       const snapshot = state2.api.getState();
-      handlers.forEach(
-        (handler) => handler.callback(state2.element, data, formData, snapshot)
-      );
+      const pending = [];
+      let synchronousError;
+      let hasSynchronousError = false;
+      try {
+        for (const handler of handlers) {
+          const result = handler.callback(state2.element, data, formData, snapshot);
+          if (result && typeof result.then === "function") pending.push(Promise.resolve(result));
+        }
+      } catch (error) {
+        synchronousError = error;
+        hasSynchronousError = true;
+      }
+      if (pending.length > 0) {
+        state2.pendingSubmitCount += 1;
+        notifySubscribers();
+        void Promise.allSettled(pending).then(() => {
+          state2.pendingSubmitCount = Math.max(0, state2.pendingSubmitCount - 1);
+          if (!state2.isDestroyed) notifySubscribers();
+        });
+      }
+      if (hasSynchronousError) throw synchronousError;
     };
     const startMutationObserver = () => {
       if (!state2.element || typeof MutationObserver === "undefined") return;
       state2.mutationObserver = new MutationObserver(() => {
         clearFieldCache();
         if (state2.isValidated) {
-          syncVisualState();
           validateNames();
-        }
+        } else syncVisualState();
         notifySubscribers();
       });
       state2.mutationObserver.observe(state2.element, {
@@ -5938,6 +6080,7 @@ var Forms = (() => {
         return state2.options;
       },
       onSubmit: createOnSubmit(state2, helpers),
+      addCleanup: createAddCleanup(state2, helpers),
       watch: createWatch(state2, helpers),
       observe: createObserve(state2, helpers),
       unwatch: createUnwatch(state2, helpers),
@@ -5975,10 +6118,8 @@ var Forms = (() => {
         api.format(config);
       }
     }
-    if (state2.isValidated) {
-      syncVisualState();
-      validateNames();
-    }
+    if (state2.isValidated) validateNames();
+    else syncVisualState();
     return api;
   };