@verbb/formie-browser 1.0.0

package/src/index.ts

@@ -0,0 +1,125 @@
+export { createFormieClient } from '#core/create-formie-client';
+export { hydrateFormieModules } from '#core/hydrate-modules';
+export { formie } from '#core/formie';
+export { ModuleRegistry } from '#modules/registry';
+export { FormieValidator } from '#validation/validator';
+export { bindLegacyDomEventCompatibility } from '#compatibility/dom-adapter';
+export { bindLegacyValidatorCompatibility } from '#compatibility/validator-adapter';
+export {
+    defineCaptchaModule,
+    definePassiveCaptchaModule,
+} from '#modules/captchas/api';
+export { definePaymentModule } from '#modules/payments/api';
+export { defineAddressModule } from '#modules/address/api';
+// Re-export the package surface from one root entry so external consumers can
+// mount forms, register modules, and share contracts without reaching into internals.
+export {
+    getFormieTranslations,
+    mergeFormieTranslations,
+    setFormieTranslations,
+    t,
+    translate,
+} from '#utils/i18n';
+export {
+    createDebug,
+    debugLog,
+    debugWarn,
+    isFormieDebugEnabled,
+    setFormieDebugEnabled,
+} from '#utils/debug';
+export {
+    LEGACY_FORMIE_DOM_EVENT_BRIDGES,
+    LEGACY_FORMIE_VALIDATOR_EVENT_BRIDGES,
+    resolveLegacyCompatibilityOptions,
+} from '#compatibility/event-map';
+export {
+    FORMIE_HTML_EVENT_NAMES,
+    getFieldModuleEventName,
+    getGlobalModuleLifecycleEventName,
+    getScopedModuleLifecycleEventName,
+    normalizeFormieEventName,
+    toDomEventName,
+    type ModuleLifecycleEventPhase,
+} from '#utils/event-names';
+export {
+    buildFieldValueRegistry,
+    fieldKeyToInputName,
+    inputNameToFieldKey,
+    normalizeFieldKey,
+    parseFieldReference,
+    resolveFieldReferenceFromFormData,
+    resolveFieldReferenceLive,
+} from '#utils/field-references';
+export type {
+    AddressModuleContext,
+    AddressModuleOptions,
+    AddressProviderModule,
+    AddressServices,
+} from '#modules/address/api';
+export type {
+    CaptchaModuleContext,
+    CaptchaModuleOptions,
+    CaptchaProviderModule,
+    CaptchaServices,
+} from '#modules/captchas/api';
+export type {
+    PaymentModuleContext,
+    PaymentModuleOptions,
+    PaymentProviderModule,
+    PaymentServices,
+} from '#modules/payments/api';
+export type {
+    FormieClient,
+    FormEventUnsubscribe,
+    FormieFormInstance,
+    FormMountOptions,
+} from '#contracts/client';
+export type { FormieModuleHydrator, FormieModuleHydratorOptions } from '#core/hydrate-modules';
+export type { FormieApp, FormieElementTarget, FormieEvent, FormieOptions } from '#core/formie';
+export type {
+    LegacyBridgeDisposition,
+    LegacyCompatibilityOptions,
+    LegacyDomEventBridge,
+    LegacyValidatorEventBridge,
+    ResolvedLegacyCompatibilityOptions,
+} from '#compatibility/event-map';
+export type { FormAction, FormMode, FormTransport, SubmitStage } from '#contracts/common';
+export type {
+    FormieModuleDefinition,
+    FormieModuleInstance,
+    ModuleHookContext,
+    ModuleMatchContext,
+    ModuleRegistrationOptions,
+    ModuleSetupContext,
+    SubmitHookContext,
+} from '#contracts/modules';
+export type {
+    FormRefreshTokensPayload,
+    FormDefinitionField,
+    FormDefinitionPage,
+    FormDefinitionPayload,
+    FormEndpointPayload,
+    FormModuleManifest,
+    FormModuleTarget,
+    FormModuleTargetType,
+    FormRedirect,
+    FormSubmitResult,
+} from '#contracts/schema';
+export type { ThemeClassMap } from '#contracts/theme';
+export type {
+    ValidationConfig,
+    ValidationContext,
+    ValidationError,
+    ValidationInput,
+    ValidationRuleDefinition,
+    ValidationRules,
+    ValidationRuleValue,
+} from '#validation/types';
+export type { TranslationReplacements } from '#utils/i18n';
+export type {
+    FieldReferenceTransform,
+    FieldValueRegistry,
+    FieldValueRegistryEntry,
+    ParsedFieldReference,
+    ResolveFieldValueResult,
+} from '#utils/field-references';

