@verbb/formie-browser 1.0.5 → 1.0.7

package/src/js/core/error-aria-live.ts

@@ -0,0 +1,45 @@
+export type ErrorAriaLivePreference = 'polite' | 'assertive' | 'off';
+
+export function getErrorAriaLivePreference(form: HTMLFormElement): ErrorAriaLivePreference {
+    const value = (form.dataset.formieErrorAriaLive || 'polite').trim().toLowerCase();
+
+    if (value === 'assertive' || value === 'off') {
+        return value;
+    }
+
+    return 'polite';
+}
+
+export function resolveValidationErrorAriaLive(
+    preference: ErrorAriaLivePreference,
+    submitted: boolean,
+): 'polite' | 'assertive' | null {
+    if (preference === 'off') {
+        return null;
+    }
+
+    if (!submitted) {
+        return 'polite';
+    }
+
+    return preference;
+}
+
+export function resolveSubmitErrorAriaLive(preference: ErrorAriaLivePreference): 'polite' | 'assertive' | null {
+    if (preference === 'off') {
+        return null;
+    }
+
+    return preference;
+}
+
+export function applyErrorAriaLive(element: HTMLElement, ariaLive: 'polite' | 'assertive' | null): void {
+    if (ariaLive) {
+        element.setAttribute('aria-live', ariaLive);
+        element.setAttribute('aria-atomic', 'true');
+        return;
+    }
+
+    element.removeAttribute('aria-live');
+    element.removeAttribute('aria-atomic');
+}

package/src/js/core/submit-result-state.ts

@@ -1,5 +1,6 @@
 import type { FormAction } from '#contracts/common';
 import type { FormSubmitResult } from '#contracts/schema';
+import { dispatchFormieDomEvent } from '#core/dom-events';
 import { dispatchPageClientEventForSubmit } from '#core/page-client-event';
 import { syncPageTabErrors } from '#core/page-tab-errors';
 import { addThemeClasses, removeThemeClasses, toggleThemeClasses } from '#theme/theme-classes';
