ngx-api-forms 1.0.0

package/fesm2022/ngx-api-forms.mjs

@@ -0,0 +1,890 @@
+import * as i0 from '@angular/core';
+import { signal, computed, inject, ElementRef, Renderer2, DestroyRef, Input, Directive } from '@angular/core';
+import { FormGroup, FormArray } from '@angular/forms';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { Subject, merge, takeUntil, tap, catchError, throwError } from 'rxjs';
+import { HttpContextToken, HttpContext } from '@angular/common/http';
+
+/**
+ * ngx-api-forms - Models & Interfaces
+ *
+ * Core types for bridging API validation errors to Angular Reactive Forms.
+ */
+// ---------------------------------------------------------------------------
+// Global (Non-Field) Errors
+// ---------------------------------------------------------------------------
+/**
+ * Sentinel field name used by presets to tag errors that are not bound to a
+ * specific form control (e.g. Django `non_field_errors`, Zod `formErrors`).
+ *
+ * FormBridge also routes any ApiFieldError whose field does not match a control
+ * to `globalErrorsSignal`, so custom presets do not need to use this constant -
+ * unmatched fields are captured automatically.
+ */
+const GLOBAL_ERROR_FIELD = '__global__';
+
+function flattenErrors(errors, parentPath = '') {
+    const result = [];
+    for (const error of errors) {
+        const path = parentPath ? `${parentPath}.${error.property}` : error.property;
+        if (error.constraints) {
+            for (const [constraint, message] of Object.entries(error.constraints)) {
+                result.push({ field: path, constraint, message });
+            }
+        }
+        // Recursively handle nested validation (e.g. nested DTOs)
+        if (error.children && error.children.length > 0) {
+            result.push(...flattenErrors(error.children, path));
+        }
+    }
+    return result;
+}
+function parseStringMessage(message) {
+    // Attempt to extract field name and constraint from common class-validator messages
+    const patterns = [
+        { regex: /^(\w+) is required$/, constraint: 'required' },
+        { regex: /^(\w+) must be shorter/, constraint: 'maxLength' },
+        { regex: /^(\w+) must be longer/, constraint: 'minLength' },
+        { regex: /^(\w+) must not be less/, constraint: 'min' },
+        { regex: /^(\w+) must not be more/, constraint: 'max' },
+        { regex: /^(\w+) must be an? email/, constraint: 'isEmail' },
+        { regex: /^(\w+) must be an? valid phone/, constraint: 'isPhoneNumber' },
+        { regex: /^(\w+) must be one of the following/, constraint: 'isEnum' },
+        { regex: /^(\w+) must be an? Date/, constraint: 'isDate' },
+        { regex: /^(\w+) must be an? IBAN/, constraint: 'isIBAN' },
+        { regex: /^(\w+) must be an? EAN/, constraint: 'isEAN' },
+        { regex: /^(\w+) must be an? URL/, constraint: 'isUrl' },
+        { regex: /^(\w+) must be an? valid url/i, constraint: 'isUrl' },
+        { regex: /^(\w+) is not valid/i, constraint: 'invalid' },
+        { regex: /^(\w+) is already taken/i, constraint: 'unique' },
+        { regex: /^(\w+) is already used/i, constraint: 'unique' },
+        { regex: /^(\w+) must be a valid decimal/i, constraint: 'isDecimal' },
+    ];
+    for (const { regex, constraint } of patterns) {
+        const match = message.match(regex);
+        if (match) {
+            const field = match[1]
+                ? match[1].charAt(0).toLowerCase() + match[1].slice(1)
+                : 'unknown';
+            return [{ field, constraint, message }];
+        }
+    }
+    // Specific messages without a field name captured by regex
+    if (/^file is required/i.test(message)) {
+        return [{ field: 'file', constraint: 'required', message }];
+    }
+    return [];
+}
+/**
+ * Creates a class-validator / NestJS error preset.
+ *
+ * @param options.noInference - When true, skips constraint guessing for string messages.
+ *   Structured `constraints` objects (e.g. `{ isEmail: 'message' }`) are always used as-is.
+ *   Only affects the fallback string message parser.
+ *
+ * @example
+ * ```typescript
+ * import { classValidatorPreset } from 'ngx-api-forms';
+ *
+ * const bridge = createFormBridge(form, { preset: classValidatorPreset() });
+ *
+ * // No inference on string messages
+ * const bridge = createFormBridge(form, { preset: classValidatorPreset({ noInference: true }) });
+ * ```
+ */
+function classValidatorPreset(options) {
+    const skipInference = options?.noInference ?? false;
+    return {
+        name: 'class-validator',
+        constraintMap: CLASS_VALIDATOR_CONSTRAINT_MAP,
+        parse(error) {
+            if (!error || typeof error !== 'object')
+                return [];
+            const err = error;
+            // Standard NestJS ValidationPipe format: { message: ClassValidatorError[] }
+            if (Array.isArray(err['message'])) {
+                const messages = err['message'];
+                // Check if it's an array of ClassValidatorError objects
+                if (messages.length > 0 && typeof messages[0] === 'object' && 'property' in messages[0]) {
+                    return flattenErrors(messages);
+                }
+                // It might be an array of strings (simple messages)
+                if (messages.length > 0 && typeof messages[0] === 'string') {
+                    if (skipInference) {
+                        return messages.map(msg => ({ field: 'unknown', constraint: 'serverError', message: msg }));
+                    }
+                    const results = [];
+                    for (const msg of messages) {
+                        results.push(...parseStringMessage(msg));
+                    }
+                    return results;
+                }
+            }
+            // Single string message: { message: "email is required" }
+            if (typeof err['message'] === 'string') {
+                if (skipInference) {
+                    return [{ field: 'unknown', constraint: 'serverError', message: err['message'] }];
+                }
+                return parseStringMessage(err['message']);
+            }
+            // Direct array (no wrapper): [{ property: 'email', constraints: {...} }]
+            if (Array.isArray(error)) {
+                const items = error;
+                if (items.length > 0 && typeof items[0] === 'object' && items[0] !== null && 'property' in items[0]) {
+                    return flattenErrors(items);
+                }
+            }
+            return [];
+        },
+    };
+}
+/**
+ * Default constraint map for class-validator.
+ * Maps class-validator constraint names to Angular form error keys.
+ */
+const CLASS_VALIDATOR_CONSTRAINT_MAP = {
+    isNotEmpty: 'required',
+    isEmail: 'email',
+    minLength: 'minlength',
+    maxLength: 'maxlength',
+    min: 'min',
+    max: 'max',
+    isPhoneNumber: 'phone',
+    isEnum: 'enum',
+    isDate: 'date',
+    isDateString: 'date',
+    isIBAN: 'iban',
+    isEAN: 'ean',
+    isUrl: 'url',
+    isURL: 'url',
+    isDecimal: 'decimal',
+    isNumber: 'number',
+    isInt: 'integer',
+    isBoolean: 'boolean',
+    isString: 'string',
+    isArray: 'array',
+    arrayMinSize: 'minlength',
+    arrayMaxSize: 'maxlength',
+    matches: 'pattern',
+    isStrongPassword: 'password',
+    unique: 'unique',
+    invalid: 'invalid',
+    required: 'required',
+    serverError: 'serverError',
+};
+
+/**
+ * FormBridge - The core class of ngx-api-forms.
+ *
+ * Bridges API validation errors to Angular Reactive Forms with:
+ * - Automatic error parsing via presets (class-validator, Laravel, Django, Zod)
+ * - i18n-friendly error messages
+ * - Angular Signals support
+ * - SSR-safe operations
+ */
+/**
+ * FormBridge wraps an Angular FormGroup and provides a clean API
+ * for bridging API validation errors and managing form state.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new FormBridge(myForm, {
+ *   preset: classValidatorPreset(),
+ * });
+ *
+ * // Apply API errors
+ * bridge.applyApiErrors(err.error);
+ *
+ * // Use signals in templates
+ * readonly errors = bridge.errorsSignal;
+ * readonly firstError = bridge.firstErrorSignal;
+ * ```
+ */
+class FormBridge {
+    _form;
+    _presets;
+    _constraintMap;
+    _i18n;
+    _catchAll;
+    _mergeErrors;
+    _debug;
+    _interceptors = [];
+    /** Signal containing the last set of resolved API errors */
+    _apiErrors = signal([], ...(ngDevMode ? [{ debugName: "_apiErrors" }] : []));
+    /** Signal containing global (non-field) errors */
+    _globalErrors = signal([], ...(ngDevMode ? [{ debugName: "_globalErrors" }] : []));
+    /** Tracks which error keys were set by the API on each control */
+    _apiErrorKeys = new Map();
+    // ---- Public Signals ----
+    /** Reactive signal of all current API errors applied to the form */
+    errorsSignal = this._apiErrors.asReadonly();
+    /**
+     * Reactive signal of global (non-field) errors.
+     *
+     * Contains errors from:
+     * - Django `non_field_errors` / `detail`
+     * - Zod `formErrors`
+     * - Any API error whose field does not match a form control
+     */
+    globalErrorsSignal = this._globalErrors.asReadonly();
+    /** Reactive signal of the first error (or null) */
+    firstErrorSignal = computed(() => {
+        const errors = this._apiErrors();
+        return errors.length > 0 ? errors[0] : null;
+    }, ...(ngDevMode ? [{ debugName: "firstErrorSignal" }] : []));
+    /** Whether any API errors are currently applied */
+    hasErrorsSignal = computed(() => this._apiErrors().length > 0 || this._globalErrors().length > 0, ...(ngDevMode ? [{ debugName: "hasErrorsSignal" }] : []));
+    constructor(form, config) {
+        this._form = form;
+        this._catchAll = config?.catchAll ?? false;
+        this._mergeErrors = config?.mergeErrors ?? false;
+        this._debug = config?.debug ?? false;
+        this._i18n = config?.i18n;
+        // Resolve presets
+        if (config?.preset) {
+            this._presets = Array.isArray(config.preset) ? config.preset : [config.preset];
+        }
+        else {
+            this._presets = [classValidatorPreset()];
+        }
+        // Build constraint map: preset defaults + custom overrides
+        const presetDefaults = this._resolvePresetConstraintMap(this._presets);
+        this._constraintMap = {
+            ...presetDefaults,
+            ...(config?.constraintMap ?? {}),
+        };
+    }
+    // ---- Public API - Error Management ----
+    /**
+     * Parse and apply API validation errors to the form.
+     *
+     * Tries each configured preset in order until one returns results.
+     * Errors are mapped to Angular form control errors.
+     *
+     * @param apiError - The raw error body from the API (e.g. `err.error`)
+     * @returns The array of resolved field errors that were applied
+     */
+    applyApiErrors(apiError) {
+        let fieldErrors = [];
+        // Try each preset until one returns results
+        for (const preset of this._presets) {
+            fieldErrors = preset.parse(apiError);
+            if (fieldErrors.length > 0)
+                break;
+        }
+        if (this._debug && fieldErrors.length === 0) {
+            console.warn('[ngx-api-forms] No preset produced results for the given error payload.', 'Presets tried:', this._presets.map(p => p.name).join(', '), 'Payload:', apiError);
+        }
+        // Run interceptors
+        for (const interceptor of this._interceptors) {
+            fieldErrors = interceptor(fieldErrors, this._form);
+        }
+        // Map and apply to form
+        const resolved = this._applyErrors(fieldErrors);
+        this._apiErrors.set(resolved);
+        return resolved;
+    }
+    /**
+     * Clear only the errors that were set by `applyApiErrors()`.
+     * Client-side validation errors (e.g. `Validators.required`) are preserved.
+     */
+    clearApiErrors() {
+        for (const [control, keys] of this._apiErrorKeys) {
+            if (!control.errors)
+                continue;
+            const remaining = { ...control.errors };
+            for (const key of keys) {
+                delete remaining[key];
+            }
+            control.setErrors(Object.keys(remaining).length > 0 ? remaining : null);
+            control.updateValueAndValidity();
+        }
+        this._apiErrorKeys.clear();
+        this._form.updateValueAndValidity({ onlySelf: false, emitEvent: true });
+        this._apiErrors.set([]);
+        this._globalErrors.set([]);
+    }
+    /**
+     * Get the first error across all form controls.
+     */
+    getFirstError() {
+        // Check API errors first
+        const apiErrors = this._apiErrors();
+        if (apiErrors.length > 0) {
+            return apiErrors[0];
+        }
+        // Fall back to client-side validation errors
+        for (const key of Object.keys(this._form.controls)) {
+            const control = this._form.controls[key];
+            if (control?.errors) {
+                const errorKeys = Object.keys(control.errors);
+                if (errorKeys.length > 0) {
+                    const errorKey = errorKeys[0];
+                    const errorValue = control.errors[errorKey];
+                    return {
+                        field: key,
+                        errorKey,
+                        message: typeof errorValue === 'string' ? errorValue : errorKey,
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Get all errors for a specific field.
+     */
+    getFieldErrors(fieldName) {
+        return this._form.controls[fieldName]?.errors ?? null;
+    }
+    /**
+     * Register an error interceptor that can modify or filter errors
+     * before they are applied to the form.
+     * Returns a dispose function to remove the interceptor.
+     */
+    addInterceptor(interceptor) {
+        this._interceptors.push(interceptor);
+        return () => {
+            this._interceptors = this._interceptors.filter(i => i !== interceptor);
+        };
+    }
+    // ---- Public API - Utilities ----
+    /**
+     * Access the underlying FormGroup.
+     */
+    get form() {
+        return this._form;
+    }
+    // ---- Private Methods ----
+    _resolvePresetConstraintMap(presets) {
+        const merged = {};
+        for (const preset of presets) {
+            if (preset.constraintMap)
+                Object.assign(merged, preset.constraintMap);
+        }
+        // If no preset provided a constraint map, fall back to class-validator
+        if (Object.keys(merged).length === 0) {
+            Object.assign(merged, CLASS_VALIDATOR_CONSTRAINT_MAP);
+        }
+        return merged;
+    }
+    _applyErrors(fieldErrors) {
+        const resolved = [];
+        const globalErrors = [];
+        // Accumulate errors per control to avoid overwrite within a single applyApiErrors call
+        const pendingErrors = new Map();
+        for (const fieldError of fieldErrors) {
+            // Global errors (explicit sentinel or unmatched field)
+            if (fieldError.field === GLOBAL_ERROR_FIELD) {
+                globalErrors.push({
+                    message: fieldError.message,
+                    constraint: fieldError.constraint,
+                });
+                continue;
+            }
+            let control = this._form.controls[fieldError.field] ?? null;
+            if (!control) {
+                // Try nested path (e.g. 'address.city' or 'items.0.name')
+                control = this._resolveNestedControl(fieldError.field);
+                if (!control) {
+                    // Route unmatched field errors to global errors
+                    globalErrors.push({
+                        message: fieldError.message,
+                        constraint: fieldError.constraint,
+                        originalField: fieldError.field,
+                    });
+                    if (this._debug) {
+                        console.warn(`[ngx-api-forms] Field "${fieldError.field}" does not match any form control - routed to globalErrorsSignal.`, 'Available controls:', Object.keys(this._form.controls).join(', '));
+                    }
+                    continue;
+                }
+            }
+            const errorKey = this._resolveErrorKey(fieldError.constraint);
+            const message = this._resolveMessage(fieldError);
+            if (!errorKey && !this._catchAll)
+                continue;
+            const finalErrorKey = errorKey || 'generic';
+            // Deduplicate: if the same key already exists on this control, suffix it
+            const existing = pendingErrors.get(control) ?? (this._mergeErrors ? (control.errors ?? {}) : {});
+            let uniqueKey = finalErrorKey;
+            if (existing[uniqueKey] !== undefined) {
+                let idx = 1;
+                while (existing[`${finalErrorKey}_${idx}`] !== undefined)
+                    idx++;
+                uniqueKey = `${finalErrorKey}_${idx}`;
+            }
+            pendingErrors.set(control, { ...existing, [uniqueKey]: message });
+            // Track this key as API-set
+            if (!this._apiErrorKeys.has(control)) {
+                this._apiErrorKeys.set(control, new Set());
+            }
+            this._apiErrorKeys.get(control).add(uniqueKey);
+            resolved.push({ field: fieldError.field, errorKey: uniqueKey, message });
+        }
+        // Apply accumulated errors once per control
+        for (const [control, errors] of pendingErrors) {
+            control.markAsTouched();
+            control.setErrors(errors);
+        }
+        // Publish global errors
+        this._globalErrors.set(globalErrors);
+        return resolved;
+    }
+    _resolveNestedControl(path) {
+        const parts = path.split('.');
+        let current = this._form;
+        for (const part of parts) {
+            if (current instanceof FormGroup) {
+                const child = current.controls[part];
+                if (!child)
+                    return null;
+                current = child;
+            }
+            else if (current instanceof FormArray) {
+                const index = parseInt(part, 10);
+                if (isNaN(index) || index < 0 || index >= current.length)
+                    return null;
+                current = current.at(index);
+            }
+            else {
+                return null;
+            }
+        }
+        return current;
+    }
+    _resolveErrorKey(constraint) {
+        // If constraint is in the map, use the mapped value.
+        // Otherwise, use the constraint as-is (pass-through).
+        // This returns '' only when constraint is empty.
+        if (this._constraintMap[constraint] !== undefined) {
+            return this._constraintMap[constraint];
+        }
+        return constraint;
+    }
+    _resolveMessage(error) {
+        if (this._i18n?.resolver) {
+            const resolved = this._i18n.resolver(error.field, error.constraint, error.message);
+            if (resolved !== null)
+                return resolved;
+        }
+        if (this._i18n?.prefix) {
+            // Return the i18n key (to be resolved by the consumer's i18n system)
+            return `${this._i18n.prefix}.${error.field}.${error.constraint}`;
+        }
+        return error.message;
+    }
+}
+function createFormBridge(form, config) {
+    return new FormBridge(form, config);
+}
+function provideFormBridge(form, config) {
+    return new FormBridge(form, config);
+}
+
+/**
+ * NgxFormError directive.
+ *
+ * Automatically displays the error message for a form control.
+ * Works with both client-side validators and API errors set by FormBridge.
+ *
+ * @example
+ * ```html
+ * <input formControlName="email" />
+ * <span ngxFormError="email" [form]="myForm"></span>
+ * <!-- Displays: "email must be a valid email" -->
+ *
+ * <!-- With custom error map -->
+ * <span ngxFormError="email"
+ *       [form]="myForm"
+ *       [errorMessages]="{ required: 'Email is required', email: 'Invalid email' }">
+ * </span>
+ * ```
+ */
+class NgxFormErrorDirective {
+    el = inject(ElementRef);
+    renderer = inject(Renderer2);
+    destroyRef = inject(DestroyRef);
+    resubscribe$ = new Subject();
+    /** The form control name to observe */
+    controlName;
+    /** The parent FormGroup */
+    form;
+    /**
+     * Optional map of error keys to display messages.
+     * If not provided, the raw error value is used (which is the API message
+     * when set by FormBridge).
+     */
+    errorMessages;
+    /**
+     * CSS class applied to the host element when an error is displayed.
+     * Default: 'ngx-form-error-visible'
+     */
+    errorClass = 'ngx-form-error-visible';
+    /**
+     * Whether to show errors only when the control is touched.
+     * Default: true
+     */
+    showOnTouched = true;
+    ngOnInit() {
+        this._subscribe();
+    }
+    ngOnChanges(changes) {
+        if ((changes['form'] || changes['controlName']) && !changes['form']?.firstChange) {
+            this._subscribe();
+        }
+    }
+    _subscribe() {
+        // Signal existing subscription to complete
+        this.resubscribe$.next();
+        const control = this.form?.get(this.controlName);
+        if (!control) {
+            this._hide();
+            return;
+        }
+        merge(control.statusChanges, control.valueChanges).pipe(takeUntil(this.resubscribe$), takeUntilDestroyed(this.destroyRef)).subscribe(() => {
+            this._updateDisplay(control);
+        });
+        this._updateDisplay(control);
+    }
+    _updateDisplay(control) {
+        if (!control.errors || (this.showOnTouched && !control.touched && !control.dirty)) {
+            this._hide();
+            return;
+        }
+        const errorKeys = Object.keys(control.errors);
+        if (errorKeys.length === 0) {
+            this._hide();
+            return;
+        }
+        const firstKey = errorKeys[0];
+        const rawValue = control.errors[firstKey];
+        let message;
+        // Priority: custom errorMessages map > raw string value > error key
+        if (this.errorMessages?.[firstKey]) {
+            message = this.errorMessages[firstKey];
+        }
+        else if (typeof rawValue === 'string') {
+            message = rawValue;
+        }
+        else {
+            message = firstKey;
+        }
+        this._show(message);
+    }
+    _show(message) {
+        const el = this.el.nativeElement;
+        this.renderer.setProperty(el, 'textContent', message);
+        this.renderer.addClass(el, this.errorClass);
+        this.renderer.setStyle(el, 'display', '');
+    }
+    _hide() {
+        const el = this.el.nativeElement;
+        this.renderer.setProperty(el, 'textContent', '');
+        this.renderer.removeClass(el, this.errorClass);
+        this.renderer.setStyle(el, 'display', 'none');
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.16", ngImport: i0, type: NgxFormErrorDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "20.3.16", type: NgxFormErrorDirective, isStandalone: true, selector: "[ngxFormError]", inputs: { controlName: ["ngxFormError", "controlName"], form: "form", errorMessages: "errorMessages", errorClass: "errorClass", showOnTouched: "showOnTouched" }, usesOnChanges: true, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.16", ngImport: i0, type: NgxFormErrorDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[ngxFormError]',
+                    standalone: true,
+                }]
+        }], propDecorators: { controlName: [{
+                type: Input,
+                args: ['ngxFormError']
+            }], form: [{
+                type: Input
+            }], errorMessages: [{
+                type: Input
+            }], errorClass: [{
+                type: Input
+            }], showOnTouched: [{
+                type: Input
+            }] } });
+
+/**
+ * Parse raw API error body into normalized field errors without touching any form.
+ * Tries each preset in order until one returns results.
+ *
+ * Use this when you only need the parsing logic (e.g. in an HttpInterceptor,
+ * a store effect, or any context where you don't have a FormBridge).
+ *
+ * @param apiError - The raw error body from the API (e.g. `err.error`)
+ * @param preset - One or more presets to try. Defaults to class-validator.
+ * @param options - Optional settings. `debug: true` logs a warning when no preset matches.
+ * @returns Normalized array of field errors
+ *
+ * @example
+ * ```typescript
+ * import { parseApiErrors } from 'ngx-api-forms';
+ * import { laravelPreset } from 'ngx-api-forms/laravel';
+ *
+ * const errors = parseApiErrors(err.error, laravelPreset());
+ * // [{ field: 'email', constraint: 'required', message: 'The email field is required.' }]
+ * ```
+ */
+function parseApiErrors(apiError, preset, options) {
+    const presets = preset
+        ? (Array.isArray(preset) ? preset : [preset])
+        : [classValidatorPreset()];
+    for (const p of presets) {
+        const result = p.parse(apiError);
+        if (result.length > 0)
+            return result;
+    }
+    if (options?.debug) {
+        console.warn('[ngx-api-forms] parseApiErrors: no preset produced results.', 'Presets tried:', presets.map(p => p.name).join(', '), 'Payload:', apiError);
+    }
+    return [];
+}
+/**
+ * Wrap an Observable with form submit lifecycle management.
+ *
+ * Standalone submit helper. Useful when you want disable/enable lifecycle
+ * without a full FormBridge instance.
+ *
+ * - Disables the form before subscribing
+ * - Re-enables the form on success or error
+ * - Returns the original Observable (errors are re-thrown)
+ *
+ * @param form - The FormGroup to manage
+ * @param source - The Observable to wrap (e.g. HttpClient call)
+ * @param options.onError - Callback invoked with the error before re-throwing
+ * @returns The wrapped Observable
+ *
+ * @example
+ * ```typescript
+ * import { wrapSubmit } from 'ngx-api-forms';
+ *
+ * wrapSubmit(this.form, this.http.post('/api', data), {
+ *   onError: (err) => this.bridge.applyApiErrors(err.error),
+ * }).subscribe();
+ * ```
+ */
+function wrapSubmit(form, source, options) {
+    form.disable();
+    return source.pipe(tap(() => form.enable()), catchError((err) => {
+        form.enable();
+        options?.onError?.(err);
+        throw err;
+    }));
+}
+/**
+ * Convert a plain object to FormData.
+ * Handles Files, Blobs, Arrays, Dates, nested objects.
+ */
+function toFormData(data) {
+    const formData = new FormData();
+    for (const [key, value] of Object.entries(data)) {
+        if (value === null || value === undefined)
+            continue;
+        if (value instanceof File || value instanceof Blob) {
+            formData.append(key, value);
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item instanceof File || item instanceof Blob) {
+                    formData.append(key, item);
+                }
+                else if (typeof item === 'object' && item !== null) {
+                    formData.append(key, JSON.stringify(item));
+                }
+                else {
+                    formData.append(key, String(item));
+                }
+            }
+            continue;
+        }
+        if (value instanceof Date) {
+            formData.append(key, value.toISOString());
+            continue;
+        }
+        if (typeof value === 'object') {
+            formData.append(key, JSON.stringify(value));
+            continue;
+        }
+        formData.append(key, String(value));
+    }
+    return formData;
+}
+/**
+ * Enable all controls in a form, with optional exceptions.
+ */
+function enableForm(form, options) {
+    for (const key of Object.keys(form.controls)) {
+        if (options?.except?.includes(key))
+            continue;
+        form.controls[key].enable();
+    }
+    form.updateValueAndValidity({ onlySelf: false, emitEvent: true });
+}
+/**
+ * Disable all controls in a form, with optional exceptions.
+ */
+function disableForm(form, options) {
+    for (const key of Object.keys(form.controls)) {
+        if (options?.except?.includes(key))
+            continue;
+        form.controls[key].disable();
+    }
+}
+/**
+ * Reset all errors on a form's controls (client-side and API).
+ */
+function clearFormErrors(form) {
+    for (const key of Object.keys(form.controls)) {
+        form.controls[key].setErrors(null);
+        form.controls[key].updateValueAndValidity();
+    }
+    form.updateValueAndValidity({ onlySelf: false, emitEvent: true });
+}
+/**
+ * Get a flat record of only the dirty (changed) fields.
+ */
+function getDirtyValues(form) {
+    const result = {};
+    for (const key of Object.keys(form.controls)) {
+        if (form.controls[key].dirty) {
+            result[key] = form.controls[key].value;
+        }
+    }
+    return result;
+}
+/**
+ * Check if any control in the form has a specific error key.
+ */
+function hasError(form, errorKey) {
+    for (const key of Object.keys(form.controls)) {
+        if (form.controls[key].hasError(errorKey)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get the error message for a specific field and error key.
+ * Returns the error value if it's a string, otherwise the error key.
+ */
+function getErrorMessage(form, fieldName, errorKey) {
+    const control = form.controls[fieldName];
+    if (!control?.errors)
+        return null;
+    if (errorKey) {
+        const value = control.errors[errorKey];
+        return value ? (typeof value === 'string' ? value : errorKey) : null;
+    }
+    // Return first error
+    const keys = Object.keys(control.errors);
+    if (keys.length === 0)
+        return null;
+    const firstValue = control.errors[keys[0]];
+    return typeof firstValue === 'string' ? firstValue : keys[0];
+}
+
+/**
+ * Angular HttpInterceptorFn that automatically applies API validation errors
+ * to a FormBridge instance attached via HttpContext.
+ *
+ * Two usage patterns:
+ * 1. Per-request: tag individual requests with `withFormBridge(bridge)` --
+ *    the interceptor catches 422/400 and calls `bridge.applyApiErrors()`.
+ * 2. Global: provide a custom `onError` callback in the interceptor config
+ *    to centralize error handling (e.g. dispatch to a store or service).
+ */
+/**
+ * HttpContext token that carries a FormBridge reference on a request.
+ * Used by `withFormBridge()` to tag requests for automatic error handling.
+ */
+const FORM_BRIDGE = new HttpContextToken(() => null);
+/**
+ * Create an Angular functional HTTP interceptor that handles API validation errors.
+ *
+ * When a response matches one of the configured status codes (default: 422, 400):
+ * - If the request was tagged with `withFormBridge(bridge)`, errors are automatically
+ *   applied to that bridge. Zero code needed in `subscribe()`.
+ * - If an `onError` callback is provided, it is called with the parsed errors for
+ *   global handling (store, toast, logging, etc.).
+ * - The error is always re-thrown so downstream `catchError` or `error` callbacks
+ *   still fire when needed.
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * import { provideHttpClient, withInterceptors } from '@angular/common/http';
+ * import { apiErrorInterceptor } from 'ngx-api-forms';
+ *
+ * export const appConfig = {
+ *   providers: [
+ *     provideHttpClient(
+ *       withInterceptors([apiErrorInterceptor()])
+ *     ),
+ *   ],
+ * };
+ *
+ * // component.ts -- zero error handling code
+ * this.http.post('/api/save', data, withFormBridge(this.bridge)).subscribe({
+ *   next: () => this.router.navigate(['/done']),
+ * });
+ * ```
+ */
+function apiErrorInterceptor(config) {
+    const statusCodes = config?.statusCodes ?? [422, 400];
+    const fallbackPreset = config?.preset ?? classValidatorPreset();
+    return (req, next) => {
+        return next(req).pipe(catchError((error) => {
+            if (statusCodes.includes(error.status)) {
+                const bridge = req.context.get(FORM_BRIDGE);
+                if (bridge) {
+                    bridge.applyApiErrors(error.error);
+                }
+                if (config?.onError) {
+                    const parsed = bridge
+                        ? bridge.errorsSignal()
+                        : parseApiErrors(error.error, fallbackPreset);
+                    config.onError(parsed, error);
+                }
+            }
+            return throwError(() => error);
+        }));
+    };
+}
+/**
+ * Attach a FormBridge to an HTTP request via HttpContext.
+ *
+ * When used with `apiErrorInterceptor`, the interceptor automatically calls
+ * `bridge.applyApiErrors()` on 422/400 responses. No error handling needed
+ * in `subscribe()`.
+ *
+ * @param bridge - The FormBridge instance to receive API errors
+ * @returns An options object to spread into HttpClient methods
+ *
+ * @example
+ * ```typescript
+ * // Errors are applied automatically -- no subscribe error handler needed
+ * this.http.post('/api/save', data, withFormBridge(this.bridge)).subscribe();
+ *
+ * // Works with all HttpClient methods
+ * this.http.put('/api/users/1', data, withFormBridge(this.bridge)).subscribe();
+ * ```
+ */
+function withFormBridge(bridge) {
+    return {
+        context: new HttpContext().set(FORM_BRIDGE, bridge),
+    };
+}
+
+/*
+ * Public API Surface of ngx-api-forms
+ */
+// Models and types
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { CLASS_VALIDATOR_CONSTRAINT_MAP, FORM_BRIDGE, FormBridge, GLOBAL_ERROR_FIELD, NgxFormErrorDirective, apiErrorInterceptor, classValidatorPreset, clearFormErrors, createFormBridge, disableForm, enableForm, getDirtyValues, getErrorMessage, hasError, parseApiErrors, provideFormBridge, toFormData, withFormBridge, wrapSubmit };
+//# sourceMappingURL=ngx-api-forms.mjs.map