@ui5/webcomponents 0.0.0-d9b978d1d → 0.0.0-da0d3eb88

package/dist/DatePicker.js

@@ -9,7 +9,6 @@ import customElement from "@ui5/webcomponents-base/dist/decorators/customElement
 import property from "@ui5/webcomponents-base/dist/decorators/property.js";
 import slot from "@ui5/webcomponents-base/dist/decorators/slot.js";
 import event from "@ui5/webcomponents-base/dist/decorators/event.js";
-import { getFeature } from "@ui5/webcomponents-base/dist/FeaturesRegistry.js";
 import "@ui5/webcomponents-localization/dist/DateFormat.js";
 import CalendarDate from "@ui5/webcomponents-localization/dist/dates/CalendarDate.js";
 import modifyDateBy from "@ui5/webcomponents-localization/dist/dates/modifyDateBy.js";
@@ -17,13 +16,14 @@ import getRoundedTimestamp from "@ui5/webcomponents-localization/dist/dates/getR
 import getTodayUTCTimestamp from "@ui5/webcomponents-localization/dist/dates/getTodayUTCTimestamp.js";
 import ValueState from "@ui5/webcomponents-base/dist/types/ValueState.js";
 import { getEffectiveAriaLabelText } from "@ui5/webcomponents-base/dist/util/AriaLabelHelper.js";
+import { submitForm } from "@ui5/webcomponents-base/dist/features/InputElementsFormSupport.js";
 import { isPageUp, isPageDown, isPageUpShift, isPageDownShift, isPageUpShiftCtrl, isPageDownShiftCtrl, isShow, isF4, isEnter, isTabNext, isTabPrevious, isF6Next, isF6Previous, } from "@ui5/webcomponents-base/dist/Keys.js";
+import AriaHasPopup from "@ui5/webcomponents-base/dist/types/AriaHasPopup.js";
 import { isPhone, isDesktop } from "@ui5/webcomponents-base/dist/Device.js";
 import CalendarPickersMode from "./types/CalendarPickersMode.js";
 import "@ui5/webcomponents-icons/dist/appointment-2.js";
 import "@ui5/webcomponents-icons/dist/decline.js";
-import HasPopup from "./types/HasPopup.js";
-import { DATEPICKER_OPEN_ICON_TITLE, DATEPICKER_DATE_DESCRIPTION, INPUT_SUGGESTIONS_TITLE } from "./generated/i18n/i18n-defaults.js";
+import { DATEPICKER_OPEN_ICON_TITLE, DATEPICKER_DATE_DESCRIPTION, INPUT_SUGGESTIONS_TITLE, FORM_TEXTFIELD_REQUIRED, } from "./generated/i18n/i18n-defaults.js";
 import DateComponentBase from "./DateComponentBase.js";
 import Icon from "./Icon.js";
 import Button from "./Button.js";
@@ -32,8 +32,8 @@ import Calendar from "./Calendar.js";
 import CalendarDateComponent from "./CalendarDate.js";
 import Input from "./Input.js";
 import InputType from "./types/InputType.js";
+import IconMode from "./types/IconMode.js";
 import DatePickerTemplate from "./generated/templates/DatePickerTemplate.lit.js";
-import DatePickerPopoverTemplate from "./generated/templates/DatePickerPopoverTemplate.lit.js";
 // default calendar for bundling
 import "@ui5/webcomponents-localization/dist/features/calendar/Gregorian.js";
 // Styles
