webspresso 0.0.111 → 0.0.113

package/core/client/forms.js

@@ -23,33 +23,48 @@ const { isArray, setElementBusyState } = require('./utils');
  * @param {string} target
  * @returns {boolean}
  */
-function isSafeRedirectUrl(target) {
-  if (!target || typeof target !== 'string') return false;
+function resolveSafeRedirectUrl(target) {
+  if (!target || typeof target !== 'string') return null;
   const trimmed = target.trim();
-  if (!trimmed) return false;
+  if (!trimmed) return null;
 
   // Block control characters
-  if (/[\u0000-\u001F\u007F-\u009F]/.test(trimmed)) return false;
+  if (/[\u0000-\u001F\u007F-\u009F]/.test(trimmed)) return null;
 
   // Block protocol-relative URLs (//example.com) and backslash traversal (/\ or \\)
   if (trimmed.startsWith('//') || trimmed.startsWith('/\\') || trimmed.startsWith('\\')) {
-    return false;
+    return null;
   }
 
   // Relative path starting with single slash (e.g. /dashboard)
   if (trimmed.startsWith('/')) {
-    return true;
+    try {
+      const parsed = new URL(trimmed, 'http://localhost');
+      if (parsed.origin !== 'http://localhost' || !parsed.pathname.startsWith('/') || parsed.pathname.startsWith('//')) {
+        return null;
+      }
+      return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+    } catch {
+      return null;
+    }
   }
 
   // Absolute URL: MUST explicitly parse as http: or https:
   try {
     const parsed = new URL(trimmed);
-    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      return null;
+    }
+    return parsed.href;
   } catch {
-    return false;
+    return null;
   }
 }
 
