fix(NcDateTimePicker): handle text input for default formatting

For some locales, the default formatting changes to accommodate the used parsing solution.

Fixes #8635

Signed-off-by: Oleksandr Dzhychko <hey@oleks.dev>

Author: odzhychko

src/components/NcDateTimePicker/NcDateTimePicker.vue

@@ -288,15 +288,17 @@ import {
 	getFirstDay,
 } from '@nextcloud/l10n'
 import VueDatePicker from '@vuepic/vue-datepicker'
+import { parse } from 'date-fns/parse'
 import { computed, useTemplateRef, warn, watchEffect } from 'vue'
 import NcIconSvgWrapper from '../NcIconSvgWrapper/NcIconSvgWrapper.vue'
 import NcTimezonePicker from '../NcTimezonePicker/NcTimezonePicker.vue'
 import { t } from '../../l10n.ts'
 import NcButton from '../NcButton/index.ts'
-import { getDateFormat, getDateRangeFormat, getDateTimeFormat, getDateTimeRangeFormat, getMonthFormat, getTimeFormat, getTimeRangeFormat, getYearFormat } from './format.ts'
+import { getDateFormat, getDateTimeFormat, getMonthFormat, getTimeFormat, getWeekFormat, getYearFormat } from './format.ts'
 import useDateFnsLocale from './useDateFnsLocale.ts'
 
 type LibraryFormatOptions = VueDatePickerProps['format']
+type LibraryTextInputOptions = VueDatePickerProps['textInput']
 
 /**
  * The preselected IANA time zone ID for the time zone picker,
@@ -344,11 +346,13 @@ const props = withDefaults(defineProps<{
 	confirm?: boolean
 
 	/**
-	 * Preview format for the picker input field.
+	 * Format for the picker input field.
 	 * Can either be a string of Unicode tokens or a function that takes a Date object
 	 * or for range picker an array of two dates, and returns the formatted date as string.
 	 *
-	 * @default Intl.DateTimeFormat is used to format dates and times
+	 * If no format is provided, localized date and time formats are used.
+	 * If a function is provided users cannot use text input.
+	 *
 	 * @see https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table
 	 */
 	format?: string | ((date: Date) => string) | ((dates: [Date, Date]) => string)
@@ -545,42 +549,70 @@ const dateFnsLocale = useDateFnsLocale(realLocale)
 
 /**
  * The date (time) formatting to be used by the library.
- * We use the provided format if possible, otherwise we provide a formatting function
- * which uses the browsers Intl API to format the date / time in the current users locale.
+ * We use the provided format if possible, otherwise we provide a localized formatting
+ * using `date-fns/locale' which is mostly similiar to Intl.DateTime formating.
  */
 const realFormat = computed<LibraryFormatOptions>(() => {
 	if (props.format) {
 		// we can cast the type here as in this case its either string
 		// function `(Date) => string` or `([Date, Date]) => string` where we cast to `(Date[]) => string` here.
 		return props.format as LibraryFormatOptions
-	} else if (props.type === 'week') {
-		// cannot format weeks with Intl.
-		return 'RR-II'
 	}
 
 	switch (props.type) {
 		case 'date':
-			return getDateFormat(realLocale)
 		case 'date-range':
-			return getDateRangeFormat(realLocale)
+			return getDateFormat(dateFnsLocale.value)
 		case 'time':
-			return getTimeFormat(realLocale)
 		case 'time-range':
-			return getTimeRangeFormat(realLocale)
+			return getTimeFormat()
 		case 'datetime':
-			return getDateTimeFormat(realLocale)
 		case 'datetime-range':
-			return getDateTimeRangeFormat(realLocale)
+			return getDateTimeFormat(dateFnsLocale.value)
 		case 'month':
-			return getMonthFormat(realLocale)
+			return getMonthFormat(dateFnsLocale.value)
 		case 'year':
-			return getYearFormat(realLocale)
+			return getYearFormat(dateFnsLocale.value)
+		case 'week':
+			return getWeekFormat()
 	}
 
 	// fallback to default formatting
 	return undefined
 })
 
