@ng-simplicity/forms-core 1.1.4 → 1.1.5

package/README.md

@@ -15,7 +15,7 @@ This core package is extended by styling integration packages that provide prebu
 
 | Package | Package version | Angular support |
 |---|---:|---|
-| `@ng-simplicity/forms-core` | `1.1.4` | `17.x`–`22.x` |
+| `@ng-simplicity/forms-core` | `1.1.5` | `17.x`–`22.x` |
 
 ---
 
@@ -46,7 +46,8 @@ Each `registerAll…` helper also registers the core structural components, so i
 ### 1. The Public Boundary: `NgsFormsService`
 - Injected by the user's component page.
 - Exposes form values and statuses through Signals and observables (e.g. `formValue$`, `dirty`, `isValid`).
-- Provides entry methods like `setFormConfig(config)` and `patchValue(data)`.
+- Provides entry methods like `setFormConfig(config)`, `patchValue(data)` and `setServerErrorMessages(errors)`.
+- `patchValue(data)` can be called straight after `setFormConfig()`: it keeps the patch and re-applies it as controls render, including fields that the patched values reveal through `visible$`, until the form settles. Form arrays need enough rows (`initialItemCount`).
 - Implements a retry loading mechanism in case child elements compile asynchronously.
 
 ### 2. The Internal Coordinator: `NgsFormsInternalService`
@@ -217,6 +218,18 @@ Each form control component that extends `NgsFormsFormItemWithVisibleAndValidato
    }
    ```
 3. **Displaying Errors**: Within your custom component template, bind your error display element to the `errorMessage` property inherited from the base class. The core engine dynamically updates `errorMessage` based on whether the control is invalid, touched, dirty, or if the form has been submitted.
+4. **Server Errors**: Pass the server's errors to `NgsFormsService.setServerErrorMessages()` in the same shape as the form value. Each leaf is a key looked up in that field's `errorMessageMap` (a key with no entry is shown as text), and form array rows are matched by index. Each error clears when its field changes, and the call returns the paths that matched no control. `constructServerErrorMessageObject()` builds the object from a list of `{ jsonPath, validator }` pairs:
+   ```typescript
+   errorMessageMap: { taken: 'User Name Not Available' }
+
+   this.formsService.setServerErrorMessages({ registration: { userName: 'taken', contacts: [{}, {}, { phone: 'invalidPhone' }] } });
+
+   // Same thing from a flat list:
+   this.formsService.setServerErrorMessages(constructServerErrorMessageObject([
+     { jsonPath: 'registration.userName', validator: 'taken' },
+     { jsonPath: 'registration.contacts[2].phone', validator: 'invalidPhone' },
+   ]));
+   ```
 
 ---
 

package/fesm2022/ng-simplicity-forms-core.mjs

