@verbb/formie-browser 1.0.0

package/src/js/utils/field-references.parser.ts

@@ -0,0 +1,121 @@
+import type { FieldReferenceTransform, ParsedFieldReference } from '#utils/field-references.types';
+import { normalizeFieldKey } from '#utils/field-references.keys';
+
+function parseTransforms(body: string): { source: string; transforms: FieldReferenceTransform[] } {
+    const parts = body.split(';').map((part) => {
+        return part.trim();
+    }).filter(Boolean);
+
+    if (!parts.length) {
+        return {
+            source: '',
+            transforms: [],
+        };
+    }
+
+    const [source, ...metadata] = parts;
+    const transforms: FieldReferenceTransform[] = [];
+    let current: FieldReferenceTransform | null = null;
+
+    metadata.forEach((entry) => {
+        if (entry.startsWith('transform=')) {
+            if (current) {
+                transforms.push(current);
+            }
+
+            current = {
+                id: decodeURIComponent(entry.slice('transform='.length) || '').trim(),
+                params: {},
+            };
+            return;
+        }
+
+        if (!current || !entry.includes('=')) {
+            return;
+        }
+
+        const [rawKey, rawValue] = entry.split('=', 2);
+        const key = (rawKey || '').trim();
+
+        if (!key || key === 'transform') {
+            return;
+        }
+
+        current.params[key] = decodeURIComponent(rawValue || '').trim();
+    });
+
+    if (current) {
+        transforms.push(current);
+    }
+
+    return {
+        source: source || '',
+        transforms,
+    };
+}
+
+export function parseFieldReference(rawValue: string): ParsedFieldReference {
+    const raw = String(rawValue || '').trim();
+
+    if (!raw) {
+        return {
+            raw,
+            target: '',
+            key: '',
+            selector: '',
+            defaultValue: '',
+            transforms: [],
+            isToken: false,
+            isValid: false,
+        };
+    }
+
+    const tokenMatch = raw.match(/^\{([a-zA-Z]+)(?::(.*))?\}$/);
+
+    if (!tokenMatch) {
+        return {
+            raw,
+            target: '',
+            key: normalizeFieldKey(raw),
+            selector: '',
+            defaultValue: '',
+            transforms: [],
+            isToken: false,
+            isValid: true,
+        };
+    }
+
+    const targetRaw = (tokenMatch[1] || '').trim().toLowerCase();
+    const bodyRaw = (tokenMatch[2] || '').trim();
+    const [beforeDefault, defaultRaw = ''] = bodyRaw.split('|', 2);
+    const { source, transforms } = parseTransforms(beforeDefault || '');
+
+    if (targetRaw !== 'field') {
+        return {
+            raw,
+            target: '',
+            key: '',
+            selector: '',
+            defaultValue: defaultRaw.trim(),
+            transforms,
+            isToken: true,
+            isValid: false,
+        };
+    }
+
+    const separatorIndex = source.indexOf(':');
+    const keyRaw = separatorIndex === -1 ? source : source.slice(0, separatorIndex);
+    const selectorRaw = separatorIndex === -1 ? '' : source.slice(separatorIndex + 1);
+    const key = normalizeFieldKey(keyRaw);
+
+    return {
+        raw,
+        target: 'field',
+        key,
+        selector: selectorRaw.trim(),
+        defaultValue: defaultRaw.trim(),
+        transforms,
+        isToken: true,
+        isValid: key !== '',
+    };
+}

package/src/js/utils/field-references.registry.ts

