@verbb/formie-browser 1.0.4 → 1.0.6

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

@@ -0,0 +1,117 @@
+import { addThemeClasses } from '#theme/theme-classes';
+
+function appendDescribedBy(input: HTMLElement, describedById: string): void {
+    const current = (input.getAttribute('aria-describedby') || '').trim();
+    const items = current ? current.split(/\s+/) : [];
+
+    if (!items.includes(describedById)) {
+        items.push(describedById);
+    }
+
+    input.setAttribute('aria-describedby', items.join(' ').trim());
+}
+
+function getFirstErroredField(form: HTMLFormElement): HTMLElement | null {
+    const fields = Array.from(form.querySelectorAll('[data-formie-field-handle]')) as HTMLElement[];
+
+    return fields.find((field) => {
+        if (field.getAttribute('data-formie-field-has-error') === 'true') {
+            return true;
+        }
+
+        return field.querySelector('[data-formie-field-error]') !== null;
+    }) || null;
+}
+
+function getFieldFocusTarget(field: HTMLElement): HTMLElement | null {
+    const invalidControl = field.querySelector('[aria-invalid="true"]') as HTMLElement | null;
+
+    if (invalidControl) {
+        return invalidControl;
+    }
+
+    return field.querySelector(
+        'input:not([type="hidden"]):not([disabled]), select:not([disabled]), textarea:not([disabled])',
+    ) as HTMLElement | null;
+}
+
+function getFormLevelErrorTarget(form: HTMLFormElement): HTMLElement | null {
+    return form.querySelector(
+        '[data-formie-message-error], [data-formie-error-container], [data-formie-errors]',
+    ) as HTMLElement | null;
+}
+
+export function enhanceServerRenderedFieldErrors(form: HTMLFormElement): void {
+    form.querySelectorAll('[data-formie-field-handle]').forEach((fieldNode) => {
+        const field = fieldNode as HTMLElement;
+        const hasServerError = field.getAttribute('data-formie-field-has-error') === 'true'
+            || field.querySelector('[data-formie-field-error]') !== null;
+
+        if (!hasServerError) {
+            return;
+        }
+
+        field.setAttribute('data-formie-field-has-error', 'true');
+        addThemeClasses(field, form, 'fieldLayoutError');
+
+        const errorContainer = field.querySelector('[data-formie-field-errors]') as HTMLElement | null;
+        const errorContainerId = errorContainer?.id || '';
+        const primaryError = field.querySelector('[data-formie-field-error]') as HTMLElement | null;
+        const primaryErrorId = primaryError?.id || '';
+
+        field.querySelectorAll('input, select, textarea').forEach((input) => {
+            const element = input as HTMLElement;
+            element.setAttribute('aria-invalid', 'true');
+            addThemeClasses(element, form, 'fieldControlError');
+            element.setAttribute('data-formie-input-has-error', 'true');
+
+            if (errorContainerId) {
+                appendDescribedBy(element, errorContainerId);
+            }
+
+            if (primaryErrorId) {
+                element.setAttribute('aria-errormessage', primaryErrorId);
+            }
+        });
+    });
+}
+
+export function hasServerRenderedValidationErrors(form: HTMLFormElement): boolean {
+    return !!getFirstErroredField(form) || !!getFormLevelErrorTarget(form);
+}
+
+export function focusFirstValidationError(form: HTMLFormElement): boolean {
+    const field = getFirstErroredField(form);
+
+    if (field) {
+        const target = getFieldFocusTarget(field);
+
+        if (target) {
+            target.scrollIntoView({ behavior: 'smooth', block: 'center' });
+
+            if (typeof target.focus === 'function') {
+                try {
+                    target.focus({ preventScroll: true });
+                } catch {
+                    target.focus();
+                }
+            }
+
+            return true;
+        }
+
+        field.scrollIntoView({ behavior: 'smooth', block: 'center' });
+
+        return true;
+    }
+
+    const formError = getFormLevelErrorTarget(form);
+
+    if (!formError) {
+        return false;
+    }
+
+    formError.scrollIntoView({ behavior: 'smooth', block: 'center' });
+
+    return true;
+}

package/src/js/modules/address/api.ts

