@verbb/formie-browser 1.0.3 → 1.0.5

package/src/css/theme/fields/_combobox.css

@@ -0,0 +1,246 @@
+/*
+ * Combobox styles are intentionally unlayered. The combobox module injects this
+ * sheet at runtime, and unlayered third-party CSS would otherwise win over
+ * @layer formie-theme rules.
+ *
+ * Tom Select default CSS is not imported; these rules provide the minimum
+ * structure plus Formie theme styling for searchable dropdowns.
+ */
+
+.formie-field .ts-wrapper.formie-combobox {
+    width: 100%;
+    display: block;
+    position: relative;
+    min-height: 0;
+    border: 0;
+    padding: 0;
+    background: none;
+    box-shadow: none;
+}
+
+.formie-field select[data-formie-combobox-input].tomselected,
+.formie-field select[data-formie-combobox-input].ts-hidden-accessible {
+    display: none !important;
+}
+
+.formie-field .ts-wrapper.formie-combobox .ts-control {
+    box-sizing: border-box;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    position: relative;
+    overflow: hidden;
+    z-index: 1;
+    width: 100%;
+    border: var(--formie-border-width) solid var(--formie-color-border);
+    border-radius: var(--formie-radius-sm);
+    background-color: var(--formie-color-surface);
+    background-image: none;
+    min-height: var(--formie-control-height);
+    padding: calc(var(--formie-control-padding-y) - 1px) var(--formie-control-padding-x);
+    box-shadow: none;
+    font-size: var(--formie-control-font-size);
+    line-height: var(--formie-line-height-tight);
+    color: var(--formie-color-text);
+    transition: border-color 150ms ease, box-shadow 150ms ease, background-color 150ms ease;
+    gap: var(--formie-space-1);
+}
+
+.formie-field .ts-wrapper.formie-combobox.single .ts-control {
+    --ts-pr-min: var(--formie-control-padding-x);
+    --ts-pr-caret: calc(var(--formie-select-indicator-size) + var(--formie-space-1));
+    padding-right: calc(var(--formie-control-padding-x) + var(--formie-select-indicator-size) + var(--formie-space-2)) !important;
+    background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20' fill='none'%3E%3Cpath d='M7 7l3-3 3 3m0 6l-3 3-3-3' stroke='%239CA3AF' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
+    background-position: right var(--formie-space-2) center;
+    background-repeat: no-repeat;
+    background-size: var(--formie-select-indicator-size) var(--formie-select-indicator-size);
+}
+
+.formie-field .ts-wrapper.formie-combobox.single .ts-control::after {
+    display: none;
+}
+
+.formie-field .ts-wrapper.formie-combobox.multi .ts-control {
+    padding: calc(var(--formie-control-padding-y) - 2px) var(--formie-control-padding-x) calc(var(--formie-control-padding-y) - 4px);
+    --ts-pr-min: var(--formie-control-padding-x);
+}
+
+.formie-field .ts-wrapper.formie-combobox.multi.has-items .ts-control {
+    padding-left: var(--formie-control-padding-x);
+}
+
+.formie-field .ts-wrapper.formie-combobox .ts-control > input {
+    flex: 1 1 auto;
+    min-width: 7rem;
+    max-width: 100%;
+    margin: 0 !important;
+    padding: 0 !important;
+    min-height: 0 !important;
+    max-height: none !important;
+    border: 0 !important;
+    background: none !important;
+    box-shadow: none !important;
+    color: var(--formie-color-text);
+    font: inherit;
+    font-size: var(--formie-control-font-size);
+    line-height: inherit;
+}
+
+.formie-field .ts-wrapper.formie-combobox .ts-control > input:focus {
+    outline: none !important;
+}
+
+.formie-field .ts-wrapper.formie-combobox.has-items .ts-control > input {
+    margin: 0 var(--formie-space-1) !important;
+}
+
+.formie-field .ts-wrapper.formie-combobox.input-hidden .ts-control > input {
+    opacity: 0;
+    position: absolute;
+    left: -10000px;
+}
+
+.formie-field .ts-wrapper.formie-combobox.single .ts-control,
+.formie-field .ts-wrapper.formie-combobox.single .ts-control > input {
+    cursor: pointer;
+}
+
+.formie-field .ts-wrapper.formie-combobox.single.input-active .ts-control,
+.formie-field .ts-wrapper.formie-combobox.single.input-active .ts-control > input {
+    cursor: text;
+}
+
+.formie-field .ts-wrapper.formie-combobox .ts-control .items-placeholder {
+    color: var(--formie-color-text-muted);
+    font: inherit;
+    font-size: var(--formie-control-font-size);
+}
+
+.formie-field .ts-wrapper.formie-combobox .ts-control > input::placeholder {
+    color: var(--formie-color-text-muted);
+}
+
+.formie-field .ts-wrapper.formie-combobox.focus .ts-control,
+.formie-field .ts-wrapper.formie-combobox .ts-control:focus-within,
+.formie-field .ts-wrapper.formie-combobox.dropdown-active .ts-control {
+    outline: 0;
+    border-color: var(--formie-color-focus-ring);
+    box-shadow: var(--formie-shadow-focus);
+    border-radius: var(--formie-radius-sm);
+}
+
+.formie-field-has-error .ts-wrapper.formie-combobox .ts-control {
+    border-color: var(--formie-color-danger);
+}
+
+.formie-field-has-error .ts-wrapper.formie-combobox.focus .ts-control,
+.formie-field-has-error .ts-wrapper.formie-combobox .ts-control:focus-within,
+.formie-field-has-error .ts-wrapper.formie-combobox.dropdown-active .ts-control {
+    border-color: var(--formie-color-danger);
+    box-shadow: var(--formie-shadow-danger-focus);
+}
+
+.formie-field .ts-wrapper.formie-combobox.multi .ts-control > .item,
+.formie-field .ts-wrapper.formie-combobox.multi .ts-control [data-value] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--formie-space-1);
+    margin: 0 var(--formie-space-1) var(--formie-space-1) 0;
+    padding: 0 var(--formie-space-2);
+    background: var(--formie-color-surface-muted, rgba(15, 23, 42, 0.06));
+    background-image: none;
+    border: var(--formie-border-width) solid var(--formie-color-border);
+    border-radius: var(--formie-radius-sm);
+    box-shadow: none;
+    color: var(--formie-color-text);
+    text-shadow: none;
+    line-height: calc(var(--formie-control-height) - var(--formie-space-3));
+}
+
+.formie-field .ts-wrapper.formie-combobox.multi .ts-control > .item.active,
+.formie-field .ts-wrapper.formie-combobox.multi .ts-control [data-value].active {
+    background: var(--formie-color-surface-muted, rgba(15, 23, 42, 0.06));
+    color: var(--formie-color-text);
+}
+
+.formie-field .ts-wrapper.formie-combobox.plugin-remove_button .item {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--formie-space-1);
+}
+
+.formie-field .ts-wrapper.formie-combobox.plugin-remove_button:not(.rtl) .item {
+    padding-right: var(--formie-space-2) !important;
+}
+
+.formie-field .ts-wrapper.formie-combobox.plugin-remove_button .item .remove {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    margin: 0;
+    padding: 0;
+    border: 0;
+    background: none;
+    box-shadow: none;
+    text-decoration: none;
+    color: var(--formie-color-text-muted);
+    font-size: 1.125em;
+    line-height: 1;
+    cursor: pointer;
+}
+
+.formie-field .ts-wrapper.formie-combobox.plugin-remove_button .item .remove:hover,
+.formie-field .ts-wrapper.formie-combobox.plugin-remove_button .item .remove:focus {
+    background: none;
+    text-decoration: none;
+    color: var(--formie-color-text);
+}
+
+.formie-field .ts-wrapper.formie-combobox .ts-dropdown {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    width: 100%;
+    z-index: var(--formie-z-popover, 30);
+    border: var(--formie-border-width) solid var(--formie-color-border);
+    border-radius: var(--formie-radius-sm);
+    background: var(--formie-color-surface);
+    box-shadow: var(--formie-shadow-popover, 0 8px 24px rgba(15, 23, 42, 0.12));
+    margin-top: var(--formie-space-1);
+    box-sizing: border-box;
+}
+
+.formie-field .ts-wrapper.formie-combobox .ts-dropdown-content {
+    overflow: hidden auto;
+    max-height: 200px;
+    scroll-behavior: smooth;
+}
+
+.formie-field .ts-wrapper.formie-combobox .ts-dropdown .option,
+.formie-field .ts-wrapper.formie-combobox .ts-dropdown .optgroup-header,
+.formie-field .ts-wrapper.formie-combobox .ts-dropdown .no-results {
+    color: var(--formie-color-text);
+    padding: var(--formie-space-2) var(--formie-control-padding-x);
+}
+
+.formie-field .ts-wrapper.formie-combobox .ts-dropdown [data-selectable] {
+    cursor: pointer;
+}
+
+.formie-field .ts-wrapper.formie-combobox .ts-dropdown .option.active,
+.formie-field .ts-wrapper.formie-combobox .ts-dropdown .option:hover,
+.formie-field .ts-wrapper.formie-combobox .ts-dropdown .active {
+    background: var(--formie-color-surface-muted, rgba(15, 23, 42, 0.05));
+    color: var(--formie-color-text);
+}
+
+.formie-field .ts-wrapper.formie-combobox .ts-dropdown .highlight {
+    background: rgba(59, 130, 246, 0.18);
+    border-radius: 2px;
+}
+
+.formie-field .ts-wrapper.formie-combobox.disabled .ts-control {
+    opacity: 0.6;
+    background-color: var(--formie-color-surface-muted, rgba(15, 23, 42, 0.04));
+    cursor: not-allowed;
+}