@@ -0,0 +1,50 @@
+import { inputNameToFieldKey } from '#utils/field-references.keys';
+import type { FieldValueInput, FieldValueRegistry, FieldValueRegistryEntry } from '#utils/field-references.types';
+
+function isFieldValueInput(node: Element): node is FieldValueInput {
+    return node instanceof HTMLInputElement || node instanceof HTMLTextAreaElement || node instanceof HTMLSelectElement;
+}
+
+function addInputEntry(registry: FieldValueRegistry, key: string, input: FieldValueInput): void {
+    const normalizedKey = key.trim();
+    const name = String(input.name || '').trim();
+
+    if (!normalizedKey || !name) {
+        return;
+    }
+
+    const entry = registry.get(normalizedKey) || {
+        key: normalizedKey,
+        names: [],
+        inputs: [],
+    };
+
+    if (!entry.names.includes(name)) {
+        entry.names.push(name);
+    }
+
+    if (!entry.inputs.includes(input)) {
+        entry.inputs.push(input);
+    }
+
+    registry.set(normalizedKey, entry);
+}
+
+export function buildFieldValueRegistry(root: ParentNode): FieldValueRegistry {
+    const registry: FieldValueRegistry = new Map<string, FieldValueRegistryEntry>();
+    const inputs = Array.from(root.querySelectorAll('[name]')).filter((node): node is FieldValueInput => {
+        return isFieldValueInput(node);
+    });
+
+    inputs.forEach((input) => {
+        const key = inputNameToFieldKey(input.name);
+
+        if (!key) {
+            return;
+        }
+
+        addInputEntry(registry, key, input);
+    });
+
+    return registry;
+}

package/src/js/utils/field-references.resolver.ts

@@ -0,0 +1,115 @@
+import { fieldKeyToInputName, normalizeFieldKey } from '#utils/field-references.keys';
+import { parseFieldReference } from '#utils/field-references.parser';
+import type {
+    FieldValueInput,
+    FieldValueRegistry,
+    ResolveFieldValueResult,
+} from '#utils/field-references.types';
+
+function readInputsValue(inputs: FieldValueInput[]): string | string[] {
+    if (!inputs.length) {
+        return '';
+    }
+
+    const first = inputs[0];
+
+    if (first instanceof HTMLSelectElement && first.multiple) {
+        return Array.from(first.selectedOptions).map((option) => {
+            return option.value;
+        });
+    }
+
+    const hasCheckboxOrRadio = inputs.some((input) => {
+        return input instanceof HTMLInputElement && (input.type === 'checkbox' || input.type === 'radio');
+    });
+
+    if (hasCheckboxOrRadio) {
+        const selected = inputs.flatMap((input) => {
+            if (!(input instanceof HTMLInputElement) || !input.checked) {
+                return [];
+            }
+
+            return [input.value];
+        });
+
+        return selected.length > 1 ? selected : (selected[0] || '');
+    }
+
+    return first.value;
+}
+
+function getEntry(registry: FieldValueRegistry, key: string) {
+    return registry.get(normalizeFieldKey(key)) || null;
+}
+
+export function resolveFieldReferenceLive(
+    reference: string,
+    registry: FieldValueRegistry,
+): ResolveFieldValueResult {
+    const parsed = parseFieldReference(reference);
+    const key = parsed.key;
+    const entry = getEntry(registry, key);
+
+    if (!entry) {
+        return {
+            key,
+            value: parsed.defaultValue,
+            found: false,
+        };
+    }
+
+    const value = readInputsValue(entry.inputs);
+
+    return {
+        key,
+        value: value === '' && parsed.defaultValue !== '' ? parsed.defaultValue : value,
+        found: true,
+    };
+}
+
+export function resolveFieldReferenceFromFormData(
+    reference: string,
+    formData: FormData,
+    registry?: FieldValueRegistry,
+): ResolveFieldValueResult {
+    const parsed = parseFieldReference(reference);
+    const key = parsed.key;
+
+    if (!key) {
+        return {
+            key,
+            value: parsed.defaultValue,
+            found: false,
+        };
+    }
+
+    const entry = registry ? getEntry(registry, key) : null;
+    const names = entry?.names?.length ? entry.names : [fieldKeyToInputName(key)];
+    const values = names.flatMap((name) => {
+        const collected = formData.getAll(name).map((value) => {
+            return String(value ?? '');
+        });
+
+        if (collected.length) {
+            return collected;
+        }
+
+        return formData.getAll(`${name}[]`).map((value) => {
+            return String(value ?? '');
+        });
+    }).filter((value) => value !== '');
+
+    if (!values.length) {
+        return {
+            key,
+            value: parsed.defaultValue,
+            found: false,
+        };
+    }
+
+    return {
+        key,
+        value: values.length > 1 ? values : values[0],
+        found: true,
+    };
+}