+function isSafeRedirectUrl(target) {
+  return resolveSafeRedirectUrl(target) !== null;
+}
+
 let errorIdSeq = 0;
 
 /**
@@ -432,16 +447,107 @@ function createFormHandle(formEl, options = {}) {
     'form';
 
   let initialSnapshot = captureInitialFormSnapshot(formEl);
+  let baselineValues = parseFormElement(formEl).data;
   let pending = false;
   let dirty = false;
+  let submitted = false;
+  let inputRevision = 0;
   let fieldErrors = {};
   let formError = null;
+  let lastError = null;
   let lastData = null;
+  let draftDebounceTimer = null;
+  let resetTimer = null;
+
+  const touchedFields = new Set();
+  const errorDisplayMode =
+    options.errorDisplay === 'touched' ||
+    (formEl && formEl.getAttribute && formEl.getAttribute('data-w-error-mode') === 'touched')
+      ? 'touched'
+      : 'always';
+
+  const validationSeqByField = new Map();
+  const validationTimersByField = new Map();
+  const validationAbortByField = new Map();
+
+  let activeSubmitAbort = null;
+  let uploadEntries = [];
+  const previewUrlsByField = new Map();
+
+  function cancelFieldValidation(fieldName) {
+    if (fieldName) {
+      const t = validationTimersByField.get(fieldName);
+      if (t) {
+        clearTimeout(t);
+        validationTimersByField.delete(fieldName);
+      }
+      const ac = validationAbortByField.get(fieldName);
+      if (ac) {
+        try {
+          ac.abort();
+        } catch (_e) {}
+        validationAbortByField.delete(fieldName);
+      }
+      return;
+    }
+    for (const t of validationTimersByField.values()) clearTimeout(t);
+    validationTimersByField.clear();
+    for (const ac of validationAbortByField.values()) {
+      try {
+        ac.abort();
+      } catch (_e) {}
+    }
+    validationAbortByField.clear();
+  }
 
+  function revokePreviewUrls(fieldName) {
+    const revokeUrl = (u) => {
+      if (typeof URL !== 'undefined' && typeof URL.revokeObjectURL === 'function') {
+        try {
+          URL.revokeObjectURL(u);
+        } catch (_e) {}
+      }
+    };
+    if (fieldName) {
+      const set = previewUrlsByField.get(fieldName);
+      if (set) {
+        for (const u of set) revokeUrl(u);
+        set.clear();
+        previewUrlsByField.delete(fieldName);
+      }
+      return;
+    }
+    for (const set of previewUrlsByField.values()) {
+      for (const u of set) revokeUrl(u);
+      set.clear();
+    }
+    previewUrlsByField.clear();
+  }
+
+  function createPreviewUrl(file, fieldName = '_default') {
+    if (!file || typeof URL === 'undefined' || typeof URL.createObjectURL !== 'function') return null;
+    const url = URL.createObjectURL(file);
+    let set = previewUrlsByField.get(fieldName);
+    if (!set) {
+      set = new Set();
+      previewUrlsByField.set(fieldName, set);
+    }
+    set.add(url);
+    return url;
+  }
+
+  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')
@@ -458,11 +564,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);
@@ -485,7 +598,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);
@@ -493,9 +621,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) ||
@@ -505,7 +639,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 },
             })
           );
         }
@@ -516,6 +650,7 @@ function createFormHandle(formEl, options = {}) {
   }
 
   function clearDraft() {
+    cancelDraftDebounce();
     if (!isDraftEnabled) return false;
     return draftStorage.remove(draftKey);
   }
@@ -525,6 +660,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 {
@@ -535,6 +684,12 @@ function createFormHandle(formEl, options = {}) {
     }
   }
 
+  function isFieldErrorVisible(fieldName) {
+    if (errorDisplayMode !== 'touched') return true;
+    if (submitted) return true;
+    return touchedFields.has(fieldName);
+  }
+
   /**
    * Render field errors and form-level error into the DOM with accessible ARIA bindings.
    * Optionally focuses the first invalid control.
@@ -547,7 +702,11 @@ function createFormHandle(formEl, options = {}) {
     for (let i = 0; i < errorSpans.length; i++) {
       const span = errorSpans[i];
       const fieldName = span.getAttribute('data-w-error');
-      const msg = fieldName && fieldErrors[fieldName] ? String(fieldErrors[fieldName]) : '';
+      const normName = fieldName && fieldName.endsWith('[]') ? fieldName.slice(0, -2) : fieldName;
+      const rawMsg = fieldName && (fieldErrors[fieldName] || (normName && fieldErrors[normName]))
+        ? String(fieldErrors[fieldName] || fieldErrors[normName])
+        : '';
+      const msg = rawMsg && (isFieldErrorVisible(fieldName) || (normName && isFieldErrorVisible(normName))) ? rawMsg : '';
       span.textContent = msg;
       if (msg) {
         span.removeAttribute('hidden');
@@ -570,7 +729,8 @@ function createFormHandle(formEl, options = {}) {
       const rawName = ctrl.getAttribute('name');
       if (!rawName) continue;
       const normName = rawName.endsWith('[]') ? rawName.slice(0, -2) : rawName;
-      const errMsg = fieldErrors[normName] || fieldErrors[rawName];
+      const rawErrMsg = fieldErrors[normName] || fieldErrors[rawName];
+      const errMsg = rawErrMsg && (isFieldErrorVisible(normName) || isFieldErrorVisible(rawName)) ? rawErrMsg : '';
 
       if (errMsg) {
         ctrl.setAttribute('aria-invalid', 'true');
@@ -654,6 +814,9 @@ function createFormHandle(formEl, options = {}) {
    * Reset form controls back to their initial default values (NOT emptying non-empty defaults).
    */
   function reset() {
+    cancelDraftDebounce();
+    cancelFieldValidation();
+    revokePreviewUrls();
     if (!formEl) return;
     if (typeof formEl.reset === 'function') {
       formEl.reset();
@@ -673,6 +836,8 @@ function createFormHandle(formEl, options = {}) {
       }
     }
     dirty = false;
+    submitted = false;
+    touchedFields.clear();
     fieldErrors = {};
     formError = null;
     syncErrorsToDom(false);
@@ -683,6 +848,9 @@ function createFormHandle(formEl, options = {}) {
    * Completely clear all user-editable controls to empty values (distinct from `reset()`).
    */
   function clear() {
+    cancelDraftDebounce();
+    cancelFieldValidation();
+    revokePreviewUrls();
     if (!formEl || typeof formEl.querySelectorAll !== 'function') return;
     const controls = formEl.querySelectorAll('input, select, textarea');
     for (let i = 0; i < controls.length; i++) {
@@ -704,6 +872,8 @@ function createFormHandle(formEl, options = {}) {
       }
     }
     dirty = computeFormDirty(formEl, initialSnapshot);
+    submitted = false;
+    touchedFields.clear();
     fieldErrors = {};
     formError = null;
     syncErrorsToDom(false);
@@ -719,11 +889,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;
@@ -757,6 +930,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);
         }
 
@@ -767,10 +941,15 @@ function createFormHandle(formEl, options = {}) {
     }
 
     if (isBaseline) {
+      cancelFieldValidation();
       initialSnapshot = captureInitialFormSnapshot(formEl);
+      baselineValues = parseFormElement(formEl).data;
       dirty = false;
+      submitted = false;
+      touchedFields.clear();
       fieldErrors = {};
       formError = null;
+      lastError = null;
       syncErrorsToDom(false);
     } else {
       dirty = computeFormDirty(formEl, initialSnapshot);
@@ -783,7 +962,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;
   }
@@ -796,6 +977,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;
   }
 
