@ng-simplicity/forms-core 1.1.3 → 1.1.5

package/index.d.ts

@@ -1,9 +1,8 @@
-import * as rxjs from 'rxjs';
 import { Subject, Subscription, Observable, BehaviorSubject } from 'rxjs';
 import * as i0 from '@angular/core';
-import { OnInit, OnDestroy, Signal, Type, InjectionToken, Injector, ViewContainerRef, ChangeDetectorRef } from '@angular/core';
+import { OnInit, OnDestroy, Signal, Type, InjectionToken, Injector, ViewContainerRef, ChangeDetectorRef, OnChanges, SimpleChanges } from '@angular/core';
 import * as _angular_forms from '@angular/forms';
-import { ValidatorFn, UntypedFormControl, FormGroup, AbstractControl, UntypedFormGroup, UntypedFormArray, FormArray } from '@angular/forms';
+import { ValidatorFn, AbstractControl, UntypedFormControl, FormGroup, UntypedFormGroup, UntypedFormArray, FormArray } from '@angular/forms';
 import * as _ng_simplicity_forms_core from '@ng-simplicity/forms-core';
 import * as i1 from '@angular/common';
 
@@ -39,8 +38,8 @@ type NgsFormsFormErrorKeyValueMap = {
 
 /** One option of a radio group or select. */
 interface NgsFormsFormInputOption {
-    /** Value written to the form control when the option is chosen. */
-    id: string;
+    /** Value written to the form control when the option is chosen. Numbers stay numbers. */
+    id: string | number;
     /** Text shown to the user. */
     label: string;
     /** Renders the option but prevents choosing it. */
@@ -133,10 +132,7 @@ interface NgsFormsFormItemConfigBaseItemWithNameAndValidators extends NgsFormsFo
     validators?: Array<ValidatorFn>;
     /**
      * Stream of validator arrays. Each emission replaces the control's validators, which lets rules depend on other
-     * values in the form. Ignored when `validators` is also set.
-     *
-     * @remarks The control's validity is recalculated on its next value change, so call `updateValueAndValidity()`
-     * yourself if you need the new rules to apply immediately.
+     * values in the form. The control is re-validated on each emission. Ignored when `validators` is also set.
      */
     validators$?: Observable<Array<ValidatorFn>>;
 }
@@ -210,6 +206,8 @@ interface NgsFormsCommonComponentState {
     displayMode?: 'input' | 'summary';
     /** Whether to show a control that lets the user switch between `summary` and `input`. */
     showEditToggle?: boolean;
+    /** Your own keys. Read them from `commonState()` in custom components. */
+    [key: string]: unknown;
 }
 
 interface NgsFormsGlobalFormState extends NgsFormsCommonComponentState {
@@ -288,10 +286,14 @@ declare abstract class NgsFormsBaseClassFormComponent<T extends NgsFormsFormItem
  * Base class for items that own a form control. Creates the control (seeded with `value` when the config has one),
  * applies `validators` / `validators$` and `disabled` / `disabled$`, registers it with the parent group under
  * `config.name` and keeps `errorMessage` up to date.
+ *
+ * @typeParam T - The item's config type.
+ * @typeParam C - The type of `control`. Inputs use the default `UntypedFormControl`; groups and arrays set it in
+ * their constructor to an `UntypedFormGroup` or `UntypedFormArray`.
  */
-declare class NgsFormsFormItemWithVisibleAndValidatorsBase<T extends NgsFormsFormItemConfigBaseItemWithNameAndValidators> extends NgsFormsBaseClassFormComponent<T> implements OnInit, OnDestroy {
+declare class NgsFormsFormItemWithVisibleAndValidatorsBase<T extends NgsFormsFormItemConfigBaseItemWithNameAndValidators, C extends AbstractControl = UntypedFormControl> extends NgsFormsBaseClassFormComponent<T> implements OnInit, OnDestroy {
     /** The item's form control. Bind it with `[formControl]`. */
-    control: UntypedFormControl | undefined;
+    control: C | undefined;
     /**
      * Message for the control's first error, taken from `errorMessageMap`. Empty while the control is valid, or
      * before it is touched, dirty or submitted.
@@ -305,13 +307,15 @@ declare class NgsFormsFormItemWithVisibleAndValidatorsBase<T extends NgsFormsFor
     /** The latest value of `disabled` / `disabled$`, or `undefined` when the config sets neither. */
     private disabledFromConfig;
     ngOnInit(): void;
+    /** Whether the control currently has `Validators.required` or `Validators.requiredTrue`. */
+    get isRequired(): boolean;
     private updateErrorMessage;
     ngOnDestroy(): void;
     private bindValidators;
     private bindDisabled;
     private applyDisabled;
-    static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsFormItemWithVisibleAndValidatorsBase<any>, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<NgsFormsFormItemWithVisibleAndValidatorsBase<any>, never, never, {}, {}, never, never, true, never>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsFormItemWithVisibleAndValidatorsBase<any, any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgsFormsFormItemWithVisibleAndValidatorsBase<any, any>, never, never, {}, {}, never, never, true, never>;
 }
 
 /**
@@ -339,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`.
  *
@@ -352,19 +434,22 @@ 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;
     setFormData(formConfig: NgsFormsFormConfig): void;
     private mergeState;
     /** Sets a component's state from its config's `initialState`, unless state for `uuid` already exists. */
     seedComponentState(uuid: string, initialState: any): void;
-    updateGlobalState(state: NgsFormsGlobalFormState): void;
-    updateComponentState(componentKey: string, state: any): void;
+    updateGlobalState(state: Partial<NgsFormsGlobalFormState>): void;
+    updateComponentState(componentKey: string, state: Partial<NgsFormsCommonComponentState>): void;
     /**
      * Merged state for one component: its own (by `uuid`), then by `name`, then global.
      * `initialState` seeds the component's own state unless state for `uuid` already exists.
      */
-    subscribeToState(uuid: string, name?: string, initialState?: any): rxjs.Observable<any>;
+    subscribeToState(uuid: string, name?: string, initialState?: any): Observable<NgsFormsCommonComponentState>;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsInternalService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<NgsFormsInternalService>;
 }
@@ -387,10 +472,6 @@ declare class NgsFormsInternalService {
  * ```
  */
 declare class NgsFormsService implements OnDestroy {
-    /**
-     * @internal
-     */
-    attempt: number;
     /**
      * Emits the root form group's value every time it changes. Combine with `toSignal()` to read it in a template.
      *
@@ -400,8 +481,20 @@ declare class NgsFormsService implements OnDestroy {
     /** The latest value emitted by `formValue$`. */
     formValue: any;
     private internalFormService;
-    private formGroupSubscriptions;
+    private formGroupBinding;
     private formGroup;
+    /** The config from the latest `setFormConfig()` call, re-applied when `<ngs-form>` (re)connects. */
+    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. */
@@ -411,14 +504,21 @@ declare class NgsFormsService implements OnDestroy {
     /**
      * Renders a form from `formConfig`, replacing any form that is already shown and resetting the submitted state.
      *
-     * @remarks It is safe to call before `<ngs-form>` has initialised (for example in `ngOnInit`): the call is retried
-     * every 25 ms for about half a second until the form component is available.
+     * @remarks It is safe to call before `<ngs-form>` has initialised (for example in `ngOnInit`): the latest config
+     * is kept and applied as soon as the form component connects, and also when it is destroyed and created again
+     * (inside an `@if` or a tab, for example). An error is logged if no form has connected after half a second.
      */
     setFormConfig(formConfig: NgsFormsFormConfig): void;
     /**
      * @internal
      */
     setInternalService(internalFormsService: NgsFormsInternalService): void;
+    /**
+     * @internal
+     * Disconnects `internalFormsService` when its `<ngs-form>` is destroyed. Does nothing if another form has
+     * connected since.
+     */
+    clearInternalService(internalFormsService: NgsFormsInternalService): void;
     /**
      * Marks the form as submitted (or not). While submitted, every invalid control shows its error message even if
      * the user never touched it.
@@ -429,17 +529,48 @@ declare class NgsFormsService implements OnDestroy {
      * Merges `state` into the state of one component, identified by its `uuid` or control `name`.
      * Components read the merged result through `commonState`.
      */
-    updateComponentState(componentKey: string, state: any): void;
+    updateComponentState(componentKey: string, state: Partial<NgsFormsCommonComponentState>): void;
     /** Merges `state` into the state shared by every component in the form. */
-    updateGlobalState(state: any): void;
+    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>;
 }
@@ -490,7 +621,7 @@ declare class NgsFormsBaseClassFormItemInputWithOptionsComponent<T extends NgsFo
  * <ngs-form></ngs-form>
  * ```
  */
-declare class NgsFormComponent {
+declare class NgsFormComponent implements OnDestroy {
     private readonly ngsInternalFormsService;
     readonly ngsFormsService: NgsFormsService;
     readonly formGroup: i0.Signal<_angular_forms.FormGroup<any> | undefined>;
@@ -501,6 +632,7 @@ declare class NgsFormComponent {
         root: _ng_simplicity_forms_core.NgsFormsFormItem<any>;
     }[]>;
     constructor();
+    ngOnDestroy(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NgsFormComponent, "ngs-form", never, {}, {}, never, never, true, never>;
 }
@@ -511,8 +643,18 @@ declare const NGS_FORMS_ITEM_DATA: InjectionToken<unknown>;
  * @internal
  */
 declare const NGS_FORMS_CONTROL_ADD_REMOVE_FN: InjectionToken<unknown>;
-/** Injection token for the row index when a component is rendered inside a form array list. */
-declare const NGS_FORMS_ITEM_INDEX: InjectionToken<unknown>;
+/**
+ * Injection token for the row index when a component is rendered inside a form array list.
+ *
+ * @remarks This is the index the row had when the component was created. Rows before it can be removed later,
+ * so to find a row's current position use `NGS_FORMS_ARRAY_ROW` with `formArray.controls.indexOf(row)`.
+ */
+declare const NGS_FORMS_ITEM_INDEX: InjectionToken<number>;
+/**
+ * Injection token for the `UntypedFormGroup` of the form array row a component is rendered in. Unlike
+ * `NGS_FORMS_ITEM_INDEX`, it stays correct when earlier rows are removed.
+ */
+declare const NGS_FORMS_ARRAY_ROW: InjectionToken<UntypedFormGroup>;
 type FormControlAddRemoveFn = (control: AbstractControl, controlName: string) => void;
 /**
  * @internal
@@ -576,12 +718,20 @@ declare class NgsFormItemController extends NgsSubscriber {
     private readonly addRemoveControlFn?;
     private readonly index?;
     private readonly changeDetectorRef?;
+    private readonly arrayRow?;
     private componentRef;
-    private parentVisibility;
     private lastVisible;
-    constructor(injector: Injector, viewContainerRef: ViewContainerRef, itemData: NgsFormsFormItem<any>, addRemoveControlFn?: INgsFormsFormControlAddRemove | undefined, index?: number | undefined, changeDetectorRef?: ChangeDetectorRef | undefined);
+    /** Incremented whenever a scheduled create becomes stale (hidden again, or destroyed). */
+    private createToken;
+    private destroyed;
+    constructor(injector: Injector, viewContainerRef: ViewContainerRef, itemData: NgsFormsFormItem<any>, addRemoveControlFn?: INgsFormsFormControlAddRemove | undefined, index?: number | undefined, changeDetectorRef?: ChangeDetectorRef | undefined, arrayRow?: UntypedFormGroup | undefined);
     destroy(): void;
     private bindVisibility;
+    /**
+     * Creates the component in a microtask. A create that is overtaken by a later visibility change or by
+     * `destroy()` before it runs is dropped.
+     */
+    private scheduleCreate;
     private create;
     private detach;
 }
@@ -592,7 +742,7 @@ declare class NgsFormItemController extends NgsSubscriber {
  * @remarks Use it inside custom container components to render child items:
  * `<ng-container [ngs-form-item]="item" [ngs-form-group]="group"></ng-container>`.
  */
-declare class NgsFormsFormItemDirective implements OnInit, OnDestroy {
+declare class NgsFormsFormItemDirective implements OnInit, OnChanges, OnDestroy {
     /** The item to render. */
     itemData: NgsFormsFormItem<any> | undefined;
     /** Form group that the item's control is added to. */
@@ -600,7 +750,8 @@ declare class NgsFormsFormItemDirective implements OnInit, OnDestroy {
     /** Form array that the item's control is added to. */
     formArray?: UntypedFormArray;
     /**
-     * Index of the item inside a form array row, provided to children as `NGS_FORMS_ITEM_INDEX`.
+     * Index of the item inside a form array row, provided to children as `NGS_FORMS_ITEM_INDEX`. When it is set, the
+     * `ngs-form-group` is also provided to children as `NGS_FORMS_ARRAY_ROW`.
      */
     index?: number;
     controller: NgsFormItemController | undefined;
@@ -608,7 +759,10 @@ declare class NgsFormsFormItemDirective implements OnInit, OnDestroy {
     private readonly injector;
     private readonly changeDetectorRef;
     private readonly formComponentRegistryService;
+    private initialized;
     ngOnInit(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    private build;
     ngOnDestroy(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsFormItemDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<NgsFormsFormItemDirective, "[ngs-form-item]", never, { "itemData": { "alias": "ngs-form-item"; "required": false; }; "formGroup": { "alias": "ngs-form-group"; "required": false; }; "formArray": { "alias": "ngs-form-array"; "required": false; }; "index": { "alias": "ngs-form-index"; "required": false; }; }, {}, never, never, true, never>;
@@ -676,7 +830,7 @@ declare class NgsFormsRowComponent extends NgsFormsBaseClassFormComponent<NgsFor
  * })
  * ```
  */
-declare class NgsFormsFormGroupComponent extends NgsFormsFormItemWithVisibleAndValidatorsBase<NgsFormsFormGroupConfig> implements OnInit {
+declare class NgsFormsFormGroupComponent extends NgsFormsFormItemWithVisibleAndValidatorsBase<NgsFormsFormGroupConfig, UntypedFormGroup> implements OnInit {
     static key: string;
     /** Creates a `form-group` item. */
     static create(config: NgsFormsFormGroupConfig): NgsFormsFormItem<NgsFormsFormGroupConfig>;
@@ -729,7 +883,7 @@ interface NgsFormItemArrayConfig extends NgsFormsFormItemConfigBaseItemWithNameA
  * @remarks Registry key: `form-array`. Put an `NgsFormsFormArrayListComponent` inside `items` to render the rows,
  * and `NgsFormsFormArrayAddItemComponent` / `NgsFormsFormArrayRemoveItemComponent` to let users change them.
  */
-declare class NgsFormsFormArrayContainerComponent extends NgsFormsFormItemWithVisibleAndValidatorsBase<NgsFormItemArrayConfig> {
+declare class NgsFormsFormArrayContainerComponent extends NgsFormsFormItemWithVisibleAndValidatorsBase<NgsFormItemArrayConfig, UntypedFormArray> {
     private formArrayService;
     static key: string;
     constructor(formArrayService: NgsFormsFormArrayInternalService);
@@ -747,8 +901,11 @@ 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. */
+    readonly rowRemoved: Subject<number>;
     constructor();
     ngOnDestroy(): void;
     /** Removes the row at `index`, unless that would go below `minItems`. */
@@ -793,7 +950,14 @@ declare class NgsFormsFormArrayListComponent extends NgsFormsBaseClassFormCompon
     internalArrayService: NgsFormsFormArrayInternalService;
     myFormArray: FormArray<any>;
     private changeDetectorRef;
+    private elementRef;
+    private injector;
     ngOnInit(): void;
+    /**
+     * When the focused element (usually the row's Remove button) was removed with its row, moves focus to the
+     * same kind of control in the row that took its place, so keyboard users are not sent back to the top of the page.
+     */
+    private restoreFocusAfterRemove;
     /** Creates a `form-array-list` item. */
     static create(config: NgsFormsFormArrayListConfig): NgsFormsFormItem<NgsFormsFormArrayListConfig>;
     castToFormGroup(control: AbstractControl): UntypedFormGroup;
@@ -815,6 +979,12 @@ interface NgsFormItemArrayRemoveItemConfig extends NgsFormsFormItemConfigBase {
     buttonClass?: string;
     /** Class of an `<i>` icon shown before the label, for example `bi bi-trash`. */
     buttonIcon?: string;
+    /**
+     * Accessible name of the button, so screen reader users can tell the rows' buttons apart. A function receives
+     * the row's zero-based index.
+     * @defaultValue `${buttonText} item ${index + 1}`, for example `Remove item 2`
+     */
+    ariaLabel?: string | ((index: number) => string);
 }
 
 /**
@@ -823,14 +993,19 @@ interface NgsFormItemArrayRemoveItemConfig extends NgsFormsFormItemConfigBase {
  * @remarks Registry key: `form-array-remove-item`. Place it inside the `templateItem` of an
  * `NgsFormsFormArrayListComponent` so each row gets one.
  */
-declare class NgsFormsFormArrayRemoveItemComponent extends NgsFormsBaseClassFormComponent<NgsFormItemArrayRemoveItemConfig> {
+declare class NgsFormsFormArrayRemoveItemComponent extends NgsFormsBaseClassFormComponent<NgsFormItemArrayRemoveItemConfig> implements OnInit {
     static key: string;
     internalArrayService: NgsFormsFormArrayInternalService;
     private elementRef;
     private indexFromDi;
-    /** Index of the row this button belongs to. */
+    private row;
+    private changeDetectorRef;
+    /** Accessible name of the button, from `ariaLabel` or `${buttonText} item ${index + 1}`. */
+    get ariaLabel(): string;
+    /** Current index of the row this button belongs to. */
     get myIndex(): number;
     constructor();
+    ngOnInit(): void;
     /** Creates a `form-array-remove-item` item. */
     static create(config: NgsFormItemArrayRemoveItemConfig): NgsFormsFormItem<NgsFormItemArrayRemoveItemConfig>;
     removeItem(): void;
@@ -885,22 +1060,43 @@ declare class NgsFormsHtmlContentComponent extends NgsFormsBaseClassFormComponen
     static ɵcmp: i0.ɵɵComponentDeclaration<NgsFormsHtmlContentComponent, "ngs-form-component-html-content", never, {}, {}, never, never, true, never>;
 }
 
+/** Configuration for `NgsFormsFormSectionComponent`. */
 interface NgsFormsFormSectionConfig extends NgsFormsFormItemContainerConfigBase {
+    /** Section heading. It also names the section's group for assistive technology. */
     title: string;
+    /**
+     * Class of the title.
+     * @defaultValue 'h3'
+     */
     titleClass?: string;
+    /**
+     * Heading level (1 to 6) that assistive technology announces for the title.
+     * @defaultValue 3
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Text shown under the title. */
     subtitle?: string;
+    /**
+     * Class of the subtitle.
+     * @defaultValue 'lead'
+     */
     subtitleClass?: string;
 }
+/** @internal */
+declare const sectionConfigDefaults: Partial<NgsFormsFormSectionConfig>;
 
 /**
  * Groups items under a title and optional subtitle. Does not create a form control, so child values stay in the
  * parent group.
  *
  * @remarks Registry key: `section`. Config: `title`, `subtitle`, `titleClass` (default `h3`),
- * `subtitleClass` (default `lead`) and `items`.
+ * `headingLevel` (default 3), `subtitleClass` (default `lead`) and `items`. The section is exposed to assistive
+ * technology as a group named by its title.
  */
 declare class NgsFormsFormSectionComponent extends NgsFormsBaseClassItemsContainerBase<NgsFormsFormSectionConfig> implements OnInit {
     static key: string;
+    /** Element id of the title, used to name the section's group. */
+    readonly titleId: string;
     /** Creates a `section` item. */
     static create(config: NgsFormsFormSectionConfig): NgsFormsFormItem<NgsFormsFormSectionConfig>;
     ngOnInit(): void;
@@ -922,5 +1118,5 @@ declare class NgsFormsCoreModule {
     static ɵinj: i0.ɵɵInjectorDeclaration<NgsFormsCoreModule>;
 }
 
-export { 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 };
-export type { INgsFormsFormControlAddRemove, NgsFormDisableFn, NgsFormItemArrayAddItemConfig, NgsFormItemArrayConfig, NgsFormItemArrayRemoveItemConfig, NgsFormItemHtmlContentConfig, NgsFormItemRowConfig, NgsFormItemVisibilityFn, NgsFormValidatorArrayBuilderFn, NgsFormsFormArrayListConfig, NgsFormsFormConfig, NgsFormsFormErrorKeyValueMap, NgsFormsFormGroupConfig, NgsFormsFormInputOption, NgsFormsFormItem, NgsFormsFormItemConfigBase, NgsFormsFormItemConfigBaseInput, NgsFormsFormItemConfigBaseInputWithOptions, NgsFormsFormItemConfigBaseItemWithNameAndValidators, NgsFormsFormItemConfigBaseTextInput, NgsFormsFormItemContainerConfigBase, NgsFormsFunctionParameters, 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.3",
+  "version": "1.1.5",
   "license": "MIT",
   "repository": {
     "type": "git",