@ng-simplicity/forms-core 1.1.2 → 1.1.4

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. */
@@ -55,10 +54,9 @@ interface NgsFormsFormItemConfigBase {
      */
     uuid?: string;
     /**
-     * Static visibility flag.
+     * Static visibility flag. `false` keeps the item out of the form, as if `visible$` had emitted `false`.
      *
-     * @notImplemented
-     * @remarks Reserved for future use: the renderer currently ignores it. Use `visible$` to show or hide an item.
+     * @remarks Ignored when `visible$` is also set.
      */
     visible?: boolean;
     /**
@@ -74,10 +72,14 @@ interface NgsFormsFormItemConfigBase {
      */
     visible$?: Observable<boolean>;
     /**
-     * Initial component state for this item.
+     * Initial component state for this item, read by input components through `commonState()`.
      *
-     * @notImplemented
-     * @remarks Reserved for future use.
+     * @remarks Applied when the component is first created, unless state for this item's `uuid` was already set.
+     * It takes precedence over state set by `name` and over global state.
+     * @example
+     * ```ts
+     * initialState: { displayMode: 'summary', showEditToggle: true }
+     * ```
      */
     initialState?: any;
 }
@@ -109,17 +111,19 @@ interface NgsFormsFormItemConfigBaseItemWithNameAndValidators extends NgsFormsFo
      */
     errorMessageMap?: NgsFormsFormErrorKeyValueMap;
     /**
-     * Static disabled flag.
+     * Static disabled flag. `true` disables the item's control (and, for groups and arrays, every control inside).
      *
-     * @notImplemented
-     * @remarks Reserved for future use: the built-in components do not read it yet.
+     * @remarks Ignored when `disabled$` is also set. Disabled controls are left out of `NgsFormsService.formValue$`
+     * and skip validation, which is how Angular reactive forms treat them.
      */
     disabled?: boolean;
     /**
-     * Stream that controls the disabled state.
+     * Stream that controls the disabled state. Each emission disables (`true`) or enables (`false`) the control.
      *
-     * @notImplemented
-     * @remarks Reserved for future use: the built-in components do not read it yet.
+     * @example
+     * ```ts
+     * disabled$: this.forms.formValue$.pipe(map((v) => !v?.profile?.hasCompany))
+     * ```
      */
     disabled$?: Observable<boolean>;
     /**
@@ -128,29 +132,23 @@ 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>>;
 }
 /** Base configuration for a labelled input control. */
 interface NgsFormsFormItemConfigBaseInput extends NgsFormsFormItemConfigBaseItemWithNameAndValidators {
     /**
-     * Optional element id.
+     * Element id for the input. When omitted the component generates a unique one.
      *
-     * @notImplemented
-     * @remarks Reserved for future use: the built-in components generate their own ids.
+     * @remarks Must be unique on the page, so avoid it inside form array rows.
      */
     id?: string;
     /** Label text shown next to or above the control. */
     label: string;
     /**
-     * Initial value.
-     *
-     * @notImplemented
-     * @remarks Reserved for future use. Set initial values with `NgsFormsService.patchValue()` after the form renders.
+     * Initial value of the control. Applied when the control is created, including when a `visible$` item is shown
+     * again.
      */
     value?: unknown;
 }
@@ -194,9 +192,22 @@ interface NgsFormsFormItem<T extends NgsFormsFormItemConfigBase> {
     config: T;
 }
 