package/src/js/utils/field-references.ts

@@ -0,0 +1,11 @@
+export { normalizeFieldKey, fieldKeyToInputName, inputNameToFieldKey } from '#utils/field-references.keys';
+export { parseFieldReference } from '#utils/field-references.parser';
+export { buildFieldValueRegistry } from '#utils/field-references.registry';
+export { resolveFieldReferenceLive, resolveFieldReferenceFromFormData } from '#utils/field-references.resolver';
+export type {
+    FieldReferenceTransform,
+    FieldValueRegistry,
+    FieldValueRegistryEntry,
+    ParsedFieldReference,
+    ResolveFieldValueResult,
+} from '#utils/field-references.types';

package/src/js/utils/field-references.types.ts

@@ -0,0 +1,31 @@
+export type FieldReferenceTransform = {
+    id: string;
+    params: Record<string, string>;
+};
+
+export type ParsedFieldReference = {
+    raw: string;
+    target: 'field' | '';
+    key: string;
+    selector: string;
+    defaultValue: string;
+    transforms: FieldReferenceTransform[];
+    isToken: boolean;
+    isValid: boolean;
+};
+
+export type FieldValueInput = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+
+export type FieldValueRegistryEntry = {
+    key: string;
+    names: string[];
+    inputs: FieldValueInput[];
+};
+
+export type FieldValueRegistry = Map<string, FieldValueRegistryEntry>;
+
+export type ResolveFieldValueResult = {
+    key: string;
+    value: string | string[];
+    found: boolean;
+};

package/src/js/utils/fields.ts

@@ -0,0 +1,58 @@
+function normalizeHandle(handle: string): string {
+    // Handles can come from token-like references or nested names. Normalize them
+    // once so DOM lookups keep using the field name syntax the form actually renders.
+    return handle
+        .replace('{field:', '')
+        .replace('{', '')
+        .replace('}', '')
+        .replace(']', '')
+        .split('[')
+        .join('][');
+}
+
+export function getFieldName(handle: string): string {
+    return `fields[${normalizeHandle(handle)}]`;
+}
+
+export function getFormFields(form: ParentNode, handle: string): HTMLElement[] {
+    const fieldName = getFieldName(handle);
+    const direct = Array.from(form.querySelectorAll(`[name="${fieldName}"]`));
+    const multi = Array.from(form.querySelectorAll(`[name="${fieldName}[]"]`));
+
+    return (multi.length ? multi : direct).filter((element): element is HTMLElement => {
+        return element instanceof HTMLElement;
+    });
+}
+
+export function getFieldLabel(form: ParentNode, handle: string): string {
+    const fields = getFormFields(form, handle);
+
+    for (const field of fields) {
+        const fieldContainer = field.closest('[data-formie-field-handle]') as HTMLElement | null;
+        const label = fieldContainer?.querySelector('[data-formie-field-label]')?.childNodes[0]?.textContent?.trim();
+
+        if (label) {
+            return label;
+        }
+    }
+
+    return '';
+}
+
+export function currencyToFloat(currencyString: string): number {
+    let sanitized = currencyString.replace(/[^\d.,-]/g, '');
+    const hasComma = sanitized.includes(',');
+    const hasDot = sanitized.includes('.');
+
+    // Accept both "1,234.56" and "1.234,56" style inputs so calculations can
+    // operate on locale-formatted values emitted by other field modules.
+    if (hasComma && hasDot) {
+        sanitized = sanitized.replace(/\./g, '').replace(/,/, '.');
+    } else if (hasComma && !hasDot) {
+        sanitized = sanitized.replace(/,/, '.');
+    } else {
+        sanitized = sanitized.replace(/,/g, '');
+    }
+
+    return parseFloat(sanitized);
+}

