iss-ctrl 0.0.11 → 0.0.13

package/fesm2022/{iss-ctrl-iss-ctrl-hz0ibyPg.mjs → iss-ctrl-iss-ctrl-BN9rcLt2.mjs}

@@ -49,19 +49,102 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
             args: [{ name: "selectStatus" }]
         }] });
 
+/**
+ * Base class for every `iss-ctrl-*` control.
+ *
+ * Controls are the presentational layer: they know nothing about {@link IssField} and are
+ * driven purely by bindings, so they can be used standalone inside any reactive form.
+ * Every control below inherits the properties declared here and adds its own on top.
+ *
+ * ### Inherited inputs
+ * | Property | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `formControlName` | `string` | `""` | Name of the control in the surrounding `FormGroup`. |
+ * | `placeholder` | `string` | `""` | Placeholder text shown while the field is empty. |
+ * | `readonly` | `boolean` | `false` | Renders the value but blocks every interaction. |
+ * | `multiple` | `boolean \| undefined` | `false` | Allows more than one value, where the control supports it. |
+ * | `min` | `number \| string \| null` | `null` | Lower bound (number or date/time string). |
+ * | `max` | `number \| string \| null` | `null` | Upper bound (number or date/time string). |
+ * | `minLength` | `number \| null` | `null` | Minimum number of characters. |
+ * | `maxLength` | `number \| null` | `null` | Maximum number of characters. |
+ * | `hints` | `Hint[]` | `[]` | Helper messages rendered under the field. |
+ * | `className` | `string \| null` | `null` | Extra CSS classes for the host. |
+ *
+ * ### Inherited outputs
+ * | Event | Payload | Description |
+ * | --- | --- | --- |
+ * | `(onChange)` | `any` | Fires after every committed value change. |
+ *
+ * ### Not inputs
+ * `disabled` and `touched` are signals owned by the control. Disable a control through the
+ * forms API (`ctrl.disable()` or a `disabled` field config), never with a template binding.
+ *
+ * ### Content projection
+ * Controls that render a `mat-form-field` project `<label>` into the floating label.
+ * An omitted label — or one that interpolates to an empty string — leaves `<mat-label>`
+ * empty, and `upgrade.scss` collapses the floating-label space for it. No label markup is
+ * removed at runtime, so a label that arrives later simply shows up.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-input formControlName="email" [readonly]="false" (onChange)="save($event)">
+ *   <label>Email</label>
+ * </iss-ctrl-input>
+ * ```
+ */
 class ControlBase {
+    /**
+     * Name of this control inside the surrounding `FormGroup`.
+     */
     formControlName = input("", ...(ngDevMode ? [{ debugName: "formControlName" }] : /* istanbul ignore next */ []));
+    /**
+     * Lower bound forwarded to the underlying input — a number, or a date/time string.
+     */
     min = input(null, ...(ngDevMode ? [{ debugName: "min" }] : /* istanbul ignore next */ []));
+    /**
+     * Upper bound forwarded to the underlying input — a number, or a date/time string.
+     */
     max = input(null, ...(ngDevMode ? [{ debugName: "max" }] : /* istanbul ignore next */ []));
+    /**
+     * Minimum number of characters accepted by the underlying input.
+     */
     minLength = input(null, ...(ngDevMode ? [{ debugName: "minLength" }] : /* istanbul ignore next */ []));
+    /**
+     * Maximum number of characters accepted by the underlying input.
+     */
     maxLength = input(null, ...(ngDevMode ? [{ debugName: "maxLength" }] : /* istanbul ignore next */ []));
+    /**
+     * Disabled state. **Not an input** — it is set by the forms API through
+     * {@link ControlBase.setDisabledState}. Disable via `ctrl.disable()` or the field config.
+     */
     disabled = signal(false, ...(ngDevMode ? [{ debugName: "disabled" }] : /* istanbul ignore next */ []));
+    /**
+     * Renders the current value but blocks every user interaction.
+     */
     readonly = input(false, ...(ngDevMode ? [{ debugName: "readonly" }] : /* istanbul ignore next */ []));
+    /**
+     * Allows selecting/entering more than one value, on controls that support it.
+     */
     multiple = input(false, ...(ngDevMode ? [{ debugName: "multiple" }] : /* istanbul ignore next */ []));
+    /**
+     * Placeholder text shown while the control has no value.
+     */
     placeholder = input("", ...(ngDevMode ? [{ debugName: "placeholder" }] : /* istanbul ignore next */ []));
+    /**
+     * Helper messages rendered beneath the field. See {@link Hint}.
+     */
     hints = input([], ...(ngDevMode ? [{ debugName: "hints" }] : /* istanbul ignore next */ []));
+    /**
+     * Extra CSS class names applied to the control host.
+     */
     className = input(null, ...(ngDevMode ? [{ debugName: "className" }] : /* istanbul ignore next */ []));
+    /**
+     * Whether the user has interacted with the control. Owned by the control, not an input.
+     */
     touched = signal(false, ...(ngDevMode ? [{ debugName: "touched" }] : /* istanbul ignore next */ []));
+    /**
+     * Emits the committed value after every change.
+     */
     onChange = output();
     ctrl = new FormControl(null);
     registerOnChange(fn) {
@@ -121,8 +204,35 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
             args: [{ template: `` }]
         }], propDecorators: { formControlName: [{ type: i0.Input, args: [{ isSignal: true, alias: "formControlName", required: false }] }], min: [{ type: i0.Input, args: [{ isSignal: true, alias: "min", required: false }] }], max: [{ type: i0.Input, args: [{ isSignal: true, alias: "max", required: false }] }], minLength: [{ type: i0.Input, args: [{ isSignal: true, alias: "minLength", required: false }] }], maxLength: [{ type: i0.Input, args: [{ isSignal: true, alias: "maxLength", required: false }] }], readonly: [{ type: i0.Input, args: [{ isSignal: true, alias: "readonly", required: false }] }], multiple: [{ type: i0.Input, args: [{ isSignal: true, alias: "multiple", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], hints: [{ type: i0.Input, args: [{ isSignal: true, alias: "hints", required: false }] }], className: [{ type: i0.Input, args: [{ isSignal: true, alias: "className", required: false }] }], onChange: [{ type: i0.Output, args: ["onChange"] }] } });
 
+/**
+ * `<iss-ctrl-checkbox>` — a list of checkboxes over a fixed set of options.
+ *
+ * The form value is the comma separated list of selected option values, while `(onChange)`
+ * emits the resolved `Option[]` (or `null` when nothing is selected).
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-checkbox formControlName="days" [options]="days" (onChange)="pick($event)"/>
+ * ```
+ *
+ * ### Own inputs
+ * | Property | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `options` | `Option[]` | **required** | The selectable choices. |
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)`
+ *
+ * Does not project a label — the field label is rendered by the wrapping `iss-field-*`.
+ */
 class CheckboxControl extends ControlBase {
+    /**
+     * Selectable choices, each a `{ value, label }` pair. Required.
+     */
     options = input.required(...(ngDevMode ? [{ debugName: "options" }] : /* istanbul ignore next */ []));
+    /**
+     * Currently checked options, keyed by value. Internal state, not an input.
+     */
     selectedOptions = signal(new Map(), ...(ngDevMode ? [{ debugName: "selectedOptions" }] : /* istanbul ignore next */ []));
     writeValue(value) {
         this.#reset();
@@ -191,7 +301,7 @@ class CheckboxControl extends ControlBase {
     <ul class="list-unstyled">
       @for (option of options(); track option.value) {
         <li class="mb-2">
-          <mat-checkbox [checked]="option | selectStatus: selectedOptions()" [disabled]="disabled() || readonly()" (change)="onCheckboxChange($event.checked, option.value)">
+          <mat-checkbox [checked]="option | selectStatus: selectedOptions()" [disabled]="disabled() || readonly()" (change)="onCheckboxChange($event.checked, option.value)">
             {{ option.label }}
           </mat-checkbox>
         </li>
@@ -211,7 +321,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
     <ul class="list-unstyled">
       @for (option of options(); track option.value) {
         <li class="mb-2">
-          <mat-checkbox [checked]="option | selectStatus: selectedOptions()" [disabled]="disabled() || readonly()" (change)="onCheckboxChange($event.checked, option.value)">
+          <mat-checkbox [checked]="option | selectStatus: selectedOptions()" [disabled]="disabled() || readonly()" (change)="onCheckboxChange($event.checked, option.value)">
             {{ option.label }}
           </mat-checkbox>
         </li>
@@ -221,7 +331,31 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                 }]
         }], propDecorators: { options: [{ type: i0.Input, args: [{ isSignal: true, alias: "options", required: true }] }] } });
 
