feat(ui5-date-picker): preventable change and input events (#3609)

In this change we introduce the preventable behaviour of the change event in the DatePicker control.
This change will allow the application developers to control the whole value setting and value validation, this means that they will receive this event before we set the value and the value state and will have the possibility to prevent our setters and validators and update the value and the value state themselves.

Fixes: #3516
Closes:  #3516

packages/main/src/DatePicker.js

@@ -230,17 +230,41 @@ const metadata = {
 		 * Fired when the input operation has finished by pressing Enter or on focusout.
 		 *
 		 * @event
+		 * @allowPreventDefault
 		 * @public
+		 * @param {String} value The submitted value.
+		 * @param {Boolean} valid Indicator if the value is in correct format pattern and in valid range.
 		*/
-		change: {},
+		change: {
+			details: {
+				value: {
+					type: String,
+				},
+				valid: {
+					type: Boolean,
+				},
+			},
+		},
 
 		/**
 		 * Fired when the value of the <code>ui5-date-picker</code> is changed at each key stroke.
 		 *
 		 * @event
+		 * @allowPreventDefault
 		 * @public
+		 * @param {String} value The submitted value.
+		 * @param {Boolean} valid Indicator if the value is in correct format pattern and in valid range.
 		*/
-		input: {},
+		input: {
+			details: {
+				value: {
+					type: String,
+				},
+				valid: {
+					type: Boolean,
+				},
+			},
+		},
 	},
 };
 
@@ -478,14 +502,22 @@ class DatePicker extends DateComponentBase {
 			value = this.normalizeValue(value); // transform valid values (in any format) to the correct format
 		}
 
+		let executeEvent = true;
+
+		events.forEach(event => {
+			if (!this.fireEvent(event, { value, valid }, true)) {
+				executeEvent = false;
+			}
+		});
+
+		if (!executeEvent) {
+			return;
+		}
+
 		if (updateValue) {
 			this.value = value;
 			this._updateValueState(); // Change the value state to Error/None, but only if needed
 		}
-
-		events.forEach(event => {
-			this.fireEvent(event, { value, valid });
-		});
 	}
 
 	_updateValueState() {

packages/main/test/pages/DatePicker.html

@@ -57,6 +57,14 @@ <h3>placeholder + title + events</h3>
 		<ui5-label id="lblChange">change: N/A</ui5-label><br/>
 		<ui5-label id="lblLiveChange">input: N/A</ui5-label><br/>
 
+		<h3>placeholder + title + prevented default events</h3>
+		<ui5-date-picker id='dpPrevent'
+			placeholder='Delivery Date...'
+			title='Delivery Date!'>
+		</ui5-date-picker>
+		<ui5-label id="lblChangePrevent">change: N/A</ui5-label><br/>
+		<ui5-label id="lblLiveChangePrevent">input: N/A</ui5-label><br/>
+
 		<h3>format-pattern - 'short'</h3>
 		<ui5-date-picker id='dp6' format-pattern='short'></ui5-date-picker>
 
@@ -153,6 +161,20 @@ <h3>DatePicker with properties given in the wrong format</h3>
 			labelLiveChange.innerHTML = 'input: ' + JSON.stringify(e.detail);
 		});
 
+		var dpPrevent = document.getElementById('dpPrevent');
+		var labelChangePrevent = document.getElementById('lblChangePrevent');
+		var labelLiveChangePrevent = document.getElementById('lblLiveChangePrevent');
+
+		dpPrevent.addEventListener('ui5-change', function(e) {
+			e.preventDefault();
+			console.log('change: ', e.detail);
+			labelChangePrevent.innerHTML = 'change: ' + JSON.stringify(e.detail);
+		});
+		dpPrevent.addEventListener('ui5-input', function(e) {
+			console.log('input: ', e.detail);
+			labelLiveChangePrevent.innerHTML = 'input: ' + JSON.stringify(e.detail);
+		});
+
 		$('#ui5-datepicker--startDate').on('ui5-input change', (function(e) {
 			var dp = $('#ui5-datepicker--startDate')[0];
 			dp.setAttribute('value-state', e.detail.valid ? 'None' : 'Error');

packages/main/test/pages/DatePicker_test_page.html

@@ -105,7 +105,7 @@ <h3>Test ariaLabel and ariaLabelledBy</h3>
 		document.querySelector("#dp8").addEventListener("ui5-change", increaseCounter);
 		document.querySelector("#dp13").addEventListener("ui5-change", function(e) {
 			document.querySelector('#lblTomorrow').innerHTML = ++counterTomorrow;
-			document.querySelector('#lblTomorrowDate').innerHTML = e.target.value;
+			document.querySelector('#lblTomorrowDate').innerHTML = e.detail.value;
 		});
 
 		var dp16 = document.getElementById('dp16');

packages/main/test/specs/DatePicker.spec.js

@@ -284,7 +284,7 @@ describe("Date Picker Tests", () => {
 
 		// Two change events should be fired and the date should twice normalized
 		assert.equal(lblChangeCounter.getHTML(false), "2", 'change event is being fired twice');
-		assert.equal(lblTomorrowDate.getHTML(false), tomorrowDate, 'tomorrow is normalazid to date twice as well');
+		assert.equal(lblTomorrowDate.getHTML(false), tomorrowDate, 'tomorrow is normalized to date twice as well');
 	});
 
 	it("today value is normalized and correctly rounded to 00:00:00", () => {
@@ -923,4 +923,14 @@ describe("Date Picker Tests", () => {
 
 		assert.equal(datepicker.input.getProperty("valueState"), "Error", "value state of the input is valid");
 	});
+
+	it("focusout fires change but doesn't change the value state if the default behaviour is prevented", () => {
+		datepicker.id = "#dpPrevent";
+
+		datepicker.input.click();
+		datepicker.root.keys("Jan 1, 1999999");
+		browser.$("#dp5").shadow$("ui5-input").shadow$("input").click(); //click elsewhere to focusout
+
+		assert.equal(datepicker.input.getProperty("valueState"), "None", 'the value state is not changed');
+	});
 });