package/src/css/theme/fields/_select.css

@@ -34,4 +34,17 @@
         border-color: var(--formie-color-danger);
         box-shadow: var(--formie-shadow-danger-focus);
     }
+
+    /* Tom Select copies native select classes onto its wrapper; keep combobox chrome on .ts-control only. */
+    .formie-field .ts-wrapper.formie-combobox,
+    .formie-field .ts-wrapper.formie-combobox.formie-select,
+    .formie-field .ts-wrapper.formie-combobox.formie-dropdown-input {
+        border: 0;
+        padding: 0;
+        min-height: 0;
+        background: none;
+        background-image: none;
+        box-shadow: none;
+        appearance: none;
+    }
 }

package/src/js/core/create-formie-client.ts

@@ -13,6 +13,11 @@ import type { ThemeClassMap } from '#contracts/theme';
 import { dispatchFormieDomEvent } from '#core/dom-events';
 import { dispatchPageClientEventForSubmit } from '#core/page-client-event';
 import { syncPageTabErrors } from '#core/page-tab-errors';
+import {
+    enhanceServerRenderedFieldErrors,
+    focusFirstValidationError,
+    hasServerRenderedValidationErrors,
+} from '#core/validation-focus';
 import { clearSubmitFeedback, executeAjaxSubmitFlow, shouldKeepSubmitLoading } from '#core/submit-flow';
 import { applySubmitResultUi } from '#core/submit-result-ui';
 import { applyPageState, clearSubmitLoading, setSubmitLoading } from '#core/submit-result-state';