+/**
+ * `<iss-ctrl-chips>` — free text entered as removable chips.
+ *
+ * Each `Enter` turns the typed text into a chip. The form value is the comma separated list
+ * of chip labels.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-chips formControlName="tags" placeholder="Add a tag">
+ *   <label>Tags</label>
+ * </iss-ctrl-chips>
+ * ```
+ *
+ * ### Own inputs
+ * None — the control is configured entirely through the inherited properties.
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)` · `placeholder`
+ *
+ * Projects `<label>` into the floating label; omit it to render the control without one.
+ */
 class ChipsControl extends ControlBase {
+    /**
+     * The chips currently rendered. Internal state, not an input.
+     */
     keywords = signal([], ...(ngDevMode ? [{ debugName: "keywords" }] : /* istanbul ignore next */ []));
     writeValue(value) {
         if (typeof value === "string") {
@@ -269,15 +403,14 @@ class ChipsControl extends ControlBase {
             { provide: NG_VALUE_ACCESSOR, useExisting: ChipsControl, multi: true }
         ], usesInheritance: true, ngImport: i0, template: `
     <mat-form-field floatLabel="auto" class="">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <input
         matInput
-        [placeholder]="placeholder()"
-        [matChipInputFor]="chipGrid"
-        [disabled]="disabled()"
-        [readonly]="readonly()"
+        [placeholder]="placeholder()"
+        [matChipInputFor]="chipGrid"
+        [disabled]="disabled()"
+        [readonly]="readonly()"
         (matChipInputTokenEnd)="add($event)"
       />
     </mat-form-field>
@@ -285,7 +418,7 @@ class ChipsControl extends ControlBase {
       @for (keyword of keywords(); track keyword) {
         <mat-chip-row (removed)="remove(keyword)">
           {{ keyword }}
-          <button matChipRemove [disabled]="disabled() || readonly()">
+          <button matChipRemove [disabled]="disabled() || readonly()">
             <ds-icon icon="trash" class="fc-red"></ds-icon>
           </button>
         </mat-chip-row>
@@ -313,15 +446,14 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                     ],
                     template: `
     <mat-form-field floatLabel="auto" class="">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <input
         matInput
-        [placeholder]="placeholder()"
-        [matChipInputFor]="chipGrid"
-        [disabled]="disabled()"
-        [readonly]="readonly()"
+        [placeholder]="placeholder()"
+        [matChipInputFor]="chipGrid"
+        [disabled]="disabled()"
+        [readonly]="readonly()"
         (matChipInputTokenEnd)="add($event)"
       />
     </mat-form-field>
@@ -329,7 +461,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
       @for (keyword of keywords(); track keyword) {
         <mat-chip-row (removed)="remove(keyword)">
           {{ keyword }}
-          <button matChipRemove [disabled]="disabled() || readonly()">
+          <button matChipRemove [disabled]="disabled() || readonly()">
             <ds-icon icon="trash" class="fc-red"></ds-icon>
           </button>
         </mat-chip-row>
@@ -355,9 +487,43 @@ const DATE_FORMAT_ADAPTER = {
 };
 const DATETIME_FORMAT = "dd/MM/yyyy hh:mm a";
 
+/**
+ * `<iss-ctrl-date-picker>` — single date selection through a Material calendar.
+ *
+ * The input itself is read-only; clicking it opens the calendar. The emitted value is a
+ * `yyyy-MM-dd` string, and a clear button appears once a date is picked.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-date-picker formControlName="startsOn" [minDate]="today" [disabledDays]="[5, 6]">
+ *   <label>Start date</label>
+ * </iss-ctrl-date-picker>
+ * ```
+ *
+ * ### Own inputs
+ * | Property | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `minDate` | `Date \| null` | `null` | Earliest selectable date. |
+ * | `maxDate` | `Date \| null` | `null` | Latest selectable date. |
+ * | `disabledDays` | `number[]` | `[]` | Week days to block, `0` = Sunday … `6` = Saturday. |
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)`
+ *
+ * Projects `<label>` into the floating label; omit it to render the control without one.
+ */
 class DatePickerControl extends ControlBase {
+    /**
+     * Week days that cannot be selected — `0` is Sunday through `6` for Saturday.
+     */
     disabledDays = input([], ...(ngDevMode ? [{ debugName: "disabledDays" }] : /* istanbul ignore next */ []));
+    /**
+     * Earliest selectable date.
+     */
     minDate = input(null, ...(ngDevMode ? [{ debugName: "minDate" }] : /* istanbul ignore next */ []));
+    /**
+     * Latest selectable date.
+     */
     maxDate = input(null, ...(ngDevMode ? [{ debugName: "maxDate" }] : /* istanbul ignore next */ []));
     clear(event) {
         if (this.readonly()) {
@@ -397,17 +563,16 @@ class DatePickerControl extends ControlBase {
             { provide: NG_VALIDATORS, useExisting: DatePickerControl, multi: true },
         ], usesInheritance: true, ngImport: i0, template: `
     <mat-form-field floatLabel="auto" class="">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <input
         class="cursor-pointer"
         matInput
         readonly
         [matDatepicker]="picker"
-        (click)="openPicker(picker)"
-        [formControl]="ctrl"
-        [readonly]="readonly()"
+        (click)="openPicker(picker)"
+        [formControl]="ctrl"
+        [readonly]="readonly()"
         [min]="minDate()"
         [max]="maxDate()"
         [matDatepickerFilter]="calendarDaysFilter"
@@ -416,7 +581,7 @@ class DatePickerControl extends ControlBase {
       @if (ctrl.getRawValue()) {
         <mat-icon matSuffix style="cursor: pointer" (click)="clear($event)">close</mat-icon>
       }
-      <mat-datepicker-toggle matIconSuffix [for]="picker" [disabled]="readonly()"></mat-datepicker-toggle>
+      <mat-datepicker-toggle matIconSuffix [for]="picker" [disabled]="readonly()"></mat-datepicker-toggle>
       <mat-datepicker #picker></mat-datepicker>
 
     </mat-form-field>
@@ -432,17 +597,16 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                         { provide: NG_VALIDATORS, useExisting: DatePickerControl, multi: true },
                     ], template: `
     <mat-form-field floatLabel="auto" class="">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <input
         class="cursor-pointer"
         matInput
         readonly
         [matDatepicker]="picker"
-        (click)="openPicker(picker)"
-        [formControl]="ctrl"
-        [readonly]="readonly()"
+        (click)="openPicker(picker)"
+        [formControl]="ctrl"
+        [readonly]="readonly()"
         [min]="minDate()"
         [max]="maxDate()"
         [matDatepickerFilter]="calendarDaysFilter"
@@ -451,18 +615,62 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
       @if (ctrl.getRawValue()) {
         <mat-icon matSuffix style="cursor: pointer" (click)="clear($event)">close</mat-icon>
       }
-      <mat-datepicker-toggle matIconSuffix [for]="picker" [disabled]="readonly()"></mat-datepicker-toggle>
+      <mat-datepicker-toggle matIconSuffix [for]="picker" [disabled]="readonly()"></mat-datepicker-toggle>
       <mat-datepicker #picker></mat-datepicker>
 
     </mat-form-field>
   ` }]
         }], propDecorators: { disabledDays: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabledDays", required: false }] }], minDate: [{ type: i0.Input, args: [{ isSignal: true, alias: "minDate", required: false }] }], maxDate: [{ type: i0.Input, args: [{ isSignal: true, alias: "maxDate", required: false }] }] } });
 
+/**
+ * `<iss-ctrl-date-range-picker>` — a start/end date range in one field.
+ *
+ * A half-filled range is not a value: clearing either endpoint clears the form value and
+ * emits `null`. The form value is a `yyyy-MM-dd` string pair; `(onDateRangeObjectChange)`
+ * emits the same range as a {@link DateRangeEmission} object.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-date-range-picker formControlName="period" (onDateRangeObjectChange)="apply($event)">
+ *   <label>Period</label>
+ * </iss-ctrl-date-range-picker>
+ * ```
+ *
+ * ### Own inputs
+ * | Property | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `minDate` | `Date \| null` | `null` | Earliest selectable date. |
+ * | `maxDate` | `Date \| null` | `null` | Latest selectable date. |
+ * | `disabledDays` | `number[]` | `[]` | Week days to block, `0` = Sunday … `6` = Saturday. |
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)`
+ *
+ * ### Outputs
+ * - `(onDateRangeObjectChange)` — `DateRangeEmission | null`, the range as an object.
+ *
+ * Projects `<label>` into the floating label; omit it to render the control without one.
+ */
 class DateRangePickerControl extends ControlBase {
+    /**
+     * Week days that cannot be selected — `0` is Sunday through `6` for Saturday.
+     */
     disabledDays = input([], ...(ngDevMode ? [{ debugName: "disabledDays" }] : /* istanbul ignore next */ []));
+    /**
+     * Earliest selectable date.
+     */
     minDate = input(null, ...(ngDevMode ? [{ debugName: "minDate" }] : /* istanbul ignore next */ []));
+    /**
+     * Latest selectable date.
+     */
     maxDate = input(null, ...(ngDevMode ? [{ debugName: "maxDate" }] : /* istanbul ignore next */ []));
+    /**
+     * Emits the selected range as an object, or `null` while the range is incomplete.
+     */
     onDateRangeObjectChange = output();
+    /**
+     * The `start`/`end` form group backing the range input. Internal state.
+     */
     range = new FormGroup({
         start: new FormControl(null),
         end: new FormControl(null),
@@ -565,9 +773,8 @@ class DateRangePickerControl extends ControlBase {
         ], usesInheritance: true, ngImport: i0, template: `
     <mat-form-field floatLabel="auto" class="">
 
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <mat-date-range-input
         [formGroup]="range"
         [rangePicker]="picker"
@@ -577,23 +784,23 @@ class DateRangePickerControl extends ControlBase {
       >
         <input
           matStartDate
-          formControlName="start"
-          [readonly]="readonly()"
+          formControlName="start"
+          [readonly]="readonly()"
           placeholder="dd/mm/yyyy"
-          (click)="openPicker(picker)"
+          (click)="openPicker(picker)"
         />
         <input
           matEndDate
-          formControlName="end"
-          [readonly]="readonly()"
+          formControlName="end"
+          [readonly]="readonly()"
           placeholder="dd/mm/yyyy"
-          (click)="openPicker(picker)"
+          (click)="openPicker(picker)"
         />
       </mat-date-range-input>
       @if (range.getRawValue().start || range.getRawValue().end) {
         <mat-icon matSuffix style="cursor: pointer" (click)="clear($event)">close</mat-icon>
       }
-      <mat-datepicker-toggle matSuffix [for]="picker" [disabled]="readonly()"></mat-datepicker-toggle>
+      <mat-datepicker-toggle matSuffix [for]="picker" [disabled]="readonly()"></mat-datepicker-toggle>
       <mat-date-range-picker #picker></mat-date-range-picker>
 
     </mat-form-field>
@@ -617,9 +824,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                     template: `
     <mat-form-field floatLabel="auto" class="">
 
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <mat-date-range-input
         [formGroup]="range"
         [rangePicker]="picker"
@@ -629,23 +835,23 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
       >
         <input
           matStartDate
-          formControlName="start"
-          [readonly]="readonly()"
+          formControlName="start"
+          [readonly]="readonly()"
           placeholder="dd/mm/yyyy"
-          (click)="openPicker(picker)"
+          (click)="openPicker(picker)"
         />
         <input
           matEndDate
-          formControlName="end"
-          [readonly]="readonly()"
+          formControlName="end"
+          [readonly]="readonly()"
           placeholder="dd/mm/yyyy"
-          (click)="openPicker(picker)"
+          (click)="openPicker(picker)"
         />
       </mat-date-range-input>
       @if (range.getRawValue().start || range.getRawValue().end) {
         <mat-icon matSuffix style="cursor: pointer" (click)="clear($event)">close</mat-icon>
       }
-      <mat-datepicker-toggle matSuffix [for]="picker" [disabled]="readonly()"></mat-datepicker-toggle>
+      <mat-datepicker-toggle matSuffix [for]="picker" [disabled]="readonly()"></mat-datepicker-toggle>
       <mat-date-range-picker #picker></mat-date-range-picker>
 
     </mat-form-field>
@@ -653,9 +859,40 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                 }]
         }], propDecorators: { disabledDays: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabledDays", required: false }] }], minDate: [{ type: i0.Input, args: [{ isSignal: true, alias: "minDate", required: false }] }], maxDate: [{ type: i0.Input, args: [{ isSignal: true, alias: "maxDate", required: false }] }], onDateRangeObjectChange: [{ type: i0.Output, args: ["onDateRangeObjectChange"] }] } });
 
+/**
+ * `<iss-ctrl-time-picker>` — time of day, picked from a list generated at a fixed interval.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-time-picker formControlName="startsAt" interval="15min" minTime="08:00" maxTime="17:00">
+ *   <label>Starts at</label>
+ * </iss-ctrl-time-picker>
+ * ```
+ *
+ * ### Own inputs
+ * | Property | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `interval` | `string` | `"30min"` | Step between the offered times. |
+ * | `minTime` | `string \| null` | `null` | Earliest offered time, `HH:mm`. |
+ * | `maxTime` | `string \| null` | `null` | Latest offered time, `HH:mm`. |
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)`
+ *
+ * Projects `<label>` into the floating label; omit it to render the control without one.
+ */
 class TimePickerControl extends ControlBase {
+    /**
+     * Step between the offered times, for example `"15min"` or `"30min"`.
+     */
     interval = input("30min", ...(ngDevMode ? [{ debugName: "interval" }] : /* istanbul ignore next */ []));
+    /**
+     * Earliest offered time of day, as `HH:mm`.
+     */
     minTime = input(null, ...(ngDevMode ? [{ debugName: "minTime" }] : /* istanbul ignore next */ []));
+    /**
+     * Latest offered time of day, as `HH:mm`.
+     */
     maxTime = input(null, ...(ngDevMode ? [{ debugName: "maxTime" }] : /* istanbul ignore next */ []));
     emit(evt) {
         if (this.readonly()) {
@@ -705,22 +942,21 @@ class TimePickerControl extends ControlBase {
             { provide: NG_VALIDATORS, useExisting: TimePickerControl, multi: true },
         ], usesInheritance: true, ngImport: i0, template: `
     <mat-form-field floatLabel="auto" class="">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <input
         matInput
         [formControl]="ctrl"
         [matTimepicker]="picker"
         [matTimepickerMin]="minTime()"
-        [matTimepickerMax]="maxTime()"
-        [readonly]="readonly()"
+        [matTimepickerMax]="maxTime()"
+        [readonly]="readonly()"
         readonly
       />
       @if (ctrl.getRawValue()) {
         <mat-icon matSuffix style="cursor: pointer" (click)="clear($event)">close</mat-icon>
       }
-      <mat-timepicker-toggle matIconSuffix [for]="picker" [disabled]="readonly()"/>
+      <mat-timepicker-toggle matIconSuffix [for]="picker" [disabled]="readonly()"/>
       <mat-timepicker (selected)="emit($event)" [interval]="interval()" #picker/>
 
     </mat-form-field>
@@ -741,22 +977,21 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                     ],
                     template: `
     <mat-form-field floatLabel="auto" class="">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <input
         matInput
         [formControl]="ctrl"
         [matTimepicker]="picker"
         [matTimepickerMin]="minTime()"
-        [matTimepickerMax]="maxTime()"
-        [readonly]="readonly()"
+        [matTimepickerMax]="maxTime()"
+        [readonly]="readonly()"
         readonly
       />
       @if (ctrl.getRawValue()) {
         <mat-icon matSuffix style="cursor: pointer" (click)="clear($event)">close</mat-icon>
       }
-      <mat-timepicker-toggle matIconSuffix [for]="picker" [disabled]="readonly()"/>
+      <mat-timepicker-toggle matIconSuffix [for]="picker" [disabled]="readonly()"/>
       <mat-timepicker (selected)="emit($event)" [interval]="interval()" #picker/>
 
     </mat-form-field>
@@ -764,15 +999,57 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                 }]
         }], propDecorators: { interval: [{ type: i0.Input, args: [{ isSignal: true, alias: "interval", required: false }] }], minTime: [{ type: i0.Input, args: [{ isSignal: true, alias: "minTime", required: false }] }], maxTime: [{ type: i0.Input, args: [{ isSignal: true, alias: "maxTime", required: false }] }] } });
 
+/**
+ * `<iss-ctrl-datetime-picker>` — a date and a time in a single field.
+ *
+ * Combines the calendar of the date picker with the time list of the time picker; both parts
+ * must be set before a value is emitted.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-datetime-picker formControlName="scheduledAt" [minDate]="today" minTime="08:00" maxTime="17:00">
+ *   <label>Scheduled at</label>
+ * </iss-ctrl-datetime-picker>
+ * ```
+ *
+ * ### Own inputs
+ * | Property | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `minDate` | `Date \| null` | `null` | Earliest selectable date. |
+ * | `maxDate` | `Date \| null` | `null` | Latest selectable date. |
+ * | `minTime` | `string \| null` | `null` | Earliest selectable time, `HH:mm`. |
+ * | `maxTime` | `string \| null` | `null` | Latest selectable time, `HH:mm`. |
+ * | `disabledDays` | `number[]` | `[]` | Week days to block, `0` = Sunday … `6` = Saturday. |
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)`
+ *
+ * Projects `<label>` into the floating label; omit it to render the control without one.
+ */
 class DatetimePickerControl extends ControlBase {
     datetimeForm = new FormGroup({
         date: new FormControl(null),
         time: new FormControl(null),
     });
+    /**
+     * Week days that cannot be selected — `0` is Sunday through `6` for Saturday.
+     */
     disabledDays = input([], ...(ngDevMode ? [{ debugName: "disabledDays" }] : /* istanbul ignore next */ []));
+    /**
+     * Earliest selectable date.
+     */
     minDate = input(null, ...(ngDevMode ? [{ debugName: "minDate" }] : /* istanbul ignore next */ []));
+    /**
+     * Latest selectable date.
+     */
     maxDate = input(null, ...(ngDevMode ? [{ debugName: "maxDate" }] : /* istanbul ignore next */ []));
+    /**
+     * Earliest selectable time of day, as `HH:mm`.
+     */
     minTime = input(null, ...(ngDevMode ? [{ debugName: "minTime" }] : /* istanbul ignore next */ []));
+    /**
+     * Latest selectable time of day, as `HH:mm`.
+     */
     maxTime = input(null, ...(ngDevMode ? [{ debugName: "maxTime" }] : /* istanbul ignore next */ []));
     setDisabledState(isDisabled) {
         super.setDisabledState(isDisabled);
@@ -839,16 +1116,16 @@ class DatetimePickerControl extends ControlBase {
             { provide: NG_VALIDATORS, useExisting: DatetimePickerControl, multi: true },
         ], usesInheritance: true, ngImport: i0, template: `
     <form [formGroup]="datetimeForm" class="d-flex flex-row gap-1">
-      <iss-ctrl-date-picker (focusout)="markAsTouched()" [disabledDays]="disabledDays()" [maxDate]="maxDate()" [minDate]="minDate()" [readonly]="readonly()" formControlName="date" (onChange)="emit()">
-        <label>
-          <ng-content select="label"></ng-content>
-        </label>
+      <iss-ctrl-date-picker (focusout)="markAsTouched()" [disabledDays]="disabledDays()" [maxDate]="maxDate()" [minDate]="minDate()" [readonly]="readonly()" formControlName="date" (onChange)="emit()">
+        <!-- Re-projected with ngProjectAs so it still matches the date picker's own select="label";
+             wrapping it in a second <label> instead would hide an empty label from the :empty rule in upgrade.scss. -->
+        <ng-content select="label" ngProjectAs="label"></ng-content>
       </iss-ctrl-date-picker>
       <iss-ctrl-time-picker
         (focusout)="markAsTouched()"
         [maxTime]="maxTime()"
-        [minTime]="minTime()"
-        [readonly]="readonly()"
+        [minTime]="minTime()"
+        [readonly]="readonly()"
         formControlName="time"
         (onChange)="emit()"
       />
@@ -874,16 +1151,16 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                     ],
                     template: `
     <form [formGroup]="datetimeForm" class="d-flex flex-row gap-1">
-      <iss-ctrl-date-picker (focusout)="markAsTouched()" [disabledDays]="disabledDays()" [maxDate]="maxDate()" [minDate]="minDate()" [readonly]="readonly()" formControlName="date" (onChange)="emit()">
-        <label>
-          <ng-content select="label"></ng-content>
-        </label>
+      <iss-ctrl-date-picker (focusout)="markAsTouched()" [disabledDays]="disabledDays()" [maxDate]="maxDate()" [minDate]="minDate()" [readonly]="readonly()" formControlName="date" (onChange)="emit()">
+        <!-- Re-projected with ngProjectAs so it still matches the date picker's own select="label";
+             wrapping it in a second <label> instead would hide an empty label from the :empty rule in upgrade.scss. -->
+        <ng-content select="label" ngProjectAs="label"></ng-content>
       </iss-ctrl-date-picker>
       <iss-ctrl-time-picker
         (focusout)="markAsTouched()"
         [maxTime]="maxTime()"
-        [minTime]="minTime()"
-        [readonly]="readonly()"
+        [minTime]="minTime()"
+        [readonly]="readonly()"
         formControlName="time"
         (onChange)="emit()"
       />
@@ -988,12 +1265,62 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                 args: ["drop", ["$event"]]
             }] } });
 
+/**
+ * `<iss-ctrl-file-picker>` — attachment upload with a per-file progress and error state.
+ *
+ * Uploading is done by the host: the control emits the picked files and renders whatever is
+ * fed back through `uploadedFiles`, `uploading` and `uploadingError`.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-file-picker
+ *   formControlName="attachments"
+ *   [multiple]="true"
+ *   accept=".pdf,.png"
+ *   [uploading]="uploading()"
+ *   [uploadedFiles]="uploaded()"
+ * />
+ * ```
+ *
+ * ### Own inputs
+ * | Property | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `accept` | `string \| undefined` | `undefined` | Accepted extensions or MIME types for the native picker. |
+ * | `showDownloadButton` | `boolean` | `true` | Shows the download action on each attachment. |
+ * | `showDeleteButton` | `boolean` | `true` | Shows the remove action on each attachment. |
+ * | `uploading` | `boolean` | `false` | Renders the in-progress state. |
+ * | `uploadedFiles` | `IssAttachment[]` | `[]` | Files already stored on the server. |
+ * | `uploadingError` | `string \| undefined` | `undefined` | Error message attached to the failed upload. |
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)` · `multiple` · `hints`
+ *
+ * Does not project a label — the field label is rendered by the wrapping `iss-field-*`.
+ */
 class FilePickerControl extends ControlBase {
+    /**
+     * Accepted extensions or MIME types, passed straight to the native file input.
+     */
     accept = input(...(ngDevMode ? [undefined, { debugName: "accept" }] : /* istanbul ignore next */ []));
+    /**
+     * Shows the download action on each listed attachment.
+     */
     showDownloadButton = input(true, ...(ngDevMode ? [{ debugName: "showDownloadButton" }] : /* istanbul ignore next */ []));
+    /**
+     * Shows the remove action on each listed attachment.
+     */
     showDeleteButton = input(true, ...(ngDevMode ? [{ debugName: "showDeleteButton" }] : /* istanbul ignore next */ []));
+    /**
+     * Renders the upload-in-progress state; set by the host that performs the upload.
+     */
     uploading = input(false, ...(ngDevMode ? [{ debugName: "uploading" }] : /* istanbul ignore next */ []));
+    /**
+     * Attachments already stored on the server, merged into the rendered list.
+     */
     uploadedFiles = input([], ...(ngDevMode ? [{ debugName: "uploadedFiles" }] : /* istanbul ignore next */ []));
+    /**
+     * Error message shown on the attachment whose upload failed.
+     */
     uploadingError = input(undefined, ...(ngDevMode ? [{ debugName: "uploadingError" }] : /* istanbul ignore next */ []));
     filesValue = computed(() => this.#returnAttachmentViewObject(), ...(ngDevMode ? [{ debugName: "filesValue" }] : /* istanbul ignore next */ []));
     attachments = signal([], ...(ngDevMode ? [{ debugName: "attachments" }] : /* istanbul ignore next */ []));
@@ -1163,13 +1490,67 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
   `, styles: [".file-uploader{--uploader-height: 150px;--uploader-width: 100%;--uploader-bg: var(--off-white);--uploader-border: 1px dashed var(--dark-gray);--uploader-radius: var(--box-radius);--uploader-padding: 1rem;height:var(--uploader-height);background-color:var(--uploader-bg);border:var(--uploader-border);border-radius:var(--uploader-radius);padding:var(--uploader-padding);text-align:center;cursor:pointer}.file-uploader --input{display:flex;flex-direction:column;align-items:center;justify-content:center;height:100%;gap:.75rem}\n"] }]
         }], propDecorators: { accept: [{ type: i0.Input, args: [{ isSignal: true, alias: "accept", required: false }] }], showDownloadButton: [{ type: i0.Input, args: [{ isSignal: true, alias: "showDownloadButton", required: false }] }], showDeleteButton: [{ type: i0.Input, args: [{ isSignal: true, alias: "showDeleteButton", required: false }] }], uploading: [{ type: i0.Input, args: [{ isSignal: true, alias: "uploading", required: false }] }], uploadedFiles: [{ type: i0.Input, args: [{ isSignal: true, alias: "uploadedFiles", required: false }] }], uploadingError: [{ type: i0.Input, args: [{ isSignal: true, alias: "uploadingError", required: false }] }] } });
 
