@verbb/formie-browser 1.0.0

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

@@ -0,0 +1,128 @@
+import { defineAddressModule } from '#modules/address/api';
+import { ADDRESS_SELECTORS } from '#modules/address/constants';
+import { loadScriptAndEnsureGlobal } from '#utils/scripts';
+
+type PcaFieldMode = {
+    SEARCH: number;
+    POPULATE: number;
+    COUNTRY: number;
+};
+
+type PcaAddressInstance = {
+    load?: () => void;
+};
+
+type PcaAddress = new (
+    fields: Array<{ element: string; field: string; mode: number }>,
+    options: Record<string, unknown>,
+) => PcaAddressInstance;
+
+type PcaGlobal = {
+    fieldMode: PcaFieldMode;
+    Address: PcaAddress;
+};
+
+type LoqateProviderOptions = {
+    apiKey?: string;
+    namespace?: string;
+    reconfigurableOptions?: Record<string, unknown>;
+};
+
+const SCRIPT_ID = 'FORMIE_LOQATE_SCRIPT';
+
+export const loqateModule = defineAddressModule<
+    LoqateProviderOptions,
+    PcaGlobal,
+    PcaAddressInstance
+>({
+    id: 'loqate',
+    load: async () => {
+        await loadScriptAndEnsureGlobal<PcaGlobal>('pca', {
+            id: SCRIPT_ID,
+            src: 'https://services.pcapredict.com/js/address-3.91.min.js',
+            async: true,
+            defer: true,
+        });
+
+        const link = document.createElement('link');
+        link.href = 'https://services.pcapredict.com/css/address-3.91.min.css';
+        link.rel = 'stylesheet';
+        link.type = 'text/css';
+
+        if (!document.querySelector(`link[href="${link.href}"]`)) {
+            document.body.appendChild(link);
+        }
+
+        return (window as unknown as { pca: PcaGlobal }).pca;
+    },
+    mount: ({ api, field, services, provider }) => {
+        const namespace = provider.namespace || '';
+        const apiKey = provider.apiKey || '';
+
+        if (!apiKey) {
+            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 => {
+            if (namespace) {
+                return `${namespace}[${handle}]`;
+            }
+
+            const cssSelector = handleToSelector[handle];
+            const el = cssSelector
+                ? (field.querySelector(cssSelector) as HTMLInputElement | null)
+                : null;
+
+            if (el?.name) {
+                return el.name;
+            }
+
+            if (el?.id) {
+                return el.id;
+            }
+
+            return '';
+        };
+
+        const autoCompleteRef = getLoqateElementRef('autoComplete');
+
+        if (!autoCompleteRef) {
+            throw new Error('Loqate: could not find autocomplete input within address field');
+        }
+
+        const fields = [
+            { element: autoCompleteRef, field: '', mode: api.fieldMode.SEARCH },
+            { element: getLoqateElementRef('address1'), field: 'Line1', mode: api.fieldMode.POPULATE },
+            { element: getLoqateElementRef('address2'), field: 'Line2', mode: api.fieldMode.POPULATE },
+            { element: getLoqateElementRef('address3'), field: 'Line3', mode: api.fieldMode.POPULATE },
+            { element: getLoqateElementRef('city'), field: 'City', mode: api.fieldMode.POPULATE },
+            { element: getLoqateElementRef('state'), field: 'Province', mode: api.fieldMode.POPULATE },
+            { element: getLoqateElementRef('zip'), field: 'PostalCode', mode: api.fieldMode.POPULATE },
+            { element: getLoqateElementRef('country'), field: 'CountryName', mode: api.fieldMode.COUNTRY },
+        ].filter((f) => f.element);
+
+        const control = new api.Address(fields, {
+            key: apiKey,
+            simulateReactEvents: true,
+            ...(provider.reconfigurableOptions || {}),
+        });
+
+        if (typeof control.load === 'function') {
+            control.load();
+        }
+
+        return control;
+    },
+});

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

@@ -0,0 +1,94 @@
+import placeKitCss from '@placekit/autocomplete-js/dist/placekit-autocomplete.css?inline';
+import { defineAddressModule } from '#modules/address/api';
+import { ensureModuleStyles } from '#modules/styles';
+import { getAddressProviderEventName } from '#utils/event-names';
+
+ensureModuleStyles('place-kit', [placeKitCss]);
+
+type PlaceKitPicker = {
+    on: (event: string, callback: (value: unknown, item: PlaceKitItem) => void) => void;
+};
+
+type PlaceKitItem = {
+    street?: { number?: string; name?: string; suffix?: string };
+    city?: string;
+    administrative?: string;
+    zipcode?: string | string[];
+    country?: string;
+    countrycode?: string;
+};
+
+type PlaceKitProviderOptions = {
+    apiKey?: string;
+    options?: Record<string, unknown>;
+};
+
+export const placeKitModule = defineAddressModule<
+    PlaceKitProviderOptions,
+    (apiKey: string, options: Record<string, unknown>) => PlaceKitPicker,
+    PlaceKitPicker
+>({
+    id: 'place-kit',
+    load: async () => {
+        const module = await import('@placekit/autocomplete-js');
+
+        const placekitAutocomplete = module.default;
+
+        return (apiKey: string, options: Record<string, unknown>) => {
+            return placekitAutocomplete(apiKey, options as Parameters<typeof placekitAutocomplete>[1]) as PlaceKitPicker;
+        };
+    },
+    mount: async ({ api, field, services, provider }) => {
+        const input = services.input.getAutocomplete();
+
+        if (!input || !provider.apiKey) {
+            throw new Error('PlaceKit API key is required');
+        }
+
+        const options = { target: input as HTMLInputElement, ...(provider.options || {}) };
+
+        field.dispatchEvent(
+            new CustomEvent(getAddressProviderEventName('place-kit', 'before-init'), {
+                bubbles: true,
+                detail: { addressProvider: 'place-kit', options },
+            }),
+        );
+
+        // PlaceKit's PKAOptions requires target; we provide it.
+        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) {
+                const num = item.street.number ?? '';
+                const name = item.street.name ?? '';
+                const suffix = item.street.suffix ?? '';
+
+                address1 = [num, name, suffix].filter(Boolean).join(' ');
+            }
+
+            const zip = Array.isArray(item.zipcode) ? item.zipcode[0] : item.zipcode;
+
+            // Country: prefer countrycode (uppercase) for select values, else full name
+            const countryValue = item.countrycode
+                ? (item.countrycode as string).toUpperCase()
+                : (item.country || '');
+
+            services.input.setValue('address1', address1);
+            services.input.setValue('city', item.city || '');
+            services.input.setValue('state', item.administrative || '');
+            services.input.setValue('zip', typeof zip === 'string' ? zip : '');
+            services.input.setValue('country', countryValue || item.country || '');
+        });
+
+        return picker;
+    },
+});

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