@@ -2,8 +2,8 @@ import { Subject, takeUntil, BehaviorSubject, switchMap, defer, map, distinctUnt
 import * as i0 from '@angular/core';
 import { Directive, InjectionToken, inject, Injectable, ChangeDetectorRef, Injector, ViewContainerRef, Input, computed, ChangeDetectionStrategy, Component, ElementRef, afterNextRender, Sanitizer, SecurityContext, NgModule } from '@angular/core';
 import { v4 } from 'uuid';
+import { FormArray, FormGroup, UntypedFormGroup, FormControl, Validators, UntypedFormArray, FormsModule, ReactiveFormsModule } from '@angular/forms';
 import { toSignal } from '@angular/core/rxjs-interop';
-import { UntypedFormGroup, FormControl, Validators, FormGroup, FormArray, UntypedFormArray, FormsModule, ReactiveFormsModule } from '@angular/forms';
 import { CommonModule } from '@angular/common';
 
 /** Base class that ties RxJS subscriptions to the component's lifetime. */
@@ -77,6 +77,202 @@ function ngsDefaults(target, ...sources) {
     return result;
 }
 
+/**
+ * Builds the object for `NgsFormsService.setServerErrorMessages()` from a flat list of paths and error keys, for
+ * APIs that return their errors that way. Array indexes create arrays, and rows without errors are filled with `{}`.
+ * Two errors on the same path become an array of keys.
+ *
+ * @example
+ * ```ts
+ * constructServerErrorMessageObject([
+ *   { jsonPath: 'registration.userName', validator: 'taken' },
+ *   { jsonPath: 'registration.contacts[2].phone', validator: 'invalidPhone' },
+ * ]);
+ * // { registration: { userName: 'taken', contacts: [{}, {}, { phone: 'invalidPhone' }] } }
+ * ```
+ */
+function constructServerErrorMessageObject(errors) {
+    const result = {};
+    for (const { jsonPath, validator } of errors) {
+        const segments = parseJsonPath(jsonPath);
+        if (!segments.length || !validator)
+            continue;
+        let node = result;
+        segments.forEach((segment, i) => {
+            const isLast = i === segments.length - 1;
+            if (Array.isArray(node) && typeof segment === 'number') {
+                while (node.length < segment)
+                    node.push({});
+            }
+            if (isLast) {
+                const existing = node[segment];
+                if (typeof existing === 'string') {
+                    node[segment] = existing === validator ? existing : [existing, validator];
+                }
+                else if (Array.isArray(existing) && existing.every((e) => typeof e === 'string')) {
+                    if (!existing.includes(validator))
+                        existing.push(validator);
+                }
+                else {
+                    node[segment] = validator;
+                }
+                return;
+            }
+            const nextIsIndex = typeof segments[i + 1] === 'number';
+            const existing = node[segment];
+            if (existing === undefined || existing === null || typeof existing !== 'object') {
+                node[segment] = nextIsIndex ? [] : {};
+            }
+            else if (nextIsIndex && !Array.isArray(existing) && Object.keys(existing).length === 0) {
+                // A `{}` placeholder for an array row that is itself an array.
+                node[segment] = [];
+            }
+            node = node[segment];
+        });
+    }
+    return result;
+}
+/** Splits `a.b[2]['c d']` into `['a', 'b', 2, 'c d']`. */
+function parseJsonPath(jsonPath) {
+    const path = (jsonPath ?? '').trim().replace(/^\$\.?/, '');
+    const segments = [];
+    const pattern = /\[\s*(\d+)\s*\]|\[\s*(['"])(.*?)\2\s*\]|([^.[\]]+)/g;
+    let match;
+    while ((match = pattern.exec(path)) !== null) {
+        if (match[1] !== undefined)
+            segments.push(Number(match[1]));
+        else if (match[3] !== undefined)
+            segments.push(match[3]);
+        else if (match[4] !== undefined)
+            segments.push(match[4]);
+    }
+    return segments;
+}
+/**
+ * Marker on the error value of a server error (`control.errors[key][NGS_FORMS_SERVER_ERROR] === true`). When the
+ * key has no entry in `errorMessageMap`, the key itself is shown as the message, so servers can send message text.
+ */
+const NGS_FORMS_SERVER_ERROR = 'ngsServerError';
+/**
+ * Applies server errors to a form and clears each one when its control's value changes.
+ *
+ * @internal Used by `NgsFormsService`.
+ */
+class NgsFormsServerErrorRegistry {
+    entries = new Map();
+    /**
+     * Validator that reports a control's server errors. Form items include it whenever they set their validators,
+     * so the errors survive re-validation until the control's value changes.
+     */
+    validator = (control) => this.validate(control);
+    /** `true` while at least one server error is set. */
+    get hasErrors() {
+        return this.entries.size > 0;
+    }
+    /** Replaces every server error with `errors`. Returns the paths that matched no control. */
+    set(root, errors) {
+        this.clear();
+        const unmatched = [];
+        this.apply(root, errors, '', unmatched);
+        return unmatched;
+    }
+    /** Removes every server error. */
+    clear() {
+        if (!this.entries.size)
+            return;
+        const controls = Array.from(this.entries.keys());
+        this.entries.clear();
+        controls.forEach((control) => control.updateValueAndValidity());
+    }
+    /** Forgets every server error without re-validating, for when the controls are being thrown away. */
+    reset() {
+        this.entries.clear();
+    }
+    apply(control, errors, path, unmatched) {
+        if (errors === null || errors === undefined)
+            return;
+        if (typeof errors === 'string' || (Array.isArray(errors) && errors.length > 0 && errors.every((e) => typeof e === 'string'))) {
+            this.applyKeys(control, typeof errors === 'string' ? [errors] : errors);
+            return;
+        }
+        if (Array.isArray(errors)) {
+            if (!(control instanceof FormArray)) {
+                if (errors.some((e) => !isEmpty(e)))
+                    unmatched.push(path);
+                return;
+            }
+            errors.forEach((rowErrors, index) => {
+                if (isEmpty(rowErrors))
+                    return;
+                const row = control.at(index);
+                const rowPath = `${path}[${index}]`;
+                if (!row) {
+                    unmatched.push(rowPath);
+                    return;
+                }
+                this.apply(row, rowErrors, rowPath, unmatched);
+            });
+            return;
+        }
+        if (!(control instanceof FormGroup)) {
+            if (!isEmpty(errors))
+                unmatched.push(path);
+            return;
+        }
+        for (const [name, childErrors] of Object.entries(errors)) {
+            if (isEmpty(childErrors))
+                continue;
+            const childPath = path ? `${path}.${name}` : name;
+            const child = control.get([name]);
+            if (!child) {
+                unmatched.push(childPath);
+                continue;
+            }
+            this.apply(child, childErrors, childPath, unmatched);
+        }
+    }
+    applyKeys(control, keys) {
+        this.entries.set(control, { keys, value: control.value });
+        if (!control.hasValidator(this.validator)) {
+            control.addValidators(this.validator);
+        }
+        // Show the message straight away, without waiting for the user to touch the field.
+        control.markAsTouched();
+        control.updateValueAndValidity();
+    }
+    validate(control) {
+        const entry = this.entries.get(control);
+        if (!entry)
+            return null;
+        if (!sameValue(control.value, entry.value)) {
+            this.entries.delete(control);
+            return null;
+        }
+        return Object.fromEntries(entry.keys.map((key) => [key, { [NGS_FORMS_SERVER_ERROR]: true }]));
+    }
+}
+function isEmpty(errors) {
+    if (errors === null || errors === undefined || errors === '')
+        return true;
+    if (Array.isArray(errors))
+        return errors.every(isEmpty);
+    if (typeof errors === 'object')
+        return Object.values(errors).every(isEmpty);
+    return false;
+}
+function sameValue(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+
 /**
  * Root base class for every form item component. Reads the item's configuration from `NGS_FORMS_ITEM_DATA`.
  *
@@ -175,6 +371,14 @@ class NgsFormsService {
     lastConfig;
     missingFormTimer;
     destroyed = false;
+    /** Patches still being applied while the form renders, in call order. */
+    pendingPatches = [];
+    patchTimer;
+    /** The controls that existed when the pending patches were last applied. */
+    patchedStructure;
+    patchRounds = 0;
+    /** Render passes in a row in which no control was added or removed. */
+    stablePatchRounds = 0;
     /** `true` once the user has changed any control in the form. */
     get dirty() {
         return this.formGroup?.dirty ?? false;
@@ -198,6 +402,8 @@ class NgsFormsService {
      */
     setFormConfig(formConfig) {
         this.lastConfig = formConfig;
+        // Patches made for the previous form do not carry over. Patches made after this call are kept until it renders.
+        this.cancelPendingPatches();
         if (this.internalServiceIsSet) {
             this.internalFormService.setFormData(formConfig);
             return;
@@ -221,6 +427,9 @@ class NgsFormsService {
         if (this.lastConfig) {
             internalFormsService.setFormData(this.lastConfig);
         }
+        if (this.pendingPatches.length) {
+            this.schedulePatchRound();
+        }
     }
     /**
      * @internal
@@ -270,17 +479,103 @@ class NgsFormsService {
         this.destroyed = true;
         clearTimeout(this.missingFormTimer);
         this.missingFormTimer = undefined;
+        this.cancelPendingPatches();
         this.formGroupBinding?.unsubscribe();
         this.formValue$.complete();
     }
+    /**
+     * Shows errors from the server on the matching controls, replacing any server errors shown before.
+     *
+     * @param errors - An object shaped like the form value (including the root group name) whose leaves are error
+     * keys, for example `{ registration: { userName: 'taken', contacts: [{}, {}, { phone: 'invalid' }] } }`. Each key
+     * is looked up in that control's `errorMessageMap`; when it has no entry the key itself is shown, so the server
+     * can also send the message text. Use `constructServerErrorMessageObject()` to build it from a list of paths.
+     * @returns The paths that matched no rendered control (a hidden item or a missing array row, for example), so you
+     * can show those errors elsewhere.
+     *
+     * @remarks The controls are marked as touched so the messages show at once, and they stay invalid until their
+     * value changes. All server errors are cleared by the next call, by `clearServerErrorMessages()`, by
+     * `setFormConfig()`, and when rows are added to or removed from a form array, because rows are matched by index.
+     */
+    setServerErrorMessages(errors) {
+        if (!this.internalFormService) {
+            console.error('setServerErrorMessages() was called before <ngs-form> connected.');
+            return [];
+        }
+        return this.internalFormService.serverErrors.set(this.formGroup, errors);
+    }
+    /** Removes every error set with `setServerErrorMessages()`. */
+    clearServerErrorMessages() {
+        this.internalFormService?.serverErrors.clear();
+    }
     /**
      * Patches values into the form, using the same shape as `formValue$` (including the root group name).
      *
-     * @remarks Only controls that are currently rendered receive values. Patch again after a conditional item becomes
-     * visible, and make sure a form array has enough rows (see `initialItemCount`) before patching array values.
+     * @remarks It is safe to call straight after `setFormConfig()`, or before `<ngs-form>` has connected. The values
+     * are applied at once to the controls that exist, kept, and applied again each time new controls appear, until
+     * the form stops changing. That covers items that render later and items behind `visible$` that the patched values
+     * themselves reveal (and anything those reveal in turn). Later calls are applied after earlier ones. A form array
+     * only receives values for rows it has, so give it enough rows with `initialItemCount`. `setFormConfig()` drops
+     * patches that are still being applied to the previous form.
      */
     patchValue(entityData) {
-        this.formGroup.patchValue(entityData);
+        this.pendingPatches.push(entityData);
+        this.applyPendingPatches();
+        this.patchRounds = 0;
+        this.stablePatchRounds = 0;
+        this.schedulePatchRound();
+    }
+    /** Maximum number of render passes a patch waits for new controls before it is dropped. */
+    static MAX_PATCH_ROUNDS = 20;
+    applyPendingPatches() {
+        for (const patch of this.pendingPatches) {
+            this.formGroup.patchValue(patch);
+        }
+        this.patchedStructure = this.internalServiceIsSet ? controlStructure(this.formGroup) : undefined;
+    }
+    /**
+     * Waits one render pass, then re-applies the pending patches if controls were added or removed. Stops once two
+     * passes in a row change nothing (rendering can take a pass to start), or after `MAX_PATCH_ROUNDS` passes. Waits
+     * without counting while no form is connected.
+     */
+    schedulePatchRound() {
+        clearTimeout(this.patchTimer);
+        if (this.destroyed || !this.pendingPatches.length)
+            return;
+        if (!this.internalServiceIsSet) {
+            // `setInternalService()` starts the rounds once <ngs-form> connects.
+            this.patchTimer = undefined;
+            return;
+        }
+        this.patchTimer = setTimeout(() => {
+            this.patchTimer = undefined;
+            if (this.destroyed || !this.internalServiceIsSet)
+                return;
+            const structure = controlStructure(this.formGroup);
+            if (structure === this.patchedStructure) {
+                if (++this.stablePatchRounds >= 2) {
+                    this.cancelPendingPatches();
+                    return;
+                }
+                this.schedulePatchRound();
+                return;
+            }
+            this.stablePatchRounds = 0;
+            this.applyPendingPatches();
+            if (++this.patchRounds >= NgsFormsService.MAX_PATCH_ROUNDS) {
+                this.cancelPendingPatches();
+                return;
+            }
+            this.schedulePatchRound();
+        });
+    }
+    cancelPendingPatches() {
+        clearTimeout(this.patchTimer);
+        this.patchTimer = undefined;
+        this.pendingPatches = [];
+        this.patchedStructure = undefined;
+        this.patchRounds = 0;
+        this.stablePatchRounds = 0;
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsService });
@@ -288,6 +583,18 @@ class NgsFormsService {
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsService, decorators: [{
             type: Injectable
         }] });
+/** A string listing the paths of every control under `control`, so a change in the form's controls can be seen. */
+function controlStructure(control, path = '') {
+    if (control instanceof FormGroup) {
+        return Object.keys(control.controls)
+            .map((name) => controlStructure(control.controls[name], `${path}.${name}`))
+            .join('|') + `|${path}{}`;
+    }
+    if (control instanceof FormArray) {
+        return control.controls.map((row, i) => controlStructure(row, `${path}[${i}]`)).join('|') + `|${path}[]`;
+    }
+    return path;
+}
 
 /**
  * Per form state holder that connects `<ngs-form>`, its items and `NgsFormsService`.
@@ -300,6 +607,8 @@ class NgsFormsInternalService {
     formConfig$ = new BehaviorSubject(undefined);
     isSubmitted$ = new BehaviorSubject(false);
     state = new BehaviorSubject({});
+    /** Server errors set with `NgsFormsService.setServerErrorMessages()`. */
+    serverErrors = new NgsFormsServerErrorRegistry();
     setIsSubmitted(isSubmitted) {
         this.isSubmitted$.next(isSubmitted);
     }
@@ -314,6 +623,7 @@ class NgsFormsInternalService {
         const state = { ...(formConfig.initialState ?? {}) };
         state['global'] = { ...(formConfig.globalState ?? {}) };
         this.state.next(state);
+        this.serverErrors.reset();
         this.formGroup$.next(new UntypedFormGroup({}));
         this.formConfig$.next(formConfig);
         this.isSubmitted$.next(false);
@@ -421,25 +731,32 @@ class NgsFormsFormItemWithVisibleAndValidatorsBase extends NgsFormsBaseClassForm
         }
         const firstErrorKey = Object.keys(errors)[0];
         const map = this.config.errorMessageMap;
-        this.errorMessage = map?.[firstErrorKey] || `Field is invalid: ${firstErrorKey}`;
+        const isServerError = errors[firstErrorKey]?.[NGS_FORMS_SERVER_ERROR] === true;
+        // A server error without a mapped message shows the server's text.
+        this.errorMessage = map?.[firstErrorKey] || (isServerError ? firstErrorKey : `Field is invalid: ${firstErrorKey}`);
     }
     ngOnDestroy() {
         super.ngOnDestroy();
         this.formAddRemoveFns.remove(this.control, this.config.name);
     }
     bindValidators() {
-        if (!this.config.validators && !this.config.validators$)
-            return;
         const control = this.control;
+        // The server error validator is always kept, so server errors survive until the control's value changes.
+        // Optional so that tests which stub `NgsFormsInternalService` keep working.
+        const serverValidators = this.privateService.serverErrors ? [this.privateService.serverErrors.validator] : [];
+        if (!this.config.validators && !this.config.validators$) {
+            control.addValidators(serverValidators);
+            return;
+        }
         if (this.config.validators) {
-            control.setValidators(this.config.validators);
+            control.setValidators([...this.config.validators, ...serverValidators]);
             // A group or array computed its status when it was created, before these validators were set.
             control.updateValueAndValidity({ emitEvent: false });
             return;
         }
         if (this.config.validators$) {
             this.subscribe(this.config.validators$, (validators) => {
-                control.setValidators(validators);
+                control.setValidators([...validators, ...serverValidators]);
                 control.updateValueAndValidity();
             });
         }
@@ -861,6 +1178,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
 class NgsFormsFormArrayInternalService {
     config = inject(NGS_FORMS_ITEM_DATA).config;
     formArray = new UntypedFormArray([]);
+    formsInternalService = inject(NgsFormsInternalService, { optional: true });
     /** Emits after a row is added or removed. */
     itemsChanged = new Subject();
     /** Emits the index of a row right after it is removed. */
@@ -884,6 +1202,8 @@ class NgsFormsFormArrayInternalService {
         if (index < 0 || index >= this.formArray.controls.length) {
             return;
         }
+        // Server errors for rows are matched by index, so they are cleared once the rows move.
+        this.formsInternalService?.serverErrors?.clear();
         this.formArray.removeAt(index);
         this.rowRemoved.next(index);
         this.itemsChanged.next();
@@ -893,6 +1213,7 @@ class NgsFormsFormArrayInternalService {
         if (this.config?.maxItems && this.formArray.controls.length >= this.config.maxItems) {
             return;
         }
+        this.formsInternalService?.serverErrors?.clear();
         this.formArray.push(new UntypedFormGroup({}));
         this.itemsChanged.next();
     }
@@ -1230,5 +1551,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
  * Generated bundle index. Do not edit.
  */
 
-export { NGS_FORMS_ARRAY_ROW, NGS_FORMS_CONTROL_ADD_REMOVE_FN, NGS_FORMS_ITEM_DATA, NGS_FORMS_ITEM_INDEX, NgsFormComponent, NgsFormsBaseClassFormComponent, NgsFormsBaseClassFormInputComponent, NgsFormsBaseClassFormItemInputWithOptionsComponent, NgsFormsBaseClassItemsContainerBase, NgsFormsColumnComponent, NgsFormsComponentRegistryService, NgsFormsCoreModule, NgsFormsFormArrayAddItemComponent, NgsFormsFormArrayContainerComponent, NgsFormsFormArrayInternalService, NgsFormsFormArrayListComponent, NgsFormsFormArrayRemoveItemComponent, NgsFormsFormControlAddRemoveFunctions, NgsFormsFormGroupComponent, NgsFormsFormItemDirective, NgsFormsFormItemWithVisibleAndValidatorsBase, NgsFormsFormSectionComponent, NgsFormsHtmlContentComponent, NgsFormsInternalService, NgsFormsRowComponent, NgsFormsService, NgsFormsTextDivComponent, NgsSubscriber, ngsDefaults, sectionConfigDefaults };
+export { NGS_FORMS_ARRAY_ROW, NGS_FORMS_CONTROL_ADD_REMOVE_FN, NGS_FORMS_ITEM_DATA, NGS_FORMS_ITEM_INDEX, NGS_FORMS_SERVER_ERROR, NgsFormComponent, NgsFormsBaseClassFormComponent, NgsFormsBaseClassFormInputComponent, NgsFormsBaseClassFormItemInputWithOptionsComponent, NgsFormsBaseClassItemsContainerBase, NgsFormsColumnComponent, NgsFormsComponentRegistryService, NgsFormsCoreModule, NgsFormsFormArrayAddItemComponent, NgsFormsFormArrayContainerComponent, NgsFormsFormArrayInternalService, NgsFormsFormArrayListComponent, NgsFormsFormArrayRemoveItemComponent, NgsFormsFormControlAddRemoveFunctions, NgsFormsFormGroupComponent, NgsFormsFormItemDirective, NgsFormsFormItemWithVisibleAndValidatorsBase, NgsFormsFormSectionComponent, NgsFormsHtmlContentComponent, NgsFormsInternalService, NgsFormsRowComponent, NgsFormsServerErrorRegistry, NgsFormsService, NgsFormsTextDivComponent, NgsSubscriber, constructServerErrorMessageObject, ngsDefaults, sectionConfigDefaults };
 //# sourceMappingURL=ng-simplicity-forms-core.mjs.map