+/**
+ * `<iss-ctrl-input>` — single line text input, the base for every scalar text field.
+ *
+ * `type` is forwarded to the native input, so `number`, `email` and `password` variants all
+ * come from this one control.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-input formControlName="amount" type="number" [min]="0" suffixText="SAR">
+ *   <label>Amount</label>
+ * </iss-ctrl-input>
+ * ```
+ *
+ * ### Own inputs
+ * | Property | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `type` | `string` | `"text"` | Native input type: `text`, `number`, `email`, `password`, … |
+ * | `prefixIcon` | `string` | `""` | Icon rendered before the value. |
+ * | `prefixText` | `string` | `""` | Text rendered before the value. |
+ * | `suffixIcon` | `string` | `""` | Icon rendered after the value. |
+ * | `suffixText` | `string` | `""` | Text rendered after the value. |
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)` · `placeholder` · `min` · `max` · `minLength` · `maxLength` · `hints`
+ *
+ * ### Outputs
+ * - `(onPrefixClick)` — `string`, the prefix affix was clicked.
+ * - `(onSuffixClick)` — `string`, the suffix affix was clicked.
+ *
+ * Projects `<label>` into the floating label; omit it to render the control without one.
+ *
+ * Also projects `[issPrefix]` and `[issSuffix]` for fully custom affixes.
+ */
 class InputControl extends ControlBase {
+    /**
+     * Native input type — `text`, `number`, `email`, `password`, and so on.
+     */
     type = input("text", ...(ngDevMode ? [{ debugName: "type" }] : /* istanbul ignore next */ []));
+    /**
+     * Icon name rendered before the value.
+     */
     prefixIcon = input("", ...(ngDevMode ? [{ debugName: "prefixIcon" }] : /* istanbul ignore next */ []));
+    /**
+     * Static text rendered before the value.
+     */
     prefixText = input("", ...(ngDevMode ? [{ debugName: "prefixText" }] : /* istanbul ignore next */ []));
+    /**
+     * Icon name rendered after the value.
+     */
     suffixIcon = input("", ...(ngDevMode ? [{ debugName: "suffixIcon" }] : /* istanbul ignore next */ []));
+    /**
+     * Static text rendered after the value, a unit or currency for example.
+     */
     suffixText = input("", ...(ngDevMode ? [{ debugName: "suffixText" }] : /* istanbul ignore next */ []));
+    /**
+     * Emits when the prefix affix is clicked.
+     */
     onPrefixClick = output();
+    /**
+     * Emits when the suffix affix is clicked.
+     */
     onSuffixClick = output();
     #disabledEffect = effect(() => {
         if (this.disabled()) {
@@ -1194,9 +1575,8 @@ class InputControl extends ControlBase {
             { provide: NG_VALIDATORS, useExisting: InputControl, multi: true }
         ], usesInheritance: true, ngImport: i0, template: `
     <mat-form-field floatLabel="auto" class="">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <ng-content select="[issPrefix]"></ng-content>
       <div (click)="emitPrefixClick()" class="cursor-pointer">
         @if (prefixText()) {
@@ -1215,8 +1595,8 @@ class InputControl extends ControlBase {
         [attr.minlength]="minLength()"
         [attr.max]="max()"
         [attr.min]="min()"
-        [placeholder]="placeholder()"
-        [readonly]="readonly()"
+        [placeholder]="placeholder()"
+        [readonly]="readonly()"
         [type]="type()"
       />
       <ng-content select="[issSuffix]"></ng-content>
@@ -1251,9 +1631,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                     ],
                     template: `
     <mat-form-field floatLabel="auto" class="">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <ng-content select="[issPrefix]"></ng-content>
       <div (click)="emitPrefixClick()" class="cursor-pointer">
         @if (prefixText()) {
@@ -1272,8 +1651,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
         [attr.minlength]="minLength()"
         [attr.max]="max()"
         [attr.min]="min()"
-        [placeholder]="placeholder()"
-        [readonly]="readonly()"
+        [placeholder]="placeholder()"
+        [readonly]="readonly()"
         [type]="type()"
       />
       <ng-content select="[issSuffix]"></ng-content>
@@ -3427,10 +3806,35 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
             args: [{ providedIn: "root" }]
         }] });
 
