@ng-simplicity/forms-core 1.1.0 → 1.1.2

package/README.md

@@ -1,11 +1,21 @@
 # @ng-simplicity/forms-core
 
+[![Documentation](https://img.shields.io/badge/Docs-ng--simplicity--forms.bryangwalsh.com-4f46e5.svg)](https://ng-simplicity-forms.bryangwalsh.com)
+
+📖 **Documentation, tutorials and live demos:** [ng-simplicity-forms.bryangwalsh.com](https://ng-simplicity-forms.bryangwalsh.com) · [Core concepts](https://ng-simplicity-forms.bryangwalsh.com/guides/core-concepts) · [API reference](https://ng-simplicity-forms.bryangwalsh.com/api)
+
 The core engine package for **NG-Simplicity Forms**. This package manages form states, dynamic registry injection, component lifecycle bindings, and structural layout directives (Rows, Columns, Sections, Groups, Arrays). It enables you to construct highly dynamic, complex forms where control properties (such as visibility, enabled/disabled state, select options, and validation rules) reactively adapt in real-time based on the current values inside the form. The engine is highly customizable, allowing you to develop and add your own custom form controls to the registry to be used in the form rendering.
 
 This core package is extended by styling integration packages that provide prebuilt themed form components:
 - **[@ng-simplicity/forms-bootstrap](../forms-bootstrap/README.md)**: Dynamic forms pre-styled with Bootstrap form fields and layouts.
 - **[@ng-simplicity/forms-material](../forms-material/README.md)**: Dynamic forms pre-styled with Angular Material inputs and controls.
 
+## Compatibility
+
+| Package | Package version | Angular support |
+|---|---:|---|
+| `@ng-simplicity/forms-core` | `1.1.2` | `17.x`–`22.x` |
+
 ---
 
 ## Installation

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

@@ -1,14 +1,16 @@
 import { Subject, takeUntil, BehaviorSubject, map, filter, merge, of } from 'rxjs';
 import * as i0 from '@angular/core';
-import { Directive, InjectionToken, inject, Injectable, ChangeDetectorRef, Injector, ViewContainerRef, Input, ChangeDetectionStrategy, Component, ElementRef, Sanitizer, SecurityContext, NgModule } from '@angular/core';
+import { Directive, InjectionToken, inject, Injectable, ChangeDetectorRef, Injector, ViewContainerRef, Input, computed, ChangeDetectionStrategy, Component, ElementRef, Sanitizer, SecurityContext, NgModule } from '@angular/core';
 import { v4 } from 'uuid';
 import { toSignal } from '@angular/core/rxjs-interop';
 import { UntypedFormGroup, FormControl, UntypedFormArray, FormsModule, ReactiveFormsModule } from '@angular/forms';
 import { CommonModule } from '@angular/common';
 
+/** Base class that ties RxJS subscriptions to the component's lifetime. */
 class NgsSubscriber {
     destroy$ = new Subject();
     subscriptions = [];
+    /** Subscribes to `subscribeTo` until the component is destroyed. */
     subscribe(subscribeTo, nextObserver) {
         subscribeTo.pipe(takeUntil(this.destroy$)).subscribe(nextObserver);
     }
@@ -24,9 +26,17 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             type: Directive
         }] });
 
+/** Injection token for the `NgsFormsFormItem` a component is rendering. */
 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. */
 const NGS_FORMS_ITEM_INDEX = new InjectionToken('ngs-forms-item-index');
+/**
+ * @internal
+ */
 const NgsFormsFormControlAddRemoveFunctions = {
     formGroup: (formGroup) => ({
         add: (control, controlName) => formGroup.addControl(controlName, control),
@@ -55,10 +65,20 @@ function ngsDefaults(target, ...sources) {
     return result;
 }
 
+/**
+ * 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.
+ */
 class NgsFormsBaseClassFormComponent extends NgsSubscriber {
+    /** Registry key the component is registered under. */
     static key;
+    /** Unique id for this component instance, handy for `id` and `for` attributes. */
     id = v4();
+    /** The item's configuration. */
     config;
+    /** The full form item: `uuid`, `type` and `config`. */
     itemData;
     constructor() {
         super();
@@ -73,11 +93,28 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{}]
         }], ctorParameters: () => [] });
 