package/src/js/compatibility/dom-adapter.ts

@@ -0,0 +1,129 @@
+import type { FormieFormInstance } from '#contracts/client';
+import {
+    LEGACY_FORMIE_DOM_EVENT_BRIDGES,
+    type LegacyDomEventBridge,
+    type ResolvedLegacyCompatibilityOptions,
+} from '#compatibility/event-map';
+import { toDomEventName } from '#utils/event-names';
+
+type BindLegacyDomEventCompatibilityOptions = {
+    target: Element;
+    form: HTMLFormElement;
+    instance: FormieFormInstance;
+    options: ResolvedLegacyCompatibilityOptions;
+    unbinds: Array<() => void>;
+};
+
+type SubmitResultLike = {
+    ok?: boolean;
+};
+
+function dispatchLegacyDomEvent(target: Document | HTMLFormElement, legacyEvent: string, detail: unknown): void {
+    target.dispatchEvent(new CustomEvent(legacyEvent, {
+        bubbles: true,
+        detail,
+    }));
+}
+
+function shouldDispatchBridge(bridge: LegacyDomEventBridge, detail: unknown): boolean {
+    if (bridge.canonicalEvent !== 'formie:submit:result') {
+        return true;
+    }
+
+    const result = detail as SubmitResultLike | null;
+
+    if (bridge.legacyEvent === 'onAfterFormieSubmit') {
+        return !!result?.ok;
+    }
+
+    if (bridge.legacyEvent === 'onFormieSubmitError') {
+        return result?.ok === false;
+    }
+
+    return true;
+}
+
+function createLegacyPageToggleDetail(form: HTMLFormElement, detail: unknown): unknown {
+    const eventDetail = detail && typeof detail === 'object' ? detail as Record<string, unknown> : {};
+    const nextPageId = typeof eventDetail.pageId === 'string' ? eventDetail.pageId : '';
+    const pages = Array.from(form.querySelectorAll<HTMLElement>('[data-formie-page-id]'));
+    const nextPageIndex = pages.findIndex((page) => {
+        return page.getAttribute('data-formie-page-id') === nextPageId;
+    });
+
+    return {
+        data: {
+            nextPageId,
+            nextPageIndex,
+            totalPages: pages.length,
+        },
+    };
+}
+
+function createLegacyDetail(
+    bridge: LegacyDomEventBridge,
+    detail: unknown,
+    target: Element,
+    form: HTMLFormElement,
+    instance: FormieFormInstance,
+): unknown {
+    const legacyFormieApi = (globalThis as { Formie?: unknown }).Formie || instance;
+
+    if (bridge.legacyEvent === 'onFormieLoaded') {
+        return {
+            formie: legacyFormieApi,
+        };
+    }
+
+    if (bridge.legacyEvent === 'onFormieInit') {
+        return {
+            formie: legacyFormieApi,
+            form: instance,
+            $form: form,
+            formId: instance.id,
+        };
+    }
+
+    if (bridge.legacyEvent === 'onFormieReady') {
+        return {
+            ...(detail && typeof detail === 'object' ? detail as Record<string, unknown> : {}),
+            form,
+            target,
+            instance,
+        };
+    }
+
+    if (bridge.legacyEvent === 'onFormiePageToggle') {
+        return createLegacyPageToggleDetail(form, detail);
+    }
+
+    return detail;
+}
+
+export function bindLegacyDomEventCompatibility({
+    target,
+    form,
+    instance,
+    options,
+    unbinds,
+}: BindLegacyDomEventCompatibilityOptions): void {
+    if (!options.legacyDomEvents) {
+        return;
+    }
+
+    LEGACY_FORMIE_DOM_EVENT_BRIDGES.forEach((bridge) => {
+        const handler = (event: Event) => {
+            if (!(event instanceof CustomEvent) || !shouldDispatchBridge(bridge, event.detail)) {
+                return;
+            }
+
+            const legacyTarget = bridge.target === 'document' ? document : form;
+            dispatchLegacyDomEvent(legacyTarget, bridge.legacyEvent, createLegacyDetail(bridge, event.detail, target, form, instance));
+        };
+
+        target.addEventListener(toDomEventName(bridge.canonicalEvent), handler as EventListener);
+        unbinds.push(() => {
+            target.removeEventListener(toDomEventName(bridge.canonicalEvent), handler as EventListener);
+        });
+    });
+}

