@verbb/formie-browser 1.0.0

package/src/js/core/dom-events.ts

@@ -0,0 +1,8 @@
+import { toDomEventName } from '#utils/event-names';
+
+export function dispatchFormieDomEvent(target: Element, eventName: string, detail: unknown): void {
+    target.dispatchEvent(new CustomEvent(toDomEventName(eventName), {
+        bubbles: true,
+        detail,
+    }));
+}

package/src/js/core/formie.ts

@@ -0,0 +1,242 @@
+import type { FormMountOptions, FormieClient, FormieFormInstance } from '#contracts/client';
+import type { FormSubmitResult } from '#contracts/schema';
+import { createFormieClient } from '#core/create-formie-client';
+import { FORMIE_HTML_EVENT_NAMES } from '#utils/event-names';
+
+export type FormieElementTarget = string | Element | Iterable<Element>;
+
+export type FormieEvent = {
+    name: string;
+    payload: unknown;
+};
+
+export type FormieOptions = Omit<Partial<FormMountOptions>, 'mode'> & {
+    element: FormieElementTarget;
+    observe?: boolean;
+    allowEmpty?: boolean;
+    client?: FormieClient;
+    onReady?: (instance: FormieFormInstance) => void;
+    onResult?: (result: FormSubmitResult, instance: FormieFormInstance) => void;
+    onSuccess?: (result: FormSubmitResult, instance: FormieFormInstance) => void;
+    onError?: (result: FormSubmitResult, instance: FormieFormInstance) => void;
+    onEvent?: (event: FormieEvent, instance: FormieFormInstance) => void;
+};
+
+export type FormieApp = {
+    client: FormieClient;
+    readonly instances: FormieFormInstance[];
+    get: (target: string | Element) => FormieFormInstance | null;
+    rescan: () => Promise<FormieFormInstance[]>;
+    destroy: () => Promise<void>;
+};
+
+type MountedState = {
+    instance: FormieFormInstance;
+    unsubs: Array<() => void>;
+};
+
+function isElement(value: unknown): value is Element {
+    return value instanceof Element;
+}
+
+function isSuccessfulResult(result: FormSubmitResult): boolean {
+    return result.ok;
+}
+
+function describeTarget(target: FormieElementTarget): string {
+    if (typeof target === 'string') {
+        return `selector "${target}"`;
+    }
+
+    if (isElement(target)) {
+        return `element "${target.tagName.toLowerCase()}"`;
+    }
+
+    return 'provided element collection';
+}
+
+function toUniqueElements(values: Iterable<Element>): Element[] {
+    const seen = new Set<Element>();
+    const elements: Element[] = [];
+
+    for (const value of values) {
+        if (!isElement(value) || seen.has(value)) {
+            continue;
+        }
+
+        seen.add(value);
+        elements.push(value);
+    }
+
+    return elements;
+}
+
+function resolveElements(target: FormieElementTarget): Element[] {
+    if (typeof target === 'string') {
+        return Array.from(document.querySelectorAll(target));
+    }
+
+    if (isElement(target)) {
+        return [target];
+    }
+
+    return toUniqueElements(target);
+}
+
+function waitForDomReady(): Promise<void> {
+    if (document.readyState !== 'loading') {
+        return Promise.resolve();
+    }
+
+    return new Promise((resolve) => {
+        document.addEventListener('DOMContentLoaded', () => resolve(), { once: true });
+    });
+}
+
+async function resolveElementsWhenReady(target: FormieElementTarget): Promise<Element[]> {
+    const elements = resolveElements(target);
+
+    if (elements.length > 0 || typeof target !== 'string') {
+        return elements;
+    }
+
+    await waitForDomReady();
+
+    return resolveElements(target);
+}
+
+function resolveObservationScope(target: FormieElementTarget): ParentNode | undefined {
+    if (typeof target === 'string') {
+        return document;
+    }
+
+    if (isElement(target)) {
+        return target.getRootNode() as ParentNode;
+    }
+
+    return document;
+}
+
+function buildMountOptions(options: FormieOptions): FormMountOptions {
+    const {
+        element: _element,
+        observe: _observe,
+        allowEmpty: _allowEmpty,
+        client: _client,
+        onReady: _onReady,
+        onResult: _onResult,
+        onSuccess: _onSuccess,
+        onError: _onError,
+        onEvent: _onEvent,
+        ...mountOptions
+    } = options;
+
+    return {
+        mode: 'server-rendered',
+        ...mountOptions,
+    };
+}
+
+async function mountResolvedElements(options: FormieOptions, client: FormieClient, states: Map<Element, MountedState>, targets: Element[]): Promise<FormieFormInstance[]> {
+    const mounted: FormieFormInstance[] = [];
+    const mountOptions = buildMountOptions(options);
+
+    for (const target of targets) {
+        const existing = states.get(target);
+
+        if (existing) {
+            mounted.push(existing.instance);
+            continue;
+        }
+
+        const instance = await client.mount(target, mountOptions);
+        const unsubs: Array<() => void> = [];
+
+        options.onReady?.(instance);
+
+        unsubs.push(instance.on('formie:submit:result', (payload) => {
+            const result = payload as FormSubmitResult;
+
+            options.onResult?.(result, instance);
+
+            if (isSuccessfulResult(result)) {
+                options.onSuccess?.(result, instance);
+            } else {
+                options.onError?.(result, instance);
+            }
+        }));
+
+        if (options.onEvent) {
+            for (const eventName of FORMIE_HTML_EVENT_NAMES) {
+                unsubs.push(instance.on(eventName, (payload) => {
+                    options.onEvent?.({
+                        name: eventName,
+                        payload,
+                    }, instance);
+                }));
+            }
+        }
+
+        states.set(target, {
+            instance,
+            unsubs,
+        });
+        mounted.push(instance);
+    }
+
+    return mounted;
+}
+
+export async function formie(options: FormieOptions): Promise<FormieApp> {
+    const client = options.client ?? createFormieClient();
+    const states = new Map<Element, MountedState>();
+    const matchedElements = await resolveElementsWhenReady(options.element);
+
+    if (matchedElements.length === 0 && !options.allowEmpty) {
+        throw new Error(`Formie could not find any elements for ${describeTarget(options.element)}.`);
+    }
+
+    await mountResolvedElements(options, client, states, matchedElements);
+
+    // The helper keeps observation opt-in so the default path stays predictable
+    // for one-off page loads while still offering a light SPA escape hatch.
+    const stopObserving = options.observe
+        ? client.observe(resolveObservationScope(options.element))
+        : null;
+
+    return {
+        client,
+        get instances() {
+            return Array.from(states.values()).map(({ instance }) => instance);
+        },
+        get(target) {
+            const element = typeof target === 'string' ? document.querySelector(target) : target;
+
+            if (!element) {
+                return null;
+            }
+
+            return states.get(element)?.instance ?? client.getInstance(element);
+        },
+        async rescan() {
+            const nextTargets = resolveElements(options.element);
+
+            if (nextTargets.length === 0) {
+                return Array.from(states.values()).map(({ instance }) => instance);
+            }
+
+            return mountResolvedElements(options, client, states, nextTargets);
+        },
+        async destroy() {
+            stopObserving?.();
+
+            const mountedEntries = Array.from(states.entries());
+
+            for (const [target, state] of mountedEntries) {
+                state.unsubs.forEach((unsubscribe) => unsubscribe());
+                await client.unmount(target);
+                states.delete(target);
+            }
+        },
+    };
+}