package/src/js/utils/http.ts

@@ -0,0 +1,51 @@
+export type RequestJsonOptions = {
+    method?: string;
+    body?: BodyInit | null;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+};
+
+async function request(url: string | URL, options: RequestJsonOptions = {}): Promise<Response> {
+    // Do not send `X-Requested-With` here: it is not CORS-safelisted, and Craft GraphQL CORS
+    // often omits it from `Access-Control-Allow-Headers` (breaks localhost → ddev, starters, etc.).
+    // `Accept` + JSON `Content-Type` are enough for Formie/Craft JSON endpoints.
+    const headers: Record<string, string> = {
+        Accept: 'application/json',
+        ...(options.headers || {}),
+    };
+    delete headers['X-Requested-With'];
+    delete headers['x-requested-with'];
+
+    return fetch(String(url), {
+        method: options.method || 'GET',
+        body: options.body ?? null,
+        signal: options.signal,
+        // Avoid sending `Cache-Control`: not CORS-safelisted; use fetch cache mode instead.
+        cache: 'no-store',
+        headers,
+        // `include` + `Access-Control-Allow-Origin: *` is invalid; many Craft GraphQL setups use `*`.
+        // `same-origin` keeps cookies for same-host deployments and avoids credentialed cross-origin
+        // fetches (e.g. Vite on localhost → ddev HTTPS) so wildcard CORS can succeed.
+        credentials: 'same-origin',
+    });
+}
+
+export async function requestJson<T>(url: string | URL, options: RequestJsonOptions = {}): Promise<T> {
+    const response = await request(url, options);
+
+    if (!response.ok) {
+        throw new Error(`Request failed (${response.status}) for ${String(url)}`);
+    }
+
+    return response.json() as Promise<T>;
+}
+
+export async function requestText(url: string | URL, options: RequestJsonOptions = {}): Promise<string> {
+    const response = await request(url, options);
+
+    if (!response.ok) {
+        throw new Error(`Request failed (${response.status}) for ${String(url)}`);
+    }
+
+    return response.text();
+}

package/src/js/utils/i18n.ts

@@ -0,0 +1,98 @@
+export type TranslationReplacements = Record<string, string | number>;
+
+type FormieWindow = Window & {
+    FormieTranslations?: Record<string, string>;
+};
+
+function getWindowTranslationStore(): Record<string, string> {
+    return (window as FormieWindow).FormieTranslations || {};
+}
+
+function hydrateTranslationsFromDom(): void {
+    if (typeof document === 'undefined') {
+        return;
+    }
+
+    const scripts = Array.from(document.querySelectorAll<HTMLScriptElement>('script[type="application/json"][data-formie-translations]:not([data-formie-translations-loaded="true"])'));
+
+    if (scripts.length === 0) {
+        return;
+    }
+
+    let nextStore: Record<string, string> | null = null;
+
+    for (const script of scripts) {
+        // Mark each seed as consumed so repeated reads stay cheap and predictable.
+        script.dataset.formieTranslationsLoaded = 'true';
+
+        const payload = script.textContent?.trim();
+
+        if (!payload) {
+            continue;
+        }
+
+        try {
+            const translations = JSON.parse(payload);
+
+            if (!translations || Array.isArray(translations) || typeof translations !== 'object') {
+                continue;
+            }
+
+            nextStore = {
+                ...(nextStore ?? getWindowTranslationStore()),
+                ...(translations as Record<string, string>),
+            };
+        } catch {
+            continue;
+        }
+    }
+
+    if (nextStore) {
+        (window as FormieWindow).FormieTranslations = nextStore;
+    }
+}
+
+function getTranslationStore(): Record<string, string> {
+    hydrateTranslationsFromDom();
+
+    return getWindowTranslationStore();
+}
+
+export function getFormieTranslations(): Record<string, string> {
+    return { ...getTranslationStore() };
+}
+
+export function setFormieTranslations(translations: Record<string, string>): Record<string, string> {
+    (window as FormieWindow).FormieTranslations = { ...translations };
+
+    return getFormieTranslations();
+}
+
+export function mergeFormieTranslations(translations: Record<string, string>): Record<string, string> {
+    // Merge lets SSR/server-rendered code seed defaults while later consumers layer in
+    // feature- or locale-specific strings without wiping the existing store.
+    (window as FormieWindow).FormieTranslations = {
+        ...getTranslationStore(),
+        ...translations,
+    };
+
+    return getFormieTranslations();
+}
+
+export function t(message: string, replacements: TranslationReplacements = {}): string {
+    let output = getTranslationStore()[message] || message;
+
+    // Keep replacement syntax intentionally small and predictable because these
+    // messages are often shared across PHP-rendered and JS-rendered validation UI.
+    output = output.replace(/{([a-zA-Z0-9]+)}/g, (match, key) => {
+        if (Object.prototype.hasOwnProperty.call(replacements, key)) {
+            return String(replacements[key]);
+        }
+
+        return match;
+    });
+
+    return output;
+}
+
+export const translate = t;