package/src/js/compatibility/event-map.ts

@@ -0,0 +1,72 @@
+export type LegacyBridgeDisposition = 'safe' | 'approximate';
+
+export type LegacyCompatibilityOptions = boolean | {
+    legacyDomEvents?: boolean;
+    legacyValidatorEvents?: boolean;
+};
+
+export type ResolvedLegacyCompatibilityOptions = {
+    enabled: boolean;
+    legacyDomEvents: boolean;
+    legacyValidatorEvents: boolean;
+};
+
+export type LegacyDomEventBridge = {
+    legacyEvent: string;
+    canonicalEvent: string;
+    disposition: LegacyBridgeDisposition;
+    target?: 'form' | 'document';
+};
+
+export type LegacyValidatorEventBridge = {
+    legacyEvent: string;
+    canonicalEvent: string;
+    disposition: 'safe';
+};
+
+export const LEGACY_FORMIE_DOM_EVENT_BRIDGES: LegacyDomEventBridge[] = [
+    { legacyEvent: 'onFormieLoaded', canonicalEvent: 'formie:mount:after', disposition: 'approximate', target: 'document' },
+    { legacyEvent: 'onFormieInit', canonicalEvent: 'formie:mount:after', disposition: 'approximate', target: 'document' },
+    { legacyEvent: 'onFormieReady', canonicalEvent: 'formie:mount:after', disposition: 'safe' },
+    { legacyEvent: 'onAfterFormieSubmit', canonicalEvent: 'formie:submit:result', disposition: 'safe' },
+    { legacyEvent: 'onFormieSubmitError', canonicalEvent: 'formie:submit:result', disposition: 'safe' },
+    { legacyEvent: 'onFormiePageToggle', canonicalEvent: 'formie:page:navigate:after', disposition: 'safe' },
+    { legacyEvent: 'onBeforeFormieSubmit', canonicalEvent: 'formie:submit:before', disposition: 'approximate' },
+    { legacyEvent: 'onFormieValidate', canonicalEvent: 'formie:stage:validate:before', disposition: 'approximate' },
+    { legacyEvent: 'onAfterFormieValidate', canonicalEvent: 'formie:stage:validate:after', disposition: 'approximate' },
+    { legacyEvent: 'onFormieSubmit', canonicalEvent: 'formie:submit:after', disposition: 'approximate' },
+];
+
+export const LEGACY_FORMIE_VALIDATOR_EVENT_BRIDGES: LegacyValidatorEventBridge[] = [
+    { legacyEvent: 'formieValidatorInitialized', canonicalEvent: 'formie:validator:ready', disposition: 'safe' },
+    { legacyEvent: 'formieValidatorDestroyed', canonicalEvent: 'formie:validator:destroy', disposition: 'safe' },
+    { legacyEvent: 'formieValidatorShowError', canonicalEvent: 'formie:validator:show-error', disposition: 'safe' },
+    { legacyEvent: 'formieValidatorClearError', canonicalEvent: 'formie:validator:clear-error', disposition: 'safe' },
+];
+
+export function resolveLegacyCompatibilityOptions(options: LegacyCompatibilityOptions | undefined): ResolvedLegacyCompatibilityOptions {
+    if (!options) {
+        return {
+            enabled: false,
+            legacyDomEvents: false,
+            legacyValidatorEvents: false,
+        };
+    }
+
+    if (options === true) {
+        return {
+            enabled: true,
+            legacyDomEvents: true,
+            legacyValidatorEvents: true,
+        };
+    }
+
+    const legacyDomEvents = options.legacyDomEvents ?? true;
+    const legacyValidatorEvents = options.legacyValidatorEvents ?? true;
+
+    return {
+        enabled: legacyDomEvents || legacyValidatorEvents,
+        legacyDomEvents,
+        legacyValidatorEvents,
+    };
+}