@@ -43,97 +43,101 @@ import ResponsivePopoverCommonCss from "./generated/themes/ResponsivePopoverComm
 /**
  * @class
  *
- * <h3 class="comment-api-title">Overview</h3>
+ * ### Overview
  *
- * The <code>ui5-date-picker</code> component provides an input field with assigned calendar which opens on user action.
- * The <code>ui5-date-picker</code> allows users to select a localized date using touch,
+ * The `ui5-date-picker` component provides an input field with assigned calendar which opens on user action.
+ * The `ui5-date-picker` allows users to select a localized date using touch,
  * mouse, or keyboard input. It consists of two parts: the date input field and the
  * date picker.
  *
- * <h3>Usage</h3>
+ * ### Usage
  *
  * The user can enter a date by:
- * <ul>
- * <li>Using the calendar that opens in a popup</li>
- * <li>Typing it in directly in the input field</li>
- * </ul>
- * <br><br>
+ *
+ * - Using the calendar that opens in a popup
+ * - Typing it in directly in the input field
+ *
  * When the user makes an entry and presses the enter key, the calendar shows the corresponding date.
  * When the user directly triggers the calendar display, the actual date is displayed.
  *
- * <h3>Formatting</h3>
+ * ### Formatting
  *
  * If a date is entered by typing it into
  * the input field, it must fit to the used date format.
- * <br><br>
+ *
  * Supported format options are pattern-based on Unicode LDML Date Format notation.
- * For more information, see <ui5-link target="_blank" href="http://unicode.org/reports/tr35/#Date_Field_Symbol_Table">UTS #35: Unicode Locale Data Markup Language</ui5-link>.
- * <br><br>
- * For example, if the <code>format-pattern</code> is "yyyy-MM-dd",
+ * For more information, see [UTS #35: Unicode Locale Data Markup Language](http://unicode.org/reports/tr35/#Date_Field_Symbol_Table).
+ *
+ * For example, if the `format-pattern` is "yyyy-MM-dd",
  * a valid value string is "2015-07-30" and the same is displayed in the input.
  *
- * <h3>Keyboard Handling</h3>
- * The <code>ui5-date-picker</code> provides advanced keyboard handling.
- * If the <code>ui5-date-picker</code> is focused,
- * you can open or close the drop-down by pressing <code>F4</code>, <code>ALT+UP</code> or <code>ALT+DOWN</code> keys.
- * Once the drop-down is opened, you can use the <code>UP</code>, <code>DOWN</code>, <code>LEFT</code>, <code>RIGHT</code> arrow keys
- * to navigate through the dates and select one by pressing the <code>Space</code> or <code>Enter</code> keys. Moreover you can
+ * ### Keyboard Handling
+ * The `ui5-date-picker` provides advanced keyboard handling.
+ * If the `ui5-date-picker` is focused,
+ * you can open or close the drop-down by pressing [F4], [Alt] + [Up] or [Alt] + [Down] keys.
+ * Once the drop-down is opened, you can use the [Up], [Down], [Left] or [Right] arrow keys
+ * to navigate through the dates and select one by pressing the `Space` or `Enter` keys. Moreover you can
  * use TAB to reach the buttons for changing month and year.
- * <br>
  *
- * If the <code>ui5-date-picker</code> input field is focused and its corresponding picker dialog is not opened,
- * then users can increment or decrement the date referenced by <code>dateValue</code> property
+ * If the `ui5-date-picker` input field is focused and its corresponding picker dialog is not opened,
+ * then users can increment or decrement the date referenced by `dateValue` property
  * by using the following shortcuts:
- * <br>
- * <ul>
- * <li>[PAGEDOWN] - Decrements the corresponding day of the month by one</li>
- * <li>[SHIFT] + [PAGEDOWN] - Decrements the corresponding month by one</li>
- * <li>[SHIFT] + [CTRL] + [PAGEDOWN] - Decrements the corresponding year by one</li>
- * <li>[PAGEUP] - Increments the corresponding day of the month by one</li>
- * <li>[SHIFT] + [PAGEUP] - Increments the corresponding month by one</li>
- * <li>[SHIFT] + [CTRL] + [PAGEUP] - Increments the corresponding year by one</li>
- * </ul>
  *
- * <h3>Calendar types</h3>
+ * - [Page Down] - Decrements the corresponding day of the month by one
+ * - [Shift] + [Page Down] - Decrements the corresponding month by one
+ * - [Shift] + [Ctrl] + [Page Down] - Decrements the corresponding year by one
+ * - [Page Up] - Increments the corresponding day of the month by one
+ * - [Shift] + [Page Up] - Increments the corresponding month by one
+ * - [Shift] + [Ctrl] + [Page Up] - Increments the corresponding year by one
+ *
+ * ### Calendar types
  * The component supports several calendar types - Gregorian, Buddhist, Islamic, Japanese and Persian.
  * By default the Gregorian Calendar is used. In order to use the Buddhist, Islamic, Japanese or Persian calendar,
- * you need to set the <code>primaryCalendarType</code> property and import one or more of the following modules:
- * <br><br>
+ * you need to set the `primaryCalendarType` property and import one or more of the following modules:
+ *
+ * `import "@ui5/webcomponents-localization/dist/features/calendar/Buddhist.js";`
+ *
+ * `import "@ui5/webcomponents-localization/dist/features/calendar/Islamic.js";`
+ *
+ * `import "@ui5/webcomponents-localization/dist/features/calendar/Japanese.js";`
  *
- * <code>import "@ui5/webcomponents-localization/dist/features/calendar/Buddhist.js";</code>
- * <br>
- * <code>import "@ui5/webcomponents-localization/dist/features/calendar/Islamic.js";</code>
- * <br>
- * <code>import "@ui5/webcomponents-localization/dist/features/calendar/Japanese.js";</code>
- * <br>
- * <code>import "@ui5/webcomponents-localization/dist/features/calendar/Persian.js";</code>
- * <br><br>
+ * `import "@ui5/webcomponents-localization/dist/features/calendar/Persian.js";`
  *
- * Or, you can use the global configuration and set the <code>calendarType</code> key:
- * <br>
- * <pre><code>&lt;script data-id="sap-ui-config" type="application/json"&gt;
- * {
- *	"calendarType": "Japanese"
- * }
- * &lt;/script&gt;</code></pre>
+ * Or, you can use the global configuration and set the `calendarType` key:
  *
- * <h3>ES6 Module Import</h3>
+ * ```html
+ * <script data-id="sap-ui-config" type="application/json">
+ * 	{
+ * 		"calendarType": "Japanese"
+ * 	}
+ * <script>
+ * ```
  *
- * <code>import "@ui5/webcomponents/dist/DatePicker";</code>
+ * ### ES6 Module Import
  *
+ * `import "@ui5/webcomponents/dist/DatePicker.js";`
  * @constructor
- * @author SAP SE
- * @alias sap.ui.webc.main.DatePicker
- * @extends sap.ui.webc.main.DateComponentBase
- * @tagname ui5-date-picker
+ * @extends DateComponentBase
  * @public
  */
 let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