@@ -576,6 +577,9 @@ export function applySubmitResultState(form: HTMLFormElement, result: FormSubmit
         const validator = formWithValidationApi.formieValidation;
         validator?.resetLiveState();
         applyPageState(form, result.nextPage.id);
+        dispatchFormieDomEvent(form, 'formie:page:navigate:after', {
+            pageId: result.nextPage.id,
+        });
         debug.log('Advanced to next page.', {
             nextPageId: result.nextPage.id,
         });

package/src/js/core/submit-result-ui.ts

@@ -1,4 +1,5 @@
 import type { FormSubmitResult } from '#contracts/schema';
+import { applyErrorAriaLive, getErrorAriaLivePreference, resolveSubmitErrorAriaLive } from '#core/error-aria-live';
 import { ensureFieldErrorContainer as resolveFieldErrorContainer } from '#core/field-error-container';
 import { syncPageTabErrors } from '#core/page-tab-errors';
 import { focusFirstValidationError } from '#core/validation-focus';
@@ -124,8 +125,10 @@ function ensureFormErrorMessageContainer(form: HTMLFormElement, container: HTMLE
     // Form-level errors use a live region because they are often the only output
     // for submit-stage failures such as provider or transport errors.
     messageContainer.setAttribute('role', 'alert');
-    messageContainer.setAttribute('aria-live', 'polite');
-    messageContainer.setAttribute('aria-atomic', 'true');
+    applyErrorAriaLive(
+        messageContainer,
+        resolveSubmitErrorAriaLive(getErrorAriaLivePreference(form)),
+    );
 
     return messageContainer;
 }
@@ -295,6 +298,8 @@ function appendDescribedBy(input: HTMLElement, describedById: string): void {
 }
 
 export function renderFieldErrors(form: HTMLFormElement, fieldErrors: Record<string, string[]>): void {
+    const errorAriaLive = resolveSubmitErrorAriaLive(getErrorAriaLivePreference(form));
+
     Object.entries(fieldErrors).forEach(([handle, messages]) => {
         const fieldNode = form.querySelector(`[data-formie-field-handle="${handle}"]`);
 
@@ -307,8 +312,7 @@ export function renderFieldErrors(form: HTMLFormElement, fieldErrors: Record<str
             ? container.id
             : `${handle}-errors`;
         container.id = containerId;
-        container.setAttribute('aria-live', 'polite');
-        container.setAttribute('aria-atomic', 'true');
+        applyErrorAriaLive(container, errorAriaLive);
         addThemeClasses(fieldNode as HTMLElement, form, 'fieldLayoutError');
         (fieldNode as HTMLElement).setAttribute('data-formie-field-has-error', 'true');
 

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

@@ -436,6 +436,10 @@ export function createManagedCaptchaModule<
                         return;
                     }
 
+                    // Reconcile immediately so captcha placeholders on the newly
+                    // visible page are mounted before screen-stage policy runs.
+                    visibility.reconcileImmediate();
+
                     // By the time provider `screen()` runs, the widget is
                     // guaranteed to be mounted and the active placeholder is
                     // resolved. That lets provider code focus on challenge

package/src/js/modules/captchas/host.ts

@@ -17,6 +17,7 @@ type Cleanup = () => void;
 type ObserveVisiblePlaceholdersResult = {
     cleanup: Cleanup;
     reconcile: () => void;
+    reconcileImmediate: () => void;
     getVisible: () => HTMLElement[];
 };
 
@@ -115,7 +116,12 @@ const CAPTCHA_VISIBILITY_EVENTS = [
     'formie:page:navigate',
     'formie:page:navigate:after',
     'formie:submit:result',
-];
+] as const;
+
+const CAPTCHA_IMMEDIATE_RECONCILE_EVENTS = new Set<string>([
+    'formie:page:navigate',
+    'formie:page:navigate:after',
+]);
 
 function bindDomEvent(target: EventTarget, eventName: string, callback: EventListener): Cleanup {
     target.addEventListener(eventName, callback);
@@ -152,7 +158,7 @@ function isElementVisible(target: Element): target is HTMLElement {
 
     const style = window.getComputedStyle(target);
 
-    return style.display !== 'none' && style.visibility !== 'hidden';
+    return style.display !== 'none' && style.visibility !== 'hidden' && target.getClientRects().length > 0;
 }
 
 function getPrimaryPlaceholder(root: Element, selector: string): HTMLElement | null {
@@ -271,6 +277,11 @@ function observeVisiblePlaceholders(
         }),
         ...CAPTCHA_VISIBILITY_EVENTS.map((eventName) => {
             return bindDomEvent(root, eventName, () => {
+                if (CAPTCHA_IMMEDIATE_RECONCILE_EVENTS.has(eventName)) {
+                    reconcileNow();
+                    return;
+                }
+
                 reconcile();
             });
         }),
@@ -292,6 +303,7 @@ function observeVisiblePlaceholders(
             visible.clear();
         },
         reconcile,
+        reconcileImmediate: reconcileNow,
         getVisible: () => {
             return queryCaptchaPlaceholders(root, selector).filter((placeholder) => isElementVisible(placeholder));
         },

package/src/js/modules/captchas/recaptcha-enterprise.ts

@@ -4,6 +4,7 @@ import {
 import { CAPTCHA_EXECUTE_WAIT_FOR_VALUE_MS } from '#modules/captchas/constants';
 import {
     loadRecaptchaGlobal,
+    whenRecaptchaReady,
     type RecaptchaGlobal,
     type RecaptchaProviderOptions,
 } from '#modules/captchas/recaptcha-shared';
@@ -94,19 +95,21 @@ export const recaptchaEnterpriseModule = defineCaptchaModule<RecaptchaEnterprise
             return;
         }
 
-        if (provider.enterpriseType === 'score' || provider.enterpriseType === 'policy') {
-            // Score and policy-based keys execute by site key and can resolve
-            // directly to a token. We write that token into the shared transport
-            // layer so the backend can validate it in the usual way.
-            const token = await enterpriseApi.execute(provider.siteKey || '', { action: provider.action || 'submit' });
+        await whenRecaptchaReady(api, async() => {
+            if (provider.enterpriseType === 'score' || provider.enterpriseType === 'policy') {
+                // Score and policy-based keys execute by site key and can resolve
+                // directly to a token. We write that token into the shared transport
+                // layer so the backend can validate it in the usual way.
+                const token = await enterpriseApi.execute(provider.siteKey || '', { action: provider.action || 'submit' });
 
-            if (typeof token === 'string' && token.trim() !== '') {
-                services.tokens.write(token.trim());
+                if (typeof token === 'string' && token.trim() !== '') {
+                    services.tokens.write(token.trim());
+                }
+            } else {
+                // Fallback branch for any future Enterprise widget-like mode.
+                enterpriseApi.execute(widget);
             }
-        } else {
-            // Fallback branch for any future Enterprise widget-like mode.
-            enterpriseApi.execute(widget);
-        }
+        });
 
         const hasToken = await services.tokens.wait(CAPTCHA_EXECUTE_WAIT_FOR_VALUE_MS);
 

package/src/js/modules/captchas/recaptcha-shared.ts

@@ -67,3 +67,17 @@ export async function loadRecaptchaGlobal(
         timeoutMs: CAPTCHA_PROVIDER_LOAD_TIMEOUT_MS,
     });
 }
+
+export function whenRecaptchaReady(api: RecaptchaGlobal, callback: () => void | Promise<void>): Promise<void> {
+    const readyApi = api.enterprise || api;
+
+    return new Promise((resolve, reject) => {
+        try {
+            readyApi.ready(() => {
+                Promise.resolve(callback()).then(resolve).catch(reject);
+            });
+        } catch (error) {
+            reject(error);
+        }
+    });
+}

package/src/js/modules/captchas/recaptcha-v3.ts

@@ -4,6 +4,7 @@ import {
 import { CAPTCHA_EXECUTE_WAIT_FOR_VALUE_MS } from '#modules/captchas/constants';
 import {
     loadRecaptchaGlobal,
+    whenRecaptchaReady,
     type RecaptchaGlobal,
     type RecaptchaProviderOptions,
 } from '#modules/captchas/recaptcha-shared';
@@ -40,11 +41,13 @@ export const recaptchaV3Module = defineCaptchaModule<RecaptchaProviderOptions, R
 
         // v3 returns its token directly from `execute()`, unlike widget-based
         // captchas that signal completion later via callbacks.
-        const token = await api.execute(provider.siteKey || '', { action: provider.action || 'submit' });
+        await whenRecaptchaReady(api, async() => {
+            const token = await api.execute(provider.siteKey || '', { action: provider.action || 'submit' });
 
-        if (typeof token === 'string' && token.trim() !== '') {
-            services.tokens.write(token.trim());
-        }
+            if (typeof token === 'string' && token.trim() !== '') {
+                services.tokens.write(token.trim());
+            }
+        });
 
         // We still wait on the shared token layer so the module follows the
         // same transport contract as every other captcha provider.

package/src/js/modules/captchas/turnstile.ts

@@ -14,6 +14,7 @@ type TurnstileGlobal = {
     render: (container: HTMLElement, options: Record<string, unknown>) => string;
     execute: (widgetId: string) => void;
     reset: (widgetId: string) => void;
+    remove: (widgetId: string) => void;
 };
 
 // Provider-specific options only. Generic captcha concerns are handled by the
@@ -123,9 +124,14 @@ export const turnstileModule = defineCaptchaModule<TurnstileProviderOptions, Tur
         });
     },
     unmount: ({ api, widget, services }) => {
-        // Reset provider state whenever the widget is torn down so the DOM
-        // transport layer and the provider widget stay in sync.
-        api.reset(widget);
+        // Remove the widget before clearing placeholder DOM so Turnstile does not
+        // log errors about orphaned challenge iframes during remounts.
+        if (typeof api.remove === 'function') {
+            api.remove(widget);
+        } else {
+            api.reset(widget);
+        }
+
         services.tokens.clear();
     },
 });