package/src/js/compatibility/validator-adapter.ts

@@ -0,0 +1,105 @@
+import type { ResolvedLegacyCompatibilityOptions } from '#compatibility/event-map';
+import type { FormieValidator } from '#validation/validator';
+
+type ValidatorReadyDetail = {
+    validator: FormieValidator;
+    addValidator: FormieValidator['addValidator'];
+    removeValidator: FormieValidator['removeValidator'];
+};
+
+type BindLegacyValidatorCompatibilityOptions = {
+    target: Element;
+    form: HTMLFormElement;
+    validatorDetail: ValidatorReadyDetail | null;
+    options: ResolvedLegacyCompatibilityOptions;
+    unbinds: Array<() => void>;
+};
+
+function dispatchLegacyValidatorEvent(target: Document | Element, legacyEvent: string, detail: unknown): void {
+    target.dispatchEvent(new CustomEvent(legacyEvent, {
+        bubbles: true,
+        detail,
+    }));
+}
+
+function matchesValidator(detail: unknown, validator: FormieValidator): detail is { validator: FormieValidator } {
+    return !!detail && typeof detail === 'object' && (detail as { validator?: FormieValidator }).validator === validator;
+}
+
+export function bindLegacyValidatorCompatibility({
+    target,
+    form,
+    validatorDetail,
+    options,
+    unbinds,
+}: BindLegacyValidatorCompatibilityOptions): void {
+    if (!options.legacyValidatorEvents || !validatorDetail) {
+        return;
+    }
+
+    const { validator, addValidator, removeValidator } = validatorDetail;
+    const baseDetail = {
+        ...validatorDetail,
+        form,
+        target,
+    };
+
+    dispatchLegacyValidatorEvent(document, 'formieValidatorInitialized', baseDetail);
+
+    const destroyHandler = (event: Event) => {
+        if (!(event instanceof CustomEvent) || !matchesValidator(event.detail, validator)) {
+            return;
+        }
+
+        dispatchLegacyValidatorEvent(document, 'formieValidatorDestroyed', {
+            ...baseDetail,
+            ...event.detail,
+        });
+    };
+
+    const showErrorHandler = (event: Event) => {
+        if (!(event instanceof CustomEvent) || !matchesValidator(event.detail, validator) || !(event.target instanceof Element)) {
+            return;
+        }
+
+        if (!form.contains(event.target)) {
+            return;
+        }
+
+        dispatchLegacyValidatorEvent(event.target, 'formieValidatorShowError', {
+            ...event.detail,
+            addValidator,
+            removeValidator,
+            form,
+            target,
+        });
+    };
+
+    const clearErrorHandler = (event: Event) => {
+        if (!(event instanceof CustomEvent) || !matchesValidator(event.detail, validator) || !(event.target instanceof Element)) {
+            return;
+        }
+
+        if (!form.contains(event.target)) {
+            return;
+        }
+
+        dispatchLegacyValidatorEvent(event.target, 'formieValidatorClearError', {
+            ...event.detail,
+            addValidator,
+            removeValidator,
+            form,
+            target,
+        });
+    };
+
+    document.addEventListener('formie:validator:destroy', destroyHandler as EventListener);
+    document.addEventListener('formie:validator:show-error', showErrorHandler as EventListener);
+    document.addEventListener('formie:validator:clear-error', clearErrorHandler as EventListener);
+
+    unbinds.push(() => {
+        document.removeEventListener('formie:validator:destroy', destroyHandler as EventListener);
+        document.removeEventListener('formie:validator:show-error', showErrorHandler as EventListener);
+        document.removeEventListener('formie:validator:clear-error', clearErrorHandler as EventListener);
+    });
+}

