@vectoriox/iox-ui 4.30.2 → 4.31.1

package/src/forms-core/validate.ts

@@ -0,0 +1,232 @@
+// The validator. ONE implementation, run by the builder canvas, the SSR engine and `iox-cms`.
+//
+// Client-side validation is UX; server-side validation is truth. Because both call this function,
+// a visitor can never be told a value is fine and then have the server reject it, and a hand-crafted
+// POST can never bypass a rule the author configured.
+
+import {
+    ControlType,
+    FieldSpec,
+    FormSpec,
+    IMPLIED_PATTERN,
+    PATTERN_PRESETS,
+    PatternPreset,
+    RuleName,
+    ValidationRule,
+} from './form.model';
+import { PATTERN_MESSAGE_KEYS, RULE_MESSAGE_KEYS } from './messages';
+
+export interface FieldError {
+    /** i18n key, or the author's own override string when they set one. */
+    messageKey: string;
+    /** Interpolation values (`{ n: 8 }`, `{ field: 'Email' }`). */
+    params?: Record<string, any>;
+}
+
+export interface FieldResult extends Partial<FieldError> {
+    valid: boolean;
+}
+
+export interface FormResult {
+    valid: boolean;
+    /** Keyed by field name. Empty when valid. */
+    errors: Record<string, FieldError>;
+}
+
+/** A file, as either runtime hands it over. Kept structural so this file imports no DOM types. */
+interface FileLike {
+    name?: string;
+    size?: number;
+    type?: string;
+}
+
+/**
+ * Validate one field's value.
+ *
+ * Order is deliberate and is part of the contract:
+ *   1. `required` (or `accepted` for a checkbox) — the only rules an EMPTY value can fail.
+ *   2. Everything else, in the order the author arranged them, but ONLY for a non-empty value.
+ *
+ * That second point is what stops an optional "Phone" field from shouting "enter a valid phone
+ * number" at someone who simply left it blank — the single most common validation-UX bug.
+ * The FIRST failure wins: a visitor fixes one thing at a time.
+ */
+export function validateField(
+    value: unknown,
+    spec: FieldSpec,
+    form: Record<string, unknown> = {},
+): FieldResult {
+    const rules = effectiveRules(spec);
+    const empty = isEmpty(value, spec.control);
+
+    for (const rule of rules) {
+        const appliesToEmpty = rule.name === RuleName.Required || rule.name === RuleName.Accepted;
+        if (empty && !appliesToEmpty) continue;
+
+        const failure = check(rule, value, spec, form);
+        if (failure) {
+            return {
+                valid: false,
+                messageKey: rule.message ?? failure.messageKey,
+                params: failure.params,
+            };
+        }
+    }
+    return { valid: true };
+}
+
+/**
+ * Validate a whole submission. Every field is checked (not short-circuited at the first bad one) so
+ * the visitor sees every problem at once instead of fixing them one reload at a time.
+ */
+export function validateForm(
+    values: Record<string, unknown>,
+    spec: FormSpec,
+): FormResult {
+    const errors: Record<string, FieldError> = {};
+    for (const field of spec.fields ?? []) {
+        const result = validateField(values?.[field.name], field, values ?? {});
+        if (!result.valid) {
+            errors[field.name] = { messageKey: result.messageKey!, params: result.params };
+        }
+    }
+    return { valid: Object.keys(errors).length === 0, errors };
+}
+
+/** The name of the first field with an error, in spec order — what the browser should focus. */
+export function firstInvalidField(spec: FormSpec, errors: Record<string, FieldError>): string | null {
+    for (const field of spec.fields ?? []) if (errors[field.name]) return field.name;
+    return null;
+}
+
+// ─── internals ───────────────────────────────────────────────────────────────
+
+/**
+ * The author's rules, plus the ones the field's own configuration implies: `required` from the
+ * switch (rather than making the author add a rule for the commonest case) and the pattern implied
+ * by an Email/Tel/Url control. An explicitly declared rule of the same name always wins, so an
+ * author who sets their own `pattern` on an Email field is not fighting an invisible second one.
+ */
+function effectiveRules(spec: FieldSpec): ValidationRule[] {
+    const declared = spec.rules ?? [];
+    const has = (name: RuleName) => declared.some(r => r.name === name);
+    const implied: ValidationRule[] = [];
+
+    if (spec.required && !has(RuleName.Required)) {
+        // A checkbox's "required" means TICKED, which is a different message and a different check.
+        implied.push(spec.control === ControlType.Checkbox
+            ? { name: RuleName.Accepted }
+            : { name: RuleName.Required });
+    }
+
+    const preset = IMPLIED_PATTERN[spec.control];
+    if (preset && !has(RuleName.Pattern)) {
+        implied.push({ name: RuleName.Pattern, params: { preset } });
+    }
+
+    return [...implied, ...declared];
+}
+
+/** Empty means "the visitor gave us nothing" — per control type, not a blanket falsy check. */
+function isEmpty(value: unknown, control: ControlType): boolean {
+    if (value === null || value === undefined) return true;
+    if (control === ControlType.Checkbox) return value === false;
+    if (Array.isArray(value)) return value.length === 0;
+    if (typeof value === 'string') return value.trim() === '';
+    return false;
+}
+
+function check(
+    rule: ValidationRule,
+    value: unknown,
+    spec: FieldSpec,
+    form: Record<string, unknown>,
+): FieldError | null {
+    const fail = (messageKey: string, params?: Record<string, any>): FieldError => ({ messageKey, params });
+    const defaultKey = RULE_MESSAGE_KEYS[rule.name];
+    const n = Number(rule.params?.['n']);
+
+    switch (rule.name) {
+        case RuleName.Required:
+            return isEmpty(value, spec.control) ? fail(defaultKey) : null;
+
+        case RuleName.Accepted:
+            return value === true ? null : fail(defaultKey);
+
+        case RuleName.MinLength:
+            return text(value).length < n ? fail(defaultKey, { n }) : null;
+
+        case RuleName.MaxLength:
+            return text(value).length > n ? fail(defaultKey, { n }) : null;
+
+        case RuleName.Min: {
+            const num = numeric(value);
+            return num === null || num < n ? fail(defaultKey, { n }) : null;
+        }
+
+        case RuleName.Max: {
+            const num = numeric(value);
+            return num === null || num > n ? fail(defaultKey, { n }) : null;
+        }
+
+        case RuleName.Pattern: {
+            const regex = patternFor(rule);
+            if (!regex) return null;   // an unparsable custom regex must not block a submission
+            if (regex.test(text(value))) return null;
+            const preset = rule.params?.['preset'] as string | undefined;
+            return fail((preset && PATTERN_MESSAGE_KEYS[preset]) || defaultKey);
+        }
+
+        case RuleName.Matches: {
+            const other = String(rule.params?.['field'] ?? '');
+            return text(value) === text(form?.[other]) ? null : fail(defaultKey, { field: other });
+        }
+
+        case RuleName.FileType: {
+            const accepted = list(rule.params?.['types']).map(t => t.toLowerCase().replace(/^\./, ''));
+            if (!accepted.length) return null;
+            const bad = files(value).some(f => {
+                const ext = (f.name ?? '').split('.').pop()?.toLowerCase() ?? '';
+                const mime = (f.type ?? '').toLowerCase();
+                return !accepted.some(t => t === ext || mime === t || mime.startsWith(t + '/'));
+            });
+            return bad ? fail(defaultKey, { types: accepted.join(', ') }) : null;
+        }
+
+        case RuleName.FileSize: {
+            const maxBytes = n * 1024 * 1024;
+            return files(value).some(f => (f.size ?? 0) > maxBytes) ? fail(defaultKey, { n }) : null;
+        }
+
+        default:
+            return null;
+    }
+}
+
+function patternFor(rule: ValidationRule): RegExp | null {
+    const preset = rule.params?.['preset'] as PatternPreset | undefined;
+    if (preset && PATTERN_PRESETS[preset]) return PATTERN_PRESETS[preset];
+    const custom = rule.params?.['regex'];
+    if (typeof custom !== 'string' || !custom) return null;
+    // A malformed regex is the AUTHOR's mistake; failing open is the only safe reading, because
+    // failing closed would make a live form permanently unsubmittable for every visitor.
+    try { return new RegExp(custom); } catch { return null; }
+}
+
+const text = (value: unknown): string =>
+    value === null || value === undefined ? '' : String(value).trim();
+
+function numeric(value: unknown): number | null {
+    const parsed = typeof value === 'number' ? value : parseFloat(text(value));
+    return Number.isFinite(parsed) ? parsed : null;
+}
+
+const list = (value: unknown): string[] =>
+    Array.isArray(value) ? value.map(String)
+        : typeof value === 'string' ? value.split(',').map(s => s.trim()).filter(Boolean)
+        : [];
+
+const files = (value: unknown): FileLike[] =>
+    Array.isArray(value) ? value as FileLike[]
+        : value && typeof value === 'object' ? [value as FileLike]
+        : [];