daterangepicker-4.x 4.2.2 → 4.2.4

package/README.md

@@ -18,8 +18,8 @@ Above samples are based on the [original repository](https://github.com/dangross
 ```html
 <script type="text/javascript" src="https://cdn.jsdelivr.net/jquery/latest/jquery.min.js"></script>
 <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/luxon@3.5.0/build/global/luxon.min.js"></script>
-<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/daterangepicker-4.x@4.2.2/daterangepicker.min.js"></script>
-<link type="text/css" href="https://cdn.jsdelivr.net/npm/daterangepicker-4.x@4.2.2/daterangepicker.min.css" rel="stylesheet" />
+<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/daterangepicker-4.x@4.2.4/daterangepicker.min.js"></script>
+<link type="text/css" href="https://cdn.jsdelivr.net/npm/daterangepicker-4.x@4.2.4/daterangepicker.min.css" rel="stylesheet" />
 
 <input type="text" id="daterange" />
 
@@ -107,6 +107,17 @@ In original daterangepicker this parameter defines whether the `<input>` is upda
 - Added option `locale.durationFormat` to show customized label for selected duration, e.g. `'4 Days, 6 Hours, 30 Minutes'` 
 - ... and maybe some new bugs 😉 
 
+## Methods
+
+Available methods are listed below in [API documentation](#DateRangePicker). You will mainly use 
+   * [.daterangepicker(options, callback)](#DateRangePicker.daterangepicker)
+   * [.setStartDate(startDate)](#DateRangePicker+setStartDate)
+   * [.setEndDate(endDate)](#DateRangePicker+setEndDate)
+   * [.setPeriod(startDate, endDate)](#DateRangePicker+setPeriod)
+   * `$(...).data('daterangepicker')` to get the daterangepicker object
+
+all other methods are used rarely.
+
 ### Differences between `moment` and `luxon` library
 This table lists a few important differences between datarangepicker using moment and luxon. Check them carefully when you migrate from older daterangepicker.
 
@@ -154,8 +165,7 @@ Licensed under the [MIT license](LICENSE).
 </dd>
 <dt><a href="#event_outsideClick.daterangepicker">"outsideClick.daterangepicker" (this)</a></dt>
 <dd><p>Emitted when user clicks outside the picker. 
-Picker values is not updated, you may trigger <a href="#event_apply.daterangepicker">&quot;apply.daterangepicker&quot;</a> 
-or <a href="#event_cancel.daterangepicker">&quot;cancel.daterangepicker&quot;</a> in your EventHandler.</p>
+Use option <code>onOutsideClick</code> to define the default action, then you may not need to handle this event.</p>
 </dd>
 <dt><a href="#event_showCalendar.daterangepicker">"showCalendar.daterangepicker" (this)</a></dt>
 <dd><p>Emitted when the calendar(s) are shown.
@@ -208,7 +218,10 @@ use <a href="#event_timeChange.daterangepicker">&quot;timeChange.daterangepicker
         * [.setEndDate(endDate, isValid)](#DateRangePicker+setEndDate)
         * [.setPeriod(startDate, endDate, isValid)](#DateRangePicker+setPeriod)
         * [.updateView()](#DateRangePicker+updateView)
-        * [.outsideClick(e)](#DateRangePicker+outsideClick)
+        * [.showCalendars()](#DateRangePicker+showCalendars)
+        * [.hideCalendars()](#DateRangePicker+hideCalendars)
+        * [.updateElement()](#DateRangePicker+updateElement)
+        * [.remove()](#DateRangePicker+remove)
     * _static_
         * [.daterangepicker(options, callback)](#DateRangePicker.daterangepicker) ⇒
 
@@ -218,7 +231,7 @@ use <a href="#event_timeChange.daterangepicker">&quot;timeChange.daterangepicker
 
 | Param | Type | Description |
 | --- | --- | --- |
-| element | [<code>jQuery</code>](https://learn.jquery.com/using-jquery-core/jquery-object/) | jQuery selector of the parent element that the date range picker will be added to |
+| element | [<code>jQuery</code>](https://api.jquery.com/Types/#jQuery/) | jQuery selector of the parent element that the date range picker will be added to |
 | options | [<code>Options</code>](#Options) | Object to configure the DateRangePicker |
 | cb | <code>function</code> | Callback function executed when |
 
@@ -308,18 +321,33 @@ Updates the picker when calendar is initiated or any date has been selected.
 Could be useful after running [setStartDate](#DateRangePicker+setStartDate) or [setEndDate](#DateRangePicker+setEndDate)
 
 **Kind**: instance method of [<code>DateRangePicker</code>](#DateRangePicker)  
-<a name="DateRangePicker+outsideClick"></a>
+<a name="DateRangePicker+showCalendars"></a>
 
-### dateRangePicker.outsideClick(e)
-Closes the picker when user clicks outside
+### dateRangePicker.showCalendars()
+Shows calendar when user selects "Custom Ranges"
 
 **Kind**: instance method of [<code>DateRangePicker</code>](#DateRangePicker)  
-**Emits**: <code>event:&quot;outsideClick.daterangepicker&quot;</code>  
+**Emits**: <code>event:&quot;showCalendar.daterangepicker&quot;</code>  
+<a name="DateRangePicker+hideCalendars"></a>
 
-| Param | Type | Description |
-| --- | --- | --- |
-| e | [<code>jQuery</code>](https://learn.jquery.com/using-jquery-core/jquery-object/) | The Event target |
+### dateRangePicker.hideCalendars()
+Hides calendar when user selects a predefined range
+
+**Kind**: instance method of [<code>DateRangePicker</code>](#DateRangePicker)  
+**Emits**: <code>event:&quot;hideCalendar.daterangepicker&quot;</code>  
+<a name="DateRangePicker+updateElement"></a>
+
+### dateRangePicker.updateElement()
+Update attached `<input>` element with selected value
+
+**Kind**: instance method of [<code>DateRangePicker</code>](#DateRangePicker)  
+**Emits**: [<code>change</code>](https://api.jquery.com/change/)  
+<a name="DateRangePicker+remove"></a>
+
+### dateRangePicker.remove()
+Removes the picker from document
 
+**Kind**: instance method of [<code>DateRangePicker</code>](#DateRangePicker)  
 <a name="DateRangePicker.daterangepicker"></a>
 
 ### DateRangePicker.daterangepicker(options, callback) ⇒
@@ -331,7 +359,7 @@ Initiate a new DateRangePicker
 | Param | Type | Description |
 | --- | --- | --- |
 | options | [<code>Options</code>](#Options) | Object to configure the DateRangePicker |
-| callback | [<code>callback</code>](#callback) | Callback function executed when date is changed.  As alternative listen to the ["apply.daterangepicker"](#event_apply.daterangepicker)  event |
+| callback | [<code>callback</code>](#callback) | Callback function executed when date is changed.<br/> Callback function is executed if selected date values has changed, before picker is hidden and before the attached `<input>` element is updated.  As alternative listen to the ["apply.daterangepicker"](#event_apply.daterangepicker) event |
 
 <a name="event_show.daterangepicker"></a>
 
@@ -371,8 +399,7 @@ Emitted when the picker is hidden
 
 ## "outsideClick.daterangepicker" (this)
 Emitted when user clicks outside the picker. 
-Picker values is not updated, you may trigger ["apply.daterangepicker"](#event_apply.daterangepicker) 
-or ["cancel.daterangepicker"](#event_cancel.daterangepicker) in your EventHandler.
+Use option `onOutsideClick` to define the default action, then you may not need to handle this event.
 
 **Kind**: event emitted  
 
@@ -468,7 +495,7 @@ Options for DateRangePicker
 | maxDate | [<code>DateTime</code>](https://moment.github.io/luxon/api-docs/index.html#datetime) \| [<code>Date</code>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) \| <code>string</code> \| <code>null</code> |  | The latest date a user may select or `null` for no limit.<br/> Must be a `luxon.DateTime` or `Date` or `string` according to [ISO-8601](ISO-8601) or a string matching `locale.format`. |
 | minSpan | [<code>Duration</code>](https://moment.github.io/luxon/api-docs/index.html#duration) \| <code>string</code> \| <code>number</code> \| <code>null</code> |  | The maximum span between the selected start and end dates.<br/> Must be a `luxon.Duration` or number of seconds or a string according to [ISO-8601](ISO-8601) duration.<br/> Ignored when `singleDatePicker: true` |
 | maxSpan | [<code>Duration</code>](https://moment.github.io/luxon/api-docs/index.html#duration) \| <code>string</code> \| <code>number</code> \| <code>null</code> |  | The minimum span between the selected start and end dates.<br/> Must be a `luxon.Duration` or number of seconds or a string according to [ISO-8601](ISO-8601) duration.<br/> Ignored when `singleDatePicker: true` |
-| initalMonth | [<code>DateTime</code>](https://moment.github.io/luxon/api-docs/index.html#datetime) \| [<code>Date</code>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) \| <code>string</code> \| <code>null</code> |  | Default: `DateTime.now().startOf('month')`<br/> The inital month shown when `startDate: null`. <br/> Must be a `luxon.DateTime` or `Date` or `string` according to [ISO-8601](ISO-8601) or a string matching `locale.format`.<br/> When `initalMonth` is used, then `endDate` is ignored and it works only with `timePicker: false` |
+| initalMonth | [<code>DateTime</code>](https://moment.github.io/luxon/api-docs/index.html#datetime) \| [<code>Date</code>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) \| <code>string</code> \| <code>null</code> |  | Default: `DateTime.now().startOf('month')`<br/> The inital month shown when `startDate: null`. Be aware, the attached `<input>` element must be also empty.`<br/> Must be a `luxon.DateTime` or `Date` or `string` according to [ISO-8601](ISO-8601) or a string matching `locale.format`.<br/> When `initalMonth` is used, then `endDate` is ignored and it works only with `timePicker: false` |
 | autoApply | <code>boolean</code> | <code>false</code> | Hide the `Apply` and `Cancel` buttons, and automatically apply a new date range as soon as two dates are clicked.<br/> Only useful when `timePicker: false` |
 | singleDatePicker | <code>boolean</code> | <code>false</code> | Show only a single calendar to choose one date, instead of a range picker with two calendars.<br/> The start and end dates provided to your callback will be the same single date chosen. |
 | showDropdowns | <code>boolean</code> | <code>false</code> | Show year and month select boxes above calendars to jump to a specific month and year |
@@ -485,7 +512,7 @@ Options for DateRangePicker
 | onOutsideClick | <code>string</code> | <code>&quot;apply&quot;</code> | Defines what picker shall do when user clicks outside the calendar.  `'apply'` or `'cancel'`. Event [onOutsideClick.daterangepicker](#event_outsideClick.daterangepicker) is always emitted. |
 | linkedCalendars | <code>boolean</code> | <code>true</code> | When enabled, the two calendars displayed will always be for two sequential months (i.e. January and February),  and both will be advanced when clicking the left or right arrows above the calendars.<br/> When disabled, the two calendars can be individually advanced and display any month/year |
 | isInvalidDate | <code>function</code> | <code>false</code> | A function that is passed each date in the two calendars before they are displayed,<br/>  and may return `true` or `false` to indicate whether that date should be available for selection or not.<br/> Signature: `isInvalidDate(date)`<br/> Function has no effect on date values set by `startDate`, `endDate`, `ranges`, [setStartDate](#DateRangePicker+setStartDate), [setEndDate](#DateRangePicker+setEndDate). |
-| isInvalidTime | <code>function</code> | <code>false</code> | A function that is passed each hour/minute/second/am-pm in the two calendars before they are displayed,<br/>  and may return `true` or `false` to indicate whether that date should be available for selection or not.<br/> Signature: `isInvalidDate(time, side, unit)`<br/> `side` is `'start'` or `'end'` or `null` for `singleDatePicker: true`<br/> `unit` is `'hour'`, `'minute'`, `'second'` or `'ampm'`<br/> Hours are always given as 24-hour clock<br/> Function has no effect on time values set by `startDate`, `endDate`, `ranges`, [setStartDate](#DateRangePicker+setStartDate), [setEndDate](#DateRangePicker+setEndDate).<br/> Ensure that your function returns `false` for at least one item. Otherwise the calender is not rendered.<br/> |
+| isInvalidTime | <code>function</code> | <code>false</code> | A function that is passed each hour/minute/second/am-pm in the two calendars before they are displayed,<br/>  and may return `true` or `false` to indicate whether that date should be available for selection or not.<br/> Signature: `isInvalidTime(time, side, unit)`<br/> `side` is `'start'` or `'end'` or `null` for `singleDatePicker: true`<br/> `unit` is `'hour'`, `'minute'`, `'second'` or `'ampm'`<br/> Hours are always given as 24-hour clock<br/> Function has no effect on time values set by `startDate`, `endDate`, `ranges`, [setStartDate](#DateRangePicker+setStartDate), [setEndDate](#DateRangePicker+setEndDate).<br/> Ensure that your function returns `false` for at least one item. Otherwise the calender is not rendered.<br/> |
 | isCustomDate | <code>function</code> | <code>false</code> | A function that is passed each date in the two calendars before they are displayed,  and may return a string or array of CSS class names to apply to that date's calendar cell.<br/> Signature: `isCustomDate(date)` |
 | applyButtonClasses | <code>string</code> | <code>&quot;btn-primary&quot;</code> | CSS class names that will be added only to the apply button |
 | cancelButtonClasses | <code>string</code> | <code>&quot;btn-default&quot;</code> | CSS class names that will be added only to the cancel button |

package/daterangepicker.js

@@ -61,7 +61,7 @@
         * Must be a `luxon.Duration` or number of seconds or a string according to {@link ISO-8601} duration.<br/>
         * Ignored when `singleDatePicker: true`
         * @property {external:DateTime|external:Date|string|null} initalMonth - Default: `DateTime.now().startOf('month')`<br/>
-        * The inital month shown when `startDate: null`. <br/>
+        * The inital month shown when `startDate: null`. Be aware, the attached `<input>` element must be also empty.`<br/>
         * Must be a `luxon.DateTime` or `Date` or `string` according to {@link ISO-8601} or a string matching `locale.format`.<br/>
         * When `initalMonth` is used, then `endDate` is ignored and it works only with `timePicker: false`
 
@@ -100,7 +100,7 @@
         * Function has no effect on date values set by `startDate`, `endDate`, `ranges`, {@link #DateRangePicker+setStartDate|setStartDate}, {@link #DateRangePicker+setEndDate|setEndDate}.
         * @property {function} isInvalidTime=false - A function that is passed each hour/minute/second/am-pm in the two calendars before they are displayed,<br/> 
         * and may return `true` or `false` to indicate whether that date should be available for selection or not.<br/>
-        * Signature: `isInvalidDate(time, side, unit)`<br/>
+        * Signature: `isInvalidTime(time, side, unit)`<br/>
         * `side` is `'start'` or `'end'` or `null` for `singleDatePicker: true`<br/>
         * `unit` is `'hour'`, `'minute'`, `'second'` or `'ampm'`<br/>
         * Hours are always given as 24-hour clock<br/>
@@ -435,16 +435,47 @@
             if (this.maxDate)
                 this.maxDate = this.maxDate.endOf('day');
         }
+
+        //if no start/end dates set, check if the input element contains initial values
+        if (typeof options.startDate === 'undefined' && typeof options.endDate === 'undefined') {
+            if ($(this.element).is(':text')) {
+                let start, end;
+                const val = $(this.element).val();
+                if (val != '') {
+                    const split = val.split(this.locale.separator);
+                    const format = typeof this.locale.format === 'string' ? this.locale.format : DateTime.parseFormatForOpts(this.locale.format);
+                    if (split.length == 2) {
+                        start = DateTime.fromFormat(split[0], format, { locale: DateTime.now().locale });
+                        end = DateTime.fromFormat(split[1], format, { locale: DateTime.now().locale });
+                    } else if (this.singleDatePicker) {
+                        start = DateTime.fromFormat(val, format, { locale: DateTime.now().locale });
+                        end = DateTime.fromFormat(val, format, { locale: DateTime.now().locale });
+                    }
+
+                    if (start.isValid && end.isValid) {
+                        this.setStartDate(start, false);
+                        this.setEndDate(end, false);
+                    } else {
+                        console.error(`Value in <input> is not a valid string`);
+                    }
+                }
+            }
+        }
+
         if (this.singleDatePicker) {
             this.endDate = this.startDate;
         } else if (this.endDate < this.startDate) {
             this.endDate = this.startDate;
+            console.warn(`Set endDate to ${this.timePicker ? endDate.toISO({ suppressMilliseconds: true }) : endDate.toISODate()}  because it was earlier than startDate`);
         }
-        if (!this.startDate && this.initalMonth)
-            this.endDate = null;
 
-        // Do some sanity checks on startDate for minDate, maxDate
-        this.constrainDate();
+        if (!this.startDate && this.initalMonth) {
+            // No initial date selected
+            this.endDate = null;
+        } else {
+            // Do some sanity checks on startDate for minDate, maxDate
+            this.constrainDate();
+        }
 
         if (typeof options.applyButtonClasses === 'string')
             this.applyButtonClasses = options.applyButtonClasses;
@@ -533,29 +564,6 @@
             }
         }
 
-        //if no start/end dates set, check if the input element contains initial values
-        if (typeof options.startDate === 'undefined' && typeof options.endDate === 'undefined') {
-            if ($(this.element).is(':text')) {
-                let start, end;
-                const val = $(this.element).val();
-                const split = val.split(this.locale.separator);
-
-                const format = typeof this.locale.format === 'string' ? this.locale.format : DateTime.parseFormatForOpts(this.locale.format);
-                if (split.length == 2) {
-                    start = DateTime.fromFormat(split[0], format, { locale: DateTime.now().locale });
-                    end = DateTime.fromFormat(split[1], format, { locale: DateTime.now().locale });
-                } else if (this.singleDatePicker && val !== "") {
-                    start = DateTime.fromFormat(val, format, { locale: DateTime.now().locale });
-                    end = DateTime.fromFormat(val, format, { locale: DateTime.now().locale });
-                }
-
-                if (start.isValid && end.isValid) {
-                    this.setStartDate(start, false);
-                    this.setEndDate(end, false);
-                }
-            }
-        }
-
         if (!this.singleDatePicker && typeof options.ranges === 'object') {
             // Process custom ranges
             for (let range in options.ranges) {
@@ -1046,7 +1054,7 @@
         },
 
         /**
-        * Displays the months
+        * Shows calendar months based on selected date values
         * @private
         */
         updateMonthsInView: function () {
@@ -1086,7 +1094,7 @@
         },
 
         /**
-        * Updates the custome ranges 
+        * Updates the selected day value from calendar with selected time values
         * @private
         */
         updateCalendars: function () {
@@ -1569,7 +1577,7 @@
         },
 
         /**
-        * Update the linke `<input>` element with selected date
+        * Disable the `Apply` button if no date value is selected
         * @private
         */
         updateFormInputs: function () {
@@ -1582,7 +1590,7 @@
         },
 
         /**
-        * Positions the calendar
+        * Place the picker at the right place in the document
         * @private
         */
         move: function () {
@@ -1784,6 +1792,7 @@
         * Closes the picker when user clicks outside
         * @param {external:jQuery} e - The Event target
         * @emits "outsideClick.daterangepicker"
+        * @private
         */
         outsideClick: function (e) {
             var target = $(e.target);
@@ -1805,8 +1814,7 @@
 
             /**
             * Emitted when user clicks outside the picker. 
-            * Picker values is not updated, you may trigger {@link #event_apply.daterangepicker|"apply.daterangepicker"} 
-            * or {@link #event_cancel.daterangepicker|"cancel.daterangepicker"} in your EventHandler.
+            * Use option `onOutsideClick` to define the default action, then you may not need to handle this event.
             * @event
             * @name "outsideClick.daterangepicker"
             * @param {DateRangePicker} this - The daterangepicker object
@@ -1817,7 +1825,6 @@
         /**
         * Shows calendar when user selects "Custom Ranges"
         * @emits "showCalendar.daterangepicker"
-        * @private
         */
         showCalendars: function () {
             this.container.addClass('show-calendar');
@@ -1835,7 +1842,6 @@
         /**
         * Hides calendar when user selects a predefined range
         * @emits "hideCalendar.daterangepicker"
-        * @private
         */
         hideCalendars: function () {
             this.container.removeClass('show-calendar');
@@ -2114,7 +2120,6 @@
 
         /**
         * Hightlight selected predefined range in calendar
-        * @param {external:jQuery} e - The Event target
         * @private
         */
         calculateChosenLabel: function () {
@@ -2310,10 +2315,12 @@
         },
 
         /**
-        * User inserted value into `<input>` 
+        * Update the picker with value from attached `<input>` element.
+        * Error is written to console if input string cannot be parsed as a valid date/range
+        * @param {external:jQuery} e - The Event target
         * @private
         */
-        elementChanged: function () {
+        elementChanged: function (e) {
             if (!this.element.is('input')) return;
             if (!this.element.val().length) return;
 
@@ -2331,7 +2338,10 @@
                 end = start;
             }
 
-            if (!start.isValid || !end.isValid) return;
+            if (!start.isValid || !end.isValid) {
+                console.error(`Input string '${dateString}' is not valid`);
+                return;
+            }
 
             this.setStartDate(start, false);
             this.setEndDate(end, false);
@@ -2339,7 +2349,7 @@
         },
 
         /**
-        * Handles key press
+        * Handles key press, IE 11 compatibility
         * @param {external:jQuery} e - The Event target
         * @private
         */
@@ -2359,8 +2369,8 @@
         },
 
         /**
-        * Update linked `<input>` element with selected value
-        * @private
+        * Update attached `<input>` element with selected value
+        * @emits external:change
         */
         updateElement: function () {
             if (this.startDate == null && this.initalMonth)
@@ -2379,8 +2389,7 @@
         },
 
         /**
-        * Remove the picker from document
-        * @private
+        * Removes the picker from document
         */
         remove: function () {
             this.container.remove();
@@ -2402,8 +2411,9 @@
     * @name DateRangePicker.daterangepicker
     * @function
     * @param {Options} options - Object to configure the DateRangePicker
-    * @param {callback} callback - Callback function executed when date is changed. 
-    * As alternative listen to the {@link #event_apply.daterangepicker|"apply.daterangepicker"}  event
+    * @param {callback} callback - Callback function executed when date is changed.<br/>
+    * Callback function is executed if selected date values has changed, before picker is hidden and before the attached `<input>` element is updated. 
+    * As alternative listen to the {@link #event_apply.daterangepicker|"apply.daterangepicker"} event
     * @returns DateRangePicker
     */
     $.fn.daterangepicker = function (options, callback) {
@@ -2423,10 +2433,13 @@
 
 
 /** @external jQuery 
-@see {@link https://learn.jquery.com/using-jquery-core/jquery-object/|jQuery} */
+@see {@link https://api.jquery.com/Types/#jQuery/|jQuery} */
 
 /** @external Selector
-@see {@link https://learn.jquery.com/using-jquery-core/jquery-object/|jQuery Selector} */
+@see {@link https://api.jquery.com/category/selectors/|jQuery Selector} */
+
+/** @external change
+@see {@link https://api.jquery.com/change/|change event} */
 
 /** @external DateTime
 @see {@link https://moment.github.io/luxon/api-docs/index.html#datetime|DateTime} */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "daterangepicker-4.x",
-  "version": "4.2.2",
+  "version": "4.2.4",
   "description": "Date range picker with time component and pre-defined ranges",
   "main": "daterangepicker.js",
   "style": "daterangepicker.css",