@verbb/formie-browser 1.0.0

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

@@ -0,0 +1,485 @@
+import type {
+    FormieModuleDefinition,
+    FormieModuleInstance,
+    ModuleSetupContext,
+    SubmitHookContext,
+} from '#contracts/modules';
+import type { FormSubmitResult } from '#contracts/schema';
+import { DEFAULT_WAIT_FOR_VALUE_MS } from '#modules/captchas/constants';
+import { ensureCaptchaValueInput, waitForCaptchaValue } from '#modules/captchas/utils';
+import {
+    createCaptchaHostServices,
+    type CaptchaHostServices,
+    type CaptchaModuleOptions,
+    type NormalizedCaptchaModuleOptions,
+    normalizeCaptchaModuleOptions,
+} from '#modules/captchas/host';
+import { createDebug } from '#utils/debug';
+import { getFormStateEventName } from '#utils/event-names';
+
+type Cleanup = () => void;
+const debug = createDebug('captchas');
+
+type CaptchaModuleFactory<TProvider extends Record<string, unknown>> = {
+    id: string;
+    defaultPlaceholderSelector: string;
+    defaultTokenFieldNames?: string[];
+    defaultWaitForValueMs?: number;
+    setup: (ctx: CaptchaModuleSetupContext<TProvider>) => Promise<FormieModuleInstance | void>;
+};
+
+export type ManagedCaptchaModuleAdapter<
+    TProvider extends Record<string, unknown>,
+    TApi,
+    TWidget,
+> = {
+    id: string;
+    defaultPlaceholderSelector: string;
+    defaultTokenFieldNames?: string[];
+    load: (ctx: CaptchaModuleSetupContext<TProvider>) => Promise<TApi>;
+    mount: (args: {
+        api: TApi;
+        placeholder: HTMLElement;
+        container: HTMLElement;
+        services: CaptchaHostServices;
+        options: NormalizedCaptchaModuleOptions<TProvider>;
+        provider: TProvider;
+    }) => Promise<TWidget> | TWidget;
+    screen: (args: {
+        api: TApi;
+        widget: TWidget;
+        placeholder: HTMLElement;
+        services: CaptchaHostServices;
+        options: NormalizedCaptchaModuleOptions<TProvider>;
+        provider: TProvider;
+        stageCtx: SubmitHookContext;
+    }) => Promise<void> | void;
+    unmount?: (args: {
+        api: TApi;
+        widget: TWidget;
+        placeholder: HTMLElement;
+        services: CaptchaHostServices;
+        options: NormalizedCaptchaModuleOptions<TProvider>;
+        provider: TProvider;
+    }) => Promise<void> | void;
+    reset?: (args: {
+        api: TApi;
+        widget: TWidget;
+        placeholder: HTMLElement;
+        services: CaptchaHostServices;
+        options: NormalizedCaptchaModuleOptions<TProvider>;
+        provider: TProvider;
+        reason: 'submit-result' | 'reset-state';
+    }) => Promise<void> | void;
+};
+
+export type CaptchaModuleSetupContext<TProvider extends Record<string, unknown>> = Omit<ModuleSetupContext, 'options'> & {
+    options: NormalizedCaptchaModuleOptions<TProvider>;
+    services: CaptchaHostServices;
+};
+
+export function createCaptchaModule<TProvider extends Record<string, unknown> = Record<string, unknown>>({
+    id,
+    defaultPlaceholderSelector,
+    defaultTokenFieldNames = [],
+    defaultWaitForValueMs = DEFAULT_WAIT_FOR_VALUE_MS,
+    setup,
+}: CaptchaModuleFactory<TProvider>): FormieModuleDefinition {
+    return {
+        id,
+        kind: 'captcha',
+        match: () => true,
+        setup: async(ctx) => {
+            // Every captcha module, passive or widget-backed, starts from the
+            // same two building blocks:
+            // 1. normalized options from the backend manifest
+            // 2. shared host services for placeholders, errors, tokens, and
+            //    refresh-token events
+            const options = normalizeCaptchaModuleOptions<TProvider>(id, ctx.options || {}, {
+                defaultPlaceholderSelector,
+                defaultTokenFieldNames,
+                defaultWaitForValueMs,
+            });
+            debug.log('Setup module.', {
+                moduleId: id,
+                placeholderSelector: options.ui.placeholderSelector,
+                tokenFieldNames: options.transport.tokenFieldNames,
+            });
+            const services = createCaptchaHostServices(ctx, options);
+
+            return setup({
+                ...ctx,
+                options,
+                services,
+            });
+        },
+    };
+}
+
+export function createPassiveCaptchaModule({
+    id,
+    defaultPlaceholderSelector,
+    defaultTokenFieldNames = [],
+    defaultWaitForValueMs = DEFAULT_WAIT_FOR_VALUE_MS,
+}: {
+    id: string;
+    defaultPlaceholderSelector: string;
+    defaultTokenFieldNames?: string[];
+    defaultWaitForValueMs?: number;
+}): FormieModuleDefinition {
+    return createCaptchaModule<Record<string, never>>({
+        id,
+        defaultPlaceholderSelector,
+        defaultTokenFieldNames,
+        defaultWaitForValueMs,
+        setup: async({ services, options, root }) => {
+            // Passive captchas do not have a browser SDK or visible widget.
+            // Their lifecycle is basically "keep the hidden transport input in
+            // sync, then verify it still exists at screen-stage submit time".
+            const cleanups: Cleanup[] = [];
+            let activePlaceholder = services.placeholder.getPrimary();
+            let sessionKey = options.transport.sessionKey;
+            let value = options.transport.value || '';
+
+            const renderPlaceholder = (placeholder: HTMLElement | null) => {
+                if (!placeholder || !sessionKey) {
+                    return;
+                }
+
+                // For passive providers, rendering simply means writing the
+                // hidden input into the current placeholder.
+                placeholder.innerHTML = '';
+                ensureCaptchaValueInput(placeholder, sessionKey, {
+                    value,
+                    container: placeholder,
+                });
+            };
+
+            const visibility = services.placeholder.observe(
+                (placeholder) => {
+                    activePlaceholder = placeholder;
+                    debug.log('Passive placeholder visible.', {
+                        moduleId: id,
+                    });
+                    renderPlaceholder(placeholder);
+                },
+                (placeholder) => {
+                    if (activePlaceholder === placeholder) {
+                        activePlaceholder = services.placeholder.getPrimary();
+                    }
+
+                    placeholder.innerHTML = '';
+                },
+            );
+
+            cleanups.push(visibility.cleanup);
+            renderPlaceholder(activePlaceholder);
+
+            cleanups.push(services.refresh.onTokensRefreshed((entry) => {
+                sessionKey = typeof entry.sessionKey === 'string' && entry.sessionKey.trim() !== ''
+                    ? entry.sessionKey.trim()
+                    : sessionKey;
+                value = typeof entry.value === 'string' ? entry.value : '';
+
+                const placeholder = services.placeholder.getPrimary() || activePlaceholder;
+                activePlaceholder = placeholder;
+                renderPlaceholder(placeholder);
+            }));
+
+            return {
+                destroy: () => {
+                    cleanups.forEach((cleanup) => {
+                        cleanup();
+                    });
+                },
+                onBeforeStage: async(stageCtx) => {
+                    if (stageCtx.stage !== 'screen' || stageCtx.action !== 'submit') {
+                        return;
+                    }
+
+                    const tokenFieldNames = sessionKey ? [sessionKey] : options.transport.tokenFieldNames;
+
+                    if (tokenFieldNames.length === 0) {
+                        return;
+                    }
+
+                    const hasToken = await waitForCaptchaValue(root, tokenFieldNames, options.transport.waitForValueMs);
+
+                    if (!hasToken) {
+                        const message = services.errors.getDefaultMessage();
+                        services.errors.show(message, activePlaceholder);
+                        debug.warn('Passive captcha missing token.', {
+                            moduleId: id,
+                            tokenFieldNames,
+                        });
+                        stageCtx.abort(message);
+                    }
+                },
+            };
+        },
+    });
+}
+
+export function createManagedCaptchaModule<
+    TProvider extends Record<string, unknown>,
+    TApi,
+    TWidget,
+>(adapter: ManagedCaptchaModuleAdapter<TProvider, TApi, TWidget>): FormieModuleDefinition {
+    return createCaptchaModule<TProvider>({
+        id: adapter.id,
+        defaultPlaceholderSelector: adapter.defaultPlaceholderSelector,
+        defaultTokenFieldNames: adapter.defaultTokenFieldNames,
+        setup: async(ctx) => {
+            // Managed providers are the widget/SDK-backed family. The factory
+            // owns only the generic plumbing:
+            // - load the provider API once
+            // - mount/unmount when placeholders appear/disappear
+            // - call the provider's `screen()` at submit time
+            //
+            // It intentionally does not know provider policy such as "execute
+            // now" vs "must already be solved" - that stays in each module.
+            const cleanups: Cleanup[] = [];
+            const mountedWidgets = new Map<HTMLElement, TWidget>();
+            const mountPromises = new Map<HTMLElement, Promise<void>>();
+            let activePlaceholder = ctx.services.placeholder.getPrimary();
+            let destroyed = false;
+
+            let apiPromise: Promise<TApi> | null = null;
+
+            const getApi = async(): Promise<TApi> => {
+                if (!apiPromise) {
+                    debug.log('Loading captcha provider API.', {
+                        moduleId: adapter.id,
+                    });
+                    apiPromise = adapter.load(ctx);
+                }
+
+                return apiPromise;
+            };
+
+            const unmountPlaceholder = async(placeholder: HTMLElement) => {
+                const widget = mountedWidgets.get(placeholder);
+
+                ctx.services.errors.clear(placeholder);
+
+                if (!widget) {
+                    placeholder.innerHTML = '';
+                    return;
+                }
+
+                const api = await getApi();
+
+                if (adapter.unmount) {
+                    await adapter.unmount({
+                        api,
+                        widget,
+                        placeholder,
+                        services: ctx.services,
+                        options: ctx.options,
+                        provider: ctx.options.provider,
+                    });
+                }
+
+                mountedWidgets.delete(placeholder);
+                placeholder.innerHTML = '';
+                ctx.services.tokens.clear();
+                debug.log('Unmounted captcha placeholder widget.', {
+                    moduleId: adapter.id,
+                });
+
+                if (activePlaceholder === placeholder) {
+                    activePlaceholder = ctx.services.placeholder.getPrimary();
+                }
+            };
+
+            const mountPlaceholder = async(placeholder: HTMLElement) => {
+                if (destroyed || mountedWidgets.has(placeholder) || mountPromises.has(placeholder)) {
+                    return;
+                }
+
+                // Guard against repeated visibility events or rapid DOM churn
+                // by tracking an in-flight mount promise per placeholder.
+                const promise = (async() => {
+                    const api = await getApi();
+
+                    if (destroyed || mountedWidgets.has(placeholder)) {
+                        return;
+                    }
+
+                    const container = ctx.services.placeholder.createContainer(placeholder);
+                    // Providers always render into a fresh container so the
+                    // shared services can safely tear down and rebuild
+                    // placeholder DOM.
+                    const widget = await adapter.mount({
+                        api,
+                        placeholder,
+                        container,
+                        services: ctx.services,
+                        options: ctx.options,
+                        provider: ctx.options.provider,
+                    });
+
+                    mountedWidgets.set(placeholder, widget);
+                    activePlaceholder = placeholder;
+                    debug.log('Mounted captcha placeholder widget.', {
+                        moduleId: adapter.id,
+                    });
+                })().finally(() => {
+                    mountPromises.delete(placeholder);
+                });
+
+                mountPromises.set(placeholder, promise);
+
+                await promise;
+            };
+
+            const visibility = ctx.services.placeholder.observe(
+                (placeholder) => {
+                    activePlaceholder = placeholder;
+                    void mountPlaceholder(placeholder);
+                },
+                (placeholder) => {
+                    void unmountPlaceholder(placeholder);
+                },
+            );
+
+            cleanups.push(visibility.cleanup);
+
+            const rerenderVisiblePlaceholders = async(reason: 'submit-result' | 'reset-state') => {
+                // Some providers can cheaply reset in-place, while others are
+                // safer to unmount and mount again. The provider advertises
+                // that through the optional `reset()` hook.
+                const visiblePlaceholders = visibility.getVisible();
+                const placeholdersToMount = visiblePlaceholders;
+
+                if (adapter.reset) {
+                    const api = await getApi();
+
+                    for (const placeholder of placeholdersToMount) {
+                        const widget = mountedWidgets.get(placeholder);
+
+                        if (!widget) {
+                            await mountPlaceholder(placeholder);
+                            continue;
+                        }
+
+                        await adapter.reset({
+                            api,
+                            widget,
+                            placeholder,
+                            services: ctx.services,
+                            options: ctx.options,
+                            provider: ctx.options.provider,
+                            reason,
+                        });
+
+                        ctx.services.tokens.clear();
+                        ctx.services.errors.clear(placeholder);
+                    }
+
+                    visibility.reconcile();
+                    return;
+                }
+
+                for (const placeholder of Array.from(mountedWidgets.keys())) {
+                    await unmountPlaceholder(placeholder);
+                }
+
+                for (const placeholder of placeholdersToMount) {
+                    await mountPlaceholder(placeholder);
+                }
+
+                visibility.reconcile();
+            };
+
+            cleanups.push(ctx.services.events.onRoot('formie:submit:result', (event) => {
+                const detail = event instanceof CustomEvent ? event.detail as FormSubmitResult : null;
+
+                if (detail?.stage === 'validate') {
+                    return;
+                }
+
+                if (detail?.ok === false && detail?.stage === 'screen') {
+                    return;
+                }
+
+                if (detail?.ok === true) {
+                    return;
+                }
+
+                void rerenderVisiblePlaceholders('submit-result');
+            }));
+
+            if (ctx.form) {
+                cleanups.push(ctx.services.events.onForm(getFormStateEventName('reset'), () => {
+                    activePlaceholder = ctx.services.placeholder.getPrimary() || activePlaceholder;
+
+                    window.setTimeout(() => {
+                        void rerenderVisiblePlaceholders('reset-state');
+                    }, 0);
+                }));
+            }
+
+            return {
+                destroy: async() => {
+                    destroyed = true;
+                    cleanups.forEach((cleanup) => {
+                        cleanup();
+                    });
+
+                    for (const placeholder of Array.from(mountedWidgets.keys())) {
+                        await unmountPlaceholder(placeholder);
+                    }
+                },
+                onBeforeStage: async(stageCtx) => {
+                    if (stageCtx.stage !== 'screen' || stageCtx.action !== 'submit') {
+                        return;
+                    }
+
+                    // 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
+                    // policy rather than generic lifecycle setup.
+                    const visiblePlaceholders = visibility.getVisible();
+
+                    // Captcha fields on hidden pages should not run in screen stage.
+                    if (visiblePlaceholders.length === 0) {
+                        return;
+                    }
+
+                    let placeholder = visiblePlaceholders.find((candidate) => candidate === activePlaceholder)
+                        || visiblePlaceholders[0];
+
+                    await mountPlaceholder(placeholder);
+                    placeholder = activePlaceholder || placeholder;
+
+                    ctx.services.errors.clear(placeholder);
+
+                    const widget = mountedWidgets.get(placeholder);
+
+                    if (!widget) {
+                        const message = ctx.services.errors.getDefaultMessage();
+                        ctx.services.errors.show(message, placeholder);
+                        debug.warn('Captcha widget unavailable at screen stage.', {
+                            moduleId: adapter.id,
+                        });
+                        stageCtx.abort(message);
+                        return;
+                    }
+
+                    const api = await getApi();
+
+                    await adapter.screen({
+                        api,
+                        widget,
+                        placeholder,
+                        services: ctx.services,
+                        options: ctx.options,
+                        provider: ctx.options.provider,
+                        stageCtx,
+                    });
+                },
+            };
+        },
+    });
+}