@@ -8,6 +8,13 @@ import type {
     AddressModuleOptions as AddressModuleManifestOptions,
 } from '#modules/address/host';
 
+export {
+    ADDRESS_LEGACY_SELECTORS,
+    ADDRESS_SELECTORS,
+    findAddressFieldInput,
+    type AddressFieldInputKey,
+} from '#modules/address/constants';
+
 // This file is the intended authoring surface for address providers.
 // Built-in providers import from here so third-party authors can follow the same patterns.
 export const defineAddressModule = createManagedAddressModule;

package/src/js/modules/address/constants.ts

@@ -2,7 +2,21 @@
 export const DEFAULT_AUTOCOMPLETE_SELECTOR = '[data-formie-address-autocomplete-input]';
 export const ADDRESS_LOCATION_SELECTOR = '[data-formie-address-location]';
 
-/** Selector for address sub-field inputs used when populating from provider. */
+/** Keys for address sub-field inputs targeted by provider modules. */
+export type AddressFieldInputKey =
+    | 'autoComplete'
+    | 'address1'
+    | 'address2'
+    | 'address3'
+    | 'city'
+    | 'state'
+    | 'zip'
+    | 'country';
+
+/**
+ * Canonical address sub-field selectors (PHP output, UI reference, provider modules).
+ * All address-owned runtime hooks use the `data-formie-address-*` namespace.
+ */
 export const ADDRESS_SELECTORS = {
     autoComplete: '[data-formie-address-autocomplete-input]',
     address1: '[data-formie-address-line1-input]',
@@ -12,4 +26,70 @@ export const ADDRESS_SELECTORS = {
     state: '[data-formie-address-state-input]',
     zip: '[data-formie-address-zip-input]',
     country: '[data-formie-address-country-input]',
-} as const;
+} as const satisfies Record<AddressFieldInputKey, string>;
+
+/**
+ * Legacy bare hooks still present on forms saved before the selector normalization.
+ * `findAddressFieldInput()` checks canonical selectors first, then these.
+ */
+export const ADDRESS_LEGACY_SELECTORS = {
+    autoComplete: '[data-formie-address-autocomplete-input]',
+    address1: '[data-address1]',
+    address2: '[data-address2]',
+    address3: '[data-address3]',
+    city: '[data-city]',
+    state: '[data-state]',
+    zip: '[data-zip]',
+    country: '[data-country]',
+} as const satisfies Record<AddressFieldInputKey, string>;
+
+const ADDRESS_FIELD_INPUT_SELECTOR_ORDER: Record<AddressFieldInputKey, readonly string[]> = {
+    autoComplete: [
+        ADDRESS_SELECTORS.autoComplete,
+        ADDRESS_LEGACY_SELECTORS.autoComplete,
+    ],
+    address1: [
+        ADDRESS_SELECTORS.address1,
+        ADDRESS_LEGACY_SELECTORS.address1,
+    ],
+    address2: [
+        ADDRESS_SELECTORS.address2,
+        ADDRESS_LEGACY_SELECTORS.address2,
+    ],
+    address3: [
+        ADDRESS_SELECTORS.address3,
+        ADDRESS_LEGACY_SELECTORS.address3,
+    ],
+    city: [
+        ADDRESS_SELECTORS.city,
+        ADDRESS_LEGACY_SELECTORS.city,
+    ],
+    state: [
+        ADDRESS_SELECTORS.state,
+        ADDRESS_LEGACY_SELECTORS.state,
+    ],
+    zip: [
+        ADDRESS_SELECTORS.zip,
+        ADDRESS_LEGACY_SELECTORS.zip,
+    ],
+    country: [
+        ADDRESS_SELECTORS.country,
+        ADDRESS_LEGACY_SELECTORS.country,
+    ],
+};
+
+/** Resolve an address sub-field input against canonical and legacy selectors. */
+export function findAddressFieldInput(
+    scope: ParentNode,
+    key: AddressFieldInputKey,
+): HTMLInputElement | HTMLSelectElement | null {
+    for (const selector of ADDRESS_FIELD_INPUT_SELECTOR_ORDER[key]) {
+        const candidate = scope.querySelector(selector);
+
+        if (candidate instanceof HTMLInputElement || candidate instanceof HTMLSelectElement) {
+            return candidate;
+        }
+    }
+
+    return null;
+}

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

