dap-design-system/dist/components/timepicker/timepicker.component.d.ts

Official design system for the DÁP (dap.gov.hu)

import { Dayjs } from 'dayjs';
import { PropertyValueMap } from 'lit';
import { FloatingStrategy, PopupPlacement, TimePreset } from '../../common/types';
import { GenericFormElement } from '../../internal/mixin/genericFormElement';
import { default as DapDSFeedback } from '../feedback/feedback.component';
import { default as DapDSFormLabel } from '../form/form-label/form-label.component';
import { default as DapDSIcon } from '../icon/icon.component';
import { default as DapDSIconButton } from '../icon-button/icon-button.component';
import { default as SystemLoadingSpinner } from '../icons/system/system-loading-spinner/system-loading-spinner.component';
import { default as SystemTimeLine } from '../icons/system/system-time-line/system-time-line.component';
import { default as DapDSPopup } from '../popup/popup.component';
import { default as DapDSTooltip } from '../tooltip/tooltip.component';
import { default as DapDSTypography } from '../typography/typography.component';
import { default as DapDSTimeGrid } from './time-grid.component';
/**
 * `dap-ds-timepicker`
 * @summary A timepicker is a graphical user interface widget that allows the user to select a time from a time range.
 * @element dap-ds-timepicker
 * @title - Timepicker
 *
 * @property {Dayjs | string} value - The value of the timepicker. Can be a Dayjs object or a string in 'HH:mm' format.
 * @property {string} label - The label of the timepicker.
 * @property {boolean} hideLabel - Visually hides the label while keeping it available to assistive technology. (default: false)
 * @property {string} description - The description of the timepicker.
 * @property {'xs' | 'sm' | 'lg'} size - The size of the timepicker.
 * @property {boolean} disabled - The disabled state of the timepicker.
 * @property {boolean} required - The required state of the timepicker.
 * @property {boolean} readonly - The readonly state of the timepicker.
 * @property {boolean} autofocus - The autofocus state of the timepicker.
 * @property {string} tooltip - The tooltip of the timepicker.
 * @property {'top' | 'right' | 'bottom' | 'left'} tooltipPlacement - The tooltip placement of the timepicker.
 * @property {string} feedback - The feedback of the timepicker.
 * @property {'negative' | 'positive' | 'warning'} feedbackType - The feedback type of the timepicker.
 * @property {boolean} optional - The optional state of the timepicker.
 * @property {string} optionalLabel - The optional label of the timepicker.
 * @property {string} requiredLabel - The required indicator of the timepicker. (default: '*')
 * @property {boolean} subtle - The weight of the label. Default is `false`
 * @property {string} autocomplete - The autocomplete of the timepicker.
 * @property {string} placeholder - The placeholder of the timepicker.
 * @property {boolean} loading - The loading state of the timepicker.
 * @property {string} format - The format of the timepicker. Defaults to 'HH:mm'.
 * @property {string} minTime - The minimum time of the timepicker. Format: 'HH:mm'.
 * @property {string} maxTime - The maximum time of the timepicker. Format: 'HH:mm'.
 * @property {number} step - The step interval in minutes. Defaults to 15.
 * @property {boolean} openTimeOnInput - Whether the time picker should open on typing.
 * @property {boolean} sendEmptyEventOnInput - Whether the time picker should send an empty event on typing.
 * @property {string} clearButton - Whether the clear button should be shown. Defaults to 'true'.
 * @property {string} clearButtonAriaLabel - The aria label of the clear button.
 * @property {string} placement - The placement of the dropdown of the timepicker.
 * @property {FloatingStrategy} floatingStrategy - The floating strategy of the timepicker.
 * @property {string} locale - The locale of the timepicker.
 * @property {boolean} closeOnSelection - Whether the dropdown should close when a time is selected.
 * @property {boolean} showSeconds - Whether to show the seconds column in the time picker.
 * @property {number} secondsStep - The step interval in seconds. Defaults to 1.
 * @property {function} disabledTime - Callback to determine if a time should be disabled.
 * @property {boolean} hideDisabledTimes - Whether to hide disabled times or show them as disabled.
 * @property {TimePreset[]} presets - Array of preset time slots for quick selection.
 *
 * @event {{ value: Dayjs | string, hour: number, minute: number, second?: number }} dds-change - Fired when the timepicker value changes.
 * @event {{ value: string }} dds-input - Fired when the timepicker input value changes.
 * @event {{ value: Dayjs | string, hour: number, minute: number, second?: number }} dds-valid-time - Fired when the timepicker input value is valid. Happens on manual input typing.
 * @event {{ value: Dayjs | string, hour: number, minute: number, second?: number, type: 'invalid' | 'out-of-range' }} dds-invalid-time - Fired when the timepicker input value is invalid. Happens on manual input typing.
 * @event {{ void }} dds-clear - Fired when the timepicker is cleared.
 * @event {{ void }} dds-focus - Emitted when the timepicker gains focus.
 * @event {{ void }} dds-blur - Emitted when the timepicker loses focus.
 *
 * @csspart base - The main timepicker container.
 * @csspart trigger - The trigger button of the timepicker.
 * @csspart label - The label of the timepicker.
 * @csspart description - The description of the timepicker.
 * @csspart feedback - The feedback of the timepicker.
 * @csspart tooltip - The tooltip of the timepicker.
 * @csspart input - The input of the timepicker.
 * @csspart clear-button - The clear button of the timepicker.
 *
 * @cssproperty --dds-timepicker-background - The background color of the timepicker. (default: var(--dds-fields-background-default))
 * @cssproperty --dds-timepicker-border-color - The border color of the timepicker. (default: var(--dds-border-neutral-base))
 * @cssproperty --dds-timepicker-border-width - The border width of the timepicker. (default: var(--dds-border-width-base, 1px))
 * @cssproperty --dds-timepicker-border-radius - The border radius of the timepicker. (default: var(--dds-radius-base))
 * @cssproperty --dds-timepicker-text-color - The text color of the timepicker. (default: var(--dds-text-neutral-base))
 * @cssproperty --dds-timepicker-placeholder-color - The placeholder text color. (default: var(--dds-text-neutral-subtle))
 * @cssproperty --dds-timepicker-disabled-background - The background color when disabled. (default: var(--dds-background-neutral-stronger))
 * @cssproperty --dds-timepicker-disabled-text - The text color when disabled. (default: var(--dds-text-neutral-disabled))
 * @cssproperty --dds-timepicker-error-border - The border color for error state. (default: var(--dds-border-negative-base))
 * @cssproperty --dds-timepicker-success-border - The border color for success state. (default: var(--dds-border-positive-base))
 * @cssproperty --dds-timepicker-icon-color - The color of the icons. (default: var(--dds-text-icon-neutral-subtle))
 * @cssproperty --dds-timepicker-clear-icon-color - The color of the clear icon. (default: var(--dds-button-subtle-icon-neutral-enabled))
 * @cssproperty --dds-timepicker-popup-background - The background color of the popup. (default: var(--dds-background-neutral-subtle))
 * @cssproperty --dds-timepicker-popup-shadow - The box shadow of the popup. (default: 0 4px 6px -1px rgb(0 0 0 / 8%), 0 2px 4px -1px rgb(0 0 0 / 6%))
 *
 * @cssproperty --dds-timepicker-padding-xs - The padding for extra small size. (default: var(--dds-spacing-200))
 * @cssproperty --dds-timepicker-padding-sm - The padding for small size. (default: var(--dds-spacing-200))
 * @cssproperty --dds-timepicker-padding-lg - The padding for large size. (default: var(--dds-spacing-300))
 * @cssproperty --dds-timepicker-padding-horizontal - The horizontal padding. (default: var(--dds-spacing-300))
 * @cssproperty --dds-timepicker-padding-vertical - The vertical padding. (default: var(--dds-spacing-200))
 * @cssproperty --dds-timepicker-gap - The gap between elements. (default: var(--dds-spacing-100))
 * @cssproperty --dds-timepicker-icon-gap - The gap between icons. (default: var(--dds-spacing-200))
 * @cssproperty --dds-timepicker-action-gap - The gap between action elements. (default: var(--dds-spacing-200))
 * @cssproperty --dds-timepicker-action-padding - The padding for action elements. (default: var(--dds-spacing-300))
 * @cssproperty --dds-timepicker-clear-icon-width - The width of the clear icon. (default: var(--dds-spacing-800))
 * @cssproperty --dds-timepicker-dropdown-icon-right - The right position of the dropdown icon. (default: var(--dds-spacing-600))
 * @cssproperty --dds-timepicker-min-width - The minimum width of the timepicker. (default: 7.5rem)
 *
 */