+/**
+ * `<iss-ctrl-mobile>` — international phone number with a country selector.
+ *
+ * The number is validated against the selected country and stored in its international form.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-mobile formControlName="mobile" [preferredCountries]="['SA', 'AE']">
+ *   <label>Mobile</label>
+ * </iss-ctrl-mobile>
+ * ```
+ *
+ * ### Own inputs
+ * | Property | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `preferredCountries` | `ISO2[]` | `["SA"]` | Countries pinned to the top of the country list. |
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)`
+ *
+ * Projects `<label>` into the floating label; omit it to render the control without one.
+ */
 class MobileControl extends ControlBase {
     phoneService = inject(Phone);
     isOpen = signal(false, ...(ngDevMode ? [{ debugName: "isOpen" }] : /* istanbul ignore next */ []));
     selectedCountry = signal(DEFAULT_COUNTRY, ...(ngDevMode ? [{ debugName: "selectedCountry" }] : /* istanbul ignore next */ []));
+    /**
+     * ISO-2 country codes pinned to the top of the country list; the first one is preselected.
+     */
     preferredCountries = input(["SA"], ...(ngDevMode ? [{ debugName: "preferredCountries" }] : /* istanbul ignore next */ []));
     searchInput = new FormControl("");
     filteredCountries = computed(() => this.#searchInCountries(), ...(ngDevMode ? [{ debugName: "filteredCountries" }] : /* istanbul ignore next */ []));
@@ -3561,9 +3965,8 @@ class MobileControl extends ControlBase {
             { provide: NG_VALIDATORS, useExisting: MobileControl, multi: true }
         ], usesInheritance: true, ngImport: i0, template: `
     <mat-form-field floatLabel="auto" cdkOverlayOrigin #trigger="cdkOverlayOrigin">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <div class="d-inline-flex align-items-center gap-1 country-flag" matPrefix (click)="toggleCountryCodeMenu()">
         <img
           ngSrc="./flags/{{selectedCountry().code.toLowerCase()}}.svg"
@@ -3582,8 +3985,8 @@ class MobileControl extends ControlBase {
         (blur)="markAsTouched()"
         (keydown)="onInput($event)"
         (input)="emit()"
-        [formControl]="ctrl"
-        [readonly]="readonly()"
+        [formControl]="ctrl"
+        [readonly]="readonly()"
         [placeholder]="selectedCountry().placeholder"
       />
     </mat-form-field>
@@ -3638,9 +4041,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                         { provide: NG_VALIDATORS, useExisting: MobileControl, multi: true }
                     ], template: `
     <mat-form-field floatLabel="auto" cdkOverlayOrigin #trigger="cdkOverlayOrigin">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <div class="d-inline-flex align-items-center gap-1 country-flag" matPrefix (click)="toggleCountryCodeMenu()">
         <img
           ngSrc="./flags/{{selectedCountry().code.toLowerCase()}}.svg"
@@ -3659,8 +4061,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
         (blur)="markAsTouched()"
         (keydown)="onInput($event)"
         (input)="emit()"
-        [formControl]="ctrl"
-        [readonly]="readonly()"
+        [formControl]="ctrl"
+        [readonly]="readonly()"
         [placeholder]="selectedCountry().placeholder"
       />
     </mat-form-field>
@@ -3719,6 +4121,26 @@ const PLATE_LETTERS = [
     { label: { ar: "ي", en: "V" }, value: "V" }
 ];
 
+/**
+ * `<iss-ctrl-plate-number>` — Saudi vehicle plate, entered as digits and letters in both
+ * Arabic and English.
+ *
+ * Typing into one script fills the matching cell in the other automatically, and letters are
+ * validated against the allowed plate alphabet.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-plate-number formControlName="plate" [readonly]="false"/>
+ * ```
+ *
+ * ### Own inputs
+ * None — the control is configured entirely through the inherited properties.
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)`
+ *
+ * Does not project a label — the field label is rendered by the wrapping `iss-field-*`.
+ */
 class PlateControl extends ControlBase {
     numbersAr = signal(Array(4).fill(""), ...(ngDevMode ? [{ debugName: "numbersAr" }] : /* istanbul ignore next */ []));
     numbersEn = signal(Array(4).fill(""), ...(ngDevMode ? [{ debugName: "numbersEn" }] : /* istanbul ignore next */ []));
@@ -3951,8 +4373,8 @@ class PlateControl extends ControlBase {
               class="plate-input number-input"
               maxlength="1"
               [attr.data-plate-input]="'num-ar-' + $index"
-              [value]="num"
-              [readonly]="readonly()"
+              [value]="num"
+              [readonly]="readonly()"
               placeholder="١"
               (keydown)="preventNonDigits($event, 'ar')"
               (keyup)="preventNonDigits($event, 'ar')"
@@ -3968,8 +4390,8 @@ class PlateControl extends ControlBase {
               class="plate-input number-input"
               maxlength="1"
               [attr.data-plate-input]="'num-en-' + $index"
-              [value]="num"
-              [readonly]="readonly()"
+              [value]="num"
+              [readonly]="readonly()"
               placeholder="1"
               (keydown)="preventNonDigits($event, 'en')"
               (keyup)="preventNonDigits($event, 'en')"
@@ -4000,8 +4422,8 @@ class PlateControl extends ControlBase {
                 maxlength="1"
                 [attr.data-plate-input]="'let-ar-' + $index"
                 [class.invalid]="letterErrors()[$index]"
-                [value]="letter"
-                [readonly]="readonly()"
+                [value]="letter"
+                [readonly]="readonly()"
                 placeholder="س"
                 (input)="onLetterInput($index, $event, 'ar')"
               />
@@ -4021,8 +4443,8 @@ class PlateControl extends ControlBase {
                 maxlength="1"
                 [attr.data-plate-input]="'let-en-' + $index"
                 [class.invalid]="letterErrors()[$index]"
-                [value]="letter"
-                [readonly]="readonly()"
+                [value]="letter"
+                [readonly]="readonly()"
                 placeholder="S"
                 (input)="onLetterInput($index, $event, 'en')"
               />
@@ -4061,8 +4483,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
               class="plate-input number-input"
               maxlength="1"
               [attr.data-plate-input]="'num-ar-' + $index"
-              [value]="num"
-              [readonly]="readonly()"
+              [value]="num"
+              [readonly]="readonly()"
               placeholder="١"
               (keydown)="preventNonDigits($event, 'ar')"
               (keyup)="preventNonDigits($event, 'ar')"
@@ -4078,8 +4500,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
               class="plate-input number-input"
               maxlength="1"
               [attr.data-plate-input]="'num-en-' + $index"
-              [value]="num"
-              [readonly]="readonly()"
+              [value]="num"
+              [readonly]="readonly()"
               placeholder="1"
               (keydown)="preventNonDigits($event, 'en')"
               (keyup)="preventNonDigits($event, 'en')"
@@ -4110,8 +4532,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                 maxlength="1"
                 [attr.data-plate-input]="'let-ar-' + $index"
                 [class.invalid]="letterErrors()[$index]"
-                [value]="letter"
-                [readonly]="readonly()"
+                [value]="letter"
+                [readonly]="readonly()"
                 placeholder="س"
                 (input)="onLetterInput($index, $event, 'ar')"
               />
@@ -4131,8 +4553,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                 maxlength="1"
                 [attr.data-plate-input]="'let-en-' + $index"
                 [class.invalid]="letterErrors()[$index]"
-                [value]="letter"
-                [readonly]="readonly()"
+                [value]="letter"
+                [readonly]="readonly()"
                 placeholder="S"
                 (input)="onLetterInput($index, $event, 'en')"
               />
@@ -4156,7 +4578,28 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
   `, styles: [".plate-container{width:600px;height:130px;border:4px solid #1D252D;border-radius:10px;background:#fff;display:flex;box-shadow:0 4px 10px #0003;overflow:hidden;position:relative}.section{display:flex;flex-direction:column;justify-content:center;align-items:center}.numbers-section{flex:2;padding:0 10px}.digit-row{display:flex;justify-content:space-between;width:80%;font-size:38px;line-height:1;color:#1d252d;margin:2px 0}.emblem-section{flex:1.2;padding:10px}.emblem-svg{width:100%;height:100%;max-height:90px}.letters-section{flex:1.8;border-right:2px solid #1D252D;padding:0 10px}.arabic-row{font-family:Noto Sans Arabic,sans-serif;font-size:32px;display:flex;justify-content:space-around;width:100%;margin-bottom:5px;color:#1d252d}.english-row{font-size:38px;display:flex;justify-content:space-around;width:100%;color:#1d252d}.ksa-strip{width:50px;display:flex;flex-direction:column;justify-content:space-between;align-items:center;padding:10px 0;background-color:#fff}.mini-emblem{width:25px;height:auto}.ksa-text{writing-mode:vertical-rl;text-orientation:upright;font-weight:900;font-size:16px;letter-spacing:2px;color:#1d252d;margin-top:auto;margin-bottom:5px}.plate-input{background:transparent;border:none;text-align:center;font-family:inherit;font-size:inherit;font-weight:700;color:#1d252d;width:100%;padding:0;margin:0;outline:none}.plate-input:focus{border-bottom:2px solid #1D252D}.digit-row,.arabic-row,.english-row{display:flex;justify-content:space-between;width:100%}.number-input,.letter-input{flex:1}.plate-input::placeholder{color:#ccc;opacity:1}.input-wrapper{position:relative;display:flex;flex-direction:column;align-items:center;flex:1}.error-tooltip{position:absolute;bottom:-15px;font-size:10px;color:red;white-space:nowrap}.plate-input.invalid{color:red}\n"] }]
         }] });
 
+/**
+ * `<iss-ctrl-radio>` — one choice out of a fixed set of options.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-radio formControlName="gender" [options]="genders"/>
+ * ```
+ *
+ * ### Own inputs
+ * | Property | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `options` | `Option[]` | **required** | The selectable choices. |
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)`
+ *
+ * Does not project a label — the field label is rendered by the wrapping `iss-field-*`.
+ */
 class RadioControl extends ControlBase {
+    /**
+     * Selectable choices, each a `{ value, label }` pair. Required.
+     */
     options = input.required(...(ngDevMode ? [{ debugName: "options" }] : /* istanbul ignore next */ []));
     writeValue(value) {
         if (!value) {
@@ -4182,7 +4625,7 @@ class RadioControl extends ControlBase {
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: RadioControl, isStandalone: true, selector: "iss-ctrl-radio", inputs: { options: { classPropertyName: "options", publicName: "options", isSignal: true, isRequired: true, transformFunction: null } }, providers: [
             { provide: NG_VALUE_ACCESSOR, useExisting: RadioControl, multi: true }
         ], usesInheritance: true, ngImport: i0, template: `
-    <mat-button-toggle-group [hideSingleSelectionIndicator]="true" [disabled]="disabled() || readonly()">
+    <mat-button-toggle-group [hideSingleSelectionIndicator]="true" [disabled]="disabled() || readonly()">
       @for (option of options(); track option.value) {
         <mat-button-toggle
           [value]="option.value"
@@ -4207,7 +4650,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                         { provide: NG_VALUE_ACCESSOR, useExisting: RadioControl, multi: true }
                     ],
                     template: `
-    <mat-button-toggle-group [hideSingleSelectionIndicator]="true" [disabled]="disabled() || readonly()">
+    <mat-button-toggle-group [hideSingleSelectionIndicator]="true" [disabled]="disabled() || readonly()">
       @for (option of options(); track option.value) {
         <mat-button-toggle
           [value]="option.value"
@@ -4221,13 +4664,59 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                 }]
         }], propDecorators: { options: [{ type: i0.Input, args: [{ isSignal: true, alias: "options", required: true }] }] } });
 
+/**
+ * `<iss-ctrl-select>` — dropdown selection, single or multiple, with a search box.
+ *
+ * Typing in the search box emits `(onQueryChange)`, so options can be loaded remotely; set
+ * `loading` while that request is in flight.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-select
+ *   formControlName="city"
+ *   [options]="cities()"
+ *   [multiple]="false"
+ *   [loading]="loading()"
+ *   (onQueryChange)="search($event)"
+ * >
+ *   <label>City</label>
+ * </iss-ctrl-select>
+ * ```
+ *
+ * ### Own inputs
+ * | Property | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `options` | `Option[]` | **required** | The selectable choices. |
+ * | `height` | `string` | `"150px"` | Max height of the open panel. |
+ * | `loading` | `boolean` | `false` | Shows the loading state inside the panel. |
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)` · `placeholder` · `multiple`
+ *
+ * ### Outputs
+ * - `(onQueryChange)` — `string`, the current search text.
+ *
+ * Projects `<label>` into the floating label; omit it to render the control without one.
+ */
 class SelectControl extends ControlBase {
     selectedOptions = signal(new Map(), ...(ngDevMode ? [{ debugName: "selectedOptions" }] : /* istanbul ignore next */ []));
+    /**
+     * Selectable choices, each a `{ value, label }` pair. Required.
+     */
     options = input.required(...(ngDevMode ? [{ debugName: "options" }] : /* istanbul ignore next */ []));
+    /**
+     * Maximum height of the open options panel, as a CSS length.
+     */
     height = input("150px", ...(ngDevMode ? [{ debugName: "height" }] : /* istanbul ignore next */ []));
     query = toSignal(this.ctrl.valueChanges);
     filteredOptions = computed(() => this.#filter(this.query()), ...(ngDevMode ? [{ debugName: "filteredOptions" }] : /* istanbul ignore next */ []));
+    /**
+     * Shows the loading state inside the panel while options are being fetched.
+     */
     loading = input(false, ...(ngDevMode ? [{ debugName: "loading" }] : /* istanbul ignore next */ []));
+    /**
+     * Emits the search text so the host can load matching options.
+     */
     onQueryChange = output();
     optionTemplate = contentChild("optionTemplate", ...(ngDevMode ? [{ debugName: "optionTemplate" }] : /* istanbul ignore next */ []));
     cardViewerTemplate = contentChild("cardViewerTemplate", ...(ngDevMode ? [{ debugName: "cardViewerTemplate" }] : /* istanbul ignore next */ []));
@@ -4370,10 +4859,9 @@ class SelectControl extends ControlBase {
             { provide: NG_VALUE_ACCESSOR, useExisting: SelectControl, multi: true },
         ], queries: [{ propertyName: "optionTemplate", first: true, predicate: ["optionTemplate"], descendants: true, isSignal: true }, { propertyName: "cardViewerTemplate", first: true, predicate: ["cardViewerTemplate"], descendants: true, isSignal: true }], usesInheritance: true, ngImport: i0, template: `
     <mat-form-field floatLabel="auto" class="">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
-      <input [formControl]="ctrl" [matAutocomplete]="auto" [matChipInputFor]="chipGrid" [placeholder]="placeholder()" [readonly]="readonly()" (blur)="markAsTouched()" class="m-0" matInput/>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
+      <input [formControl]="ctrl" [matAutocomplete]="auto" [matChipInputFor]="chipGrid" [placeholder]="placeholder()" [readonly]="readonly()" (blur)="markAsTouched()" class="m-0" matInput/>
       @if (!disabled()) {
         @if (selectedOptions().size) {
           <span matSuffix class="sfi sfi-close fs-18 fc-black cursor-pointer" (click)="clearSelection()"></span>
@@ -4421,7 +4909,7 @@ class SelectControl extends ControlBase {
             } @else {
               {{ chip[1].label }}
             }
-            <button matChipRemove [disabled]="readonly()" [attr.aria-label]="'remove ' + chip[1].label">
+            <button matChipRemove [disabled]="readonly()" [attr.aria-label]="'remove ' + chip[1].label">
               <ds-icon icon="trash" class="fc-red"></ds-icon>
             </button>
           </mat-chip-row>
@@ -4449,10 +4937,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                         { provide: NG_VALUE_ACCESSOR, useExisting: SelectControl, multi: true },
                     ], template: `
     <mat-form-field floatLabel="auto" class="">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
-      <input [formControl]="ctrl" [matAutocomplete]="auto" [matChipInputFor]="chipGrid" [placeholder]="placeholder()" [readonly]="readonly()" (blur)="markAsTouched()" class="m-0" matInput/>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
+      <input [formControl]="ctrl" [matAutocomplete]="auto" [matChipInputFor]="chipGrid" [placeholder]="placeholder()" [readonly]="readonly()" (blur)="markAsTouched()" class="m-0" matInput/>
       @if (!disabled()) {
         @if (selectedOptions().size) {
           <span matSuffix class="sfi sfi-close fs-18 fc-black cursor-pointer" (click)="clearSelection()"></span>
@@ -4500,7 +4987,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
             } @else {
               {{ chip[1].label }}
             }
-            <button matChipRemove [disabled]="readonly()" [attr.aria-label]="'remove ' + chip[1].label">
+            <button matChipRemove [disabled]="readonly()" [attr.aria-label]="'remove ' + chip[1].label">
               <ds-icon icon="trash" class="fc-red"></ds-icon>
             </button>
           </mat-chip-row>
@@ -4510,6 +4997,22 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
   `, schemas: [CUSTOM_ELEMENTS_SCHEMA] }]
         }], propDecorators: { options: [{ type: i0.Input, args: [{ isSignal: true, alias: "options", required: true }] }], height: [{ type: i0.Input, args: [{ isSignal: true, alias: "height", required: false }] }], loading: [{ type: i0.Input, args: [{ isSignal: true, alias: "loading", required: false }] }], onQueryChange: [{ type: i0.Output, args: ["onQueryChange"] }], optionTemplate: [{ type: i0.ContentChild, args: ["optionTemplate", { isSignal: true }] }], cardViewerTemplate: [{ type: i0.ContentChild, args: ["cardViewerTemplate", { isSignal: true }] }] } });
 