+/**
+ * State that components read through `commonState()`. Set it with `globalState` / `initialState` in the config, or
+ * at runtime with `NgsFormsService.updateGlobalState()` and `updateComponentState()`.
+ *
+ * @remarks The built-in theme components do not read these yet. They are a contract for your own components.
+ */
 interface NgsFormsCommonComponentState {
+    /**
+     * `input` shows the editable control. `summary` shows a compact, read-only display of the current value, for
+     * example to save space on small screens.
+     */
     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 {
@@ -222,19 +233,30 @@ interface NgsFormsFormConfig<T = NgsFormsFormItem<any>> {
      * @remarks Reserved for future use: values currently update on every change.
      */
     inputUpdateDebounce: number;
-    /** Initial state shared by every component in the form. */
+    /**
+     * Initial state shared by every component in the form. Applied each time `setFormConfig()` is called; change it
+     * later with `NgsFormsService.updateGlobalState()`.
+     */
     globalState: NgsFormsGlobalFormState;
     /**
      * The root item, usually an `NgsFormsFormGroupComponent`, whose form group backs the whole form.
      */
     root: T;
     /**
-     * Initial form state.
+     * Initial state for individual components, keyed by item `uuid` or control `name`.
      *
-     * @notImplemented
-     * @remarks Reserved for future use.
+     * @remarks Applied each time `setFormConfig()` is called, together with `globalState`. Same as calling
+     * `NgsFormsService.updateComponentState(key, state)` for each entry before the form renders.
+     * @example
+     * ```ts
+     * initialState: { email: { displayMode: 'input' } }
+     * ```
      */
-    initialState?: any;
+    initialState?: {
+        [componentKey: string]: NgsFormsCommonComponentState & {
+            [key: string]: any;
+        };
+    };
 }
 
 /**
@@ -246,7 +268,10 @@ interface NgsFormsFormConfig<T = NgsFormsFormItem<any>> {
 declare abstract class NgsFormsBaseClassFormComponent<T extends NgsFormsFormItemConfigBase> extends NgsSubscriber {
     /** Registry key the component is registered under. */
     static key: string;
-    /** Unique id for this component instance, handy for `id` and `for` attributes. */
+    /**
+     * Element id for this component, handy for `id` and `for` attributes. The config's `id` when it sets one,
+     * otherwise a generated unique id.
+     */
     id: string;
     /** The item's configuration. */
     protected config: T;
@@ -258,12 +283,17 @@ declare abstract class NgsFormsBaseClassFormComponent<T extends NgsFormsFormItem
 }
 
 /**
- * Base class for items that own a form control. Creates the control, applies `validators` / `validators$`,
- * registers it with the parent group under `config.name` and keeps `errorMessage` up to date.
+ * 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.
@@ -274,12 +304,18 @@ declare class NgsFormsFormItemWithVisibleAndValidatorsBase<T extends NgsFormsFor
     private changeDetectorRef;
     /** Whether the form has been marked as submitted with `NgsFormsService.setIsSubmitted()`. */
     readonly submitted: Signal<boolean>;
+    /** 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;
-    static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsFormItemWithVisibleAndValidatorsBase<any>, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<NgsFormsFormItemWithVisibleAndValidatorsBase<any>, never, never, {}, {}, never, never, true, never>;
+    private bindDisabled;
+    private applyDisabled;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsFormItemWithVisibleAndValidatorsBase<any, any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgsFormsFormItemWithVisibleAndValidatorsBase<any, any>, never, never, {}, {}, never, never, true, never>;
 }
 
 /**
@@ -321,12 +357,19 @@ declare class NgsFormsInternalService {
         [key: string]: any;
     }>;
     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;
-    updateGlobalState(state: NgsFormsGlobalFormState): void;
-    updateComponentState(componentKey: string, state: any): void;
-    subscribeToState(uuid: string, name?: string): rxjs.Observable<any>;
+    /** Sets a component's state from its config's `initialState`, unless state for `uuid` already exists. */
+    seedComponentState(uuid: string, initialState: 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): Observable<NgsFormsCommonComponentState>;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsInternalService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<NgsFormsInternalService>;
 }
@@ -349,10 +392,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.
      *
@@ -362,8 +401,12 @@ 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;
     /** `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. */
@@ -373,14 +416,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.
@@ -391,9 +441,9 @@ 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;
     /**
      * Patches values into the form, using the same shape as `formValue$` (including the root group name).
@@ -418,11 +468,10 @@ declare abstract class NgsFormsBaseClassFormInputComponent<T extends NgsFormsFor
     /** Merged state for this component: its own state, then state by name, then global state. */
     readonly commonState: Signal<NgsFormsCommonComponentState>;
     /**
-     * Switches between input and summary display.
-     *
-     * @notImplemented
+     * Switches this component between `input` and `summary` display by updating its own state.
+     * With no argument it flips the current mode.
      */
-    toggleDisplayMode(setTo: 'summary' | 'input'): void;
+    toggleDisplayMode(setTo?: 'summary' | 'input'): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsBaseClassFormInputComponent<any>, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<NgsFormsBaseClassFormInputComponent<any>, never, never, {}, {}, never, never, true, never>;
 }
@@ -453,7 +502,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>;
@@ -464,6 +513,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>;
 }
@@ -474,8 +524,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
@@ -539,12 +599,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;
 }
@@ -555,7 +623,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. */
@@ -563,7 +631,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;
@@ -571,7 +640,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>;
@@ -639,7 +711,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>;
@@ -663,13 +735,6 @@ interface NgsFormItemArrayAddItemConfig extends NgsFormsFormItemConfigBase {
     buttonClass?: string;
     /** Class of an `<i>` icon shown before the label, for example `bi bi-plus`. */
     buttonIcon?: string;
-    /**
-     * Callback after a row is added.
-     *
-     * @notImplemented
-     * @remarks Reserved for future use.
-     */
-    onAddItem?: () => void;
 }
 
 /** Configuration for `NgsFormsFormArrayContainerComponent`. */
@@ -699,7 +764,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);
@@ -719,6 +784,8 @@ declare class NgsFormsFormArrayInternalService implements OnDestroy {
     readonly formArray: UntypedFormArray;
     /** 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`. */
@@ -763,7 +830,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;
@@ -786,12 +860,11 @@ interface NgsFormItemArrayRemoveItemConfig extends NgsFormsFormItemConfigBase {
     /** Class of an `<i>` icon shown before the label, for example `bi bi-trash`. */
     buttonIcon?: string;
     /**
-     * Callback after a row is removed.
-     *
-     * @notImplemented
-     * @remarks Reserved for future use.
+     * 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`
      */
-    onRemoveItem?: () => void;
+    ariaLabel?: string | ((index: number) => string);
 }
 
 /**
@@ -800,14 +873,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;
@@ -862,22 +940,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;
@@ -899,5 +998,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, 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 };

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@ng-simplicity/forms-core",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/BryanGWalsh/NgSimplicityForms.git",
     "directory": "libs/forms-core"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "peerDependencies": {
     "@angular/common": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",
     "@angular/core": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",