refactor(DatePicker, DateRangePicker): remove the dependency on date-fns within the component, allowing the option to provide custom functions for date formatting and parsing.

mrholek · mrholek · commit 4cde4a83a67c · 2023-09-26T15:05:32.000+02:00
diff --git a/docs/assets/js/snippets.js b/docs/assets/js/snippets.js
@@ -11,8 +11,7 @@
  * For details, see https://creativecommons.org/licenses/by/3.0/.
  */
 
-/* global coreui: false */
-
+/* global coreui: false, dayjs: false */
 (() => {
   'use strict'
 
@@ -316,6 +315,37 @@
   }
   // js-docs-end date-picker-disabled-dates
 
+  // js-docs-start date-picker-custom-formats1
+  const myDatePickerCustomFormats1 = document.getElementById('myDatePickerCustomFormats1')
+  if (myDatePickerCustomFormats1) {
+    dayjs.extend(window.dayjs_plugin_customParseFormat)
+    const optionsDatePickerCustomFormats1 = {
+      locale: 'en-US',
+      date: new Date(2022, 8, 3),
+      inputDateFormat: date => dayjs(date).format('MMMM DD, YYYY'),
+      inputDateParse: date => dayjs(date, 'MMMM DD, YYYY').toDate()
+    }
+
+    new coreui.DatePicker(myDatePickerCustomFormats1, optionsDatePickerCustomFormats1)
+  }
+  // js-docs-end date-picker-custom-formats1
+
+  // js-docs-start date-picker-custom-formats2
+  const myDatePickerCustomFormats2 = document.getElementById('myDatePickerCustomFormats2')
+  if (myDatePickerCustomFormats2) {
+    dayjs.extend(window.dayjs_plugin_customParseFormat)
+    dayjs.locale('es')
+    const optionsDatePickerCustomFormats2 = {
+      locale: 'es-ES',
+      date: new Date(2022, 8, 3),
+      inputDateFormat: date => dayjs(date).format('YYYY MMMM DD'),
+      inputDateParse: date => dayjs(date, 'YYYY MMMM DD').toDate()
+    }
+
+    new coreui.DatePicker(myDatePickerCustomFormats2, optionsDatePickerCustomFormats2)
+  }
+  // js-docs-end date-picker-custom-formats2
+
   // -------------------------------
   // Date Range Pickers
   // -------------------------------
@@ -341,6 +371,39 @@
   }
   // js-docs-end date-range-picker-disabled-dates
 