+/**
+ * `<iss-ctrl-slide-toggle>` — an on/off switch for a boolean value.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-slide-toggle formControlName="active" (onChange)="save($event)"/>
+ * ```
+ *
+ * ### Own inputs
+ * None — the control is configured entirely through the inherited properties.
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)`
+ *
+ * Does not project a label — the field label is rendered by the wrapping `iss-field-*`.
+ */
 class SlideToggleControl extends ControlBase {
     onSlideToggleChange(checked) {
         if (this.readonly()) {
@@ -4523,8 +5026,8 @@ class SlideToggleControl extends ControlBase {
             { provide: NG_VALUE_ACCESSOR, useExisting: SlideToggleControl, multi: true }
         ], usesInheritance: true, ngImport: i0, template: `
     <mat-slide-toggle
-      class="d-block" [formControl]="ctrl"
-      [disabled]="readonly()"
+      class="d-block" [formControl]="ctrl"
+      [disabled]="readonly()"
       (change)="onSlideToggleChange($event.checked)"
     >
     </mat-slide-toggle>
@@ -4540,8 +5043,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                     ],
                     template: `
     <mat-slide-toggle
-      class="d-block" [formControl]="ctrl"
-      [disabled]="readonly()"
+      class="d-block" [formControl]="ctrl"
+      [disabled]="readonly()"
       (change)="onSlideToggleChange($event.checked)"
     >
     </mat-slide-toggle>
@@ -4549,6 +5052,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                 }]
         }] });
 
+/**
+ * `<iss-ctrl-textarea>` — multi line free text.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-textarea formControlName="notes" [maxLength]="500" placeholder="Add a note">
+ *   <label>Notes</label>
+ * </iss-ctrl-textarea>
+ * ```
+ *
+ * ### Own inputs
+ * None — the control is configured entirely through the inherited properties.
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)` · `placeholder` · `minLength` · `maxLength` · `hints`
+ *
+ * Projects `<label>` into the floating label; omit it to render the control without one.
+ */
 class TextareaControl extends ControlBase {
     #disabledEffect = effect(() => {
         if (this.disabled()) {
@@ -4567,16 +5088,15 @@ class TextareaControl extends ControlBase {
             { provide: NG_VALIDATORS, useExisting: TextareaControl, multi: true }
         ], usesInheritance: true, ngImport: i0, template: `
     <mat-form-field floatLabel="auto" class="custom-textarea">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <textarea
         matInput
         [placeholder]="placeholder()"
         [formControl]="ctrl"
         [attr.maxlength]="maxLength()"
-        [attr.minlength]="minLength()"
-        [readonly]="readonly()"
+        [attr.minlength]="minLength()"
+        [readonly]="readonly()"
         (input)="emitValue()"
         (focusout)="markAsTouched()"
       >
@@ -4604,16 +5124,15 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                     schemas: [CUSTOM_ELEMENTS_SCHEMA],
                     template: `
     <mat-form-field floatLabel="auto" class="custom-textarea">
-      <mat-label class="fs-16 fc-black">
-        <ng-content select="label"></ng-content>
-      </mat-label>
+      <!-- Kept on one line: an omitted or empty label must leave <mat-label> :empty so upgrade.scss can collapse the floating-label space. -->
+      <mat-label class="fs-16 fc-black"><ng-content select="label"></ng-content></mat-label>
       <textarea
         matInput
         [placeholder]="placeholder()"
         [formControl]="ctrl"
         [attr.maxlength]="maxLength()"
-        [attr.minlength]="minLength()"
-        [readonly]="readonly()"
+        [attr.minlength]="minLength()"
+        [readonly]="readonly()"
         (input)="emitValue()"
         (focusout)="markAsTouched()"
       >
@@ -4624,7 +5143,30 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                 }]
         }] });
 
+/**
+ * `<iss-ctrl-toggle-button>` — options rendered as a button group instead of a dropdown.
+ *
+ * With `multiple` set, several buttons can be active at once.
+ *
+ * @example
+ * ```html
+ * <iss-ctrl-toggle-button formControlName="priority" [options]="priorities" [multiple]="false"/>
+ * ```
+ *
+ * ### Own inputs
+ * | Property | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `options` | `Option[]` | **required** | The selectable choices. |
+ *
+ * ### Inherited from {@link ControlBase}
+ * `formControlName` · `readonly` · `className` · `(onChange)` · `multiple`
+ *
+ * Does not project a label — the field label is rendered by the wrapping `iss-field-*`.
+ */
 class ToggleButtonControl extends ControlBase {
+    /**
+     * Selectable choices, each a `{ value, label }` pair. Required.
+     */
     options = input.required(...(ngDevMode ? [{ debugName: "options" }] : /* istanbul ignore next */ []));
     selectedOptions = signal(new Map(), ...(ngDevMode ? [{ debugName: "selectedOptions" }] : /* istanbul ignore next */ []));
     writeValue(value) {
@@ -4705,8 +5247,8 @@ class ToggleButtonControl extends ControlBase {
             { provide: NG_VALUE_ACCESSOR, useExisting: ToggleButtonControl, multi: true }
         ], usesInheritance: true, ngImport: i0, template: `
     <mat-button-toggle-group
-      [formControl]="ctrl"
-      [disabled]="readonly()"
+      [formControl]="ctrl"
+      [disabled]="readonly()"
       [multiple]=multiple()
       [hideMultipleSelectionIndicator]="true"
       [hideSingleSelectionIndicator]="true"
@@ -4723,8 +5265,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
             type: Component,
             args: [{ selector: "iss-ctrl-toggle-button", imports: [MatButtonToggleModule, ReactiveFormsModule], template: `
     <mat-button-toggle-group
-      [formControl]="ctrl"
-      [disabled]="readonly()"
+      [formControl]="ctrl"
+      [disabled]="readonly()"
       [multiple]=multiple()
       [hideMultipleSelectionIndicator]="true"
       [hideSingleSelectionIndicator]="true"
@@ -4747,32 +5289,131 @@ class FieldAsyncValidation {
     }
 }
 
+/**
+ * Per-field configuration, reachable as `field.config` and consumed by the `iss-field-*`
+ * components. Every entry is a signal, so it can be changed at runtime by field events.
+ *
+ * Not every key applies to every field — the class doc of each `iss-field-*` component
+ * lists exactly which of these it reads.
+ *
+ * ### Keys by area
+ * - **Common:** `type` · `disabled` · `readonly` · `placeholder` · `suffix` · `hideLabel` · `multiple`
+ * - **Bounds:** `min` · `max` · `minLength` · `maxLength`
+ * - **Dates:** `minDate` · `maxDate` · `dateFilter`
+ * - **Attachments:** `allowedFileSize` · `allowedFileTypes` · `minFilesCount` · `maxFilesCount` · `templateId` · `templateUrl`
+ * - **Users:** `minUsersCount` · `maxUsersCount`
+ * - **Table:** `showInTableColumns` · `tableWithFilter` · `tableWithSort` · `tableWithPagination`
+ *
+ * @example
+ * ```json
+ * { "name": "email", "type": "text_input", "config": { "type": "email", "maxLength": 120 } }
+ * ```
+ */
 class FieldConfig {
+    /**
+     * Native input type for `text_input` (`text`, `email`, `number`, `password`, …).
+     */
     type = signal(undefined, ...(ngDevMode ? [{ debugName: "type" }] : /* istanbul ignore next */ []));
+    /**
+     * Disables the control; the underlying `FormControl` is disabled on init.
+     */
     disabled = signal(undefined, ...(ngDevMode ? [{ debugName: "disabled" }] : /* istanbul ignore next */ []));
+    /**
+     * Shows the value but blocks interaction. Unlike `disabled`, the value is still submitted.
+     */
     readonly = signal(undefined, ...(ngDevMode ? [{ debugName: "readonly" }] : /* istanbul ignore next */ []));
+    /**
+     * Placeholder text shown while the field is empty.
+     */
     placeholder = signal(undefined, ...(ngDevMode ? [{ debugName: "placeholder" }] : /* istanbul ignore next */ []));
+    /**
+     * Text rendered after the value (a unit or currency, for example).
+     */
     suffix = signal(undefined, ...(ngDevMode ? [{ debugName: "suffix" }] : /* istanbul ignore next */ []));
+    /**
+     * Hides the field label without removing it from the accessibility tree.
+     */
     hideLabel = signal(undefined, ...(ngDevMode ? [{ debugName: "hideLabel" }] : /* istanbul ignore next */ []));
+    /**
+     * Allows more than one value — multi select, multi file upload, multi toggle.
+     */
     multiple = signal(undefined, ...(ngDevMode ? [{ debugName: "multiple" }] : /* istanbul ignore next */ []));
+    /**
+     * Minimum number of characters. Source: `config.minLength`.
+     */
     minLength = signal(undefined, ...(ngDevMode ? [{ debugName: "minLength" }] : /* istanbul ignore next */ []));
+    /**
+     * Maximum number of characters. Source: `config.maxLength`.
+     */
     maxLength = signal(undefined, ...(ngDevMode ? [{ debugName: "maxLength" }] : /* istanbul ignore next */ []));
+    /**
+     * Minimum numeric value (also the minimum user count for the user picker).
+     */
     min = signal(undefined, ...(ngDevMode ? [{ debugName: "min" }] : /* istanbul ignore next */ []));
+    /**
+     * Maximum numeric value (also the maximum user count for the user picker).
+     */
     max = signal(undefined, ...(ngDevMode ? [{ debugName: "max" }] : /* istanbul ignore next */ []));
+    /**
+     * Earliest selectable date for date, datetime and date-range fields.
+     */
     minDate = signal(undefined, ...(ngDevMode ? [{ debugName: "minDate" }] : /* istanbul ignore next */ []));
+    /**
+     * Latest selectable date for date, datetime and date-range fields.
+     */
     maxDate = signal(undefined, ...(ngDevMode ? [{ debugName: "maxDate" }] : /* istanbul ignore next */ []));
+    /**
+     * Restricts the calendar to working days. Source: `config.acceptWorkDaysOnly`.
+     */
     dateFilter = signal(undefined, ...(ngDevMode ? [{ debugName: "dateFilter" }] : /* istanbul ignore next */ []));
+    /**
+     * Id of a downloadable template offered next to an attachment field.
+     */
     templateId = signal(undefined, ...(ngDevMode ? [{ debugName: "templateId" }] : /* istanbul ignore next */ []));
+    /**
+     * Direct URL of the downloadable template for an attachment field.
+     */
     templateUrl = signal(undefined, ...(ngDevMode ? [{ debugName: "templateUrl" }] : /* istanbul ignore next */ []));
+    /**
+     * Maximum size per uploaded file. Source: `config.allowedSize`.
+     */
     allowedFileSize = signal(undefined, ...(ngDevMode ? [{ debugName: "allowedFileSize" }] : /* istanbul ignore next */ []));
+    /**
+     * Comma separated list of accepted file extensions or MIME types.
+     */
     allowedFileTypes = signal(undefined, ...(ngDevMode ? [{ debugName: "allowedFileTypes" }] : /* istanbul ignore next */ []));
+    /**
+     * Maximum number of files that may be attached.
+     */
     maxFilesCount = signal(undefined, ...(ngDevMode ? [{ debugName: "maxFilesCount" }] : /* istanbul ignore next */ []));
+    /**
+     * Minimum number of files required.
+     */
     minFilesCount = signal(undefined, ...(ngDevMode ? [{ debugName: "minFilesCount" }] : /* istanbul ignore next */ []));
+    /**
+     * Maximum number of users selectable in a user picker.
+     */
     maxUsersCount = signal(undefined, ...(ngDevMode ? [{ debugName: "maxUsersCount" }] : /* istanbul ignore next */ []));
+    /**
+     * Minimum number of users required in a user picker.
+     */
     minUsersCount = signal(undefined, ...(ngDevMode ? [{ debugName: "minUsersCount" }] : /* istanbul ignore next */ []));
+    /**
+     * Parsed from the field definition but not consumed yet — table columns currently come
+     * from `field.children`.
+     */
     showInTableColumns = signal(undefined, ...(ngDevMode ? [{ debugName: "showInTableColumns" }] : /* istanbul ignore next */ []));
+    /**
+     * Enables the filter row on a `table` field.
+     */
     tableWithFilter = signal(undefined, ...(ngDevMode ? [{ debugName: "tableWithFilter" }] : /* istanbul ignore next */ []));
+    /**
+     * Enables column sorting on a `table` field.
+     */
     tableWithSort = signal(undefined, ...(ngDevMode ? [{ debugName: "tableWithSort" }] : /* istanbul ignore next */ []));
+    /**
+     * Enables the paginator on a `table` field.
+     */
     tableWithPagination = signal(undefined, ...(ngDevMode ? [{ debugName: "tableWithPagination" }] : /* istanbul ignore next */ []));
     constructor(config) {
         this.type.set(config?.type);
@@ -4877,6 +5518,38 @@ class FieldEvent {
     }
 }
 
+/**
+ * Runtime model of a single form field, built from the JSON definition returned by the API.
+ *
+ * It is what `iss-field-*` components inject through the `FIELD_DATA` token, and the object
+ * field events read from and write to. Signal-valued members can be changed at runtime and
+ * the rendered field reacts immediately.
+ *
+ * ### Properties
+ * | Property | Type | Description |
+ * | --- | --- | --- |
+ * | `id` | `number` | Unique field id. |
+ * | `name` | `string` | Control name inside the form group. |
+ * | `type` | `string` | Key into the `COMPONENTS` index (`text_input`, `dropdown_list`, …). |
+ * | `base` | `string` | Underlying data type of the field. |
+ * | `label()` | `string` | Visible label. |
+ * | `hint()` | `string` | Helper text under the field. |
+ * | `options()` | `Option[]` | Choices for select, radio, checkbox and toggle fields. |
+ * | `api()` | `string` | Endpoint used to load options or lookups. |
+ * | `mode()` | `"edit" \| "view"` | Renders the control or the read-only viewer. |
+ * | `visible()` | `boolean` | Whether the field is rendered at all. |
+ * | `loading()` | `boolean` | Shows the field's own loading state. |
+ * | `config` | `FieldConfig` | Per-type configuration — see {@link FieldConfig}. |
+ * | `validation` | `any` | Synchronous validation rules. |
+ * | `asyncValidation` | `FieldAsyncValidation` | Remote validation rules. |
+ * | `events` | `FieldEvent[]` | Cross-field reactions (show, hide, set value, …). |
+ * | `children` | `IssField[]` | Nested fields, used by table and group fields. |
+ * | `value` / `defaultValue` | `string` | Initial and fallback raw values. |
+ * | `jsonValue` | `any` | Initial resolved value for controls with a rich payload. |
+ * | `ctrlValue()` | `string \| null` | Live raw value of the control. |
+ * | `ctrlJsonValue()` | `any` | Live resolved value (selected options, files, users, …). |
+ * | `response()` / `apiResponse` | `any` | Latest payload returned for this field. |
+ */
 class IssField {
     id;
     name;
@@ -5162,38 +5835,61 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
             args: [{ providedIn: "root" }]
         }] });
 
