@verbb/formie-browser 1.0.0

package/src/js/modules/fields/shared.ts

@@ -0,0 +1,238 @@
+import type { ModuleSetupContext } from '#contracts/modules';
+import { getFieldModuleEventName } from '#utils/event-names';
+import type { ValidationContext } from '#validation/types';
+
+type ElementCleanup = void | (() => void);
+type ValidatorApi = {
+    addValidator: (name: string, validatorFunction: (ctx: ValidationContext) => boolean, errorMessage?: (ctx: ValidationContext) => string) => void;
+    removeValidator: (name: string) => void;
+};
+
+type FormWithValidationApi = HTMLFormElement & {
+    formieValidation?: ValidatorApi;
+};
+
+const fallbackCssEscape = (value: string): string => {
+    return value.replace(/["\\]/g, '\\$&');
+};
+const validatorRegistrations = new WeakMap<HTMLFormElement, Map<string, number>>();
+
+export function escapeSelectorValue(value: string): string {
+    if (typeof window.CSS?.escape === 'function') {
+        return window.CSS.escape(value);
+    }
+
+    return fallbackCssEscape(value);
+}
+
+export function getFieldContainers(root: Element, fieldHandle?: string): HTMLElement[] {
+    if (!fieldHandle) {
+        return Array.from(root.querySelectorAll('[data-formie-field-handle]')).filter((element): element is HTMLElement => {
+            return element instanceof HTMLElement;
+        });
+    }
+
+    return Array.from(root.querySelectorAll(`[data-formie-field-handle="${escapeSelectorValue(fieldHandle)}"]`)).filter((element): element is HTMLElement => {
+        return element instanceof HTMLElement;
+    });
+}
+
+export function getModuleFieldContainers(ctx: ModuleSetupContext): HTMLElement[] {
+    // Target-aware manifests may already hand a module one concrete field node.
+    // Fall back to scanning descendants only when the target is a broader surface.
+    if (ctx.target instanceof HTMLElement && ctx.target.hasAttribute('data-formie-field-handle')) {
+        return [ctx.target];
+    }
+
+    if (ctx.target instanceof HTMLElement) {
+        return Array.from(ctx.target.querySelectorAll('[data-formie-field-handle]')).filter((element): element is HTMLElement => {
+            return element instanceof HTMLElement;
+        });
+    }
+
+    return [];
+}
+
+export function getModuleFieldTarget(ctx: ModuleSetupContext): HTMLElement | null {
+    return getModuleFieldContainers(ctx)[0] || null;
+}
+
+export function getFormValidator(form: HTMLFormElement | null): ValidatorApi | null {
+    if (!form) {
+        return null;
+    }
+
+    const formWithValidationApi = form as FormWithValidationApi;
+    return formWithValidationApi.formieValidation || null;
+}
+
+export function retainFormValidators(
+    form: HTMLFormElement | null,
+    key: string,
+    register: (validator: ValidatorApi) => void,
+): void {
+    if (!form) {
+        return;
+    }
+
+    const formRegistrations = validatorRegistrations.get(form) || new Map<string, number>();
+    const currentCount = formRegistrations.get(key) || 0;
+
+    if (currentCount === 0) {
+        const validator = getFormValidator(form);
+        if (validator) {
+            register(validator);
+        }
+    }
+
+    formRegistrations.set(key, currentCount + 1);
+    validatorRegistrations.set(form, formRegistrations);
+}
+
+export function releaseFormValidators(form: HTMLFormElement | null, key: string, validatorNames: readonly string[]): void {
+    if (!form) {
+        return;
+    }
+
+    const formRegistrations = validatorRegistrations.get(form);
+    const currentCount = formRegistrations?.get(key) || 0;
+
+    if (currentCount <= 1) {
+        const validator = getFormValidator(form);
+        validatorNames.forEach((validatorName) => {
+            validator?.removeValidator(validatorName);
+        });
+
+        formRegistrations?.delete(key);
+
+        if (!formRegistrations || formRegistrations.size === 0) {
+            validatorRegistrations.delete(form);
+            return;
+        }
+
+        validatorRegistrations.set(form, formRegistrations);
+        return;
+    }
+
+    formRegistrations?.set(key, currentCount - 1);
+}
+
+export function observeMatchingElements<TElement extends Element>(
+    root: Element,
+    selector: string,
+    isMatch: (element: Element) => element is TElement,
+    init: (element: TElement) => ElementCleanup,
+): () => void {
+    const cleanups = new Map<TElement, () => void>();
+
+    const register = (element: Element): void => {
+        if (!isMatch(element) || cleanups.has(element)) {
+            return;
+        }
+
+        const cleanup = init(element);
+        cleanups.set(element, cleanup || (() => {}));
+    };
+
+    const scan = (node: ParentNode): void => {
+        if (node instanceof Element && node.matches(selector)) {
+            register(node);
+        }
+
+        node.querySelectorAll(selector).forEach((element) => {
+            register(element);
+        });
+    };
+
+    const prune = (): void => {
+        cleanups.forEach((cleanup, element) => {
+            if (root.contains(element)) {
+                return;
+            }
+
+            // Dynamic row/page removal should run per-element teardown immediately
+            // so nested modules do not retain stale listeners or observer state.
+            cleanup();
+            cleanups.delete(element);
+        });
+    };
+
+    scan(root);
+
+    const observer = new MutationObserver((mutations) => {
+        mutations.forEach((mutation) => {
+            mutation.addedNodes.forEach((node) => {
+                if (node instanceof Element) {
+                    scan(node);
+                }
+            });
+        });
+
+        prune();
+    });
+
+    observer.observe(root, {
+        childList: true,
+        subtree: true,
+    });
+
+    return () => {
+        observer.disconnect();
+
+        cleanups.forEach((cleanup) => {
+            cleanup();
+        });
+
+        cleanups.clear();
+    };
+}
+
+function getOwnerDocument(root: Element): Document {
+    return root.ownerDocument || document;
+}
+
+export function getTemplateSource(
+    root: Element,
+    templateId: string | null | undefined,
+): HTMLTemplateElement | HTMLScriptElement | HTMLElement | null {
+    const doc = getOwnerDocument(root);
+
+    if (templateId) {
+        const explicitCandidates: Array<Element | null> = [
+            root.querySelector(`template[data-formie-template-id="${escapeSelectorValue(templateId)}"]`),
+            root.querySelector(`script[data-formie-template-id="${escapeSelectorValue(templateId)}"]`),
+            doc.querySelector(`template[data-formie-template-id="${escapeSelectorValue(templateId)}"]`),
+            doc.querySelector(`script[data-formie-template-id="${escapeSelectorValue(templateId)}"]`),
+            doc.getElementById(templateId),
+        ];
+
+        for (const candidate of explicitCandidates) {
+            if (candidate instanceof HTMLTemplateElement || candidate instanceof HTMLScriptElement) {
+                return candidate;
+            }
+        }
+    }
+
+    return null;
+}
+
+export function getTemplateSourceHtml(source: HTMLTemplateElement | HTMLScriptElement | HTMLElement): string {
+    if (source instanceof HTMLTemplateElement) {
+        return source.innerHTML;
+    }
+
+    if (source instanceof HTMLScriptElement) {
+        return source.textContent || '';
+    }
+
+    return source.innerHTML;
+}
+
+export function dispatchFieldEvent(target: Element, moduleId: string, name: string, detail: Record<string, unknown>): void {
+    const eventName = getFieldModuleEventName(moduleId, name);
+
+    target.dispatchEvent(new CustomEvent(eventName, {
+        bubbles: true,
+        detail,
+    }));
+}

package/src/js/modules/fields/signature.ts

@@ -0,0 +1,202 @@
+import SignaturePad from 'signature_pad';
+import signatureCss from '#theme/fields/_signature.css?inline';
+
+import type { FormieModuleDefinition } from '#contracts/modules';
+import { dispatchFieldEvent, getModuleFieldContainers } from '#modules/fields/shared';
+import { ensureModuleStyles } from '#modules/styles';
+
+const INPUT_SELECTOR = 'input[data-formie-signature-input]';
+const CANVAS_SELECTOR = 'canvas[data-formie-signature-canvas]';
+const CLEAR_SELECTOR = '[data-formie-signature-clear]';
+const MODULE_ID = 'signature';
+
+ensureModuleStyles(MODULE_ID, [signatureCss]);
+
+type SignatureOptions = {
+    backgroundColor?: string;
+    penColor?: string;
+    penWeight?: string;
+};
+
+function getCanvasSize(canvas: HTMLCanvasElement): { width: number; height: number } {
+    const rect = canvas.getBoundingClientRect();
+
+    return {
+        width: Math.round(rect.width),
+        height: Math.round(rect.height),
+    };
+}
+
+function drawValueOnCanvas(canvas: HTMLCanvasElement, value: string): void {
+    if (!value) {
+        return;
+    }
+
+    const image = new Image();
+    image.src = value;
+    image.onload = () => {
+        const ratio = Math.max(window.devicePixelRatio || 1, 1);
+        const context = canvas.getContext('2d');
+        if (!context) {
+            return;
+        }
+
+        context.drawImage(image, 0, 0, canvas.width / ratio, canvas.height / ratio);
+    };
+}
+
+function initSignatureField(
+    root: HTMLElement,
+    field: HTMLElement,
+    input: HTMLInputElement,
+    canvas: HTMLCanvasElement,
+    clearButton: HTMLElement | null,
+    options: SignatureOptions,
+): () => void {
+    const penWeight = parseFloat(options.penWeight || '2') || 2;
+    const resizeTarget = canvas.parentElement instanceof HTMLElement ? canvas.parentElement : field;
+    const signaturePad = new SignaturePad(canvas, {
+        backgroundColor: options.backgroundColor || 'rgba(255, 255, 255, 0)',
+        penColor: options.penColor || '#000000',
+        dotSize: penWeight,
+        minWidth: penWeight,
+        maxWidth: penWeight,
+    });
+
+    const resizeCanvas = () => {
+        const { width, height } = getCanvasSize(canvas);
+
+        if (!(width > 0) || !(height > 0)) {
+            return;
+        }
+
+        const ratio = Math.max(window.devicePixelRatio || 1, 1);
+        const context = canvas.getContext('2d');
+        if (!context) {
+            return;
+        }
+
+        // SignaturePad clears bitmap state when the canvas size changes, so resize
+        // captures the current data URL first and redraws it onto the new surface.
+        const existingValue = input.value || (signaturePad.isEmpty() ? '' : signaturePad.toDataURL());
+        canvas.width = width * ratio;
+        canvas.height = height * ratio;
+        context.setTransform(1, 0, 0, 1, 0, 0);
+        context.scale(ratio, ratio);
+        signaturePad.clear();
+        drawValueOnCanvas(canvas, existingValue);
+    };
+
+    const scheduleResize = (delay = 0) => {
+        window.setTimeout(() => {
+            window.requestAnimationFrame(() => {
+                resizeCanvas();
+            });
+        }, delay);
+    };
+    const resizeHandler = () => {
+        scheduleResize();
+    };
+    const pageNavigateHandler = () => {
+        // Multi-page forms can reveal a signature pad after layout changes; delay
+        // slightly so the newly visible page has settled before measuring.
+        scheduleResize(100);
+    };
+    const resizeObserver = typeof ResizeObserver === 'undefined'
+        ? null
+        : new ResizeObserver(() => {
+            scheduleResize();
+        });
+
+    const syncInputValue = (nextValue: string) => {
+        const valueChanged = input.value !== nextValue;
+        input.value = nextValue;
+
+        if (!valueChanged) {
+            return;
+        }
+
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+        input.dispatchEvent(new Event('change', { bubbles: true }));
+    };
+
+    const syncValue = () => {
+        syncInputValue(signaturePad.isEmpty() ? '' : signaturePad.toDataURL());
+    };
+
+    const clearSignature = () => {
+        signaturePad.clear();
+        syncInputValue('');
+    };
+
+    signaturePad.addEventListener('endStroke', syncValue);
+    window.addEventListener('resize', resizeHandler);
+    root.addEventListener('formie:page:navigate:after', pageNavigateHandler as EventListener);
+    resizeObserver?.observe(resizeTarget);
+    scheduleResize();
+
+    if (clearButton) {
+        clearButton.addEventListener('click', clearSignature);
+    }
+
+    dispatchFieldEvent(field, MODULE_ID, 'init', {
+        signature: signaturePad,
+    });
+
+    return () => {
+        signaturePad.removeEventListener('endStroke', syncValue);
+        window.removeEventListener('resize', resizeHandler);
+        root.removeEventListener('formie:page:navigate:after', pageNavigateHandler as EventListener);
+        resizeObserver?.disconnect();
+        if (clearButton) {
+            clearButton.removeEventListener('click', clearSignature);
+        }
+
+        signaturePad.clear();
+    };
+}
+
+export const signatureModule: FormieModuleDefinition = {
+    id: MODULE_ID,
+    kind: 'field',
+    match: (ctx) => {
+        return !!ctx.target.querySelector(CANVAS_SELECTOR);
+    },
+    setup: async(ctx) => {
+        const options = (ctx.options || {}) as SignatureOptions;
+        const root = ctx.root instanceof HTMLElement
+            ? ctx.root
+            : (ctx.target instanceof HTMLElement ? ctx.target : null);
+
+        if (!root) {
+            return;
+        }
+
+        const fields = getModuleFieldContainers(ctx);
+        const cleanups = fields.map((field) => {
+            const input = field.querySelector(INPUT_SELECTOR);
+            const canvas = field.querySelector(CANVAS_SELECTOR);
+            const clearButton = field.querySelector(CLEAR_SELECTOR);
+
+            if (!(input instanceof HTMLInputElement) || !(canvas instanceof HTMLCanvasElement)) {
+                return () => {};
+            }
+
+            return initSignatureField(root, field, input, canvas, clearButton instanceof HTMLElement ? clearButton : null, options);
+        });
+
+        await ctx.emit('formie:module:signature:init', {
+            count: cleanups.length,
+        });
+
+        return {
+            destroy: () => {
+                cleanups.forEach((cleanup) => {
+                    cleanup();
+                });
+
+                void ctx.emit('formie:module:signature:destroy', {});
+            },
+        };
+    },
+};

package/src/js/modules/fields/summary.ts

@@ -0,0 +1,272 @@
+import summaryCss from '#theme/fields/_summary.css?inline';
+
+import type { FormieModuleDefinition } from '#contracts/modules';
+import { dispatchFieldEvent, getModuleFieldContainers } from '#modules/fields/shared';
+import { ensureModuleStyles } from '#modules/styles';
+import { toggleThemeClasses } from '#theme/theme-classes';
+import { debounce } from '#utils/async';
+import { createDebug } from '#utils/debug';
+import { requestText } from '#utils/http';
+
+const BLOCKS_SELECTOR = '[data-formie-summary-blocks]';
+const CONTAINER_SELECTOR = '[data-formie-summary-container]';
+const SUMMARY_ACTION = 'formie/fields/get-summary-html';
+const MODULE_ID = 'summary';
+const debug = createDebug('fields', 'summary');
+
+ensureModuleStyles(MODULE_ID, [summaryCss]);
+
+type SummaryRequestState = {
+    accessToken: string | null;
+};
+
+function getSummaryRequestUrl(): string {
+    const url = new URL(window.location.href);
+    url.hash = '';
+
+    return url.toString();
+}
+
+function getSummaryRequestState(field: HTMLElement): SummaryRequestState {
+    const summaryTokenInput = field.querySelector('[data-formie-summary-token]') as HTMLInputElement | null;
+    const accessToken = summaryTokenInput?.value?.trim() || null;
+
+    return {
+        accessToken,
+    };
+}
+
+async function requestSummaryHtml(form: HTMLFormElement, state: SummaryRequestState, signal?: AbortSignal): Promise<string> {
+    if (!state.accessToken) {
+        throw new Error('Summary field requires an access token.');
+    }
+
+    // Summary output is server-rendered from the current submission state rather
+    // than rebuilt in JS, so it stays aligned with backend formatting rules.
+    const formData = new FormData(form);
+    formData.set('action', SUMMARY_ACTION);
+    formData.set('accessToken', state.accessToken);
+
+    return requestText(getSummaryRequestUrl(), {
+        method: 'POST',
+        body: formData,
+        signal,
+        headers: {
+            Accept: 'text/html',
+        },
+    });
+}
+
+function initSummaryField(field: HTMLElement, root: Element): () => void {
+    const form = field.closest('form');
+
+    if (!(form instanceof HTMLFormElement)) {
+        debug.warn('Missing form ancestor; skipping field.');
+        return () => {};
+    }
+
+    let hasFetched = false;
+    let isDirty = true;
+    let isVisible = false;
+    let dirtyVersion = 0;
+    let requestVersion = 0;
+    let activeRequest: AbortController | null = null;
+
+    const getBlocks = (): HTMLElement | null => {
+        const blocks = field.querySelector(BLOCKS_SELECTOR);
+        return blocks instanceof HTMLElement ? blocks : null;
+    };
+
+    const getContainer = (): HTMLElement | null => {
+        const container = field.querySelector(CONTAINER_SELECTOR);
+        return container instanceof HTMLElement ? container : null;
+    };
+
+    const setLoadingState = (isLoading: boolean): void => {
+        const blocks = getBlocks();
+
+        if (!blocks) {
+            return;
+        }
+
+        if (isLoading) {
+            blocks.setAttribute('data-formie-loading', 'true');
+            blocks.setAttribute('aria-busy', 'true');
+            toggleThemeClasses(blocks, form, 'loading', true);
+            return;
+        }
+
+        blocks.removeAttribute('data-formie-loading');
+        blocks.removeAttribute('aria-busy');
+        toggleThemeClasses(blocks, form, 'loading', false);
+    };
+
+    const initialState = getSummaryRequestState(field);
+    setLoadingState(!!initialState.accessToken);
+
+    const queueFetch = (): void => {
+        if (!isVisible || (hasFetched && !isDirty)) {
+            return;
+        }
+
+        debug.log('Queueing fetch.');
+        void fetchSummary();
+    };
+
+    const fetchSummary = debounce(async() => {
+        const state = getSummaryRequestState(field);
+
+        if (!getBlocks() || !state.accessToken) {
+            debug.warn('Missing state for fetch.', state);
+            setLoadingState(false);
+            return;
+        }
+
+        requestVersion += 1;
+        const currentRequestVersion = requestVersion;
+        const requestDirtyVersion = dirtyVersion;
+        activeRequest?.abort();
+        activeRequest = new AbortController();
+        setLoadingState(true);
+
+        try {
+            const html = await requestSummaryHtml(form, state, activeRequest.signal);
+
+            if (currentRequestVersion !== requestVersion) {
+                return;
+            }
+
+            const container = getContainer();
+            const nextMarkup = document.createElement('template');
+            nextMarkup.innerHTML = html.trim();
+            const nextContainer = nextMarkup.content.querySelector(CONTAINER_SELECTOR);
+
+            if (container && nextContainer instanceof HTMLElement) {
+                container.replaceWith(nextContainer);
+            } else if (container) {
+                container.innerHTML = html;
+            }
+
+            hasFetched = true;
+            isDirty = dirtyVersion !== requestDirtyVersion;
+            debug.log('Fetch complete.', {
+                isDirty,
+                dirtyVersion,
+                requestVersion: currentRequestVersion,
+            });
+            dispatchFieldEvent(field, MODULE_ID, 'fetch-summary', {
+                summary: field,
+                html,
+            });
+        } catch (error) {
+            if (error instanceof DOMException && error.name === 'AbortError') {
+                debug.log('Fetch aborted.');
+                return;
+            }
+
+            console.error('[formie] Failed to load summary field HTML.', error);
+        } finally {
+            if (currentRequestVersion === requestVersion) {
+                setLoadingState(false);
+                activeRequest = null;
+
+                if (isDirty) {
+                    queueFetch();
+                }
+            }
+        }
+    }, 300);
+
+    const markDirty = (event?: Event): void => {
+        const target = event?.target;
+
+        if (target instanceof Node && field.contains(target)) {
+            return;
+        }
+
+        isDirty = true;
+        dirtyVersion += 1;
+        debug.log('Marked dirty.', { dirtyVersion });
+    };
+
+    const handleFieldMutation = (event: Event): void => {
+        markDirty(event);
+        queueFetch();
+    };
+
+    const handleSubmitResult = (): void => {
+        isDirty = true;
+        debug.log('Submit result received; refreshing.');
+        queueFetch();
+    };
+
+    const handlePageNavigate = (): void => {
+        isDirty = true;
+        debug.log('Page navigation received; refreshing.');
+        queueFetch();
+    };
+
+    // Defer the summary fetch until the field is near view. This avoids extra
+    // requests for hidden pages or summaries the user never reaches.
+    const observer = new IntersectionObserver((entries) => {
+        isVisible = !!entries[0]?.isIntersecting;
+
+        if (!isVisible) {
+            return;
+        }
+
+        debug.log('Field became visible.');
+        dispatchFieldEvent(field, MODULE_ID, 'field-visible', {
+            summary: field,
+        });
+        queueFetch();
+    }, {
+        root: form,
+        rootMargin: '50px',
+    });
+
+    observer.observe(field);
+    form.addEventListener('input', handleFieldMutation);
+    form.addEventListener('change', handleFieldMutation);
+    root.addEventListener('formie:page:navigate:after', handlePageNavigate as EventListener);
+    root.addEventListener('formie:submit:result', handleSubmitResult as EventListener);
+
+    return () => {
+        activeRequest?.abort();
+        observer.disconnect();
+        form.removeEventListener('input', handleFieldMutation);
+        form.removeEventListener('change', handleFieldMutation);
+        root.removeEventListener('formie:page:navigate:after', handlePageNavigate as EventListener);
+        root.removeEventListener('formie:submit:result', handleSubmitResult as EventListener);
+        debug.log('Field destroyed.');
+    };
+}
+
+export const summaryModule: FormieModuleDefinition = {
+    id: MODULE_ID,
+    kind: 'field',
+    match: (ctx) => {
+        return !!ctx.target.querySelector(BLOCKS_SELECTOR);
+    },
+    setup: async(ctx) => {
+        const cleanups = getModuleFieldContainers(ctx).map((field) => {
+            return initSummaryField(field, ctx.root);
+        });
+        debug.log('Module setup.', { fieldCount: cleanups.length });
+
+        await ctx.emit('formie:module:summary:init', {
+            count: cleanups.length,
+        });
+
+        return {
+            destroy: () => {
+                cleanups.forEach((cleanup) => {
+                    cleanup();
+                });
+
+                debug.log('Module destroy.', { fieldCount: cleanups.length });
+                void ctx.emit('formie:module:summary:destroy', {});
+            },
+        };
+    },
+};