@samline/forms 2.2.3 → 2.3.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.2.3/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/forms@2.3.0/dist/browser/global.global.js"></script>
 ```
 
-> Pin the version in production. Replace `2.2.3` with the version you ship.
+> Pin the version in production. Replace `2.3.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.2.3/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/forms@2.3.0/dist/browser/global.global.js"></script>
 <script>
   const contactForm = window.Forms.newForm({ id: 'contact-form' })
 

package/dist/browser/global.d.ts

@@ -2,14 +2,25 @@ type FormatType = 'general' | 'phone' | 'numeral' | 'date' | 'time' | 'creditCar
 interface FieldFormatConfig {
     /** One of the supported `@samline/formatter` `FormatType` values. */
     type: FormatType;
-    /** Name of the visible input(s) inside the bound form. */
+    /**
+     * Canonical name of the formatted field. The value the backend
+     * ultimately receives (the `raw` output of the formatter) is
+     * exposed under this name; the formatter is responsible for
+     * keeping it in sync with the visible input.
+     */
     field: string | string[];
     /**
-     * Optional name for the hidden raw mirror. Defaults to
-     * `${fieldName}Raw`. The mirror is created on first `format()`
-     * call and reused on subsequent calls.
+     * Name of the visible input that shows the formatted value to
+     * the user. Defaults to `${fieldName}_displayed`.
+     *
+     * The visible is **renamed** from `field` to `displayField` on
+     * the first `format()` call (idempotent on re-binding). A hidden
+     * `<input type="hidden" name="<field>">` is created next to it
+     * to carry the raw value. Both names are first-class in the
+     * controller's API (`getValue`, `getField`, `setValue`, `watch`,
+     * `getData`) — see `docs/api/format.md` for the full contract.
      */
-    rawField?: string;
+    displayField?: string;
     /**
      * Format-specific options forwarded to `@samline/formatter`.
      * Any key documented for the chosen `type` is accepted (e.g.

package/dist/browser/global.global.js

@@ -4665,33 +4665,45 @@ var Forms = (() => {
     }
     return value.replace(/([!"#$%&'()*+,./:;<=>?@\[\\\]^`{|}~])/g, "\\$1");
   };
-  var findRawMirror = (form2, fieldName) => {
+  var findVisibleField = (form2, displayName) => {
+    const node = form2.querySelector(
+      `[name="${cssEscape(displayName)}"]:not([type="hidden"])`
+    );
+    if (node instanceof HTMLInputElement || node instanceof HTMLTextAreaElement) {
+      return node;
+    }
+    return null;
+  };
+  var findHiddenMirror = (form2, fieldName) => {
     const byAttr = form2.querySelector(
       `[${FORMATTER_RAW_ATTRIBUTE}="${cssEscape(fieldName)}"]`
     );
     if (byAttr) return byAttr;
     const byName = form2.querySelector(
-      `[name="${cssEscape(`${fieldName}_raw`)}"]`
+      `input[type="hidden"][name="${cssEscape(fieldName)}"]`
     );
     if (byName) return byName;
-    const byNameOld = form2.querySelector(
-      `[name="${cssEscape(`${fieldName}Raw`)}"]`
-    );
-    if (byNameOld) return byNameOld;
     return null;
   };
-  var ensureRawMirror = (form2, fieldName) => {
-    const existing = findRawMirror(form2, fieldName);
+  var ensureHiddenMirror = (form2, fieldName) => {
+    const existing = findHiddenMirror(form2, fieldName);
     if (existing) return existing;
     const input = document.createElement("input");
     input.type = "hidden";
-    input.name = `${fieldName}_raw`;
+    input.name = fieldName;
     input.setAttribute("aria-hidden", "true");
     input.tabIndex = -1;
     input.setAttribute(FORMATTER_RAW_ATTRIBUTE, fieldName);
     form2.appendChild(input);
     return input;
   };
+  var renameVisibleField = (visible, displayName) => {
+    if (visible.name === displayName) return;
+    visible.name = displayName;
+  };
+  var restoreVisibleName = (visible, originalName) => {
+    visible.name = originalName;
+  };
   var applyFormattedValue = (visible, mirror, formatted, raw, inputType) => {
     const rawInput = visible.value;
     const caret = clamp(
@@ -4809,6 +4821,7 @@ var Forms = (() => {
   };
 
   // src/api/format.ts
+  var UNBOUND = null;
   var registry = /* @__PURE__ */ new WeakMap();
   var getRegistry = (state2) => {
     let bucket = registry.get(state2);
@@ -4819,99 +4832,128 @@ var Forms = (() => {
     return bucket;
   };
   var resolveFieldNames = (config) => Array.isArray(config.field) ? config.field : [config.field];
-  var addListener = (state2, target, type, handler) => {
-    target.addEventListener(type, handler);
-    state2.listeners.push({ element: target, type, handler });
+  var addListener = (state2, target, type, handler, useCapture) => {
+    if (useCapture) {
+      target.addEventListener(type, handler, { capture: true });
+    } else {
+      target.addEventListener(type, handler);
+    }
+    const entry = { element: target, type, handler };
+    if (useCapture !== void 0) entry.capture = useCapture;
+    state2.listeners.push(entry);
   };
-  var buildHandler = (field, mirror, formatFn, formatType, formatOptions, mirrorFieldName) => {
+  var readInputType = (event) => {
+    const candidate = event;
+    return typeof candidate.inputType === "string" ? candidate.inputType : void 0;
+  };
+  var buildHandler = (visible, mirror, formatFn, formatType, formatOptions) => {
     const handler = (event) => {
-      if (!field.isConnected) return;
-      if (event.target !== field) return;
-      const rawInput = event.target.value;
+      if (!visible.isConnected || !mirror.isConnected) return;
+      const isVisible = event.target === visible;
+      const isMirror = event.target === mirror;
+      if (!isVisible && !isMirror) return;
+      const rawInput = isMirror ? mirror.value : visible.value;
       const inputType = readInputType(event);
       const { formatted, raw } = formatFn(rawInput, formatType, formatOptions);
       if (!formatted && !raw) {
-        field.value = "";
-        if (mirror && mirror.value !== "") mirror.value = "";
+        visible.value = "";
+        if (mirror.value !== "") mirror.value = "";
         return;
       }
-      applyFormattedValue(field, mirror, formatted, raw, inputType);
-      void mirrorFieldName;
+      applyFormattedValue(visible, mirror, formatted, raw, inputType);
     };
     return handler;
   };
-  var readInputType = (event) => {
-    const candidate = event;
-    return typeof candidate.inputType === "string" ? candidate.inputType : void 0;
-  };
   var applyFormat = async (state2, helpers, config) => {
     if (!state2.element || !state2.api) return;
-    const formatter = await loadFormatter();
-    if (!formatter) return;
     const formatType = config.type;
     const formatOptions = config.options;
     const fieldNames = resolveFieldNames(config);
     const bucket = getRegistry(state2);
     for (const fieldName of fieldNames) {
-      const fields = helpers.getFieldsByName(fieldName);
-      if (fields.length === 0) continue;
-      const writable = fields.filter(
-        (f2) => f2 instanceof HTMLInputElement && f2.type !== "checkbox" && f2.type !== "radio" && f2.type !== "file" && f2.type !== "submit" && f2.type !== "button" || f2 instanceof HTMLTextAreaElement
+      const displayName = config.displayField ?? `${fieldName}_displayed`;
+      const canonicalFields = helpers.getFieldsByName(fieldName);
+      const candidates = canonicalFields.filter(
+        (f2) => f2 instanceof HTMLInputElement && f2.type !== "hidden" || f2 instanceof HTMLTextAreaElement
       );
-      if (writable.length === 0) continue;
-      for (const field of writable) {
-        const existing = bucket.get(fieldName);
-        const mirrorName = config.rawField ?? `${fieldName}_raw`;
-        let mirror = findRawMirror(state2.element, fieldName) ?? null;
-        const mirrorIsOwned = !mirror;
-        if (!mirror) mirror = ensureRawMirror(state2.element, fieldName);
-        if (mirror && mirror.name !== mirrorName) mirror.name = mirrorName;
-        const trackerMirrorName = mirror?.name ?? mirrorName;
-        if (existing) {
-          existing.mirrorName = trackerMirrorName;
-          existing.mirrorIsOwned = mirrorIsOwned;
-          state2.formattedFields.set(fieldName, {
-            config,
-            mirrorName: trackerMirrorName,
-            mirrorIsOwned
-          });
-          const current = field.value;
-          if (current !== "") {
-            const { formatted, raw } = formatter.format(current, formatType, formatOptions);
-            applyFormattedValue(field, mirror, formatted, raw);
-          }
-          continue;
-        }
-        const handler = buildHandler(
-          field,
-          mirror,
-          formatter.format,
-          formatType,
-          formatOptions,
-          trackerMirrorName
-        );
-        addListener(state2, state2.element, "input", handler);
-        bucket.set(fieldName, {
-          fields: /* @__PURE__ */ new Set([field]),
-          mirrorName: trackerMirrorName,
-          handler,
+      let visible = candidates[0] ?? null;
+      if (!visible) {
+        visible = findVisibleField(state2.element, displayName);
+      }
+      if (!visible) continue;
+      const existing = bucket.get(fieldName);
+      let mirror = findHiddenMirror(state2.element, fieldName);
+      const mirrorIsOwned = !mirror;
+      if (!mirror) mirror = ensureHiddenMirror(state2.element, fieldName);
+      renameVisibleField(visible, displayName);
+      if (existing) {
+        existing.displayName = displayName;
+        existing.mirrorIsOwned = mirrorIsOwned;
+        state2.formattedFields.set(fieldName, {
+          config,
+          displayName,
           mirrorIsOwned
         });
+      } else {
+        bucket.set(fieldName, {
+          canonicalName: fieldName,
+          displayName,
+          visible,
+          mirror,
+          mirrorIsOwned,
+          handler: UNBOUND
+        });
         state2.formattedFields.set(fieldName, {
           config,
-          mirrorName: trackerMirrorName,
+          displayName,
           mirrorIsOwned
         });
-        const initial = field.value;
-        if (initial !== "") {
-          const { formatted, raw } = formatter.format(initial, formatType, formatOptions);
-          applyFormattedValue(field, mirror, formatted, raw);
-        } else if (mirrorIsOwned && mirror && mirror.value !== "") {
-          mirror.value = "";
+      }
+    }
+    const formatter = await loadFormatter();
+    if (!formatter) {
+      rollbackPhase1(bucket, state2.formattedFields);
+      return;
+    }
+    for (const [, entry] of bucket) {
+      if (entry.handler !== UNBOUND) {
+        const current = entry.visible.value;
+        if (current !== "") {
+          const { formatted, raw } = formatter.format(current, formatType, formatOptions);
+          applyFormattedValue(entry.visible, entry.mirror, formatted, raw);
         }
+        continue;
+      }
+      const handler = buildHandler(
+        entry.visible,
+        entry.mirror,
+        formatter.format,
+        formatType,
+        formatOptions
+      );
+      addListener(state2, state2.element, "input", handler, true);
+      entry.handler = handler;
+      const initial = entry.visible.value;
+      if (initial !== "") {
+        const { formatted, raw } = formatter.format(initial, formatType, formatOptions);
+        applyFormattedValue(entry.visible, entry.mirror, formatted, raw);
+      } else if (entry.mirrorIsOwned && entry.mirror.value !== "") {
+        entry.mirror.value = "";
       }
     }
   };
+  var rollbackPhase1 = (bucket, registry2) => {
+    for (const [fieldName, entry] of bucket) {
+      if (entry.visible.isConnected) {
+        restoreVisibleName(entry.visible, fieldName);
+      }
+      if (entry.mirrorIsOwned && entry.mirror.isConnected) {
+        entry.mirror.remove();
+      }
+      bucket.delete(fieldName);
+      registry2.delete(fieldName);
+    }
+  };
   var createFormat = (state2, helpers) => (config) => {
     if (state2.isDestroyed) return state2.api;
     if (!state2.element) return state2.api;
@@ -4919,6 +4961,14 @@ var Forms = (() => {
     return state2.api;
   };
   var createFormatAll = createFormat;
+  var resolveCanonicalForName = (state2, name) => {
+    const bucket = registry.get(state2);
+    if (!bucket) return null;
+    for (const [canonical, entry] of bucket) {
+      if (canonical === name || entry.displayName === name) return canonical;
+    }
+    return null;
+  };
   var cleanupFormatRegistry = (state2) => {
     if (!state2.element) {
       registry.delete(state2);
@@ -4930,10 +4980,14 @@ var Forms = (() => {
       return;
     }
     for (const [fieldName, entry] of bucket) {
-      state2.element.removeEventListener("input", entry.handler);
-      if (entry.mirrorIsOwned) {
-        const mirror = findRawMirror(state2.element, entry.mirrorName);
-        mirror?.remove();
+      if (entry.handler !== UNBOUND) {
+        state2.element.removeEventListener("input", entry.handler, true);
+      }
+      if (entry.visible.isConnected) {
+        restoreVisibleName(entry.visible, fieldName);
+      }
+      if (entry.mirrorIsOwned && entry.mirror.isConnected) {
+        entry.mirror.remove();
       }
       bucket.delete(fieldName);
       state2.formattedFields.delete(fieldName);
@@ -4946,7 +5000,12 @@ var Forms = (() => {
     if (state2.isDestroyed) return;
     state2.isDestroyed = true;
     for (const listener of state2.listeners) {
-      listener.element.removeEventListener(listener.type, listener.handler);
+      const options = listener.capture ? { capture: true } : void 0;
+      if (options) {
+        listener.element.removeEventListener(listener.type, listener.handler, options);
+      } else {
+        listener.element.removeEventListener(listener.type, listener.handler);
+      }
     }
     state2.listeners.length = 0;
     if (state2.autoSubmitTimer) {
@@ -5383,9 +5442,15 @@ var Forms = (() => {
       const snapshot = state2.api.getState();
       state2.subscribers.forEach((listener) => listener(snapshot));
     };
-    const addListener2 = (node, type, handler) => {
-      node.addEventListener(type, handler);
-      state2.listeners.push({ element: node, type, handler });
+    const addListener2 = (node, type, handler, capture) => {
+      if (capture) {
+        node.addEventListener(type, handler, { capture: true });
+      } else {
+        node.addEventListener(type, handler);
+      }
+      const entry = { element: node, type, handler };
+      if (capture !== void 0) entry.capture = capture;
+      state2.listeners.push(entry);
     };
     const clearFieldCache = () => state2.fieldCache.clear();
     const getFieldsByName = (name) => {
@@ -5401,6 +5466,12 @@ var Forms = (() => {
       for (const field of getNamedFields(state2.element)) {
         names.add(field.name);
       }
+      for (const [canonical, entry] of state2.formattedFields) {
+        names.add(canonical);
+        if (entry.displayName && entry.displayName !== canonical) {
+          names.add(entry.displayName);
+        }
+      }
       return Array.from(names);
     };
     const getValues = () => {
@@ -5486,14 +5557,16 @@ var Forms = (() => {
       const name = target2.name;
       if (!name) return;
       clearFieldCache();
+      const canonical = resolveCanonicalForName(state2, name) ?? name;
       if (normalizedOptions.clearManualErrorsOnChange) {
-        delete state2.manualErrors[name];
+        delete state2.manualErrors[canonical];
       }
-      syncVisualState([name]);
-      if (state2.isValidated && state2.validators[name]) {
-        validateNames([name]);
+      syncVisualState([canonical]);
+      if (state2.isValidated && state2.validators[canonical]) {
+        validateNames([canonical]);
       }
-      emitFieldWatchers(name);
+      emitFieldWatchers(canonical);
+      if (canonical !== name) emitFieldWatchers(name);
       notifySubscribers();
       scheduleAutoSubmit();
     };