package/src/js/utils/scripts.ts

@@ -0,0 +1,84 @@
+import { waitFor } from '#utils/async';
+
+type GlobalWindow = Window & Record<string, unknown>;
+
+type LoadExternalScriptOptions = {
+    id: string;
+    src: string;
+    async?: boolean;
+    defer?: boolean;
+};
+
+const scriptLoadCache = new Map<string, Promise<HTMLScriptElement>>();
+
+export async function ensureGlobal<T = unknown>(globalName: string, timeoutMs = 5000): Promise<T> {
+    // Third-party SDKs often attach themselves to `window` after their script tag
+    // loads, so callers wait on the global rather than assuming load == ready.
+    return waitFor(() => {
+        const value = (window as unknown as GlobalWindow)[globalName];
+
+        if (typeof value === 'undefined' || value === null) {
+            return null;
+        }
+
+        return value as T;
+    }, {
+        timeoutMs,
+        intervalMs: 30,
+    });
+}
+
+export async function loadExternalScript({
+    id,
+    src,
+    async = true,
+    defer = true,
+}: LoadExternalScriptOptions): Promise<HTMLScriptElement> {
+    const existing = document.getElementById(id) as HTMLScriptElement | null;
+
+    if (existing) {
+        return existing;
+    }
+
+    // Cache by id so multiple forms/providers can safely request the same SDK
+    // without racing duplicate script tags into the page.
+    if (!scriptLoadCache.has(id)) {
+        scriptLoadCache.set(id, new Promise((resolve, reject) => {
+            const script = document.createElement('script');
+            script.id = id;
+            script.src = src;
+            script.async = async;
+            script.defer = defer;
+            script.onload = () => {
+                resolve(script);
+            };
+            script.onerror = () => {
+                scriptLoadCache.delete(id);
+                reject(new Error(`Failed to load external script: ${src}`));
+            };
+
+            document.body.appendChild(script);
+        }));
+    }
+
+    return scriptLoadCache.get(id) as Promise<HTMLScriptElement>;
+}
+
+export async function loadScriptAndEnsureGlobal<T = unknown>(
+    globalName: string,
+    options: LoadExternalScriptOptions & {
+        timeoutMs?: number;
+    },
+): Promise<T> {
+    const existing = (window as unknown as GlobalWindow)[globalName];
+
+    if (typeof existing !== 'undefined' && existing !== null) {
+        return existing as T;
+    }
+
+    // Some providers expose one stable global no matter how many forms use them,
+    // so load once and then gate on that final ready signal.
+    await loadExternalScript(options);
+
+    return ensureGlobal<T>(globalName, options.timeoutMs);
+}