@@ -1,8 +1,9 @@
 import type { ModuleSetupContext } from '#contracts/modules';
 import {
     ADDRESS_LOCATION_SELECTOR,
-    ADDRESS_SELECTORS,
     DEFAULT_AUTOCOMPLETE_SELECTOR,
+    findAddressFieldInput,
+    type AddressFieldInputKey,
 } from '#modules/address/constants';
 
 type Cleanup = () => void;
@@ -24,7 +25,7 @@ export type AddressHostServices = {
     form: HTMLFormElement | null;
     input: {
         getAutocomplete: () => HTMLInputElement | null;
-        setValue: (selector: keyof typeof ADDRESS_SELECTORS, value: string, fallback?: string) => void;
+        setValue: (selector: AddressFieldInputKey, value: string, fallback?: string) => void;
     };
     location: {
         getButton: () => HTMLElement | null;
@@ -90,12 +91,21 @@ export function createAddressHostServices(
                 return field.querySelector(autocompleteSelector) as HTMLInputElement | null;
             },
             setValue: (selectorKey, value, fallback) => {
-                const selector = ADDRESS_SELECTORS[selectorKey];
-                const el = field.querySelector(selector) as HTMLInputElement | null;
+                const el = findAddressFieldInput(field, selectorKey);
 
-                if (el) {
-                    el.value = value || fallback || '';
+                if (!el) {
+                    return;
                 }
+
+                const nextValue = value || fallback || '';
+
+                if (el.value === nextValue) {
+                    return;
+                }
+
+                el.value = nextValue;
+                el.dispatchEvent(new Event('input', { bubbles: true }));
+                el.dispatchEvent(new Event('change', { bubbles: true }));
             },
         },
         location: {

package/src/js/modules/address/loqate.ts

@@ -1,5 +1,5 @@
 import { defineAddressModule } from '#modules/address/api';
-import { ADDRESS_SELECTORS } from '#modules/address/constants';
+import { findAddressFieldInput, type AddressFieldInputKey } from '#modules/address/constants';
 import { loadScriptAndEnsureGlobal } from '#utils/scripts';
 
 type PcaFieldMode = {
@@ -63,27 +63,13 @@ export const loqateModule = defineAddressModule<
             throw new Error('Loqate API key is required');
         }
 
-        const handleToSelector: Record<string, string> = {
-            autoComplete: ADDRESS_SELECTORS.autoComplete,
-            address1: ADDRESS_SELECTORS.address1,
-            address2: ADDRESS_SELECTORS.address2,
-            address3: ADDRESS_SELECTORS.address3,
-            city: ADDRESS_SELECTORS.city,
-            state: ADDRESS_SELECTORS.state,
-            zip: ADDRESS_SELECTORS.zip,
-            country: ADDRESS_SELECTORS.country,
-        };
-
         // Loqate PCA expects element to be an id string, name string, or RegExp matching ids – not CSS selectors
-        const getLoqateElementRef = (handle: string): string => {
+        const getLoqateElementRef = (handle: AddressFieldInputKey): string => {
             if (namespace) {
                 return `${namespace}[${handle}]`;
             }
 
-            const cssSelector = handleToSelector[handle];
-            const el = cssSelector
-                ? (field.querySelector(cssSelector) as HTMLInputElement | null)
-                : null;
+            const el = findAddressFieldInput(field, handle);
 
             if (el?.name) {
                 return el.name;

package/src/js/modules/fields/address-country.ts

@@ -0,0 +1,156 @@
+import type { FormieModuleDefinition } from '#contracts/modules';
+import { ADDRESS_SELECTORS, findAddressFieldInput } from '#modules/address/constants';
+import { getModuleFieldContainers } from '#modules/fields/shared';
+import { fetchCountryFromIp } from '#utils/country-from-ip';
+import { createDebug } from '#utils/debug';
+
+const MODULE_ID = 'address-country';
+const COUNTRY_SELECTOR = ADDRESS_SELECTORS.country;
+const debug = createDebug('fields', 'address-country');
+
+type ComboboxSelect = HTMLSelectElement & {
+    _formieTomSelect?: {
+        setValue: (value: string, silent?: boolean) => void;
+    };
+};
+
+type AddressCountryOptions = {
+    countryPreselectFromIp?: boolean;
+    countryAllowed?: string[];
+    countryOptionValue?: 'short' | 'full';
+    countryFromIpAction?: string;
+};
+
+function resolveCountrySelectValue(
+    countryCode: string,
+    countryName: string | null | undefined,
+    optionValue: 'short' | 'full',
+): string {
+    if (optionValue === 'full' && countryName) {
+        return countryName;
+    }
+
+    return countryCode.toUpperCase();
+}
+
+function isCountryAllowed(countryCode: string, countryAllowed: string[] = []): boolean {
+    if (!countryAllowed.length) {
+        return true;
+    }
+
+    const upperCode = countryCode.toUpperCase();
+
+    return countryAllowed.some((allowed) => allowed.toUpperCase() === upperCode);
+}
+
+function optionExists(select: HTMLSelectElement, value: string): boolean {
+    return Array.from(select.options).some((option) => option.value === value);
+}
+
+async function setCountrySelectValue(select: HTMLSelectElement, value: string): Promise<void> {
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+        const combobox = (select as ComboboxSelect)._formieTomSelect;
+
+        if (combobox || !select.hasAttribute('data-formie-combobox-input')) {
+            if (combobox) {
+                combobox.setValue(value, true);
+            } else {
+                select.value = value;
+            }
+
+            select.dispatchEvent(new Event('change', { bubbles: true }));
+            return;
+        }
+
+        await new Promise((resolve) => {
+            window.setTimeout(resolve, 50);
+        });
+    }
+
+    debug.warn('Timed out waiting for country combobox initialisation.');
+}
+
+async function preselectCountry(
+    addressRoot: HTMLElement,
+    options: AddressCountryOptions,
+): Promise<void> {
+    const countryControl = findAddressFieldInput(addressRoot, 'country');
+
+    if (!(countryControl instanceof HTMLSelectElement)) {
+        debug.warn('Country control not found or not a select; skipping preselect.');
+        return;
+    }
+
+    if (countryControl.value.trim()) {
+        return;
+    }
+
+    const response = await fetchCountryFromIp(options.countryFromIpAction);
+
+    if (!response?.countryCode) {
+        return;
+    }
+
+    if (!isCountryAllowed(response.countryCode, options.countryAllowed)) {
+        debug.log('Detected country is not in the allowed list; skipping preselect.', {
+            countryCode: response.countryCode,
+        });
+        return;
+    }
+
+    const optionValue = options.countryOptionValue === 'full' ? 'full' : 'short';
+    const selectValue = resolveCountrySelectValue(
+        response.countryCode,
+        response.countryName,
+        optionValue,
+    );
+
+    if (!optionExists(countryControl, selectValue)) {
+        debug.warn('Detected country is not available in the country dropdown; skipping preselect.', {
+            selectValue,
+        });
+        return;
+    }
+
+    await setCountrySelectValue(countryControl, selectValue);
+    debug.log('Preselected country from IP.', { selectValue });
+}
+
+export const addressCountryModule: FormieModuleDefinition = {
+    id: MODULE_ID,
+    kind: 'field',
+    match: (ctx) => {
+        return !!ctx.target.querySelector(COUNTRY_SELECTOR);
+    },
+    setup: async (ctx) => {
+        const options = (ctx.options || {}) as AddressCountryOptions;
+
+        if (!options.countryPreselectFromIp) {
+            return {
+                destroy: () => {},
+            };
+        }
+
+        const fields = getModuleFieldContainers(ctx);
+        const tasks = fields.map(async (field) => {
+            const addressRoot = field.closest('[data-formie-field-type="address"]')
+                || field.closest('[data-formie-address-field-layout]')?.closest('[data-formie-field]')
+                || field;
+
+            if (!(addressRoot instanceof HTMLElement)) {
+                return;
+            }
+
+            await preselectCountry(addressRoot, options);
+        });
+
+        await Promise.all(tasks);
+        debug.log('Module setup.', { fieldCount: fields.length });
+
+        return {
+            destroy: () => {
+                debug.log('Module destroy.', { fieldCount: fields.length });
+            },
+        };
+    },
+};