package/src/js/core/hydrate-modules.ts

@@ -0,0 +1,102 @@
+import type { FormEventUnsubscribe } from '#contracts/client';
+import type { FormMode } from '#contracts/common';
+import type { FormieModuleDefinition, FormieModuleInstance, ModuleRegistrationOptions } from '#contracts/modules';
+import type { FormModuleManifest } from '#contracts/schema';
+import { EventBus } from '#events/event-bus';
+import { loadModulesFromManifest } from '#modules/loader';
+import { ModuleRegistry } from '#modules/registry';
+import { createDebug } from '#utils/debug';
+
+export type FormieModuleHydratorOptions = {
+    root: Element;
+    form?: HTMLFormElement | null;
+    modules?: FormModuleManifest[];
+    mode?: FormMode;
+    registry?: ModuleRegistry;
+};
+
+export type FormieModuleHydrator = {
+    destroy: () => Promise<void>;
+    on: (eventName: string, callback: (payload: unknown) => void | Promise<void>) => FormEventUnsubscribe;
+    emit: (eventName: string, payload?: unknown) => Promise<void>;
+    registerModule: (moduleDefinition: FormieModuleDefinition, options?: ModuleRegistrationOptions) => boolean;
+    unregisterModule: (moduleId: string) => void;
+    getRegisteredModules: () => FormieModuleDefinition[];
+};
+
+const debug = createDebug('general', 'module-hydrator');
+
+export async function hydrateFormieModules(options: FormieModuleHydratorOptions): Promise<FormieModuleHydrator> {
+    const root = options.root;
+    const form = options.form ?? (root instanceof HTMLFormElement ? root : root.closest('form'));
+    const modules = options.modules ?? [];
+    const mode = options.mode ?? 'server-rendered';
+    const registry = options.registry ?? new ModuleRegistry();
+    const bus = new EventBus();
+
+    // This helper reuses the canonical module manifest loader without mounting the
+    // full form client, which lets non-frontend hosts like the CP opt into shared
+    // field modules without inheriting submit or pagination ownership.
+    const instances = await loadModulesFromManifest(modules, {
+        registry,
+        setupContext: {
+            formId: form?.id || (root as HTMLElement).id || 'formie-modules',
+            root,
+            form,
+            target: root,
+            scope: 'form',
+            state: {},
+            options: {},
+            on: (eventName, callback) => {
+                return bus.on(eventName, callback);
+            },
+            emit: async(eventName, payload) => {
+                await bus.emit(eventName, payload);
+            },
+        },
+        matchContext: {
+            root,
+            form,
+            mode,
+        },
+    });
+
+    debug.log('Hydrated module manifest.', {
+        moduleCount: modules.length,
+        instanceCount: instances.length,
+        mode,
+    });
+
+    return {
+        destroy: async() => {
+            await destroyModuleInstances(instances);
+            bus.clear();
+        },
+        on: (eventName, callback) => {
+            return bus.on(eventName, callback);
+        },
+        emit: async(eventName, payload) => {
+            await bus.emit(eventName, payload);
+        },
+        registerModule: (moduleDefinition, registrationOptions = {}) => {
+            return registry.register(moduleDefinition, registrationOptions);
+        },
+        unregisterModule: (moduleId) => {
+            registry.unregister(moduleId);
+        },
+        getRegisteredModules: () => {
+            return registry.getAll();
+        },
+    };
+}
+
+async function destroyModuleInstances(instances: FormieModuleInstance[]): Promise<void> {
+    for (const instance of instances) {
+        try {
+            await instance.destroy();
+        } catch (error) {
+            console.error('[formie] Failed to destroy module instance.', error);
+            debug.warn('Failed destroying module instance.', { error });
+        }
+    }
+}