package/src/js/contracts/client.ts

@@ -0,0 +1,43 @@
+import type { LegacyCompatibilityOptions } from '#compatibility/event-map';
+import type { FormAction, FormMode, FormTransport } from '#contracts/common';
+import type { FormieModuleDefinition, ModuleRegistrationOptions } from '#contracts/modules';
+import type { FormEndpointPayload, FormSubmitResult } from '#contracts/schema';
+
+export type FormMountOptions = {
+    mode: FormMode;
+    transport?: FormTransport;
+    formHandle?: string;
+    endpoint?: string;
+    payload?: FormEndpointPayload;
+    staticCache?: boolean;
+    refreshTokens?: boolean;
+    locale?: string;
+    siteId?: number;
+    autoVisible?: boolean;
+    compatibility?: LegacyCompatibilityOptions;
+    theme?: 'formie' | 'none';
+    themeConfig?: Record<string, unknown>;
+};
+
+export type FormEventUnsubscribe = () => void;
+
+export type FormieFormInstance = {
+    id: string;
+    root: Element;
+    submit: (action?: FormAction) => Promise<FormSubmitResult>;
+    destroy: () => Promise<void>;
+    on: (eventName: string, callback: (payload: unknown) => void) => FormEventUnsubscribe;
+};
+
+export type FormieClient = {
+    mount: (target: Element, options: FormMountOptions) => Promise<FormieFormInstance>;
+    unmount: (target: Element) => Promise<void>;
+    update: (target: Element, options: Partial<FormMountOptions>) => Promise<FormieFormInstance>;
+    getInstance: (target: Element) => FormieFormInstance | null;
+    refreshForCache: (targetOrId: Element | string) => Promise<void>;
+    registerModule: (moduleDefinition: FormieModuleDefinition, options?: ModuleRegistrationOptions) => boolean;
+    unregisterModule: (moduleId: string) => void;
+    getRegisteredModules: () => FormieModuleDefinition[];
+    scan: (root?: ParentNode) => Promise<FormieFormInstance[]>;
+    observe: (root?: ParentNode) => () => void;
+};

package/src/js/contracts/common.ts

@@ -0,0 +1,14 @@
+export type FormAction = 'submit' | 'back' | 'save';
+
+export type FormMode = 'server-rendered' | 'client-rendered';
+
+export type FormTransport = 'rest' | 'graphql';
+
+export type SubmitStage =
+    | 'prepare'
+    | 'normalize'
+    | 'validate'
+    | 'screen'
+    | 'authorize'
+    | 'dispatch'
+    | 'finalize';

package/src/js/contracts/modules.ts