package/src/js/modules/captchas/friendly-captcha-v1.ts

@@ -0,0 +1,65 @@
+import { defineCaptchaModule } from '#modules/captchas/api';
+
+type FriendlyChallengeModule = typeof import('friendly-challenge');
+
+// FriendlyCaptcha v1 ships a different package and callback shape from v2, so
+// it keeps its own provider module even though the high-level flow is similar.
+type FriendlyCaptchaProviderOptions = {
+    siteKey?: string | null;
+    language?: string;
+    startMode?: string;
+};
+
+export const friendlyCaptchaV1Module = defineCaptchaModule<
+    FriendlyCaptchaProviderOptions,
+    FriendlyChallengeModule,
+    import('friendly-challenge').WidgetInstance
+>({
+    id: 'friendly-captcha-v1',
+    defaultPlaceholderSelector: '[data-friendly-captcha-placeholder]',
+    defaultTokenFieldNames: ['frc-captcha-solution'],
+    load: async() => {
+        // The provider owns its package choice. Shared captcha services only
+        // cares that `load()` returns some API object for later lifecycle work.
+        return import('friendly-challenge');
+    },
+    mount: ({ api, container, provider, services }) => {
+        return new api.WidgetInstance(container, {
+            sitekey: provider.siteKey || '',
+            startMode: (provider.startMode as 'auto' | 'focus' | 'none' | undefined) || 'none',
+            language: (provider.language as 'en' | undefined) || 'en',
+            solutionFieldName: 'frc-captcha-solution',
+            doneCallback: (token?: string) => {
+                // v1 writes to its provider-defined solution field name, while
+                // the shared transport services own how that ends up in the form DOM.
+                if (typeof token === 'string' && token.trim() !== '') {
+                    services.tokens.write(token.trim());
+                }
+
+                services.errors.clear();
+            },
+            errorCallback: () => {
+                services.tokens.clear();
+            },
+        });
+    },
+    screen: async({ widget, placeholder, services, stageCtx }) => {
+        // FriendlyCaptcha is started programmatically on submit when needed.
+        if (services.tokens.has()) {
+            return;
+        }
+
+        await widget.start();
+        const hasToken = await services.tokens.wait();
+
+        if (!hasToken) {
+            const message = services.errors.getDefaultMessage();
+            services.errors.show(message, placeholder);
+            stageCtx.abort(message);
+        }
+    },
+    unmount: ({ widget, services }) => {
+        widget.destroy();
+        services.tokens.clear();
+    },
+});

