@verbb/formie-browser 1.0.0

package/src/js/utils/unload-warning.ts

@@ -0,0 +1,190 @@
+const DIRTY_TRACKING_IGNORED_FIELD_NAMES = new Set([
+    'CRAFT_CSRF_TOKEN',
+    'action',
+    'redirect',
+    'requestToken',
+    'renderId',
+    'submitAction',
+    'pageId',
+    'draftContextToken',
+    'draftContext',
+    'continuationToken',
+]);
+
+function serializeStableValue(value: unknown, seen: WeakSet<object>): string {
+    if (value == null) {
+        return String(value);
+    }
+
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+
+    if (typeof value === 'function') {
+        return '[function]';
+    }
+
+    if (typeof File !== 'undefined' && value instanceof File) {
+        return `[file:${value.name}:${value.size}:${value.type}]`;
+    }
+
+    if (typeof Blob !== 'undefined' && value instanceof Blob) {
+        return `[blob:${value.size}:${value.type}]`;
+    }
+
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => serializeStableValue(item, seen)).join(',')}]`;
+    }
+
+    if (typeof value === 'object') {
+        if (seen.has(value as object)) {
+            return '[circular]';
+        }
+
+        seen.add(value as object);
+        const entries = Object.entries(value as Record<string, unknown>)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => {
+                return `${JSON.stringify(key)}:${serializeStableValue(item, seen)}`;
+            });
+        seen.delete(value as object);
+
+        return `{${entries.join(',')}}`;
+    }
+
+    return JSON.stringify(String(value));
+}
+
+function stableSerialize(value: unknown): string {
+    return serializeStableValue(value, new WeakSet<object>());
+}
+
+function shouldTrackFieldName(name: string): boolean {
+    if (!name) {
+        return false;
+    }
+
+    const normalizedName = name.endsWith('[]') ? name.slice(0, -2) : name;
+
+    return !DIRTY_TRACKING_IGNORED_FIELD_NAMES.has(normalizedName);
+}
+
+function buildTrackedSnapshot(form: HTMLFormElement): string {
+    const entries = Array.from(new FormData(form).entries()).filter(([name]) => {
+        return shouldTrackFieldName(String(name || ''));
+    });
+
+    return stableSerialize(entries);
+}
+
+export type FormUnloadWarningGuard = {
+    captureBaseline: () => void;
+    scheduleBaselineCapture: () => void;
+    refreshDirtyState: () => boolean;
+    destroy: () => void;
+};
+
+export function createFormUnloadWarningGuard(
+    form: HTMLFormElement,
+    options: {
+        shouldWarn?: () => boolean;
+    } = {},
+): FormUnloadWarningGuard {
+    let baselineSnapshot: string | null = null;
+    let isReady = false;
+    let isDirty = false;
+    let animationFrameId: number | null = null;
+    let dirtyTimerId: number | null = null;
+    let baselineTimerId: number | null = null;
+
+    const clearScheduledWork = (): void => {
+        if (animationFrameId !== null) {
+            window.cancelAnimationFrame(animationFrameId);
+            animationFrameId = null;
+        }
+
+        if (dirtyTimerId !== null) {
+            window.clearTimeout(dirtyTimerId);
+            dirtyTimerId = null;
+        }
+
+        if (baselineTimerId !== null) {
+            window.clearTimeout(baselineTimerId);
+            baselineTimerId = null;
+        }
+    };
+
+    const refreshDirtyState = (): boolean => {
+        if (!isReady) {
+            return false;
+        }
+
+        isDirty = buildTrackedSnapshot(form) !== baselineSnapshot;
+
+        return isDirty;
+    };
+
+    const captureBaseline = (): void => {
+        baselineSnapshot = buildTrackedSnapshot(form);
+        isReady = true;
+        isDirty = false;
+    };
+
+    const scheduleBaselineCapture = (): void => {
+        clearScheduledWork();
+        isReady = false;
+
+        animationFrameId = window.requestAnimationFrame(() => {
+            animationFrameId = null;
+            baselineTimerId = window.setTimeout(() => {
+                baselineTimerId = null;
+                captureBaseline();
+            }, 0);
+        });
+    };
+
+    const scheduleDirtyRefresh = (): void => {
+        if (dirtyTimerId !== null) {
+            window.clearTimeout(dirtyTimerId);
+        }
+
+        dirtyTimerId = window.setTimeout(() => {
+            dirtyTimerId = null;
+            refreshDirtyState();
+        }, 120);
+    };
+
+    const handleBeforeUnload = (event: BeforeUnloadEvent): void => {
+        if (options.shouldWarn && !options.shouldWarn()) {
+            return;
+        }
+
+        if (!refreshDirtyState()) {
+            return;
+        }
+
+        event.preventDefault();
+        event.returnValue = '';
+    };
+
+    form.addEventListener('input', scheduleDirtyRefresh);
+    form.addEventListener('change', scheduleDirtyRefresh);
+    window.addEventListener('beforeunload', handleBeforeUnload);
+    scheduleBaselineCapture();
+
+    return {
+        captureBaseline,
+        scheduleBaselineCapture,
+        refreshDirtyState,
+        destroy: () => {
+            clearScheduledWork();
+            form.removeEventListener('input', scheduleDirtyRefresh);
+            form.removeEventListener('change', scheduleDirtyRefresh);
+            window.removeEventListener('beforeunload', handleBeforeUnload);
+        },
+    };
+}

package/src/js/validation/rules/email.ts

@@ -0,0 +1,18 @@
+import type { ValidationRuleDefinition } from '#validation/types';
+
+const email: ValidationRuleDefinition = {
+    rule: ({ input, getRule }) => {
+        if (!getRule('email') || !input.value || input.value.length < 1) {
+            return true;
+        }
+
+        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input.value);
+    },
+    message: ({ input, label, t }) => {
+        return input.getAttribute('data-formie-pattern-email-message')
+            ?? input.getAttribute('data-pattern-email-message')
+            ?? t('{attribute} is not a valid email address.', { attribute: label });
+    },
+};
+
+export default email;

package/src/js/validation/rules/match.ts

@@ -0,0 +1,26 @@
+import type { ValidationRuleDefinition } from '#validation/types';
+import { getComparableInput, getLabelText } from '#validation/rules/shared';
+
+const match: ValidationRuleDefinition = {
+    rule: (ctx) => {
+        const sourceInput = getComparableInput(ctx);
+
+        if (!sourceInput) {
+            return true;
+        }
+
+        return sourceInput.value === ctx.input.value;
+    },
+    message: (ctx) => {
+        const sourceInput = getComparableInput(ctx);
+        const sourceField = sourceInput?.closest('[data-formie-field-handle]') as HTMLElement | null;
+        const sourceLabel = getLabelText(sourceField);
+
+        return ctx.t('{name} must match {value}.', {
+            name: ctx.label,
+            value: sourceLabel,
+        });
+    },
+};
+
+export default match;

package/src/js/validation/rules/minmax.ts

@@ -0,0 +1,47 @@
+import type { ValidationRuleDefinition } from '#validation/types';
+
+const minmax: ValidationRuleDefinition = {
+    rule: ({ input }) => {
+        if (input.type !== 'number' || input.value.trim() === '') {
+            return true;
+        }
+
+        const value = parseFloat(input.value);
+        const min = input.hasAttribute('min') ? parseFloat(input.getAttribute('min') || '') : null;
+        const max = input.hasAttribute('max') ? parseFloat(input.getAttribute('max') || '') : null;
+
+        if (Number.isNaN(value)) {
+            return false;
+        }
+
+        if (min !== null && value < min) {
+            return false;
+        }
+
+        if (max !== null && value > max) {
+            return false;
+        }
+
+        return true;
+    },
+    message: ({ input, label, t }) => {
+        const min = input.hasAttribute('min') ? parseFloat(input.getAttribute('min') || '') : null;
+        const max = input.hasAttribute('max') ? parseFloat(input.getAttribute('max') || '') : null;
+
+        if (min !== null && max !== null) {
+            return t('{attribute} must be between {min} and {max}.', { attribute: label, min, max });
+        }
+
+        if (min !== null) {
+            return t('{attribute} must be no less than {min}.', { attribute: label, min });
+        }
+
+        if (max !== null) {
+            return t('{attribute} must be no greater than {max}.', { attribute: label, max });
+        }
+
+        return t('{attribute} has an invalid value.', { attribute: label });
+    },
+};
+
+export default minmax;

package/src/js/validation/rules/number.ts

@@ -0,0 +1,55 @@
+import type { ValidationRuleDefinition } from '#validation/types';
+
+const number: ValidationRuleDefinition = {
+    rule: ({ input, getRule }) => {
+        const rule = getRule('number');
+
+        if (!rule || !input.value || input.value.trim() === '') {
+            return true;
+        }
+
+        const value = parseFloat(input.value);
+
+        if (Number.isNaN(value)) {
+            return false;
+        }
+
+        if (rule !== true && typeof rule === 'object') {
+            const min = typeof rule.min === 'number' ? rule.min : null;
+            const max = typeof rule.max === 'number' ? rule.max : null;
+
+            if (min !== null && value < min) {
+                return false;
+            }
+
+            if (max !== null && value > max) {
+                return false;
+            }
+        }
+
+        return true;
+    },
+    message: ({ input, label, getRule, t }) => {
+        const rule = getRule('number');
+        const min = rule !== true && rule && typeof rule === 'object' && typeof rule.min === 'number' ? rule.min : null;
+        const max = rule !== true && rule && typeof rule === 'object' && typeof rule.max === 'number' ? rule.max : null;
+
+        if (min !== null && max !== null) {
+            return t('{attribute} must be between {min} and {max}.', { attribute: label, min, max });
+        }
+
+        if (min !== null) {
+            return t('{attribute} must be no less than {min}.', { attribute: label, min });
+        }
+
+        if (max !== null) {
+            return t('{attribute} must be no greater than {max}.', { attribute: label, max });
+        }
+
+        return input.getAttribute('data-formie-pattern-number-message')
+            ?? input.getAttribute('data-pattern-number-message')
+            ?? t('{attribute} is not a valid number.', { attribute: label });
+    },
+};
+
+export default number;

package/src/js/validation/rules/pattern.ts

@@ -0,0 +1,29 @@
+import type { ValidationRuleDefinition } from '#validation/types';
+
+const pattern: ValidationRuleDefinition = {
+    rule: ({ input, config }) => {
+        const rawPattern = input.getAttribute('pattern');
+        const patternToMatch = rawPattern ? new RegExp(`^(?:${rawPattern})$`) : config.patterns[input.type];
+
+        if (!patternToMatch || !input.value || input.value.length < 1) {
+            return true;
+        }
+
+        return patternToMatch.test(input.value);
+    },
+    message: ({ input, label, t }) => {
+        const messages = {
+            email: t('{attribute} is not a valid email address.', { attribute: label }),
+            url: t('{attribute} is not a valid URL.', { attribute: label }),
+            number: t('{attribute} is not a valid number.', { attribute: label }),
+            default: t('{attribute} is not a valid format.', { attribute: label }),
+        };
+
+        return input.getAttribute(`data-formie-pattern-${input.type}-message`)
+            ?? input.getAttribute(`data-pattern-${input.type}-message`)
+            ?? messages[input.type as keyof typeof messages]
+            ?? messages.default;
+    },
+};
+
+export default pattern;

package/src/js/validation/rules/required.ts

@@ -0,0 +1,30 @@
+import type { ValidationRuleDefinition } from '#validation/types';
+
+const required: ValidationRuleDefinition = {
+    rule: ({ input, getRule }) => {
+        if (!getRule('required') || input.type === 'hidden') {
+            return true;
+        }
+
+        if (input.type === 'checkbox' || input.type === 'radio') {
+            const checkboxInputs = input.form?.querySelectorAll(`[name="${input.name}"]:not([type="hidden"]):not([disabled])`) || [];
+
+            if (checkboxInputs.length) {
+                return Array.from(checkboxInputs).some((button) => {
+                    return button instanceof HTMLInputElement && button.checked;
+                });
+            }
+
+            return input instanceof HTMLInputElement ? input.checked : true;
+        }
+
+        return input.value.trim() !== '';
+    },
+    message: ({ input, label, t }) => {
+        return input.getAttribute('data-formie-required-message')
+            ?? input.getAttribute('data-required-message')
+            ?? t('{attribute} cannot be blank.', { attribute: label });
+    },
+};
+
+export default required;

package/src/js/validation/rules/shared.ts

@@ -0,0 +1,47 @@
+import type { ValidationContext, ValidationInput } from '#validation/types';
+
+export function stripTags(value: string): string {
+    const doc = new DOMParser().parseFromString(value, 'text/html');
+    return doc.body.textContent || '';
+}
+
+export function countGraphemes(value: string): number {
+    // Validation rules share grapheme counting with the field module path so
+    // visible counters and submit-time validation agree on what "1 character" means.
+    const unicodeRegExp = /(?:\p{Extended_Pictographic}[\p{Emoji_Modifier}\p{M}]*(?:\p{Join_Control}\p{Extended_Pictographic}[\p{Emoji_Modifier}\p{M}]*)*|\s|.)\p{M}*/gu;
+    const graphemes = value.match(unicodeRegExp) || [];
+
+    return graphemes.length;
+}
+
+export function getWordCount(value: string): number {
+    return stripTags(value).split(/\S+/).length - 1;
+}
+
+export function getLabelText(field: HTMLElement | null): string {
+    return field?.querySelector('[data-formie-field-label]')?.childNodes[0]?.textContent?.trim() || '';
+}
+
+export function getComparableInput(ctx: ValidationContext): ValidationInput | null {
+    const match = ctx.getRule('match');
+
+    if (!match || match === true || typeof match !== 'object' || !ctx.field) {
+        return null;
+    }
+
+    const fieldHandle = typeof match.fieldHandle === 'string' ? match.fieldHandle.trim() : '';
+
+    if (!fieldHandle) {
+        return null;
+    }
+
+    // Match validation resolves by field handle, not raw input name, so it stays
+    // aligned with the DOM contract used throughout the rest of the browser client.
+    const sourceField = ctx.form.querySelector(`[data-formie-field-handle="${fieldHandle}"]`) as HTMLElement | null;
+
+    if (!sourceField) {
+        return null;
+    }
+
+    return sourceField.querySelector(ctx.config.fieldsSelector) as ValidationInput | null;
+}

package/src/js/validation/rules/url.ts

@@ -0,0 +1,23 @@
+import type { ValidationRuleDefinition } from '#validation/types';
+
+const url: ValidationRuleDefinition = {
+    rule: ({ input, getRule }) => {
+        if (!getRule('url') || !input.value || input.value.length < 1) {
+            return true;
+        }
+
+        try {
+            new URL(input.value);
+            return true;
+        } catch {
+            return false;
+        }
+    },
+    message: ({ input, label, t }) => {
+        return input.getAttribute('data-formie-pattern-url-message')
+            ?? input.getAttribute('data-pattern-url-message')
+            ?? t('{attribute} is not a valid URL.', { attribute: label });
+    },
+};
+
+export default url;

package/src/js/validation/rules.ts

@@ -0,0 +1,16 @@
+import type { ValidationRuleDefinition } from '#validation/types';
+import email from '#validation/rules/email';
+import match from '#validation/rules/match';
+import number from '#validation/rules/number';
+import required from '#validation/rules/required';
+import url from '#validation/rules/url';
+
+export default {
+    // Keep the core validator registry centralized so FormieValidator can extend
+    // it at runtime while still shipping one predictable builtin rule surface.
+    required,
+    email,
+    url,
+    number,
+    match,
+} satisfies Record<string, ValidationRuleDefinition>;

package/src/js/validation/types.ts

@@ -0,0 +1,50 @@
+export type ValidationInput = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+
+export type ValidationRule = {
+    type: string;
+    fieldId?: string | null;
+    fieldHandle?: string | null;
+    min?: number | null;
+    max?: number | null;
+    [key: string]: unknown;
+};
+
+export type ValidationRuleValue = ValidationRule | boolean;
+
+export type ValidationRules = Record<string, ValidationRuleValue>;
+
+export type ValidationConfig = {
+    live: boolean;
+    errorMessage?: string;
+    fieldContainerErrorClass: string[];
+    inputErrorClass: string[];
+    messagesClass: string[];
+    messageClass: string[];
+    fieldsSelector: string;
+    patterns: Record<string, RegExp>;
+};
+
+export type ValidationContext = {
+    t: (message: string, replacements?: Record<string, string | number>) => string;
+    input: ValidationInput;
+    label: string;
+    field: HTMLElement | null;
+    form: HTMLFormElement;
+    config: ValidationConfig;
+    rules: ValidationRules;
+    getRule: (rule: string) => ValidationRuleValue | false;
+};
+
+export type ValidationRuleDefinition = {
+    rule: (ctx: ValidationContext) => boolean;
+    message?: (ctx: ValidationContext) => string;
+};
+
+export type ValidationError = {
+    input: ValidationInput;
+    field: HTMLElement | null;
+    validator: string;
+    message: string;
+    handle: string | null;
+    result: boolean;
+};