export default class DapDSTimePicker extends GenericFormElement {
    static tagName: string;
    static dependencies: {
        'dap-ds-form-label': typeof DapDSFormLabel;
        'dap-ds-tooltip': typeof DapDSTooltip;
        'dap-ds-icon-button': typeof DapDSIconButton;
        'dap-ds-icon': typeof DapDSIcon;
        'dap-ds-typography': typeof DapDSTypography;
        'dap-ds-popup': typeof DapDSPopup;
        'dap-ds-icon-loading-spinner': typeof SystemLoadingSpinner;
        'dap-ds-icon-time-line': typeof SystemTimeLine;
        'dap-ds-time-grid': typeof DapDSTimeGrid;
        'dap-ds-feedback': typeof DapDSFeedback;
    };
    private static nextId;
    private readonly inputId;
    private readonly labelId;
    private readonly descriptionId;
    private readonly triggerInput;
    private readonly timeGrid;
    /** The value of the timepicker (selected time).
     * @type {Dayjs | string | Date | number}
     */
    value?: Dayjs | string | Date | number;
    private _timeValue?;
    private get timeValue();
    private set timeValue(value);
    /** The minimum time of the timepicker. This time will be the minimum selectable time.
     * @type {string}
     * @default '00:00'
     */
    minTime: string;
    /** The maximum time of the timepicker. This time will be the maximum selectable time.
     * @type {string}
     * @default '23:59'
     */
    maxTime: string;
    /** The step interval in minutes for the time input.
     * @type {number}
     * @default 5
     */
    step: number;
    /** The placement of the dropdown of the timepicker.
     * @type {'top-start' | 'top' | 'top-end' | 'right-start' | 'right' | 'right-end' | 'bottom-start' | 'bottom' | 'bottom-end' | 'left-start' | 'left' | 'left-end'}
     */
    placement: PopupPlacement;
    /** The open state of the timepicker. */
    opened: boolean;
    /** Whether the time picker should open on typing. */
    openTimeOnInput: boolean;
    /** Whether the time picker should send an empty event on typing. */
    sendEmptyEventOnInput: boolean;
    /** The placeholder of the timepicker. */
    placeholder: string | null;
    /** The loading state of the timepicker. */
    loading?: boolean;
    /** The format of the timepicker. This is the time format used for display and validation.
     * @type {string}
     * @default 'HH:mm'
     */
    format: string;
    /** Whether the clear button should be shown. */
    clearButton?: string;
    /** The aria label of the clear button. */
    clearButtonAriaLabel?: string;
    /** `data-testid` for the clear button. */
    clearButtonTestId: string;
    /** `data-testid` for the time indicator button that opens the grid. */
    timeButtonTestId: string;
    /** The floating strategy of the timepicker. */
    floatingStrategy: FloatingStrategy;
    /** Whether to keep popup open when trigger leaves viewport. */
    disableViewportAutoClose: boolean;
    /** The locale of the timepicker. By default it uses the global locale from dayjs.
     * @type {'hu' | 'en' | 'de'}
     */
    locale: string;
    /** Whether the dropdown should close when a time is selected. */
    closeOnSelection: boolean;
    /** Whether to show the seconds column in the time picker. */
    showSeconds: boolean;
    /** The step interval in seconds for the time input.
     * @type {number}
     * @default 1
     */
    secondsStep: number;
    /** Callback function to determine if a specific time should be disabled.
     * @param {number} hour - The hour to check (0-23)
     * @param {number} minute - The minute to check (0-59)
     * @param {number} second - The second to check (0-59, optional)
     * @returns {boolean} True if the time should be disabled
     */
    disabledTime?: (hour: number, minute: number, second?: number) => boolean;
    /** Whether to hide disabled times from the grid or show them as disabled.
     * @type {boolean}
     * @default false
     */
    hideDisabledTimes: boolean;
    /** Array of preset time slots for quick selection.
     * @type {TimePreset[]}
     */
    presets?: TimePreset[];
    private setValueState;
    static readonly styles: import('lit').CSSResult;
    private languageChangeHandler;
    constructor();
    connectedCallback(): void;
    disconnectedCallback(): void;
    protected firstUpdated(_changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>): void;
    attributeChangedCallback(name: string, oldValue: any, newValue: any): void;
    /**
     * Normalizes a time value to a Dayjs object.
     * Handles Dayjs objects, Date objects, strings (HH:mm or HH:mm:ss format, or date strings), and undefined/null.
     */
    private normalizeTime;
    private syncTimeValue;
    protected updated(_changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>): void;
    private updateTimeGridSelection;
    private getHourValue;
    private getMinuteValue;
    private getSecondValue;
    getFormattedValue(): string;
    isValidTime(value: string): boolean;
    isValueValid(): boolean;
    isInputValid(): boolean;
    setValue(value?: Dayjs, setInputValue?: boolean, sendEmptyEventOnInput?: boolean): void;
    clearSelection(): Promise<void>;
    private readonly handleDocumentMouseDown;
    private readonly handlePopupAutoClose;
    private readonly handleInput;
    private readonly handleKeyDown;
    get focusElement(): HTMLInputElement;
    private readonly handleClick;
    private readonly handleClearClick;
    private readonly handleTimeChange;
    showTimePicker(): Promise<void>;
    hideTimePicker(options?: {
        skipFocus?: boolean;
    }): Promise<void>;
    private readonly handleFocus;
    private readonly handleBlur;
    private readonly handlePopupOpened;
    getValidity(): boolean;
    get validity(): ValidityState;
    checkValidity(): boolean;
    reportValidity(): boolean;
    setValidity(): void;
    handleInvalid(event: Event): void;
    render(): import('lit-html').TemplateResult;
}