daterangepicker-4.x 4.2.1 → 4.2.3

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.1/daterangepicker.min.js"></script>
-<link type="text/css" href="https://cdn.jsdelivr.net/npm/daterangepicker-4.x@4.2.1/daterangepicker.min.css" rel="stylesheet" />
+<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/daterangepicker-4.x@4.2.3/daterangepicker.min.js"></script>
+<link type="text/css" href="https://cdn.jsdelivr.net/npm/daterangepicker-4.x@4.2.3/daterangepicker.min.css" rel="stylesheet" />
 
 <input type="text" id="daterange" />
 
@@ -107,6 +107,16 @@ 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)
+
+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 +164,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 +217,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 +230,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 +320,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 +358,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 +398,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  
 
@@ -482,10 +508,10 @@ Options for DateRangePicker
 | timePickerSeconds | <code>boolean</code> | <code>boolean</code> | **Deprecated**, use `timePickerStepSize`<br/>Show seconds in the timePicker |
 | timePickerIncrement | <code>boolean</code> | <code>1</code> | **Deprecated**, use `timePickerStepSize`<br/>Increment of the minutes selection list for times |
 | autoUpdateInput | <code>boolean</code> | <code>true</code> | Indicates whether the date range picker should instantly update the value of the attached `<input>`  element when the selected dates change.<br/>The `<input>` element will be always updated on `Apply` and reverted when user clicks on `Cancel`. |
-| onOutsideClick | <code>string</code> | <code>&quot;none&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. |
+| 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)` 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/> 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/> |
+| 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/> |
 | 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 |
@@ -500,9 +526,9 @@ Options for DateRangePicker
 | locale.format | <code>object</code> \| <code>string</code> |  | Default: `DateTime.DATE_SHORT`<br/>Date formats. Either given as string,  see [Format Tokens](https://moment.github.io/luxon/#/formatting?id=table-of-tokens) or an object according  to [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)<br/> I recommend to use the luxon [Presets](https://moment.github.io/luxon/#/formatting?id=presets). |
 | locale.separator= | <code>string</code> |  | Defaut: `' - '` - Separator for start and end time |
 | locale.weekLabel | <code>string</code> | <code>&quot;W&quot;</code> | Label for week numbers |
-| locale.daysOfWeek | <code>Array</code> |  | Default: `Info.weekdays('short')`<br/>Array with weekday names, from Monday to Sunday |
-| locale.monthNames | <code>Array</code> |  | Default: `Info.months('long')`<br/>Array with month names |
-| locale.firstDay | <code>number</code> |  | Default: `Info.getStartOfWeek()`<br/>First day of the week, 1 for Monday through 7 for Sunday |
+| locale.daysOfWeek | <code>Array</code> |  | Default: `luxon.weekdays('short')`<br/>Array with weekday names, from Monday to Sunday |
+| locale.monthNames | <code>Array</code> |  | Default: `luxon.Info.months('long')`<br/>Array with month names |
+| locale.firstDay | <code>number</code> |  | Default: `luxon.Info.getStartOfWeek()`<br/>First day of the week, 1 for Monday through 7 for Sunday |
 | locale.applyLabel | <code>string</code> | <code>&quot;Apply&quot;</code> | Label of `Apply` Button |
 | locale.cancelLabel | <code>string</code> | <code>&quot;Cancel&quot;</code> | Label of `Cancel` Button |
 | locale.customRangeLabel | <code>string</code> | <code>&quot;Custom&quot;</code> | Range - Title for custom ranges |

package/daterangepicker.js

@@ -89,20 +89,21 @@
         
         * @property {boolean} autoUpdateInput=true - Indicates whether the date range picker should instantly update the value of the attached `<input>` 
         * element when the selected dates change.<br/>The `<input>` element will be always updated on `Apply` and reverted when user clicks on `Cancel`.
-        * @property {string} onOutsideClick=none - Defines what picker shall do when user clicks outside the calendar. 
+        * @property {string} onOutsideClick=apply - Defines what picker shall do when user clicks outside the calendar. 
         * `'apply'` or `'cancel'`. Event {@link #event_outsideClick.daterangepicker|onOutsideClick.daterangepicker} is always emitted.
         * @property {boolean} linkedCalendars=true - 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
         * @property {function} isInvalidDate=false - 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)`