@@ -870,12 +1052,60 @@ function createFormHandle(formEl, options = {}) {
 
     const { data: payloadData, formData, isMultipart } = parseFormElement(formEl, submitter);
 
-    // Clear previous errors before request starts
+    // 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, mark submitted = true
+    cancelFieldValidation();
+    submitted = true;
     fieldErrors = {};
     formError = null;
+    lastError = null;
     syncErrorsToDom(false);
+    const submitRevision = inputRevision;
+    const submittedSnapshot = captureInitialFormSnapshot(formEl);
     setPendingState(true, submitter);
 
+    // Track per-file upload state if multipart
+    const submitAbortController = new AbortController();
+    activeSubmitAbort = submitAbortController;
+    if (isMultipart && formEl && typeof formEl.querySelectorAll === 'function') {
+      const nextUploads = [];
+      const fileInputs = formEl.querySelectorAll('input[type="file"]');
+      for (let i = 0; i < fileInputs.length; i++) {
+        const fi = fileInputs[i];
+        const fName = fi.getAttribute('name') || 'file';
+        const files = fi.files || [];
+        for (let j = 0; j < files.length; j++) {
+          const f = files[j];
+          nextUploads.push({
+            field: fName,
+            name: f.name || 'file',
+            size: typeof f.size === 'number' ? f.size : 0,
+            status: 'uploading',
+            loaded: 0,
+            total: typeof f.size === 'number' ? f.size : 0,
+            percent: null,
+            error: null,
+          });
+        }
+      }
+      uploadEntries = nextUploads;
+      if (uploadEntries.length > 0) notifyStateChange();
+    } else {
+      uploadEntries = [];
+    }
+
     try {
       let responseData;
       const reqKey = `form:${formName}:${method}:${actionUrl}`;
@@ -883,17 +1113,39 @@ function createFormHandle(formEl, options = {}) {
         responseData = await api.get(actionUrl, payloadData, {
           key: reqKey,
           policy: 'latest',
+          signal: submitAbortController.signal,
         });
       } else {
         const bodyToSend = isMultipart && formData ? formData : payloadData;
-        responseData = await api.request(method, actionUrl, bodyToSend, {
+        const reqOpts = {
           key: reqKey,
           policy: 'drop',
-        });
+          signal: submitAbortController.signal,
+        };
+        if (isMultipart && uploadEntries.length > 0) {
+          reqOpts.onUploadProgress = (prog) => {
+            for (let i = 0; i < uploadEntries.length; i++) {
+              uploadEntries[i].loaded = prog.loaded;
+              uploadEntries[i].total = prog.total || uploadEntries[i].total;
+              uploadEntries[i].percent = prog.percent;
+            }
+            if (typeof submitOptions.onUploadProgress === 'function') {
+              submitOptions.onUploadProgress(prog, uploadEntries);
+            }
+            notifyStateChange();
+          };
+        }
+        responseData = await api.request(method, actionUrl, bodyToSend, reqOpts);
+      }
+
+      if (uploadEntries.length > 0) {
+        for (let i = 0; i < uploadEntries.length; i++) {
+          uploadEntries[i].status = 'done';
+          if (uploadEntries[i].percent !== null) uploadEntries[i].percent = 100;
+        }
       }
 
       lastData = responseData;
-      dirty = false;
       fieldErrors = {};
       formError = null;
       syncErrorsToDom(false);
@@ -914,17 +1166,51 @@ function createFormHandle(formEl, options = {}) {
         clearAttr === 'true' ||
         clearAttr === '1';
 
-      if (shouldClear) {
-        clear();
-      } else if (shouldReset) {
-        reset();
-      } else {
-        // Current state becomes the new clean baseline after successful save
-        initialSnapshot = captureInitialFormSnapshot(formEl);
-      }
+      const editedDuringSubmit = inputRevision !== submitRevision;
 
-      if (isDraftEnabled) {
-        clearDraft();
+      if (!editedDuringSubmit) {
+        dirty = false;
+        if (shouldClear) {
+          clear();
+        } else if (shouldReset) {
+          reset();
+        } else {
+          // Current state becomes the new clean baseline after successful save
+          initialSnapshot = captureInitialFormSnapshot(formEl);
+          baselineValues = parseFormElement(formEl).data;
+        }
+
+        if (isDraftEnabled) {
+          clearDraft();
+        }
+      } else {
+        // User edited form controls while submit was in flight:
+        // Never wipe out the new unsubmitted edits via reset() or clear().
+        // Update baseline to what was actually committed on the server (or empty baseline if clearOnSuccess).
+        if (shouldClear) {
+          const clearedSnapshot = new Map();
+          for (const [ctrl, snap] of submittedSnapshot.entries()) {
+            clearedSnapshot.set(ctrl, {
+              ...snap,
+              checked: false,
+              value: '',
+              selectedValues: [],
+            });
+          }
+          initialSnapshot = clearedSnapshot;
+          baselineValues = {};
+        } else if (!shouldReset) {
+          initialSnapshot = submittedSnapshot;
+          baselineValues = payloadData && typeof payloadData === 'object' ? { ...payloadData } : {};
+        }
+        dirty = computeFormDirty(formEl, initialSnapshot);
+        if (isDraftEnabled) {
+          if (dirty) {
+            saveDraft();
+          } else {
+            clearDraft();
+          }
+        }
       }
 
       // Invoke registered success hooks. Note: Any background fragment refresh failure
@@ -943,11 +1229,12 @@ function createFormHandle(formEl, options = {}) {
       }
 
       // Explicit redirect behavior
-      const redirectTarget =
+      const rawRedirectTarget =
         submitOptions.redirectOnSuccess ||
         (formEl && formEl.getAttribute('data-w-redirect')) ||
         null;
-      if (redirectTarget && isSafeRedirectUrl(redirectTarget)) {
+      const redirectTarget = resolveSafeRedirectUrl(rawRedirectTarget);
+      if (redirectTarget) {
         if (typeof options.navigate === 'function') {
           options.navigate(redirectTarget);
         } else if (typeof window !== 'undefined' && window.location) {
@@ -967,6 +1254,16 @@ function createFormHandle(formEl, options = {}) {
 
       return { ok: true, submitted: true, data: responseData, refreshOk, refreshError, hookError };
     } catch (err) {
+      lastError = err || null;
+      if (uploadEntries.length > 0) {
+        const isCanceled = Boolean(err && err.isCanceled);
+        for (let i = 0; i < uploadEntries.length; i++) {
+          if (uploadEntries[i].status === 'uploading') {
+            uploadEntries[i].status = isCanceled ? 'canceled' : 'error';
+            uploadEntries[i].error = isCanceled ? null : (err && err.message ? err.message : 'Upload failed');
+          }
+        }
+      }
       if (err && err.kind === 'validation') {
         fieldErrors = { ...(err.fieldErrors || {}) };
         formError = err.formError || (Object.keys(fieldErrors).length === 0 ? err.message : null);
@@ -989,44 +1286,227 @@ function createFormHandle(formEl, options = {}) {
       if (submitOptions.throwOnError) {
         throw err;
       }
-      return { ok: false, submitted: false, error: err };
+      return {
+        ok: false,
+        submitted: false,
+        outcomeUnknown: Boolean(err && err.outcomeUnknown),
+        outcome: (err && err.outcome) || 'failed',
+        error: err,
+      };
     } finally {
+      if (activeSubmitAbort === submitAbortController) {
+        activeSubmitAbort = null;
+      }
       setPendingState(false, submitter);
     }
   }
 
-  // Listen to native submit and input/change events on `formEl`
-  let draftDebounceTimer = null;
+  function parseFieldValidateConfig(ctrl) {
+    const ctrlAttr = ctrl && ctrl.getAttribute ? ctrl.getAttribute('data-w-validate') : null;
+    const formAttr = formEl && formEl.getAttribute ? formEl.getAttribute('data-w-validate') : null;
+    const raw = ctrlAttr !== null ? ctrlAttr : formAttr;
+    if (!raw || raw === 'false') return null;
+    const parts = String(raw).split(/[\s,|]+/).map((s) => s.trim().toLowerCase()).filter(Boolean);
+    const onBlur = parts.includes('blur') || parts.includes('true') || raw === '';
+    let debounceMs = null;
+    for (const p of parts) {
+      if (p.startsWith('debounce:')) {
+        const ms = Number(p.slice('debounce:'.length).replace(/ms$/i, ''));
+        debounceMs = Number.isFinite(ms) && ms >= 0 ? ms : 300;
+      } else if (p === 'debounce') {
+        debounceMs = 300;
+      }
+    }
+    return { onBlur, debounceMs };
+  }
+
+  async function validateField(fieldName, vOpts = {}) {
+    if (!formEl || !api || !fieldName) return { ok: true, valid: true, errors: {} };
+    const norm = fieldName.endsWith('[]') ? fieldName.slice(0, -2) : fieldName;
+
+    const seq = (validationSeqByField.get(norm) || 0) + 1;
+    validationSeqByField.set(norm, seq);
+
+    const prevAbort = validationAbortByField.get(norm);
+    if (prevAbort) {
+      try {
+        prevAbort.abort();
+      } catch (_e) {}
+    }
+    const ac = new AbortController();
+    validationAbortByField.set(norm, ac);
+
+    const validateUrl =
+      vOpts.url ||
+      (formEl.getAttribute && (formEl.getAttribute('data-w-validate-url') || formEl.getAttribute('action'))) ||
+      (typeof window !== 'undefined' && window.location ? window.location.pathname : '/');
+    const method = String(vOpts.method || (formEl.getAttribute && formEl.getAttribute('method')) || 'POST').toUpperCase();
+
+    const { data: allValues } = parseFormElement(formEl);
+    const ctrl = formEl.querySelector ? (formEl.querySelector(`[name="${norm}"]`) || formEl.querySelector(`[name="${fieldName}"]`)) : null;
+    const contextAttr = ctrl && ctrl.getAttribute ? ctrl.getAttribute('data-w-validate-context') : null;
+
+    let payload = { [norm]: allValues[norm] };
+    if (vOpts.contextFields === '*' || contextAttr === '*') {
+      payload = { ...allValues };
+    } else {
+      const ctxList = isArray(vOpts.contextFields)
+        ? vOpts.contextFields
+        : typeof contextAttr === 'string' && contextAttr.trim()
+          ? contextAttr.split(',').map((s) => s.trim()).filter(Boolean)
+          : [];
+      for (const cf of ctxList) {
+        if (Object.prototype.hasOwnProperty.call(allValues, cf)) {
+          payload[cf] = allValues[cf];
+        }
+      }
+    }
+
+    try {
+      const resp = await api.request(method, validateUrl, payload, {
+        headers: { 'X-Webspresso-Validate-Fields': norm },
+        signal: ac.signal,
+      });
+
+      if (seq !== validationSeqByField.get(norm)) {
+        return { ok: true, stale: true, valid: true, errors: {} };
+      }
+
+      const respErrors = resp && resp.errors && typeof resp.errors === 'object' ? resp.errors : {};
+      if (respErrors[norm]) {
+        fieldErrors[norm] = String(respErrors[norm]);
+      } else {
+        delete fieldErrors[norm];
+      }
+      syncErrorsToDom(false);
+      notifyStateChange();
+      return {
+        ok: true,
+        valid: !fieldErrors[norm],
+        errors: fieldErrors[norm] ? { [norm]: fieldErrors[norm] } : {},
+      };
+    } catch (err) {
+      if (seq !== validationSeqByField.get(norm) || (err && err.isCanceled)) {
+        return { ok: true, stale: true, canceled: Boolean(err && err.isCanceled), errors: {} };
+      }
+      // If server returned a 400/422 validation envelope, extract only this field's error
+      if (err && err.kind === 'validation' && err.fieldErrors) {
+        if (err.fieldErrors[norm]) {
+          fieldErrors[norm] = String(err.fieldErrors[norm]);
+        } else {
+          delete fieldErrors[norm];
+        }
+        syncErrorsToDom(false);
+        notifyStateChange();
+        return { ok: true, valid: !fieldErrors[norm], errors: fieldErrors[norm] ? { [norm]: fieldErrors[norm] } : {} };
+      }
+      // Network or 5xx error: NEVER mark the field as invalid!
+      if (typeof formEl.dispatchEvent === 'function' && typeof CustomEvent !== 'undefined') {
+        formEl.dispatchEvent(
+          new CustomEvent('w-form:validation-error', {
+            bubbles: true,
+            detail: { field: norm, error: err },
+          })
+        );
+      }
+      return { ok: false, networkError: true, error: err };
+    } finally {
+      if (validationAbortByField.get(norm) === ac) {
+        validationAbortByField.delete(norm);
+      }
+    }
+  }
+
+  function cancelUpload() {
+    if (activeSubmitAbort) {
+      try {
+        activeSubmitAbort.abort();
+      } catch (_e) {}
+      activeSubmitAbort = null;
+      return true;
+    }
+    return false;
+  }
+
+  // Listen to native submit, focusout, and input/change events on `formEl`
   const onDomInput = (evt) => {
+    inputRevision += 1;
     dirty = computeFormDirty(formEl, initialSnapshot);
     const target = evt && evt.target;
     if (target && target.getAttribute) {
+      const type = (target.type || '').toLowerCase();
       const rawName = target.getAttribute('name');
+      if (type === 'file' && evt.type === 'change' && rawName) {
+        revokePreviewUrls(rawName);
+      }
       if (rawName) {
         const norm = rawName.endsWith('[]') ? rawName.slice(0, -2) : rawName;
+        if (evt.type === 'change' && (type === 'checkbox' || type === 'radio' || target.tagName === 'SELECT')) {
+          touchedFields.add(norm);
+        }
         if (fieldErrors[norm] || fieldErrors[rawName]) {
           delete fieldErrors[norm];
           delete fieldErrors[rawName];
           syncErrorsToDom(false);
         }
+        if (evt.type === 'input') {
+          const vCfg = parseFieldValidateConfig(target);
+          if (vCfg && vCfg.debounceMs !== null) {
+            const prevTimer = validationTimersByField.get(norm);
+            if (prevTimer) clearTimeout(prevTimer);
+            const t = setTimeout(() => {
+              validationTimersByField.delete(norm);
+              validateField(norm).catch(() => {});
+            }, vCfg.debounceMs);
+            validationTimersByField.set(norm, t);
+          }
+        }
       }
     }
     if (isDraftEnabled) {
-      if (draftDebounceTimer) clearTimeout(draftDebounceTimer);
+      cancelDraftDebounce();
       draftDebounceTimer = setTimeout(() => {
+        draftDebounceTimer = null;
         saveDraft();
       }, 150);
     }
     notifyStateChange();
   };
 
+  const onDomFocusOut = (evt) => {
+    const target = evt && evt.target;
+    if (!target || !target.getAttribute) return;
+    const rawName = target.getAttribute('name');
+    if (!rawName) return;
+    const type = (target.type || '').toLowerCase();
+    if (type === 'submit' || type === 'button' || type === 'reset' || type === 'hidden') return;
+    const norm = rawName.endsWith('[]') ? rawName.slice(0, -2) : rawName;
+    const wasTouched = touchedFields.has(norm);
+    touchedFields.add(norm);
+    if (!wasTouched) {
+      syncErrorsToDom(false);
+      notifyStateChange();
+    }
+    const vCfg = parseFieldValidateConfig(target);
+    if (vCfg && vCfg.onBlur) {
+      validateField(norm).catch(() => {});
+    }
+  };
+
   const onDomSubmit = (evt) => {
     submit(evt);
   };
 
   const onDomReset = () => {
-    setTimeout(() => {
+    cancelDraftDebounce();
+    cancelFieldValidation();
+    revokePreviewUrls();
+    if (resetTimer) clearTimeout(resetTimer);
+    resetTimer = setTimeout(() => {
+      resetTimer = null;
       dirty = false;
+      submitted = false;
+      touchedFields.clear();
       fieldErrors = {};
       formError = null;
       syncErrorsToDom(false);
@@ -1037,6 +1517,7 @@ function createFormHandle(formEl, options = {}) {
   if (formEl && typeof formEl.addEventListener === 'function') {
     formEl.addEventListener('input', onDomInput);
     formEl.addEventListener('change', onDomInput);
+    formEl.addEventListener('focusout', onDomFocusOut);
     formEl.addEventListener('submit', onDomSubmit);
     formEl.addEventListener('reset', onDomReset);
   }
@@ -1062,9 +1543,66 @@ function createFormHandle(formEl, options = {}) {
       dirty = computeFormDirty(formEl, initialSnapshot);
       return dirty;
     },
+    get touched() {
+      return touchedFields.size > 0;
+    },
+    get touchedFields() {
+      return Array.from(touchedFields);
+    },
+    get submitted() {
+      return submitted;
+    },
+    isTouched(fieldName) {
+      if (!fieldName) return touchedFields.size > 0;
+      const norm = fieldName.endsWith('[]') ? fieldName.slice(0, -2) : fieldName;
+      return touchedFields.has(norm) || touchedFields.has(fieldName);
+    },
+    touch(fieldName) {
+      if (fieldName) {
+        const norm = fieldName.endsWith('[]') ? fieldName.slice(0, -2) : fieldName;
+        touchedFields.add(norm);
+      } else if (formEl && typeof formEl.querySelectorAll === 'function') {
+        const controls = formEl.querySelectorAll('input, select, textarea');
+        for (let i = 0; i < controls.length; i++) {
+          const n = controls[i].getAttribute && controls[i].getAttribute('name');
+          if (n) touchedFields.add(n.endsWith('[]') ? n.slice(0, -2) : n);
+        }
+      }
+      syncErrorsToDom(false);
+      notifyStateChange();
+      return handle;
+    },
+    untouch(fieldName) {
+      if (fieldName) {
+        const norm = fieldName.endsWith('[]') ? fieldName.slice(0, -2) : fieldName;
+        touchedFields.delete(norm);
+        touchedFields.delete(fieldName);
+      } else {
+        touchedFields.clear();
+      }
+      syncErrorsToDom(false);
+      notifyStateChange();
+      return handle;
+    },
+    validateField,
+    get uploads() {
+      return uploadEntries.map((u) => ({ ...u }));
+    },
+    cancelUpload,
+    createPreviewUrl,
+    revokePreviewUrls,
+    get inputRevision() {
+      return inputRevision;
+    },
+    get draftKey() {
+      return draftKey;
+    },
     get values() {
       return parseFormElement(formEl).data;
     },
+    get baseline() {
+      return { ...(baselineValues || {}) };
+    },
     get errors() {
       return { ...fieldErrors };
     },
@@ -1074,6 +1612,9 @@ function createFormHandle(formEl, options = {}) {
     get formError() {
       return formError;
     },
+    get lastError() {
+      return lastError;
+    },
     get lastData() {
       return lastData;
     },
@@ -1093,6 +1634,7 @@ function createFormHandle(formEl, options = {}) {
     saveDraft,
     restoreDraft,
     clearDraft,
+    setDraftKey,
     get hasDraft() {
       return hasDraft();
     },
@@ -1112,12 +1654,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);
@@ -1140,15 +1690,25 @@ function createFormHandle(formEl, options = {}) {
       return () => {};
     },
     destroy() {
+      cancelDraftDebounce();
+      cancelFieldValidation();
+      cancelUpload();
+      revokePreviewUrls();
+      if (resetTimer) {
+        clearTimeout(resetTimer);
+        resetTimer = null;
+      }
       if (formEl && typeof formEl.removeEventListener === 'function') {
         formEl.removeEventListener('input', onDomInput);
         formEl.removeEventListener('change', onDomInput);
+        formEl.removeEventListener('focusout', onDomFocusOut);
         formEl.removeEventListener('submit', onDomSubmit);
         formEl.removeEventListener('reset', onDomReset);
       }
       if (formEl) {
         delete formEl.__wFormHandle;
       }
+      beforeSubmitListeners.clear();
       successListeners.clear();
       errorListeners.clear();
       stateListeners.clear();