package/src/js/core/page-client-event.ts

@@ -0,0 +1,129 @@
+import { createDebug } from '#utils/debug';
+
+const debug = createDebug('general', 'page-client-event');
+
+const CLIENT_EVENT_ATTR = 'data-formie-client-event';
+
+type ClientEventPayload = {
+    fields?: Array<{ label?: string; value?: string }>;
+};
+
+function escapePageIdForSelector(pageId: string): string {
+    if (typeof window !== 'undefined' && window.CSS?.escape) {
+        return window.CSS.escape(pageId);
+    }
+
+    return pageId.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+export function resolveSubmittedPageId(form: HTMLFormElement): string | null {
+    const input = form.querySelector('input[name="pageId"]') as HTMLInputElement | null;
+    const fromInput = input?.value?.trim();
+
+    if (fromInput) {
+        return fromInput;
+    }
+
+    const visible = form.querySelector('[data-formie-page]:not([data-formie-page-hidden])') as HTMLElement | null;
+    const fromVisible = visible?.getAttribute('data-formie-page-id')?.trim();
+
+    if (fromVisible) {
+        return fromVisible;
+    }
+
+    const fallback = form.querySelector('[data-formie-page]') as HTMLElement | null;
+
+    return fallback?.getAttribute('data-formie-page-id')?.trim() || null;
+}
+
+function parseClientEventAttr(raw: string | null): ClientEventPayload | null {
+    if (!raw?.trim()) {
+        return null;
+    }
+
+    try {
+        const parsed = JSON.parse(raw) as ClientEventPayload;
+
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    } catch {
+        debug.warn('Invalid data-formie-client-event JSON.', {
+            rawPreview: raw.slice(0, 80),
+        });
+
+        return null;
+    }
+}
+
+function buildPayloadObject(fields: Array<{ label?: string; value?: string }>): Record<string, string> {
+    const out: Record<string, string> = {};
+
+    fields.forEach((row) => {
+        const key = typeof row.label === 'string' ? row.label.trim() : '';
+
+        if (!key) {
+            return;
+        }
+
+        out[key] = typeof row.value === 'string' ? row.value : '';
+    });
+
+    return out;
+}
+
+/**
+ * When the builder enables JavaScript events for a page, the theme emits
+ * `data-formie-client-event` on that page's section. On each successful
+ * **submit** (not back/save), push the configured key/value object to
+ * `window.dataLayer` (when present) and dispatch `formie:client-event`.
+ */
+export function dispatchPageClientEventForSubmit(form: HTMLFormElement, action: string): void {
+    if (action !== 'submit') {
+        return;
+    }
+
+    const pageId = resolveSubmittedPageId(form);
+
+    if (!pageId) {
+        debug.log('No submitted page id; skipping client event.');
+
+        return;
+    }
+
+    const section = form.querySelector(
+        `[data-formie-page][data-formie-page-id="${escapePageIdForSelector(pageId)}"]`,
+    ) as HTMLElement | null;
+
+    if (!section) {
+        debug.log('No page section for id; skipping client event.', { pageId });
+
+        return;
+    }
+
+    const rawAttr = section.getAttribute(CLIENT_EVENT_ATTR);
+
+    if (rawAttr === null) {
+        return;
+    }
+
+    const config = parseClientEventAttr(rawAttr);
+
+    if (!config || !Array.isArray(config.fields)) {
+        return;
+    }
+
+    const payload = buildPayloadObject(config.fields);
+    const win = window as Window & { dataLayer?: unknown[] };
+
+    win.dataLayer = win.dataLayer || [];
+    win.dataLayer.push(payload);
+
+    form.dispatchEvent(new CustomEvent('formie:client-event', {
+        bubbles: true,
+        detail: { payload },
+    }));
+
+    debug.log('Dispatched page client event.', {
+        pageId,
+        keys: Object.keys(payload),
+    });
+}

package/src/js/core/page-tab-errors.ts

@@ -0,0 +1,37 @@
+import { toggleThemeClasses } from '#theme/theme-classes';
+
+function setTabErrorState(tab: HTMLElement, hasError: boolean): void {
+    toggleThemeClasses(tab, tab, 'tabError', hasError);
+
+    if (hasError) {
+        tab.setAttribute('data-formie-tab-error', 'true');
+        return;
+    }
+
+    tab.removeAttribute('data-formie-tab-error');
+}
+
+export function syncPageTabErrors(form: HTMLFormElement): void {
+    const pageIdsWithErrors = new Set<string>();
+
+    // Page tabs derive their error state from rendered field markup so they stay
+    // in sync regardless of whether errors came from client validation or submit.
+    form.querySelectorAll('[data-formie-page]').forEach((pageNode) => {
+        const page = pageNode as HTMLElement;
+        const pageId = page.getAttribute('data-formie-page-id');
+
+        if (!pageId) {
+            return;
+        }
+
+        if (page.querySelector('[data-formie-field-has-error]')) {
+            pageIdsWithErrors.add(pageId);
+        }
+    });
+
+    form.querySelectorAll('[data-formie-tab]').forEach((tabNode) => {
+        const tab = tabNode as HTMLElement;
+        const pageId = tab.getAttribute('data-formie-page-id');
+        setTabErrorState(tab, !!pageId && pageIdsWithErrors.has(pageId));
+    });
+}

package/src/js/core/submit-flow.ts

@@ -0,0 +1,120 @@
+import type { FormAction } from '#contracts/common';
+import type { FormSubmitResult } from '#contracts/schema';
+import { EventBus } from '#events/event-bus';
+import { runSubmitPipeline } from '#submit/pipeline';
+import { createDebug } from '#utils/debug';
+import { FormieValidator } from '#validation/validator';
+import {
+    applySubmitResultUi,
+    clearAriaInvalid,
+    clearFieldErrors,
+    clearFormErrors,
+    clearFormSuccess,
+} from './submit-result-ui';
+import { applySubmitResultState, clearSubmitLoading, setSubmitLoading } from './submit-result-state';
+
+const debug = createDebug('general', 'submit-flow');
+
+export function shouldRefreshTokensAfterSubmit(result: FormSubmitResult): boolean {
+    if (!result.ok && result.stage === 'validate') {
+        return false;
+    }
+
+    return true;
+}
+
+export function shouldKeepSubmitLoading(result: FormSubmitResult | null): boolean {
+    if (!result) {
+        return false;
+    }
+
+    if (result.keepSubmitLoading === true) {
+        return true;
+    }
+
+    if (result.ok && result.redirect?.url && result.redirect.target !== 'new-tab') {
+        return true;
+    }
+
+    return false;
+}
+
+export function clearSubmitFeedback(form: HTMLFormElement): void {
+    clearFieldErrors(form);
+    clearFormErrors(form);
+    clearFormSuccess(form);
+    clearAriaInvalid(form);
+}
+
+export async function executeAjaxSubmitFlow(params: {
+    id?: string;
+    target: Element;
+    form: HTMLFormElement;
+    bus: EventBus;
+    validator: FormieValidator | null;
+    validateOnSubmit?: boolean;
+    action: FormAction;
+    submitter?: HTMLElement | null;
+    waitForSubmitDelay: (form: HTMLFormElement) => Promise<void>;
+    onRefreshTokensAfterSubmit: (result: FormSubmitResult) => Promise<void>;
+    dispatchSubmitResult: (result: FormSubmitResult) => void;
+}): Promise<FormSubmitResult> {
+    const {
+        id,
+        target,
+        form,
+        bus,
+        validator,
+        validateOnSubmit,
+        action,
+        submitter,
+        waitForSubmitDelay,
+        onRefreshTokensAfterSubmit,
+        dispatchSubmitResult,
+    } = params;
+
+    clearSubmitFeedback(form);
+    setSubmitLoading(form, submitter || null);
+
+    let result: FormSubmitResult = {
+        ok: false,
+        code: 'SUBMIT_ERROR',
+        message: 'Submission failed.',
+        formErrors: ['Submission failed.'],
+    };
+
+    try {
+        await waitForSubmitDelay(form);
+        result = await runSubmitPipeline(form, action, bus, {
+            validator,
+            validateOnSubmit,
+        });
+        applySubmitResultUi(form, result);
+        applySubmitResultState(form, result, action);
+        if (shouldRefreshTokensAfterSubmit(result)) {
+            await onRefreshTokensAfterSubmit(result);
+        }
+        dispatchSubmitResult(result);
+    } catch (error) {
+        result = {
+            ok: false,
+            code: 'SUBMIT_ERROR',
+            message: error instanceof Error ? error.message : 'Submission failed.',
+            formErrors: [error instanceof Error ? error.message : 'Submission failed.'],
+        };
+        applySubmitResultUi(form, result);
+        dispatchSubmitResult(result);
+        debug.warn('Submit failed with exception.', {
+            id,
+            action,
+            target,
+            error: error instanceof Error ? error.message : error,
+        });
+    } finally {
+        if (!shouldKeepSubmitLoading(result)) {
+            clearSubmitLoading(form);
+        }
+    }
+
+    return result;
+}