+        * Signature: `isInvalidDate(date)`<br/>
         * 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/>
-        * `side` is 'start' or 'end' or `null` for `singleDatePicker = true`<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`, {@link #DateRangePicker+setStartDate|setStartDate}, {@link #DateRangePicker+setEndDate|setEndDate}.<br/>
         * Ensure that your function returns `false` for at least one item. Otherwise the calender is not rendered.<br/>
         * @property {function} isCustomDate=false - A function that is passed each date in the two calendars before they are displayed, 
@@ -135,9 +136,9 @@
         * I recommend to use the luxon [Presets](https://moment.github.io/luxon/#/formatting?id=presets).
         * @property {string} locale.separator= - Defaut: `' - '` - Separator for start and end time
         * @property {string} locale.weekLabel=W - Label for week numbers
-        * @property {Array} locale.daysOfWeek - Default: `Info.weekdays('short')`<br/>Array with weekday names, from Monday to Sunday
-        * @property {Array} locale.monthNames - Default: `Info.months('long')`<br/>Array with month names
-        * @property {number} locale.firstDay - Default: `Info.getStartOfWeek()`<br/>First day of the week, 1 for Monday through 7 for Sunday
+        * @property {Array} locale.daysOfWeek - Default: `luxon.weekdays('short')`<br/>Array with weekday names, from Monday to Sunday
+        * @property {Array} locale.monthNames - Default: `luxon.Info.months('long')`<br/>Array with month names
+        * @property {number} locale.firstDay - Default: `luxon.Info.getStartOfWeek()`<br/>First day of the week, 1 for Monday through 7 for Sunday
         * @property {string} locale.applyLabel=Apply - Label of `Apply` Button
         * @property {string} locale.cancelLabel=Cancel - Label of `Cancel` Button
         * @property {string} locale.customRangeLabel=Custom Range - Title for custom ranges
@@ -1045,7 +1046,7 @@
         },
 
         /**
-        * Displays the months
+        * Shows calendar months based on selected date values
         * @private
         */
         updateMonthsInView: function () {
@@ -1085,7 +1086,7 @@
         },
 
         /**
-        * Updates the custome ranges 
+        * Updates the selected day value from calendar with selected time values
         * @private
         */
         updateCalendars: function () {
@@ -1568,7 +1569,7 @@
         },
 
         /**
-        * Update the linke `<input>` element with selected date
+        * Disable the `Apply` button if no date value is selected
         * @private
         */
         updateFormInputs: function () {
@@ -1581,7 +1582,7 @@
         },
 
         /**
-        * Positions the calendar
+        * Place the picker at the right place in the document
         * @private
         */
         move: function () {
@@ -1783,6 +1784,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);
@@ -1804,8 +1806,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
@@ -1816,7 +1817,6 @@
         /**
         * Shows calendar when user selects "Custom Ranges"
         * @emits "showCalendar.daterangepicker"
-        * @private
         */
         showCalendars: function () {
             this.container.addClass('show-calendar');
@@ -1834,7 +1834,6 @@
         /**
         * Hides calendar when user selects a predefined range
         * @emits "hideCalendar.daterangepicker"
-        * @private
         */
         hideCalendars: function () {
             this.container.removeClass('show-calendar');
@@ -2113,7 +2112,6 @@
 
         /**
         * Hightlight selected predefined range in calendar
-        * @param {external:jQuery} e - The Event target
         * @private
         */
         calculateChosenLabel: function () {
@@ -2309,10 +2307,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;
 
@@ -2330,7 +2330,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);
@@ -2338,7 +2341,7 @@
         },
 
         /**
-        * Handles key press
+        * Handles key press, IE 11 compatibility
         * @param {external:jQuery} e - The Event target
         * @private
         */
@@ -2358,8 +2361,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)
@@ -2378,8 +2381,7 @@
         },
 
         /**
-        * Remove the picker from document
-        * @private
+        * Removes the picker from document
         */
         remove: function () {
             this.container.remove();
@@ -2401,8 +2403,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) {
@@ -2422,10 +2425,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.1",
+  "version": "4.2.3",
   "description": "Date range picker with time component and pre-defined ranges",
   "main": "daterangepicker.js",
   "style": "daterangepicker.css",