@tekus/design-system 5.31.0 → 5.32.0

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

@@ -0,0 +1,203 @@
+import * as _angular_core from '@angular/core';
+import { OnInit } from '@angular/core';
+import { ControlValueAccessor, Validator, NgControl, FormControl, ValidationErrors } from '@angular/forms';
+import { InputMask } from 'primeng/inputmask';
+
+declare class TimePickerComponent implements OnInit, ControlValueAccessor, Validator {
+    /** @internal */
+    readonly ngControl: NgControl | null;
+    /** @internal */
+    private readonly destroyRef;
+    constructor();
+    /**
+     * @description
+     * Marks the field as required. When `true`, the component returns a
+     * `{ required: true }` validation error when no time is selected.
+     *
+     * @default false
+     *
+     * @example
+     * <tk-time-picker [required]="true" errorMessage="Time is required" />
+     */
+    required: _angular_core.InputSignal<boolean>;
+    /**
+     * @description
+     * Controls how the user enters the time.
+     * - `true`  — direct keyboard input via a masked field; the clock icon opens
+     *   a spinner overlay for visual selection. Only 24-hour format is supported
+     *   in this mode.
+     * - `false` — spinners only; keyboard input is disabled.
+     *
+     * @default false
+     */
+    editableInput: _angular_core.InputSignal<boolean>;
+    /**
+     * @description
+     * Time display format used both for the masked input and for PrimeNG's spinner.
+     * Supported tokens: `HH` (24-h hours), `hh` (12-h hours), `mm` (minutes),
+     * `ss` (seconds).
+     *
+     * @default 'HH:mm'
+     */
+    timeFormat: _angular_core.InputSignal<string>;
+    /**
+     * @description
+     * Hour format for the time spinner.
+     * - `'24'` — 0–23 hours.
+     * - `'12'` — 1–12 hours with AM/PM toggle. Ignored when `editableInput=true`.
+     *
+     * @default '24'
+     */
+    hourFormat: _angular_core.InputSignal<"12" | "24">;
+    /** @description Hour increment/decrement step for the spinner. @default 1 */
+    stepHour: _angular_core.InputSignal<number>;
+    /** @description Minute increment/decrement step for the spinner. @default 1 */
+    stepMinute: _angular_core.InputSignal<number>;
+    /** @description Second increment/decrement step for the spinner. @default 1 */
+    stepSecond: _angular_core.InputSignal<number>;
+    /**
+     * @description Whether to show the seconds segment. Only active when `hourFormat="24"`.
+     * @default false
+     */
+    showSeconds: _angular_core.InputSignal<boolean>;
+    /** @description Shows a clear (×) button that resets the value to `null`. @default true */
+    showClear: _angular_core.InputSignal<boolean>;
+    /**
+     * @description
+     * Shows the clock icon inside the input field.
+     * When `false`, the overlay can only be opened by clicking the input itself.
+     *
+     * @default true
+     */
+    showIcon: _angular_core.InputSignal<boolean>;
+    /** @description Disables the component. @default false */
+    disabled: _angular_core.InputSignal<boolean>;
+    /**
+     * @description
+     * Earliest selectable time. Enforced through Angular form validation only —
+     * the field value is never cleared when the limit is reached.
+     *
+     * @default null
+     */
+    minDate: _angular_core.InputSignal<Date | null>;
+    /**
+     * @description Latest selectable time. Same validation-only semantics as `minDate`.
+     * @default null
+     */
+    maxDate: _angular_core.InputSignal<Date | null>;
+    /** @description Floating label text shown above the input field. @default 'Select a time' */
+    labelText: _angular_core.InputSignal<string>;
+    /**
+     * @description
+     * Validation error message rendered beneath the field when the bound control
+     * is invalid and the field has been dirtied or touched.
+     *
+     * @default null
+     */
+    errorMessage: _angular_core.InputSignal<string | null>;
+    /**
+     * @description
+     * Optional external `FormControl` to bind when not using the standard
+     * `formControl` / `formControlName` / `ngModel` directives.
+     */
+    control: _angular_core.InputSignal<FormControl<any> | undefined>;
+    /**
+     * @description
+     * Target element or CSS selector to which the overlay panel is appended.
+     * @default 'body'
+     */
+    appendTo: _angular_core.InputSignal<string | HTMLElement | null | undefined>;
+    /**
+     * @description
+     * Two-way signal binding for the selected time value (`Date | null`).
+     */
+    modelValue: _angular_core.ModelSignal<Date | null>;
+    /** @description Emits the selected value whenever a complete time is chosen. */
+    handleSelect: _angular_core.OutputEmitterRef<Date>;
+    /** @description Emits when the user clears the field via the clear button. */
+    handleClear: _angular_core.OutputEmitterRef<void>;
+    /** @internal */
+    disabledStatus: _angular_core.WritableSignal<boolean>;
+    /** @internal */
+    effectiveDisabled: _angular_core.Signal<boolean>;
+    /** @internal */
+    readonly maskInput: _angular_core.Signal<InputMask | undefined>;
+    /**
+     * @description
+     * Forces `'24'` when `editableInput=true` because the InputMask digit-only
+     * pattern cannot represent AM/PM tokens.
+     */
+    effectiveHourFormat: _angular_core.Signal<"12" | "24">;
+    /**
+     * @description
+     * PrimeNG InputMask pattern derived from `timeFormat` by replacing all
+     * time-letter placeholders with the digit wildcard `'9'`.
+     */
+    effectiveTimeMask: _angular_core.Signal<string>;
+    /**
+     * @description
+     * Formats the current `modelValue` as a time string matching `timeFormat`,
+     * bound to the InputMask via `[ngModel]`.
+     */
+    maskedTimeValue: _angular_core.Signal<string>;
+    /** @internal */
+    effectiveShowSeconds: _angular_core.Signal<boolean>;
+    /** @internal */
+    private readonly internalControl;
+    /** @internal */
+    readonly effectiveControl: _angular_core.Signal<FormControl<any>>;
+    /** @internal */
+    readonly uid: string;
+    /** @internal */
+    private readonly partialMask;
+    /** @internal */
+    private readonly invalidTimeInput;
+    /** @internal */ onChange: (value: Date | null) => void;
+    /** @internal */ onTouched: () => void;
+    /** @internal */ onValidatorChange: () => void;
+    /** @internal */ private lastValue;
+    /** @internal */ private readonly boundValidate;
+    /** @inheritdoc */
+    ngOnInit(): void;
+    /** @inheritdoc */
+    writeValue(value: Date | null): void;
+    /** @inheritdoc */
+    registerOnChange(fn: (value: Date | null) => void): void;
+    /** @inheritdoc */
+    registerOnTouched(fn: () => void): void;
+    /** @inheritdoc */
+    registerOnValidatorChange(fn: () => void): void;
+    /** @inheritdoc */
+    validate(): ValidationErrors | null;
+    /** @inheritdoc */
+    setDisabledState(isDisabled: boolean): void;
+    /** @description Marks the control as touched when the user leaves the field. */
+    onBlur(): void;
+    /** @description Programmatically clears the selected value, resetting it to `null`. */
+    clear(): void;
+    /**
+     * @description
+     * Parses the string emitted by InputMask and propagates the resulting Date.
+     */
+    onMaskedTimeChange(timeStr: string): void;
+    /**
+     * @description
+     * Handles value changes from the hidden spinner overlay in mask+overlay mode.
+     */
+    onOverlayTimeChange(value: Date | null): void;
+    /**
+     * @description
+     * Fires when the spinner overlay opens. If no value is selected, auto-commits
+     * the time that PrimeNG displays by default (minDate or current time).
+     */
+    onOverlayShow(): void;
+    /**
+     * @description
+     * Adjusts hours or minutes when the spinner rolls over a unit boundary.
+     */
+    private applyTimeCascading;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TimePickerComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TimePickerComponent, "tk-time-picker", never, { "required": { "alias": "required"; "required": false; "isSignal": true; }; "editableInput": { "alias": "editableInput"; "required": false; "isSignal": true; }; "timeFormat": { "alias": "timeFormat"; "required": false; "isSignal": true; }; "hourFormat": { "alias": "hourFormat"; "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; }; "showClear": { "alias": "showClear"; "required": false; "isSignal": true; }; "showIcon": { "alias": "showIcon"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "minDate": { "alias": "minDate"; "required": false; "isSignal": true; }; "maxDate": { "alias": "maxDate"; "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; }; "appendTo": { "alias": "appendTo"; "required": false; "isSignal": true; }; "modelValue": { "alias": "modelValue"; "required": false; "isSignal": true; }; }, { "modelValue": "modelValueChange"; "handleSelect": "handleSelect"; "handleClear": "handleClear"; }, never, never, true, never>;
+}
+
+export { TimePickerComponent };