package/src/js/modules/captchas/friendly-captcha-v2.ts

@@ -0,0 +1,84 @@
+import { defineCaptchaModule } from '#modules/captchas/api';
+
+type FriendlyCaptchaSdkModule = typeof import('@friendlycaptcha/sdk');
+type FriendlyCaptchaWidget = import('@friendlycaptcha/sdk').WidgetHandle;
+
+// FriendlyCaptcha v2 is similar in intent to v1, but its SDK, widget handle
+// type and emitted event names are different enough that keeping a dedicated
+// provider module is clearer than trying to abstract them together.
+type FriendlyCaptchaProviderOptions = {
+    siteKey?: string | null;
+    language?: string;
+    startMode?: string;
+};
+
+export const friendlyCaptchaV2Module = defineCaptchaModule<
+    FriendlyCaptchaProviderOptions,
+    FriendlyCaptchaSdkModule,
+    FriendlyCaptchaWidget
+>({
+    id: 'friendly-captcha-v2',
+    defaultPlaceholderSelector: '[data-friendly-captcha-placeholder]',
+    defaultTokenFieldNames: ['frc-captcha-response'],
+    load: async () => {
+        return import('@friendlycaptcha/sdk');
+    },
+    mount: ({ api, container, provider, services }) => {
+        // v2 uses an SDK instance that then creates a widget handle. This is a
+        // good example of provider-specific lifecycle detail that should stay
+        // outside the generic captcha services layer.
+        const sdk = new api.FriendlyCaptchaSDK();
+        const widget = sdk.createWidget({
+            element: container,
+            sitekey: provider.siteKey || '',
+            formFieldName: 'frc-captcha-response',
+            language: provider.language,
+            startMode: (provider.startMode as 'auto' | 'focus' | 'none' | undefined) || 'none',
+        });
+
+        widget.addEventListener('frc:widget.complete', (event) => {
+            const detail = (event as CustomEvent<{ response?: string }>).detail;
+
+            // v2 exposes the solved response in its custom event detail rather
+            // than a direct callback argument.
+            if (typeof detail?.response === 'string' && detail.response.trim() !== '') {
+                services.tokens.write(detail.response.trim());
+            }
+
+            services.errors.clear();
+        });
+
+        widget.addEventListener('frc:widget.expire', () => {
+            services.tokens.clear();
+            services.errors.clear();
+        });
+
+        widget.addEventListener('frc:widget.error', (event) => {
+            const detail = (event as CustomEvent<{ error?: unknown }>).detail;
+            if (detail?.error) {
+                services.tokens.clear();
+            }
+        });
+
+        return widget;
+    },
+    screen: async ({ widget, placeholder, services, stageCtx }) => {
+        // As with v1, start the challenge only if no token is currently present.
+        if (services.tokens.has()) {
+            return;
+        }
+
+        widget.start();
+        const hasToken = await services.tokens.wait();
+
+        if (!hasToken) {
+            const message = services.errors.getDefaultMessage();
+            services.errors.show(message, placeholder);
+            stageCtx.abort(message);
+        }
+    },
+    unmount: ({ widget, services }) => {
+        widget.destroy();
+        services.tokens.clear();
+    },
+});