package/src/js/modules/fields/conditions/effects.ts

@@ -72,7 +72,49 @@ function setVisibilityState(node: Element, hidden: boolean): boolean {
     return wasHidden !== hidden;
 }
 
+const SUBMIT_CONTROL_SELECTOR = 'button[type="submit"], button[data-formie-action], input[type="submit"]';
+
+function syncControlDisabledState(control: Element, hidden: boolean): void {
+    if (!(control instanceof HTMLButtonElement || control instanceof HTMLInputElement)) {
+        return;
+    }
+
+    if (hidden) {
+        if (!control.hasAttribute(CONDITION_DISABLED_ATTR)) {
+            if (control.hasAttribute('disabled')) {
+                control.setAttribute(PRESERVED_DISABLED_ATTR, 'true');
+            }
+
+            control.setAttribute(CONDITION_DISABLED_ATTR, 'true');
+        }
+
+        control.setAttribute('disabled', 'true');
+        return;
+    }
+
+    if (!control.hasAttribute(CONDITION_DISABLED_ATTR)) {
+        return;
+    }
+
+    if (control.hasAttribute(PRESERVED_DISABLED_ATTR)) {
+        control.setAttribute('disabled', 'true');
+        control.removeAttribute(PRESERVED_DISABLED_ATTR);
+    } else {
+        control.removeAttribute('disabled');
+    }
+
+    control.removeAttribute(CONDITION_DISABLED_ATTR);
+}
+
 function syncDisabledState(node: Element, hidden: boolean): void {
+    if (node.matches(SUBMIT_CONTROL_SELECTOR)) {
+        syncControlDisabledState(node, hidden);
+    }
+
+    node.querySelectorAll(SUBMIT_CONTROL_SELECTOR).forEach((control) => {
+        syncControlDisabledState(control, hidden);
+    });
+
     node.querySelectorAll('input, textarea, select').forEach((input) => {
         if (hidden) {
             if (!input.hasAttribute(CONDITION_DISABLED_ATTR)) {

package/src/js/modules/fields/index.ts

@@ -12,6 +12,7 @@ export const builtinFieldModuleLoaders: Record<string, () => Promise<FormieModul
     'custom-maps': () => import('#modules/fields/custom-maps').then((module) => module.customMapsModule),
     'date-picker': () => import('#modules/fields/date-picker').then((module) => module.datePickerModule),
     'file-upload': () => import('#modules/fields/file-upload').then((module) => module.fileUploadModule),
+    'upload-manager': () => import('#modules/fields/upload-manager').then((module) => module.uploadManagerModule),
     'hidden': () => import('#modules/fields/hidden').then((module) => module.hiddenModule),
     'phone-country': () => import('#modules/fields/phone-country').then((module) => module.phoneCountryModule),
     'address-country': () => import('#modules/fields/address-country').then((module) => module.addressCountryModule),

package/src/js/modules/fields/signature.ts

@@ -8,7 +8,16 @@ import { ensureModuleStyles } from '#modules/styles';
 const INPUT_SELECTOR = 'input[data-formie-signature-input]';
 const CANVAS_SELECTOR = 'canvas[data-formie-signature-canvas]';
 const CLEAR_SELECTOR = '[data-formie-signature-clear]';
+const MESSAGE_SELECTOR = '[data-formie-signature-message]';
 const MODULE_ID = 'signature';
+const MAX_SIZE_ATTEMPTS = 20;
+const SIZE_RETRY_MS = 100;
+const VISIBILITY_ATTRS = [
+    'hidden',
+    'data-formie-conditionally-hidden',
+    'data-formie-page-hidden',
+    'data-formie-row-hidden',
+] as const;
 
 ensureModuleStyles(MODULE_ID, [signatureCss]);
 
@@ -18,6 +27,11 @@ type SignatureOptions = {
     penWeight?: string;
 };
 
+type SignatureMessages = {
+    noCanvas: string;
+    initFailed: string;
+};
+
 function getCanvasSize(canvas: HTMLCanvasElement): { width: number; height: number } {
     const rect = canvas.getBoundingClientRect();
 
@@ -27,6 +41,58 @@ function getCanvasSize(canvas: HTMLCanvasElement): { width: number; height: numb
     };
 }
 
+function supportsCanvas(): boolean {
+    const probe = document.createElement('canvas');
+
+    return typeof probe.getContext === 'function' && !!probe.getContext('2d');
+}
+
+function getMessageElement(field: HTMLElement): HTMLElement | null {
+    const message = field.querySelector(MESSAGE_SELECTOR);
+
+    return message instanceof HTMLElement ? message : null;
+}
+
+function getSignatureMessages(field: HTMLElement): SignatureMessages {
+    const message = getMessageElement(field);
+
+    return {
+        noCanvas: message?.dataset.formieSignatureMessageNoCanvas
+            || 'This browser does not support canvas, which is required for signatures.',
+        initFailed: message?.dataset.formieSignatureMessageInitFailed
+            || 'The signature pad could not be loaded. Try refreshing the page.',
+    };
+}
+
+function setSignatureMessage(field: HTMLElement, canvas: HTMLCanvasElement, message: string | null): void {
+    const messageElement = getMessageElement(field);
+
+    if (!messageElement) {
+        return;
+    }
+
+    if (message) {
+        messageElement.textContent = message;
+        messageElement.hidden = false;
+        canvas.setAttribute('aria-hidden', 'true');
+        field.classList.add('formie-signature-has-message');
+        return;
+    }
+
+    messageElement.textContent = '';
+    messageElement.hidden = true;
+    canvas.removeAttribute('aria-hidden');
+    field.classList.remove('formie-signature-has-message');
+}
+
+function isFieldVisible(field: HTMLElement): boolean {
+    return !field.hasAttribute('hidden')
+        && !field.hasAttribute('data-formie-conditionally-hidden')
+        && !field.hasAttribute('data-formie-page-hidden')
+        && !field.hasAttribute('data-formie-row-hidden')
+        && field.getClientRects().length > 0;
+}
+
 function drawValueOnCanvas(canvas: HTMLCanvasElement, value: string): void {
     if (!value) {
         return;
@@ -45,6 +111,18 @@ function drawValueOnCanvas(canvas: HTMLCanvasElement, value: string): void {
     };
 }
 
+async function restoreSignatureValue(signaturePad: SignaturePad, canvas: HTMLCanvasElement, value: string): Promise<void> {
+    if (!value) {
+        return;
+    }
+
+    try {
+        await signaturePad.fromDataURL(value);
+    } catch {
+        drawValueOnCanvas(canvas, value);
+    }
+}
+
 function initSignatureField(
     root: HTMLElement,
     field: HTMLElement,
@@ -53,8 +131,21 @@ function initSignatureField(
     clearButton: HTMLElement | null,
     options: SignatureOptions,
 ): () => void {
+    const messages = getSignatureMessages(field);
+
+    if (!supportsCanvas()) {
+        setSignatureMessage(field, canvas, messages.noCanvas);
+
+        return () => {};
+    }
+
     const penWeight = parseFloat(options.penWeight || '2') || 2;
     const resizeTarget = canvas.parentElement instanceof HTMLElement ? canvas.parentElement : field;
+    let sizeAttempts = 0;
+    let sizeRetryTimer: number | null = null;
+    let readyDispatched = false;
+    let initFailed = false;
+
     const signaturePad = new SignaturePad(canvas, {
         backgroundColor: options.backgroundColor || 'rgba(255, 255, 255, 0)',
         penColor: options.penColor || '#000000',
@@ -63,51 +154,142 @@ function initSignatureField(
         maxWidth: penWeight,
     });
 
-    const resizeCanvas = () => {
+    const clearSizeRetry = () => {
+        if (sizeRetryTimer !== null) {
+            window.clearTimeout(sizeRetryTimer);
+            sizeRetryTimer = null;
+        }
+    };
+
+    const markReady = () => {
+        if (readyDispatched) {
+            return;
+        }
+
+        readyDispatched = true;
+        initFailed = false;
+        setSignatureMessage(field, canvas, null);
+        dispatchFieldEvent(field, MODULE_ID, 'init', {
+            signature: signaturePad,
+        });
+    };
+
+    const markInitFailed = () => {
+        if (readyDispatched || initFailed) {
+            return;
+        }
+
+        initFailed = true;
+        setSignatureMessage(field, canvas, messages.initFailed);
+    };
+
+    const resizeCanvas = async(): Promise<boolean> => {
         const { width, height } = getCanvasSize(canvas);
 
         if (!(width > 0) || !(height > 0)) {
-            return;
+            return false;
         }
 
         const ratio = Math.max(window.devicePixelRatio || 1, 1);
         const context = canvas.getContext('2d');
         if (!context) {
-            return;
+            return false;
         }
 
-        // SignaturePad clears bitmap state when the canvas size changes, so resize
-        // captures the current data URL first and redraws it onto the new surface.
         const existingValue = input.value || (signaturePad.isEmpty() ? '' : signaturePad.toDataURL());
+
         canvas.width = width * ratio;
         canvas.height = height * ratio;
         context.setTransform(1, 0, 0, 1, 0, 0);
         context.scale(ratio, ratio);
         signaturePad.clear();
-        drawValueOnCanvas(canvas, existingValue);
+
+        await restoreSignatureValue(signaturePad, canvas, existingValue);
+        markReady();
+
+        return true;
+    };
+
+    const scheduleSizeRetry = () => {
+        if (readyDispatched || initFailed) {
+            return;
+        }
+
+        if (sizeAttempts >= MAX_SIZE_ATTEMPTS) {
+            markInitFailed();
+            return;
+        }
+
+        clearSizeRetry();
+        sizeRetryTimer = window.setTimeout(() => {
+            sizeRetryTimer = null;
+            sizeAttempts += 1;
+            void attemptResize();
+        }, SIZE_RETRY_MS);
+    };
+
+    const attemptResize = async() => {
+        const sized = await resizeCanvas();
+
+        if (!sized) {
+            scheduleSizeRetry();
+            return;
+        }
+
+        clearSizeRetry();
+        sizeAttempts = 0;
     };
 
     const scheduleResize = (delay = 0) => {
         window.setTimeout(() => {
             window.requestAnimationFrame(() => {
-                resizeCanvas();
+                void attemptResize();
             });
         }, delay);
     };
-    const resizeHandler = () => {
+
+    const requestResize = () => {
+        if (isFieldVisible(field) && !readyDispatched) {
+            initFailed = false;
+        }
+
         scheduleResize();
     };
+
+    const resizeHandler = () => {
+        requestResize();
+    };
+
     const pageNavigateHandler = () => {
-        // Multi-page forms can reveal a signature pad after layout changes; delay
-        // slightly so the newly visible page has settled before measuring.
+        if (!isFieldVisible(field)) {
+            return;
+        }
+
+        sizeAttempts = 0;
+        initFailed = false;
         scheduleResize(100);
     };
+
+    const visibilityHandler = () => {
+        if (!isFieldVisible(field)) {
+            return;
+        }
+
+        sizeAttempts = 0;
+        initFailed = false;
+        requestResize();
+    };
+
     const resizeObserver = typeof ResizeObserver === 'undefined'
         ? null
         : new ResizeObserver(() => {
-            scheduleResize();
+            requestResize();
         });
 
+    const visibilityObserver = new MutationObserver(() => {
+        visibilityHandler();
+    });
+
     const syncInputValue = (nextValue: string) => {
         const valueChanged = input.value !== nextValue;
         input.value = nextValue;
@@ -133,21 +315,23 @@ function initSignatureField(
     window.addEventListener('resize', resizeHandler);
     root.addEventListener('formie:page:navigate:after', pageNavigateHandler as EventListener);
     resizeObserver?.observe(resizeTarget);
+    visibilityObserver.observe(field, {
+        attributes: true,
+        attributeFilter: [...VISIBILITY_ATTRS],
+    });
     scheduleResize();
 
     if (clearButton) {
         clearButton.addEventListener('click', clearSignature);
     }
 
-    dispatchFieldEvent(field, MODULE_ID, 'init', {
-        signature: signaturePad,
-    });
-
     return () => {
+        clearSizeRetry();
         signaturePad.removeEventListener('endStroke', syncValue);
         window.removeEventListener('resize', resizeHandler);
         root.removeEventListener('formie:page:navigate:after', pageNavigateHandler as EventListener);
         resizeObserver?.disconnect();
+        visibilityObserver.disconnect();
         if (clearButton) {
             clearButton.removeEventListener('click', clearSignature);
         }