+/**
+ * Maps a field's `type` to the `iss-field-*` component that renders it.
+ *
+ * The outlet looks the field up here and lazy-loads the component, so a `type` that is not
+ * a key of this object renders nothing. Hover a field class for the `config` keys it reads.
+ *
+ * | `type` | Component | Control | Renders |
+ * | --- | --- | --- | --- |
+ * | `text_input` | `InputField` | `iss-ctrl-input` | Single line text, number, email, password. |
+ * | `textarea` | `TextareaField` | `iss-ctrl-textarea` | Multi line free text. |
+ * | `dropdown_list` | `SelectField` | `iss-ctrl-select` | Searchable single/multi select. |
+ * | `toggle_button` | `ToggleButtonField` | `iss-ctrl-toggle-button` | Options as a button group. |
+ * | `checkbox` | `CheckboxField` | `iss-ctrl-checkbox` | Multi choice checkbox list. |
+ * | `radio` | `RadioField` | `iss-ctrl-radio` | Single choice radio list. |
+ * | `date` | `DatePickerField` | `iss-ctrl-date-picker` | A single date. |
+ * | `time` | `TimePickerField` | `iss-ctrl-time-picker` | A time of day. |
+ * | `datetime` | `DatetimePickerField` | `iss-ctrl-datetime-picker` | Date and time together. |
+ * | `date_range` | `DateRangePickerField` | `iss-ctrl-date-range-picker` | A start/end date range. |
+ * | `attachment` | `FilePickerField` | `iss-ctrl-file-picker` | File upload. |
+ * | `userPicker` | `UserPickerField` | `iss-ctrl-select` | Employee lookup. |
+ * | `vehicle_plate` | `PlateField` | `iss-ctrl-plate-number` | Saudi vehicle plate. |
+ * | `enrichment` | `NoteField` | — | Read-only explanatory text. |
+ * | `mobile` | `MobileField` | `iss-ctrl-mobile` | International phone number. |
+ * | `table` | `TableField` | `iss-ctrl-table` | Repeatable rows built from `children`. |
+ * | `chips` | `ChipsField` | `iss-ctrl-chips` | Free text as removable chips. |
+ * | `switch` | `SlideToggleField` | `iss-ctrl-slide-toggle` | Boolean on/off switch. |
+ */
 const COMPONENTS = {
-    date: () => Promise.resolve().then(function () { return datePicker_field; }).then((c) => c.DatePickerField),
-    datetime: () => Promise.resolve().then(function () { return datetimePicker_field; }).then((c) => c.DatetimePickerField),
-    dateRange: () => Promise.resolve().then(function () { return dateRangePicker_field; }).then((c) => c.DateRangePickerField),
-    date_range: () => Promise.resolve().then(function () { return dateRangePicker_field; }).then((c) => c.DateRangePickerField),
-    select: () => Promise.resolve().then(function () { return select_field; }).then((c) => c.SelectField),
-    input: () => Promise.resolve().then(function () { return input_field; }).then((c) => c.InputField),
-    text: () => Promise.resolve().then(function () { return input_field; }).then((c) => c.InputField),
+    text_input: () => Promise.resolve().then(function () { return input_field; }).then((c) => c.InputField),
+    textarea: () => Promise.resolve().then(function () { return textarea_field; }).then((c) => c.TextareaField),
+    dropdown_list: () => Promise.resolve().then(function () { return select_field; }).then((c) => c.SelectField),
+    toggle_button: () => Promise.resolve().then(function () { return toggleButton_field; }).then((c) => c.ToggleButtonField),
     checkbox: () => Promise.resolve().then(function () { return checkbox_field; }).then((c) => c.CheckboxField),
-    file: () => Promise.resolve().then(function () { return filePicker_field; }).then((c) => c.FilePickerField),
-    file2: () => Promise.resolve().then(function () { return filePicker_field; }).then((c) => c.FilePickerField),
     radio: () => Promise.resolve().then(function () { return radio_field; }).then((c) => c.RadioField),
-    textarea: () => Promise.resolve().then(function () { return textarea_field; }).then((c) => c.TextareaField),
-    chips: () => Promise.resolve().then(function () { return chips_field; }).then((c) => c.ChipsField),
-    plate: () => Promise.resolve().then(function () { return plate_field; }).then((c) => c.PlateField),
-    note: () => import('./iss-ctrl-note.field-4uLl0oS_.mjs').then((c) => c.NoteField),
-    slideToggle: () => Promise.resolve().then(function () { return slideToggle_field; }).then((c) => c.SlideToggleField),
-    toggle: () => Promise.resolve().then(function () { return toggleButton_field; }).then((c) => c.ToggleButtonField),
+    date: () => Promise.resolve().then(function () { return datePicker_field; }).then((c) => c.DatePickerField),
     time: () => Promise.resolve().then(function () { return timePicker_field; }).then((c) => c.TimePickerField),
+    datetime: () => Promise.resolve().then(function () { return datetimePicker_field; }).then((c) => c.DatetimePickerField),
+    date_range: () => Promise.resolve().then(function () { return dateRangePicker_field; }).then((c) => c.DateRangePickerField),
+    attachment: () => Promise.resolve().then(function () { return filePicker_field; }).then((c) => c.FilePickerField),
+    userPicker: () => import('./iss-ctrl-user-picker.field-8Jb1325c.mjs').then((c) => c.UserPickerField),
+    vehicle_plate: () => Promise.resolve().then(function () { return plate_field; }).then((c) => c.PlateField),
+    enrichment: () => import('./iss-ctrl-note.field-C9cVaAz0.mjs').then((c) => c.NoteField),
     mobile: () => Promise.resolve().then(function () { return mobile_field; }).then((c) => c.MobileField),
-    table: () => import('./iss-ctrl-table.field-kPIwve-M.mjs').then((c) => c.TableField),
-    userPicker: () => import('./iss-ctrl-user-picker.field-l-0bW6lP.mjs').then((c) => c.UserPickerField),
-    userPicker2: () => import('./iss-ctrl-user-picker.field-l-0bW6lP.mjs').then((c) => c.UserPickerField),
+    table: () => import('./iss-ctrl-table.field-BP-HMKO3.mjs').then((c) => c.TableField),
+    chips: () => Promise.resolve().then(function () { return chips_field; }).then((c) => c.ChipsField),
+    switch: () => Promise.resolve().then(function () { return slideToggle_field; }).then((c) => c.SlideToggleField),
 };
 
 const SERVICES = {
-    setValue: () => import('./iss-ctrl-set-value-event-BbEYFBe3.mjs').then((s) => s.SetValueEvent),
+    setValue: () => import('./iss-ctrl-set-value-event-CrpzRR6X.mjs').then((s) => s.SetValueEvent),
     show: () => import('./iss-ctrl-show-event-BcRCwAfo.mjs').then((s) => s.ShowEvent),
-    load: () => import('./iss-ctrl-load-value-event-DThpI9BA.mjs').then((s) => s.LoadValueEvent),
-    loadOptions: () => import('./iss-ctrl-load-options-event-ClX9TiiD.mjs').then((s) => s.LoadOptionsEvent),
-    triggerBasedOnJsonValue: () => import('./iss-ctrl-trigger-based-on-json-value-DuLD4SOS.mjs').then((s) => s.TriggerBasedOnJsonValue),
-    replaceApiKeyDefaultImpl: () => import('./iss-ctrl-replace-api-keys-BQL9zimJ.mjs').then((s) => s.ReplaceApiKeys),
+    load: () => import('./iss-ctrl-load-value-event-CDAKsE_O.mjs').then((s) => s.LoadValueEvent),
+    loadOptions: () => import('./iss-ctrl-load-options-event-ClQPHNBO.mjs').then((s) => s.LoadOptionsEvent),
+    triggerBasedOnJsonValue: () => import('./iss-ctrl-trigger-based-on-json-value-DS4TR38v.mjs').then((s) => s.TriggerBasedOnJsonValue),
+    replaceApiKeyDefaultImpl: () => import('./iss-ctrl-replace-api-keys-CvhCKvNB.mjs').then((s) => s.ReplaceApiKeys),
 };
 
 // Read-only counterpart of COMPONENTS: the component used to render a field's value
@@ -5308,7 +6004,7 @@ class Outlet {
     #formEngine = inject(FormEngine);
     #loader = inject(Loader);
     #effectRef = effect((onCleanup) => {
-        // Dynamic imports cannot be cancelled, but an old result must never replace
+        // Dynamic imports cannot be canceled, but an old result must never replace
         // the components produced for a newer fields input (or a destroyed outlet).
         let active = true;
         onCleanup(() => {
@@ -5738,14 +6434,49 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
             args: [{ providedIn: "root" }]
         }] });
 