@@ -0,0 +1,25 @@
+import {
+    createManagedCaptchaModule,
+    createPassiveCaptchaModule,
+    type CaptchaModuleSetupContext,
+    type ManagedCaptchaModuleAdapter,
+} from '#modules/captchas/factories';
+import type {
+    CaptchaHostServices,
+    CaptchaModuleOptions as CaptchaModuleManifestOptions,
+} from '#modules/captchas/host';
+
+// This file is the intended authoring surface for captcha providers.
+// Built-in providers import from here so third-party authors can follow the
+// same patterns we use internally.
+export const defineCaptchaModule = createManagedCaptchaModule;
+export const definePassiveCaptchaModule = createPassiveCaptchaModule;
+
+export type CaptchaServices = CaptchaHostServices;
+export type CaptchaModuleContext<TProvider extends Record<string, unknown>> = CaptchaModuleSetupContext<TProvider>;
+export type CaptchaModuleOptions<TProvider extends Record<string, unknown>> = CaptchaModuleManifestOptions<TProvider>;
+export type CaptchaProviderModule<
+    TProvider extends Record<string, unknown>,
+    TApi,
+    TWidget,
+> = ManagedCaptchaModuleAdapter<TProvider, TApi, TWidget>;

package/src/js/modules/captchas/captcha-eu.ts