@@ -24,6 +29,7 @@ import { runSubmitPipeline } from '#submit/pipeline';
 import { clearSubmissionOnUnload, requestGraphqlRender, requestRefreshTokens, requestRender, requestSetPage } from '#transport/forms-api';
 import { createDebug } from '#utils/debug';
 import { createFormUnloadWarningGuard } from '#utils/unload-warning';
+import { getValidationScope } from '#validation/scope';
 import { FormieValidator } from '#validation/validator';
 import { bindSubmitReadiness } from '#validation/submit-readiness';
 
@@ -745,6 +751,22 @@ function bindFormEvents(
                         allowNativeSubmit = false;
                         clearInternalNavigation(form);
                         clearSubmitLoading(form);
+
+                        if (validator && shouldValidateOnSubmit(form)) {
+                            const { scope, final } = getValidationScope(form);
+                            const validationErrors = validator.submit(final ? form : scope, { final });
+
+                            if (validationErrors.length > 0) {
+                                applySubmitResultUi(form, {
+                                    ok: false,
+                                    stage: 'validate',
+                                    code: 'VALIDATION_FAILED',
+                                    message: validator.config.errorMessage || 'Validation failed.',
+                                    fieldErrors: validator.getFieldErrors(validationErrors),
+                                    formErrors: [validator.config.errorMessage || 'Validation failed.'],
+                                });
+                            }
+                        }
                     };
 
                     if (typeof form.requestSubmit === 'function') {
@@ -996,6 +1018,11 @@ export function createFormieClient(): FormieClient {
                 normalizeHeadlessManagedUrls(target, form, normalizedOptions);
             }
 
+            if (normalizedOptions.mode === 'server-rendered' && hasServerRenderedValidationErrors(form)) {
+                enhanceServerRenderedFieldErrors(form);
+                focusFirstValidationError(form);
+            }
+
             syncPageTabErrors(form);
         }
 

package/src/js/core/field-error-container.ts

