@wernfried/daterangepicker 4.17.5 → 4.19.0

package/dist/esm/daterangepicker.js

@@ -532,6 +532,160 @@ class DateRangePicker {
   set endDate(val) {
     this.#endDate = val;
   }
+  /**
+   * DateRangePicker specific events
+   */
+  #events = {
+    /**
+    * Emitted when the date is changed through `<input>` element or via {@link #DateRangePicker+setStartDate|setStartDate} or 
+    * {@link #DateRangePicker+setRange|setRange} and date is not valid due to 
+    * `minDate`, `maxDate`, `minSpan`, `maxSpan`, `invalidDate` and `invalidTime` constraints.<br>
+    * Event is only triggered when date string is valid and date value is changing<br>
+    * @event
+    * @name "violate.daterangepicker"
+    * @param {DateRangePicker} picker - The daterangepicker object
+    * @param {InputViolation} result - The violation object, see example of `validateInput()`
+    * @param {Object} newDate - Object of {startDate, endDate}
+    * @return {boolean}=undefined - If handler returns `true`, then values from `newDate` object are used
+    * @example
+    * 
+    * $('#picker').daterangepicker({
+    *   startDate: DateTime.now(),
+    *   // allow only dates from current year
+    *   minDate: DateTime.now().startOf('year'),
+    *   manDate: DateTime.now().endOf('year'),
+    *   singleDatePicker: true,
+    *   locale: {
+    *      format: DateTime.DATETIME_SHORT
+    *   }
+    * }).on('violate.daterangepicker', (ev, picker, result, newDate) => {
+    *   newDate.startDate = DateTime.now().minus({ days: 3 }).startOf('day');
+    *   return true;
+    * });
+    *
+    * // Try to set date outside permitted range at <input> elemet
+    * $('#picker').val(DateTime.now().minus({ years: 10 })).toLocaleString(DateTime.DATETIME_SHORT).trigger('keyup');
+    
+    * // Try to set date outside permitted range by code
+    * const drp = $('#picker').data('daterangepicker').setStartDate(DateTime.now().minus({ years: 10 })
+    * 
+    * // -> Calendar selects and shows "today - 3 days"
+    */
+    onViolate: { type: "violate.daterangepicker", param: (...args) => [this, ...args] },
+    /**
+    * Emitted before the calendar time picker is rendered.
+    * @event
+    * @name "beforeRenderCalendar.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    */
+    onBeforeRenderTimePicker: { type: "beforeRenderTimePicker.daterangepicker", param: this },
+    /**
+    * Emitted before the calendar is rendered. Useful to remove any manually added elements.
+    * @event
+    * @name "beforeRenderCalendar.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    */
+    onBeforeRenderCalendar: { type: "beforeRenderCalendar.daterangepicker", param: this },
+    /**
+    * Emitted when the picker is shown 
+    * @event
+    * @name "show.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    */
+    onShow: { type: "show.daterangepicker", param: this },
+    /**
+    * Emitted before the picker will hide. When EventHandler returns `true`, then picker remains visible
+    * @event
+    * @name "beforeHide.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    * @return {boolean} cancel - If `true`, then the picker remains visible
+    */
+    onBeforeHide: { type: "beforeHide.daterangepicker", param: this },
+    /**
+    * Emitted when the picker is hidden
+    * @event
+    * @name "hide.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    */
+    onHide: { type: "hide.daterangepicker", param: this },
+    /**
+    * Emitted when the calendar(s) are shown.
+    * Only useful when {@link #Ranges|Ranges} are used.
+    * @event
+    * @name "showCalendar.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    */
+    onShowCalendar: { type: "showCalendar.daterangepicker", param: this },
+    /**
+    * Emitted when the calendar(s) are hidden. Only used when {@link #Ranges|Ranges} are used.
+    * @event
+    * @name "hideCalendar.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    */
+    onHideCalendar: { type: "hideCalendar.daterangepicker", param: this },
+    /**
+    * Emitted when user clicks outside the picker. 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
+    */
+    onOutsideClick: { type: "outsideClick.daterangepicker", param: this },
+    /**
+    * Emitted when the date changed. Does not trigger when time is changed, use {@link #event_timeChange.daterangepicker|"timeChange.daterangepicker"} to handle it
+    * @event
+    * @name "dateChange.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    * @param {string} side - Either `'start'` or `'end'` indicating whether startDate or endDate was changed. `null` when `singleDatePicker: true`
+    */
+    onDateChange: { type: "dateChange.daterangepicker", param: (side) => [this, side] },
+    /**
+    * Emitted when the time changed. Does not trigger when date is changed
+    * @event
+    * @name "timeChange.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    * @param {string} side - Either `'start'` or `'end'` indicating whether startDate or endDate was changed
+    */
+    onTimeChange: { type: "timeChange.daterangepicker", param: (side) => [this, side] },
+    /**
+    * Emitted when the `Apply` button is clicked, or when a predefined {@link #Ranges|Ranges} is clicked 
+    * @event
+    * @name "apply.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    */
+    onApply: { type: "apply.daterangepicker", param: this },
+    /**
+    * Emitted when the `Cancel` button is clicked
+    * @event
+    * @name "cancel.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    */
+    onCancel: { type: "cancel.daterangepicker", param: this },
+    /**
+    * Emitted when the date is changed through `<input>` element. Event is only triggered when date string is valid and date value has changed
+    * @event
+    * @name "inputChange.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    */
+    onInputChange: { type: "inputChange.daterangepicker", param: this },
+    /**
+    * Emitted after month view changed, for example by click on 'prev' or 'next'
+    * @event
+    * @name "monthViewChange.daterangepicker"
+    * @param {DateRangePicker} this - The daterangepicker object
+    * @param {external:DateTime} left - For day of left-hand calendar
+    * @param {external:DateTime|null} right - For day of right-hand calendar
+    */
+    onMonthViewChange: {
+      type: "monthViewChange.daterangepicker",
+      param: (left, right) => [this, left.startOf("month"), right ? right.startOf("month") : null]
+    }
+  };
+  /**
+   * Getter for all DateRangePickerEvents
+   */
+  get events() {
+    return this.#events;
+  }
   /* #region Set startDate/endDate */
   /**
   * Sets the date range picker's currently selected start date to the provided date.<br>
@@ -559,6 +713,7 @@ class DateRangePicker {
         return violations;
       }
     }
+    const monthChange = !this.#startDate.hasSame(newDate, "month");
     this.#startDate = newDate;
     this.#endDate = this.#startDate;
     if (!this.timePicker) {
@@ -567,7 +722,7 @@ class DateRangePicker {
     }
     this.updateElement();
     if (updateView)
-      this.updateView();
+      this.updateView(monthChange);
     return violations;
   }
   /**
@@ -614,6 +769,7 @@ class DateRangePicker {
         return violations;
       }
     }
+    const monthChange = !this.#startDate.hasSame(newDate[0], "month") || !this.#endDate.hasSame(newDate[1], "month");
     this.#startDate = newDate[0];
     this.#endDate = newDate[1];
     if (!this.timePicker) {
@@ -622,7 +778,7 @@ class DateRangePicker {
     }
     this.updateElement();
     if (updateView)
-      this.updateView();
+      this.updateView(monthChange);
     return violations;
   }
   /**
@@ -708,42 +864,6 @@ class DateRangePicker {
     }
   }
   /**
-  * Emitted when the date is changed through `<input>` element or via {@link #DateRangePicker+setStartDate|setStartDate} or 
-  * {@link #DateRangePicker+setRange|setRange} and date is not valid due to 
-  * `minDate`, `maxDate`, `minSpan`, `maxSpan`, `invalidDate` and `invalidTime` constraints.<br>
-  * Event is only triggered when date string is valid and date value is changing<br>
-  * @event
-  * @name "violated.daterangepicker"
-  * @param {Object} this - The event object
-  * @param {DateRangePicker} picker - The daterangepicker object
-  * @param {InputViolation} result - The violation object, see example of `validateInput()`
-  * @param {Object} newDate - Object of {startDate, endDate}
-  * @return {boolean}=undefined - If handler returns `true`, then values from `newDate` object are used
-  * @example
-  * 
-  * $('#picker').daterangepicker({
-  *   startDate: DateTime.now(),
-  *   // allow only dates from current year
-  *   minDate: DateTime.now().startOf('year'),
-  *   manDate: DateTime.now().endOf('year'),
-  *   singleDatePicker: true,
-  *   locale: {
-  *      format: DateTime.DATETIME_SHORT
-  *   }
-  * }).on('violated.daterangepicker', (ev, picker, result, newDate) => {
-  *   newDate.startDate = DateTime.now().minus({ days: 3 }).startOf('day');
-  *   return true;
-  * });
-  *
-  * // Try to set date outside permitted range at <input> elemet
-  * $('#picker').val(DateTime.now().minus({ years: 10 })).toLocaleString(DateTime.DATETIME_SHORT).trigger('keyup');
-  
-  * // Try to set date outside permitted range by code
-  * const drp = $('#picker').data('daterangepicker').setStartDate(DateTime.now().minus({ years: 10 })
-  * 
-  * // -> Calendar selects and shows "today - 3 days"
-  */
-  /**
   * @typedef InputViolation
   * @type {Object}
   * @property {external:DateTime} startDate - Violation of startDate
@@ -843,7 +963,7 @@ class DateRangePicker {
         return null;
       if (dipatch) {
         let newValues = { startDate };
-        const ret = this.element.triggerHandler("violated.daterangepicker", [this, result, newValues]);
+        const ret = this.triggerHandler(this.#events.onViolate, result, newValues);
         if (ret) {
           result.newDate = newValues;
           return result;
@@ -919,7 +1039,7 @@ class DateRangePicker {
       return null;
     if (dipatch) {
       let newValues = { startDate, endDate };
-      const ret = this.element.triggerHandler("violated.daterangepicker", [this, result, newValues]);
+      const ret = this.triggerHandler(this.#events.onViolate, result, newValues);
       if (ret) {
         result.newDate = newValues;
         return result;
@@ -933,11 +1053,12 @@ class DateRangePicker {
   /**
   * Updates the picker when calendar is initiated or any date has been selected. 
   * Could be useful after running {@link #DateRangePicker+setStartDate|setStartDate} or {@link #DateRangePicker+setEndDate|setRange} 
+  * @param {boolean} monthChange - If `true` then monthView changed
   * @emits "beforeRenderTimePicker.daterangepicker"
   */