@@ -0,0 +1,86 @@
+import { defineCaptchaModule } from '#modules/captchas/api';
+import { CAPTCHA_PROVIDER_LOAD_TIMEOUT_MS } from '#modules/captchas/constants';
+import { loadScriptAndEnsureGlobal } from '#utils/scripts';
+
+// Captcha.eu has its own widget/global shape, so keep the typed surface local
+// to this provider rather than teaching shared captcha services about it.
+type CaptchaEuGlobal = {
+    init: () => void;
+    setup: (publicKey: string) => void;
+    WidgetV2: {
+        render: (container: HTMLElement) => void;
+    };
+    on: (eventName: string, callback: (event: CustomEvent<unknown>) => void, container?: HTMLElement) => void;
+};
+
+// Only Captcha.eu-specific settings belong here.
+type CaptchaEuProviderOptions = {
+    publicKey?: string | null;
+    endPoint?: string | null;
+};
+
+async function loadCaptchaEuGlobal(options: CaptchaEuProviderOptions): Promise<CaptchaEuGlobal> {
+    // Captcha.eu can be self-hosted or pointed at a different endpoint, so the
+    // SDK URL is derived from provider config rather than hardcoded globally.
+    const baseUrl = String(options.endPoint || 'https://www.captcha.eu').trim().replace(/\/+$/, '');
+
+    return loadScriptAndEnsureGlobal<CaptchaEuGlobal>('KROT', {
+        id: 'FORMIE_CAPTCHA_EU_SCRIPT',
+        src: `${baseUrl}/sdk.js`,
+        async: true,
+        defer: true,
+        timeoutMs: CAPTCHA_PROVIDER_LOAD_TIMEOUT_MS,
+    });
+}
+
+export const captchaEuModule = defineCaptchaModule<CaptchaEuProviderOptions, CaptchaEuGlobal, HTMLElement>({
+    id: 'captcha-eu',
+    defaultPlaceholderSelector: '[data-captcha-eu-placeholder]',
+    defaultTokenFieldNames: ['captcha-eu-token'],
+    load: ({ options }) => {
+        return loadCaptchaEuGlobal(options.provider);
+    },
+    mount: ({ api, container, provider, services }) => {
+        // Captcha.eu requires an init/setup/render sequence. That ordering is
+        // provider-specific, so keep it here instead of abstracting it away.
+        api.init();
+
+        api.setup(String(provider.publicKey || ''));
+
+        api.WidgetV2.render(container);
+
+        api.on('CPT_OK', (event) => {
+            // Captcha.eu emits a structured payload in the event detail rather
+            // than a simple token string, so we serialize it into the shared
+            // transport input the backend already knows how to validate.
+            services.tokens.write(JSON.stringify(event.detail || {}), {
+                container,
+            });
+
+            services.errors.clear();
+        }, container);
+
+        api.on('CPT_EXPIRED', () => {
+            // Once the provider says the challenge has expired, remove the
+            // serialized payload from the transport layer immediately.
+            services.tokens.clear();
+            services.errors.clear();
+        }, container);
+
+        return container;
+    },
+    screen: async ({ placeholder, services, stageCtx }) => {
+        // Captcha.eu solves through its own widget lifecycle and callback. By
+        // screen time we only need to wait for the shared transport layer to
+        // contain the provider payload.
+        const hasToken = await services.tokens.wait();
+
+        if (!hasToken) {
+            const message = services.errors.getDefaultMessage();
+
+            services.errors.show(message, placeholder);
+
+            stageCtx.abort(message);
+        }
+    },
+});

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

@@ -0,0 +1,4 @@
+export const DEFAULT_WAIT_FOR_VALUE_MS = 2000;
+export const CAPTCHA_PROVIDER_LOAD_TIMEOUT_MS = 5000;
+export const CAPTCHA_SUBMIT_WAIT_FOR_VALUE_MS = 5000;
+export const CAPTCHA_EXECUTE_WAIT_FOR_VALUE_MS = 120000;