+/**
+ * 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);
+ * }
+ * ```
+ */
 class NgsFormsComponentRegistryService {
     itemComponentRegistry = {};
+    /** Returns the component registered for `key`, or `undefined` when nothing is registered. */
     getComponentTypeForKey(key) {
         return this.itemComponentRegistry[key];
     }
+    /** Registers `component` under `key`, replacing any component already registered for it. */
     register(key, component) {
         this.itemComponentRegistry[key] = component;
     }
@@ -89,24 +126,59 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{ providedIn: 'platform' }]
         }] });
 
+/**
+ * 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$);
+ * }
+ * ```
+ */
 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.
+     *
+     * @remarks The value is keyed by the root group's `name`, for example `{ profile: { firstName: 'Ada' } }`.
+     */
     formValue$ = new BehaviorSubject({});
+    /** The latest value emitted by `formValue$`. */
     formValue = {};
     internalFormService;
     formGroupSubscriptions = [];
     formGroup = new UntypedFormGroup({});
+    /** `true` once the user has changed any control in the form. */
     get dirty() {
         return this.formGroup?.dirty ?? false;
     }
+    /** `true` when every rendered control passes its validators. Hidden items are not validated. */
     get isValid() {
         if (!this.internalServiceIsSet)
             return false;
         return this.internalFormService.checkIsValid();
     }
+    /** `true` once `<ngs-form>` has connected to this service. */
     get internalServiceIsSet() {
         return !!this.internalFormService;
     }
+    /**
+     * 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) {
         if (!this.internalServiceIsSet) {
             if (this.attempt > 20) {
@@ -119,10 +191,17 @@ class NgsFormsService {
         }
         this.internalFormService.setFormData(formConfig);
     }
+    /**
+     * @internal
+     */
     setInternalService(internalFormsService) {
         this.internalFormService = internalFormsService;
         this.bindFormGroup();
     }
+    /**
+     * 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) {
         if (!this.internalServiceIsSet)
             return;
@@ -138,15 +217,26 @@ class NgsFormsService {
             }));
         });
     }
+    /**
+     * Merges `state` into the state of one component, identified by its `uuid` or control `name`.
+     * Components read the merged result through `commonState`.
+     */
     updateComponentState(componentKey, state) {
         this.internalFormService?.updateComponentState(componentKey, state);
     }
+    /** Merges `state` into the state shared by every component in the form. */
     updateGlobalState(state) {
         this.internalFormService?.updateGlobalState(state);
     }
     ngOnDestroy() {
         this.formGroupSubscriptions.forEach((subscription) => subscription.unsubscribe());
     }
+    /**
+     * 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) {
         this.formGroup.patchValue(entityData);
     }
@@ -157,6 +247,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             type: Injectable
         }] });
 
+/**
+ * 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.
+ */
 class NgsFormsInternalService {
     formGroup$ = new BehaviorSubject(new UntypedFormGroup({}));
     formConfig$ = new BehaviorSubject(undefined);
@@ -208,12 +304,22 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             type: Injectable
         }] });
 
+/**
+ * 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.
+ */
 class NgsFormsFormItemWithVisibleAndValidatorsBase extends NgsFormsBaseClassFormComponent {
+    /** The item's form control. Bind it with `[formControl]`. */
     control;
+    /**
+     * 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 = '';
     formAddRemoveFns = inject(NGS_FORMS_CONTROL_ADD_REMOVE_FN);
     privateService = inject(NgsFormsInternalService);
     changeDetectorRef = inject(ChangeDetectorRef);
+    /** Whether the form has been marked as submitted with `NgsFormsService.setIsSubmitted()`. */
     submitted = toSignal(this.privateService.isSubmitted$, { initialValue: false });
     ngOnInit() {
         if (!this.control) {
@@ -271,10 +377,22 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{}]
         }] });
 