+/**
+ * Base class for every `iss-field-*` field.
+ *
+ * A field is the form-engine layer around a control: it reads its whole configuration from
+ * the injected {@link IssField} (label, options, config, validation, events), registers its
+ * `FormControl` on the parent `FormGroup` on init and removes it again on destroy, and
+ * switches between the control (`mode() === "edit"`) and the viewer (`mode() === "view"`).
+ *
+ * ### Inputs
+ * | Property | Type | Description |
+ * | --- | --- | --- |
+ * | `issField` | `IssField` | **Required.** The field definition; also provided through the `FIELD_DATA` token. |
+ * | `formReady` | `boolean \| undefined` | Set by the outlet once the whole form exists; gates event wiring. |
+ *
+ * ### Properties available on `field`
+ * `name` · `type` · `base` · `label()` · `hint()` · `options()` · `api()` · `mode()` ·
+ * `visible()` · `loading()` · `value` · `jsonValue` · `defaultValue` · `ctrlValue()` ·
+ * `ctrlJsonValue()` · `events` · `validation` · `asyncValidation` · `children` ·
+ * `response()` · `config` — see {@link IssField} and {@link FieldConfig}.
+ *
+ * Fields are not used directly in templates; the outlet resolves them from the field `type`
+ * through the `COMPONENTS` index.
+ */
 class FieldBase {
+    /**
+     * The field definition rendered by this component. Required.
+     */
     issField = input.required(...(ngDevMode ? [{ debugName: "issField" }] : /* istanbul ignore next */ []));
+    /**
+     * Set by the outlet once every field is registered; field events start only after it turns true.
+     */
     formReady = input(...(ngDevMode ? [undefined, { debugName: "formReady" }] : /* istanbul ignore next */ []));
+    /**
+     * The {@link IssField} for this instance, injected through the `FIELD_DATA` token.
+     */
     field = inject(FIELD_DATA);
     parentFormGroup = inject(ControlContainer);
     formEngine = inject(FormEngine);
     eventHandler = inject(EventHandler);
     destroyRef = inject(DestroyRef);
+    /**
+     * The `FormControl` this field registers on the parent form under `field.name`.
+     */
     ctrl = new FormControl(null);
     ctrlValueChange = toSignal(this.ctrl.valueChanges, { initialValue: this.ctrl.getRawValue() });
     #valueChangeEffectRef = effect(() => {
@@ -5852,6 +6583,34 @@ var input_viewer = /*#__PURE__*/Object.freeze({
     InputViewer: InputViewer
 });
 
+/**
+ * `<iss-field-input>` — single line text, number, email or password entry.
+ *
+ * Rendered by the outlet for fields of type `text_input`. In `edit` mode it renders
+ * {@link InputControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `type` | `string` | Native input type — `text`, `number`, `email`, `password`, … |
+ * | `placeholder` | `string` | Placeholder shown while empty. |
+ * | `min` | `number` | Minimum numeric value. |
+ * | `max` | `number` | Maximum numeric value. |
+ * | `minLength` | `number` | Minimum number of characters. |
+ * | `maxLength` | `number` | Maximum number of characters. |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * @example
+ * ```json
+ * { "name": "email", "type": "text_input", "label": "Email", "config": { "type": "email", "maxLength": 120 } }
+ * ```
+ */
 class InputField extends FieldBase {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: InputField, deps: null, target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: InputField, isStandalone: true, selector: "iss-field-input", usesInheritance: true, ngImport: i0, template: `
@@ -5862,8 +6621,8 @@ class InputField extends FieldBase {
           [type]="field.config.type() ?? ''"
           [placeholder]="field.config.placeholder() ?? ''"
           [min]="field.config.min() ?? null"
-          [max]="field.config.max() ?? null"
-          [readonly]="field.config.readonly() ?? false"
+          [max]="field.config.max() ?? null"
+          [readonly]="field.config.readonly() ?? false"
           [minLength]="field.config.minLength() ?? null"
           [maxLength]="field.config.maxLength() ?? null"
         >
@@ -5895,8 +6654,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
           [type]="field.config.type() ?? ''"
           [placeholder]="field.config.placeholder() ?? ''"
           [min]="field.config.min() ?? null"
-          [max]="field.config.max() ?? null"
-          [readonly]="field.config.readonly() ?? false"
+          [max]="field.config.max() ?? null"
+          [readonly]="field.config.readonly() ?? false"
           [minLength]="field.config.minLength() ?? null"
           [maxLength]="field.config.maxLength() ?? null"
         >
@@ -5937,12 +6696,36 @@ var textarea_viewer = /*#__PURE__*/Object.freeze({
     TextareaViewer: TextareaViewer
 });
 
+/**
+ * `<iss-field-textarea>` — multi line free text.
+ *
+ * Rendered by the outlet for fields of type `textarea`. In `edit` mode it renders
+ * {@link TextareaControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `minLength` | `number` | Minimum number of characters. |
+ * | `maxLength` | `number` | Maximum number of characters. |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * @example
+ * ```json
+ * { "name": "notes", "type": "textarea", "label": "Notes", "config": { "maxLength": 500 } }
+ * ```
+ */
 class TextareaField extends FieldBase {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: TextareaField, deps: null, target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: TextareaField, isStandalone: true, selector: "iss-field-textarea", usesInheritance: true, ngImport: i0, template: `
     @if (field.visible()) {
       @if (field.mode() === "edit") {
-        <iss-ctrl-textarea [formControlName]="field.name" [minLength]="field.config.minLength() ?? null" [maxLength]="field.config.maxLength() ?? null" [readonly]="field.config.readonly() ?? false">
+        <iss-ctrl-textarea [formControlName]="field.name" [minLength]="field.config.minLength() ?? null" [maxLength]="field.config.maxLength() ?? null" [readonly]="field.config.readonly() ?? false">
           <label>{{ field.label() }}</label>
         </iss-ctrl-textarea>
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
@@ -5966,7 +6749,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                     template: `
     @if (field.visible()) {
       @if (field.mode() === "edit") {
-        <iss-ctrl-textarea [formControlName]="field.name" [minLength]="field.config.minLength() ?? null" [maxLength]="field.config.maxLength() ?? null" [readonly]="field.config.readonly() ?? false">
+        <iss-ctrl-textarea [formControlName]="field.name" [minLength]="field.config.minLength() ?? null" [maxLength]="field.config.maxLength() ?? null" [readonly]="field.config.readonly() ?? false">
           <label>{{ field.label() }}</label>
         </iss-ctrl-textarea>
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
@@ -6019,12 +6802,34 @@ var chips_viewer = /*#__PURE__*/Object.freeze({
     ChipsViewer: ChipsViewer
 });
 
+/**
+ * `<iss-field-chips>` — free text entered as removable chips.
+ *
+ * Rendered by the outlet for fields of type `chips`. In `edit` mode it renders
+ * {@link ChipsControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * @example
+ * ```json
+ * { "name": "tags", "type": "chips", "label": "Tags" }
+ * ```
+ */
 class ChipsField extends FieldBase {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: ChipsField, deps: null, target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: ChipsField, isStandalone: true, selector: "iss-field-chips", usesInheritance: true, ngImport: i0, template: `
     @if (field.visible()) {
       @if (field.mode() === "edit") {
-        <iss-ctrl-chips [formControlName]="field.name" [readonly]="field.config.readonly() ?? false"><label>{{ field.label() }}</label></iss-ctrl-chips>
+        <iss-ctrl-chips [formControlName]="field.name" [readonly]="field.config.readonly() ?? false"><label>{{ field.label() }}</label></iss-ctrl-chips>
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
       } @else {
         <iss-viewer-chips [field]="field"/>
@@ -6046,7 +6851,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                     template: `
     @if (field.visible()) {
       @if (field.mode() === "edit") {
-        <iss-ctrl-chips [formControlName]="field.name" [readonly]="field.config.readonly() ?? false"><label>{{ field.label() }}</label></iss-ctrl-chips>
+        <iss-ctrl-chips [formControlName]="field.name" [readonly]="field.config.readonly() ?? false"><label>{{ field.label() }}</label></iss-ctrl-chips>
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
       } @else {
         <iss-viewer-chips [field]="field"/>
@@ -6090,6 +6895,29 @@ var radio_viewer = /*#__PURE__*/Object.freeze({
     RadioViewer: RadioViewer
 });
 
+/**
+ * `<iss-field-radio>` — one choice out of a fixed set of options.
+ *
+ * Rendered by the outlet for fields of type `radio`. In `edit` mode it renders
+ * {@link RadioControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `hideLabel` | `boolean` | Hides the field label. |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()` · `options()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * @example
+ * ```json
+ * { "name": "gender", "type": "radio", "label": "Gender", "options": [{ "value": "m", "label": "Male" }] }
+ * ```
+ */
 class RadioField extends FieldBase {
     onChange($event) {
         this.field.ctrlJsonValue.set($event);
@@ -6103,7 +6931,7 @@ class RadioField extends FieldBase {
         }
 
         @if (field.mode() === "edit") {
-          <iss-ctrl-radio [formControlName]="field.name" [options]="field.options()" [readonly]="field.config.readonly() ?? false" (onChange)="onChange($event)"/>
+          <iss-ctrl-radio [formControlName]="field.name" [options]="field.options()" [readonly]="field.config.readonly() ?? false" (onChange)="onChange($event)"/>
           <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
         } @else {
           <iss-viewer-radio [field]="field"/>
@@ -6132,7 +6960,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
         }
 
         @if (field.mode() === "edit") {
-          <iss-ctrl-radio [formControlName]="field.name" [options]="field.options()" [readonly]="field.config.readonly() ?? false" (onChange)="onChange($event)"/>
+          <iss-ctrl-radio [formControlName]="field.name" [options]="field.options()" [readonly]="field.config.readonly() ?? false" (onChange)="onChange($event)"/>
           <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
         } @else {
           <iss-viewer-radio [field]="field"/>
@@ -6177,6 +7005,32 @@ var select_viewer = /*#__PURE__*/Object.freeze({
     SelectViewer: SelectViewer
 });
 
+/**
+ * `<iss-field-select>` — single or multiple selection from a dropdown.
+ *
+ * Rendered by the outlet for fields of type `dropdown_list`. In `edit` mode it renders
+ * {@link SelectControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `multiple` | `boolean` | Allows selecting more than one option. |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()` · `options()` · `ctrlJsonValue()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * The raw form value holds the selected option values; the resolved options are written
+ * back to `field.ctrlJsonValue`.
+ *
+ * @example
+ * ```json
+ * { "name": "city", "type": "dropdown_list", "label": "City", "options": [{ "value": "1", "label": "Riyadh" }] }
+ * ```
+ */
 class SelectField extends FieldBase {
     onChange($event) {
         this.field.ctrlJsonValue.set($event);
@@ -6185,7 +7039,7 @@ class SelectField extends FieldBase {
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: SelectField, isStandalone: true, selector: "iss-field-select", usesInheritance: true, ngImport: i0, template: `
     @if (field.visible()) {
       @if (field.mode() === "edit") {
-        <iss-ctrl-select [formControlName]="field.name" [options]="field.options()" [multiple]="field.config.multiple()" [readonly]="field.config.readonly() ?? false" (onChange)="onChange($event)">
+        <iss-ctrl-select [formControlName]="field.name" [options]="field.options()" [multiple]="field.config.multiple()" [readonly]="field.config.readonly() ?? false" (onChange)="onChange($event)">
           <label>{{ field.label() }}</label>
         </iss-ctrl-select>
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
@@ -6209,7 +7063,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                     template: `
     @if (field.visible()) {
       @if (field.mode() === "edit") {
-        <iss-ctrl-select [formControlName]="field.name" [options]="field.options()" [multiple]="field.config.multiple()" [readonly]="field.config.readonly() ?? false" (onChange)="onChange($event)">
+        <iss-ctrl-select [formControlName]="field.name" [options]="field.options()" [multiple]="field.config.multiple()" [readonly]="field.config.readonly() ?? false" (onChange)="onChange($event)">
           <label>{{ field.label() }}</label>
         </iss-ctrl-select>
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
@@ -6247,6 +7101,28 @@ var mobile_viewer = /*#__PURE__*/Object.freeze({
     MobileViewer: MobileViewer
 });
 
+/**
+ * `<iss-field-mobile>` — an international phone number with a country selector.
+ *
+ * Rendered by the outlet for fields of the type `mobile`. In `edit` mode it renders
+ * {@link MobileControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()`
+ *
+ * Every field also honors `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * @example
+ * ```json
+ * { "name": "mobile", "type": "mobile", "label": "Mobile" }
+ * ```
+ */
 class MobileField extends FieldBase {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: MobileField, deps: null, target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: MobileField, isStandalone: true, selector: "iss-field-mobile", usesInheritance: true, ngImport: i0, template: `
@@ -6320,6 +7196,29 @@ var checkbox_viewer = /*#__PURE__*/Object.freeze({
     CheckboxViewer: CheckboxViewer
 });
 
+/**
+ * `<iss-field-checkbox>` — a list of checkboxes over a fixed set of options.
+ *
+ * Rendered by the outlet for fields of type `checkbox`. In `edit` mode it renders
+ * {@link CheckboxControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `hideLabel` | `boolean` | Hides the field label. |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()` · `options()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * @example
+ * ```json
+ * { "name": "days", "type": "checkbox", "label": "Days", "options": [{ "value": "sun", "label": "Sunday" }] }
+ * ```
+ */
 class CheckboxField extends FieldBase {
     updateField($event) {
         this.field.ctrlJsonValue.set($event);
@@ -6328,7 +7227,7 @@ class CheckboxField extends FieldBase {
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: CheckboxField, isStandalone: true, selector: "iss-field-checkbox", usesInheritance: true, ngImport: i0, template: `
     @if (field.visible()) {
       @if (field.mode() === "edit") {
-        <iss-ctrl-checkbox [formControlName]="field.name" [options]="field.options()" [readonly]="field.config.readonly() ?? false" (onChange)="updateField($event)">
+        <iss-ctrl-checkbox [formControlName]="field.name" [options]="field.options()" [readonly]="field.config.readonly() ?? false" (onChange)="updateField($event)">
           @if (!field.config.hideLabel()) {
             <label>{{ field.label() }}</label>
           }
@@ -6354,7 +7253,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                     template: `
     @if (field.visible()) {
       @if (field.mode() === "edit") {
-        <iss-ctrl-checkbox [formControlName]="field.name" [options]="field.options()" [readonly]="field.config.readonly() ?? false" (onChange)="updateField($event)">
+        <iss-ctrl-checkbox [formControlName]="field.name" [options]="field.options()" [readonly]="field.config.readonly() ?? false" (onChange)="updateField($event)">
           @if (!field.config.hideLabel()) {
             <label>{{ field.label() }}</label>
           }
@@ -6402,6 +7301,30 @@ var toggleButton_viewer = /*#__PURE__*/Object.freeze({
     ToggleButtonViewer: ToggleButtonViewer
 });
 
+/**
+ * `<iss-field-toggle-button>` — options rendered as a button group.
+ *
+ * Rendered by the outlet for fields of type `toggle_button`. In `edit` mode it renders
+ * {@link ToggleButtonControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `multiple` | `boolean` | Allows more than one active button. |
+ * | `hideLabel` | `boolean` | Hides the field label. |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()` · `options()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * @example
+ * ```json
+ * { "name": "priority", "type": "toggle_button", "label": "Priority", "options": [{ "value": "high", "label": "High" }] }
+ * ```
+ */
 class ToggleButtonField extends FieldBase {
     onChange($event) {
         this.field.ctrlJsonValue.set($event);
@@ -6415,9 +7338,9 @@ class ToggleButtonField extends FieldBase {
       @if (field.mode() === "edit") {
         <iss-ctrl-toggle-button
           [formControlName]="field.name"
-          [options]="field.options()"
-          [multiple]="field.config.multiple()"
-          [readonly]="field.config.readonly() ?? false"
+          [options]="field.options()"
+          [multiple]="field.config.multiple()"
+          [readonly]="field.config.readonly() ?? false"
           (onChange)="onChange($event)"
         />
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
@@ -6447,9 +7370,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
       @if (field.mode() === "edit") {
         <iss-ctrl-toggle-button
           [formControlName]="field.name"
-          [options]="field.options()"
-          [multiple]="field.config.multiple()"
-          [readonly]="field.config.readonly() ?? false"
+          [options]="field.options()"
+          [multiple]="field.config.multiple()"
+          [readonly]="field.config.readonly() ?? false"
           (onChange)="onChange($event)"
         />
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
@@ -6499,6 +7422,29 @@ var slideToggle_viewer = /*#__PURE__*/Object.freeze({
     SlideToggleViewer: SlideToggleViewer
 });
 
+/**
+ * `<iss-field-slide-toggle>` — an on/off switch for a boolean value.
+ *
+ * Rendered by the outlet for fields of type `switch`. In `edit` mode it renders
+ * {@link SlideToggleControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `hideLabel` | `boolean` | Hides the field label. |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * @example
+ * ```json
+ * { "name": "active", "type": "switch", "label": "Active" }
+ * ```
+ */
 class SlideToggleField extends FieldBase {
     onChange($event) {
         this.field.ctrlJsonValue.set($event);
@@ -6511,7 +7457,7 @@ class SlideToggleField extends FieldBase {
       }
 
       @if (field.mode() === "edit") {
-        <iss-ctrl-slide-toggle [formControlName]="field.name" [readonly]="field.config.readonly() ?? false" (onChange)="onChange($event)"/>
+        <iss-ctrl-slide-toggle [formControlName]="field.name" [readonly]="field.config.readonly() ?? false" (onChange)="onChange($event)"/>
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
       } @else {
         <iss-viewer-slide-toggle [field]="field"/>
@@ -6532,7 +7478,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
       }
 
       @if (field.mode() === "edit") {
-        <iss-ctrl-slide-toggle [formControlName]="field.name" [readonly]="field.config.readonly() ?? false" (onChange)="onChange($event)"/>
+        <iss-ctrl-slide-toggle [formControlName]="field.name" [readonly]="field.config.readonly() ?? false" (onChange)="onChange($event)"/>
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
       } @else {
         <iss-viewer-slide-toggle [field]="field"/>
@@ -6724,6 +7670,29 @@ var plate_viewer = /*#__PURE__*/Object.freeze({
     PlateViewer: PlateViewer
 });
 
+/**
+ * `<iss-field-plate-number>` — a Saudi vehicle plate in Arabic and English.
+ *
+ * Rendered by the outlet for fields of type `vehicle_plate`. In `edit` mode it renders
+ * {@link PlateControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `hideLabel` | `boolean` | Hides the field label. |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * @example
+ * ```json
+ * { "name": "plate", "type": "vehicle_plate", "label": "Plate number" }
+ * ```
+ */
 class PlateField extends FieldBase {
     updateField($event) {
         this.field.ctrlJsonValue.set($event);
@@ -6736,7 +7705,7 @@ class PlateField extends FieldBase {
       }
 
       @if (field.mode() === "edit") {
-        <iss-ctrl-plate-number [formControlName]="field.name" [readonly]="field.config.readonly() ?? false" (onChange)="updateField($event)"/>
+        <iss-ctrl-plate-number [formControlName]="field.name" [readonly]="field.config.readonly() ?? false" (onChange)="updateField($event)"/>
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
       } @else {
         <iss-viewer-plate [field]="field"/>
@@ -6763,7 +7732,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
       }
 
       @if (field.mode() === "edit") {
-        <iss-ctrl-plate-number [formControlName]="field.name" [readonly]="field.config.readonly() ?? false" (onChange)="updateField($event)"/>
+        <iss-ctrl-plate-number [formControlName]="field.name" [readonly]="field.config.readonly() ?? false" (onChange)="updateField($event)"/>
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
       } @else {
         <iss-viewer-plate [field]="field"/>
@@ -6997,6 +7966,36 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
             args: [{ providedIn: "root" }]
         }] });
 
+/**
+ * `<iss-field-file-picker>` — attachment upload.
+ *
+ * Rendered by the outlet for fields of type `attachment`. In `edit` mode it renders
+ * {@link FilePickerControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `multiple` | `boolean` | Allows attaching more than one file. |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()` · `value` · `validation` · `ctrlJsonValue()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * The field uploads the picked files itself, stores the returned ids as the control value
+ * and keeps the resolved attachments in `field.ctrlJsonValue`.
+ *
+ * Accepted extensions come from the `fileType` **validation** rule, not from `config`; the
+ * `allowedFileSize`, `allowedFileTypes`, `minFilesCount`, `maxFilesCount`, `templateId` and
+ * `templateUrl` config keys exist on {@link FieldConfig} but are not read here yet.
+ *
+ * @example
+ * ```json
+ * { "name": "attachments", "type": "attachment", "label": "Attachments", "config": { "multiple": true }, "validation": { "fileType": ["pdf", "png"] } }
+ * ```
+ */
 class FilePickerField extends FieldBase {
     picker = new FormControl();
     fileHandlerService = inject(FileHandler);
@@ -7107,8 +8106,8 @@ class FilePickerField extends FieldBase {
           [formControl]="picker"
           [accept]="accept"
           (onChange)="captureFile($event)"
-          [multiple]="field.config.multiple()"
-          [readonly]="field.config.readonly() ?? false"
+          [multiple]="field.config.multiple()"
+          [readonly]="field.config.readonly() ?? false"
           [uploading]="uploading()"
           [uploadedFiles]="attachments()"
           [uploadingError]="uploadingError()"
@@ -7142,8 +8141,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
           [formControl]="picker"
           [accept]="accept"
           (onChange)="captureFile($event)"
-          [multiple]="field.config.multiple()"
-          [readonly]="field.config.readonly() ?? false"
+          [multiple]="field.config.multiple()"
+          [readonly]="field.config.readonly() ?? false"
           [uploading]="uploading()"
           [uploadedFiles]="attachments()"
           [uploadingError]="uploadingError()"
@@ -7183,6 +8182,28 @@ var timePicker_viewer = /*#__PURE__*/Object.freeze({
     TimePickerViewer: TimePickerViewer
 });
 
+/**
+ * `<iss-field-time-picker>` — a time of day, picked from a generated list.
+ *
+ * Rendered by the outlet for fields of type `time`. In `edit` mode it renders
+ * {@link TimePickerControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * @example
+ * ```json
+ * { "name": "startsAt", "type": "time", "label": "Starts at" }
+ * ```
+ */
 class TimePickerField extends FieldBase {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: TimePickerField, deps: null, target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: TimePickerField, isStandalone: true, selector: "iss-field-time-picker", usesInheritance: true, ngImport: i0, template: `
@@ -7250,12 +8271,36 @@ var datePicker_viewer = /*#__PURE__*/Object.freeze({
     DatePickerViewer: DatePickerViewer
 });
 
+/**
+ * `<iss-field-date-picker>` — a single date, picked from a calendar.
+ *
+ * Rendered by the outlet for fields of type `date`. In `edit` mode it renders
+ * {@link DatePickerControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `minDate` | `Date` | Earliest selectable date. |
+ * | `maxDate` | `Date` | Latest selectable date. |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * @example
+ * ```json
+ * { "name": "startsOn", "type": "date", "label": "Start date", "config": { "minDate": "2026-01-01" } }
+ * ```
+ */
 class DatePickerField extends FieldBase {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: DatePickerField, deps: null, target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: DatePickerField, isStandalone: true, selector: "iss-field-date-picker", usesInheritance: true, ngImport: i0, template: `
     @if (field.visible()) {
       @if (field.mode() === "edit") {
-        <iss-ctrl-date-picker [formControlName]="field.name" [minDate]="field.config.minDate() ?? null" [maxDate]="field.config.maxDate() ?? null" [readonly]="field.config.readonly() ?? false">
+        <iss-ctrl-date-picker [formControlName]="field.name" [minDate]="field.config.minDate() ?? null" [maxDate]="field.config.maxDate() ?? null" [readonly]="field.config.readonly() ?? false">
           <label>{{ field.label() }}</label>
         </iss-ctrl-date-picker>
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
@@ -7279,7 +8324,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
                     template: `
     @if (field.visible()) {
       @if (field.mode() === "edit") {
-        <iss-ctrl-date-picker [formControlName]="field.name" [minDate]="field.config.minDate() ?? null" [maxDate]="field.config.maxDate() ?? null" [readonly]="field.config.readonly() ?? false">
+        <iss-ctrl-date-picker [formControlName]="field.name" [minDate]="field.config.minDate() ?? null" [maxDate]="field.config.maxDate() ?? null" [readonly]="field.config.readonly() ?? false">
           <label>{{ field.label() }}</label>
         </iss-ctrl-date-picker>
         <iss-validation-message-viewer [errors]="ctrl.errors" [showMessage]="!ctrl.untouched"/>
@@ -7321,6 +8366,30 @@ var datetimePicker_viewer = /*#__PURE__*/Object.freeze({
     DatePickerTimeViewer: DatePickerTimeViewer
 });
 
+/**
+ * `<iss-field-datetime-picker>` — a date and a time in one field.
+ *
+ * Rendered by the outlet for fields of type `datetime`. In `edit` mode it renders
+ * {@link DatetimePickerControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `minDate` | `Date` | Earliest selectable date. |
+ * | `maxDate` | `Date` | Latest selectable date. |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * @example
+ * ```json
+ * { "name": "scheduledAt", "type": "datetime", "label": "Scheduled at" }
+ * ```
+ */
 class DatetimePickerField extends FieldBase {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: DatetimePickerField, deps: null, target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: DatetimePickerField, isStandalone: true, selector: "iss-field-datetime-picker", usesInheritance: true, ngImport: i0, template: `
@@ -7399,6 +8468,32 @@ var dateRangePicker_viewer = /*#__PURE__*/Object.freeze({
     DateRangePickerViewer: DateRangePickerViewer
 });
 
+/**
+ * `<iss-field-date-range-picker>` — a start and end date in one field.
+ *
+ * Rendered by the outlet for fields of type `date_range`. In `edit` mode it renders
+ * {@link DateRangePickerControl} plus the validation message; in `view` mode the matching viewer.
+ *
+ * ### Supported `config` keys
+ * | Key | Type | Description |
+ * | --- | --- | --- |
+ * | `minDate` | `Date` | Earliest selectable date. |
+ * | `maxDate` | `Date` | Latest selectable date. |
+ * | `readonly` | `boolean` | Shows the value but blocks interaction. |
+ *
+ * ### Other field members used
+ * `label()`
+ *
+ * Every field also honours `visible`, `mode`, `validation`, `asyncValidation` and
+ * `events` — see {@link IssField} for the full model and {@link FieldConfig} for all keys.
+ *
+ * A half-filled range is treated as no value at all.
+ *
+ * @example
+ * ```json
+ * { "name": "period", "type": "date_range", "label": "Period" }
+ * ```
+ */
 class DateRangePickerField extends FieldBase {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: DateRangePickerField, deps: null, target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: DateRangePickerField, isStandalone: true, selector: "iss-field-date-range-picker", usesInheritance: true, ngImport: i0, template: `
@@ -7756,5 +8851,5 @@ var time_validator = /*#__PURE__*/Object.freeze({
  * Generated bundle index. Do not edit.
  */
 
-export { PlateViewer as $, TimePickerField as A, DatePickerField as B, ControlBase as C, DatePickerControl as D, Employee as E, FieldBase as F, DatetimePickerField as G, HOST as H, IssField as I, DateRangePickerField as J, InputViewer as K, Loader as L, MobileControl as M, TextareaViewer as N, Outlet as O, PLACEHOLDER_REGEX as P, ChipsViewer as Q, RadioControl as R, SelectControl as S, TextareaControl as T, RadioViewer as U, VIEW_PROVIDER as V, SelectViewer as W, MobileViewer as X, CheckboxViewer as Y, ToggleButtonViewer as Z, SlideToggleViewer as _, ViewerBase as a, AttachmentViewer as a0, TimePickerViewer as a1, DatePickerViewer as a2, DatePickerTimeViewer as a3, DateRangePickerViewer as a4, DEFAULT_COUNTRY as a5, COUNTRIES as a6, DATE_FORMAT_ADAPTER as a7, DATETIME_FORMAT as a8, PLATE_LETTERS as a9, VALIDATION_MESSAGES as aa, COMPONENTS as ab, SERVICES as ac, VALIDATORS as ad, FIELD_DATA as ae, UI_LANGUAGE as af, ATTACHMENT_UPLOAD_URL as ag, ATTACHMENT_UPLOAD_RESPONSE_MAPPER as ah, ATTACHMENT_DOWNLOAD_URL as ai, USER_SEARCH_API as aj, HintsComponent as ak, Droppable as al, ArabicNumberPipe as am, FieldDataInjector as an, PlateLetterPipe as ao, SelectStatusPipe as ap, TranslatePipe as aq, FileHandler as ar, Phone as as, arrayFrom as at, formatFileSize as au, IssValidators as av, FileValidators as aw, TimeValidator as ax, FormEngine as b, ValidationMessageComponent as c, CheckboxControl as d, ChipsControl as e, DateRangePickerControl as f, getPropertyByPath as g, DatetimePickerControl as h, FilePickerControl as i, InputControl as j, PlateControl as k, SlideToggleControl as l, TimePickerControl as m, ToggleButtonControl as n, InputField as o, TextareaField as p, ChipsField as q, replacePlaceholders as r, RadioField as s, SelectField as t, MobileField as u, CheckboxField as v, ToggleButtonField as w, SlideToggleField as x, PlateField as y, FilePickerField as z };
-//# sourceMappingURL=iss-ctrl-iss-ctrl-hz0ibyPg.mjs.map
+export { PlateViewer as $, TimePickerField as A, DatePickerField as B, ControlBase as C, DatePickerControl as D, Employee as E, FieldBase as F, DatetimePickerField as G, HOST as H, IssField as I, DateRangePickerField as J, InputViewer as K, Loader as L, MobileControl as M, TextareaViewer as N, Outlet as O, PLACEHOLDER_REGEX as P, ChipsViewer as Q, RadioControl as R, SelectControl as S, TextareaControl as T, RadioViewer as U, VIEW_PROVIDER as V, SelectViewer as W, MobileViewer as X, CheckboxViewer as Y, ToggleButtonViewer as Z, SlideToggleViewer as _, ValidationMessageComponent as a, AttachmentViewer as a0, TimePickerViewer as a1, DatePickerViewer as a2, DatePickerTimeViewer as a3, DateRangePickerViewer as a4, DEFAULT_COUNTRY as a5, COUNTRIES as a6, DATE_FORMAT_ADAPTER as a7, DATETIME_FORMAT as a8, PLATE_LETTERS as a9, VALIDATION_MESSAGES as aa, COMPONENTS as ab, SERVICES as ac, VALIDATORS as ad, FIELD_DATA as ae, UI_LANGUAGE as af, ATTACHMENT_UPLOAD_URL as ag, ATTACHMENT_UPLOAD_RESPONSE_MAPPER as ah, ATTACHMENT_DOWNLOAD_URL as ai, USER_SEARCH_API as aj, HintsComponent as ak, Droppable as al, ArabicNumberPipe as am, FieldDataInjector as an, PlateLetterPipe as ao, SelectStatusPipe as ap, TranslatePipe as aq, FileHandler as ar, Phone as as, arrayFrom as at, formatFileSize as au, IssValidators as av, FileValidators as aw, TimeValidator as ax, ViewerBase as b, FormEngine as c, CheckboxControl as d, ChipsControl as e, DateRangePickerControl as f, getPropertyByPath as g, DatetimePickerControl as h, FilePickerControl as i, InputControl as j, PlateControl as k, SlideToggleControl as l, TimePickerControl as m, ToggleButtonControl as n, InputField as o, TextareaField as p, ChipsField as q, replacePlaceholders as r, RadioField as s, SelectField as t, MobileField as u, CheckboxField as v, ToggleButtonField as w, SlideToggleField as x, PlateField as y, FilePickerField as z };
+//# sourceMappingURL=iss-ctrl-iss-ctrl-BN9rcLt2.mjs.map