package/types/tekus-design-system-utils-wcag-contrast.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Pure utilities implementing the official WCAG 2.x contrast formula
+ * (relative luminance + contrast ratio).
+ *
+ * Thresholds follow the normal-text criteria (conservative):
+ * `>= 7` AAA, `>= 4.5` AA, otherwise `fail`.
+ */
+type WcagLevel = 'AAA' | 'AA' | 'fail';
+interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+}
+interface ContrastResult {
+    ratio: number;
+    level: WcagLevel;
+}
+/**
+ * Parses a hex color (`#abc`, `abc`, `#aabbcc` or `aabbcc`) into RGB channels (0–255).
+ * Returns `null` when the value is not a valid hex color.
+ */
+declare function hexToRgb(hex: string): RgbColor | null;
+/**
+ * WCAG relative luminance of a hex color (0 = black, 1 = white).
+ * Returns `NaN` for invalid hex values.
+ */
+declare function relativeLuminance(hex: string): number;
+/**
+ * Contrast ratio between two hex colors, rounded to 2 decimals.
+ * Range: 1 (identical) to 21 (black on white).
+ */
+declare function calcContrastRatio(bg: string, fg: string): number;
+/**
+ * Maps a contrast ratio to its WCAG level for normal text:
+ * `>= 7` → AAA, `>= 4.5` → AA, otherwise `fail`.
+ */
+declare function resolveWcagLevel(ratio: number): WcagLevel;
+/**
+ * Convenience helper combining {@link calcContrastRatio} and {@link resolveWcagLevel}.
+ */
+declare function getContrastResult(bg: string, fg: string): ContrastResult;
+/**
+ * Whether a hex color is perceived as light, using the ITU-R BT.601
+ * perceived-luminance formula normalized to [0, 1] with a 0.5 threshold.
+ * Invalid hex values are treated as dark (`false`).
+ */
+declare function isLightColor(hex: string): boolean;
+/**
+ * Ideal text color over the given background:
+ * black (`#000000`) on light backgrounds, white (`#ffffff`) on dark ones.
+ */
+declare function getContrastTextColor(background: string): string;
+
+export { calcContrastRatio, getContrastResult, getContrastTextColor, hexToRgb, isLightColor, relativeLuminance, resolveWcagLevel };
+export type { ContrastResult, RgbColor, WcagLevel };