+  // js-docs-start date-range-picker-custom-formats1
+  const myDateRangePickerCustomFormats1 = document.getElementById('myDateRangePickerCustomFormats1')
+  if (myDateRangePickerCustomFormats1) {
+    dayjs.extend(window.dayjs_plugin_customParseFormat)
+    const optionsDateRangePickerCustomFormats1 = {
+      locale: 'en-US',
+      startDate: new Date(2022, 8, 3),
+      endDate: new Date(2022, 8, 17),
+      inputDateFormat: date => dayjs(date).format('MMMM DD, YYYY'),
+      inputDateParse: date => dayjs(date, 'MMMM DD, YYYY').toDate()
+    }
+
+    new coreui.DateRangePicker(myDateRangePickerCustomFormats1, optionsDateRangePickerCustomFormats1)
+  }
+  // js-docs-end date-range-picker-custom-formats1
+
+  // js-docs-start date-range-picker-custom-formats2
+  const myDateRangePickerCustomFormats2 = document.getElementById('myDateRangePickerCustomFormats2')
+  if (myDateRangePickerCustomFormats2) {
+    dayjs.extend(window.dayjs_plugin_customParseFormat)
+    dayjs.locale('es')
+    const optionsDateRangePickerCustomFormats2 = {
+      locale: 'es-ES',
+      startDate: new Date(2022, 8, 3),
+      endDate: new Date(2022, 8, 17),
+      inputDateFormat: date => dayjs(date).format('YYYY MMMM DD'),
+      inputDateParse: date => dayjs(date, 'YYYY MMMM DD').toDate()
+    }
+
+    new coreui.DateRangePicker(myDateRangePickerCustomFormats2, optionsDateRangePickerCustomFormats2)
+  }
+  // js-docs-end date-range-picker-custom-formats2
+
   // js-docs-start date-range-picker-custom-ranges
   const myDateRangePickerCustomRanges = document.getElementById('myDateRangePickerCustomRanges')
   if (myDateRangePickerCustomRanges) {
diff --git a/docs/content/forms/date-picker.md b/docs/content/forms/date-picker.md
@@ -6,6 +6,7 @@ group: forms
 toc: true
 pro_component: true
 other_frameworks: date-picker
+dayjs: true
 ---
 
 ## Example
@@ -236,6 +237,48 @@ RTL support is built-in and can be explicitly controlled through the `$enable-rt
 </div>
 {{< /example >}}
 
+## Custom formats
+
+As of v5.0.0, the `format` property is removed in Date Picker. Instead, utilize the `inputDateFormat` to format dates into custom strings and `inputDateParse` to parse custom strings into Date objects.
+
+The provided code demonstrates how to use the `inputDateFormat` and `inputDateParse` properties. In this example, we use the `dayjs` library to format and parse dates.
+
+The `inputDateFormat` property formats the date into a custom string, while the `inputDateParse` property parses a custom string into a Date object. The code showcases the date range in different formats based on locale, such as 'MMMM DD, YYYY' and 'YYYY MMMM DD', and accommodates different locales, like 'en-US' and 'es-ES'.
+
+
+{{< example >}}
+<div class="row">
+  <div class="col-lg-4">
+    <div id="myDatePickerCustomFormats1"></div>
+  </div>
+</div>
+{{< /example >}}
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/plugin/customParseFormat.js"></script>
+```
+
+{{< js-docs name="date-picker-custom-formats1" file="docs/assets/js/snippets.js" >}}
+
+To use localized dates, we need to additionally add locale files, in this case, Spanish:
+
+{{< example >}}
+<div class="row">
+  <div class="col-lg-4">
+    <div id="myDatePickerCustomFormats2"></div>
+  </div>
+</div>
+{{< /example >}}
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/plugin/customParseFormat.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/locale/es.js"></script>
+```
+
+{{< js-docs name="date-picker-custom-formats2" file="docs/assets/js/snippets.js" >}}
+
 ## Usage
 
 ### Via data attributes
@@ -282,8 +325,9 @@ const datePickerList = datePickerElementList.map(datePickerEl => {
 | `disabledDates` | array | null | `null` | Specify the list of dates that cannot be selected. |
 | `firstDayOfWeek` | number | `1` | <p>Sets the day of start week.</p><ul><li>`0` - Sunday</li><li>`1` - Monday</li><li>`2` - Tuesday</li><li>`3` - Wednesday</li><li>`4` - Thursday</li><li>`5` - Friday</li><li>`6` - Saturday</li></ul> |
 | `footer` | boolean | `false` | Toggle visibility of footer element. |
-| `format` | string | | Set date format. We use date-fns to format dates. Visit <a href="https://date-fns.org/v2.28.0/docs/format" target="_blank" rel="nofollow">https://date-fns.org/v2.28.0/docs/format</a> to check accepted patterns. |
 | `indicator` | boolean | `true` | Toggle visibility or set the content of the input indicator. |
+| `inputDateFormat` | function | `null` | Custom function to format the selected date into a string according to a custom format. |
+| `inputDateParse` | function | `null` | Custom function to parse the input value into a valid Date object. |
 | `inputReadOnly` | boolean | `false` | Toggle the readonly state for the component. |
 | `invalid` | boolean | `false` | Toggle the invalid state for the component. |
 | `locale` | string | `'default'` | Sets the default locale for components. If not set, it is inherited from the navigator.language. |
diff --git a/docs/content/forms/date-range-picker.md b/docs/content/forms/date-range-picker.md
@@ -6,6 +6,7 @@ group: forms
 toc: true
 pro_component: true
 other_frameworks: date-range-picker
+dayjs: true
 ---
 
 ## Example
@@ -279,6 +280,48 @@ RTL support is built-in and can be explicitly controlled through the `$enable-rt
 </div>
 {{< /example >}}
 
+## Custom formats
+
+As of v5.0.0, the `format` property is removed in Date Range Picker. Instead, utilize the `inputDateFormat` to format dates into custom strings and `inputDateParse` to parse custom strings into Date objects.
+
+The provided code demonstrates how to use the `inputDateFormat` and `inputDateParse` properties. In this example, we use the `dayjs` library to format and parse dates.
+
+The `inputDateFormat` property formats the date into a custom string, while the `inputDateParse` property parses a custom string into a Date object. The code showcases the date range in different formats based on locale, such as 'MMMM DD, YYYY' and 'YYYY MMMM DD', and accommodates different locales, like 'en-US' and 'es-ES'.
+
+
+{{< example >}}
+<div class="row">
+  <div class="col-lg-7">
+    <div id="myDateRangePickerCustomFormats1"></div>
+  </div>
+</div>
+{{< /example >}}
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/plugin/customParseFormat.js"></script>
+```
+
+{{< js-docs name="date-range-picker-custom-formats1" file="docs/assets/js/snippets.js" >}}
+
+To use localized dates, we need to additionally add locale files, in this case, Spanish:
+
+{{< example >}}
+<div class="row">
+  <div class="col-lg-7">
+    <div id="myDateRangePickerCustomFormats2"></div>
+  </div>
+</div>
+{{< /example >}}
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/plugin/customParseFormat.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/locale/es.js"></script>
+```
+
+{{< js-docs name="date-range-picker-custom-formats2" file="docs/assets/js/snippets.js" >}}
+
 ## Usage
 
 ### Via data attributes
@@ -326,8 +369,9 @@ const dateRangePickerList = dateRangePickerElementList.map(dateRangePickerEl =>
 | `endName` | string | `null` | Set the name attribute for the end date input element. |
 | `firstDayOfWeek` | number | `1` | <p>Sets the day of start week.</p>  <ul><li>`0` - Sunday</li><li>`1` - Monday</li><li>`2` - Tuesday</li><li>`3` - Wednesday</li><li>`4` - Thursday</li><li>`5` - Friday</li><li>`6` - Saturday</li></ul> |
 | `footer` | boolean | `false` | Toggle visibility of footer element. |
-| `format` | string | | Set date format. We use date-fns to format dates. Visit <a href="https://date-fns.org/v2.28.0/docs/format" target="_blank" rel="nofollow">https://date-fns.org/v2.28.0/docs/format</a> to check accepted patterns. |
 | `indicator` | boolean | `true` | Toggle visibility or set the content of the input indicator. |
+| `inputDateFormat` | function | `null` | Custom function to format the selected date into a string according to a custom format. |
+| `inputDateParse` | function | `null` | Custom function to parse the input value into a valid Date object. |
 | `inputReadOnly` | boolean | `false` | Toggle the readonly state for the component. |
 | `invalid` | boolean | `false` | Toggle the invalid state for the component. |
 | `locale` | string | `'default'` | Sets the default locale for components. If not set, it is inherited from the navigator.language. |
diff --git a/docs/content/migration.md b/docs/content/migration.md
@@ -1,7 +1,7 @@
 ---
 layout: docs
 title: Migrating to v5
-description: Track and review changes to the CoreUI for Bootstrap source files, documentation, and components to help you migrate from v3 to v4.
+description: Track and review changes to the CoreUI for Bootstrap source files, documentation, and components to help you migrate from v4 to v5.
 group: migration
 aliases: "/migration/"
 toc: true
@@ -89,6 +89,16 @@ Learn more by reading the new [color modes documentation]({{< docsref "/customiz
 
 - <span class="badge text-warning-emphasis bg-warning-subtle">Deprecated</span> The `.btn-close-white` class has been deprecated and replaced with `data-coreui-theme="dark"` on the close button or any parent element. [See the docs for an example.]({{< docsref "/components/close-button#dark-variant" >}})
 
+#### Date Picker
+
+- <span class="badge bg-danger">Breaking</span> Removed option `format`, use `inputDateFormat` instead of. [See the docs for an example.]({{< docsref "/forms/date-picker#custom-formats" >}})
+- <span class="badge bg-danger">Breaking</span> `dateChange.coreui.date-picker` event return only the date object, instead of the date object and formatted string.
+
+#### Date Range Picker
+
+- <span class="badge bg-danger">Breaking</span> Removed option `format`, use `inputDateFormat` instead of. [See the docs for an example.]({{< docsref "/forms/date-range-picker#custom-formats" >}})
+- <span class="badge bg-danger">Breaking</span> `startDateChange.coreui.date-range-picker` and `endDateChange.coreui.date-range-picker` events return only the date object, instead of the date object and formatted string.
+
 #### Dropdowns
 
 - <span class="badge text-warning-emphasis bg-warning-subtle">Deprecated</span> The `.dropdown-menu-dark` class has been deprecated and replaced with `data-coreui-theme="dark"` on the dropdown or any parent element. [See the docs for an example.]({{< docsref "/components/dropdowns#dark-dropdowns" >}})
diff --git a/docs/layouts/partials/scripts.html b/docs/layouts/partials/scripts.html
@@ -8,6 +8,12 @@
 <script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>
 {{- end }}
 
+{{- if eq .Params.dayjs true -}}
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/plugin/customParseFormat.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1/locale/es.js"></script>
+{{- end }}
+
 {{- $vendor := resources.Match "js/vendor/*.js" -}}
 {{- $js := resources.Match "js/*.js" -}}
 {{- $targetDocsJSPath := printf "/assets/js/docs.js" -}}
diff --git a/js/src/date-picker.js b/js/src/date-picker.js
@@ -75,8 +75,7 @@ class DatePicker extends DateRangePicker {
         this._updateDateRangePickerCalendars()
 
         EventHandler.trigger(this._element, EVENT_DATE_CHANGE, {
-          date: event.date,
-          formatedDate: event.date ? this._formatDate(event.date) : undefined
+          date: event.date
         })
       })
     }
diff --git a/js/src/date-range-picker.js b/js/src/date-range-picker.js
@@ -6,7 +6,6 @@
  */
 
 import * as Popper from '@popperjs/core'
-import { format as dateFormat, parseISO } from 'date-fns'
 import BaseComponent from './base-component.js'
 import Calendar from './calendar.js'
 import TimePicker from './time-picker.js'
@@ -84,7 +83,8 @@ const Default = {
   endName: null,
   firstDayOfWeek: 1,
   footer: false,
-  format: null,
+  inputDateFormat: null,
+  inputDateParse: null,
   invalid: false,
   indicator: true,
   locale: 'default',
@@ -127,8 +127,9 @@ const DefaultType = {
   endName: 'string',
   firstDayOfWeek: 'number',
   footer: 'boolean',
-  format: '(string|null)',
   indicator: 'boolean',
+  inputDateFormat: 'function',
+  inputDateParse: 'function',
   invalid: 'boolean',
   locale: 'string',
   maxDate: '(date|string|null)',
@@ -323,8 +324,8 @@ class DateRangePicker extends BaseComponent {
     })
 
     EventHandler.on(this._startInput, EVENT_INPUT, event => {
-      const date = this._config.format ?
-        parseISO(event.target.value) :
+      const date = this._config.inputDateParse ?
+        this._config.inputDateParse(event.target.value) :
         getLocalDateFromString(event.target.value, this._config.locale, this._config.timepicker)
 
       if (date instanceof Date && date.getTime()) {
@@ -362,8 +363,8 @@ class DateRangePicker extends BaseComponent {
     })
 
     EventHandler.on(this._endInput, EVENT_INPUT, event => {
-      const date = this._config.format ?
-        parseISO(event.target.value) :
+      const date = this._config.inputDateParse ?
+        this._config.inputDateParse(event.target.value) :
         getLocalDateFromString(event.target.value, this._config.locale, this._config.timepicker)
       if (date instanceof Date && date.getTime()) {
         this._endDate = date
@@ -390,8 +391,7 @@ class DateRangePicker extends BaseComponent {
         }
 
         EventHandler.trigger(this._element, EVENT_START_DATE_CHANGE, {
-          date: event.date,
-          formatedDate: event.date ? this._formatDate(event.date) : undefined
+          date: event.date
         })
       })
 
@@ -406,8 +406,7 @@ class DateRangePicker extends BaseComponent {
         }
 
         EventHandler.trigger(this._element, EVENT_END_DATE_CHANGE, {
-          date: event.date,
-          formatedDate: event.date ? this._formatDate(event.date) : undefined
+          date: event.date
         })
       })
 
@@ -597,11 +596,6 @@ class DateRangePicker extends BaseComponent {
     })
 
     EventHandler.one(calendarEl, 'calendarDateChange.coreui.calendar', event => {
-      // this._calendarDate = new Date(
-      //   event.date.getFullYear(),
-      //   event.date.getMonth(),
-      //   1
-      // )
       this._calendarDate = event.date
       this._updateDateRangePickerCalendars()
     })
@@ -755,7 +749,7 @@ class DateRangePicker extends BaseComponent {
     inputEl.autocomplete = 'off'
     inputEl.disabled = this._config.disabled
     inputEl.placeholder = placeholder
-    inputEl.readOnly = this._config.inputReadOnly || typeof this._config.format === 'string'
+    inputEl.readOnly = this._config.inputReadOnly
     inputEl.required = this._config.required
     inputEl.type = 'text'
     inputEl.value = value
@@ -831,8 +825,8 @@ class DateRangePicker extends BaseComponent {
 
     const _date = new Date(date)
 
-    return this._config.format ?
-      dateFormat(_date, this._config.format) :
+    return this._config.inputDateFormat ?
+      this._config.inputDateFormat(_date) :
       (this._config.timepicker ?
         _date.toLocaleString(this._config.locale) :
         _date.toLocaleDateString(this._config.locale))
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json

Original file line number	Diff line number	Diff line change
`@@ -75,8 +75,7 @@ class DatePicker extends DateRangePicker {`
`75`	`75`	`this._updateDateRangePickerCalendars()`
`76`	`76`
`77`	`77`	`EventHandler.trigger(this._element, EVENT_DATE_CHANGE, {`
`78`		`- date: event.date,`
`79`		`- formatedDate: event.date ? this._formatDate(event.date) : undefined`
	`78`	`+ date: event.date`
`80`	`79`	`})`
`81`	`80`	`})`
`82`	`81`	`}`