@ng-simplicity/forms-core 1.1.3 → 1.1.4

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.3` | `17.x`–`22.x` |
+| `@ng-simplicity/forms-core` | `1.1.4` | `17.x`–`22.x` |
 
 ---
 
@@ -397,10 +397,17 @@ import { NgsFormsFormArrayRemoveItemComponent } from '@ng-simplicity/forms-core'
 const removeContactBtn = NgsFormsFormArrayRemoveItemComponent.create({
   buttonText: 'Delete',
   buttonClass: 'btn btn-danger',
-  buttonIcon: 'trash-icon'
+  buttonIcon: 'trash-icon',
+  // Optional accessible name. Defaults to `${buttonText} item ${index + 1}`, for example "Delete item 2".
+  ariaLabel: (index) => `Delete contact ${index + 1}`,
 });
 ```
 
+The button always removes its own row, even after earlier rows have been removed. When the removed row held the focus, focus moves to the Remove button of the row that takes its place. Custom components inside a row can inject `NGS_FORMS_ARRAY_ROW` (the row's `UntypedFormGroup`) and use `formArray.controls.indexOf(row)` to find the row's current index; `NGS_FORMS_ITEM_INDEX` is the index the row had when it was created.
+
+```typescript
+```
+
 ### 5. Section (`section`)
 A visual layout grouping with a title and subtitle.
 - **Component**: `NgsFormsFormSectionComponent`
@@ -413,6 +420,7 @@ import { NgsFormsFormSectionComponent } from '@ng-simplicity/forms-core';
 const personalSection = NgsFormsFormSectionComponent.create({
   title: 'Personal Information',
   titleClass: 'custom-title-class', // Optional, defaults to 'h3'
+  headingLevel: 2, // Optional heading level announced by screen readers, defaults to 3
   subtitle: 'Tell us a bit about yourself',
   subtitleClass: 'custom-subtitle-class', // Optional, defaults to 'lead'
   items: [

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

@@ -1,9 +1,9 @@
-import { Subject, takeUntil, BehaviorSubject, map, filter, merge, of } from 'rxjs';
+import { Subject, takeUntil, BehaviorSubject, switchMap, defer, map, distinctUntilChanged, merge, of } from 'rxjs';
 import * as i0 from '@angular/core';
-import { Directive, InjectionToken, inject, Injectable, ChangeDetectorRef, Injector, ViewContainerRef, Input, computed, ChangeDetectionStrategy, Component, ElementRef, Sanitizer, SecurityContext, NgModule } 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 { toSignal } from '@angular/core/rxjs-interop';
-import { UntypedFormGroup, FormControl, FormGroup, FormArray, UntypedFormArray, FormsModule, ReactiveFormsModule } from '@angular/forms';
+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. */
@@ -32,8 +32,18 @@ const NGS_FORMS_ITEM_DATA = new InjectionToken('ngs-forms-item-data');
  * @internal
  */
 const NGS_FORMS_CONTROL_ADD_REMOVE_FN = new InjectionToken('ngs-form-control-remove-fn');
-/** Injection token for the row index when a component is rendered inside a form array list. */
+/**
+ * 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)`.
+ */
 const NGS_FORMS_ITEM_INDEX = new InjectionToken('ngs-forms-item-index');
+/**
+ * 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.
+ */
+const NGS_FORMS_ARRAY_ROW = new InjectionToken('ngs-forms-array-row');
 /**
  * @internal
  */
@@ -43,10 +53,12 @@ const NgsFormsFormControlAddRemoveFunctions = {
         remove: (control, controlName) => formGroup.removeControl(controlName),
     }),
     formArray: (formArray) => ({
-        add: (control, controlName) => formArray.controls.push(control),
-        remove: (control, controlName) => {
+        add: (control) => formArray.push(control),
+        remove: (control) => {
             const index = formArray.controls.indexOf(control);
-            formArray.controls.splice(index, 1);
+            if (index >= 0) {
+                formArray.removeAt(index);
+            }
         },
     }),
 };
@@ -148,10 +160,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
  * ```
  */
 class NgsFormsService {
-    /**
-     * @internal
-     */
-    attempt = 0;
     /**
      * Emits the root form group's value every time it changes. Combine with `toSignal()` to read it in a template.
      *
@@ -161,8 +169,12 @@ class NgsFormsService {
     /** The latest value emitted by `formValue$`. */
     formValue = {};
     internalFormService;
-    formGroupSubscriptions = [];
+    formGroupBinding;
     formGroup = new UntypedFormGroup({});
+    /** The config from the latest `setFormConfig()` call, re-applied when `<ngs-form>` (re)connects. */
+    lastConfig;
+    missingFormTimer;
+    destroyed = false;
     /** `true` once the user has changed any control in the form. */
     get dirty() {
         return this.formGroup?.dirty ?? false;
@@ -180,27 +192,48 @@ class NgsFormsService {
     /**
      * 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) {
-        if (!this.internalServiceIsSet) {
-            if (this.attempt > 20) {
-                console.error('Internal form service is unavailable.  Is the ngs-form root tag added to the page?');
-                return;
-            }
-            this.attempt++;
-            setTimeout(() => this.setFormConfig(formConfig), 25);
+        this.lastConfig = formConfig;
+        if (this.internalServiceIsSet) {
+            this.internalFormService.setFormData(formConfig);
             return;
         }
-        this.internalFormService.setFormData(formConfig);
+        if (this.missingFormTimer === undefined && !this.destroyed) {
+            this.missingFormTimer = setTimeout(() => {
+                this.missingFormTimer = undefined;
+                if (!this.internalServiceIsSet && !this.destroyed) {
+                    console.error('Internal form service is unavailable.  Is the ngs-form root tag added to the page?');
+                }
+            }, 500);
+        }
     }
     /**
      * @internal
      */
     setInternalService(internalFormsService) {
+        this.formGroupBinding?.unsubscribe();
         this.internalFormService = internalFormsService;
         this.bindFormGroup();
+        if (this.lastConfig) {
+            internalFormsService.setFormData(this.lastConfig);
+        }
+    }
+    /**
+     * @internal
+     * Disconnects `internalFormsService` when its `<ngs-form>` is destroyed. Does nothing if another form has
+     * connected since.
+     */
+    clearInternalService(internalFormsService) {
+        if (this.internalFormService !== internalFormsService)
+            return;
+        this.formGroupBinding?.unsubscribe();
+        this.formGroupBinding = undefined;
+        this.internalFormService = undefined;
+        this.formGroup = new UntypedFormGroup({});
     }
     /**
      * Marks the form as submitted (or not). While submitted, every invalid control shows its error message even if
@@ -212,13 +245,14 @@ class NgsFormsService {
         this.internalFormService.setIsSubmitted(isSubmitted);
     }
     bindFormGroup() {
-        this.internalFormService.formGroup$.subscribe((fg) => {
+        this.formGroupBinding = this.internalFormService.formGroup$
+            .pipe(switchMap((fg) => {
             this.formGroup = fg;
-            this.formGroupSubscriptions.forEach((subscription) => subscription.unsubscribe());
-            this.formGroupSubscriptions.push(this.formGroup.valueChanges.subscribe((v) => {
-                this.formValue = v;
-                this.formValue$.next(v);
-            }));
+            return fg.valueChanges;
+        }))
+            .subscribe((v) => {
+            this.formValue = v;
+            this.formValue$.next(v);
         });
     }
     /**
@@ -233,7 +267,11 @@ class NgsFormsService {
         this.internalFormService?.updateGlobalState(state);
     }
     ngOnDestroy() {
-        this.formGroupSubscriptions.forEach((subscription) => subscription.unsubscribe());
+        this.destroyed = true;
+        clearTimeout(this.missingFormTimer);
+        this.missingFormTimer = undefined;
+        this.formGroupBinding?.unsubscribe();
+        this.formValue$.complete();
     }
     /**
      * Patches values into the form, using the same shape as `formValue$` (including the root group name).
@@ -265,10 +303,12 @@ class NgsFormsInternalService {
     setIsSubmitted(isSubmitted) {
         this.isSubmitted$.next(isSubmitted);
     }
+    /** `true` when no rendered control fails its validators. A form whose controls are all disabled counts as valid. */
     checkIsValid() {
-        if (!this.formGroup$.value)
+        const formGroup = this.formGroup$.value;
+        if (!formGroup)
             return false;
-        return this.formGroup$.value.valid;
+        return formGroup.valid || formGroup.disabled === true;
     }
     setFormData(formConfig) {
         const state = { ...(formConfig.initialState ?? {}) };
@@ -302,18 +342,13 @@ class NgsFormsInternalService {
      */
     subscribeToState(uuid, name, initialState) {
         this.seedComponentState(uuid, initialState);
-        let last = '';
-        return this.state.pipe(map((allState) => {
+        // `defer` gives every subscriber its own comparison, so each one receives the current state first.
+        return defer(() => this.state.pipe(map((allState) => {
             const stateByUuid = allState[uuid] || {};
             const stateByName = name ? (allState[name] || {}) : {};
             const globalState = allState['global'] || {};
             return ngsDefaults(stateByUuid, ngsDefaults(stateByName, globalState));
-        }), filter((currentState) => {
-            const stringifiedState = JSON.stringify(currentState);
-            const isUpdated = stringifiedState !== last;
-            last = stringifiedState;
-            return isUpdated;
-        }));
+        }), distinctUntilChanged((previous, current) => JSON.stringify(previous) === JSON.stringify(current))));
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsInternalService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsInternalService });
@@ -326,6 +361,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
  * 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`.
  */
 class NgsFormsFormItemWithVisibleAndValidatorsBase extends NgsFormsBaseClassFormComponent {
     /** The item's form control. Bind it with `[formControl]`. */
@@ -347,15 +386,24 @@ class NgsFormsFormItemWithVisibleAndValidatorsBase extends NgsFormsBaseClassForm
             const initialValue = this.config.value;
             this.control = new FormControl(initialValue, { validators: [] });
         }
+        const control = this.control;
         this.bindValidators();
-        this.formAddRemoveFns.add(this.control, this.config.name);
+        this.formAddRemoveFns.add(control, this.config.name);
         this.bindDisabled();
-        // Listen to changes and update error message dynamically
-        this.subscribe(merge(this.control.valueChanges, this.control.statusChanges, this.privateService.isSubmitted$), () => {
+        // Recompute the error message on value, status and touched changes, and when the form is submitted.
+        // `control.events` (Angular 18+) includes touched changes, so blurring an untouched field shows its error.
+        // Angular 17 has no `events`, so there the message updates on value and status changes only.
+        const controlEvents$ = control.events ?? merge(control.valueChanges, control.statusChanges);
+        this.subscribe(merge(controlEvents$, this.privateService.isSubmitted$), () => {
             this.updateErrorMessage();
             this.changeDetectorRef.markForCheck();
         });
     }
+    /** Whether the control currently has `Validators.required` or `Validators.requiredTrue`. */
+    get isRequired() {
+        const control = this.control;
+        return !!control && (control.hasValidator(Validators.required) || control.hasValidator(Validators.requiredTrue));
+    }
     updateErrorMessage() {
         if (!this.control) {
             this.errorMessage = '';
@@ -382,12 +430,18 @@ class NgsFormsFormItemWithVisibleAndValidatorsBase extends NgsFormsBaseClassForm
     bindValidators() {
         if (!this.config.validators && !this.config.validators$)
             return;
+        const control = this.control;
         if (this.config.validators) {
-            this.control.setValidators(this.config.validators);
+            control.setValidators(this.config.validators);
+            // 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) => this.control.setValidators(validators));
+            this.subscribe(this.config.validators$, (validators) => {
+                control.setValidators(validators);
+                control.updateValueAndValidity();
+            });
         }
     }
     bindDisabled() {
@@ -399,14 +453,21 @@ class NgsFormsFormItemWithVisibleAndValidatorsBase extends NgsFormsBaseClassForm
             this.disabledFromConfig = !!disabled;
             this.applyDisabled(control);
         });
+        const reapply = () => {
+            if (this.disabledFromConfig && control.enabled) {
+                control.disable();
+            }
+        };
         // Child controls are added to groups and arrays after the container has been disabled, and adding an enabled
         // child re-enables its parent. Re-apply the configured state whenever a container's status changes.
         if (control instanceof FormGroup || control instanceof FormArray) {
-            this.subscribe(control.statusChanges, () => {
-                if (this.disabledFromConfig && control.enabled) {
-                    control.disable();
-                }
-            });
+            this.subscribe(control.statusChanges, reapply);
+        }
+        // Enabling a parent group or array enables every child in it. The parent emits its status after its children
+        // are enabled, so re-apply the configured state then. (Doing it on the child's own status change would be undone
+        // by the end of the child's `enable()`, which re-enables the bound DOM element.)
+        if (control.parent) {
+            this.subscribe(control.parent.statusChanges, reapply);
         }
     }
     applyDisabled(control) {
@@ -485,10 +546,13 @@ class NgsFormItemController extends NgsSubscriber {
     addRemoveControlFn;
     index;
     changeDetectorRef;
+    arrayRow;
     componentRef;
-    parentVisibility = new BehaviorSubject(false);
     lastVisible;
-    constructor(injector, viewContainerRef, itemData, addRemoveControlFn, index, changeDetectorRef) {
+    /** Incremented whenever a scheduled create becomes stale (hidden again, or destroyed). */
+    createToken = 0;
+    destroyed = false;
+    constructor(injector, viewContainerRef, itemData, addRemoveControlFn, index, changeDetectorRef, arrayRow) {
         super();
         this.injector = injector;
         this.viewContainerRef = viewContainerRef;
@@ -496,9 +560,12 @@ class NgsFormItemController extends NgsSubscriber {
         this.addRemoveControlFn = addRemoveControlFn;
         this.index = index;
         this.changeDetectorRef = changeDetectorRef;
+        this.arrayRow = arrayRow;
         this.bindVisibility();
     }
     destroy() {
+        this.destroyed = true;
+        this.createToken++;
         this.detach();
         super.ngOnDestroy();
     }
@@ -506,7 +573,7 @@ class NgsFormItemController extends NgsSubscriber {
         const config = this.itemData.config;
         const visible$ = config.visible$ ?? (config.visible !== undefined ? of(config.visible) : undefined);
         if (!visible$) {
-            Promise.resolve().then(() => this.create());
+            this.scheduleCreate();
             return;
         }
         this.subscribe(visible$, (visible) => {
@@ -514,17 +581,37 @@ class NgsFormItemController extends NgsSubscriber {
                 return;
             this.lastVisible = visible;
             if (visible) {
-                Promise.resolve().then(() => this.create());
+                this.scheduleCreate();
                 return;
             }
+            // Cancels a create that was scheduled but has not run yet.
+            this.createToken++;
             this.detach();
         });
     }
+    /**
+     * Creates the component in a microtask. A create that is overtaken by a later visibility change or by
+     * `destroy()` before it runs is dropped.
+     */
+    scheduleCreate() {
+        const token = ++this.createToken;
+        Promise.resolve().then(() => {
+            if (this.destroyed || token !== this.createToken)
+                return;
+            this.create();
+        });
+    }
     create() {
+        if (this.componentRef && !this.componentRef.hostView.destroyed) {
+            return;
+        }
         const providers = [{ provide: NGS_FORMS_ITEM_DATA, useValue: this.itemData }];
         if (this.index !== undefined) {
             providers.push({ provide: NGS_FORMS_ITEM_INDEX, useValue: this.index });
         }
+        if (this.arrayRow) {
+            providers.push({ provide: NGS_FORMS_ARRAY_ROW, useValue: this.arrayRow });
+        }
         if (this.addRemoveControlFn) {
             providers.push({ provide: NGS_FORMS_CONTROL_ADD_REMOVE_FN, useValue: this.addRemoveControlFn });
         }
@@ -540,11 +627,10 @@ class NgsFormItemController extends NgsSubscriber {
         this.componentRef = this.viewContainerRef.createComponent(componentType, { injector: myInjector });
         this.componentRef.changeDetectorRef?.detectChanges();
         this.changeDetectorRef?.markForCheck();
-        this.parentVisibility.next(true);
     }
     detach() {
-        this.parentVisibility.next(false);
         this.componentRef?.destroy();
+        this.componentRef = undefined;
         this.changeDetectorRef?.markForCheck();
     }
 }
@@ -563,7 +649,8 @@ class NgsFormsFormItemDirective {
     /** Form array that the item's control is added to. */
     formArray;
     /**
-     * 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;
     controller;
@@ -571,7 +658,24 @@ class NgsFormsFormItemDirective {
     injector = inject(Injector);
     changeDetectorRef = inject(ChangeDetectorRef);
     formComponentRegistryService = inject(NgsFormsComponentRegistryService);
+    initialized = false;
     ngOnInit() {
+        this.initialized = true;
+        this.build();
+    }
+    ngOnChanges(changes) {
+        if (!this.initialized) {
+            return;
+        }
+        // A new item, group or array means a different control, so the component is rebuilt. An index change on its own
+        // keeps the component: the row it belongs to is still the same, and `NGS_FORMS_ARRAY_ROW` follows it.
+        if (changes['itemData'] || changes['formGroup'] || changes['formArray']) {
+            this.controller?.destroy();
+            this.controller = undefined;
+            this.build();
+        }
+    }
+    build() {
         if (!this.itemData) {
             return console.error('Form item without form data');
         }
@@ -582,13 +686,13 @@ class NgsFormsFormItemDirective {
         if (this.formGroup) {
             addRemoveFn = NgsFormsFormControlAddRemoveFunctions.formGroup(this.formGroup);
         }
-        this.controller = new NgsFormItemController(this.injector, this.viewContainerRef, this.itemData, addRemoveFn, this.index, this.changeDetectorRef);
+        this.controller = new NgsFormItemController(this.injector, this.viewContainerRef, this.itemData, addRemoveFn, this.index, this.changeDetectorRef, this.index !== undefined ? this.formGroup : undefined);
     }
     ngOnDestroy() {
         this.controller?.destroy();
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsFormItemDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "20.3.19", type: NgsFormsFormItemDirective, isStandalone: true, selector: "[ngs-form-item]", inputs: { itemData: ["ngs-form-item", "itemData"], formGroup: ["ngs-form-group", "formGroup"], formArray: ["ngs-form-array", "formArray"], index: ["ngs-form-index", "index"] }, ngImport: i0 });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "20.3.19", type: NgsFormsFormItemDirective, isStandalone: true, selector: "[ngs-form-item]", inputs: { itemData: ["ngs-form-item", "itemData"], formGroup: ["ngs-form-group", "formGroup"], formArray: ["ngs-form-array", "formArray"], index: ["ngs-form-index", "index"] }, usesOnChanges: true, ngImport: i0 });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsFormItemDirective, decorators: [{
             type: Directive,
@@ -633,6 +737,9 @@ class NgsFormComponent {
     constructor() {
         this.ngsFormsService.setInternalService(this.ngsInternalFormsService);
     }
+    ngOnDestroy() {
+        this.ngsFormsService.clearInternalService(this.ngsInternalFormsService);
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.19", type: NgsFormComponent, isStandalone: true, selector: "ngs-form", providers: [NgsFormsInternalService], ngImport: i0, template: "<!-- Tracking by form group re-creates the tree whenever setFormConfig() is called again, since each call creates a new group. -->\n@for (entry of rendered(); track entry.group) {\n  <ng-container [ngs-form-group]=\"entry.group\" [ngs-form-item]=\"entry.root\"></ng-container>\n}\n", dependencies: [{ kind: "directive", type: NgsFormsFormItemDirective, selector: "[ngs-form-item]", inputs: ["ngs-form-item", "ngs-form-group", "ngs-form-array", "ngs-form-index"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
@@ -756,6 +863,8 @@ class NgsFormsFormArrayInternalService {
     formArray = new UntypedFormArray([]);
     /** Emits after a row is added or removed. */
     itemsChanged = new Subject();
+    /** Emits the index of a row right after it is removed. */
+    rowRemoved = new Subject();
     constructor() {
         if (this.config.initialItemCount) {
             for (let i = 0; i < this.config.initialItemCount; i++) {
@@ -764,16 +873,19 @@ class NgsFormsFormArrayInternalService {
         }
     }
     ngOnDestroy() {
+        this.itemsChanged.complete();
+        this.rowRemoved.complete();
     }
     /** Removes the row at `index`, unless that would go below `minItems`. */
     removeAt(index) {
         if (this.config?.minItems && this.formArray.controls.length <= this.config.minItems) {
             return;
         }
-        if (!this.formArray.controls.length) {
+        if (index < 0 || index >= this.formArray.controls.length) {
             return;
         }
         this.formArray.removeAt(index);
+        this.rowRemoved.next(index);
         this.itemsChanged.next();
     }
     /** Appends an empty row, unless the array already has `maxItems` rows. */
@@ -859,10 +971,33 @@ class NgsFormsFormArrayListComponent extends NgsFormsBaseClassFormComponent {
     internalArrayService = inject(NgsFormsFormArrayInternalService);
     myFormArray = this.internalArrayService.formArray;
     changeDetectorRef = inject(ChangeDetectorRef);
+    elementRef = inject(ElementRef);
+    injector = inject(Injector);
     ngOnInit() {
         this.subscribe(this.internalArrayService.itemsChanged, () => {
             this.changeDetectorRef.markForCheck();
         });
+        this.subscribe(this.internalArrayService.rowRemoved, (index) => this.restoreFocusAfterRemove(index));
+    }
+    /**
+     * 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.
+     */
+    restoreFocusAfterRemove(index) {
+        afterNextRender(() => {
+            const active = document.activeElement;
+            if (active && active !== document.body) {
+                return;
+            }
+            const host = this.elementRef.nativeElement;
+            const rows = Array.from(host.querySelectorAll(':scope > [data-index]'));
+            const row = rows[Math.min(index, rows.length - 1)];
+            const focusable = 'button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), a[href], [tabindex]:not([tabindex="-1"])';
+            const target = row?.querySelector('ngs-forms-form-array-remove-item button:not([disabled])') ??
+                row?.querySelector(focusable) ??
+                host.closest('ngs-forms-form-array')?.querySelector(focusable);
+            target?.focus();
+        }, { injector: this.injector });
     }
     /** Creates a `form-array-list` item. */
     static create(config) {
@@ -894,8 +1029,26 @@ class NgsFormsFormArrayRemoveItemComponent extends NgsFormsBaseClassFormComponen
     internalArrayService = inject(NgsFormsFormArrayInternalService);
     elementRef = inject(ElementRef);
     indexFromDi = inject(NGS_FORMS_ITEM_INDEX, { optional: true });
-    /** Index of the row this button belongs to. */
+    row = inject(NGS_FORMS_ARRAY_ROW, { optional: true });
+    changeDetectorRef = inject(ChangeDetectorRef);
+    /** Accessible name of the button, from `ariaLabel` or `${buttonText} item ${index + 1}`. */
+    get ariaLabel() {
+        const index = this.myIndex;
+        const label = this.config.ariaLabel;
+        if (typeof label === 'function')
+            return label(index);
+        if (label)
+            return label;
+        return `${this.config.buttonText || 'Remove'} item ${index + 1}`;
+    }
+    /** Current index of the row this button belongs to. */
     get myIndex() {
+        if (this.row) {
+            const index = this.internalArrayService.formArray.controls.indexOf(this.row);
+            if (index >= 0) {
+                return index;
+            }
+        }
         if (this.indexFromDi !== null && this.indexFromDi !== undefined) {
             return this.indexFromDi;
         }
@@ -912,6 +1065,10 @@ class NgsFormsFormArrayRemoveItemComponent extends NgsFormsBaseClassFormComponen
     constructor() {
         super();
     }
+    ngOnInit() {
+        // The row's position changes when earlier rows are removed, which changes the default accessible name.
+        this.subscribe(this.internalArrayService.itemsChanged, () => this.changeDetectorRef.markForCheck());
+    }
     /** Creates a `form-array-remove-item` item. */
     static create(config) {
         return {
@@ -924,11 +1081,11 @@ class NgsFormsFormArrayRemoveItemComponent extends NgsFormsBaseClassFormComponen
         this.internalArrayService.removeAt(this.myIndex);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsFormArrayRemoveItemComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.19", type: NgsFormsFormArrayRemoveItemComponent, isStandalone: true, selector: "ngs-forms-form-array-remove-item", usesInheritance: true, ngImport: i0, template: "<button\n  (click)=\"removeItem()\"\n  [class]=\"config.buttonClass || 'btn btn-outline-danger btn-sm'\"\n  type=\"button\">\n  @if (config.buttonIcon) {\n    <i [class]=\"config.buttonIcon\" aria-hidden=\"true\"></i>\n  }\n  {{ config.buttonText || 'Remove' }}\n</button>\n", changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.19", type: NgsFormsFormArrayRemoveItemComponent, isStandalone: true, selector: "ngs-forms-form-array-remove-item", usesInheritance: true, ngImport: i0, template: "<button\n  (click)=\"removeItem()\"\n  [class]=\"config.buttonClass || 'btn btn-outline-danger btn-sm'\"\n  [attr.aria-label]=\"ariaLabel\"\n  type=\"button\">\n  @if (config.buttonIcon) {\n    <i [class]=\"config.buttonIcon\" aria-hidden=\"true\"></i>\n  }\n  {{ config.buttonText || 'Remove' }}\n</button>\n", changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsFormArrayRemoveItemComponent, decorators: [{
             type: Component,
-            args: [{ selector: 'ngs-forms-form-array-remove-item', changeDetection: ChangeDetectionStrategy.OnPush, template: "<button\n  (click)=\"removeItem()\"\n  [class]=\"config.buttonClass || 'btn btn-outline-danger btn-sm'\"\n  type=\"button\">\n  @if (config.buttonIcon) {\n    <i [class]=\"config.buttonIcon\" aria-hidden=\"true\"></i>\n  }\n  {{ config.buttonText || 'Remove' }}\n</button>\n" }]
+            args: [{ selector: 'ngs-forms-form-array-remove-item', changeDetection: ChangeDetectionStrategy.OnPush, template: "<button\n  (click)=\"removeItem()\"\n  [class]=\"config.buttonClass || 'btn btn-outline-danger btn-sm'\"\n  [attr.aria-label]=\"ariaLabel\"\n  type=\"button\">\n  @if (config.buttonIcon) {\n    <i [class]=\"config.buttonIcon\" aria-hidden=\"true\"></i>\n  }\n  {{ config.buttonText || 'Remove' }}\n</button>\n" }]
         }], ctorParameters: () => [] });
 
 /**
@@ -963,6 +1120,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{ selector: 'ngs-form-component-text-div', imports: [], changeDetection: ChangeDetectionStrategy.OnPush, template: "<div class=\"{{ config.classes }}\">{{ config.text }}</div>\n" }]
         }] });
 
+;
+
 /**
  * Renders an HTML string inside the form. The HTML is passed through Angular's sanitizer.
  *
@@ -996,8 +1155,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{ selector: 'ngs-form-component-html-content', imports: [], changeDetection: ChangeDetectionStrategy.OnPush, template: "<div [innerHTML]=\"html\"></div>\n" }]
         }], ctorParameters: () => [] });
 
+/** @internal */
 const sectionConfigDefaults = {
     titleClass: 'h3',
+    headingLevel: 3,
     subtitleClass: 'lead',
 };
 
@@ -1006,10 +1167,13 @@ const sectionConfigDefaults = {
  * 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.
  */
 class NgsFormsFormSectionComponent extends NgsFormsBaseClassItemsContainerBase {
     static key = 'section';
+    /** Element id of the title, used to name the section's group. */
+    titleId = `${this.itemData.uuid || v4()}-section-title`;
     /** Creates a `section` item. */
     static create(config) {
         return {
@@ -1022,11 +1186,11 @@ class NgsFormsFormSectionComponent extends NgsFormsBaseClassItemsContainerBase {
         this.config = ngsDefaults(this.config, sectionConfigDefaults);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsFormSectionComponent, deps: null, target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.19", type: NgsFormsFormSectionComponent, isStandalone: true, selector: "ngs-forms-form-section", usesInheritance: true, ngImport: i0, template: "<div class=\"form-section\">\n  <div class=\"form-section-title {{config.titleClass}}\">{{ config.title }}</div>\n  @if (config.subtitle) {\n    <div class=\"form-section-subtitle {{config.subtitleClass}}\">{{ config.subtitle }}</div>\n  }\n  @if (config.items.length) {\n    <div class=\"form-section-items\">\n      @for (item of config.items; track item.uuid) {\n        <ng-container [ngs-form-item]=\"item\"></ng-container>\n      }\n    </div>\n  }\n</div>\n", dependencies: [{ kind: "directive", type: NgsFormsFormItemDirective, selector: "[ngs-form-item]", inputs: ["ngs-form-item", "ngs-form-group", "ngs-form-array", "ngs-form-index"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.19", type: NgsFormsFormSectionComponent, isStandalone: true, selector: "ngs-forms-form-section", usesInheritance: true, ngImport: i0, template: "<div class=\"form-section\" role=\"group\" [attr.aria-labelledby]=\"titleId\">\n  <div class=\"form-section-title {{config.titleClass}}\" role=\"heading\" [attr.aria-level]=\"config.headingLevel\" [id]=\"titleId\">{{ config.title }}</div>\n  @if (config.subtitle) {\n    <div class=\"form-section-subtitle {{config.subtitleClass}}\">{{ config.subtitle }}</div>\n  }\n  @if (config.items.length) {\n    <div class=\"form-section-items\">\n      @for (item of config.items; track item.uuid) {\n        <ng-container [ngs-form-item]=\"item\"></ng-container>\n      }\n    </div>\n  }\n</div>\n", dependencies: [{ kind: "directive", type: NgsFormsFormItemDirective, selector: "[ngs-form-item]", inputs: ["ngs-form-item", "ngs-form-group", "ngs-form-array", "ngs-form-index"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsFormSectionComponent, decorators: [{
             type: Component,
-            args: [{ selector: 'ngs-forms-form-section', imports: [NgsFormsFormItemDirective], changeDetection: ChangeDetectionStrategy.OnPush, template: "<div class=\"form-section\">\n  <div class=\"form-section-title {{config.titleClass}}\">{{ config.title }}</div>\n  @if (config.subtitle) {\n    <div class=\"form-section-subtitle {{config.subtitleClass}}\">{{ config.subtitle }}</div>\n  }\n  @if (config.items.length) {\n    <div class=\"form-section-items\">\n      @for (item of config.items; track item.uuid) {\n        <ng-container [ngs-form-item]=\"item\"></ng-container>\n      }\n    </div>\n  }\n</div>\n" }]
+            args: [{ selector: 'ngs-forms-form-section', imports: [NgsFormsFormItemDirective], changeDetection: ChangeDetectionStrategy.OnPush, template: "<div class=\"form-section\" role=\"group\" [attr.aria-labelledby]=\"titleId\">\n  <div class=\"form-section-title {{config.titleClass}}\" role=\"heading\" [attr.aria-level]=\"config.headingLevel\" [id]=\"titleId\">{{ config.title }}</div>\n  @if (config.subtitle) {\n    <div class=\"form-section-subtitle {{config.subtitleClass}}\">{{ config.subtitle }}</div>\n  }\n  @if (config.items.length) {\n    <div class=\"form-section-items\">\n      @for (item of config.items; track item.uuid) {\n        <ng-container [ngs-form-item]=\"item\"></ng-container>\n      }\n    </div>\n  }\n</div>\n" }]
         }] });
 
 // --
@@ -1066,5 +1230,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
  * Generated bundle index. Do not edit.
  */
 
-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 { 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 };
 //# sourceMappingURL=ng-simplicity-forms-core.mjs.map