@tekus/design-system 5.31.0 → 5.32.0

package/types/tekus-design-system-components-date-picker.d.ts

@@ -1,268 +1,318 @@
-import * as _fortawesome_fontawesome_common_types from '@fortawesome/fontawesome-common-types';
 import * as _angular_core from '@angular/core';
 import { OnInit } from '@angular/core';
-import { ControlValueAccessor, NgControl, FormControl } from '@angular/forms';
+import { ControlValueAccessor, Validator, NgControl, FormControl, ValidationErrors } from '@angular/forms';
 
 type DateValue = Date | [Date, Date] | null;
-declare class DatePickerComponent implements OnInit, ControlValueAccessor {
-    /** Internal references and injections */
+/**
+ * @description
+ * Wrapper around PrimeNG's DatePicker with support for single-date, date-range,
+ * and combined date+time modes. Implements `ControlValueAccessor` and `Validator`
+ * so it works transparently with reactive forms (`[formControl]`, `[control]`)
+ * and template-driven forms (`[(ngModel)]`). A signal model (`[(modelValue)]`)
+ * is also available for standalone usage without Angular forms.
+ *
+ * For time-only selection use `tk-time-picker` instead.
+ *
+ * @example
+ * <!-- Date range with reactive form -->
+ * <tk-date-picker
+ *   [control]="form.controls.stayRange"
+ *   selectionMode="range"
+ *   labelText="Stay dates"
+ *   [showClear]="true">
+ * </tk-date-picker>
+ *
+ * @example
+ * <!-- Combined date + time -->
+ * <tk-date-picker
+ *   [showTime]="true"
+ *   hourFormat="24"
+ *   [(modelValue)]="appointmentDateTime"
+ *   labelText="Appointment">
+ * </tk-date-picker>
+ */
+declare class DatePickerComponent implements OnInit, ControlValueAccessor, Validator {
+    /** @internal */
     readonly ngControl: NgControl | null;
+    /** @internal */
     private readonly destroyRef;
     constructor();
     /**
-     * @property {InputSignal<'date' | 'time' | 'both'>} variant
      * @description
-     * Defines the visual and functional mode:
-     * - `'date'`: standard date/range picker
-     * - `'time'`: time-only picker
-     * - `'both'`: date and time picker
-     * @default 'date'
+     * Marks the field as required. When `true`, the component returns a
+     * `{ required: true }` validation error when no date is selected.
+     *
+     * @default false
+     *
+     * @example
+     * <tk-date-picker [required]="true" errorMessage="Date is required" />
      */
-    variant: _angular_core.InputSignal<"date" | "time" | "both">;
+    required: _angular_core.InputSignal<boolean>;
     /**
-     * @property {InputSignal<'single' | 'range'>} selectionMode
      * @description
-     * Defines how the datepicker behaves:
-     * - `'single'`: select one date
-     * - `'range'`: select a pair of dates [start, end]
+     * Selection behaviour for the date calendar.
+     * - `'single'` — one date.
+     * - `'range'` — a pair of dates `[start, end]`.
+     *
      * @default 'range'
+     *
+     * @example
+     * <tk-date-picker selectionMode="single" />
      */
     selectionMode: _angular_core.InputSignal<"single" | "range">;
     /**
-     * @property {InputSignal<boolean>} readonlyInput
      * @description
-     * Disables manual typing in the input and forces the user to select via the calendar.
-     * @default true
-     */
-    readonlyInput: _angular_core.InputSignal<boolean>;
-    /**
-     * @property {InputSignal<boolean>} showClear
-     * @description
-     * Displays a clear button that resets the datepicker value.
+     * Shows a clear (×) button that resets the value to `null`.
+     *
      * @default true
+     *
+     * @example
+     * <tk-date-picker [showClear]="false" />
      */
     showClear: _angular_core.InputSignal<boolean>;
     /**
-     * @property {InputSignal<boolean>} showIcon
      * @description
-     * Shows the calendar or clock icon inside the input.
+     * Shows the calendar icon inside the input field.
+     * When `false`, the overlay can only be opened by clicking the input itself.
+     *
      * @default true
+     *
+     * @example
+     * <tk-date-picker [showIcon]="false" />
      */
     showIcon: _angular_core.InputSignal<boolean>;
     /**
-     * @property {InputSignal<string>} dateFormat
      * @description
-     * Format used by PrimeNG for displaying dates.
+     * Date display format forwarded to PrimeNG (e.g. `'dd/mm/yy'`, `'yy-mm-dd'`).
+     *
      * @default 'dd/mm/yy'
+     *
+     * @example
+     * <tk-date-picker dateFormat="yy-mm-dd" />
      */
     dateFormat: _angular_core.InputSignal<string>;
     /**
-     * @property {InputSignal<string>} timeFormat
-     * @description
-     * Format used by PrimeNG for displaying times.
-     * @default 'HH:mm'
-     */
-    timeFormat: _angular_core.InputSignal<string>;
-    /**
-     * @property {InputSignal<number>} stepHour
-     * @description
-     * Hours to skip when clicking up/down.
+     * @description Hour increment/decrement step for the time spinner (used when `showTime=true`).
      * @default 1
      */
     stepHour: _angular_core.InputSignal<number>;
     /**
-     * @property {InputSignal<number>} stepMinute
-     * @description
-     * Minutes to skip when clicking up/down.
+     * @description Minute increment/decrement step for the time spinner (used when `showTime=true`).
      * @default 1
      */
     stepMinute: _angular_core.InputSignal<number>;
     /**
-     * @property {InputSignal<number>} stepSecond
-     * @description
-     * Seconds to skip when clicking up/down.
+     * @description Second increment/decrement step for the time spinner (used when `showTime=true`).
      * @default 1
      */
     stepSecond: _angular_core.InputSignal<number>;
     /**
-     * @property {InputSignal<boolean>} showSeconds
      * @description
-     * Whether to show seconds in the time picker.
-     * Only applicable when hourFormat is '24'.
+     * Whether to show the seconds segment in the time spinner.
+     * Only active when `showTime=true` and `hourFormat="24"`.
+     *
      * @default false
      */
     showSeconds: _angular_core.InputSignal<boolean>;
     /**
-     * @property {InputSignal<boolean>} disabled
      * @description
-     * Whether the component is disabled.
+     * Disables the entire component. Can also be controlled through the bound
+     * form control via `control.disable()` / `control.enable()`.
+     *
      * @default false
+     *
+     * @example
+     * <tk-date-picker [disabled]="isReadonly()" />
      */
     disabled: _angular_core.InputSignal<boolean>;
     /**
-     * @property {InputSignal<boolean>} inline
      * @description
-     * Whether to display the datepicker inline.
+     * Renders the calendar inline (always visible) instead of in a dropdown overlay.
+     *
      * @default false
+     *
+     * @example
+     * <tk-date-picker [inline]="true" selectionMode="single" />
      */
     inline: _angular_core.InputSignal<boolean>;
     /**
-     * @property {InputSignal<boolean>} showTime
      * @description
-     * Whether to show the time picker along with the date picker.
+     * Adds a time spinner alongside the date calendar.
+     *
      * @default false
+     *
+     * @example
+     * <tk-date-picker [showTime]="true" hourFormat="24" />
      */
     showTime: _angular_core.InputSignal<boolean>;
     /**
-     * @property {InputSignal<'12' | '24'>} hourFormat
      * @description
-     * Format of the hours: '12' or '24'.
+     * Hour format for the time spinner (only relevant when `showTime=true`).
+     * - `'24'` — 0–23 hours.
+     * - `'12'` — 1–12 hours with AM/PM toggle.
+     *
      * @default '24'
+     *
+     * @example
+     * <tk-date-picker [showTime]="true" hourFormat="12" />
      */
     hourFormat: _angular_core.InputSignal<"12" | "24">;
     /**
-     * @property {InputSignal<string | HTMLElement | null | undefined>} appendTo
      * @description
-     * Target element to attach the overlay to.
-     * @default 'null'
+     * Target element or CSS selector to which the overlay panel is appended.
+     * Use `'body'` to escape `overflow:hidden` parent containers (e.g. modals).
+     *
+     * @default 'body'
+     *
+     * @example
+     * <tk-date-picker appendTo="body" />
      */
     appendTo: _angular_core.InputSignal<string | HTMLElement | null | undefined>;
     /**
-     * @property {InputSignal<number>} baseZIndex
-     * @description
-     * Base z-index value for the overlay.
+     * @description Base z-index applied to the overlay panel.
      * @default 10000
      */
     baseZIndex: _angular_core.InputSignal<number>;
     /**
-     * @property {InputSignal<Date | null>} maxDate
      * @description
-     * Maximum selectable date.
+     * Latest selectable date. Enforced both by PrimeNG (disables calendar days)
+     * and by Angular form validation.
+     *
      * @default null
+     *
+     * @example
+     * <tk-date-picker [maxDate]="today" errorMessage="Date cannot be in the future" />
      */
     maxDate: _angular_core.InputSignal<Date | null>;
     /**
-     * @property {InputSignal<Date | null>} minDate
      * @description
-     * Minimum selectable date.
+     * Earliest selectable date. Enforced both by PrimeNG (disables calendar days)
+     * and by Angular form validation.
+     *
      * @default null
+     *
+     * @example
+     * <tk-date-picker [minDate]="today" errorMessage="Date must be today or later" />
      */
     minDate: _angular_core.InputSignal<Date | null>;
     /**
-     * @property {InputSignal<string>} labelText
-     * @description
-     * Label shown by the float-label wrapper.
+     * @description Floating label text shown above the input field.
+     * @default 'Select a date'
+     * @example
+     * <tk-date-picker labelText="Check-in date" />
      */
     labelText: _angular_core.InputSignal<string>;
     /**
-     * @property {InputSignal<FormControl>} control
      * @description
-     * External FormControl used to read/set the datepicker value.
-     * If not provided, an internal FormControl is created.
+     * Validation error message rendered beneath the field when the bound control
+     * is invalid and the field has been dirtied or touched.
+     *
+     * @default null
+     *
+     * @example
+     * <tk-date-picker [minDate]="minDate" errorMessage="Date is required" />
+     */
+    errorMessage: _angular_core.InputSignal<string | null>;
+    /**
+     * @description
+     * Optional external `FormControl` to bind when not using the standard
+     * `formControl` / `formControlName` / `ngModel` directives.
+     *
+     * @example
+     * <tk-date-picker [control]="form.controls.startDate" />
      */
     control: _angular_core.InputSignal<FormControl<any> | undefined>;
     /**
-     * @property {ModelSignal<DateValue>} modelValue
      * @description
-     * The value of the datepicker model. Supports two-way binding.
+     * Two-way signal binding for the selected value.
+     * Accepts `Date` (single), `[Date, Date]` (range), or `null` (cleared).
+     *
+     * @example
+     * <tk-date-picker [(modelValue)]="selectedDate" />
      */
     modelValue: _angular_core.ModelSignal<DateValue>;
     /**
-     * @property {OutputRef<DateValue>} handleSelect
      * @description
-     * Emitted when a value is selected.
+     * Emits the selected value whenever a complete selection is made.
+     * In range mode, fires only when both start and end dates are chosen.
+     *
+     * @example
+     * <tk-date-picker (handleSelect)="onDateSelected($event)" />
      */
     handleSelect: _angular_core.OutputEmitterRef<DateValue>;
     /**
-     * @property {OutputRef<void>} handleClear
-     * @description
-     * Emitted when the value is cleared.
+     * @description Emits when the user clears the field via the clear button.
+     * @example
+     * <tk-date-picker (handleClear)="onCleared()" />
      */
     handleClear: _angular_core.OutputEmitterRef<void>;
-    /**
-     * @property {WritableSignal<boolean>} disabledStatus
-     * @description
-     * Internal signal to track disabled state.
-     */
+    /** @internal */
     disabledStatus: _angular_core.WritableSignal<boolean>;
-    /**
-     * @property {Signal<boolean>} effectiveDisabled
-     * @description
-     * Returns true if either the [disabled] input is true OR the FormControl is disabled.
-     */
+    /** @internal */
     effectiveDisabled: _angular_core.Signal<boolean>;
-    /** Computed properties */
-    /**
-     * @property {Signal<'single' | 'range'>} effectiveSelectionMode
-     * @description
-     * Returns 'single' automatically if variant is 'time', otherwise returns the user-provided selectionMode.
-     */
+    /** @internal */
+    effectiveMinDate: _angular_core.Signal<Date | null>;
+    /** @internal */
+    effectiveMaxDate: _angular_core.Signal<Date | null>;
+    /** @internal */
     effectiveSelectionMode: _angular_core.Signal<"single" | "range">;
-    /**
-     * @property {Signal<string>} effectiveDateFormat
-     * @description
-     * Returns the user-provided dateFormat or timeFormat based on the variant.
-     */
+    /** @internal */
+    effectiveHourFormat: _angular_core.Signal<"12" | "24">;
+    /** @internal */
     effectiveDateFormat: _angular_core.Signal<string>;
-    /**
-     * @property {Signal<boolean>} effectiveShowSeconds
-     * @description
-     * Returns whether seconds should be shown, restricted to 24h format.
-     */
+    /** @internal */
     effectiveShowSeconds: _angular_core.Signal<boolean>;
-    /**
-     * @property {Signal<boolean>} effectiveShowTime
-     * @description
-     * Returns whether the time picker should be shown.
-     */
+    /** @internal */
     effectiveShowTime: _angular_core.Signal<boolean>;
+    /** @internal */
+    private readonly internalControl;
     /**
-     * @property {Signal<FormControl>} effectiveControl
      * @description
-     * Returns the external FormControl from NgControl or a local fallback.
+     * Memoised signal returning the active `FormControl` in priority order:
+     * `NgControl` (reactive forms) → `control` input → internal fallback control.
      */
-    private readonly internalControl;
-    get effectiveControl(): FormControl;
-    /** Icons */
-    faCalendarDay: _fortawesome_fontawesome_common_types.IconDefinition;
-    faClock: _fortawesome_fontawesome_common_types.IconDefinition;
-    /** CVA Logic */
-    onChange: (value: DateValue) => void;
-    onTouched: () => void;
-    private lastValue;
-    private isWriting;
+    readonly effectiveControl: _angular_core.Signal<FormControl<any>>;
+    /** @internal Unique DOM id used for `inputId` / `for` binding on every instance. */
+    readonly uid: string;
+    /** @internal */ onChange: (value: DateValue) => void;
+    /** @internal */ onTouched: () => void;
+    /** @internal */ onValidatorChange: () => void;
+    /** @internal */ private lastValue;
+    /** @internal */ private readonly boundValidate;
+    /** @inheritdoc */
     ngOnInit(): void;
+    /** @inheritdoc */
     writeValue(value: DateValue): void;
+    /** @inheritdoc */
     registerOnChange(fn: (value: DateValue) => void): void;
+    /** @inheritdoc */
     registerOnTouched(fn: () => void): void;
+    /** @inheritdoc */
+    registerOnValidatorChange(fn: () => void): void;
+    /** @inheritdoc */
+    validate(): ValidationErrors | null;
+    private validateBounds;
+    /** @inheritdoc */
     setDisabledState(isDisabled: boolean): void;
-    /**
-     * @method onModelChange
-     * @description
-     * Called when the PrimeNG DatePicker template updates the value.
-     */
+    /** @description Central change handler for PrimeNG's `ngModelChange`. */
     onModelChange(value: DateValue): void;
+    /** @description Marks the control as touched when the user leaves the field. */
+    onBlur(): void;
     /**
-     * @method applyTimeCascading
-     * @private
-     * @description
-     * Adjusts the date when minutes or seconds wrap around.
-     */
-    private applyTimeCascading;
-    /**
-     * @method onBlur
-     * @description
-     * Triggered when the component loses focus.
+     * @description Programmatically clears the selected value, resetting it to `null`.
+     *
+     * @example
+     * <tk-date-picker #picker />
+     * <button (click)="picker.clear()">Reset</button>
      */
-    onBlur(): void;
+    clear(): void;
     /**
-     * @method clear
      * @description
-     * Programmatically clears the value.
+     * Adjusts hours or minutes when the spinner rolls over a unit boundary.
      */
-    clear(): void;
+    private applyTimeCascading;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DatePickerComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DatePickerComponent, "tk-date-picker", never, { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "readonlyInput": { "alias": "readonlyInput"; "required": false; "isSignal": true; }; "showClear": { "alias": "showClear"; "required": false; "isSignal": true; }; "showIcon": { "alias": "showIcon"; "required": false; "isSignal": true; }; "dateFormat": { "alias": "dateFormat"; "required": false; "isSignal": true; }; "timeFormat": { "alias": "timeFormat"; "required": false; "isSignal": true; }; "stepHour": { "alias": "stepHour"; "required": false; "isSignal": true; }; "stepMinute": { "alias": "stepMinute"; "required": false; "isSignal": true; }; "stepSecond": { "alias": "stepSecond"; "required": false; "isSignal": true; }; "showSeconds": { "alias": "showSeconds"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "inline": { "alias": "inline"; "required": false; "isSignal": true; }; "showTime": { "alias": "showTime"; "required": false; "isSignal": true; }; "hourFormat": { "alias": "hourFormat"; "required": false; "isSignal": true; }; "appendTo": { "alias": "appendTo"; "required": false; "isSignal": true; }; "baseZIndex": { "alias": "baseZIndex"; "required": false; "isSignal": true; }; "maxDate": { "alias": "maxDate"; "required": false; "isSignal": true; }; "minDate": { "alias": "minDate"; "required": false; "isSignal": true; }; "labelText": { "alias": "labelText"; "required": false; "isSignal": true; }; "control": { "alias": "control"; "required": false; "isSignal": true; }; "modelValue": { "alias": "modelValue"; "required": false; "isSignal": true; }; }, { "modelValue": "modelValueChange"; "handleSelect": "handleSelect"; "handleClear": "handleClear"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DatePickerComponent, "tk-date-picker", never, { "required": { "alias": "required"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "showClear": { "alias": "showClear"; "required": false; "isSignal": true; }; "showIcon": { "alias": "showIcon"; "required": false; "isSignal": true; }; "dateFormat": { "alias": "dateFormat"; "required": false; "isSignal": true; }; "stepHour": { "alias": "stepHour"; "required": false; "isSignal": true; }; "stepMinute": { "alias": "stepMinute"; "required": false; "isSignal": true; }; "stepSecond": { "alias": "stepSecond"; "required": false; "isSignal": true; }; "showSeconds": { "alias": "showSeconds"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "inline": { "alias": "inline"; "required": false; "isSignal": true; }; "showTime": { "alias": "showTime"; "required": false; "isSignal": true; }; "hourFormat": { "alias": "hourFormat"; "required": false; "isSignal": true; }; "appendTo": { "alias": "appendTo"; "required": false; "isSignal": true; }; "baseZIndex": { "alias": "baseZIndex"; "required": false; "isSignal": true; }; "maxDate": { "alias": "maxDate"; "required": false; "isSignal": true; }; "minDate": { "alias": "minDate"; "required": false; "isSignal": true; }; "labelText": { "alias": "labelText"; "required": false; "isSignal": true; }; "errorMessage": { "alias": "errorMessage"; "required": false; "isSignal": true; }; "control": { "alias": "control"; "required": false; "isSignal": true; }; "modelValue": { "alias": "modelValue"; "required": false; "isSignal": true; }; }, { "modelValue": "modelValueChange"; "handleSelect": "handleSelect"; "handleClear": "handleClear"; }, never, never, true, never>;
 }
 
 export { DatePickerComponent };

package/types/tekus-design-system-components-icon.d.ts

@@ -82,9 +82,18 @@ declare class IconComponent {
     /**
      * Gets the key style for the icon based on the current styleIcon model.
      *
-    * @returns 'light' | 'regular' | 'solid' | null
+     * @returns 'light' | 'regular' | 'solid' | null
      */
     getKeyStyle(): 'light' | 'regular' | 'solid' | null;
+    /**
+     * Converts a kebab-case icon name to the FontAwesome camelCase key (e.g. 'arrow-right' → 'faArrowRight').
+     */
+    private toFaKey;
+    /**
+     * Fallback loader for any FA icon not registered in the catalog.
+     * Dynamically imports the icon by name from the appropriate FA pro package.
+     */
+    private loadIconFaFallback;
     /**
      * Loads a custom icon from the IconCatalog.
      * Sanitize the SVG content and apply the appropriate color.

package/types/tekus-design-system-components-table.d.ts

@@ -4,7 +4,7 @@ import { TagSeverity } from '@tekus/design-system/components/tag';
 import { SortEvent } from 'primeng/api';
 import { TkAction } from '@tekus/design-system/components/action-group';
 
-type TableColumnType = 'text' | 'tag' | 'actions' | 'selection' | 'checkbox' | 'action-group' | 'connection-status';
+type TableColumnType = 'text' | 'tag' | 'actions' | 'selection' | 'checkbox' | 'action-group' | 'connection-status' | 'image';
 interface TableColumn<T = unknown> {
     field?: string;
     header: string;
@@ -25,6 +25,11 @@ interface TableColumn<T = unknown> {
         action: (row: T) => void;
     }>;
     actionGroupMaxVisible?: number;
+    imageAlt?: (row: T) => string;
+    imageWidth?: string;
+    imageHeight?: string;
+    imageFallback?: string;
+    imageAction?: (row: T) => void;
 }
 
 declare class TableComponent<T = unknown> {
@@ -193,6 +198,26 @@ declare class TableComponent<T = unknown> {
      * Handles primitives directly and avoids [object Object] for complex types.
      */
     private cellToString;
+    /**
+     * @method handleImageClick
+     * @description
+     * Handles click events on image-type cells.
+     * Stops row selection propagation and invokes the column's imageAction callback when defined.
+     * No-op when imageAction is not set, preserving default row-click behavior.
+     * @param event {Event} - The native click event.
+     * @param col {TableColumn<T>} - The column definition that may carry an imageAction.
+     * @param row {T} - The data row associated with the clicked image.
+     */
+    handleImageClick(event: Event, col: TableColumn<T>, row: T): void;
+    /**
+     * @method onImageError
+     * @description
+     * Handles image load errors by replacing the broken src with a fallback URL.
+     * Called from the template's (error) binding on image-type columns.
+     * @param event {Event} - The native error event from the <img> element.
+     * @param fallback {string | undefined} - Optional URL to use as replacement src.
+     */
+    onImageError(event: Event, fallback?: string): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TableComponent<any>, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<TableComponent<any>, "tk-table", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "columns": { "alias": "columns"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "selection": { "alias": "selection"; "required": false; "isSignal": true; }; "dataKey": { "alias": "dataKey"; "required": false; "isSignal": true; }; }, { "selection": "selectionChange"; }, never, never, true, never>;
 }