dap-design-system
Version:
Official design system for the DÁP (dap.gov.hu)
241 lines (240 loc) • 14 kB
TypeScript
import { Dayjs } from 'dayjs';
import { PropertyValueMap } from 'lit';
import { FloatingStrategy, PopupPlacement } from '../../common/types';
import { GenericFormElement } from '../../internal/mixin/genericFormElement';
import { default as DapDSCalendar } from '../calendar/calendar.component';
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 BusinessCalendarLine } from '../icons/business/business-calendar-line/business-calendar-line.component';
import { default as SystemLoadingSpinner } from '../icons/system/system-loading-spinner/system-loading-spinner.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';
/**
* `dap-ds-datepicker`
* @summary A datepicker is a graphical user interface widget that allows the user to select a date from a calendar and/or time from a time range.
* @element dap-ds-datepicker
* @title - Datepicker
*
* @property {Dayjs} value - The value of the datepicker.
* @property {string} label - The label of the datepicker.
* @property {boolean} hideLabel - Visually hides the label while keeping it available to assistive technology. (default: false)
* @property {string} description - The description of the datepicker.
* @property {'xs' | 'sm' | 'sm'} size - The size of the datepicker.
* @property {boolean} disabled - The disabled state of the datepicker.
* @property {boolean} required - The required state of the datepicker.
* @property {boolean} readonly - The readonly state of the datepicker.
* @property {boolean} autofocus - The autofocus state of the datepicker.
* @property {string} tooltip - The tooltip of the datepicker.
* @property {'top' | 'right' | 'bottom' | 'left'} tooltipPlacement - The tooltip placement of the datepicker.
* @property {string} feedback - The feedback of the datepicker.
* @property {'negative' | 'positive' | 'warning'} feedbackType - The feedback type of the datepicker.
* @property {boolean} optional - The optional state of the datepicker.
* @property {string} optionalLabel - The optional label of the datepicker.
* @property {string} requiredLabel - The required indicator of the datepicker. (default: '*')
* @property {boolean} subtle - The weight of the label. Default is `false`
* @property {string} autocomplete - The autocomplete of the datepicker.
* @property {boolean} autofocus - The autofocus of the datepicker.
*
* @event {{ value: string }} dds-change - Fired when the datepicker value changes.
* @event {{ value: string }} dds-input - Fired when the datepicker input value changes.
* @event {{ value: string }} dds-valid-date - Fired when the datepicker input value is valid. Happens on manual input typing.
* @event {{ value: string, type: 'invalid' | 'out-of-range' }} dds-invalid-date - Fired when the datepicker input value is invalid. Happens on manual input typing.
* @event {{ void }} dds-clear - Fired when the datepicker is cleared.
* @event {{ void }} dds-focus - Emitted when the datepicker gains focus.
* @event {{ void }} dds-blur - Emitted when the datepicker loses focus.
*
* @csspart base - The main datepicker container.
* @csspart calendar - The calendar of the datepicker.
* @csspart trigger - The trigger button of the datepicker.
* @csspart label - The label of the datepicker.
* @csspart description - The description of the datepicker.
* @csspart feedback - The feedback of the datepicker.
* @csspart tooltip - The tooltip of the datepicker.
* @csspart input - The input of the datepicker.
* @csspart clear-button - The clear button of the datepicker.
* @csspart calendar-grid-cell-base - The base of the calendar grid cell.
* @csspart calendar-grid-cell - The cell of the calendar grid.
* @csspart calendar-grid-header-cell-base - The base of the calendar grid header cell.
* @csspart calendar-grid-header-cell - The header cell of the calendar grid.
* @csspart calendar-grid-cell-today-mark - The today mark of the calendar grid cell.
*
* @cssproperty --dds-combobox-background - The background color of the combobox. (default: var(--dds-fields-background-default))
* @cssproperty --dds-combobox-border-color - The border color of the combobox. (default: var(--dds-border-neutral-base))
* @cssproperty --dds-combobox-border-width - The border width of the combobox. (default: var(--dds-border-width-base, 1px))
* @cssproperty --dds-combobox-border-radius - The border radius of the combobox. (default: var(--dds-radius-base))
* @cssproperty --dds-combobox-text-color - The text color of the combobox. (default: var(--dds-text-neutral-base))
* @cssproperty --dds-combobox-placeholder-color - The placeholder text color. (default: var(--dds-text-neutral-subtle))
* @cssproperty --dds-combobox-disabled-background - The background color when disabled. (default: var(--dds-background-neutral-stronger))
* @cssproperty --dds-combobox-disabled-text - The text color when disabled. (default: var(--dds-text-neutral-disabled))
* @cssproperty --dds-combobox-error-border - The border color for error state. (default: var(--dds-border-negative-base))
* @cssproperty --dds-combobox-success-border - The border color for success state. (default: var(--dds-border-positive-base))
* @cssproperty --dds-combobox-icon-color - The color of the icons. (default: var(--dds-text-icon-neutral-subtle))
* @cssproperty --dds-combobox-clear-icon-color - The color of the clear icon. (default: var(--dds-button-subtle-icon-neutral-enabled))
* @cssproperty --dds-combobox-popup-background - The background color of the popup. (default: var(--dds-background-neutral-subtle))
* @cssproperty --dds-combobox-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-combobox-padding-xs - The padding for extra small size. (default: var(--dds-spacing-200))
* @cssproperty --dds-combobox-padding-sm - The padding for small size. (default: var(--dds-spacing-200))
* @cssproperty --dds-combobox-padding-lg - The padding for large size. (default: var(--dds-spacing-300))
* @cssproperty --dds-combobox-padding-horizontal - The horizontal padding. (default: var(--dds-spacing-300))
* @cssproperty --dds-combobox-padding-vertical - The vertical padding. (default: var(--dds-spacing-200))
* @cssproperty --dds-combobox-gap - The gap between elements. (default: var(--dds-spacing-100))
* @cssproperty --dds-combobox-icon-gap - The gap between icons. (default: var(--dds-spacing-200))
* @cssproperty --dds-combobox-action-gap - The gap between action elements. (default: var(--dds-spacing-200))
* @cssproperty --dds-combobox-action-padding - The padding for action elements. (default: var(--dds-spacing-300))
* @cssproperty --dds-combobox-clear-icon-width - The width of the clear icon. (default: var(--dds-spacing-800))
* @cssproperty --dds-combobox-dropdown-icon-right - The right position of the dropdown icon. (default: var(--dds-spacing-600))
* @cssproperty --dds-combobox-min-width - The minimum width of the combobox. (default: 7.5rem)
*/
export default class DapDSDatePicker 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-calendar-line': typeof BusinessCalendarLine;
'dap-ds-calendar': typeof DapDSCalendar;
'dap-ds-feedback': typeof DapDSFeedback;
};
private static nextId;
/**
* Property converter for date properties.
* Converts string attributes (from React) to Dayjs objects.
* Allows both attribute binding (strings) and property binding (Dayjs objects).
*
* Note: When properties are set directly (bypassing attributes), they are normalized
* in the `updated` lifecycle method via `normalizeDate`.
*/
private static datePropertyConverter;
private readonly inputId;
private readonly labelId;
private readonly descriptionId;
private readonly triggerInput;
private readonly calendar;
private readonly popup;
/** The value of the datepicker (selected date in single mode).
* @type {Dayjs}
*/
value?: Dayjs;
/** The mode of the datepicker - single date or range selection.
* @type {'single' | 'range'}
* @default 'single'
*/
mode: 'single' | 'range';
/** The current visible date (month and year) of the calendar. Only the month and year are considered.
* @type {Dayjs | string | Date}
* @default dayjs()
*/
currentDate?: Dayjs | string | Date;
/** The minimum date (month and year) of the datepicker. Only the month and year are considered.
* @type {Dayjs | string | Date}
* @default dayjs('1901-01-01')
*/
minDate?: Dayjs | string | Date;
/** The maximum date (month and year) of the datepicker. Only the month and year are considered.
* @type {Dayjs | string | Date}
* @default dayjs('2099-12-31')
*/
maxDate?: Dayjs | string | Date;
/** The disabled date of the datepicker. This function will be called for each date to determine if it is disabled.
* @type {(date: Dayjs) => boolean}
* @default (date: Dayjs) => false
*/
disabledDate: (date: Dayjs) => boolean;
/** The start date of the range selection (only used in range mode).
* @type {Dayjs | string | Date}
*/
rangeStart?: Dayjs | string | Date;
/** The end date of the range selection (only used in range mode).
* @type {Dayjs | string | Date}
*/
rangeEnd?: Dayjs | string | Date;
/** The placement of the dropdown of the datepicker.
* @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 datepicker. */
opened: boolean;
/** Wheter the calendar should open on typing. */
openCalendarOnInput: boolean;
/** Wheter the calendar should send an empty event on typing. */
sendEmptyEventOnInput: boolean;
/** The placeholder of the datepicker. */
placeholder: string | null;
/** The loading state of the datepicker. */
loading?: boolean;
/** Whether to enable input masking. When active, only digit characters are accepted and format separators are auto-inserted after each complete digit group. Only works in single mode with a single configured format. */
mask: boolean;
/** The format of the datepicker. This is a comma separated list of [formats](https://day.js.org/docs/en/display/format). */
format?: string;
/** The format separator character in the format attribute. */
formatSeparator: 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 calendar indicator button that opens the calendar. */
calendarButtonTestId: string;
/** The floating strategy of the datepicker. */
floatingStrategy: FloatingStrategy;
/** Whether to keep popup open when trigger leaves viewport. */
disableViewportAutoClose: boolean;
/** The locale of the datepicker. By default it uses the global locale from dayjs. It is determined from the browser language.
* @type {'hu' | 'en' | 'de'}
*/
locale: string;
/** Whether to hide dates from adjacent months (previous/next) in the calendar grid. When not explicitly set, defaults to `false` for single mode and `true` for range mode.
* @type {boolean}
*/
hideAdjacentMonths?: boolean;
private formatOptions;
private setValueState;
private lastMaskDigitCount;
static readonly styles: import('lit').CSSResult;
constructor();
/**
* Normalizes a date value to a Dayjs object.
* Handles Dayjs objects, timestamps (numbers or strings), strings, Date objects, and undefined/null.
*/
private normalizeDate;
protected firstUpdated(_changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>): void;
protected updated(_changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>): void;
getFormattedValue(): string;
isValidFormat(value: string): boolean;
isValueValid(): boolean;
isInputValid(): boolean;
setValue(value?: Dayjs, setInputValue?: boolean, sendEmptyEventOnInput?: boolean): void;
clearSelection(): Promise<void>;
private isMaskActive;
private getActiveMaskFormat;
private parseMaskTokens;
private buildMaskedValue;
private readonly handleDocumentMouseDown;
private readonly handlePopupAutoClose;
private readonly handleInput;
private readonly handleKeyDown;
get focusElement(): HTMLInputElement;
private readonly handleClick;
private readonly handleClearClick;
showCalendar(): Promise<void>;
hideCalendar(options?: {
skipFocus?: boolean;
}): Promise<void>;
private readonly handleFocus;
private readonly handleBlur;
getValidity(): boolean;
get validity(): ValidityState;
checkValidity(): boolean;
reportValidity(): boolean;
setValidity(): void;
handleInvalid(event: Event): void;
render(): import('lit-html').TemplateResult;
}