+/**
+ * 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.
+ */
 class NgsFormsBaseClassFormInputComponent extends NgsFormsFormItemWithVisibleAndValidatorsBase {
+    /** The `NgsFormsService` of the form this input belongs to. */
     myFormService = inject(NgsFormsService);
     internalService = inject(NgsFormsInternalService);
+    /** Merged state for this component: its own state, then state by name, then global state. */
     commonState = toSignal(this.internalService.subscribeToState(this.itemData.uuid || '', this.config.name), { initialValue: {} });
+    /**
+     * Switches between input and summary display.
+     *
+     * @notImplemented
+     */
     toggleDisplayMode(setTo) {
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsBaseClassFormInputComponent, deps: null, target: i0.ɵɵFactoryTarget.Directive });
@@ -285,6 +403,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{}]
         }] });
 
+/** Base class for container items that render `config.items` without owning a form control. */
 class NgsFormsBaseClassItemsContainerBase extends NgsFormsBaseClassFormComponent {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsBaseClassItemsContainerBase, deps: null, target: i0.ɵɵFactoryTarget.Directive });
     static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "20.3.19", type: NgsFormsBaseClassItemsContainerBase, isStandalone: true, usesInheritance: true, ngImport: i0 });
@@ -294,7 +413,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{}]
         }] });
 
+/**
+ * Base class for inputs with options. Exposes `options` as a signal that follows `options$` when given and falls
+ * back to the static `options`.
+ */
 class NgsFormsBaseClassFormItemInputWithOptionsComponent extends NgsFormsBaseClassFormInputComponent {
+    /** The current options. */
     options = toSignal(this.config.options$ ?? of(this.config.options ?? []), { initialValue: this.config.options ?? [] });
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsBaseClassFormItemInputWithOptionsComponent, deps: null, target: i0.ɵɵFactoryTarget.Directive });
     static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "20.3.19", type: NgsFormsBaseClassFormItemInputWithOptionsComponent, isStandalone: true, usesInheritance: true, ngImport: i0 });
@@ -372,10 +496,22 @@ class NgsFormItemController extends NgsSubscriber {
     }
 }
 
+/**
+ * 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>`.
+ */
 class NgsFormsFormItemDirective {
+    /** The item to render. */
     itemData = undefined;
+    /** Form group that the item's control is added to. */
     formGroup;
+    /** 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;
     controller;
     viewContainerRef = inject(ViewContainerRef);
@@ -421,24 +557,45 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
                 args: ['ngs-form-index']
             }] } });
 
+/**
+ * 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>
+ * ```
+ */
 class NgsFormComponent {
     ngsInternalFormsService = inject(NgsFormsInternalService);
     ngsFormsService = inject(NgsFormsService);
     formGroup = toSignal(this.ngsInternalFormsService.formGroup$);
     formConfig = toSignal(this.ngsInternalFormsService.formConfig$);
+    /** The root item to render with the form group it belongs to (empty until a config is set). */
+    rendered = computed(() => {
+        const group = this.formGroup();
+        const root = this.formConfig()?.root;
+        return group && root ? [{ group, root }] : [];
+    }, ...(ngDevMode ? [{ debugName: "rendered" }] : []));
     constructor() {
         this.ngsFormsService.setInternalService(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: "@if (formConfig()?.root && formGroup()) {\n  <ng-container [ngs-form-group]=\"formGroup()!\" [ngs-form-item]=\"formConfig()!.root\"></ng-container>\n}\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 });
+    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 });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormComponent, decorators: [{
             type: Component,
-            args: [{ selector: 'ngs-form', providers: [NgsFormsInternalService], imports: [NgsFormsFormItemDirective], changeDetection: ChangeDetectionStrategy.OnPush, template: "@if (formConfig()?.root && formGroup()) {\n  <ng-container [ngs-form-group]=\"formGroup()!\" [ngs-form-item]=\"formConfig()!.root\"></ng-container>\n}\n\n" }]
+            args: [{ selector: 'ngs-form', providers: [NgsFormsInternalService], imports: [NgsFormsFormItemDirective], changeDetection: ChangeDetectionStrategy.OnPush, 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" }]
         }], ctorParameters: () => [] });
 
+/**
+ * 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.
+ */
 class NgsFormsColumnComponent extends NgsFormsBaseClassItemsContainerBase {
     static key = 'column';
+    /** Creates a `column` item. */
     static create(config) {
         return {
             uuid: config.uuid || v4(),
@@ -454,8 +611,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{ selector: 'ngs-form-component-column', imports: [NgsFormsFormItemDirective], changeDetection: ChangeDetectionStrategy.OnPush, template: "@for (item of config.items; track item.uuid) {\n  <ng-container [ngs-form-item]=\"item\"></ng-container>\n}\n" }]
         }] });
 