+    get formValidityMessage() {
+        return DatePicker_1.i18nBundle.getText(FORM_TEXTFIELD_REQUIRED);
+    }
+    get formValidity() {
+        return { valueMissing: this.required && !this.value };
+    }
+    async formElementAnchor() {
+        return (await this.getFocusDomRefAsync())?.getFocusDomRefAsync();
+    }
+    get formFormattedValue() {
+        return this.value;
+    }
     /**
      * @protected
      */
     onResponsivePopoverAfterClose() {
-        this._isPickerOpen = false;
+        this.open = false;
         if (isPhone()) {
             this.blur(); // close device's keyboard and prevent further typing
         }
@@ -141,26 +145,21 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
             this._getInput()?.focus();
         }
     }
+    onResponsivePopoverBeforeOpen() {
+        this._calendarCurrentPicker = this.firstPicker;
+    }
     onBeforeRendering() {
-        this.FormSupport = getFeature("FormSupport");
         ["minDate", "maxDate"].forEach((prop) => {
             const propValue = this[prop];
             if (!this.isValid(propValue)) {
                 console.warn(`Invalid value for property "${prop}": ${propValue} is not compatible with the configured format pattern: "${this._displayFormat}"`); // eslint-disable-line
             }
         });
-        if (this.FormSupport) {
-            this.FormSupport.syncNativeHiddenInput(this);
-        }
-        else if (this.name) {
-            console.warn(`In order for the "name" property to have effect, you should also: import "@ui5/webcomponents/dist/features/InputElementsFormSupport.js";`); // eslint-disable-line
-        }
         this.value = this.normalizeValue(this.value) || this.value;
         this.liveValue = this.value;
     }
     /**
      * Override in derivatives to change calendar selection mode
-     * @returns {string}
      * @protected
      */
     get _calendarSelectionMode() {
@@ -171,7 +170,6 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
      * Override in derivatives to provide the calendar a timestamp based on their properties
      * By default focus the calendar on the selected date if set, or the current day otherwise
      * @protected
-     * @returns { number } the calendar timestamp
      */
     get _calendarTimestamp() {
         if (this.value && this.dateValueUTC && this._checkValueValidity(this.value)) {
@@ -184,7 +182,6 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
      * Used to provide selectedDates to the calendar based on the component's state
      * Override in derivatives to provide different rules for setting the calendar's selected dates
      * @protected
-     * @returns { array } the selected dates
      */
     get _calendarSelectedDates() {
         if (this.value && this._checkValueValidity(this.value)) {
@@ -195,7 +192,7 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
     _onkeydown(e) {
         if (isShow(e)) {
             e.preventDefault(); // Prevent scroll on Alt/Option + Arrow Up/Down
-            if (this.isOpen()) {
+            if (this.open) {
                 if (!isF4(e)) {
                     this._toggleAndFocusInput();
                 }
@@ -204,15 +201,16 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
                 this._toggleAndFocusInput();
             }
         }
-        if ((this._getInput().isEqualNode(e.target) && this.isOpen()) && (isTabNext(e) || isTabPrevious(e) || isF6Next(e) || isF6Previous(e))) {
-            this.closePicker();
+        const target = e.target;
+        if (target && this.open && this._getInput().id === target.id && (isTabNext(e) || isTabPrevious(e) || isF6Next(e) || isF6Previous(e))) {
+            this._togglePicker();
         }
-        if (this.isOpen()) {
+        if (this.open) {
             return;
         }
         if (isEnter(e)) {
-            if (this.FormSupport) {
-                this.FormSupport.triggerFormSubmit(this);
+            if (this._internals?.form) {
+                submitForm(this);
             }
         }
         else if (isPageUpShiftCtrl(e)) {
@@ -241,10 +239,9 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
         }
     }
     /**
-     *
-     * @param { number } amount
-     * @param { string } unit
-     * @param { boolean } preserveDate whether to preserve the day of the month (f.e. 15th of March + 1 month = 15th of April)
+     * @param amount
+     * @param unit
+     * @param preserveDate whether to preserve the day of the month (f.e. 15th of March + 1 month = 15th of April)
      * @protected
      */
     _modifyDateValue(amount, unit, preserveDate) {
@@ -282,18 +279,14 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
         }
     }
     _updateValueState() {
-        const isValid = this._checkValueValidity(this.value);
-        if (isValid && this.valueState === ValueState.Error) { // If not valid - always set Error regardless of the current value state
-            this.valueState = ValueState.None;
-        }
-        else if (!isValid) { // However if valid, change only Error (but not the others) to None
-            this.valueState = ValueState.Error;
+        const valid = this._checkValueValidity(this.value);
+        const previousValueState = this.valueState;
+        this.valueState = valid ? ValueState.None : ValueState.Negative;
+        const eventPrevented = !this.fireEvent("value-state-change", { valueState: this.valueState, valid }, true);
+        if (eventPrevented) {
+            this.valueState = previousValueState;
         }
     }
-    _toggleAndFocusInput() {
-        this.togglePicker();
-        this._getInput().focus();
-    }
     _getInput() {
         return this.shadowRoot.querySelector("[ui5-input]");
     }
@@ -319,8 +312,7 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
     /**
      * Checks if the provided value is valid and within valid range.
      * @protected
-     * @param { string } value
-     * @returns { boolean }
+     * @param value
      */
     _checkValueValidity(value) {
         if (value === "") {
@@ -330,20 +322,18 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
     }
     _click(e) {
         if (isPhone()) {
-            this.responsivePopover.showAt(this);
+            this.responsivePopover.opener = this;
+            this.responsivePopover.open = true;
             e.preventDefault(); // prevent immediate selection of any item
         }
     }
     /**
      * Checks if a value is valid against the current date format of the DatePicker.
      * @public
-     * @method
-     * @name sap.ui.webc.main.DatePicker#isValid
-     * @param { string } [value=""] A value to be tested against the current date format
-     * @returns { boolean }
+     * @param value A value to be tested against the current date format
      */
-    isValid(value = "") {
-        if (value === "") {
+    isValid(value) {
+        if (value === "" || value === undefined) {
             return true;
         }
         return !!this.getFormat().parse(value);
@@ -351,13 +341,10 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
     /**
      * Checks if a date is between the minimum and maximum date.
      * @public
-     * @method
-     * @name sap.ui.webc.main.DatePicker#isInValidRange
-     * @param { string } [value=""] A value to be checked
-     * @returns { boolean }
+     * @param value A value to be checked
      */
-    isInValidRange(value = "") {
-        if (value === "") {
+    isInValidRange(value) {
+        if (value === "" || value === undefined) {
             return true;
         }
         const calendarDate = this._getCalendarDateFromString(value);
@@ -401,8 +388,7 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
     get accInfo() {
         return {
             "ariaRoledescription": this.dateAriaDescription,
-            "ariaHasPopup": HasPopup.Grid,
-            "ariaAutoComplete": "none",
+            "ariaHasPopup": AriaHasPopup.Grid.toLowerCase(),
             "ariaRequired": this.required,
             "ariaLabel": getEffectiveAriaLabelText(this),
         };
@@ -423,16 +409,29 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
     get _shouldHideHeader() {
         return false;
     }
+    /**
+     * Returns the first picker depending on the CalendarPickerMode
+     */
+    get firstPicker() {
+        const calendarPickerMode = this._calendarPickersMode;
+        let firstPicker = "day";
+        if (calendarPickerMode === CalendarPickersMode.YEAR) {
+            firstPicker = "year";
+        }
+        else if (calendarPickerMode === CalendarPickersMode.MONTH_YEAR) {
+            firstPicker = "month";
+        }
+        return firstPicker;
+    }
     /**
      * Defines whether the value help icon is hidden
      * @private
      */
-    get _ariaHidden() {
-        return isDesktop();
+    get _iconMode() {
+        return isDesktop() ? IconMode.Decorative : IconMode.Interactive;
     }
-    async _respPopover() {
-        const staticAreaItem = await this.getStaticAreaItemDomRef();
-        return staticAreaItem.querySelector("[ui5-responsive-popover]");
+    _respPopover() {
+        return this.shadowRoot.querySelector("[ui5-responsive-popover]");
     }
     _canOpenPicker() {
         return !this.disabled && !this.readonly;
@@ -452,14 +451,14 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
     }
     /**
      * The user selected a new date in the calendar
-     * @param event
+     * @param e
      * @protected
      */
     onSelectedDatesChange(e) {
         e.preventDefault();
-        const newValue = e.detail.values && e.detail.values[0];
+        const newValue = e.detail.selectedValues && e.detail.selectedValues[0];
         this._updateValueAndFireEvents(newValue, true, ["change", "value-changed"]);
-        this.closePicker();
+        this._togglePicker();
     }
     /**
      * The user clicked the "month" button in the header
@@ -475,64 +474,25 @@ let DatePicker = DatePicker_1 = class DatePicker extends DateComponentBase {
     }
     /**
      * Formats a Java Script date object into a string representing a locale date
-     * according to the <code>formatPattern</code> property of the DatePicker instance
+     * according to the `formatPattern` property of the DatePicker instance
      * @public
-     * @method
-     * @name sap.ui.webc.main.DatePicker#formatValue
-     * @param {Date} date A Java Script date object to be formatted as string
-     * @returns {string} The date as string
+     * @param date A Java Script date object to be formatted as string
+     * @returns The date as string
      */
     formatValue(date) {
         return this.getFormat().format(date);
     }
-    /**
-     * Closes the picker.
-     * @public
-     * @method
-     * @name sap.ui.webc.main.DatePicker#closePicker
-     */
-    closePicker() {
-        this.responsivePopover.close();
+    _togglePicker() {
+        this.open = !this.open;
     }
-    /**
-     * Opens the picker.
-     * @public
-     * @async
-     * @method
-     * @name sap.ui.webc.main.DatePicker#openPicker
-     * @returns {Promise} Resolves when the picker is open
-     */
-    async openPicker() {
-        this._isPickerOpen = true;
-        this._calendarCurrentPicker = "day";
-        this.responsivePopover = await this._respPopover();
-        this.responsivePopover.showAt(this);
-    }
-    togglePicker() {
-        if (this.isOpen()) {
-            this.closePicker();
-        }
-        else if (this._canOpenPicker()) {
-            this.openPicker();
-        }
-    }
-    /**
-     * Checks if the picker is open.
-     * @public
-     * @method
-     * @name sap.ui.webc.main.DatePicker#isOpen
-     * @returns {boolean} true if the picker is open, false otherwise
-     */
-    isOpen() {
-        return !!this._isPickerOpen;
+    _toggleAndFocusInput() {
+        this._togglePicker();
+        this._getInput().focus();
     }
     /**
      * Currently selected date represented as a Local JavaScript Date instance.
-     *
      * @public
-     * @readonly
-     * @name sap.ui.webc.main.DatePicker.prototype.dateValue
-     * @type { Date }
+     * @default null
      */
     get dateValue() {
         return this.liveValue ? this.getFormat().parse(this.liveValue) : this.getFormat().parse(this.value);
@@ -575,15 +535,15 @@ __decorate([
 __decorate([
     property({ type: Boolean })
 ], DatePicker.prototype, "hideWeekNumbers", void 0);
+__decorate([
+    property({ type: Boolean })
+], DatePicker.prototype, "open", void 0);
 __decorate([
     property()
 ], DatePicker.prototype, "accessibleName", void 0);
 __decorate([
     property({ defaultValue: "" })
 ], DatePicker.prototype, "accessibleNameRef", void 0);
-__decorate([
-    property({ type: Boolean, noAttribute: true })
-], DatePicker.prototype, "_isPickerOpen", void 0);
 __decorate([
     property({ type: Object })
 ], DatePicker.prototype, "_respPopoverConfig", void 0);
@@ -593,17 +553,14 @@ __decorate([
 __decorate([
     slot({ type: HTMLElement })
 ], DatePicker.prototype, "valueStateMessage", void 0);
-__decorate([
-    slot({ type: HTMLElement })
-], DatePicker.prototype, "formSupport", void 0);
 DatePicker = DatePicker_1 = __decorate([
     customElement({
         tag: "ui5-date-picker",
         languageAware: true,
+        formAssociated: true,
         template: DatePickerTemplate,
-        staticAreaTemplate: DatePickerPopoverTemplate,
-        styles: datePickerCss,
-        staticAreaStyles: [
+        styles: [
+            datePickerCss,
             ResponsivePopoverCommonCss,
             datePickerPopoverCss,
         ],
@@ -618,19 +575,23 @@ DatePicker = DatePicker_1 = __decorate([
     })
     /**
      * Fired when the input operation has finished by pressing Enter or on focusout.
-     *
-     * @event sap.ui.webc.main.DatePicker#change
      * @allowPreventDefault
      * @public
      * @param {string} value The submitted value.
      * @param {boolean} valid Indicator if the value is in correct format pattern and in valid range.
-    */
+     */
     ,
     event("change", {
         detail: {
+            /**
+             * @public
+             */
             value: {
                 type: String,
             },
+            /**
+             * @public
+             */
             valid: {
                 type: Boolean,
             },
@@ -638,19 +599,49 @@ DatePicker = DatePicker_1 = __decorate([
     })
     /**
      * Fired when the value of the component is changed at each key stroke.
-     *
-     * @event sap.ui.webc.main.DatePicker#input
      * @allowPreventDefault
      * @public
      * @param {string} value The submitted value.
      * @param {boolean} valid Indicator if the value is in correct format pattern and in valid range.
-    */
+     */
     ,
     event("input", {
         detail: {
+            /**
+             * @public
+             */
             value: {
                 type: String,
             },
+            /**
+             * @public
+             */
+            valid: {
+                type: Boolean,
+            },
+        },
+    })
+    /**
+     * Fired before the value state of the component is updated internally.
+     * The event is preventable, meaning that if it's default action is
+     * prevented, the component will not update the value state.
+     * @allowPreventDefault
+     * @public
+     * @param {string} valueState The new `valueState` that will be set.
+     * @param {boolean} valid Indicator if the value is in correct format pattern and in valid range.
+     */
+    ,
+    event("value-state-change", {
+        detail: {
+            /**
+             * @public
+             */
+            valueState: {
+                type: String,
+            },
+            /**
+             * @public
+             */
             valid: {
                 type: Boolean,
             },