@ng-simplicity/forms-core 1.1.1 → 1.1.3

package/index.d.ts

@@ -2,20 +2,28 @@ 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 * as i2 from '@angular/forms';
+import * as _angular_forms from '@angular/forms';
 import { ValidatorFn, UntypedFormControl, FormGroup, AbstractControl, UntypedFormGroup, UntypedFormArray, FormArray } from '@angular/forms';
 import * as _ng_simplicity_forms_core from '@ng-simplicity/forms-core';
 import * as i1 from '@angular/common';
 
+/** Base class that ties RxJS subscriptions to the component's lifetime. */
 declare abstract class NgsSubscriber {
     protected readonly destroy$: Subject<void>;
     protected subscriptions: Subscription[];
+    /** Subscribes to `subscribeTo` until the component is destroyed. */
     subscribe<T>(subscribeTo: Observable<T>, nextObserver: (value: T) => void): void;
     ngOnDestroy(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsSubscriber, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<NgsSubscriber, never, never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Shape for server side validation errors, nested to mirror the form structure.
+ *
+ * @notImplemented
+ * @remarks Reserved for future use: nothing in the library consumes it yet.
+ */
 interface NgsServerSideValidationErrorObjectType {
     key: string;
     path: string;
@@ -24,103 +32,319 @@ interface NgsServerSideValidationErrorObjectType {
     children: NgsServerSideValidationErrorObjectType[];
 }
 
+/** Map of validator error keys to user facing messages. */
 type NgsFormsFormErrorKeyValueMap = {
     [key: string]: string;
 };
 
+/** One option of a radio group or select. */
 interface NgsFormsFormInputOption {
+    /** Value written to the form control when the option is chosen. */
     id: string;
+    /** Text shown to the user. */
     label: string;
+    /** Renders the option but prevents choosing it. */
     disabled?: boolean;
 }
 
+/** Base configuration shared by every form item (inputs, containers and content items). */
 interface NgsFormsFormItemConfigBase {
+    /**
+     * Stable identifier for the item. Generated with `uuid` by the `create()` factories when omitted.
+     * Component state set with `NgsFormsService.updateComponentState()` can be keyed by this value.
+     */
     uuid?: string;
+    /**
+     * Static visibility flag. `false` keeps the item out of the form, as if `visible$` had emitted `false`.
+     *
+     * @remarks Ignored when `visible$` is also set.
+     */
     visible?: boolean;
+    /**
+     * Stream that controls whether the item is rendered.
+     *
+     * @remarks When the stream emits `false` the item's component is destroyed and its control is removed from the
+     * parent form group, so hidden fields are excluded from the form value and from validation. When it emits `true`
+     * the component is created again with a fresh control. Items without `visible$` are always rendered.
+     * @example
+     * ```ts
+     * visible$: this.forms.formValue$.pipe(map((v) => v?.profile?.contactMethod === 'email'))
+     * ```
+     */
     visible$?: Observable<boolean>;
+    /**
+     * Initial component state for this item, read by input components through `commonState()`.
+     *
+     * @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;
 }
+/**
+ * Configuration for items that render a list of child items without creating a form control of their own
+ * (for example sections and columns).
+ */
 interface NgsFormsFormItemContainerConfigBase extends NgsFormsFormItemConfigBase {
+    /** The child items to render, in order. */
     items: Array<NgsFormsFormItem<any>>;
 }
+/**
+ * Configuration for `NgsFormsFormGroupComponent`: a named group of child items backed by an `UntypedFormGroup`.
+ */
 interface NgsFormsFormGroupConfig extends NgsFormsFormItemConfigBaseItemWithNameAndValidators, NgsFormsFormItemContainerConfigBase {
 }
+/** Base configuration for items that own a form control (inputs, groups and arrays). */
 interface NgsFormsFormItemConfigBaseItemWithNameAndValidators extends NgsFormsFormItemConfigBase {
+    /**
+     * Control name inside the parent form group. Becomes the key of this item's value in `NgsFormsService.formValue$`.
+     */
     name: string;
+    /**
+     * Maps validator error keys (for example `required`, `minlength`, `email`) to the message shown to the user.
+     *
+     * @remarks Only the first error on the control is displayed. Errors without an entry fall back to
+     * `Field is invalid: <errorKey>`. Messages appear once the control is touched or dirty, or after
+     * `NgsFormsService.setIsSubmitted(true)`.
+     */
     errorMessageMap?: NgsFormsFormErrorKeyValueMap;
+    /**
+     * Static disabled flag. `true` disables the item's control (and, for groups and arrays, every control inside).
+     *
+     * @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. Each emission disables (`true`) or enables (`false`) the control.
+     *
+     * @example
+     * ```ts
+     * disabled$: this.forms.formValue$.pipe(map((v) => !v?.profile?.hasCompany))
+     * ```
+     */
     disabled$?: Observable<boolean>;
+    /**
+     * Angular validators applied to the item's control. Takes precedence over `validators$` when both are set.
+     */
     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.
+     */
     validators$?: Observable<Array<ValidatorFn>>;
 }
+/** Base configuration for a labelled input control. */
 interface NgsFormsFormItemConfigBaseInput extends NgsFormsFormItemConfigBaseItemWithNameAndValidators {
+    /**
+     * Element id for the input. When omitted the component generates a unique one.
+     *
+     * @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 of the control. Applied when the control is created, including when a `visible$` item is shown
+     * again.
+     */
     value?: unknown;
 }
+/** Base configuration for single line text inputs. */
 interface NgsFormsFormItemConfigBaseTextInput extends NgsFormsFormItemConfigBaseInput {
+    /** Placeholder text shown while the input is empty. */
     placeholder?: string;
+    /**
+     * The HTML input type.
+     * @defaultValue 'text'
+     */
     type?: 'text' | 'email' | 'password';
 }
+/**
+ * Base configuration for inputs that choose from a list of options (radio groups and selects).
+ */
 interface NgsFormsFormItemConfigBaseInputWithOptions extends NgsFormsFormItemConfigBaseInput {
+    /** Static list of options. Used as the initial value when `options$` is also set. */
     options?: Array<NgsFormsFormInputOption>;
+    /**
+     * Stream of options. Each emission replaces the rendered options, which makes cascading selects and
+     * server-loaded option lists possible.
+     */
     options$?: Observable<Array<NgsFormsFormInputOption>>;
 }
 
+/**
+ * A node in the form tree: which registered component to render (`type`) and the configuration to give it.
+ *
+ * @remarks You rarely build these by hand. Every built-in component has a static `create(config)` factory that
+ * returns one with the right `type` and a generated `uuid`.
+ */
 interface NgsFormsFormItem<T extends NgsFormsFormItemConfigBase> {
+    /** Unique identifier of the node. */
     uuid?: string;
+    /**
+     * Registry key of the component that renders this item, for example `input-text` or `form-group`.
+     */
     type: string;
+    /** The configuration handed to the component through the `NGS_FORMS_ITEM_DATA` token. */
     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;
 }
 
 interface NgsFormsGlobalFormState extends NgsFormsCommonComponentState {
 }
 
+/**
+ * The top level configuration passed to `NgsFormsService.setFormConfig()`.
+ *
+ * @example
+ * ```ts
+ * const config: NgsFormsFormConfig = {
+ *   inputUpdateDebounce: 0,
+ *   globalState: {},
+ *   root: NgsFormsFormGroupComponent.create({ name: 'profile', items: [ ... ] }),
+ * };
+ * ```
+ */
 interface NgsFormsFormConfig<T = NgsFormsFormItem<any>> {
+    /**
+     * Debounce, in milliseconds, for input value updates.
+     *
+     * @notImplemented
+     * @remarks Reserved for future use: values currently update on every change.
+     */
     inputUpdateDebounce: number;
+    /**
+     * 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;
-    initialState?: any;
+    /**
+     * Initial state for individual components, keyed by item `uuid` or control `name`.
+     *
+     * @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?: {
+        [componentKey: string]: NgsFormsCommonComponentState & {
+            [key: string]: any;
+        };
+    };
 }
 
+/**
+ * Root base class for every form item component. Reads the item's configuration from `NGS_FORMS_ITEM_DATA`.
+ *
+ * @remarks Extend it for components that do not own a form control, such as static content or buttons. Declare a
+ * `static key` and a `static create(config)` factory so the component can be registered and used in configs.
+ */
 declare abstract class NgsFormsBaseClassFormComponent<T extends NgsFormsFormItemConfigBase> extends NgsSubscriber {
+    /** Registry key the component is registered under. */
     static key: string;
+    /**
+     * 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;
+    /** The full form item: `uuid`, `type` and `config`. */
     protected readonly itemData: NgsFormsFormItem<T>;
     constructor();
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsBaseClassFormComponent<any>, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<NgsFormsBaseClassFormComponent<any>, never, never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * 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.
+ */
 declare class NgsFormsFormItemWithVisibleAndValidatorsBase<T extends NgsFormsFormItemConfigBaseItemWithNameAndValidators> extends NgsFormsBaseClassFormComponent<T> implements OnInit, OnDestroy {
+    /** The item's form control. Bind it with `[formControl]`. */
     control: UntypedFormControl | 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.
+     */
     errorMessage: string;
     private formAddRemoveFns;
     private privateService;
     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;
     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>;
 }
 
+/**
+ * Maps registry keys (the `type` of an `NgsFormsFormItem`) to the Angular components that render them.
+ *
+ * @remarks The service is provided in the `platform` injector, so there is one registry per page. Registering a
+ * key again replaces the previous component, which is how a theme package or your own component can override a
+ * built-in one. Register components before the form renders, typically in the constructor of the component that
+ * hosts `<ngs-form>`.
+ * @example
+ * ```ts
+ * constructor(registry: NgsFormsComponentRegistryService) {
+ *   NgsFormsBootstrapModule.registerAllBootStrapComponents(registry);
+ *   registry.register(MyRatingComponent.key, MyRatingComponent);
+ * }
+ * ```
+ */
 declare class NgsFormsComponentRegistryService {
     private readonly itemComponentRegistry;
+    /** Returns the component registered for `key`, or `undefined` when nothing is registered. */
     getComponentTypeForKey(key: string): Type<unknown> | undefined;
+    /** Registers `component` under `key`, replacing any component already registered for it. */
     register(key: string, component: Type<unknown>): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsComponentRegistryService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<NgsFormsComponentRegistryService>;
 }
 
+/**
+ * Per form state holder that connects `<ngs-form>`, its items and `NgsFormsService`.
+ *
+ * @remarks Provided by `NgsFormComponent`. Application code should use `NgsFormsService` instead; this service is
+ * exported for authors of custom components and may change between minor versions.
+ */
 declare class NgsFormsInternalService {
     formGroup$: BehaviorSubject<FormGroup<any>>;
     formConfig$: BehaviorSubject<NgsFormsFormConfig<NgsFormsFormItem<any>> | undefined>;
@@ -132,69 +356,167 @@ declare class NgsFormsInternalService {
     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;
-    subscribeToState(uuid: string, name?: string): rxjs.Observable<any>;
+    /**
+     * 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>;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsInternalService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<NgsFormsInternalService>;
 }
 
+/**
+ * The public API of a form. Provide it on the component that hosts `<ngs-form>` so each form gets its own instance.
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   selector: 'app-profile',
+ *   imports: [NgsFormComponent],
+ *   providers: [NgsFormsService],
+ *   template: `<ngs-form />`,
+ * })
+ * export class ProfileComponent {
+ *   private readonly forms = inject(NgsFormsService);
+ *   readonly value = toSignal(this.forms.formValue$);
+ * }
+ * ```
+ */
 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.
+     *
+     * @remarks The value is keyed by the root group's `name`, for example `{ profile: { firstName: 'Ada' } }`.
+     */
     formValue$: BehaviorSubject<any>;
+    /** The latest value emitted by `formValue$`. */
     formValue: any;
     private internalFormService;
     private formGroupSubscriptions;
     private formGroup;
+    /** `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. */
     get isValid(): boolean;
+    /** `true` once `<ngs-form>` has connected to this service. */
     get internalServiceIsSet(): boolean;
+    /**
+     * 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.
+     */
     setFormConfig(formConfig: NgsFormsFormConfig): void;
+    /**
+     * @internal
+     */
     setInternalService(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.
+     */
     setIsSubmitted(isSubmitted: boolean): void;
     private bindFormGroup;
+    /**
+     * 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;
+    /** Merges `state` into the state shared by every component in the form. */
     updateGlobalState(state: any): void;
     ngOnDestroy(): 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.
+     */
     patchValue(entityData: any): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<NgsFormsService>;
 }
 
+/**
+ * Base class for input components. Adds access to the form's `NgsFormsService` and the merged component state.
+ *
+ * @remarks This is the class to extend when you build your own input. See the Custom components guide.
+ */
 declare abstract class NgsFormsBaseClassFormInputComponent<T extends NgsFormsFormItemConfigBaseInput> extends NgsFormsFormItemWithVisibleAndValidatorsBase<T> {
+    /** The `NgsFormsService` of the form this input belongs to. */
     readonly myFormService: NgsFormsService;
     private readonly internalService;
+    /** Merged state for this component: its own state, then state by name, then global state. */
     readonly commonState: Signal<NgsFormsCommonComponentState>;
-    toggleDisplayMode(setTo: 'summary' | 'input'): void;
+    /**
+     * 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;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsBaseClassFormInputComponent<any>, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<NgsFormsBaseClassFormInputComponent<any>, never, never, {}, {}, never, never, true, never>;
 }
 
+/** Base class for container items that render `config.items` without owning a form control. */
 declare class NgsFormsBaseClassItemsContainerBase<T extends NgsFormsFormItemContainerConfigBase> extends NgsFormsBaseClassFormComponent<T> implements OnDestroy {
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsBaseClassItemsContainerBase<any>, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<NgsFormsBaseClassItemsContainerBase<any>, never, never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Base class for inputs with options. Exposes `options` as a signal that follows `options$` when given and falls
+ * back to the static `options`.
+ */
 declare class NgsFormsBaseClassFormItemInputWithOptionsComponent<T extends NgsFormsFormItemConfigBaseInputWithOptions> extends NgsFormsBaseClassFormInputComponent<T> {
+    /** The current options. */
     options: Signal<Array<NgsFormsFormInputOption>>;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsBaseClassFormItemInputWithOptionsComponent<any>, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<NgsFormsBaseClassFormItemInputWithOptionsComponent<any>, never, never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Renders the form described by the `NgsFormsFormConfig` given to the nearest `NgsFormsService`.
+ *
+ * @remarks Place it in the template of the component that provides `NgsFormsService`. It takes no inputs.
+ * @example
+ * ```html
+ * <ngs-form></ngs-form>
+ * ```
+ */
 declare class NgsFormComponent {
     private readonly ngsInternalFormsService;
     readonly ngsFormsService: NgsFormsService;
-    readonly formGroup: i0.Signal<i2.FormGroup<any> | undefined>;
+    readonly formGroup: i0.Signal<_angular_forms.FormGroup<any> | undefined>;
     readonly formConfig: i0.Signal<_ng_simplicity_forms_core.NgsFormsFormConfig<_ng_simplicity_forms_core.NgsFormsFormItem<any>> | undefined>;
+    /** The root item to render with the form group it belongs to (empty until a config is set). */
+    readonly rendered: i0.Signal<{
+        group: _angular_forms.FormGroup<any>;
+        root: _ng_simplicity_forms_core.NgsFormsFormItem<any>;
+    }[]>;
     constructor();
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NgsFormComponent, "ngs-form", never, {}, {}, never, never, true, never>;
 }
 
+/** Injection token for the `NgsFormsFormItem` a component is rendering. */
 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>;
 type FormControlAddRemoveFn = (control: AbstractControl, controlName: string) => void;
+/**
+ * @internal
+ */
 interface INgsFormsFormControlAddRemove {
     add: FormControlAddRemoveFn;
     remove: FormControlAddRemoveFn;
@@ -203,6 +525,9 @@ interface IControlAddRemoveFunctionsBuilder {
     formGroup: (formGroup: UntypedFormGroup) => INgsFormsFormControlAddRemove;
     formArray: (formArray: UntypedFormArray) => INgsFormsFormControlAddRemove;
 }
+/**
+ * @internal
+ */
 declare const NgsFormsFormControlAddRemoveFunctions: IControlAddRemoveFunctionsBuilder;
 
 /**
@@ -210,11 +535,34 @@ declare const NgsFormsFormControlAddRemoveFunctions: IControlAddRemoveFunctionsB
  * Returns a new object with properties from source assigned to target
  * if the properties are undefined or missing on target.
  */
+/**
+ * Returns a copy of `target` with any `undefined` properties filled in from `source`. A dependency free
+ * alternative to lodash `defaults`, handy for applying default config values in custom components.
+ */
 declare function ngsDefaults<T extends object, U extends object>(target: T, source: U): T & U;
 
+/**
+ * Function form of a visibility rule.
+ *
+ * @notImplemented
+ * @remarks Reserved for future use. Use `visible$` today.
+ */
 type NgsFormItemVisibilityFn = (params: NgsFormsFunctionParameters) => Observable<boolean> | boolean;
+/**
+ * Function form of a validator rule.
+ *
+ * @notImplemented
+ * @remarks Reserved for future use. Use `validators$` today.
+ */
 type NgsFormValidatorArrayBuilderFn = (params: NgsFormsFunctionParameters) => Observable<Array<ValidatorFn>> | Array<ValidatorFn>;
+/**
+ * Function form of a disable rule.
+ *
+ * @notImplemented
+ * @remarks Reserved for future use.
+ */
 type NgsFormDisableFn = (params: NgsFormsFunctionParameters) => Observable<boolean> | boolean;
+/** Parameters passed to the function rule types. */
 interface NgsFormsFunctionParameters {
     injector: Injector;
     formGroup: UntypedFormGroup;
@@ -238,10 +586,22 @@ declare class NgsFormItemController extends NgsSubscriber {
     private detach;
 }
 
+/**
+ * Structural building block that looks up a form item's component in the registry and renders it.
+ *
+ * @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 {
+    /** The item to render. */
     itemData: NgsFormsFormItem<any> | undefined;
+    /** Form group that the item's control is added to. */
     formGroup?: UntypedFormGroup;
+    /** 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?: number;
     controller: NgsFormItemController | undefined;
     private readonly viewContainerRef;
@@ -254,31 +614,71 @@ declare class NgsFormsFormItemDirective implements OnInit, OnDestroy {
     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>;
 }
 
+/**
+ * Renders its items one after another without any wrapper markup. Useful as a grouping node inside a row.
+ *
+ * @remarks Registry key: `column`. Does not create a form control.
+ */
 declare class NgsFormsColumnComponent extends NgsFormsBaseClassItemsContainerBase<NgsFormsFormItemContainerConfigBase> {
     static key: string;
+    /** Creates a `column` item. */
     static create(config: NgsFormsFormItemContainerConfigBase): NgsFormsFormItem<NgsFormsFormItemContainerConfigBase>;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsColumnComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NgsFormsColumnComponent, "ngs-form-component-column", never, {}, {}, never, never, true, never>;
 }
 
+/** Configuration for `NgsFormsRowComponent`. */
 interface NgsFormItemRowConfig extends NgsFormsFormItemConfigBase {
+    /** Class for the element that wraps the whole row. */
     containerClass?: string;
+    /** Class for each item's wrapper, matched by index. */
     columnClasses?: Array<string> | string;
+    /** Class applied to every item's wrapper. Takes precedence over `columnClasses`. */
     columnClass?: string;
+    /** Items to lay out. */
     items: Array<NgsFormsFormItem<any>>;
 }
 
+/**
+ * Lays out items side by side. Each item is wrapped in a div whose class comes from `columnClass` (same for every
+ * item) or `columnClasses` (one per item), so it works with any CSS grid system.
+ *
+ * @remarks Registry key: `form-row`. Does not create a form control.
+ * @example
+ * ```ts
+ * NgsFormsRowComponent.create({
+ *   containerClass: 'row g-3',
+ *   columnClasses: ['col-md-6', 'col-md-6'],
+ *   items: [firstName, lastName],
+ * })
+ * ```
+ */
 declare class NgsFormsRowComponent extends NgsFormsBaseClassFormComponent<NgsFormItemRowConfig> {
     static key: string;
     constructor();
     getIndividualRowDivClass(index: number): string;
+    /** Creates a `form-row` item. */
     static create(config: NgsFormItemRowConfig): NgsFormsFormItem<NgsFormItemRowConfig>;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsRowComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NgsFormsRowComponent, "ngs-forms-row-component", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * A named group of items backed by an `UntypedFormGroup`. Its value is nested under `name` in the form value.
+ *
+ * @remarks Registry key: `form-group`. Usually the `root` of a form, and also useful for nesting related fields
+ * (an address, for example) or for hiding a whole group with `visible$`.
+ * @example
+ * ```ts
+ * NgsFormsFormGroupComponent.create({
+ *   name: 'address',
+ *   items: [addressLine1, city, postcode],
+ * })
+ * ```
+ */
 declare class NgsFormsFormGroupComponent extends NgsFormsFormItemWithVisibleAndValidatorsBase<NgsFormsFormGroupConfig> implements OnInit {
     static key: string;
+    /** Creates a `form-group` item. */
     static create(config: NgsFormsFormGroupConfig): NgsFormsFormItem<NgsFormsFormGroupConfig>;
     get formGroupControl(): UntypedFormGroup;
     constructor();
@@ -286,83 +686,152 @@ declare class NgsFormsFormGroupComponent extends NgsFormsFormItemWithVisibleAndV
     static ɵcmp: i0.ɵɵComponentDeclaration<NgsFormsFormGroupComponent, "ngs-forms-form-group", never, {}, {}, never, never, true, never>;
 }
 
+/** Configuration for `NgsFormsFormArrayAddItemComponent`. */
 interface NgsFormItemArrayAddItemConfig extends NgsFormsFormItemConfigBase {
+    /**
+     * Button label.
+     * @defaultValue 'Add Item'
+     */
     buttonText?: string;
+    /**
+     * Button class.
+     * @defaultValue 'btn btn-outline-primary'
+     */
     buttonClass?: string;
+    /** Class of an `<i>` icon shown before the label, for example `bi bi-plus`. */
     buttonIcon?: string;
-    onAddItem?: () => void;
 }
 
+/** Configuration for `NgsFormsFormArrayContainerComponent`. */
 interface NgsFormItemArrayConfig extends NgsFormsFormItemConfigBaseItemWithNameAndValidators {
+    /** Number of rows created when the array first renders. */
     initialItemCount?: number;
+    /** Remove buttons do nothing while the array has this many rows or fewer. */
     minItems?: number;
+    /** Add buttons do nothing once the array has this many rows. */
     maxItems?: number;
+    /** Class for the element that wraps the array's items. */
     containerClass?: string;
+    /**
+     * Class for each row.
+     *
+     * @notImplemented
+     * @remarks Reserved for future use. Set `containerClass` on `NgsFormsFormArrayListComponent` to style rows.
+     */
     itemContainerClass?: string;
+    /** Items rendered inside the array: typically a list plus an add button. */
     items: Array<NgsFormsFormItem<any>>;
 }
 
+/**
+ * A repeatable list of rows backed by an `UntypedFormArray`. Its value is an array under `name`.
+ *
+ * @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> {
     private formArrayService;
     static key: string;
     constructor(formArrayService: NgsFormsFormArrayInternalService);
+    /** Creates a `form-array` item. */
     static create(config: NgsFormItemArrayConfig): NgsFormsFormItem<NgsFormItemArrayConfig>;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsFormArrayContainerComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NgsFormsFormArrayContainerComponent, "ngs-forms-form-array", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Holds the `UntypedFormArray` of one `NgsFormsFormArrayContainerComponent` and is shared with its list and buttons.
+ *
+ * @remarks Inject it in a custom component placed inside a form array to add or remove rows programmatically.
+ */
 declare class NgsFormsFormArrayInternalService implements OnDestroy {
     config: NgsFormItemArrayConfig;
     readonly formArray: UntypedFormArray;
+    /** Emits after a row is added or removed. */
     readonly itemsChanged: Subject<void>;
     constructor();
     ngOnDestroy(): void;
+    /** Removes the row at `index`, unless that would go below `minItems`. */
     removeAt(index: number): void;
+    /** Appends an empty row, unless the array already has `maxItems` rows. */
     addItem(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsFormArrayInternalService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<NgsFormsFormArrayInternalService>;
 }
 
+/**
+ * A button that appends a row to the enclosing form array, up to `maxItems`.
+ *
+ * @remarks Registry key: `form-array-add-item`. Must be placed inside an `NgsFormsFormArrayContainerComponent`.
+ */
 declare class NgsFormsFormArrayAddItemComponent extends NgsFormsBaseClassFormComponent<NgsFormItemArrayAddItemConfig> {
     static key: string;
     internalArrayService: NgsFormsFormArrayInternalService;
+    /** Creates a `form-array-add-item` item. */
     static create(config: NgsFormItemArrayAddItemConfig): NgsFormsFormItem<NgsFormItemArrayAddItemConfig>;
     addItem(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsFormArrayAddItemComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NgsFormsFormArrayAddItemComponent, "ngs-forms-form-array-add-item", never, {}, {}, never, never, true, never>;
 }
 
+/** Configuration for `NgsFormsFormArrayListComponent`. */
 interface NgsFormsFormArrayListConfig extends NgsFormsFormItemConfigBase {
+    /** The item rendered for each row, usually a row or column of inputs. */
     templateItem: NgsFormsFormItem<any>;
+    /** Class for the element that wraps each row. */
     containerClass?: string;
 }
 
+/**
+ * Renders one copy of `templateItem` for every row of the enclosing form array. Each row gets its own form group,
+ * so the controls in the template become the properties of each array entry.
+ *
+ * @remarks Registry key: `form-array-list`. Must be placed inside an `NgsFormsFormArrayContainerComponent`.
+ */
 declare class NgsFormsFormArrayListComponent extends NgsFormsBaseClassFormComponent<NgsFormsFormArrayListConfig> implements OnInit {
     static key: string;
     internalArrayService: NgsFormsFormArrayInternalService;
     myFormArray: FormArray<any>;
     private changeDetectorRef;
     ngOnInit(): void;
+    /** Creates a `form-array-list` item. */
     static create(config: NgsFormsFormArrayListConfig): NgsFormsFormItem<NgsFormsFormArrayListConfig>;
     castToFormGroup(control: AbstractControl): UntypedFormGroup;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsFormArrayListComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NgsFormsFormArrayListComponent, "ngs-forms-form-array-list", never, {}, {}, never, never, true, never>;
 }
 
+/** Configuration for `NgsFormsFormArrayRemoveItemComponent`. */
 interface NgsFormItemArrayRemoveItemConfig extends NgsFormsFormItemConfigBase {
+    /**
+     * Button label.
+     * @defaultValue 'Remove'
+     */
     buttonText?: string;
+    /**
+     * Button class.
+     * @defaultValue 'btn btn-outline-danger btn-sm'
+     */
     buttonClass?: string;
+    /** Class of an `<i>` icon shown before the label, for example `bi bi-trash`. */
     buttonIcon?: string;
-    onRemoveItem?: () => void;
 }
 
+/**
+ * A button that removes its own row from the enclosing form array, down to `minItems`.
+ *
+ * @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> {
     static key: string;
     internalArrayService: NgsFormsFormArrayInternalService;
     private elementRef;
     private indexFromDi;
+    /** Index of the row this button belongs to. */
     get myIndex(): number;
     constructor();
+    /** Creates a `form-array-remove-item` item. */
     static create(config: NgsFormItemArrayRemoveItemConfig): NgsFormsFormItem<NgsFormItemArrayRemoveItemConfig>;
     removeItem(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsFormArrayRemoveItemComponent, never>;
@@ -374,24 +843,43 @@ interface NgsFormsTextDivConfig extends NgsFormsFormItemConfigBase {
     classes?: string;
 }
 
+/**
+ * Renders a line of static text, such as a heading or a hint, inside the form.
+ *
+ * @remarks Registry key: `text-div`. Config: `text` and optional `classes`.
+ */
 declare class NgsFormsTextDivComponent extends NgsFormsBaseClassFormComponent<NgsFormsTextDivConfig> {
     static key: string;
+    /** Creates a `text-div` item. */
     static create(config: NgsFormsTextDivConfig): NgsFormsFormItem<NgsFormsTextDivConfig>;
+    /**
+     * Shortcut for a heading: creates a `text-div` with `text` and the given class (default `h2`).
+     */
     static title(title: string, divClass?: string): NgsFormsFormItem<NgsFormsTextDivConfig>;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsTextDivComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NgsFormsTextDivComponent, "ngs-form-component-text-div", never, {}, {}, never, never, true, never>;
 }
 
+/** Configuration for `NgsFormsHtmlContentComponent`. */
 interface NgsFormItemHtmlContentConfig extends NgsFormsFormItemConfigBase {
+    /** The HTML to render. */
     html: string;
+    /** Reserved. The HTML is always sanitized. */
     sanitize: boolean;
 }
 
+/**
+ * Renders an HTML string inside the form. The HTML is passed through Angular's sanitizer.
+ *
+ * @remarks Registry key: `content-html`. Registered by `registerCoreNgsFormComponents()`, which the theme packages'
+ * `registerAll…` helpers call for you.
+ */
 declare class NgsFormsHtmlContentComponent extends NgsFormsBaseClassFormComponent<NgsFormItemHtmlContentConfig> {
     static key: string;
     contentConfig: NgsFormItemHtmlContentConfig;
     html: string;
     constructor();
+    /** Creates a `content-html` item. */
     static create(config: NgsFormItemHtmlContentConfig): NgsFormsFormItem<NgsFormItemHtmlContentConfig>;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsHtmlContentComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NgsFormsHtmlContentComponent, "ngs-form-component-html-content", never, {}, {}, never, never, true, never>;
@@ -404,18 +892,33 @@ interface NgsFormsFormSectionConfig extends NgsFormsFormItemContainerConfigBase
     subtitleClass?: string;
 }
 
+/**
+ * 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`.
+ */
 declare class NgsFormsFormSectionComponent extends NgsFormsBaseClassItemsContainerBase<NgsFormsFormSectionConfig> implements OnInit {
     static key: string;
+    /** Creates a `section` item. */
     static create(config: NgsFormsFormSectionConfig): NgsFormsFormItem<NgsFormsFormSectionConfig>;
     ngOnInit(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsFormSectionComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NgsFormsFormSectionComponent, "ngs-forms-form-section", never, {}, {}, never, never, true, never>;
 }
 
+/** Registration helpers for the structural components in `@ng-simplicity/forms-core`. */
 declare class NgsFormsCoreModule {
+    /**
+     * Registers the structural components: `form-group`, `form-row`, `column`, `form-array`, `form-array-list`,
+     * `form-array-add-item`, `form-array-remove-item`, `text-div`, `content-html` and `section`.
+     *
+     * @remarks The theme packages call this for you from their own `registerAll…` helpers.
+     */
     static registerCoreNgsFormComponents(registryService: NgsFormsComponentRegistryService): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgsFormsCoreModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<NgsFormsCoreModule, never, [typeof i1.CommonModule, typeof i2.FormsModule, typeof i2.ReactiveFormsModule], never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<NgsFormsCoreModule, never, [typeof i1.CommonModule, typeof _angular_forms.FormsModule, typeof _angular_forms.ReactiveFormsModule], never>;
     static ɵinj: i0.ɵɵInjectorDeclaration<NgsFormsCoreModule>;
 }