iss-ctrl 0.0.11 → 0.0.13

package/types/iss-ctrl.d.ts

@@ -20,19 +20,102 @@ interface Hint {
     align: HintAlignment;
 }
 
+/**
+ * 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>
+ * ```
+ */
 declare class ControlBase implements ControlValueAccessor, Validator {
+    /**
+     * Name of this control inside the surrounding `FormGroup`.
+     */
     formControlName: InputSignal<string>;
+    /**
+     * Lower bound forwarded to the underlying input — a number, or a date/time string.
+     */
     min: InputSignal<number | string | null>;
+    /**
+     * Upper bound forwarded to the underlying input — a number, or a date/time string.
+     */
     max: InputSignal<number | string | null>;
+    /**
+     * Minimum number of characters accepted by the underlying input.
+     */
     minLength: InputSignal<number | null>;
+    /**
+     * Maximum number of characters accepted by the underlying input.
+     */
     maxLength: InputSignal<number | null>;
+    /**
+     * 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: WritableSignal<boolean>;
+    /**
+     * Renders the current value but blocks every user interaction.
+     */
     readonly: InputSignal<boolean>;
+    /**
+     * Allows selecting/entering more than one value, on controls that support it.
+     */
     multiple: InputSignal<boolean | undefined>;
+    /**
+     * Placeholder text shown while the control has no value.
+     */
     placeholder: InputSignal<string>;
+    /**
+     * Helper messages rendered beneath the field. See {@link Hint}.
+     */
     hints: InputSignal<Hint[]>;
+    /**
+     * Extra CSS class names applied to the control host.
+     */
     className: InputSignal<string | null>;
+    /**
+     * Whether the user has interacted with the control. Owned by the control, not an input.
+     */
     touched: WritableSignal<boolean>;
+    /**
+     * Emits the committed value after every change.
+     */
     onChange: OutputEmitterRef<any>;
     protected ctrl: FormControl;
     registerOnChange(fn: () => void): void;
@@ -50,9 +133,36 @@ declare class ControlBase implements ControlValueAccessor, Validator {
     static ɵcmp: i0.ɵɵComponentDeclaration<ControlBase, "ng-component", never, { "formControlName": { "alias": "formControlName"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "minLength": { "alias": "minLength"; "required": false; "isSignal": true; }; "maxLength": { "alias": "maxLength"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "hints": { "alias": "hints"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; }, { "onChange": "onChange"; }, never, never, true, never>;
 }
 
+/**
+ * `<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-*`.
+ */
 declare class CheckboxControl extends ControlBase {
     #private;
+    /**
+     * Selectable choices, each a `{ value, label }` pair. Required.
+     */
     options: InputSignal<Option[]>;
+    /**
+     * Currently checked options, keyed by value. Internal state, not an input.
+     */
     selectedOptions: WritableSignal<Map<string, Option>>;
     writeValue(value: string | null): void;
     addToSelectedOptionsMap(option: Map<string, Option>): void;
@@ -63,8 +173,32 @@ declare class CheckboxControl extends ControlBase {
     static ɵcmp: i0.ɵɵComponentDeclaration<CheckboxControl, "iss-ctrl-checkbox", never, { "options": { "alias": "options"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * `<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.
+ */
 declare class ChipsControl extends ControlBase {
     #private;
+    /**
+     * The chips currently rendered. Internal state, not an input.
+     */
     readonly keywords: WritableSignal<string[]>;
     writeValue(value: string | null): void;
     remove(keyword: string): void;
@@ -73,9 +207,43 @@ declare class ChipsControl extends ControlBase {
     static ɵcmp: i0.ɵɵComponentDeclaration<ChipsControl, "iss-ctrl-chips", never, {}, {}, never, ["label"], true, never>;
 }
 
+/**
+ * `<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.
+ */
 declare class DatePickerControl extends ControlBase implements Validator {
+    /**
+     * Week days that cannot be selected — `0` is Sunday through `6` for Saturday.
+     */
     disabledDays: InputSignal<number[]>;
+    /**
+     * Earliest selectable date.
+     */
     minDate: InputSignal<Date | null>;
+    /**
+     * Latest selectable date.
+     */
     maxDate: InputSignal<Date | null>;
     clear(event: MouseEvent): void;
     protected calendarDaysFilter: (d: Date | null) => boolean;
@@ -91,12 +259,56 @@ interface DateRangeEmission {
     end: string;
 }
 
+/**
+ * `<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.
+ */
 declare class DateRangePickerControl extends ControlBase implements OnInit, OnDestroy {
     #private;
+    /**
+     * Week days that cannot be selected — `0` is Sunday through `6` for Saturday.
+     */
     disabledDays: InputSignal<number[]>;
+    /**
+     * Earliest selectable date.
+     */
     minDate: InputSignal<Date | null>;
+    /**
+     * Latest selectable date.
+     */
     maxDate: InputSignal<Date | null>;
+    /**
+     * Emits the selected range as an object, or `null` while the range is incomplete.
+     */
     onDateRangeObjectChange: OutputEmitterRef<DateRangeEmission | null>;
+    /**
+     * The `start`/`end` form group backing the range input. Internal state.
+     */
     readonly range: FormGroup;
     ngOnInit(): void;
     setDisabledState(isDisabled: boolean): void;
@@ -109,13 +321,55 @@ declare class DateRangePickerControl extends ControlBase implements OnInit, OnDe
     static ɵcmp: i0.ɵɵComponentDeclaration<DateRangePickerControl, "iss-ctrl-date-range-picker", never, { "disabledDays": { "alias": "disabledDays"; "required": false; "isSignal": true; }; "minDate": { "alias": "minDate"; "required": false; "isSignal": true; }; "maxDate": { "alias": "maxDate"; "required": false; "isSignal": true; }; }, { "onDateRangeObjectChange": "onDateRangeObjectChange"; }, never, ["label"], true, never>;
 }
 
+/**
+ * `<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.
+ */
 declare class DatetimePickerControl extends ControlBase {
     #private;
     datetimeForm: FormGroup;
+    /**
+     * Week days that cannot be selected — `0` is Sunday through `6` for Saturday.
+     */
     disabledDays: InputSignal<number[]>;
+    /**
+     * Earliest selectable date.
+     */
     minDate: InputSignal<Date | null>;
+    /**
+     * Latest selectable date.
+     */
     maxDate: InputSignal<Date | null>;
+    /**
+     * Earliest selectable time of day, as `HH:mm`.
+     */
     minTime: InputSignal<string | null>;
+    /**
+     * Latest selectable time of day, as `HH:mm`.
+     */
     maxTime: InputSignal<string | null>;
     setDisabledState(isDisabled: boolean): void;
     emit(): void;
@@ -141,13 +395,63 @@ interface IssFile {
     file?: File;
 }
 
+/**
+ * `<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-*`.
+ */
 declare class FilePickerControl extends ControlBase implements OnDestroy {
     #private;
+    /**
+     * Accepted extensions or MIME types, passed straight to the native file input.
+     */
     accept: InputSignal<string | undefined>;
+    /**
+     * Shows the download action on each listed attachment.
+     */
     showDownloadButton: InputSignal<boolean>;
+    /**
+     * Shows the remove action on each listed attachment.
+     */
     showDeleteButton: InputSignal<boolean>;
+    /**
+     * Renders the upload-in-progress state; set by the host that performs the upload.
+     */
     uploading: InputSignal<boolean>;
+    /**
+     * Attachments already stored on the server, merged into the rendered list.
+     */
     uploadedFiles: InputSignal<IssAttachment[]>;
+    /**
+     * Error message shown on the attachment whose upload failed.
+     */
     uploadingError: InputSignal<string | undefined>;
     readonly filesValue: Signal<any>;
     protected attachments: WritableSignal<IssFile[]>;
@@ -160,14 +464,68 @@ declare class FilePickerControl extends ControlBase implements OnDestroy {
     static ɵcmp: i0.ɵɵComponentDeclaration<FilePickerControl, "iss-ctrl-file-picker", never, { "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "showDownloadButton": { "alias": "showDownloadButton"; "required": false; "isSignal": true; }; "showDeleteButton": { "alias": "showDeleteButton"; "required": false; "isSignal": true; }; "uploading": { "alias": "uploading"; "required": false; "isSignal": true; }; "uploadedFiles": { "alias": "uploadedFiles"; "required": false; "isSignal": true; }; "uploadingError": { "alias": "uploadingError"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * `<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.
+ */
 declare class InputControl extends ControlBase implements Validator, OnDestroy {
     #private;
+    /**
+     * Native input type — `text`, `number`, `email`, `password`, and so on.
+     */
     type: InputSignal<string>;
+    /**
+     * Icon name rendered before the value.
+     */
     prefixIcon: InputSignal<string>;
+    /**
+     * Static text rendered before the value.
+     */
     prefixText: InputSignal<string>;
+    /**
+     * Icon name rendered after the value.
+     */
     suffixIcon: InputSignal<string>;
+    /**
+     * Static text rendered after the value, a unit or currency for example.
+     */
     suffixText: InputSignal<string>;
+    /**
+     * Emits when the prefix affix is clicked.
+     */
     onPrefixClick: OutputEmitterRef<string>;
+    /**
+     * Emits when the suffix affix is clicked.
+     */
     onSuffixClick: OutputEmitterRef<string>;
     emitSuffixClick(): void;
     emitPrefixClick(): void;
@@ -211,11 +569,36 @@ declare class Phone {
     static ɵprov: i0.ɵɵInjectableDeclaration<Phone>;
 }
 
+/**
+ * `<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.
+ */
 declare class MobileControl extends ControlBase implements OnDestroy, Validator {
     #private;
     phoneService: Phone;
     isOpen: WritableSignal<boolean>;
     selectedCountry: WritableSignal<Country>;
+    /**
+     * ISO-2 country codes pinned to the top of the country list; the first one is preselected.
+     */
     preferredCountries: InputSignal<ISO2[]>;
     searchInput: FormControl;
     filteredCountries: Signal<Country[]>;
@@ -231,6 +614,26 @@ declare class MobileControl extends ControlBase implements OnDestroy, Validator
     static ɵcmp: i0.ɵɵComponentDeclaration<MobileControl, "iss-ctrl-mobile", never, { "preferredCountries": { "alias": "preferredCountries"; "required": false; "isSignal": true; }; }, {}, never, ["label"], true, never>;
 }
 
+/**
+ * `<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-*`.
+ */
 declare class PlateControl extends ControlBase {
     #private;
     numbersAr: i0.WritableSignal<string[]>;
@@ -250,7 +653,28 @@ declare class PlateControl extends ControlBase {
     static ɵcmp: i0.ɵɵComponentDeclaration<PlateControl, "iss-ctrl-plate-number", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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-*`.
+ */
 declare class RadioControl extends ControlBase {
+    /**
+     * Selectable choices, each a `{ value, label }` pair. Required.
+     */
     options: InputSignal<Option[]>;
     writeValue(value: string | null): void;
     onRadioChange(value: string): void;
@@ -258,14 +682,60 @@ declare class RadioControl extends ControlBase {
     static ɵcmp: i0.ɵɵComponentDeclaration<RadioControl, "iss-ctrl-radio", never, { "options": { "alias": "options"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * `<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.
+ */
 declare class SelectControl extends ControlBase implements OnDestroy {
     #private;
     selectedOptions: WritableSignal<Map<string, Option>>;
+    /**
+     * Selectable choices, each a `{ value, label }` pair. Required.
+     */
     options: InputSignal<Option[]>;
+    /**
+     * Maximum height of the open options panel, as a CSS length.
+     */
     height: InputSignal<string>;
     query: Signal<string>;
     readonly filteredOptions: Signal<Option[]>;
+    /**
+     * Shows the loading state inside the panel while options are being fetched.
+     */
     loading: InputSignal<boolean>;
+    /**
+     * Emits the search text so the host can load matching options.
+     */
     onQueryChange: OutputEmitterRef<string>;
     protected optionTemplate: any;
     protected cardViewerTemplate: any;
@@ -281,12 +751,46 @@ declare class SelectControl extends ControlBase implements OnDestroy {
     static ɵcmp: i0.ɵɵComponentDeclaration<SelectControl, "iss-ctrl-select", never, { "options": { "alias": "options"; "required": true; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; }, { "onQueryChange": "onQueryChange"; }, ["optionTemplate", "cardViewerTemplate"], ["label"], true, never>;
 }
 
+/**
+ * `<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-*`.
+ */
 declare class SlideToggleControl extends ControlBase {
     onSlideToggleChange(checked: boolean): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<SlideToggleControl, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<SlideToggleControl, "iss-ctrl-slide-toggle", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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.
+ */
 declare class TextareaControl extends ControlBase implements OnDestroy {
     #private;
     ngOnDestroy(): void;
@@ -294,10 +798,41 @@ declare class TextareaControl extends ControlBase implements OnDestroy {
     static ɵcmp: i0.ɵɵComponentDeclaration<TextareaControl, "iss-ctrl-textarea", never, {}, {}, never, ["label"], true, never>;
 }
 
+/**
+ * `<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.
+ */
 declare class TimePickerControl extends ControlBase {
     #private;
+    /**
+     * Step between the offered times, for example `"15min"` or `"30min"`.
+     */
     interval: InputSignal<string>;
+    /**
+     * Earliest offered time of day, as `HH:mm`.
+     */
     minTime: InputSignal<string | null>;
+    /**
+     * Latest offered time of day, as `HH:mm`.
+     */
     maxTime: InputSignal<string | null>;
     emit(evt: any): void;
     clear(event: MouseEvent): void;
@@ -306,8 +841,31 @@ declare class TimePickerControl extends ControlBase {
     static ɵcmp: i0.ɵɵComponentDeclaration<TimePickerControl, "iss-ctrl-time-picker", never, { "interval": { "alias": "interval"; "required": false; "isSignal": true; }; "minTime": { "alias": "minTime"; "required": false; "isSignal": true; }; "maxTime": { "alias": "maxTime"; "required": false; "isSignal": true; }; }, {}, never, ["label"], true, never>;
 }
 
+/**
+ * `<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-*`.
+ */
 declare class ToggleButtonControl extends ControlBase {
     #private;
+    /**
+     * Selectable choices, each a `{ value, label }` pair. Required.
+     */
     options: InputSignal<Option[]>;
     selectedOptions: WritableSignal<Map<string, Option>>;
     writeValue(value: string | null): void;
@@ -333,32 +891,131 @@ declare class FieldAsyncValidation {
     constructor(asyncValidation: any);
 }
 
+/**
+ * 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 } }
+ * ```
+ */
 declare class FieldConfig {
+    /**
+     * Native input type for `text_input` (`text`, `email`, `number`, `password`, …).
+     */
     type: WritableSignal<string | undefined>;
+    /**
+     * Disables the control; the underlying `FormControl` is disabled on init.
+     */
     disabled: WritableSignal<boolean | undefined>;
+    /**
+     * Shows the value but blocks interaction. Unlike `disabled`, the value is still submitted.
+     */
     readonly: WritableSignal<boolean | undefined>;
+    /**
+     * Placeholder text shown while the field is empty.
+     */
     placeholder: WritableSignal<string | undefined>;
+    /**
+     * Text rendered after the value (a unit or currency, for example).
+     */
     suffix: WritableSignal<string | undefined>;
+    /**
+     * Hides the field label without removing it from the accessibility tree.
+     */
     hideLabel: WritableSignal<boolean | undefined>;
+    /**
+     * Allows more than one value — multi select, multi file upload, multi toggle.
+     */
     multiple: WritableSignal<boolean | undefined>;
+    /**
+     * Minimum number of characters. Source: `config.minLength`.
+     */
     minLength: WritableSignal<number | undefined>;
+    /**
+     * Maximum number of characters. Source: `config.maxLength`.
+     */
     maxLength: WritableSignal<number | undefined>;
+    /**
+     * Minimum numeric value (also the minimum user count for the user picker).
+     */
     min: WritableSignal<number | undefined>;
+    /**
+     * Maximum numeric value (also the maximum user count for the user picker).
+     */
     max: WritableSignal<number | undefined>;
+    /**
+     * Earliest selectable date for date, datetime and date-range fields.
+     */
     minDate: WritableSignal<Date | undefined>;
+    /**
+     * Latest selectable date for date, datetime and date-range fields.
+     */
     maxDate: WritableSignal<Date | undefined>;
+    /**
+     * Restricts the calendar to working days. Source: `config.acceptWorkDaysOnly`.
+     */
     dateFilter: WritableSignal<boolean | undefined>;
+    /**
+     * Id of a downloadable template offered next to an attachment field.
+     */
     templateId: WritableSignal<string | undefined>;
+    /**
+     * Direct URL of the downloadable template for an attachment field.
+     */
     templateUrl: WritableSignal<string | undefined>;
+    /**
+     * Maximum size per uploaded file. Source: `config.allowedSize`.
+     */
     allowedFileSize: WritableSignal<number | undefined>;
+    /**
+     * Comma separated list of accepted file extensions or MIME types.
+     */
     allowedFileTypes: WritableSignal<string | undefined>;
+    /**
+     * Maximum number of files that may be attached.
+     */
     maxFilesCount: WritableSignal<number | undefined>;
+    /**
+     * Minimum number of files required.
+     */
     minFilesCount: WritableSignal<number | undefined>;
+    /**
+     * Maximum number of users selectable in a user picker.
+     */
     maxUsersCount: WritableSignal<number | undefined>;
+    /**
+     * Minimum number of users required in a user picker.
+     */
     minUsersCount: WritableSignal<number | undefined>;
+    /**
+     * Parsed from the field definition but not consumed yet — table columns currently come
+     * from `field.children`.
+     */
     showInTableColumns: WritableSignal<boolean | undefined>;
+    /**
+     * Enables the filter row on a `table` field.
+     */
     tableWithFilter: WritableSignal<boolean | undefined>;
+    /**
+     * Enables column sorting on a `table` field.
+     */
     tableWithSort: WritableSignal<boolean | undefined>;
+    /**
+     * Enables the paginator on a `table` field.
+     */
     tableWithPagination: WritableSignal<boolean | undefined>;
     constructor(config: any);
 }
@@ -419,6 +1076,38 @@ declare class FieldEvent {
     constructor(action: any, loader: Loader);
 }
 
+/**
+ * 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. |
+ */
 declare class IssField {
     id: number;
     name: string;
@@ -496,15 +1185,50 @@ declare class FormEngine {
     static ɵprov: i0.ɵɵInjectableDeclaration<FormEngine>;
 }
 
+/**
+ * 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.
+ */
 declare class FieldBase implements OnInit, OnDestroy {
     #private;
+    /**
+     * The field definition rendered by this component. Required.
+     */
     issField: InputSignal<IssField>;
+    /**
+     * Set by the outlet once every field is registered; field events start only after it turns true.
+     */
     formReady: InputSignal<boolean | undefined>;
+    /**
+     * The {@link IssField} for this instance, injected through the `FIELD_DATA` token.
+     */
     field: IssField;
     parentFormGroup: ControlContainer;
     formEngine: FormEngine;
     eventHandler: EventHandler;
     destroyRef: DestroyRef;
+    /**
+     * The `FormControl` this field registers on the parent form under `field.name`.
+     */
     ctrl: FormControl;
     ctrlValueChange: i0.Signal<any>;
     get form(): FormGroup;
@@ -514,56 +1238,294 @@ declare class FieldBase implements OnInit, OnDestroy {
     static ɵcmp: i0.ɵɵComponentDeclaration<FieldBase, "ng-component", never, { "issField": { "alias": "issField"; "required": true; "isSignal": true; }; "formReady": { "alias": "formReady"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * `<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 } }
+ * ```
+ */
 declare class InputField extends FieldBase {
     static ɵfac: i0.ɵɵFactoryDeclaration<InputField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<InputField, "iss-field-input", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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 } }
+ * ```
+ */
 declare class TextareaField extends FieldBase {
     static ɵfac: i0.ɵɵFactoryDeclaration<TextareaField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<TextareaField, "iss-field-textarea", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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" }
+ * ```
+ */
 declare class ChipsField extends FieldBase {
     static ɵfac: i0.ɵɵFactoryDeclaration<ChipsField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<ChipsField, "iss-field-chips", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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" }] }
+ * ```
+ */
 declare class RadioField extends FieldBase {
     onChange($event: any): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<RadioField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<RadioField, "iss-field-radio", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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" }] }
+ * ```
+ */
 declare class SelectField extends FieldBase {
     onChange($event: string | FormData): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<SelectField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<SelectField, "iss-field-select", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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" }
+ * ```
+ */
 declare class MobileField extends FieldBase {
     static ɵfac: i0.ɵɵFactoryDeclaration<MobileField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<MobileField, "iss-field-mobile", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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" }] }
+ * ```
+ */
 declare class CheckboxField extends FieldBase {
     updateField($event: any): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<CheckboxField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<CheckboxField, "iss-field-checkbox", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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" }] }
+ * ```
+ */
 declare class ToggleButtonField extends FieldBase {
     onChange($event: any): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<ToggleButtonField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<ToggleButtonField, "iss-field-toggle-button", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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" }
+ * ```
+ */
 declare class SlideToggleField extends FieldBase {
     onChange($event: any): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<SlideToggleField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<SlideToggleField, "iss-field-slide-toggle", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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" }
+ * ```
+ */
 declare class PlateField extends FieldBase {
     updateField($event: any): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<PlateField, never>;
@@ -586,6 +1548,36 @@ declare class FileHandler {
     static ɵprov: i0.ɵɵInjectableDeclaration<FileHandler>;
 }
 
+/**
+ * `<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"] } }
+ * ```
+ */
 declare class FilePickerField extends FieldBase implements OnDestroy {
     #private;
     picker: FormControl<any>;
@@ -602,21 +1594,117 @@ declare class FilePickerField extends FieldBase implements OnDestroy {
     static ɵcmp: i0.ɵɵComponentDeclaration<FilePickerField, "iss-field-file-picker", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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" }
+ * ```
+ */
 declare class TimePickerField extends FieldBase {
     static ɵfac: i0.ɵɵFactoryDeclaration<TimePickerField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<TimePickerField, "iss-field-time-picker", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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" } }
+ * ```
+ */
 declare class DatePickerField extends FieldBase {
     static ɵfac: i0.ɵɵFactoryDeclaration<DatePickerField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<DatePickerField, "iss-field-date-picker", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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" }
+ * ```
+ */
 declare class DatetimePickerField extends FieldBase {
     static ɵfac: i0.ɵɵFactoryDeclaration<DatetimePickerField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<DatetimePickerField, "iss-field-datetime-picker", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * `<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" }
+ * ```
+ */
 declare class DateRangePickerField extends FieldBase {
     static ɵfac: i0.ɵɵFactoryDeclaration<DateRangePickerField, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<DateRangePickerField, "iss-field-date-range-picker", never, {}, {}, never, never, true, never>;
@@ -758,6 +1846,33 @@ interface DynamicImport<T> {
     [key: PropertyKey]: () => Promise<T>;
 }
 
+/**
+ * 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. |
+ */
 declare const COMPONENTS: DynamicImport<Type<any>>;
 
 declare const SERVICES: DynamicImport<Type<any>>;