-  updateView() {
+  updateView(monthChange) {
     if (this.timePicker) {
-      this.element.trigger("beforeRenderTimePicker.daterangepicker", this);
+      this.triggerEvent(this.#events.onBeforeRenderTimePicker);
       this.renderTimePicker("start");
       this.renderTimePicker("end");
       if (!this.#endDate) {
@@ -948,7 +1069,7 @@ class DateRangePicker {
     }
     this.updateLabel();
     this.updateMonthsInView();
-    this.updateCalendars();
+    this.updateCalendars(monthChange);
     this.setApplyBtnState();
   }
   /**
@@ -987,9 +1108,11 @@ class DateRangePicker {
   /**
   * Updates the selected day value from calendar with selected time values
   * @emits "beforeRenderCalendar.daterangepicker"
+  * @emits "monthViewChange.daterangepicker"
+  * @param {boolean} monthChange - If `true` then monthView changed
   * @private
   */
-  updateCalendars() {
+  updateCalendars(monthChange) {
     if (this.timePicker) {
       var hour, minute, second;
       if (this.#endDate) {
@@ -1033,9 +1156,15 @@ class DateRangePicker {
       if (!this.singleMonthView)
         this.rightCalendar.month = this.rightCalendar.month.set({ hour: 0, minute: 0, second: 0 });
     }
-    this.element.trigger("beforeRenderCalendar.daterangepicker", this);
+    this.triggerEvent(this.#events.onBeforeRenderCalendar);
     this.renderCalendar("left");
     this.renderCalendar("right");
+    if (monthChange)
+      this.triggerEvent(
+        this.#events.onMonthViewChange,
+        this.leftCalendar.month,
+        this.singleMonthView || this.singleDatePicker ? null : this.rightCalendar.month
+      );
     this.container.find(".ranges li").removeClass("active");
     if (this.#endDate == null) return;
     this.calculateChosenLabel();
@@ -1478,10 +1607,10 @@ class DateRangePicker {
     }.bind(this));
     this.oldStartDate = this.#startDate;
     this.oldEndDate = this.#endDate;
-    this.updateView();
+    this.updateView(false);
     this.container.show();
     this.move();
-    this.element.trigger("show.daterangepicker", this);
+    this.triggerEvent(this.#events.onShow);
     this.isShowing = true;
   }
   /**
@@ -1498,12 +1627,12 @@ class DateRangePicker {
     if (!this.#startDate.equals(this.oldStartDate) || !this.#endDate.equals(this.oldEndDate))
       this.callback(this.startDate, this.endDate, this.chosenLabel);
     this.updateElement();
-    if (this.element.triggerHandler("beforeHide.daterangepicker", this))
+    if (this.triggerHandler(this.#events.onBeforeHide))
       return;
     $(document).off(".daterangepicker");
     $(window).off(".daterangepicker");
     this.container.hide();
-    this.element.trigger("hide.daterangepicker", this);
+    this.triggerEvent(this.#events.onHide);
     this.isShowing = false;
   }
   /**
@@ -1523,7 +1652,7 @@ class DateRangePicker {
   showCalendars() {
     this.container.addClass("show-calendar");
     this.move();
-    this.element.trigger("showCalendar.daterangepicker", this);
+    this.triggerEvent(this.#events.onShowCalendar);
   }
   /**
   * Hides calendar when user selects a predefined range
@@ -1531,7 +1660,7 @@ class DateRangePicker {
   */
   hideCalendars() {
     this.container.removeClass("show-calendar");
-    this.element.trigger("hideCalendar.daterangepicker", this);
+    this.triggerEvent(this.#events.onHideCalendar);
   }
   /* #endregion */
   /* #region Handle mouse related events */
@@ -1552,7 +1681,7 @@ class DateRangePicker {
       this.#endDate = this.oldEndDate;
     }
     this.hide();
-    this.element.trigger("outsideClick.daterangepicker", this);
+    this.triggerEvent(this.#events.onOutsideClick);
   }
   /**
   * Move calendar to previous month
@@ -1568,7 +1697,7 @@ class DateRangePicker {
     } else {
       this.rightCalendar.month = this.rightCalendar.month.minus({ month: 1 });
     }
-    this.updateCalendars();
+    this.updateCalendars(true);
   }
   /**
   * Move calendar to next month
@@ -1584,7 +1713,7 @@ class DateRangePicker {
       if (this.linkedCalendars)
         this.leftCalendar.month = this.leftCalendar.month.plus({ month: 1 });
     }
-    this.updateCalendars();
+    this.updateCalendars(true);
   }
   /**
   * User hovers over date values
@@ -1689,17 +1818,18 @@ class DateRangePicker {
     if (label == this.locale.customRangeLabel) {
       this.showCalendars();
     } else {
-      var dates = this.ranges[label];
-      this.#startDate = dates[0];
-      this.#endDate = dates[1];
+      var newDate = this.ranges[label];
+      const monthChange = !this.#startDate.hasSame(newDate[0], "month") || !this.#endDate.hasSame(newDate[1], "month");
+      this.#startDate = newDate[0];
+      this.#endDate = newDate[1];
       if (!this.timePicker) {
         this.#startDate.startOf("day");
         this.#endDate.endOf("day");
       }
       if (!this.alwaysShowCalendars)
         this.hideCalendars();
-      if (this.element.triggerHandler("beforeHide.daterangepicker", this))
-        this.updateView();
+      if (this.triggerHandler(this.#events.onBeforeHide))
+        this.updateView(monthChange);
       this.clickApply();
     }
   }
@@ -1778,11 +1908,11 @@ class DateRangePicker {
         this.clickApply();
       side = null;
     }
-    this.updateView();
+    this.updateView(false);
     e.stopPropagation();
     if (this.autoUpdateInput)
       this.updateElement();
-    this.element.trigger("dateChange.daterangepicker", [this, side]);
+    this.triggerEvent(this.#events.onDateChange, side);
   }
   /**
   * Hightlight selected predefined range in calendar
@@ -1865,14 +1995,14 @@ class DateRangePicker {
     } else if (this.#endDate) {
       this.#endDate = this.#endDate.set({ hour, minute, second });
     }
-    this.updateCalendars();
+    this.updateCalendars(false);
     this.setApplyBtnState();
-    this.element.trigger("beforeRenderTimePicker.daterangepicker", this);
+    this.triggerEvent(this.#events.onBeforeRenderTimePicker);
     this.renderTimePicker("start");
     this.renderTimePicker("end");
     if (this.autoUpdateInput)
       this.updateElement();
-    this.element.trigger("timeChange.daterangepicker", [this, this.singleDatePicker ? null : side]);
+    this.triggerEvent(this.#events.onTimeChange, this.singleDatePicker ? null : side);
   }
   /**
   * Calender month moved
@@ -1883,6 +2013,7 @@ class DateRangePicker {
     var isLeft = $(e.target).closest(".drp-calendar").hasClass("left"), leftOrRight = isLeft ? "left" : "right", cal = this.container.find(".drp-calendar." + leftOrRight);
     var month = parseInt(cal.find(".monthselect").val(), 10);
     var year = cal.find(".yearselect").val();
+    let monthChange = false;
     if (!isLeft) {
       if (year < this.#startDate.year || year == this.#startDate.year && month < this.#startDate.month) {
         month = this.#startDate.month;
@@ -1902,15 +2033,17 @@ class DateRangePicker {
       }
     }
     if (isLeft) {
+      monthChange = !DateTime.fromObject({ year, month }).hasSame(this.leftCalendar.month, "month");
       this.leftCalendar.month = this.leftCalendar.month.set({ year, month });
       if (this.linkedCalendars)
         this.rightCalendar.month = this.leftCalendar.month.plus({ month: 1 });
     } else {
+      monthChange = !DateTime.fromObject({ year, month }).hasSame(this.leftCalendar.month, "month");
       this.rightCalendar.month = this.rightCalendar.month.set({ year, month });
       if (this.linkedCalendars)
         this.leftCalendar.month = this.rightCalendar.month.minus({ month: 1 });
     }
-    this.updateCalendars();
+    this.updateCalendars(monthChange);
   }
   /**
   * User clicked `Apply` button
@@ -1919,7 +2052,7 @@ class DateRangePicker {
      */
   clickApply() {
     this.hide();
-    this.element.trigger("apply.daterangepicker", this);
+    this.triggerEvent(this.#events.onApply);
   }
   /**
   * User clicked `Cancel` button
@@ -1930,13 +2063,13 @@ class DateRangePicker {
     this.#startDate = this.oldStartDate;
     this.#endDate = this.oldEndDate;
     this.hide();
-    this.element.trigger("cancel.daterangepicker", this);
+    this.triggerEvent(this.#events.onCancel);
   }
   /* #endregion */
   /**
   * Update the picker with value from `<input>` element.<br> 
   * Input values must be given in format of `locale.format`. Invalid values are handles by `violated.daterangepicker` Event
-  * @emits "inputChanged.daterangepicker"
+  * @emits "inputChange.daterangepicker"
   * @private
   */
   elementChanged() {
@@ -1944,6 +2077,7 @@ class DateRangePicker {
     if (!this.element.val().length) return;
     const format = typeof this.locale.format === "string" ? this.locale.format : DateTime.parseFormatForOpts(this.locale.format);
     const dateString = this.element.val().split(this.locale.separator);
+    let monthChange = false;
     if (this.singleDatePicker) {
       let newDate = DateTime.fromFormat(this.element.val(), format, { locale: DateTime.now().locale });
       const oldDate = this.#startDate;
@@ -1957,6 +2091,7 @@ class DateRangePicker {
           return;
         }
       }
+      monthChange = !this.#startDate.hasSame(newDate, "month");
       this.#startDate = newDate;
       this.#endDate = this.#startDate;
       if (!this.timePicker) {
@@ -1977,6 +2112,7 @@ class DateRangePicker {
           return;
         }
       }
+      monthChange = !this.#startDate.hasSame(newDate[0], "month") || !this.#endDate.hasSame(newDate[1], "month");
       this.#startDate = newDate[0];
       this.#endDate = newDate[1];
       if (!this.timePicker) {
@@ -1986,9 +2122,9 @@ class DateRangePicker {
     } else {
       return;
     }
-    this.updateView();
+    this.updateView(monthChange);
     this.updateElement();
-    this.element.trigger("inputChanged.daterangepicker", this);
+    this.triggerEvent(this.#events.onInputChange);
   }
   /**
   * Handles key press, IE 11 compatibility
@@ -2068,6 +2204,34 @@ class DateRangePicker {
     this.element.off(".daterangepicker");
     this.element.removeData();
   }
+  /**
+   * Helper function to trigger events
+   * @param {Event} ev - From this.#events
+   * @param  {...any} args - Argument spread
+   * @private
+   */
+  triggerEvent(ev, ...args) {
+    if (args.length === 0) {
+      this.element.trigger(ev.type, ev.param);
+    } else {
+      const params = ev.param(...args);
+      this.element.trigger(ev.type, params);
+    }
+  }
+  /**
+   * Helper function to trigger events
+   * @param {Event} ev - From this.#events
+   * @param  {...any} args - Argument spread
+   * @private
+   */
+  triggerHandler(ev, ...args) {
+    if (args.length === 0) {
+      return this.element.triggerHandler(ev.type, ev.param);
+    } else {
+      const params = ev.param(...args);
+      return this.element.triggerHandler(ev.type, params);
+    }
+  }
 }
 if (!$.fn.daterangepicker) {
   $.fn.daterangepicker = function(options, callback) {