time-pickerpackage.src.vaadin-time-picker.d.ts Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of vaadin-webcomponents Show documentation
Show all versions of vaadin-webcomponents Show documentation
Mvnpm composite: Vaadin webcomponents
The newest version!
/**
* @license
* Copyright (c) 2018 - 2024 Vaadin Ltd.
* This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
*/
import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
import { InputControlMixin } from '@vaadin/field-base/src/input-control-mixin.js';
import { PatternMixin } from '@vaadin/field-base/src/pattern-mixin.js';
import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
export interface TimePickerTime {
hours: number | string;
minutes: number | string;
seconds?: number | string;
milliseconds?: number | string;
}
export interface TimePickerI18n {
parseTime(time: string): TimePickerTime | undefined;
formatTime(time: TimePickerTime | undefined): string;
}
/**
* Fired when the user commits a value change.
*/
export type TimePickerChangeEvent = Event & {
target: TimePicker;
};
/**
* Fired when the `invalid` property changes.
*/
export type TimePickerInvalidChangedEvent = CustomEvent<{ value: boolean }>;
/**
* Fired when the `opened` property changes.
*/
export type TimePickerOpenedChangedEvent = CustomEvent<{ value: boolean }>;
/**
* Fired when the `value` property changes.
*/
export type TimePickerValueChangedEvent = CustomEvent<{ value: string }>;
/**
* Fired whenever the field is validated.
*/
export type TimePickerValidatedEvent = CustomEvent<{ valid: boolean }>;
export interface TimePickerCustomEventMap {
'invalid-changed': TimePickerInvalidChangedEvent;
'opened-changed': TimePickerOpenedChangedEvent;
'value-changed': TimePickerValueChangedEvent;
validated: TimePickerValidatedEvent;
}
export interface TimePickerEventMap extends HTMLElementEventMap, TimePickerCustomEventMap {
change: TimePickerChangeEvent;
}
/**
* `` is a Web Component providing a time-selection field.
*
* ```html
* ` provides the same set of shadow DOM parts and state attributes as ``.
* See [``](#/elements/vaadin-text-field) for the styling documentation.
*
* In addition to `` parts, the following parts are available for theming:
*
* Part name | Description
* ----------------|----------------
* `toggle-button` | The toggle button
*
* In addition to `` state attributes, the following state attributes are available for theming:
*
* Attribute | Description
* ----------|------------------------------------------
* `opened` | Set when the time-picker dropdown is open
*
* ### Internal components
*
* In addition to `` itself, the following internal
* components are themable:
*
* - `` - has the same API as [``](#/elements/vaadin-combo-box-light).
* - `` - has the same API as [``](#/elements/vaadin-overlay).
* - `` - has the same API as [``](#/elements/vaadin-item).
* - [``](#/elements/vaadin-input-container) - an internal element wrapping the input.
*
* Note: the `theme` attribute value set on `` is
* propagated to the internal components listed above.
*
* See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
*
* ### Change events
*
* Depending on the nature of the value change that the user attempts to commit e.g. by pressing Enter,
* the component can fire either a `change` event or an `unparsable-change` event:
*
* Value change | Event
* :------------------------|:------------------
* empty => parsable | change
* empty => unparsable | unparsable-change
* parsable => empty | change
* parsable => parsable | change
* parsable => unparsable | change
* unparsable => empty | unparsable-change
* unparsable => parsable | change
* unparsable => unparsable | unparsable-change
*
* @fires {Event} change - Fired when the user commits a value change.
* @fires {CustomEvent} invalid-changed - Fired when the `invalid` property changes.
* @fires {CustomEvent} opened-changed - Fired when the `opened` property changes.
* @fires {CustomEvent} value-changed - Fired when the `value` property changes.
* @fires {CustomEvent} validated - Fired whenever the field is validated.
*/
declare class TimePicker extends PatternMixin(InputControlMixin(ThemableMixin(ElementMixin(HTMLElement)))) {
/**
* The time value for this element.
*
* Supported time formats are in ISO 8601:
* - `hh:mm` (default)
* - `hh:mm:ss`
* - `hh:mm:ss.fff`
*/
value: string;
/**
* True if the dropdown is open, false otherwise.
*/
opened: boolean;
/**
* Minimum time allowed.
*
* Supported time formats are in ISO 8601:
* - `hh:mm`
* - `hh:mm:ss`
* - `hh:mm:ss.fff`
*/
min: string;
/**
* Maximum time allowed.
*
* Supported time formats are in ISO 8601:
* - `hh:mm`
* - `hh:mm:ss`
* - `hh:mm:ss.fff`
*/
max: string;
/**
* Specifies the number of valid intervals in a day used for
* configuring the items displayed in the selection box.
*
* It also configures the precision of the value string. By default
* the component formats values as `hh:mm` but setting a step value
* lower than one minute or one second, format resolution changes to
* `hh:mm:ss` and `hh:mm:ss.fff` respectively.
*
* Unit must be set in seconds, and for correctly configuring intervals
* in the dropdown, it need to evenly divide a day.
*
* Note: it is possible to define step that is dividing an hour in inexact
* fragments (i.e. 5760 seconds which equals 1 hour 36 minutes), but it is
* not recommended to use it for better UX experience.
*/
step: number | null | undefined;
/**
* Set true to prevent the overlay from opening automatically.
* @attr {boolean} auto-open-disabled
*/
autoOpenDisabled: boolean | null | undefined;
/**
* A space-delimited list of CSS class names to set on the overlay element.
*
* @attr {string} overlay-class
*/
overlayClass: string;
/**
* The object used to localize this component.
* To change the default localization, replace the entire
* _i18n_ object or just the property you want to modify.
*
* The object has the following JSON structure:
*
* ```
* {
* // A function to format given `Object` as
* // time string. Object is in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`
* formatTime: (time) => {
* // returns a string representation of the given
* // object in `hh` / 'hh:mm' / 'hh:mm:ss' / 'hh:mm:ss.fff' - formats
* },
*
* // A function to parse the given text to an `Object` in the format
* // `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`.
* // Must properly parse (at least) text
* // formatted by `formatTime`.
* parseTime: text => {
* // Parses a string in object/string that can be formatted by`formatTime`.
* }
* }
* ```
*
* Both `formatTime` and `parseTime` need to be implemented
* to ensure the component works properly.
*/
i18n: TimePickerI18n;
/**
* Opens the dropdown list.
*/
open(): void;
/**
* Closes the dropdown list.
*/
close(): void;
addEventListener(
type: K,
listener: (this: TimePicker, ev: TimePickerEventMap[K]) => void,
options?: AddEventListenerOptions | boolean,
): void;
removeEventListener(
type: K,
listener: (this: TimePicker, ev: TimePickerEventMap[K]) => void,
options?: EventListenerOptions | boolean,
): void;
}
declare global {
interface HTMLElementTagNameMap {
'vaadin-time-picker': TimePicker;
}
}
export { TimePicker };