@sixbell-telco/sdk
Version:
A collection of reusable components designed for use in Sixbell Telco Angular projects
324 lines (323 loc) • 16.6 kB
TypeScript
import { ControlValueAccessor, FormControl, FormGroup } from '@angular/forms';
import { OverlayComponent } from '@sixbell-telco/sdk/components/overlay';
import { DateRange, QuickRangePreset } from '@sixbell-telco/sdk/utils/date';
import 'cally';
import { DatePickerValue, OptionalTimeString } from '../types/date-picker.types';
import * as i0 from "@angular/core";
/**
* Datepicker - Single date and date range picker with optional time selection
*
* @remarks
* This component wraps Cally.js calendar elements and provides a rich, accessible
* date and date-range picking experience for Angular apps. It supports:
* - Single or range modes
* - Quick action ranges
* - Optional time selection with minutes or seconds
* - 12h/24h time display for the trigger text
* - Locale-aware calendar (auto-mapped from the TranslationService or overridden)
* - Form integration (reactive forms) and standalone usage
*
* The component is exported as `stDatepicker` for template reference variables
* to access methods (e.g. displayValue()).
*
* @example Basic single date
* ```html
* <st-datepicker
* label="Pick a date"
* mode="single"
* format="DD/MM/YYYY"
* (dateUpdated)="onDate($event)"
* #picker="stDatepicker"
* >
* <st-button [outline]="true">{{ picker.displayValue() || 'Pick a date' }}</st-button>
* </st-datepicker>
* ```
*
* @example Date range with time (minutes)
* ```html
* <st-datepicker
* label="Pick range with time"
* mode="range"
* [showTimePicker]="true"
* [showSeconds]="false"
* (rangeUpdated)="onRange($event)"
* (startTimeChanged)="onStartTime($event)"
* (endTimeChanged)="onEndTime($event)"
* #picker="stDatepicker"
* >
* <st-button [outline]="true">{{ picker.displayValue() || 'Pick range' }}</st-button>
* </st-datepicker>
* ```
*
* @example Reactive form control (range)
* ```html
* <form [formGroup]="form">
* <st-datepicker
* [parentForm]="form"
* formControlName="range"
* mode="range"
* [rangeCalendars]="2"
* [showQuickActions]="true"
* name="range"
* >
* <st-input [value]="picker.displayValue()" [readonly]="true" name="range"></st-input>
* </st-datepicker>
* </form>
* ```
*/
export declare class DatepickerComponent implements ControlValueAccessor {
/** Internal state for single date (ISO format) */
private readonly _selectedDateValue;
/** Internal state for date range (ISO format) */
private readonly _selectedRangeValue;
/** Disabled state */
private readonly _disabled;
/** Flag to prevent concurrent range updates */
private isUpdatingRange;
/** Translation service for reactive language changes */
private readonly translationService;
/** Form change callback */
private onControlChange;
/** Form touch callback */
private onControlTouch;
/** Overlay reference for controlling calendar popup */
datePickerOverlay: import("@angular/core").Signal<OverlayComponent | undefined>;
/** Label displayed above the fieldset legend */
label: import("@angular/core").InputSignal<string>;
/**
* Picker mode
* @defaultValue 'single'
* @remarks 'single' for single date, 'range' for start/end selection
*/
mode: import("@angular/core").InputSignal<"single" | "range">;
/**
* Display/parse format for dates
* @defaultValue 'DD/MM/YYYY'
* @remarks Used for trigger text and for parsing external values (when provided as display strings)
*/
format: import("@angular/core").InputSignal<"DD/MM/YYYY" | "MM/DD/YYYY" | "YYYY-MM-DD" | "DD-MM-YYYY" | "MM-DD-YYYY" | "YYYY/MM/DD" | "DD.MM.YYYY" | "MM.DD.YYYY" | "YYYY.MM.DD">;
/**
* Locale used by the calendar web component
* @defaultValue 'en-US'
* @remarks If omitted or set to 'en-US', the component will auto-map from the TranslationService using `languageMapping`.
*/
language: import("@angular/core").InputSignal<"en-US" | "en-GB" | "es-ES" | "es-MX" | "fr-FR" | "de-DE" | "it-IT" | "pt-BR" | "pt-PT" | "ja-JP" | "ko-KR" | "zh-CN" | "zh-TW" | "ru-RU" | "ar-SA" | "hi-IN" | "nl-NL" | "sv-SE" | "da-DK" | "no-NO" | "fi-FI" | "pl-PL" | "tr-TR" | "he-IL" | "th-TH" | "vi-VN">;
/** Optional minimum selectable date (display or ISO). Internally coerced to ISO. */
minDate: import("@angular/core").InputSignal<string | null>;
/** Optional maximum selectable date (display or ISO). Internally coerced to ISO. */
maxDate: import("@angular/core").InputSignal<string | null>;
/** Single date value (external binding). Accepts display or ISO; stored internally as ISO. */
value: import("@angular/core").InputSignal<string>;
/** Date range value (external binding). Accepts display or ISO; stored internally as ISO. */
rangeValue: import("@angular/core").InputSignal<DateRange | null>;
/** Name attribute for associated input (useful when wrapping with st-input). */
name: import("@angular/core").InputSignal<string>;
/**
* Number of calendars to show in range mode
* @defaultValue 2
*/
rangeCalendars: import("@angular/core").InputSignal<2 | 1>;
/**
* Whether to show quick action buttons for common ranges
* @defaultValue true
*/
showQuickActions: import("@angular/core").InputSignal<boolean>;
/**
* Whether to show time pickers for start/end
* @defaultValue false
*/
showTimePicker: import("@angular/core").InputSignal<boolean>;
/**
* Whether to include seconds in time inputs and display
* @defaultValue false
*/
showSeconds: import("@angular/core").InputSignal<boolean>;
/**
* Time display format for trigger text
* @defaultValue '24h'
* @remarks Affects only the textual display in the trigger, not the underlying stored time format
*/
timeDisplayFormat: import("@angular/core").InputSignal<"24h" | "12h">;
/**
* Mapping of translation language codes (e.g. 'en','es','pt') to calendar locales (e.g. 'en-US','es-MX','pt-BR')
* @defaultValue { en: 'en-US', es: 'es-MX', pt: 'pt-BR' }
*/
languageMapping: import("@angular/core").InputSignal<Record<string, "en-US" | "en-GB" | "es-ES" | "es-MX" | "fr-FR" | "de-DE" | "it-IT" | "pt-BR" | "pt-PT" | "ja-JP" | "ko-KR" | "zh-CN" | "zh-TW" | "ru-RU" | "ar-SA" | "hi-IN" | "nl-NL" | "sv-SE" | "da-DK" | "no-NO" | "fi-FI" | "pl-PL" | "tr-TR" | "he-IL" | "th-TH" | "vi-VN">>;
/**
* Use locale-based formatting for the trigger display instead of the custom pattern
* @defaultValue false
*/
useLocaleDisplay: import("@angular/core").InputSignal<boolean>;
/**
* Locale date style when useLocaleDisplay=true
* @defaultValue 'short'
*/
dateStyle: import("@angular/core").InputSignal<"short" | "medium" | "long" | "full">;
/** Optional external defaults for start/end time (HH:mm or HH:mm:ss). When empty string, inputs render blank. */
startTimeValue: import("@angular/core").InputSignal<OptionalTimeString>;
endTimeValue: import("@angular/core").InputSignal<OptionalTimeString>;
/**
* Current start time value (internal signal). Empty when unset.
* @internal
*/
readonly startTime: import("@angular/core").WritableSignal<OptionalTimeString>;
/**
* Current end time value (internal signal). Empty when unset.
* @internal
*/
readonly endTime: import("@angular/core").WritableSignal<OptionalTimeString>;
/** Parent reactive form group (optional) */
parentForm: import("@angular/core").InputSignal<FormGroup<any> | null>;
/** Name of the form control inside the parent form (optional) */
formControlName: import("@angular/core").InputSignal<string>;
/**
* Emits formatted single date when it changes
* @remarks Uses the `format` (or locale display if enabled). For range mode, use `rangeUpdated`.
*/
dateUpdated: import("@angular/core").OutputEmitterRef<string>;
/**
* Emits an ISO `DateRange` when both start & end are selected
* @remarks Start/end are always emitted in ISO (YYYY-MM-DD). Time values are emitted separately.
*/
rangeUpdated: import("@angular/core").OutputEmitterRef<DateRange>;
/** Emits formatted date when value changes (single mode). Alias of `dateUpdated`. */
valueChanged: import("@angular/core").OutputEmitterRef<string>;
/** Emits ISO date range (alias of `rangeUpdated`). */
rangeValueChanged: import("@angular/core").OutputEmitterRef<DateRange>;
/** Emits start time (HH:mm or HH:mm:ss) changes; empty string when cleared */
startTimeChanged: import("@angular/core").OutputEmitterRef<OptionalTimeString>;
/** Emits end time (HH:mm or HH:mm:ss) changes; empty string when cleared */
endTimeChanged: import("@angular/core").OutputEmitterRef<OptionalTimeString>;
/** Effective minimum date (input or default 10 years ago) */
effectiveMinDate: import("@angular/core").Signal<string>;
/** Effective maximum date (input or default 10 years ahead) */
effectiveMaxDate: import("@angular/core").Signal<string>;
/** Locale for calendar components */
calendarLocale: import("@angular/core").Signal<"en-US" | "en-GB" | "es-ES" | "es-MX" | "fr-FR" | "de-DE" | "it-IT" | "pt-BR" | "pt-PT" | "ja-JP" | "ko-KR" | "zh-CN" | "zh-TW" | "ru-RU" | "ar-SA" | "hi-IN" | "nl-NL" | "sv-SE" | "da-DK" | "no-NO" | "fi-FI" | "pl-PL" | "tr-TR" | "he-IL" | "th-TH" | "vi-VN">;
/** Form control instance from parent form group */
formField: import("@angular/core").Signal<FormControl<any> | null>;
/** Formatted display value for single date */
selectedDate: import("@angular/core").Signal<string>;
/** Formatted display value for date range */
selectedRange: import("@angular/core").Signal<{
start: string;
end: string;
} | null>;
/** @internal Value for calendar-range component (ISO/ISO format) */
rangeCalendarValue: import("@angular/core").Signal<string>;
displayValue: import("@angular/core").Signal<string>;
/** Time values normalized for the inputs based on showSeconds */
startTimeDisplay: import("@angular/core").Signal<string>;
endTimeDisplay: import("@angular/core").Signal<string>;
/** Keep internal state in sync when rangeValue input changes */
syncInputEff: import("@angular/core").EffectRef;
/** Sync external start/end time inputs into internal signals */
syncTimeInputsEff: import("@angular/core").EffectRef;
/** Exposed selected date value (ISO format) for template access */
selectedDateValue: import("@angular/core").Signal<string>;
private formatMonthYear;
private formatWeekday;
private formatDateLocale;
fromDay: import("@angular/core").Signal<string>;
fromMonthYear: import("@angular/core").Signal<string>;
fromWeekday: import("@angular/core").Signal<string>;
toDay: import("@angular/core").Signal<string>;
toMonthYear: import("@angular/core").Signal<string>;
toWeekday: import("@angular/core").Signal<string>;
constructor();
/**
* Initialize component values based on inputs
*/
private initializeValues;
/**
* Set single date value programmatically
*/
private setSingleDateValue;
/**
* Emit change events and notify form controls
*/
private emitChanges;
/**
* Close overlay if available
*/
private closeOverlay;
/**
* Handle calendar change events from Cally components
* @internal
*/
onCalendarChange(calendarElement: HTMLElement, event?: Event): void;
/**
* Apply a predefined quick range preset
* @param preset One of: 'last7Days' | 'last30Days' | 'last6Months' | 'lastYear'
* @remarks This updates the date range (ISO). Time inputs are not modified.
*/
selectQuickRange(preset: QuickRangePreset): Promise<void>;
/**
* Apply a time-based quick range (last N hours). Visible only when time picker is enabled.
* @param hours Number of hours to go back from now
* @remarks Updates the date range and emits start/end time strings (HH:mm:ss)
*/
selectQuickLastHours(hours: number): Promise<void>;
/**
* Clear the current range selection
* @remarks Also clears start/end time inputs and emits empty strings for time changes.
*/
clearRange(): Promise<void>;
/**
* Clear the current single date selection
*/
clearDate(): void;
/**
* Set range value programmatically
*/
private setRangeValue;
/**
* Update calendar element to ensure Cally.js synchronization
*/
private updateCalendarElementValue;
/**
* Handle single date calendar change
*/
private handleSingleCalendarChange;
/**
* Handle range calendar change
*/
private handleRangeCalendarChange;
/**
* Finalize range selection: ensure same-day times if needed and emit when selection is complete
*/
private finalizeRangeSelection;
/**
* Extract date value from calendar element
*/
private extractDateValue;
/**
* Extract range value from calendar element
*/
private extractRangeValue;
/**
* Write external model value into the component
*/
writeValue(obj: DatePickerValue): void;
/**
* Register form change callback
*/
registerOnChange(fn: (value: DatePickerValue) => void): void;
/**
* Register form touched callback
*/
registerOnTouched(fn: () => void): void;
/**
* Update disabled state from Angular forms
*/
setDisabledState(isDisabled: boolean): void;
/** Icons for navigation buttons */
readonly iconChevronLeft = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"currentColor\"><path d=\"M15.41 7.41L14 6l-6 6l6 6l1.41-1.41L10.83 12z\"></path></svg>";
readonly iconChevronRight = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"currentColor\"><path d=\"M10 6L8.59 7.41L13.17 12l-4.58 4.59L10 18l6-6z\"></path></svg>";
readonly iconClock = "<svg xmlns=\"http://www.w3.org/2000/svg\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" aria-hidden=\"true\" data-slot=\"icon\" style=\"stroke-width:var(--ng-icon__stroke-width, 1.5)\"><path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M12 6v6h4.5m4.5 0a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z\"></path></svg>";
private clampTime;
onStartTimeChange(ev: Event): void;
onEndTimeChange(ev: Event): void;
static ɵfac: i0.ɵɵFactoryDeclaration<DatepickerComponent, never>;
static ɵcmp: i0.ɵɵComponentDeclaration<DatepickerComponent, "st-datepicker", ["stDatepicker"], { "label": { "alias": "label"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "format": { "alias": "format"; "required": false; "isSignal": true; }; "language": { "alias": "language"; "required": false; "isSignal": true; }; "minDate": { "alias": "minDate"; "required": false; "isSignal": true; }; "maxDate": { "alias": "maxDate"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "rangeValue": { "alias": "rangeValue"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "rangeCalendars": { "alias": "rangeCalendars"; "required": false; "isSignal": true; }; "showQuickActions": { "alias": "showQuickActions"; "required": false; "isSignal": true; }; "showTimePicker": { "alias": "showTimePicker"; "required": false; "isSignal": true; }; "showSeconds": { "alias": "showSeconds"; "required": false; "isSignal": true; }; "timeDisplayFormat": { "alias": "timeDisplayFormat"; "required": false; "isSignal": true; }; "languageMapping": { "alias": "languageMapping"; "required": false; "isSignal": true; }; "useLocaleDisplay": { "alias": "useLocaleDisplay"; "required": false; "isSignal": true; }; "dateStyle": { "alias": "dateStyle"; "required": false; "isSignal": true; }; "startTimeValue": { "alias": "startTimeValue"; "required": false; "isSignal": true; }; "endTimeValue": { "alias": "endTimeValue"; "required": false; "isSignal": true; }; "parentForm": { "alias": "parentForm"; "required": false; "isSignal": true; }; "formControlName": { "alias": "formControlName"; "required": false; "isSignal": true; }; }, { "dateUpdated": "dateUpdated"; "rangeUpdated": "rangeUpdated"; "valueChanged": "valueChanged"; "rangeValueChanged": "rangeValueChanged"; "startTimeChanged": "startTimeChanged"; "endTimeChanged": "endTimeChanged"; }, never, ["*"], true, never>;
}