@ng-simplicity/forms-core 1.1.1 → 1.1.3

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 { UntypedFormGroup, FormControl, FormGroup, FormArray, 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,15 +65,29 @@ 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;
-    id = v4();
+    /**
+     * 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;
+    /** The item's configuration. */
     config;
+    /** The full form item: `uuid`, `type` and `config`. */
     itemData;
     constructor() {
         super();
         this.itemData = inject(NGS_FORMS_ITEM_DATA);
         this.config = this.itemData.config;
+        this.id = this.config.id || v4();
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsBaseClassFormComponent, deps: [], target: i0.ɵɵFactoryTarget.Directive });
     static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "20.3.19", type: NgsFormsBaseClassFormComponent, isStandalone: true, usesInheritance: true, ngImport: i0 });
@@ -73,11 +97,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 +130,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 +195,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 +221,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 +251,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);
@@ -171,6 +271,9 @@ class NgsFormsInternalService {
         return this.formGroup$.value.valid;
     }
     setFormData(formConfig) {
+        const state = { ...(formConfig.initialState ?? {}) };
+        state['global'] = { ...(formConfig.globalState ?? {}) };
+        this.state.next(state);
         this.formGroup$.next(new UntypedFormGroup({}));
         this.formConfig$.next(formConfig);
         this.isSubmitted$.next(false);
@@ -181,13 +284,24 @@ class NgsFormsInternalService {
         this.state.value[key] = updated;
         this.state.next(this.state.value);
     }
+    /** Sets a component's state from its config's `initialState`, unless state for `uuid` already exists. */
+    seedComponentState(uuid, initialState) {
+        if (!uuid || !initialState || this.state.value[uuid])
+            return;
+        this.mergeState(uuid, initialState);
+    }
     updateGlobalState(state) {
         this.mergeState('global', state);
     }
     updateComponentState(componentKey, state) {
         this.mergeState(componentKey, state);
     }
-    subscribeToState(uuid, name) {
+    /**
+     * 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, name, initialState) {
+        this.seedComponentState(uuid, initialState);
         let last = '';
         return this.state.pipe(map((allState) => {
             const stateByUuid = allState[uuid] || {};
@@ -208,21 +322,34 @@ 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 (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.
+ */
 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 });
+    /** The latest value of `disabled` / `disabled$`, or `undefined` when the config sets neither. */
+    disabledFromConfig;
     ngOnInit() {
         if (!this.control) {
-            this.control = new FormControl(undefined, { validators: [] });
+            const initialValue = this.config.value;
+            this.control = new FormControl(initialValue, { validators: [] });
         }
-        //this.bindVisible();
         this.bindValidators();
-        //this.bindControlValidityChange();
         this.formAddRemoveFns.add(this.control, this.config.name);
+        this.bindDisabled();
         // Listen to changes and update error message dynamically
         this.subscribe(merge(this.control.valueChanges, this.control.statusChanges, this.privateService.isSubmitted$), () => {
             this.updateErrorMessage();
@@ -263,6 +390,34 @@ class NgsFormsFormItemWithVisibleAndValidatorsBase extends NgsFormsBaseClassForm
             this.subscribe(this.config.validators$, (validators) => this.control.setValidators(validators));
         }
     }
+    bindDisabled() {
+        const disabled$ = this.config.disabled$ ?? (this.config.disabled !== undefined ? of(this.config.disabled) : undefined);
+        if (!disabled$)
+            return;
+        const control = this.control;
+        this.subscribe(disabled$, (disabled) => {
+            this.disabledFromConfig = !!disabled;
+            this.applyDisabled(control);
+        });
+        // Child controls are added to groups and arrays after the container has been disabled, and adding an enabled
+        // child re-enables its parent. Re-apply the configured state whenever a container's status changes.
+        if (control instanceof FormGroup || control instanceof FormArray) {
+            this.subscribe(control.statusChanges, () => {
+                if (this.disabledFromConfig && control.enabled) {
+                    control.disable();
+                }
+            });
+        }
+    }
+    applyDisabled(control) {
+        if (this.disabledFromConfig && !control.disabled) {
+            control.disable();
+        }
+        else if (!this.disabledFromConfig && control.disabled) {
+            control.enable();
+        }
+        this.changeDetectorRef.markForCheck();
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsFormItemWithVisibleAndValidatorsBase, deps: null, target: i0.ɵɵFactoryTarget.Directive });
     static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "20.3.19", type: NgsFormsFormItemWithVisibleAndValidatorsBase, isStandalone: true, usesInheritance: true, ngImport: i0 });
 }
@@ -271,11 +426,25 @@ 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);
-    commonState = toSignal(this.internalService.subscribeToState(this.itemData.uuid || '', this.config.name), { initialValue: {} });
+    /** 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, this.config.initialState), { initialValue: {} });
+    /**
+     * Switches this component between `input` and `summary` display by updating its own state.
+     * With no argument it flips the current mode.
+     */
     toggleDisplayMode(setTo) {
+        const current = this.commonState().displayMode ?? 'input';
+        const displayMode = setTo ?? (current === 'summary' ? 'input' : 'summary');
+        this.internalService.updateComponentState(this.itemData.uuid || this.config.name, { displayMode });
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.19", ngImport: i0, type: NgsFormsBaseClassFormInputComponent, deps: null, target: i0.ɵɵFactoryTarget.Directive });
     static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "20.3.19", type: NgsFormsBaseClassFormInputComponent, isStandalone: true, usesInheritance: true, ngImport: i0 });
@@ -285,6 +454,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 +464,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 });
@@ -328,11 +503,13 @@ class NgsFormItemController extends NgsSubscriber {
         super.ngOnDestroy();
     }
     bindVisibility() {
-        if (!this.itemData.config.visible$) {
+        const config = this.itemData.config;
+        const visible$ = config.visible$ ?? (config.visible !== undefined ? of(config.visible) : undefined);
+        if (!visible$) {
             Promise.resolve().then(() => this.create());
             return;
         }
-        this.subscribe(this.itemData.config.visible$, (visible) => {
+        this.subscribe(visible$, (visible) => {
             if (this.lastVisible === visible)
                 return;
             this.lastVisible = visible;
@@ -372,10 +549,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 +610,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 +664,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 +692,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 +708,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 +746,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 +765,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 +776,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 +791,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 +818,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 +832,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 +848,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 +864,7 @@ class NgsFormsFormArrayListComponent extends NgsFormsBaseClassFormComponent {
             this.changeDetectorRef.markForCheck();
         });
     }
+    /** Creates a `form-array-list` item. */
     static create(config) {
         return {
             uuid: config.uuid || v4(),
@@ -618,11 +883,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 +912,7 @@ class NgsFormsFormArrayRemoveItemComponent extends NgsFormsBaseClassFormComponen
     constructor() {
         super();
     }
+    /** Creates a `form-array-remove-item` item. */
     static create(config) {
         return {
             uuid: config.uuid || v4(),
@@ -651,15 +924,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 +946,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 +956,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 +980,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 +1001,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 +1029,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 +1048,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 });