webspresso 0.0.110 → 0.0.112

package/core/client/forms.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { defaultStorage } = require('./storage');
+const { isArray, setElementBusyState } = require('./utils');
 
 /**
  * Webspresso Native HTML Form Layer & Typed Form Handle
@@ -202,12 +203,12 @@ function parseFormElement(formEl, submitterOrOptions = null) {
   function appendValue(normName, val, forceArray) {
     if (val === undefined) return;
     if (forceArray) {
-      if (!Array.isArray(data[normName])) {
+      if (!isArray(data[normName])) {
         data[normName] = [];
       }
       data[normName].push(val);
     } else if (normName in data) {
-      if (!Array.isArray(data[normName])) {
+      if (!isArray(data[normName])) {
         data[normName] = [data[normName]];
       }
       data[normName].push(val);
@@ -326,7 +327,7 @@ function parseFormElement(formEl, submitterOrOptions = null) {
     formData = new FormData();
     for (const [key, val] of Object.entries(data)) {
       if (val === undefined) continue;
-      if (Array.isArray(val)) {
+      if (isArray(val)) {
         for (const item of val) {
           if (item === undefined) continue;
           if (typeof Blob !== 'undefined' && item instanceof Blob) {
@@ -416,27 +417,44 @@ function computeFormDirty(formEl, initialSnapshot) {
  */
 function createFormHandle(formEl, options = {}) {
   if (formEl && formEl.__wFormHandle) {
+    if (options.services && typeof formEl.__wFormHandle.__setServices === 'function') {
+      formEl.__wFormHandle.__setServices(options.services);
+    }
     return formEl.__wFormHandle;
   }
 
   const api = options.api;
   const debug = options.debug || null;
+  let services = options.services || null;
   const formName =
     (formEl && formEl.getAttribute && formEl.getAttribute('data-w-form')) ||
     (formEl && formEl.getAttribute && formEl.getAttribute('name')) ||
     'form';
 
   let initialSnapshot = captureInitialFormSnapshot(formEl);
+  let baselineValues = parseFormElement(formEl).data;
   let pending = false;
   let dirty = false;
+  let inputRevision = 0;
   let fieldErrors = {};
   let formError = null;
+  let lastError = null;
   let lastData = null;
+  let draftDebounceTimer = null;
+  let resetTimer = null;
 
+  const beforeSubmitListeners = new Set();
   const successListeners = new Set();
   const errorListeners = new Set();
   const stateListeners = new Set();
 
+  function cancelDraftDebounce() {
+    if (draftDebounceTimer) {
+      clearTimeout(draftDebounceTimer);
+      draftDebounceTimer = null;
+    }
+  }
+
   // Form draft persistence setup (sessionStorage by default, or localStorage)
   const rawDraftAttr = formEl
     ? formEl.getAttribute('data-w-persist-draft') || formEl.getAttribute('data-w-draft')
@@ -453,11 +471,18 @@ function createFormHandle(formEl, options = {}) {
     draftStorageType = 'local';
   }
 
-  const draftKey =
+  const draftScope =
+    options.draftScope ||
+    (formEl && formEl.getAttribute && formEl.getAttribute('data-w-draft-scope')) ||
+    '';
+
+  const baseDraftKey =
     options.draftKey ||
     (formEl && (formEl.getAttribute('data-w-draft-key') || formEl.getAttribute('data-w-persist-key'))) ||
     `form_draft:${formName || 'anon'}`;
 
+  let draftKey = draftScope ? `${baseDraftKey}:${draftScope}` : baseDraftKey;
+
   const draftStorage =
     (options.storage && options.storage[draftStorageType]) ||
     (draftStorageType === 'local' ? defaultStorage.local : defaultStorage.session);
@@ -480,7 +505,22 @@ function createFormHandle(formEl, options = {}) {
     return safeData;
   }
 
+  function sanitizeDraftObject(raw) {
+    if (!raw || typeof raw !== 'object' || isArray(raw)) return null;
+    const clean = {};
+    for (const [k, v] of Object.entries(raw)) {
+      if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;
+      if (v === null || v === undefined || typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+        clean[k] = v;
+      } else if (isArray(v) && v.every((item) => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean')) {
+        clean[k] = v;
+      }
+    }
+    return Object.keys(clean).length > 0 ? clean : null;
+  }
+
   function saveDraft() {
+    cancelDraftDebounce();
     if (!formEl || !isDraftEnabled) return false;
     const draftPayload = extractDraftValues(formEl);
     return draftStorage.set(draftKey, draftPayload);
@@ -488,9 +528,15 @@ function createFormHandle(formEl, options = {}) {
 
   function restoreDraft() {
     if (!formEl || !isDraftEnabled) return false;
-    const saved = draftStorage.get(draftKey, null);
-    if (saved && typeof saved === 'object' && Object.keys(saved).length > 0) {
-      fill(saved, { baseline: false });
+    let saved = null;
+    try {
+      saved = draftStorage.get(draftKey, null);
+    } catch (_e) {
+      saved = null;
+    }
+    const cleanDraft = sanitizeDraftObject(saved);
+    if (cleanDraft) {
+      fill(cleanDraft, { baseline: false });
       if (typeof formEl.dispatchEvent === 'function') {
         const CustomEventCtor =
           (formEl.ownerDocument && formEl.ownerDocument.defaultView && formEl.ownerDocument.defaultView.CustomEvent) ||
@@ -500,7 +546,7 @@ function createFormHandle(formEl, options = {}) {
             new CustomEventCtor('w-form:draft-restored', {
               bubbles: true,
               cancelable: true,
-              detail: { form: handle, draft: saved, key: draftKey },
+              detail: { form: handle, draft: cleanDraft, key: draftKey },
             })
           );
         }
@@ -511,6 +557,7 @@ function createFormHandle(formEl, options = {}) {
   }
 
   function clearDraft() {
+    cancelDraftDebounce();
     if (!isDraftEnabled) return false;
     return draftStorage.remove(draftKey);
   }
@@ -520,6 +567,20 @@ function createFormHandle(formEl, options = {}) {
     return draftStorage.has(draftKey);
   }
 
+  function setDraftKey(nextKey, keyOpts = {}) {
+    cancelDraftDebounce();
+    if (typeof nextKey === 'string' && nextKey.trim()) {
+      draftKey = nextKey.trim();
+      if (formEl && typeof formEl.setAttribute === 'function') {
+        formEl.setAttribute('data-w-draft-key', draftKey);
+      }
+      if (keyOpts && keyOpts.restore === true && isDraftEnabled) {
+        restoreDraft();
+      }
+    }
+    return handle;
+  }
+
   function notifyStateChange() {
     for (const fn of stateListeners) {
       try {
@@ -615,32 +676,32 @@ function createFormHandle(formEl, options = {}) {
    * Toggle pending state on the form and submit buttons to prevent double submissions.
    */
   function setPendingState(nextPending, activeSubmitter = null) {
-    pending = Boolean(nextPending);
+    const next = Boolean(nextPending);
+    if (pending === next) return;
+    pending = next;
     if (!formEl) return;
 
     if (pending) {
       formEl.setAttribute('aria-busy', 'true');
       formEl.setAttribute('data-w-pending', 'true');
+      formEl.setAttribute('data-w-busy', 'true');
     } else {
       formEl.removeAttribute('aria-busy');
       formEl.removeAttribute('data-w-pending');
+      formEl.removeAttribute('data-w-busy');
     }
 
     const submitButtons = formEl.querySelectorAll
       ? formEl.querySelectorAll('button[type="submit"], button:not([type]), input[type="submit"]')
       : [];
+    let submitterHandled = false;
     for (let i = 0; i < submitButtons.length; i++) {
       const btn = submitButtons[i];
-      if (btn.hasAttribute('data-w-disabled')) continue; // Managed by controller binding
-      if (pending) {
-        btn.__wWasDisabled = Boolean(btn.disabled);
-        btn.disabled = true;
-      } else if (!btn.__wWasDisabled) {
-        btn.disabled = false;
-      }
+      if (btn === activeSubmitter) submitterHandled = true;
+      setElementBusyState(btn, pending);
     }
-    if (activeSubmitter && !activeSubmitter.hasAttribute('data-w-disabled')) {
-      activeSubmitter.disabled = pending;
+    if (activeSubmitter && !submitterHandled) {
+      setElementBusyState(activeSubmitter, pending);
     }
     notifyStateChange();
   }
@@ -649,6 +710,7 @@ function createFormHandle(formEl, options = {}) {
    * Reset form controls back to their initial default values (NOT emptying non-empty defaults).
    */
   function reset() {
+    cancelDraftDebounce();
     if (!formEl) return;
     if (typeof formEl.reset === 'function') {
       formEl.reset();
@@ -678,6 +740,7 @@ function createFormHandle(formEl, options = {}) {
    * Completely clear all user-editable controls to empty values (distinct from `reset()`).
    */
   function clear() {
+    cancelDraftDebounce();
     if (!formEl || typeof formEl.querySelectorAll !== 'function') return;
     const controls = formEl.querySelectorAll('input, select, textarea');
     for (let i = 0; i < controls.length; i++) {
@@ -714,11 +777,14 @@ function createFormHandle(formEl, options = {}) {
    *                                            snapshot, clears `dirty`, and clears previous validation errors.
    */
   function fill(values = {}, options = {}) {
-    if (!formEl || typeof formEl.querySelectorAll !== 'function' || !values || typeof values !== 'object') {
+    if (!formEl || typeof formEl.querySelectorAll !== 'function' || !values || typeof values !== 'object' || isArray(values)) {
       return handle;
     }
 
     const isBaseline = Boolean(options.baseline);
+    if (isBaseline) {
+      cancelDraftDebounce();
+    }
 
     for (const [key, val] of Object.entries(values)) {
       if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;
@@ -734,7 +800,7 @@ function createFormHandle(formEl, options = {}) {
         if (type === 'file') continue; // Browser security prevents setting file input value
 
         if (type === 'checkbox') {
-          if (Array.isArray(val)) {
+          if (isArray(val)) {
             ctrl.checked = val.map(String).includes(String(ctrl.value));
           } else {
             ctrl.checked = Boolean(val);
@@ -743,7 +809,7 @@ function createFormHandle(formEl, options = {}) {
           ctrl.checked = String(val) === String(ctrl.value);
         } else if (ctrl.tagName === 'SELECT') {
           if (ctrl.multiple) {
-            const arr = Array.isArray(val) ? val.map(String) : [String(val)];
+            const arr = isArray(val) ? val.map(String) : [String(val)];
             const opts = ctrl.options || [];
             for (let j = 0; j < opts.length; j++) {
               opts[j].selected = arr.includes(String(opts[j].value));
@@ -752,6 +818,7 @@ function createFormHandle(formEl, options = {}) {
             ctrl.value = val === null || val === undefined ? '' : String(val);
           }
         } else {
+          if (val !== null && typeof val === 'object') continue;
           ctrl.value = val === null || val === undefined ? '' : String(val);
         }
 
@@ -763,9 +830,11 @@ function createFormHandle(formEl, options = {}) {
 
     if (isBaseline) {
       initialSnapshot = captureInitialFormSnapshot(formEl);
+      baselineValues = parseFormElement(formEl).data;
       dirty = false;
       fieldErrors = {};
       formError = null;
+      lastError = null;
       syncErrorsToDom(false);
     } else {
       dirty = computeFormDirty(formEl, initialSnapshot);
@@ -778,7 +847,9 @@ function createFormHandle(formEl, options = {}) {
 
   function setAction(url) {
     if (formEl && url) {
-      formEl.setAttribute('action', String(url));
+      const nextAction = String(url);
+      formEl.setAttribute('action', nextAction);
+      formEl.__wCustomAction = nextAction;
     }
     return handle;
   }
@@ -791,6 +862,7 @@ function createFormHandle(formEl, options = {}) {
       action = action.replace(new RegExp(`:${k}\\b`, 'g'), encodeURIComponent(String(v)));
     }
     formEl.setAttribute('action', action);
+    formEl.__wCustomAction = action;
     return handle;
   }
 
@@ -865,9 +937,23 @@ function createFormHandle(formEl, options = {}) {
 
     const { data: payloadData, formData, isMultipart } = parseFormElement(formEl, submitter);
 
+    // Execute beforeSubmit hooks before initiating network request
+    for (const guardFn of beforeSubmitListeners) {
+      let allowed = true;
+      try {
+        allowed = await guardFn(payloadData, { form: handle, submitter, action: actionUrl, method });
+      } catch (guardErr) {
+        return { ok: false, submitted: false, canceled: true, reason: 'before-submit-error', error: guardErr };
+      }
+      if (allowed === false) {
+        return { ok: false, submitted: false, canceled: true, reason: 'before-submit' };
+      }
+    }
+
     // Clear previous errors before request starts
     fieldErrors = {};
     formError = null;
+    lastError = null;
     syncErrorsToDom(false);
     setPendingState(true, submitter);
 
@@ -916,6 +1002,7 @@ function createFormHandle(formEl, options = {}) {
       } else {
         // Current state becomes the new clean baseline after successful save
         initialSnapshot = captureInitialFormSnapshot(formEl);
+        baselineValues = parseFormElement(formEl).data;
       }
 
       if (isDraftEnabled) {
@@ -923,9 +1010,18 @@ function createFormHandle(formEl, options = {}) {
       }
 
       // Invoke registered success hooks. Note: Any background fragment refresh failure
-      // is handled by the fragment coordinator and NEVER puts this form into validation error state!
+      // or side-effect service error in onSuccess NEVER puts a succeeded form into validation error
+      // state or makes the completed mutation appear rolled back!
+      let hookError = null;
       for (const listener of successListeners) {
-        await listener(responseData, { values: payloadData, form: handle });
+        try {
+          await listener(responseData, { values: payloadData, form: handle, services });
+        } catch (listenerErr) {
+          if (!hookError) hookError = listenerErr;
+          if (debug && typeof debug.trackCleanupError === 'function') {
+            debug.trackCleanupError(`form_${formName}`, formName, 'form:onSuccess', listenerErr);
+          }
+        }
       }
 
       // Explicit redirect behavior
@@ -951,8 +1047,9 @@ function createFormHandle(formEl, options = {}) {
         }
       }
 
-      return { ok: true, submitted: true, data: responseData, refreshOk, refreshError };
+      return { ok: true, submitted: true, data: responseData, refreshOk, refreshError, hookError };
     } catch (err) {
+      lastError = err || null;
       if (err && err.kind === 'validation') {
         fieldErrors = { ...(err.fieldErrors || {}) };
         formError = err.formError || (Object.keys(fieldErrors).length === 0 ? err.message : null);
@@ -966,7 +1063,7 @@ function createFormHandle(formEl, options = {}) {
 
       for (const listener of errorListeners) {
         try {
-          await listener(err, { values: payloadData, form: handle });
+          await listener(err, { values: payloadData, form: handle, services });
         } catch (_e) {
           // Ignore
         }
@@ -982,8 +1079,8 @@ function createFormHandle(formEl, options = {}) {
   }
 
   // Listen to native submit and input/change events on `formEl`
-  let draftDebounceTimer = null;
   const onDomInput = (evt) => {
+    inputRevision += 1;
     dirty = computeFormDirty(formEl, initialSnapshot);
     const target = evt && evt.target;
     if (target && target.getAttribute) {
@@ -998,8 +1095,9 @@ function createFormHandle(formEl, options = {}) {
       }
     }
     if (isDraftEnabled) {
-      if (draftDebounceTimer) clearTimeout(draftDebounceTimer);
+      cancelDraftDebounce();
       draftDebounceTimer = setTimeout(() => {
+        draftDebounceTimer = null;
         saveDraft();
       }, 150);
     }
@@ -1011,7 +1109,10 @@ function createFormHandle(formEl, options = {}) {
   };
 
   const onDomReset = () => {
-    setTimeout(() => {
+    cancelDraftDebounce();
+    if (resetTimer) clearTimeout(resetTimer);
+    resetTimer = setTimeout(() => {
+      resetTimer = null;
       dirty = false;
       fieldErrors = {};
       formError = null;
@@ -1035,6 +1136,12 @@ function createFormHandle(formEl, options = {}) {
   handle = {
     name: formName,
     el: formEl,
+    get services() {
+      return services;
+    },
+    __setServices(nextServices) {
+      if (nextServices) services = nextServices;
+    },
     get pending() {
       return pending;
     },
@@ -1042,9 +1149,18 @@ function createFormHandle(formEl, options = {}) {
       dirty = computeFormDirty(formEl, initialSnapshot);
       return dirty;
     },
+    get inputRevision() {
+      return inputRevision;
+    },
+    get draftKey() {
+      return draftKey;
+    },
     get values() {
       return parseFormElement(formEl).data;
     },
+    get baseline() {
+      return { ...(baselineValues || {}) };
+    },
     get errors() {
       return { ...fieldErrors };
     },
@@ -1054,6 +1170,9 @@ function createFormHandle(formEl, options = {}) {
     get formError() {
       return formError;
     },
+    get lastError() {
+      return lastError;
+    },
     get lastData() {
       return lastData;
     },
@@ -1073,6 +1192,7 @@ function createFormHandle(formEl, options = {}) {
     saveDraft,
     restoreDraft,
     clearDraft,
+    setDraftKey,
     get hasDraft() {
       return hasDraft();
     },
@@ -1092,12 +1212,20 @@ function createFormHandle(formEl, options = {}) {
     clearErrors() {
       fieldErrors = {};
       formError = null;
+      lastError = null;
       syncErrorsToDom(false);
       notifyStateChange();
     },
     reset,
     clear,
     submit,
+    beforeSubmit(fn) {
+      if (typeof fn === 'function') {
+        beforeSubmitListeners.add(fn);
+        return () => beforeSubmitListeners.delete(fn);
+      }
+      return () => {};
+    },
     onSuccess(fn) {
       if (typeof fn === 'function') {
         successListeners.add(fn);
@@ -1120,6 +1248,11 @@ function createFormHandle(formEl, options = {}) {
       return () => {};
     },
     destroy() {
+      cancelDraftDebounce();
+      if (resetTimer) {
+        clearTimeout(resetTimer);
+        resetTimer = null;
+      }
       if (formEl && typeof formEl.removeEventListener === 'function') {
         formEl.removeEventListener('input', onDomInput);
         formEl.removeEventListener('change', onDomInput);
@@ -1129,6 +1262,7 @@ function createFormHandle(formEl, options = {}) {
       if (formEl) {
         delete formEl.__wFormHandle;
       }
+      beforeSubmitListeners.clear();
       successListeners.clear();
       errorListeners.clear();
       stateListeners.clear();