+const textInput = computed<LibraryTextInputOptions>(() => {
+	const realFormatVal = realFormat.value
+	if (typeof realFormatVal === 'function') {
+		// NOTE We could provide a format string through `textInput.format`.
+		// Then Vuepic uses it when the user focuses the input.
+		// But this feature has a bug.
+		// It does not respect the provided locale when formatting.
+		// See https://github.com/Vuepic/vue-datepicker/issues/1286
+		//
+		// Possible workarounds that seem not to be worth implementing for now:
+		// - replace input value when user focuses the input by ourselves
+
+		// Disable text input if user provided a format function.
+		// We do not know how to parse such values.
+		return false
+	}
+
+	if (typeof realFormatVal === 'string') {
+		return {
+			// This should not be required in Vuepic because `format` is automatically used for parsing.
+			// But v11 has a bug because the format string ist cut off wrongly.
+			// This is fixed in v12.1.0 and can then be simplified.
+			// See https://github.com/Vuepic/vue-datepicker/issues/1208
+			format: (value: string) => {
+				return parse(value, realFormatVal, new Date(), { locale: (dateFnsLocale.value) })
+			},
+		}
+	}
+
+	return true
+})
+
 const pickerType = computed(() => ({
 	timePicker: props.type === 'time' || props.type === 'time-range',
 	yearPicker: props.type === 'year',
@@ -808,7 +840,7 @@ function sameDay(a: Date, b: Date): boolean {
 			sixWeeks="fair"
 			:inline
 			:teleport="appendToBody ? (targetElement || undefined) : false"
-			textInput
+			:textInput
 			:weekNumName
 			:weekNumbers="showWeekNumber ? { type: 'iso' } : undefined"
 			:weekStart

src/components/NcDateTimePicker/format.ts

@@ -3,62 +3,121 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-type DateFormat = ((date: Date) => string)
-type DateRangeFormat = ((dates: Date[]) => string)
-type LocaleCode = string
+import type { Locale } from 'date-fns/locale'
 
-export function getDateFormat(locale: LocaleCode): DateFormat {
-	const formatter = new Intl.DateTimeFormat(locale, { dateStyle: 'medium' })
-	return (date) => {
-		return formatter.format(date)
+type DateFormat = string
+
+/**
+ * Provide the format string for dates.
+ *
+ * @param locale locale to get the format string for
+ */
+export function getDateFormat(locale: Locale): DateFormat {
+	if (locale.code.split('-')[0] === 'de') {
+		// For german 'P' aka. 'short' is similiar to `{ dateStyle: 'medium' }: Intl.DateTimeFormatOptions`
+		// See https://github.com/date-fns/date-fns/blob/v4.1.0/src/locale/de/_lib/formatLong/index.ts#L8-L9
+		return 'P'
 	}
+	// Usually 'PP' aka. 'medium' is similiar to `{ dateStyle: 'medium' }: Intl.DateTimeFormatOptions`
+	return 'PP'
 }
 
-export function getDateRangeFormat(locale: LocaleCode): DateRangeFormat {
-	const formatter = new Intl.DateTimeFormat(locale, { dateStyle: 'medium' })
-	return (dates) => {
-		return formatter.formatRange(dates[0], dates[1])
-	}
+/**
+ * Provide the format string for times.
+ */
+export function getTimeFormat(): DateFormat {
+	// 'p' aka. 'medium' is similiar to `{ timeStyle: 'medium' }: Intl.DateTimeFormatOptions`
+	return 'p'
 }
 
-export function getTimeFormat(locale: LocaleCode): DateFormat {
-	const formatter = new Intl.DateTimeFormat(locale, { timeStyle: 'short' })
-	return (date) => {
-		return formatter.format(date)
-	}
+/**
+ * Provide the format string for date times.
+ *
+ * @param locale locale to get the format string for
+ */
+export function getDateTimeFormat(locale: Locale): DateFormat {
+	return getDateFormat(locale) + getTimeFormat()
 }
 
-export function getTimeRangeFormat(locale: LocaleCode): DateRangeFormat {
-	const formatter = new Intl.DateTimeFormat(locale, { timeStyle: 'short' })
-	return (dates) => {
-		return formatter.formatRange(dates[0], dates[1])
-	}
+/**
+ * Provide the format string for weeks.
+ */
+export function getWeekFormat(): DateFormat {
+	// cannot format weeks with Intl.
+	// Do not use RR (or RRR) because what is formated with RR cannot be parsed with RR.
+	// e.g. RR formats "2025" to "2025", but expects "25" when parsing.
+	return 'RRRR-II'
 }
 
-export function getDateTimeFormat(locale: LocaleCode): DateFormat {
-	const formatter = new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short' })
-	return (date) => {
-		return formatter.format(date)
-	}
+/**
+ * Provide the format string for month.
+ *
+ * @param locale locale to get the format string for
+ */
+export function getMonthFormat(locale: Locale): DateFormat {
+	return guessFormat(locale.code, true)
 }
 
-export function getDateTimeRangeFormat(locale: LocaleCode): DateRangeFormat {
-	const formatter = new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short' })
-	return (dates) => {
-		return formatter.formatRange(dates[0], dates[1])
-	}
+/**
+ * Provide the format string for year.
+ *
+ * @param locale locale to get the format string for
+ */
+export function getYearFormat(locale: Locale): DateFormat {
+	return guessFormat(locale.code, false)
 }
 
-export function getMonthFormat(locale: LocaleCode): DateFormat {
-	const formatter = new Intl.DateTimeFormat(locale, { year: 'numeric', month: '2-digit' })
-	return (date) => {
-		return formatter.format(date)
+/**
+ * Guess the format string for a numeric year with optionally a 2-digit month.
+ *
+ * @param localeCode locale to guess the format string for
+ * @param includeMonth whether to include the month
+ */
+function guessFormat(localeCode: string, includeMonth: boolean): string {
+	const sampleDate = new Date(2026, 0, 1)
+	const formatOptions: Intl.DateTimeFormatOptions = {
+		year: 'numeric',
+		// Specify because other calendar systems are not supported
+		calendar: 'gregory',
+	}
+	if (includeMonth) {
+		formatOptions.month = '2-digit'
 	}
+	// Format extraction using `Intl.DateTime.formatToParts` is inspired from
+	// `formatStr` in `@formkit/tempo` and `parseFormatForOpts` in `luxon`.
+	const formatter = Intl.DateTimeFormat(localeCode, formatOptions)
+	const parts = formatter.formatToParts(sampleDate)
+	const partStrings = parts.map((part) => {
+		switch (part.type) {
+			case 'month':
+				return 'MM'
+			case 'year':
+				return 'yyyy'
+			case 'literal':
+				return escapeLiteraForFormatString(part.value)
+			// Everything else is not expected and supported.
+			default:
+				return ''
+		}
+	})
+	return partStrings.join('')
 }
 
-export function getYearFormat(locale: LocaleCode): DateFormat {
-	const formatter = new Intl.DateTimeFormat(locale, { year: 'numeric' })
-	return (date) => {
-		return formatter.format(date)
-	}
+/**
+ * Escape literal value as required for by `date-fns/format`.
+ *
+ * > The characters wrapped between two single quotes characters (') are escaped.
+ * > Two single quotes in a row, whether inside or outside a quoted sequence,
+ * > represent a 'real' single quote. (see the last example).
+ * https://date-fns.org/v4.4.0/docs/format
+ *
+ * @param literalValue literal value to be escaped
+ */
+function escapeLiteraForFormatString(literalValue): string {
+	// > The characters wrapped between two single quotes characters (') are escaped.
+	// > Two single quotes in a row, whether inside or outside a quoted sequence,
+	// > represent a 'real' single quote. (see the last example).
+	// https://date-fns.org/v4.1.0/docs/format
+	literalValue = literalValue.replaceAll(/'/g, '\'\'')
+	return literalValue.replaceAll(/[A-Za-z]+/g, (latinCharSeq) => `'${latinCharSeq}'`)
 }

tests/component/components/NcDateTimePicker/FormattingSnapshot.story.vue

@@ -8,33 +8,68 @@
 </template>
 
 <script setup lang="ts">
-import { getDateFormat, getDateRangeFormat, getDateTimeFormat, getDateTimeRangeFormat, getMonthFormat, getTimeFormat, getTimeRangeFormat, getYearFormat } from '../../../../src/components/NcDateTimePicker/format.ts'
+import type { Locale } from 'date-fns/locale'
+
+import { format as dateFnsLocale } from 'date-fns/format'
+import * as allDateFnsLocales from 'date-fns/locale'
+import { getDateFormat, getDateTimeFormat, getMonthFormat, getTimeFormat, getYearFormat } from '../../../../src/components/NcDateTimePicker/format.ts'
 import allLocales from './allLocales.ts'
 
 const date = new Date(2000, 0, 2, 3, 4)
-const dateRange = [new Date(2000, 0, 1), new Date(2000, 0, 7)]
-const timeRange = [new Date(2000, 0, 1, 2, 3), new Date(2000, 0, 1, 8, 9)]
-const dateTimeRange = [new Date(2000, 0, 1, 2, 3), new Date(2000, 0, 7, 8, 9)]
+const dateRange = [new Date(2000, 0, 1), new Date(2000, 0, 7)] as const
+const timeRange = [new Date(2000, 0, 1, 2, 3), new Date(2000, 0, 1, 8, 9)] as const
+const dateTimeRange = [new Date(2000, 0, 1, 2, 3), new Date(2000, 0, 7, 8, 9)] as const
 
 const snapshot = {
 
 }
 
+const byLocaleCodeDateFnsLocale = new Map(Object.values(allDateFnsLocales).map((locale) => [locale.code, locale]))
+
+function findDateFnsLocale(localeCode: string): Locale | undefined {
+	const dateFnsLocale = byLocaleCodeDateFnsLocale.get(localeCode)
+	if (dateFnsLocale !== undefined) {
+		return dateFnsLocale
+	}
+	if (localeCode.includes('-')) {
+		return findDateFnsLocale(localeCode.split('-')[0])
+	}
+	return undefined
+}
+
+function format(date: Date, formatStr: string, locale: Locale) {
+	return dateFnsLocale(date, formatStr, { locale })
+}
+
+function formatRange(dates: readonly [Date, Date], formatStr: string, locale: Locale) {
+	return format(dates[0], formatStr, locale) + ' - ' + format(dates[1], formatStr, locale)
+}
+
 for (const locale of allLocales) {
 	const localeCode = locale.code.replaceAll('_', '-')
-	if (Intl.DateTimeFormat.supportedLocalesOf([localeCode]).length === 0) {
-		continue
+
+	const supportedByIntl = Intl.DateTimeFormat.supportedLocalesOf([localeCode]).length !== 0
+	let dateFnsLocale = findDateFnsLocale(localeCode)
+	if (dateFnsLocale === undefined) {
+		if (supportedByIntl) {
+			dateFnsLocale = allDateFnsLocales.enUS
+		} else {
+			// Exclude snapshot if locale is not supported by Intl.DateTimeFormat or date-fns/locale.
+			// Including such locales would only bloat the snapshot.
+			continue
+		}
 	}
+
 	snapshot[localeCode] = {
 		localeName: locale.name,
-		date: getDateFormat(localeCode)(date),
-		dateRange: getDateRangeFormat(localeCode)(dateRange),
-		time: getTimeFormat(localeCode)(date),
-		timeRange: getTimeRangeFormat(localeCode)(timeRange),
-		dateTime: getDateTimeFormat(localeCode)(date),
-		dateTimeRange: getDateTimeRangeFormat(localeCode)(dateTimeRange),
-		month: getMonthFormat(localeCode)(date),
-		year: getYearFormat(localeCode)(date),
+		date: format(date, getDateFormat(dateFnsLocale), dateFnsLocale),
+		dateRange: formatRange(dateRange, getDateFormat(dateFnsLocale), dateFnsLocale),
+		time: format(date, getTimeFormat(), dateFnsLocale),
+		timeRange: formatRange(timeRange, getTimeFormat(), dateFnsLocale),
+		dateTime: format(date, getDateTimeFormat(dateFnsLocale), dateFnsLocale),
+		dateTimeRange: formatRange(dateTimeRange, getDateTimeFormat(dateFnsLocale), dateFnsLocale),
+		month: format(date, getMonthFormat(dateFnsLocale), dateFnsLocale),
+		year: format(date, getYearFormat(dateFnsLocale), dateFnsLocale),
 	}
 }