-// --
-
+/**
+ * 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],
+ * })
+ * ```
+ */
 class NgsFormsRowComponent extends NgsFormsBaseClassFormComponent {
     static key = 'form-row';
     constructor() {
@@ -470,6 +639,7 @@ class NgsFormsRowComponent extends NgsFormsBaseClassFormComponent {
         }
         return this.config.columnClasses[index];
     }
+    /** Creates a `form-row` item. */
     static create(config) {
         return {
             uuid: config.uuid || v4(),
@@ -485,8 +655,22 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{ selector: 'ngs-forms-row-component', imports: [NgsFormsFormItemDirective], changeDetection: ChangeDetectionStrategy.OnPush, template: "<div class=\"{{config.containerClass}}\">\n  @for(item of config.items; track item; let i = $index){\n    <div class=\"{{getIndividualRowDivClass(i)}}\">\n      <ng-container [ngs-form-item]=\"item\"></ng-container>\n    </div>\n  }\n</div>\n" }]
         }], ctorParameters: () => [] });
 
+/**
+ * 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],
+ * })
+ * ```
+ */
 class NgsFormsFormGroupComponent extends NgsFormsFormItemWithVisibleAndValidatorsBase {
     static key = 'form-group';
+    /** Creates a `form-group` item. */
     static create(config) {
         return {
             uuid: config.uuid || v4(),
@@ -509,9 +693,15 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{ selector: 'ngs-forms-form-group', imports: [NgsFormsFormItemDirective], changeDetection: ChangeDetectionStrategy.OnPush, template: "@if (config.items) {\n  @for (item of config.items; track item.uuid) {\n    <ng-container [ngs-form-item]=\"item\" [ngs-form-group]=\"formGroupControl\"></ng-container>\n  }\n}\n" }]
         }], ctorParameters: () => [] });
 
+/**
+ * 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.
+ */
 class NgsFormsFormArrayInternalService {
     config = inject(NGS_FORMS_ITEM_DATA).config;
     formArray = new UntypedFormArray([]);
+    /** Emits after a row is added or removed. */
     itemsChanged = new Subject();
     constructor() {
         if (this.config.initialItemCount) {
@@ -522,6 +712,7 @@ class NgsFormsFormArrayInternalService {
     }
     ngOnDestroy() {
     }
+    /** 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;
@@ -532,6 +723,7 @@ class NgsFormsFormArrayInternalService {
         this.formArray.removeAt(index);
         this.itemsChanged.next();
     }
+    /** Appends an empty row, unless the array already has `maxItems` rows. */
     addItem() {
         if (this.config?.maxItems && this.formArray.controls.length >= this.config.maxItems) {
             return;
@@ -546,9 +738,15 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             type: Injectable
         }], ctorParameters: () => [] });
 
+/**
+ * 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`.
+ */
 class NgsFormsFormArrayAddItemComponent extends NgsFormsBaseClassFormComponent {
     static key = 'form-array-add-item';
     internalArrayService = inject(NgsFormsFormArrayInternalService);
+    /** Creates a `form-array-add-item` item. */
     static create(config) {
         return {
             uuid: config.uuid || v4(),
@@ -567,6 +765,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{ selector: 'ngs-forms-form-array-add-item', changeDetection: ChangeDetectionStrategy.OnPush, template: "<button\n  (click)=\"addItem()\"\n  [class]=\"config.buttonClass || 'btn btn-outline-primary'\"\n  type=\"button\">\n  @if (config.buttonIcon) {\n    <i [class]=\"config.buttonIcon\" aria-hidden=\"true\"></i>\n  }\n  {{ config.buttonText || 'Add Item' }}\n</button>\n" }]
         }] });
 