@@ -0,0 +1,53 @@
+import type { FormAction, FormMode, SubmitStage } from '#contracts/common';
+import type { FormModuleManifest, FormModuleTargetType, FormSubmitResult } from '#contracts/schema';
+
+export type ModuleMatchContext = {
+    root: Element;
+    form: HTMLFormElement | null;
+    target: Element;
+    scope: FormModuleTargetType;
+    mode: FormMode;
+    manifestItem: FormModuleManifest;
+};
+
+export type ModuleHookContext = {
+    formId: string;
+    root: Element;
+    form: HTMLFormElement | null;
+    target: Element;
+    scope: FormModuleTargetType;
+    state: Record<string, unknown>;
+};
+
+export type ModuleSetupContext = ModuleHookContext & {
+    options?: Record<string, unknown>;
+    on: (eventName: string, callback: (payload: unknown) => void) => () => void;
+    emit: (eventName: string, payload?: unknown) => Promise<void>;
+};
+
+export type ModuleRegistrationOptions = {
+    replace?: boolean;
+};
+
+export type SubmitHookContext = {
+    form: HTMLFormElement;
+    stage: SubmitStage;
+    action: FormAction;
+    formData: FormData;
+    abort: (reason?: string) => void;
+    isAborted: () => boolean;
+    abortReason: () => string | undefined;
+};
+
+export type FormieModuleInstance = {
+    destroy: () => void | Promise<void>;
+    onBeforeStage?: (ctx: SubmitHookContext) => void | Promise<void>;
+    onAfterStage?: (ctx: SubmitHookContext, result?: FormSubmitResult) => void | Promise<void>;
+};
+
+export type FormieModuleDefinition = {
+    id: string;
+    kind: 'field' | 'captcha' | 'payment' | 'address' | 'core';
+    match: (ctx: ModuleMatchContext) => boolean;
+    setup: (ctx: ModuleSetupContext) => Promise<FormieModuleInstance | void>;
+};

package/src/js/contracts/schema.ts

@@ -0,0 +1,83 @@
+import type { FormAction, SubmitStage } from '#contracts/common';
+import type { ThemeClassMap } from '#contracts/theme';
+
+export type FormDefinitionField = {
+    id: string;
+    uid?: string;
+    handle: string;
+    type: string;
+    label?: string;
+    required?: boolean;
+    settings?: Record<string, unknown>;
+    children?: FormDefinitionField[];
+};
+
+export type FormDefinitionPage = {
+    id: string;
+    name?: string;
+    fields: FormDefinitionField[];
+    settings?: Record<string, unknown>;
+};
+
+export type FormDefinitionPayload = {
+    formId?: string;
+    handle?: string;
+    pages?: FormDefinitionPage[];
+    settings?: Record<string, unknown>;
+    theme?: ThemeClassMap;
+};
+
+export type FormRefreshTokensPayload = {
+    csrf?: {
+        param: string;
+        token: string;
+    };
+    requestToken?: string;
+    renderId?: string;
+    captchas?: Record<string, { sessionKey: string; value?: string }>;
+    meta?: Record<string, unknown>;
+};
+
+export type FormRedirect = {
+    url: string;
+    target?: 'same-tab' | 'new-tab';
+};
+
+export type FormSubmitResult = {
+    ok: boolean;
+    action?: FormAction;
+    stage?: SubmitStage;
+    code?: string;
+    message?: string;
+    keepSubmitLoading?: boolean;
+    fieldErrors?: Record<string, string[]>;
+    pageFieldErrors?: Record<string, Record<string, string[]>>;
+    formErrors?: string[];
+    nextPage?: { id: string } | null;
+    redirect?: FormRedirect | null;
+    submitData?: unknown[];
+    meta?: Record<string, unknown>;
+};
+
+export type FormEndpointPayload = {
+    html?: string;
+    theme?: ThemeClassMap;
+    modules?: FormModuleManifest[];
+    refreshTokens?: FormRefreshTokensPayload;
+};
+
+export type FormModuleTargetType = 'form' | 'field' | 'page' | 'button' | 'selector';
+
+export type FormModuleTarget = {
+    targetType: FormModuleTargetType;
+    targetId: string;
+};
+
+export type FormModuleManifest = {
+    id: string;
+    src?: string;
+    type: string;
+    targets?: FormModuleTarget[];
+    renderTargets?: string[];
+    config?: Record<string, unknown>;
+};

package/src/js/contracts/theme.ts

@@ -0,0 +1 @@
+export type ThemeClassMap = Record<string, string[] | string>;