@@ -0,0 +1,39 @@
+export type FieldErrorPosition = 'above' | 'below';
+
+export function getFieldErrorPosition(fieldNode: Element): FieldErrorPosition {
+    const layout = fieldNode.querySelector('[data-formie-field-layout]');
+    const position = layout?.getAttribute('data-formie-error-position')?.trim();
+
+    return position === 'above' ? 'above' : 'below';
+}
+
+export function ensureFieldErrorContainer(
+    fieldNode: Element,
+    applyTheme?: (container: HTMLElement) => void,
+): HTMLElement {
+    const existing = fieldNode.querySelector('[data-formie-field-errors]') as HTMLElement | null;
+
+    if (existing) {
+        return existing;
+    }
+
+    const content = fieldNode.querySelector('[data-formie-field-content]') as HTMLElement | null;
+    const control = fieldNode.querySelector('[data-formie-field-control]') as HTMLElement | null;
+    const position = getFieldErrorPosition(fieldNode);
+    const container = document.createElement('div');
+
+    container.setAttribute('data-formie-field-errors', 'true');
+    applyTheme?.(container);
+
+    if (content && control) {
+        if (position === 'above') {
+            content.insertBefore(container, control);
+        } else {
+            content.appendChild(container);
+        }
+    } else {
+        fieldNode.appendChild(container);
+    }
+
+    return container;
+}

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

@@ -102,6 +102,16 @@ function getConfiguredSubmitAction(form: HTMLFormElement): string {
     return (form.dataset.formieSubmitAction || '').trim();
 }
 
+function getResolvedSubmitAction(form: HTMLFormElement, result: FormSubmitResult): string {
+    const fromResponse = result.meta?.effectiveSubmitAction;
+
+    if (typeof fromResponse === 'string' && fromResponse.trim() !== '') {
+        return fromResponse.trim();
+    }
+
+    return getConfiguredSubmitAction(form);
+}
+
 function shouldHideFormOnSuccess(form: HTMLFormElement): boolean {
     const rawValue = form.dataset.formieSubmitActionFormHide;
 
@@ -580,7 +590,7 @@ export function applySubmitResultState(form: HTMLFormElement, result: FormSubmit
     }
 
     if (action === 'submit' && !result.redirect?.url) {
-        const configuredSubmitAction = getConfiguredSubmitAction(form);
+        const configuredSubmitAction = getResolvedSubmitAction(form, result);
         const preserveHiddenState = configuredSubmitAction === 'message' && shouldHideFormOnSuccess(form);
 
         if (configuredSubmitAction === 'reload') {
@@ -603,7 +613,7 @@ export function applySubmitResultState(form: HTMLFormElement, result: FormSubmit
     }
 
     if (action === 'submit' && result.redirect?.url && result.redirect.target === 'new-tab') {
-        const configuredSubmitAction = getConfiguredSubmitAction(form);
+        const configuredSubmitAction = getResolvedSubmitAction(form, result);
         const preserveHiddenState = configuredSubmitAction === 'message' && shouldHideFormOnSuccess(form);
         clearPendingFinalSubmitReset(form);
         resetSubmissionState(form, { preserveHiddenState });

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

@@ -1,5 +1,7 @@
 import type { FormSubmitResult } from '#contracts/schema';
+import { ensureFieldErrorContainer as resolveFieldErrorContainer } from '#core/field-error-container';
 import { syncPageTabErrors } from '#core/page-tab-errors';
+import { focusFirstValidationError } from '#core/validation-focus';
 import { setFormHiddenState } from '#core/submit-result-state';
 import { addThemeClasses, removeThemeClasses } from '#theme/theme-classes';
 
@@ -150,16 +152,9 @@ function ensureFormSuccessContainer(form: HTMLFormElement, position: string): HT
 }
 
 function ensureFieldErrorContainer(fieldNode: Element): HTMLElement {
-    let container = fieldNode.querySelector('[data-formie-field-errors]') as HTMLElement | null;
-
-    if (!container) {
-        container = document.createElement('div');
-        container.setAttribute('data-formie-field-errors', 'true');
+    return resolveFieldErrorContainer(fieldNode, (container) => {
         addThemeClasses(container, fieldNode, 'fieldErrors');
-        fieldNode.appendChild(container);
-    }
-
-    return container;
+    });
 }
 
 function removeDescribedBy(input: HTMLElement, describedById: string): void {
@@ -439,10 +434,9 @@ export function applySubmitResultUi(form: HTMLFormElement, result: FormSubmitRes
 
     if (result.formErrors?.length) {
         renderFormErrors(form, result.formErrors);
-        return;
-    }
-
-    if (!result.fieldErrors && result.message) {
+    } else if (!result.fieldErrors && result.message) {
         renderFormErrors(form, [result.message]);
     }
+
+    focusFirstValidationError(form);
 }

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;
+}