+/**
+ * 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.
+ */
 class NgsFormsFormArrayContainerComponent extends NgsFormsFormItemWithVisibleAndValidatorsBase {
     formArrayService;
     static key = 'form-array';
@@ -575,6 +779,7 @@ class NgsFormsFormArrayContainerComponent extends NgsFormsFormItemWithVisibleAnd
         this.formArrayService = formArrayService;
         this.control = this.formArrayService.formArray;
     }
+    /** Creates a `form-array` item. */
     static create(config) {
         return {
             uuid: config.uuid || v4(),
@@ -590,6 +795,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{ selector: 'ngs-forms-form-array', imports: [NgsFormsFormItemDirective], providers: [NgsFormsFormArrayInternalService], changeDetection: ChangeDetectionStrategy.OnPush, template: "<div [class]=\"config.containerClass || ''\">\n  @for (item of config.items; track item.uuid) {\n    <ng-container [ngs-form-item]=\"item\"></ng-container>\n  }\n</div>\n" }]
         }], ctorParameters: () => [{ type: NgsFormsFormArrayInternalService }] });
 
+/**
+ * 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`.
+ */
 class NgsFormsFormArrayListComponent extends NgsFormsBaseClassFormComponent {
     static key = 'form-array-list';
     internalArrayService = inject(NgsFormsFormArrayInternalService);
@@ -600,6 +811,7 @@ class NgsFormsFormArrayListComponent extends NgsFormsBaseClassFormComponent {
             this.changeDetectorRef.markForCheck();
         });
     }
+    /** Creates a `form-array-list` item. */
     static create(config) {
         return {
             uuid: config.uuid || v4(),
@@ -618,11 +830,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             args: [{ selector: 'ngs-forms-form-array-list', imports: [NgsFormsFormItemDirective], changeDetection: ChangeDetectionStrategy.OnPush, template: "@for (formGroup of myFormArray.controls; track formGroup; let i = $index) {\n  <div [attr.data-index]=\"$index\" [class]=\"config.containerClass || ''\">\n    <ng-container [ngs-form-group]=\"castToFormGroup(formGroup)\" [ngs-form-index]=\"i\"\n                  [ngs-form-item]=\"config.templateItem\"></ng-container>\n  </div>\n}\n" }]
         }] });
 
+/**
+ * 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.
+ */
 class NgsFormsFormArrayRemoveItemComponent extends NgsFormsBaseClassFormComponent {
     static key = 'form-array-remove-item';
     internalArrayService = inject(NgsFormsFormArrayInternalService);
     elementRef = inject(ElementRef);
     indexFromDi = inject(NGS_FORMS_ITEM_INDEX, { optional: true });
+    /** Index of the row this button belongs to. */
     get myIndex() {
         if (this.indexFromDi !== null && this.indexFromDi !== undefined) {
             return this.indexFromDi;
@@ -640,6 +859,7 @@ class NgsFormsFormArrayRemoveItemComponent extends NgsFormsBaseClassFormComponen
     constructor() {
         super();
     }
+    /** Creates a `form-array-remove-item` item. */
     static create(config) {
         return {
             uuid: config.uuid || v4(),
@@ -651,15 +871,21 @@ 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  index:{{ myIndex }}\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  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  index:{{ myIndex }}\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  type=\"button\">\n  @if (config.buttonIcon) {\n    <i [class]=\"config.buttonIcon\" aria-hidden=\"true\"></i>\n  }\n  {{ config.buttonText || 'Remove' }}\n</button>\n" }]
         }], ctorParameters: () => [] });
 
