@samline/forms 2.8.0 → 2.10.0

package/dist/index.cjs

@@ -241,12 +241,37 @@ var restoreCursor = (field, position) => {
 var state = null;
 var MISSING_MESSAGE = "[samline/forms] The `format()` and `formatAll()` methods require the @samline/formatter package. Install it with: npm i @samline/formatter (or pnpm/bun/yarn equivalent).";
 var warned = false;
+var phonePromise = null;
+var PHONE_MESSAGE = "[samline/forms] Phone formatting needs `@samline/formatter/phone` (@samline/formatter >= 3.0.0 makes phones opt-in) and it could not be loaded.";
 var warnOnce = () => {
   if (warned) return;
   warned = true;
   console.error(MISSING_MESSAGE);
 };
-var loadFormatter = () => {
+var ensurePhone = (formatter) => {
+  if (typeof formatter.isPhoneRegistered !== "function") return Promise.resolve(true);
+  if (formatter.isPhoneRegistered()) return Promise.resolve(true);
+  if (!phonePromise) {
+    phonePromise = (async () => {
+      try {
+        const mod = await import("@samline/formatter/phone");
+        mod.registerPhone();
+        return true;
+      } catch {
+        console.error(PHONE_MESSAGE);
+        phonePromise = null;
+        return false;
+      }
+    })();
+  }
+  return phonePromise;
+};
+var loadFormatter = async (options = {}) => {
+  const formatter = await loadFormatterModule();
+  if (!formatter || !options.phone) return formatter;
+  return await ensurePhone(formatter) ? formatter : null;
+};
+var loadFormatterModule = () => {
   if (state && state.status === "resolved") {
     if (!state.module) warnOnce();
     return Promise.resolve(state.module);
@@ -381,7 +406,7 @@ var applyFormat = async (state2, helpers, config) => {
       phase1Entries.push(entry);
     }
   }
-  const formatter = await loadFormatter();
+  const formatter = await loadFormatter({ phone: formatType === "phone" });
   if (state2.isDestroyed) {
     rollbackPhase1(phase1Entries, bucket, state2.formattedFields);
     return;
@@ -520,6 +545,7 @@ var createDestroy = (state2, _helpers) => () => {
     }
   }
   state2.watchedFields.clear();
+  state2.groupWatchers.clear();
   state2.subscribers.clear();
   state2.submitHandlers.clear();
   state2.fieldCache.clear();
@@ -747,9 +773,9 @@ var writeFieldValue = (fields, value) => {
       continue;
     }
     if (field instanceof HTMLSelectElement && field.multiple) {
-      const selectedValues = normalizedArray ?? [normalizedValue];
+      const selectedValues2 = normalizedArray ?? [normalizedValue];
       for (const option of field.options) {
-        option.selected = selectedValues.includes(option.value);
+        option.selected = selectedValues2.includes(option.value);
       }
       continue;
     }
@@ -784,8 +810,7 @@ var submitForm = (form2) => {
 var createGetValue = (state2, helpers) => (name) => readFieldValue(helpers.getFieldsByName(name));
 
 // src/api/observe.ts
-var createObserve = (state2, helpers) => (field, callback) => {
-  if (state2.isDestroyed) return () => void 0;
+var observeField = (state2, field, callback) => {
   const callbacks = state2.watchedFields.get(field) ?? /* @__PURE__ */ new Set();
   callbacks.add(callback);
   state2.watchedFields.set(field, callbacks);
@@ -800,6 +825,26 @@ var createObserve = (state2, helpers) => (field, callback) => {
     }
   };
 };
+var observeFields = (state2, fields, callback) => {
+  const names = Array.from(new Set(fields));
+  if (names.length === 0) return () => void 0;
+  const entry = { fields: names, callback };
+  state2.groupWatchers.add(entry);
+  if (state2.element) {
+    const values = Object.fromEntries(names.map((name) => [name, state2.api.getValue(name)]));
+    callback(values, null, state2.element, state2.api.getState());
+  }
+  return () => {
+    state2.groupWatchers.delete(entry);
+  };
+};
+var createObserve = (state2, _helpers) => {
+  function observe(field, callback) {
+    if (state2.isDestroyed) return () => void 0;
+    return Array.isArray(field) ? observeFields(state2, field, callback) : observeField(state2, field, callback);
+  }
+  return observe;
+};
 
 // src/api/on-submit.ts
 var createOnSubmit = (state2, _helpers) => (callback, preventDefault = true) => {
@@ -871,6 +916,75 @@ var createSetErrors = (state2, helpers) => (fields) => {
   return state2.api;
 };
 
+// src/api/set-options.ts
+var isGroup = (entry) => typeof entry === "object" && entry !== null && Array.isArray(entry.options);
+var createOption = (entry) => {
+  const option = document.createElement("option");
+  if (typeof entry === "object") {
+    option.value = String(entry.value);
+    option.textContent = entry.label ?? String(entry.value);
+    option.disabled = Boolean(entry.disabled);
+    if (entry.selected) option.defaultSelected = true;
+  } else {
+    option.value = String(entry);
+    option.textContent = String(entry);
+  }
+  return option;
+};
+var buildNodes = (options) => {
+  const nodes = [];
+  let hasExplicitSelection = false;
+  const track = (option) => {
+    if (option.defaultSelected) hasExplicitSelection = true;
+    return option;
+  };
+  for (const entry of options) {
+    if (entry === null || entry === void 0) continue;
+    if (isGroup(entry)) {
+      const group = document.createElement("optgroup");
+      group.label = entry.label;
+      group.disabled = Boolean(entry.disabled);
+      for (const child of entry.options) {
+        if (child === null || child === void 0) continue;
+        group.appendChild(track(createOption(child)));
+      }
+      nodes.push(group);
+      continue;
+    }
+    nodes.push(track(createOption(entry)));
+  }
+  return { nodes, hasExplicitSelection };
+};
+var selectedValues = (select) => Array.from(select.selectedOptions, (option) => option.value);
+var restoreSelection = (select, previous) => {
+  if (previous.length === 0) return;
+  const options = Array.from(select.options);
+  if (select.multiple) {
+    for (const option of options) option.selected = previous.includes(option.value);
+    return;
+  }
+  const match = options.find((option) => option.value === previous[0]);
+  if (match) match.selected = true;
+};
+var sameValues = (left, right) => left.length === right.length && left.every((value, index) => value === right[index]);
+var createSetOptions = (state2, helpers) => (name, options, config = {}) => {
+  if (!state2.element || state2.isDestroyed) return state2.api;
+  const selects = helpers.getFieldsByName(name).filter((field) => field instanceof HTMLSelectElement);
+  if (selects.length === 0) return state2.api;
+  const keepValue = config.keepValue ?? true;
+  const changed = [];
+  for (const select of selects) {
+    const previous = selectedValues(select);
+    const { nodes, hasExplicitSelection } = buildNodes(options);
+    select.replaceChildren(...nodes);
+    if (keepValue && !hasExplicitSelection) restoreSelection(select, previous);
+    if (!sameValues(previous, selectedValues(select))) changed.push(select);
+  }
+  helpers.commitOwnMutations(selects);
+  changed[0]?.dispatchEvent(new Event("input", { bubbles: true }));
+  return state2.api;
+};
+
 // src/api/set-value.ts
 var createSetValue = (state2, helpers) => (name, value) => {
   if (state2.isDestroyed) return state2.api;
@@ -894,28 +1008,46 @@ var createSubscribe = (state2, _helpers) => (listener) => {
 };
 
 // src/api/unwatch.ts
-var createUnwatch = (state2, _helpers) => (field, callback) => {
-  if (!field) {
-    state2.watchedFields.clear();
-    return state2.api;
-  }
-  if (!callback) {
-    state2.watchedFields.delete(field);
+var sameFields = (left, right) => left.length === right.size && left.every((name) => right.has(name));
+var createUnwatch = (state2, _helpers) => {
+  function unwatch(field, callback) {
+    if (field === void 0 || field === "") {
+      state2.watchedFields.clear();
+      state2.groupWatchers.clear();
+      return state2.api;
+    }
+    if (Array.isArray(field)) {
+      const names = new Set(field);
+      for (const entry of Array.from(state2.groupWatchers)) {
+        if (!sameFields(entry.fields, names)) continue;
+        if (callback && entry.callback !== callback) continue;
+        state2.groupWatchers.delete(entry);
+      }
+      return state2.api;
+    }
+    if (!callback) {
+      state2.watchedFields.delete(field);
+      return state2.api;
+    }
+    const callbacks = state2.watchedFields.get(field);
+    callbacks?.delete(callback);
+    if (callbacks && callbacks.size === 0) {
+      state2.watchedFields.delete(field);
+    }
     return state2.api;
   }
-  const callbacks = state2.watchedFields.get(field);
-  callbacks?.delete(callback);
-  if (callbacks && callbacks.size === 0) {
-    state2.watchedFields.delete(field);
-  }
-  return state2.api;
+  return unwatch;
 };
 
 // src/api/watch.ts
-var createWatch = (state2, helpers) => (field, callback) => {
+var createWatch = (state2, helpers) => {
   const observe = createObserve(state2, helpers);
-  observe(field, callback);
-  return state2.api;
+  function watch(field, callback) {
+    if (Array.isArray(field)) observe(field, callback);
+    else observe(field, callback);
+    return state2.api;
+  }
+  return watch;
 };
 
 // src/core/validation.ts
@@ -1083,6 +1215,7 @@ var createFormController = (target, options = {}) => {
     attributes,
     validators: normalizedOptions.validators ?? {},
     watchedFields: /* @__PURE__ */ new Map(),
+    groupWatchers: /* @__PURE__ */ new Set(),
     subscribers: /* @__PURE__ */ new Set(),
     submitHandlers: /* @__PURE__ */ new Set(),
     fieldCache: /* @__PURE__ */ new Map(),
@@ -1253,7 +1386,7 @@ var createFormController = (target, options = {}) => {
     }
     return affected;
   };
-  const emitFieldWatchers = (name) => {
+  const emitSingleWatchers = (name) => {
     if (!state2.element || !state2.api) return;
     const callbacks = state2.watchedFields.get(name);
     if (!callbacks || callbacks.size === 0) return;
@@ -1262,6 +1395,23 @@ var createFormController = (target, options = {}) => {
     const snapshot = state2.api.getState();
     callbacks.forEach((callback) => callback(value, fieldElement, state2.element, snapshot));
   };
+  const emitGroupWatchers = (names) => {
+    if (!state2.element || !state2.api || state2.groupWatchers.size === 0) return;
+    let snapshot;
+    for (const entry of Array.from(state2.groupWatchers)) {
+      const changed = names ? names.find((name) => entry.fields.includes(name)) : null;
+      if (changed === void 0) continue;
+      snapshot ?? (snapshot = state2.api.getState());
+      const values = Object.fromEntries(
+        entry.fields.map((field) => [field, state2.api.getValue(field)])
+      );
+      entry.callback(values, changed, state2.element, snapshot);
+    }
+  };
+  const emitFieldWatchers = (name) => {
+    emitSingleWatchers(name);
+    emitGroupWatchers([name]);
+  };
   const runAutoSubmit = () => {
     state2.autoSubmitTimer = null;
     if (!state2.element || state2.isDestroyed || !state2.autoSubmitEnabled) return;
@@ -1282,8 +1432,20 @@ var createFormController = (target, options = {}) => {
     }
     runAutoSubmit();
   };
+  const selectSnapshots = /* @__PURE__ */ new WeakMap();
+  const readSelectSnapshot = (select) => Array.from(select.selectedOptions, (option) => option.value).join("\0");
+  const snapshotSelect = (select) => {
+    selectSnapshots.set(select, readSelectSnapshot(select));
+  };
+  const snapshotAllSelects = () => {
+    if (!state2.element) return;
+    for (const field of getNamedFields(state2.element)) {
+      if (field instanceof HTMLSelectElement) snapshotSelect(field);
+    }
+  };
   const emitAllFieldWatchers = () => {
-    for (const name of Array.from(state2.watchedFields.keys())) emitFieldWatchers(name);
+    for (const name of Array.from(state2.watchedFields.keys())) emitSingleWatchers(name);
+    emitGroupWatchers(null);
   };
   const applyReset = () => {
     if (!state2.element || state2.isDestroyed) return;
@@ -1295,6 +1457,7 @@ var createFormController = (target, options = {}) => {
     state2.validationElementErrors.clear();
     clearAttributes(state2.element, [attributes.error, attributes.filled, "aria-invalid"]);
     syncVisualState();
+    snapshotAllSelects();
     emitAllFieldWatchers();
     notifySubscribers();
   };
@@ -1309,7 +1472,8 @@ var createFormController = (target, options = {}) => {
     validateNames,
     emitFieldWatchers,
     scheduleAutoSubmit,
-    applyReset
+    applyReset,
+    commitOwnMutations: (selects) => commitOwnMutations(selects)
   };
   const handleDelegatedEvent = (event) => {
     const target2 = event.target;
@@ -1317,6 +1481,7 @@ var createFormController = (target, options = {}) => {
     const name = target2.name;
     if (!name) return;
     clearFieldCache();
+    if (target2 instanceof HTMLSelectElement) snapshotSelect(target2);
     const canonical = resolveCanonicalForName(state2, name) ?? name;
     const displayName = resolveDisplayNameForName(state2, name);
     if (normalizedOptions.clearManualErrorsOnChange) {
@@ -1327,8 +1492,9 @@ var createFormController = (target, options = {}) => {
     if (state2.isValidated && affectedValidationNames.some((field) => state2.validators[field] !== void 0)) {
       validateNames(affectedValidationNames);
     }
-    emitFieldWatchers(canonical);
-    if (canonical !== name) emitFieldWatchers(name);
+    emitSingleWatchers(canonical);
+    if (canonical !== name) emitSingleWatchers(name);
+    emitGroupWatchers(canonical !== name ? [canonical, name] : [canonical]);
     notifySubscribers();
     scheduleAutoSubmit();
   };
@@ -1357,6 +1523,10 @@ var createFormController = (target, options = {}) => {
   };
   const handleSubmitEvent = (event) => {
     if (!state2.element || state2.isDestroyed || !state2.api) return;
+    if (!state2.isAutoSubmitting && state2.autoSubmitTimer) {
+      clearTimeout(state2.autoSubmitTimer);
+      state2.autoSubmitTimer = null;
+    }
     if (normalizedOptions.clearErrorsOnSubmit) state2.manualErrors = {};
     const validation = state2.api.validate();
     const handlers = Array.from(state2.submitHandlers);
@@ -1409,18 +1579,62 @@ var createFormController = (target, options = {}) => {
     const cancel = () => clearTimeout(timer);
     state2.cleanups.add(cancel);
   };
+  const touchesFields = (node) => node instanceof Element && (isFieldElement(node) || node.querySelector("input, select, textarea") !== null);
+  const isStructural = (record) => record.type === "attributes" || Array.from(record.addedNodes).some(touchesFields) || Array.from(record.removedNodes).some(touchesFields);
+  const isOptionNode = (node) => node instanceof HTMLOptionElement || node instanceof HTMLOptGroupElement;
+  const optionListOwner = (record) => {
+    if (record.type !== "childList") return null;
+    const touchesOptions = Array.from(record.addedNodes).some(isOptionNode) || Array.from(record.removedNodes).some(isOptionNode);
+    if (!touchesOptions) return null;
+    const target2 = record.target;
+    if (target2 instanceof HTMLSelectElement) return target2;
+    if (target2 instanceof HTMLOptGroupElement && target2.parentElement instanceof HTMLSelectElement) {
+      return target2.parentElement;
+    }
+    return null;
+  };
+  const handleMutations = (records) => {
+    if (state2.isDestroyed) return;
+    const structural = records.some(isStructural);
+    const changedNames = /* @__PURE__ */ new Set();
+    for (const record of records) {
+      const select = optionListOwner(record);
+      if (!select || !select.name) continue;
+      const next = readSelectSnapshot(select);
+      if (selectSnapshots.get(select) !== next) changedNames.add(select.name);
+      selectSnapshots.set(select, next);
+    }
+    if (!structural && changedNames.size === 0) return;
+    clearFieldCache();
+    if (structural) {
+      snapshotAllSelects();
+      if (state2.isValidated) validateNames();
+      else syncVisualState();
+    } else {
+      const affected = /* @__PURE__ */ new Set();
+      for (const name of changedNames) {
+        for (const field of getAffectedValidationNames(name)) affected.add(field);
+      }
+      const names = Array.from(affected);
+      syncVisualState(Array.from(changedNames));
+      if (state2.isValidated && names.some((field) => state2.validators[field] !== void 0)) {
+        validateNames(names);
+      }
+    }
+    for (const name of changedNames) emitFieldWatchers(name);
+    notifySubscribers();
+  };
+  const commitOwnMutations = (selects) => {
+    selects.forEach(snapshotSelect);
+    const pending = state2.mutationObserver?.takeRecords() ?? [];
+    const foreign = pending.filter(
+      (record) => !selects.some((select) => select.contains(record.target))
+    );
+    if (foreign.length > 0) handleMutations(foreign);
+  };
   const startMutationObserver = () => {
     if (!state2.element || typeof MutationObserver === "undefined") return;
-    const touchesFields = (node) => node instanceof Element && (isFieldElement(node) || node.querySelector("input, select, textarea") !== null);
-    const isRelevant = (record) => record.type === "attributes" || Array.from(record.addedNodes).some(touchesFields) || Array.from(record.removedNodes).some(touchesFields);
-    state2.mutationObserver = new MutationObserver((records) => {
-      if (state2.isDestroyed || !records.some(isRelevant)) return;
-      clearFieldCache();
-      if (state2.isValidated) {
-        validateNames();
-      } else syncVisualState();
-      notifySubscribers();
-    });
+    state2.mutationObserver = new MutationObserver(handleMutations);
     state2.mutationObserver.observe(state2.element, {
       childList: true,
       subtree: true,
@@ -1449,6 +1663,7 @@ var createFormController = (target, options = {}) => {
     setErrors: createSetErrors(state2, helpers),
     clearErrors: createClearErrors(state2, helpers),
     setValue: createSetValue(state2, helpers),
+    setOptions: createSetOptions(state2, helpers),
     getValue: createGetValue(state2, helpers),
     getField: createGetField(state2, helpers),
     validate: createValidate(state2, helpers),
@@ -1468,6 +1683,7 @@ var createFormController = (target, options = {}) => {
     addListener2(document, "input", handleExternalDelegatedEvent);
     addListener2(state2.element, "submit", handleSubmitEvent);
     addListener2(state2.element, "reset", handleResetEvent);
+    snapshotAllSelects();
     startMutationObserver();
   }
   if (normalizedOptions.autoSubmit) {