feat(ui5-date-picker): add valueFormat and displayFormat (#11751)

Add support for separate value and display formatting in DatePicker component.

Add valueFormat property to control internal value representation
Add displayFormat property to control user-visible date format
Maintain backward compatibility with existing formatPattern usage
Enable decoupling of data format from presentation format
This addresses the limitation where value and display formats were
tightly coupled, allowing developers to store dates in standardized
formats (e.g., ISO 8601) while presenting them in user-friendly
formats (e.g., "Jan 1st, 2020").

Closes #1957

Author: tsanislavgatev

packages/main/cypress/specs/DatePicker.cy.tsx

@@ -78,6 +78,28 @@ describe("Date Picker Tests", () => {
 			.should("have.attr", "value-state", "None");
 	});
 
+	it("custom formatting", () => {
+		cy.mount(<DatePicker displayFormat="yyyy, dd/MM" valueFormat="yyyy-MM-dd"></DatePicker>);
+
+		cy.get("[ui5-date-picker]")
+			.as("datePicker");
+
+		cy.get<DatePicker>("@datePicker")
+			.ui5DatePickerGetInnerInput()
+			.realClick()
+			.should("be.focused")
+			.realType("2018, 05/05")
+			.realPress("Enter");
+
+		cy.get("@datePicker")
+			.shadow()
+			.find("ui5-datetime-input")
+			.should("have.attr", "value", "2018, 05/05");
+
+		cy.get("@datePicker")
+			.should("have.attr", "value", "2018-05-05");
+	});
+
 	it("value state", () => {
 		cy.mount(<DatePicker></DatePicker>);
 		cy.get("[ui5-date-picker]")

packages/main/cypress/specs/DateRangePicker.cy.tsx

@@ -64,6 +64,28 @@ describe("DateRangePicker general interaction", () => {
 			.should("have.attr", "value-state", "None");
 	});
 
+	it("custom formatting", () => {
+		cy.mount(<DateRangePicker displayFormat="dd/MM/yyyy" valueFormat="yyyy-MM-dd"></DateRangePicker>);
+
+		cy.get("[ui5-daterange-picker]")
+			.as("dateRangePicker");
+
+		cy.get<DateRangePicker>("@dateRangePicker")
+			.ui5DatePickerGetInnerInput()
+			.realClick()
+			.should("be.focused")
+			.realType("05/05/2018 - 06/06/2018")
+			.realPress("Enter");
+
+		cy.get("@dateRangePicker")
+			.shadow()
+			.find("ui5-datetime-input")
+			.should("have.attr", "value", "05/05/2018 - 06/06/2018");
+
+		cy.get("@dateRangePicker")
+			.should("have.attr", "value", "2018-05-05 - 2018-06-06");
+	});
+
 	it("Selected dates are updated after value update in the input field", () => {
 		cy.mount(<DateRangePickerTemplate formatPattern="dd/MM/yyyy" />);
 

packages/main/cypress/specs/DateTimePicker.cy.tsx

@@ -418,6 +418,28 @@ describe("DateTimePicker general interaction", () => {
 			.and("have.attr", "value", "");
 	});
 
+	it("custom formatting", () => {
+		cy.mount(<DateTimePicker displayFormat="yyyy, dd/MM hh:mm:ss" valueFormat="yyyy-MM-dd hh:mm:ss"></DateTimePicker>);
+
+		cy.get("[ui5-datetime-picker]")
+			.as("dateTimePicker");
+
+		cy.get<DateTimePicker>("@dateTimePicker")
+			.ui5DatePickerGetInnerInput()
+			.realClick()
+			.should("be.focused")
+			.realType("2018, 05/05 12:00:00")
+			.realPress("Enter");
+
+		cy.get("@dateTimePicker")
+			.shadow()
+			.find("ui5-datetime-input")
+			.should("have.attr", "value", "2018, 05/05 12:00:00");
+
+		cy.get("@dateTimePicker")
+			.should("have.attr", "value", "2018-05-05 12:00:00");
+	});
+
 	it("Min and max dates are set, with no format pattern provided, using valid ISO format", () => {
 		cy.mount(
 			<DateTimePickerTemplate minDate="2023-05-01" maxDate="2023-05-31" />

packages/main/src/DateComponentBase.ts

@@ -55,11 +55,30 @@ class DateComponentBase extends UI5Element {
 	/**
 	 * Determines the format, displayed in the input field.
 	 * @default undefined
+	 * @deprecated
 	 * @public
 	 */
 	@property()
 	formatPattern?: string;
 
+	/**
+	 * Determines the format, displayed in the input field.
+	 * @default undefined
+	 * @since 2.14.0
+	 * @public
+	 */
+	@property()
+	displayFormat?: string;
+
+	/**
+	 * Determines the format, used for the value attribute.
+	 * @default undefined
+	 * @since 2.14.0
+	 * @public
+	 */
+	@property()
+	valueFormat?: string;
+
 	/**
 	 * Determines the minimum date available for selection.
 	 *
@@ -143,6 +162,14 @@ class DateComponentBase extends UI5Element {
 		return this._formatPattern !== "medium" && this._formatPattern !== "short" && this._formatPattern !== "long";
 	}
 
+	get _isValueFormatPattern() {
+		return this._valueFormat !== "medium" && this._valueFormat !== "short" && this._valueFormat !== "long";
+	}
+
+	get _isDisplayFormatPattern() {
+		return this._displayFormat !== "medium" && this._displayFormat !== "short" && this._displayFormat !== "long";
+	}
+
 	get hasSecondaryCalendarType() {
 		return !!this.secondaryCalendarType && this.secondaryCalendarType !== this.primaryCalendarType;
 	}
@@ -159,7 +186,14 @@ class DateComponentBase extends UI5Element {
 	}
 
 	_getCalendarDateFromString(value: string) {
-		const jsDate = this.getFormat().parse(value) as Date;
+		const jsDate = this.getValueFormat().parse(value) as Date;
+		if (jsDate) {
+			return CalendarDate.fromLocalJSDate(jsDate, this._primaryCalendarType);
+		}
+	}
+
+	_getCalendarDateFromStringDisplayValue(value: string) {
+		const jsDate = this.getDisplayFormat().parse(value) as Date;
 		if (jsDate) {
 			return CalendarDate.fromLocalJSDate(jsDate, this._primaryCalendarType);
 		}
@@ -173,10 +207,32 @@ class DateComponentBase extends UI5Element {
 	}
 
 	_getStringFromTimestamp(timestamp: number) {
+		if (!timestamp) {
+			return "";
+		}
+
 		const localDate = UI5Date.getInstance(timestamp);
 		return this.getFormat().format(localDate, true);
 	}
 
+	_getDisplayStringFromTimestamp(timestamp: number) {
+		if (!timestamp) {
+			return "";
+		}
+
+		const localDate = UI5Date.getInstance(timestamp);
+		return this.getDisplayFormat().format(localDate, true);
+	}
+
+	_getValueStringFromTimestamp(timestamp: number) {
+		if (!timestamp) {
+			return "";
+		}
+
+		const localDate = UI5Date.getInstance(timestamp);
+		return this.getValueFormat().format(localDate, true);
+	}
+
 	getFormat() {
 		return this._isPattern
 			? DateFormat.getDateInstance({
@@ -191,6 +247,58 @@ class DateComponentBase extends UI5Element {
 			});
 	}
 
+	get _displayFormat() {
+		if (this.displayFormat) {
+			return this.displayFormat;
+		}
+
+		return this._formatPattern;
+	}
+
+	get _valueFormat() {
+		if (this.valueFormat) {
+			return this.valueFormat;
+		}
+
+		if (this._formatPattern) {
+			return this._formatPattern;
+		}
+
+		return "";
+	}
+
+	getDisplayFormat() {
+		return this._isDisplayFormatPattern
+			? DateFormat.getDateInstance({
+				strictParsing: true,
+				pattern: this._displayFormat,
+				calendarType: this._primaryCalendarType,
+			})
+			: DateFormat.getDateInstance({
+				strictParsing: true,
+				style: this._displayFormat,
+				calendarType: this._primaryCalendarType,
+			});
+	}
+
+	getValueFormat() {
+		if (!this._valueFormat) {
+			return this.getISOFormat();
+		}
+
+		return this._isValueFormatPattern
+			? DateFormat.getDateInstance({
+				strictParsing: true,
+				pattern: this._valueFormat,
+				calendarType: this._primaryCalendarType,
+			})
+			: DateFormat.getDateInstance({
+				strictParsing: true,
+				style: this._valueFormat,
+				calendarType: this._primaryCalendarType,
+			});
+	}
+
 	getISOFormat() {
 		if (!this._isoFormatInstance) {
 			this._isoFormatInstance = DateFormat.getDateInstance({