+/**
+ * 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`.
+ */
 class NgsFormsTextDivComponent extends NgsFormsBaseClassFormComponent {
     static key = 'text-div';
+    /** Creates a `text-div` item. */
     static create(config) {
         return {
             uuid: config.uuid || v4(),
@@ -667,6 +893,9 @@ class NgsFormsTextDivComponent extends NgsFormsBaseClassFormComponent {
             config: config,
         };
     }
+    /**
+     * Shortcut for a heading: creates a `text-div` with `text` and the given class (default `h2`).
+     */
     static title(title, divClass = 'h2') {
         return NgsFormsTextDivComponent.create({
             text: title,
@@ -674,13 +903,19 @@ class NgsFormsTextDivComponent extends NgsFormsBaseClassFormComponent {
         });
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsTextDivComponent, deps: null, target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "20.3.19", type: NgsFormsTextDivComponent, isStandalone: true, selector: "ngs-form-component-text-div", usesInheritance: true, ngImport: i0, template: "<div class=\"{{config.classes\">{{ config.text }}</div>\n", changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "20.3.19", type: NgsFormsTextDivComponent, isStandalone: true, selector: "ngs-form-component-text-div", usesInheritance: true, ngImport: i0, template: "<div class=\"{{ config.classes }}\">{{ config.text }}</div>\n", changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsTextDivComponent, decorators: [{
             type: Component,
-            args: [{ selector: 'ngs-form-component-text-div', imports: [], changeDetection: ChangeDetectionStrategy.OnPush, template: "<div class=\"{{config.classes\">{{ config.text }}</div>\n" }]
+            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.
+ *
+ * @remarks Registry key: `content-html`. Registered by `registerCoreNgsFormComponents()`, which the theme packages'
+ * `registerAll…` helpers call for you.
+ */
 class NgsFormsHtmlContentComponent extends NgsFormsBaseClassFormComponent {
     static key = 'content-html';
     contentConfig = this.config;
@@ -692,6 +927,7 @@ class NgsFormsHtmlContentComponent extends NgsFormsBaseClassFormComponent {
             sanitizer.sanitize(SecurityContext.HTML, this.contentConfig.html) ||
                 '';
     }
+    /** Creates a `content-html` item. */
     static create(config) {
         return {
             uuid: config.uuid || v4(),
@@ -712,8 +948,16 @@ const sectionConfigDefaults = {
     subtitleClass: 'lead',
 };
 
+/**
+ * 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`.
+ */
 class NgsFormsFormSectionComponent extends NgsFormsBaseClassItemsContainerBase {
     static key = 'section';
+    /** Creates a `section` item. */
     static create(config) {
         return {
             uuid: config.uuid || v4(),
@@ -732,7 +976,16 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.19", ngImpo
             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" }]
         }] });
 
+// --
+
+/** Registration helpers for the structural components in `@ng-simplicity/forms-core`. */
 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) {
         registryService.register(NgsFormsFormGroupComponent.key, NgsFormsFormGroupComponent);
         registryService.register(NgsFormsRowComponent.key, NgsFormsRowComponent);
@@ -742,7 +995,7 @@ class NgsFormsCoreModule {
         registryService.register(NgsFormsFormArrayRemoveItemComponent.key, NgsFormsFormArrayRemoveItemComponent);
         registryService.register(NgsFormsFormArrayListComponent.key, NgsFormsFormArrayListComponent);
         registryService.register(NgsFormsTextDivComponent.key, NgsFormsTextDivComponent);
-        //registryService.register('content-html', NgsFormsHtmlContentComponent);
+        registryService.register(NgsFormsHtmlContentComponent.key, NgsFormsHtmlContentComponent);
         registryService.register(NgsFormsFormSectionComponent.key, NgsFormsFormSectionComponent);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsCoreModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });