@verbb/formie-browser 1.0.14 → 1.0.16

package/src/js/core/dom-events.ts

@@ -1,6 +1,35 @@
-import { toDomEventName } from '#utils/event-names';
+import type { FormieFormInstance } from '#contracts/client';
+import { FORMIE_HTML_EVENT_NAMES, toDomEventName } from '#utils/event-names';
+
+const formEventInstances = new WeakMap<Element, FormieFormInstance>();
+const lifecycleEvents = new Set<string>([...FORMIE_HTML_EVENT_NAMES, 'formie:state:reset']);
+
+export function bindFormEventInstance(root: Element, form: HTMLFormElement | null, instance: FormieFormInstance): () => void {
+    // Wrapper mounts also dispatch lifecycle events from their inner form.
+    const targets = new Set<Element>(form ? [root, form] : [root]);
+    targets.forEach((target) => formEventInstances.set(target, instance));
+    return () => {
+        targets.forEach((target) => {
+            if (formEventInstances.get(target) === instance) formEventInstances.delete(target);
+        });
+    };
+}
+
+export function withFormEventInstance<T extends object>(target: Element, detail: T): T & { instance?: FormieFormInstance } {
+    const instance = formEventInstances.get(target);
+    // Retain payload identity: synchronous hooks can modify the active result.
+    return instance ? Object.assign(detail, { instance }) : detail;
+}
 
 export function dispatchFormieDomEvent(target: Element, eventName: string, detail: unknown): void {
+    // Early setup and standalone module hydration have no mounted form instance.
+    // Custom module events retain their own payload shapes.
+    if (lifecycleEvents.has(eventName) || eventName.startsWith('formie:stage:')) {
+        if (detail == null) detail = formEventInstances.has(target) ? {} : detail;
+        if (detail && typeof detail === 'object' && !Array.isArray(detail)) {
+            detail = withFormEventInstance(target, detail);
+        }
+    }
     target.dispatchEvent(new CustomEvent(toDomEventName(eventName), {
         bubbles: true,
         detail,

package/src/js/core/page-client-event.ts

@@ -1,3 +1,4 @@
+import { dispatchFormieDomEvent } from '#core/dom-events';
 import { createDebug } from '#utils/debug';
 
 const debug = createDebug('general', 'page-client-event');
@@ -114,13 +115,10 @@ export function dispatchResolvedClientEvents(form: HTMLFormElement, events: Reso
     events.forEach((item) => {
         win.dataLayer!.push(item.payload);
 
-        form.dispatchEvent(new CustomEvent('formie:client-event', {
-            bubbles: true,
-            detail: {
-                event: item.event,
-                payload: item.payload,
-            },
-        }));
+        dispatchFormieDomEvent(form, 'formie:client-event', {
+            event: item.event,
+            payload: item.payload,
+        });
     });
 
     debug.log('Dispatched resolved client events.', {

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

@@ -5,6 +5,7 @@ import { dispatchPageClientEventForSubmit, dispatchResolvedClientEvents } from '
 import { syncPageTabErrors } from '#core/page-tab-errors';
 import { addThemeClasses, removeThemeClasses, toggleThemeClasses } from '#theme/theme-classes';
 import { createDebug } from '#utils/debug';
+import { resetFormStartedAt } from '#utils/form-started-at';
 import { getFormStateEventName, normalizeFormieEventName } from '#utils/event-names';
 import type { FormieValidator } from '#validation/validator';
 import { syncSubmitReadiness } from '#validation/submit-readiness';
@@ -371,6 +372,17 @@ export function applyPageState(form: HTMLFormElement, nextPageId: string): void
 }
 
 function syncSubmissionIdentity(form: HTMLFormElement, result: FormSubmitResult): void {
+    if (result.meta?.resetSubmissionIdentity === true) {
+        // Saved spam is terminal. Preserve the entered values for correction,
+        // but do not try to continue the rejected record on the next submit.
+        removeHiddenInput(form, 'submissionId');
+        removeHiddenInput(form, 'submissionUid');
+        removeHiddenInput(form, 'progressId');
+        setHiddenInputValue(form, 'expectedVersion', '0');
+        clearResumeTokenState(form);
+        return;
+    }
+
     const session = result.meta?.session as { version?: number } | undefined;
     const version = session?.version ?? result.meta?.version;
     if (typeof version === 'number') {
@@ -449,6 +461,15 @@ function resetSubmissionState(form: HTMLFormElement, options: ResetSubmissionSta
     // A full state reset is broader than the native form reset: it also clears
     // hidden continuity inputs, resume-token state, page UI, and live validation.
     form.reset();
+    // Summary modules on hidden pages are unmounted and cannot clear themselves.
+    form.querySelectorAll('[data-formie-summary-token]').forEach((element) => {
+        if (element instanceof HTMLInputElement) {
+            element.remove();
+        } else {
+            element.removeAttribute('data-formie-summary-token');
+        }
+    });
+    form.querySelectorAll('[data-formie-summary-blocks]').forEach((element) => element.replaceChildren());
     if (!options.preserveHiddenState) {
         setFormHiddenState(form, false);
     }
@@ -458,16 +479,17 @@ function resetSubmissionState(form: HTMLFormElement, options: ResetSubmissionSta
     removeHiddenInput(form, 'progressId');
     removeHiddenInput(form, 'pageId');
     clearResumeTokenState(form);
+    resetFormStartedAt(form);
     validator?.resetLiveState();
 
     if (firstPageId) {
         applyPageState(form, firstPageId);
-        form.dispatchEvent(new CustomEvent(getFormStateEventName('reset'), { bubbles: true }));
+        dispatchFormieDomEvent(form, getFormStateEventName('reset'), undefined);
         return;
     }
 
     syncPageTabErrors(form);
-    form.dispatchEvent(new CustomEvent(getFormStateEventName('reset'), { bubbles: true }));
+    dispatchFormieDomEvent(form, getFormStateEventName('reset'), undefined);
 }
 
 function shouldResetSubmissionState(result: FormSubmitResult): boolean {
@@ -542,6 +564,12 @@ export function applySubmitResultState(form: HTMLFormElement, result: FormSubmit
         return;
     }
 
+    // Provider handlers may navigate as soon as their action event is dispatched.
+    // Treat checkout navigation like the generic redirect before invoking them.
+    if (result.payment?.action?.type === 'redirect' && result.payment.action.url) {
+        markInternalNavigation(form, 'payment-redirect');
+    }
+
     // Dispatch payment/redirect events from submitData (e.g. formie:payment:mollie:redirect)
     const eventDispatchResult = dispatchSubmitDataEvents(form, result);
 

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

@@ -363,7 +363,7 @@ function shouldRenderSuccessMessage(form: HTMLFormElement, result: FormSubmitRes
     return getConfiguredCompletionBehavior(form) === 'message' && getSuccessMessagePosition(form) !== '';
 }
 
-export function renderFormSuccess(form: HTMLFormElement, message: string): void {
+export function renderFormSuccess(form: HTMLFormElement, message: string, options: { hideForm?: boolean } = {}): void {
     const position = getSuccessMessagePosition(form);
 
     if (!position) {
@@ -384,10 +384,17 @@ export function renderFormSuccess(form: HTMLFormElement, message: string): void
     successNode.innerHTML = message;
     container.appendChild(successNode);
 
-    if (shouldHideFormOnSuccess(form)) {
+    if (options.hideForm !== false && shouldHideFormOnSuccess(form)) {
         setFormHiddenState(form, true);
     }
 
+    const scrollToTop = form.dataset.formieScrollToTop?.trim().toLowerCase();
+
+    if (scrollToTop !== undefined && ['', 'true', '1'].includes(scrollToTop)) {
+        // Scroll after hiding the form so the message's final position is used.
+        container.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+
     const timeoutMs = getSuccessMessageTimeoutMs(form);
 
     if (timeoutMs !== null) {
@@ -407,8 +414,23 @@ export function applySubmitResultUi(form: HTMLFormElement, result: FormSubmitRes
     clearAriaInvalid(form);
 
     if (result.ok) {
+        const summaryTokens = result.meta?.summaryTokens;
+
+        // Hidden-page modules mount only after navigation. Persist access before
+        // that happens so the new summary instance can read its saved submission.
+        if (summaryTokens && typeof summaryTokens === 'object') {
+            form.querySelectorAll<HTMLElement>('[data-formie-field-uid]').forEach((field) => {
+                const token = (summaryTokens as Record<string, unknown>)[field.dataset.formieFieldUid || ''];
+
+                if (typeof token === 'string' && token) {
+                    field.querySelector('[data-formie-summary-container]')?.setAttribute('data-formie-summary-token', token);
+                }
+            });
+        }
+
         if (shouldRenderSuccessMessage(form, result)) {
-            renderFormSuccess(form, result.message || '');
+            // Saving progress acknowledges persistence without completing the form.
+            renderFormSuccess(form, result.message || '', { hideForm: result.action !== 'save' });
         }
 
         return;

package/src/js/core/validation-focus.ts

@@ -14,20 +14,34 @@ function getFirstErroredField(form: HTMLFormElement): HTMLElement | null {
     }) || null;
 }
 
+function getVisibleControl(control: HTMLElement): HTMLElement {
+    if (control instanceof HTMLTextAreaElement) {
+        const richText = (control as HTMLTextAreaElement & { richText?: { content: HTMLElement } }).richText;
+
+        if (richText) {
+            return richText.content;
+        }
+    }
+
+    return control;
+}
+
 function getFieldFocusTarget(field: HTMLElement): HTMLElement | null {
     const invalidControl = Array.from(field.querySelectorAll('[aria-invalid="true"]')).find((node) => {
         return !isValidationSkipped(node);
     }) as HTMLElement | undefined;
 
     if (invalidControl) {
-        return invalidControl;
+        return getVisibleControl(invalidControl);
     }
 
-    return Array.from(field.querySelectorAll(
+    const control = Array.from(field.querySelectorAll(
         'input:not([type="hidden"]):not([disabled]), select:not([disabled]), textarea:not([disabled])',
     )).find((node) => {
         return !isValidationSkipped(node);
-    }) as HTMLElement | undefined ?? null;
+    }) as HTMLElement | undefined;
+
+    return control ? getVisibleControl(control) : null;
 }
 
 function getFormLevelErrorTarget(form: HTMLFormElement): HTMLElement | null {

package/src/js/modules/address/google-address.ts

@@ -30,7 +30,8 @@ async function loadGoogleMapsScript(apiKey: string): Promise<GoogleMaps> {
         if (maps?.places?.PlaceAutocompleteElement) {
             return existing as GoogleMaps;
         }
-        const imp = maps as { importLibrary?: (name: string) => Promise<unknown> } | undefined;
+        const imp = maps as
+            { importLibrary?: (name: string) => Promise<unknown> } | undefined;
         if (typeof imp?.importLibrary === 'function') {
             await imp.importLibrary('places');
         }
@@ -44,7 +45,8 @@ async function loadGoogleMapsScript(apiKey: string): Promise<GoogleMaps> {
     const existingScript = document.getElementById(SCRIPT_ID);
     if (existingScript) {
         const google = await ensureGlobal<GoogleMaps>('google', 10000);
-        const maps = google?.maps as { importLibrary?: (name: string) => Promise<unknown> } | undefined;
+        const maps = google?.maps as
+            { importLibrary?: (name: string) => Promise<unknown> } | undefined;
         if (typeof maps?.importLibrary === 'function') {
             await maps.importLibrary('places');
         }
@@ -80,7 +82,8 @@ async function loadGoogleMapsScript(apiKey: string): Promise<GoogleMaps> {
         });
 
         const google = await ready;
-        const maps = google?.maps as { importLibrary?: (name: string) => Promise<unknown> } | undefined;
+        const maps = google?.maps as
+            { importLibrary?: (name: string) => Promise<unknown> } | undefined;
         if (typeof maps?.importLibrary === 'function') {
             await maps.importLibrary('places');
         }
@@ -152,7 +155,13 @@ type AddressComponent = {
     long_text?: string;
 };
 
-function parseAddressComponents(components: AddressComponent[]): Record<string, string> {
+type GooglePostalAddress = {
+    addressLines?: unknown[];
+};
+
+function parseAddressComponents(
+    components: AddressComponent[],
+): Record<string, string> {
     const map = componentMap();
     const out: Record<string, string> = {};
 
@@ -162,10 +171,11 @@ function parseAddressComponents(components: AddressComponent[]): Record<string,
         if (!type || !map[type as keyof typeof map]) continue;
 
         const fieldKey = map[type as keyof typeof map];
-        const val = (comp as unknown as Record<string, string>)[fieldKey]
-            ?? comp.short_text
-            ?? comp.long_text
-            ?? '';
+        const val =
+            (comp as unknown as Record<string, string>)[fieldKey] ??
+            comp.short_text ??
+            comp.long_text ??
+            '';
 
         out[type] = val;
     }
@@ -173,17 +183,26 @@ function parseAddressComponents(components: AddressComponent[]): Record<string,
     return out;
 }
 
-function buildAddressFromComponents(formData: Record<string, string>): {
+export function buildAddressFromComponents(
+    formData: Record<string, string>,
+    postalAddress?: GooglePostalAddress,
+): {
     address1: string;
     city: string;
     state: string;
     zip: string;
     country: string;
 } {
-    let address1 = '';
+    const postalAddressLines = postalAddress?.addressLines?.filter(
+        (line): line is string =>
+            typeof line === 'string' && line.trim() !== '',
+    );
+    let address1 = postalAddressLines?.join(', ') || '';
 
-    if (formData.street_number || formData.route) {
-        address1 = [formData.street_number, formData.route].filter(Boolean).join(' ');
+    if (!address1 && (formData.street_number || formData.route)) {
+        address1 = [formData.street_number, formData.route]
+            .filter(Boolean)
+            .join(' ');
 
         if (formData.subpremise) {
             address1 = `${formData.subpremise}/${address1}`;
@@ -203,7 +222,8 @@ function hasCountryRestriction(options: Record<string, unknown>): boolean {
     const componentRestrictions = options.componentRestrictions;
 
     if (componentRestrictions && typeof componentRestrictions === 'object') {
-        const country = (componentRestrictions as { country?: unknown }).country;
+        const country = (componentRestrictions as { country?: unknown })
+            .country;
 
         if (Array.isArray(country) ? country.length > 0 : Boolean(country)) {
             return true;
@@ -215,7 +235,9 @@ function hasCountryRestriction(options: Record<string, unknown>): boolean {
     return Array.isArray(includedRegionCodes) && includedRegionCodes.length > 0;
 }
 
-export function buildGoogleAutocompleteOptions(provider: GoogleAddressProviderOptions): Record<string, unknown> {
+export function buildGoogleAutocompleteOptions(
+    provider: GoogleAddressProviderOptions,
+): Record<string, unknown> {
     const options = { types: ['geocode'], ...(provider.options || {}) };
     const country = provider.countryDefaultValue?.trim().toLowerCase();
 
@@ -247,10 +269,13 @@ export const googleAddressModule = defineAddressModule<
     },
     mount: async ({ api, field, services, provider }) => {
         const input = services.input.getAutocomplete();
-        const PlaceAutocompleteElement = api?.maps?.places?.PlaceAutocompleteElement;
+        const PlaceAutocompleteElement =
+            api?.maps?.places?.PlaceAutocompleteElement;
 
         if (!input || typeof PlaceAutocompleteElement !== 'function') {
-            console.warn('[formie] Google Places API not ready; address autocomplete skipped.');
+            console.warn(
+                '[formie] Google Places API not ready; address autocomplete skipped.',
+            );
             return null;
         }
 
@@ -303,20 +328,40 @@ export const googleAddressModule = defineAddressModule<
         wrapper.appendChild(input);
 
         const onSelect = async (ev: Event): Promise<void> => {
-            const e = ev as unknown as { placePrediction?: { toPlace: () => Promise<{ addressComponents?: unknown[]; formattedAddress?: string; fetchFields: (opts: { fields: string[] }) => Promise<void> }> } };
+            const e = ev as unknown as {
+                placePrediction?: {
+                    toPlace: () => Promise<{
+                        addressComponents?: unknown[];
+                        formattedAddress?: string;
+                        postalAddress?: GooglePostalAddress;
+                        fetchFields: (opts: {
+                            fields: string[];
+                        }) => Promise<void>;
+                    }>;
+                };
+            };
             const pred = e.placePrediction;
 
             if (!pred) return;
 
             const place = await pred.toPlace();
-            await place.fetchFields({ fields: ['addressComponents', 'formattedAddress'] });
+            await place.fetchFields({
+                fields: [
+                    'addressComponents',
+                    'formattedAddress',
+                    'postalAddress',
+                ],
+            });
 
             if (!place.addressComponents) return;
 
             const formData = parseAddressComponents(
                 place.addressComponents as AddressComponent[],
             );
-            const address = buildAddressFromComponents(formData);
+            const address = buildAddressFromComponents(
+                formData,
+                place.postalAddress,
+            );
 
             setFieldValues(services, {
                 ...address,
@@ -324,15 +369,19 @@ export const googleAddressModule = defineAddressModule<
             });
 
             field.dispatchEvent(
-                new CustomEvent(getAddressProviderEventName('google', 'populate'), {
-                    bubbles: true,
-                    detail: {
-                        addressProvider: 'google',
-                        place,
-                        formattedAddress: place.formattedAddress,
-                        addressComponents: place.addressComponents,
+                new CustomEvent(
+                    getAddressProviderEventName('google', 'populate'),
+                    {
+                        bubbles: true,
+                        detail: {
+                            addressProvider: 'google',
+                            place,
+                            formattedAddress: place.formattedAddress,
+                            addressComponents: place.addressComponents,
+                            postalAddress: place.postalAddress,
+                        },
                     },
-                }),
+                ),
             );
         };
         autocomplete.addEventListener('gmp-select', onSelect as EventListener);
@@ -342,9 +391,14 @@ export const googleAddressModule = defineAddressModule<
     onCurrentLocation: async (position, { field, services, provider }) => {
         const { latitude, longitude } = position.coords;
         const form = services.form;
-        const actionUrl = provider.geocodeEndpoint || form?.action || window.location.href;
-        const fieldHandle = field.getAttribute('data-formie-field-handle')?.trim();
-        const formHandle = (form?.querySelector('[name="handle"]') as HTMLInputElement | null)?.value?.trim();
+        const actionUrl =
+            provider.geocodeEndpoint || form?.action || window.location.href;
+        const fieldHandle = field
+            .getAttribute('data-formie-field-handle')
+            ?.trim();
+        const formHandle = (
+            form?.querySelector('[name="handle"]') as HTMLInputElement | null
+        )?.value?.trim();
 
         if (!formHandle || !fieldHandle) return;
 
@@ -356,14 +410,18 @@ export const googleAddressModule = defineAddressModule<
             formData.append('handle', formHandle);
             formData.append('fieldHandle', fieldHandle);
 
-            const response = await browserRequest(actionUrl, {
-                method: 'POST',
-                body: formData,
-                headers: {
-                    'X-Requested-With': 'XMLHttpRequest',
-                    Accept: 'application/json',
+            const response = await browserRequest(
+                actionUrl,
+                {
+                    method: 'POST',
+                    body: formData,
+                    headers: {
+                        'X-Requested-With': 'XMLHttpRequest',
+                        Accept: 'application/json',
+                    },
                 },
-            }, getFormBrowserRequestOptions(form));
+                getFormBrowserRequestOptions(form),
+            );
 
             const data = await response.json();
 

package/src/js/modules/address/place-kit.ts

@@ -58,13 +58,6 @@ export const placeKitModule = defineAddressModule<
         const picker = api(provider.apiKey, options as { target: HTMLInputElement });
 
         picker.on('pick', (value, item: PlaceKitItem) => {
-            field.dispatchEvent(
-                new CustomEvent(getAddressProviderEventName('place-kit', 'populate'), {
-                    bubbles: true,
-                    detail: { addressProvider: 'place-kit', addressComponents: item },
-                }),
-            );
-
             let address1 = '';
 
             if (item.street) {
@@ -87,6 +80,19 @@ export const placeKitModule = defineAddressModule<
             services.input.setValue('state', item.administrative || '');
             services.input.setValue('zip', typeof zip === 'string' ? zip : '');
             services.input.setValue('country', countryValue || item.country || '');
+
+            // Notify dependent state controls after all address values are applied.
+            // Keep the provider value available while country options are loading.
+            field.dispatchEvent(
+                new CustomEvent(getAddressProviderEventName('place-kit', 'populate'), {
+                    bubbles: true,
+                    detail: {
+                        addressProvider: 'place-kit',
+                        addressComponents: item,
+                        state: item.administrative || '',
+                    },
+                }),
+            );
         });
 
         return picker;