@verbb/formie-browser 1.0.14 → 1.0.16

package/src/js/modules/payments/factories.ts

@@ -132,6 +132,9 @@ export function createManagedPaymentModule<
             const cleanups: Cleanup[] = [];
             let apiPromise: Promise<TApi> | null = null;
             let widget: TWidget | null = null;
+            let mountPromise: Promise<void> | null = null;
+            let destructionPromise: Promise<void> | null = null;
+            let destroyed = false;
             let customSetupResult: PaymentSetupResult | null = null;
             let authorizeInFlight: Promise<boolean> | null = null;
 
@@ -145,32 +148,59 @@ export function createManagedPaymentModule<
             };
 
             const ensureMounted = async() => {
-                if (!adapter.mount || widget || !isPaymentFieldActive(ctx.target)) {
+                const mount = adapter.mount;
+
+                if (destroyed || !mount || widget || !isPaymentFieldActive(ctx.target)) {
                     return;
                 }
 
-                const api = await getApi();
-
-                try {
-                    widget = await adapter.mount({
-                        api,
-                        field: ctx.target,
-                        services,
-                        options,
-                        provider: options.provider,
-                    });
-                    debug.log('Payment widget mounted.', {
-                        moduleId: adapter.moduleId,
-                        handle: options.handle,
-                    });
-                } catch (error) {
-                    // Propagate initialization failure to the required/optional policy.
-                    debug.warn('Payment widget mount failed.', {
-                        moduleId: adapter.moduleId,
-                        handle: options.handle,
+                // Conditions can fire again while a provider is requesting its session.
+                // Share the whole mount, including API loading, with submission callers.
+                if (!mountPromise) {
+                    mountPromise = (async() => {
+                        try {
+                            const api = await getApi();
+
+                            if (destroyed || !isPaymentFieldActive(ctx.target)) {
+                                return;
+                            }
+
+                            services.removeError();
+                            widget = await mount({
+                                api,
+                                field: ctx.target,
+                                services,
+                                options,
+                                provider: options.provider,
+                            });
+                            debug.log('Payment widget mounted.', {
+                                moduleId: adapter.moduleId,
+                                handle: options.handle,
+                            });
+                        } catch (error) {
+                            // Setup and submission callers still receive provider failures.
+                            debug.warn('Payment widget mount failed.', {
+                                moduleId: adapter.moduleId,
+                                handle: options.handle,
+                            });
+                            throw error;
+                        }
+                    })().finally(() => {
+                        mountPromise = null;
                     });
-                    throw error;
                 }
+
+                return mountPromise;
+            };
+
+            const handleVisibility = () => {
+                // Event listeners have no awaited caller to handle a rejection.
+                // Allow the next visibility or submission attempt to retry the mount.
+                void ensureMounted().catch(() => {
+                    if (!destroyed && isPaymentFieldActive(ctx.target)) {
+                        services.addError(options.transport.errorMessage);
+                    }
+                });
             };
 
             // Clear stale payment feedback at the start of every submit attempt.
@@ -194,10 +224,6 @@ export function createManagedPaymentModule<
             // Remount when page flow or field conditions reveal this payment field.
             const visibilityEvents = ['formie:page:navigate:after', 'formie:submit:result'];
             visibilityEvents.forEach((eventName) => {
-                const handleVisibility = () => {
-                    void ensureMounted();
-                };
-
                 ctx.root.addEventListener(eventName, handleVisibility as EventListener);
                 cleanups.push(() => {
                     ctx.root.removeEventListener(eventName, handleVisibility as EventListener);
@@ -205,41 +231,48 @@ export function createManagedPaymentModule<
             });
 
             // Conditions emit on the module bus (not only as page-nav DOM events).
-            cleanups.push(ctx.on('formie:conditions:evaluated', () => {
-                void ensureMounted();
-            }));
+            cleanups.push(ctx.on('formie:conditions:evaluated', handleVisibility));
 
-            const destroy = async() => {
-                debug.log('Destroying payment module.', {
-                    moduleId: adapter.moduleId,
-                    handle: options.handle,
-                });
-                cleanups.forEach((c) => c());
+            const destroy = (): Promise<void> => {
+                if (destructionPromise) return destructionPromise;
+                destroyed = true;
+                destructionPromise = (async() => {
+                    debug.log('Destroying payment module.', {
+                        moduleId: adapter.moduleId,
+                        handle: options.handle,
+                    });
+                    cleanups.forEach((cleanup) => cleanup());
 
-                if (widget && adapter.unmount) {
-                    const api = await getApi();
+                    // A session request may finish after teardown starts. Release the
+                    // resulting widget before another instance can use this container.
+                    await mountPromise?.catch(() => {});
+                    const mountedWidget = widget;
+                    widget = null;
 
-                    await adapter.unmount({
-                        api,
-                        widget,
-                        field: ctx.target,
-                        services,
-                        options,
-                        provider: options.provider,
-                    });
-                    debug.log('Payment widget unmounted.', {
+                    try {
+                        if (mountedWidget && adapter.unmount) {
+                            const api = await getApi();
+
+                            await adapter.unmount({
+                                api,
+                                widget: mountedWidget,
+                                field: ctx.target,
+                                services,
+                                options,
+                                provider: options.provider,
+                            });
+                        }
+                    } finally {
+                        if (registry[occurrenceKey]?.destroy === destroy) {
+                            delete registry[occurrenceKey];
+                        }
+                    }
+                    debug.log('Payment module destroy complete.', {
                         moduleId: adapter.moduleId,
                         handle: options.handle,
                     });
-                }
-
-                if (registry[occurrenceKey]?.destroy === destroy) {
-                    delete registry[occurrenceKey];
-                }
-                debug.log('Payment module destroy complete.', {
-                    moduleId: adapter.moduleId,
-                    handle: options.handle,
-                });
+                })();
+                return destructionPromise;
             };
 
             registry[occurrenceKey] = { destroy };

package/src/js/modules/payments/opayo.ts

@@ -3,6 +3,7 @@ import { browserRequest, type BrowserRequestOptions } from '@verbb/formie-core';
 import opayoCss from '#theme-css/integrations/_opayo.css?inline';
 
 import { definePaymentModule } from '#modules/payments/api';
+import { findPaymentInputBySuffix } from '#modules/payments/utils';
 import { ensureModuleStyles } from '#modules/styles';
 import { toggleThemeClasses } from '#theme/theme-classes';
 import { createDebug } from '#utils/debug';
@@ -277,6 +278,12 @@ export const opayoModule = definePaymentModule<OpayoProviderOptions, null, Opayo
             return false;
         }
 
+        // A completed challenge resumes the original transaction. The server
+        // verifies this reference and its ownership; no new card token is needed.
+        if (findPaymentInputBySuffix(field, 'opayo3DSComplete')?.value.trim()) {
+            return true;
+        }
+
         if (isDropInCheckoutMode(provider)) {
             if (!widget) {
                 services.addError('Opayo drop-in checkout is not ready.');

package/src/js/submit/pipeline.ts

@@ -1,5 +1,7 @@
+import type { FormieFormInstance } from '#contracts/client';
 import type { FormAction, SubmitStage } from '#contracts/common';
 import type { FormSubmitResult } from '#contracts/schema';
+import { withFormEventInstance } from '#core/dom-events';
 import { EventBus } from '#events/event-bus';
 import { submitForm } from '#transport/forms-api';
 import { createDebug } from '#utils/debug';
@@ -7,6 +9,7 @@ import { getFormPages, getValidationScope } from '#validation/scope';
 import type { FormieValidator } from '#validation/validator';
 
 export type SubmitPipelineContext = {
+    instance?: FormieFormInstance;
     form: HTMLFormElement;
     action: FormAction;
     formData: FormData;
@@ -207,7 +210,7 @@ export async function runSubmitPipeline(
     let dispatchResult: FormSubmitResult | null = null;
     const finalSubmitAttempt = isFinalSubmitAttempt(form, action);
 
-    const context: SubmitPipelineContext = {
+    const context: SubmitPipelineContext = withFormEventInstance(form, {
         form,
         action,
         formData: buildSubmitFormData(form, action),
@@ -218,6 +221,10 @@ export async function runSubmitPipeline(
         },
         isAborted: () => aborted,
         abortReason: () => abortReason,
+    });
+
+    const emitSubmitResult = (eventName: string, result: FormSubmitResult) => {
+        return bus.emitSafe(eventName, withFormEventInstance(form, result));
     };
 
     const runners: Record<SubmitStage, StageRunner> = {
@@ -368,7 +375,7 @@ export async function runSubmitPipeline(
         if (aborted) {
             const abortedResult = getAbortedResult(stage, abortReason);
             {
-                const emitReport = await bus.emitSafe('formie:submit:after', abortedResult);
+                const emitReport = await emitSubmitResult('formie:submit:after', abortedResult);
                 if (emitReport.failed.length > 0) {
                     debug.warn('Submit after listeners failed (abort before stage).', {
                         stage,
@@ -377,7 +384,7 @@ export async function runSubmitPipeline(
                 }
             }
             if (finalSubmitAttempt) {
-                const emitReport = await bus.emitSafe('formie:submit:final:after', abortedResult);
+                const emitReport = await emitSubmitResult('formie:submit:final:after', abortedResult);
                 if (emitReport.failed.length > 0) {
                     debug.warn('Final submit after listeners failed (abort before stage).', {
                         stage,
@@ -414,7 +421,7 @@ export async function runSubmitPipeline(
         if (aborted) {
             const abortedResult = getAbortedResult(stage, abortReason);
             {
-                const emitReport = await bus.emitSafe('formie:submit:after', abortedResult);
+                const emitReport = await emitSubmitResult('formie:submit:after', abortedResult);
                 if (emitReport.failed.length > 0) {
                     debug.warn('Submit after listeners failed (abort after stage).', {
                         stage,
@@ -423,7 +430,7 @@ export async function runSubmitPipeline(
                 }
             }
             if (finalSubmitAttempt) {
-                const emitReport = await bus.emitSafe('formie:submit:final:after', abortedResult);
+                const emitReport = await emitSubmitResult('formie:submit:final:after', abortedResult);
                 if (emitReport.failed.length > 0) {
                     debug.warn('Final submit after listeners failed (abort after stage).', {
                         stage,
@@ -439,7 +446,7 @@ export async function runSubmitPipeline(
         // matching stage after-hook so modules can clean up their own state.
         if (stageResult && !stageResult.ok) {
             {
-                const emitReport = await bus.emitSafe('formie:submit:after', stageResult);
+                const emitReport = await emitSubmitResult('formie:submit:after', stageResult);
                 if (emitReport.failed.length > 0) {
                     debug.warn('Submit after listeners failed (failed stage).', {
                         stage,
@@ -448,7 +455,7 @@ export async function runSubmitPipeline(
                 }
             }
             if (finalSubmitAttempt) {
-                const emitReport = await bus.emitSafe('formie:submit:final:after', stageResult);
+                const emitReport = await emitSubmitResult('formie:submit:final:after', stageResult);
                 if (emitReport.failed.length > 0) {
                     debug.warn('Final submit after listeners failed (failed stage).', {
                         stage,
@@ -473,7 +480,7 @@ export async function runSubmitPipeline(
     };
 
     {
-        const emitReport = await bus.emitSafe('formie:submit:after', successResult);
+        const emitReport = await emitSubmitResult('formie:submit:after', successResult);
         if (emitReport.failed.length > 0) {
             debug.warn('Submit after listeners failed (success).', {
                 failed: emitReport.failed.length,
@@ -481,7 +488,7 @@ export async function runSubmitPipeline(
         }
     }
     if (finalSubmitAttempt) {
-        const emitReport = await bus.emitSafe('formie:submit:final:after', successResult);
+        const emitReport = await emitSubmitResult('formie:submit:final:after', successResult);
         if (emitReport.failed.length > 0) {
             debug.warn('Final submit after listeners failed (success).', {
                 failed: emitReport.failed.length,

package/src/js/utils/async.ts

@@ -79,3 +79,37 @@ export function waitForElement(
         });
     });
 }
+
+export function waitForElementRemoval(
+    selector: string,
+    root: ParentNode = document,
+    timeoutMs = 10000,
+): Promise<void> {
+    return new Promise((resolve, reject) => {
+        if (!root.querySelector(selector)) {
+            resolve();
+            return;
+        }
+
+        let timeoutId: number | null = null;
+        const observer = new MutationObserver(() => {
+            if (root.querySelector(selector)) {
+                return;
+            }
+
+            observer.disconnect();
+            if (timeoutId !== null) window.clearTimeout(timeoutId);
+            resolve();
+        });
+
+        observer.observe(root, {
+            childList: true,
+            subtree: true,
+        });
+
+        timeoutId = window.setTimeout(() => {
+            observer.disconnect();
+            reject(new Error(`Timed out waiting for "${selector}" to be removed.`));
+        }, Math.max(timeoutMs, 0));
+    });
+}

package/src/js/utils/form-started-at.ts

@@ -11,15 +11,30 @@ export function ensureFormStartedAt(form: HTMLFormElement): void {
     const renderId = renderIdInput?.value?.trim() ?? '';
     const storageKey = renderId ? `${FORM_STARTED_AT_STORAGE_PREFIX}${renderId}` : null;
 
-    let startedAt = storageKey ? sessionStorage.getItem(storageKey) : null;
+    const continuing = ['submissionUid', 'progressId'].some((name) =>
+        form.querySelector<HTMLInputElement>(`input[name="${name}"]`)?.value.trim()
+    );
+
+    // Reuse elapsed time for an existing draft or live mount, not a fresh visit.
+    let startedAt = startedAtInput.value || (continuing && storageKey ? sessionStorage.getItem(storageKey) : null);
 
     if (!startedAt) {
         startedAt = String(Date.now());
+    }
 
-        if (storageKey) {
-            sessionStorage.setItem(storageKey, startedAt);
-        }
+    if (storageKey) {
+        sessionStorage.setItem(storageKey, startedAt);
     }
 
     startedAtInput.value = startedAt;
 }
+
+export function resetFormStartedAt(form: HTMLFormElement): void {
+    const input = form.querySelector<HTMLInputElement>('input[name="formStartedAt"]');
+
+    if (input) {
+        // Hidden input values survive form.reset(), so start the next submission explicitly.
+        input.value = String(Date.now());
+        ensureFormStartedAt(form);
+    }
+}

package/src/js/utils/unload-warning.ts

@@ -1,4 +1,5 @@
 import { isFormCsrfFieldName } from '#utils/csrf';
+import { dispatchFormieDomEvent } from '#core/dom-events';
 
 const DIRTY_TRACKING_IGNORED_FIELD_NAMES = new Set([
     'action',
@@ -14,6 +15,37 @@ const DIRTY_TRACKING_IGNORED_FIELD_NAMES = new Set([
     'progressId',
 ]);
 
+type FormSnapshot = Array<[string, FormDataEntryValue]>;
+
+export type FormUnloadWarningExclusionsEventDetail = {
+    readonly form: HTMLFormElement;
+    readonly exclude: (...fieldNames: string[]) => void;
+};
+
+function collectExcludedFieldNames(form: HTMLFormElement): Set<string> {
+    const excludedFieldNames = new Set<string>();
+    let collecting = true;
+
+    dispatchFormieDomEvent(form, 'formie:unload-warning:collect-exclusions', {
+        form,
+        exclude: (...fieldNames: string[]) => {
+            // Exclusions belong to this synchronous comparison, not a later check.
+            if (!collecting) {
+                return;
+            }
+
+            fieldNames.forEach((name) => {
+                if (typeof name === 'string' && name !== '') {
+                    excludedFieldNames.add(name);
+                }
+            });
+        },
+    } satisfies FormUnloadWarningExclusionsEventDetail);
+    collecting = false;
+
+    return excludedFieldNames;
+}
+
 function serializeStableValue(value: unknown, seen: WeakSet<object>): string {
     if (value == null) {
         return String(value);
@@ -82,9 +114,16 @@ function shouldTrackFieldName(name: string, form: HTMLFormElement): boolean {
     return !DIRTY_TRACKING_IGNORED_FIELD_NAMES.has(normalizedName);
 }
 
-function buildTrackedSnapshot(form: HTMLFormElement): string {
-    const entries = Array.from(new FormData(form).entries()).filter(([name]) => {
-        return shouldTrackFieldName(String(name || ''), form);
+function buildTrackedSnapshot(
+    snapshot: FormSnapshot,
+    form: HTMLFormElement,
+    excludedFieldNames: Set<string>,
+): string {
+    const entries = snapshot.filter(([name]) => {
+        return (
+            !excludedFieldNames.has(name) &&
+            shouldTrackFieldName(String(name || ''), form)
+        );
     });
 
     return stableSerialize(entries);
@@ -103,8 +142,9 @@ export function createFormUnloadWarningGuard(
         shouldWarn?: () => boolean;
     } = {},
 ): FormUnloadWarningGuard {
-    let baselineSnapshot: string | null = null;
+    let baselineSnapshot: FormSnapshot = [];
     let isReady = false;
+    let destroyed = false;
     let isDirty = false;
     let animationFrameId: number | null = null;
     let dirtyTimerId: number | null = null;
@@ -132,18 +172,31 @@ export function createFormUnloadWarningGuard(
             return false;
         }
 
-        isDirty = buildTrackedSnapshot(form) !== baselineSnapshot;
+        // Apply the same current exclusions to both sides. A late registration
+        // must neither create a false edit nor reset genuine visitor changes.
+        const excludedFieldNames = collectExcludedFieldNames(form);
+        const currentSnapshot = Array.from(new FormData(form).entries());
+        isDirty =
+            buildTrackedSnapshot(currentSnapshot, form, excludedFieldNames) !==
+            buildTrackedSnapshot(baselineSnapshot, form, excludedFieldNames);
 
         return isDirty;
     };
 
     const captureBaseline = (): void => {
-        baselineSnapshot = buildTrackedSnapshot(form);
+        if (destroyed) {
+            return;
+        }
+        clearScheduledWork();
+        baselineSnapshot = Array.from(new FormData(form).entries());
         isReady = true;
         isDirty = false;
     };
 
     const scheduleBaselineCapture = (): void => {
+        if (destroyed) {
+            return;
+        }
         clearScheduledWork();
         isReady = false;
 
@@ -183,13 +236,16 @@ export function createFormUnloadWarningGuard(
     form.addEventListener('input', scheduleDirtyRefresh);
     form.addEventListener('change', scheduleDirtyRefresh);
     window.addEventListener('beforeunload', handleBeforeUnload);
-    scheduleBaselineCapture();
+    captureBaseline();
 
     return {
         captureBaseline,
         scheduleBaselineCapture,
         refreshDirtyState,
         destroy: () => {
+            destroyed = true;
+            isReady = false;
+            baselineSnapshot = [];
             clearScheduledWork();
             form.removeEventListener('input', scheduleDirtyRefresh);
             form.removeEventListener('change', scheduleDirtyRefresh);

package/src/js/validation/rules/required.ts

@@ -7,6 +7,24 @@ const required: ValidationRuleDefinition = {
             return true;
         }
 
+        // Required tables need rows, not a value in every cell. Cell values are
+        // optional, including unchecked checkboxes and blank email addresses.
+        if (input.closest('[data-formie-field-handle]')?.getAttribute('data-formie-field-type') === 'table') {
+            return true;
+        }
+
+        if (input instanceof HTMLInputElement && input.type === 'file') {
+            if (input.files?.length) {
+                return true;
+            }
+
+            const field = input.closest('[data-formie-field-handle]');
+            const name = input.name.replace(/\[\]$/, '');
+
+            return Array.from(field?.querySelectorAll<HTMLInputElement>('input[type="hidden"][data-formie-file-upload-asset-id]') || [])
+                .some((asset) => !asset.disabled && asset.name.startsWith(`${name}[`) && Number(asset.getAttribute('data-formie-file-upload-asset-id')) > 0);
+        }
+
         if (input.type === 'checkbox' || input.type === 'radio') {
             const checkboxInputs = input.form?.querySelectorAll(`[name="${input.name}"]:not([type="hidden"]):not([disabled])`) || [];
 

package/src/js/validation/submit-readiness.ts

@@ -33,8 +33,10 @@ export function syncSubmitReadiness(form: HTMLFormElement, validator: FormieVali
     }
 
     const { scope, final } = getValidationScope(form);
+    // Readiness observes DOM changes; redrawing errors here would retrigger it indefinitely.
     const isReady = validator.isValid(scope, {
         includeHiddenPages: final,
+        renderErrors: false,
     });
 
     form.setAttribute(SUBMIT_READY_ATTR, isReady ? 'true' : 'false');

package/src/js/validation/validator.ts

@@ -25,6 +25,7 @@ type ValidatorDefinition = {
 
 type ValidateOptions = {
     includeHiddenPages?: boolean;
+    renderErrors?: boolean;
 };
 
 const DEFAULT_PATTERNS: Record<string, RegExp> = {
@@ -40,11 +41,13 @@ const DEFAULT_PATTERNS: Record<string, RegExp> = {
 const debug = createDebug('general', 'validator');
 
 function isValidationInput(node: Element | null): node is ValidationInput {
+    // Enhancement libraries inject unnamed search controls that do not submit
+    // field values and must not inherit the field's validation rules.
     return !!node && (
         node instanceof HTMLInputElement ||
         node instanceof HTMLSelectElement ||
         node instanceof HTMLTextAreaElement
-    );
+    ) && !!node.name;
 }
 
 function isPainted(element: HTMLElement): boolean {
@@ -161,6 +164,7 @@ export class FormieValidator {
 
         this.inputs(inputOrSelector).forEach((input) => {
             let errorShown = false;
+            const renderErrors = options.renderErrors !== false && this.shouldShowError(input);
 
             if (!this.isVisible(input, options)) {
                 return;
@@ -179,7 +183,7 @@ export class FormieValidator {
                 seenGroups.add(groupKey);
             }
 
-            if (this.shouldShowError(input)) {
+            if (renderErrors) {
                 this.removeError(input);
             }
 
@@ -191,7 +195,7 @@ export class FormieValidator {
                 if (!isValid) {
                     const errorMessage = this.getErrorMessage(input, validatorName, validatorConfig, opts);
 
-                    if (this.shouldShowError(input) && !errorShown) {
+                    if (renderErrors && !errorShown) {
                         this.showError(input, validatorName, errorMessage);
                     }
 
@@ -208,7 +212,7 @@ export class FormieValidator {
                 }
             });
 
-            if (!errorShown && this.shouldShowError(input)) {
+            if (!errorShown && renderErrors) {
                 this.removeError(input);
             }
         });
@@ -298,8 +302,10 @@ export class FormieValidator {
         errorMessages.innerHTML = '';
 
         const handle = fieldContainer.getAttribute('data-formie-field-handle') || 'field';
-        const errorId = `${handle}-error`;
-        errorMessages.id = errorMessages.id || `${handle}-errors`;
+        errorMessages.id = errorMessages.id || `${input.id || `${this.form.id}-${handle}`}-errors`;
+        // Use the rendered field's scoped region so matching handles in other
+        // forms cannot capture this control's accessible error reference.
+        const errorId = `${errorMessages.id}-1`;
         applyErrorAriaLive(
             errorMessages,
             resolveValidationErrorAriaLive(this.config.errorAriaLive, this.submitted),
@@ -485,6 +491,23 @@ export class FormieValidator {
             return isPainted(richTextHost);
         }
 
+        // Searchable selects keep their value in a hidden native control. Its
+        // adjacent combobox determines whether that value is active for validation.
+        if (element instanceof HTMLSelectElement && element.hasAttribute('data-formie-combobox-input')) {
+            const combobox = element.nextElementSibling;
+
+            if (combobox instanceof HTMLElement && combobox.classList.contains('formie-combobox')) {
+                return isPainted(combobox);
+            }
+        }
+
+        // Third-party select enhancements hide the native value control without
+        // Formie's combobox marker. The containing field still determines whether
+        // its selected values need validation, including an empty required value.
+        if (element instanceof HTMLSelectElement && field instanceof HTMLElement) {
+            return isPainted(element) || isPainted(field);
+        }
+
         return isPainted(element);
     }
 

package/src/vendor.d.ts

@@ -58,7 +58,9 @@ declare module 'flatpickr/dist/l10n/index.js' {
 
 declare module 'intl-tel-input' {
     type IntlTelInputInstance = {
+        readonly promise: Promise<void>;
         setCountry(country: string): void;
+        setNumber(number: string): void;
         isValidNumber(): boolean;
         getSelectedCountryData(): { iso2?: string } | null;
         getValidationError(): number;