@ng-simplicity/forms-core 1.1.4 → 1.1.5

package/index.d.ts

@@ -343,6 +343,84 @@ declare class NgsFormsComponentRegistryService {
     static ɵprov: i0.ɵɵInjectableDeclaration<NgsFormsComponentRegistryService>;
 }
 
+/**
+ * Server errors for a form, in the same shape as the form value. Each leaf is the error key (or keys) to show on
+ * that control. The key is looked up in the control's `errorMessageMap`, just like a client-side validator's key.
+ *
+ * @example
+ * ```ts
+ * // Root group `registration`, its `userName` field taken, and the third row of the `contacts` array rejected.
+ * const errors: NgsFormsServerErrors = {
+ *   registration: {
+ *     userName: 'taken',
+ *     contacts: [{}, {}, { phone: 'invalidPhone' }, {}],
+ *   },
+ * };
+ * ```
+ */
+type NgsFormsServerErrors = string | string[] | NgsFormsServerErrorGroup | NgsFormsServerErrorArray;
+/** Server errors for the controls of a form group, keyed by control name. */
+interface NgsFormsServerErrorGroup {
+    [controlName: string]: NgsFormsServerErrors | null | undefined;
+}
+/** Server errors for the rows of a form array, by row index. Use `{}` or `null` for a row without errors. */
+type NgsFormsServerErrorArray = Array<NgsFormsServerErrors | null | undefined>;
+/** One server error: the path of the control and the error key to show on it. */
+interface NgsFormsServerErrorPath {
+    /**
+     * Path of the control in the form value, for example `registration.userName` or
+     * `registration.contacts[2].phone`. A leading `$` or `$.` is ignored, and bracket keys such as `['user name']`
+     * are allowed.
+     */
+    jsonPath: string;
+    /** The error key, looked up in the control's `errorMessageMap`. */
+    validator: string;
+}
+/**
+ * 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' }] } }
+ * ```
+ */
+declare function constructServerErrorMessageObject(errors: ReadonlyArray<NgsFormsServerErrorPath>): NgsFormsServerErrorGroup;
+/**
+ * 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.
+ */
+declare 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`.
+ */
+declare class NgsFormsServerErrorRegistry {
+    private readonly entries;
+    /**
+     * 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.
+     */
+    readonly validator: ValidatorFn;
+    /** `true` while at least one server error is set. */
+    get hasErrors(): boolean;
+    /** Replaces every server error with `errors`. Returns the paths that matched no control. */
+    set(root: AbstractControl, errors: NgsFormsServerErrors | null | undefined): string[];
+    /** Removes every server error. */
+    clear(): void;
+    /** Forgets every server error without re-validating, for when the controls are being thrown away. */
+    reset(): void;
+    private apply;
+    private applyKeys;
+    private validate;
+}
+
 /**
  * Per form state holder that connects `<ngs-form>`, its items and `NgsFormsService`.
  *
@@ -356,6 +434,8 @@ declare class NgsFormsInternalService {
     state: BehaviorSubject<{
         [key: string]: any;
     }>;
+    /** Server errors set with `NgsFormsService.setServerErrorMessages()`. */
+    readonly serverErrors: NgsFormsServerErrorRegistry;
     setIsSubmitted(isSubmitted: boolean): void;
     /** `true` when no rendered control fails its validators. A form whose controls are all disabled counts as valid. */
     checkIsValid(): boolean;
@@ -407,6 +487,14 @@ declare class NgsFormsService implements OnDestroy {
     private lastConfig;
     private missingFormTimer;
     private destroyed;
+    /** Patches still being applied while the form renders, in call order. */
+    private pendingPatches;
+    private patchTimer;
+    /** The controls that existed when the pending patches were last applied. */
+    private patchedStructure;
+    private patchRounds;
+    /** Render passes in a row in which no control was added or removed. */
+    private stablePatchRounds;
     /** `true` once the user has changed any control in the form. */
     get dirty(): boolean;
     /** `true` when every rendered control passes its validators. Hidden items are not validated. */
@@ -445,13 +533,44 @@ declare class NgsFormsService implements OnDestroy {
     /** Merges `state` into the state shared by every component in the form. */
     updateGlobalState(state: Partial<NgsFormsGlobalFormState>): void;
     ngOnDestroy(): void;
+    /**
+     * 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: NgsFormsServerErrors): string[];
+    /** Removes every error set with `setServerErrorMessages()`. */
+    clearServerErrorMessages(): void;
     /**
      * 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: any): void;
+    /** Maximum number of render passes a patch waits for new controls before it is dropped. */
+    private static readonly MAX_PATCH_ROUNDS;
+    private applyPendingPatches;
+    /**
+     * 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.
+     */
+    private schedulePatchRound;
+    private cancelPendingPatches;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<NgsFormsService>;
 }
@@ -782,6 +901,7 @@ declare class NgsFormsFormArrayContainerComponent extends NgsFormsFormItemWithVi
 declare class NgsFormsFormArrayInternalService implements OnDestroy {
     config: NgsFormItemArrayConfig;
     readonly formArray: UntypedFormArray;
+    private readonly formsInternalService;
     /** Emits after a row is added or removed. */
     readonly itemsChanged: Subject<void>;
     /** Emits the index of a row right after it is removed. */
@@ -998,5 +1118,5 @@ declare class NgsFormsCoreModule {
     static ɵinj: i0.ɵɵInjectorDeclaration<NgsFormsCoreModule>;
 }
 
-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 type { INgsFormsFormControlAddRemove, NgsFormDisableFn, NgsFormItemArrayAddItemConfig, NgsFormItemArrayConfig, NgsFormItemArrayRemoveItemConfig, NgsFormItemHtmlContentConfig, NgsFormItemRowConfig, NgsFormItemVisibilityFn, NgsFormValidatorArrayBuilderFn, NgsFormsCommonComponentState, NgsFormsFormArrayListConfig, NgsFormsFormConfig, NgsFormsFormErrorKeyValueMap, NgsFormsFormGroupConfig, NgsFormsFormInputOption, NgsFormsFormItem, NgsFormsFormItemConfigBase, NgsFormsFormItemConfigBaseInput, NgsFormsFormItemConfigBaseInputWithOptions, NgsFormsFormItemConfigBaseItemWithNameAndValidators, NgsFormsFormItemConfigBaseTextInput, NgsFormsFormItemContainerConfigBase, NgsFormsFormSectionConfig, NgsFormsFunctionParameters, NgsFormsGlobalFormState, NgsFormsTextDivConfig, NgsServerSideValidationErrorObjectType };
+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 };
+export type { INgsFormsFormControlAddRemove, NgsFormDisableFn, NgsFormItemArrayAddItemConfig, NgsFormItemArrayConfig, NgsFormItemArrayRemoveItemConfig, NgsFormItemHtmlContentConfig, NgsFormItemRowConfig, NgsFormItemVisibilityFn, NgsFormValidatorArrayBuilderFn, NgsFormsCommonComponentState, NgsFormsFormArrayListConfig, NgsFormsFormConfig, NgsFormsFormErrorKeyValueMap, NgsFormsFormGroupConfig, NgsFormsFormInputOption, NgsFormsFormItem, NgsFormsFormItemConfigBase, NgsFormsFormItemConfigBaseInput, NgsFormsFormItemConfigBaseInputWithOptions, NgsFormsFormItemConfigBaseItemWithNameAndValidators, NgsFormsFormItemConfigBaseTextInput, NgsFormsFormItemContainerConfigBase, NgsFormsFormSectionConfig, NgsFormsFunctionParameters, NgsFormsGlobalFormState, NgsFormsServerErrorArray, NgsFormsServerErrorGroup, NgsFormsServerErrorPath, NgsFormsServerErrors, NgsFormsTextDivConfig, NgsServerSideValidationErrorObjectType };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-simplicity/forms-core",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "license": "MIT",
   "repository": {
     "type": "git",