@ionic/core 9.0.11-dev.11793888057.13a7fa02 → 9.0.11-dev.11793890855.1bf6a6e5

package/dist/collection/components/datetime/datetime.js

@@ -50,6 +50,11 @@ import { checkForPresentationFormatMismatch, warnIfTimeZoneProvided } from "./ut
  * @part calendar-day today - The calendar day that contains the current day.
  * @part calendar-day disabled - The calendar day that is disabled.
  *
+ * @part range-start - The calendar day button that is the start of a range selection.
+ * @part range-end - The calendar day button that is the end of a range selection.
+ * @part range-selection - The calendar day button that is part of a range selection (includes start and end).
+ * @part range-track - The track that connects the start and end days of a range selection.
+ *
  * @part datetime-header - The datetime header contains the content for the `title` slot and the selected date.
  * @part datetime-title - The element that contains the `title` slot content.
  * @part datetime-selected-date - The element that contains the selected date.
@@ -130,8 +135,22 @@ export class Datetime {
         /**
          * If `true`, multiple dates can be selected at once. Only
          * applies to `presentation="date"` and `preferWheel="false"`.
+         *
+         * @deprecated Use `selectionMode="multiple"` instead.
          */
         this.multiple = false;
+        /**
+         * The text shown in the datetime header when the start of the range
+         * is empty, also used by screen readers to announce the start date.
+         * Only applies when `selectionMode="range"`.
+         */
+        this.startDateLabel = 'Start date';
+        /**
+         * The text shown in the datetime header when the end of the range
+         * is empty, also used by screen readers to announce the end date.
+         * Only applies when `selectionMode="range"`.
+         */
+        this.endDateLabel = 'End date';
         /**
          * If `true`, a header will be shown above the calendar
          * picker. This will include both the slotted title, and
@@ -184,8 +203,8 @@ export class Datetime {
          */
         this.preferWheel = false;
         this.warnIfIncorrectValueUsage = () => {
-            const { multiple, value } = this;
-            if (!multiple && Array.isArray(value)) {
+            const { value } = this;
+            if (!this.isMultipleMode && !this.isRangeMode && Array.isArray(value)) {
                 /**
                  * We do some processing on the `value` array so
                  * that it looks more like an array when logged to
@@ -194,7 +213,13 @@ export class Datetime {
                  * Default toString() behavior: a,b
                  * Custom behavior: ['a', 'b']
                  */
-                printIonWarning(`[ion-datetime] - An array of values was passed, but multiple is "false". This is incorrect usage and may result in unexpected behaviors. To dismiss this warning, pass a string to the "value" property when multiple="false".
+                printIonWarning(`[ion-datetime] - An array of values was passed, but neither selectionMode="multiple" nor selectionMode="range" is set. This is incorrect usage and may result in unexpected behaviors.
+
+  Value Passed: [${value.map((v) => `'${v}'`).join(', ')}]
+`, this.el);
+            }
+            if (this.isRangeMode && Array.isArray(value) && value.length > 2) {
+                printIonWarning(`[ion-datetime] - More than 2 values were passed with selectionMode="range". Only the first and last values will be used.
 
   Value Passed: [${value.map((v) => `'${v}'`).join(', ')}]
 `, this.el);
@@ -220,6 +245,9 @@ export class Datetime {
         };
         this.getActivePart = () => {
             const { activeParts } = this;
+            if (this.isRangeParts(activeParts)) {
+                return activeParts.start;
+            }
             return Array.isArray(activeParts) ? activeParts[0] : activeParts;
         };
         this.closeParentOverlay = (role) => {
@@ -234,6 +262,33 @@ export class Datetime {
                 ...parts,
             };
         };
+        /**
+         * Checks whether the span from start to end contains any disabled day.
+         * Used by range mode to prevent selecting across disabled dates.
+         */
+        this.rangeContainsDisabledDate = (start, end) => {
+            const { minParts, maxParts, parsedDayValues, parsedMonthValues, parsedYearValues, isDateEnabled } = this;
+            let cursor = getNextDay(start);
+            while (isBefore(cursor, end)) {
+                if (isDayDisabled(cursor, minParts, maxParts, parsedDayValues) ||
+                    (parsedMonthValues !== undefined && !parsedMonthValues.includes(cursor.month)) ||
+                    (parsedYearValues !== undefined && !parsedYearValues.includes(cursor.year))) {
+                    return true;
+                }
+                if (isDateEnabled) {
+                    try {
+                        if (!isDateEnabled(convertDataToISO(cursor))) {
+                            return true;
+                        }
+                    }
+                    catch {
+                        // Swallow user callback exceptions during validation
+                    }
+                }
+                cursor = getNextDay(cursor);
+            }
+            return false;
+        };
         this.setActiveParts = (parts, removeDate = false) => {
             /** if the datetime component is in readonly mode,
              * allow browsing of the calendar without changing
@@ -243,7 +298,7 @@ export class Datetime {
                 return;
             }
             this.hasUnconfirmedSelection = true;
-            const { multiple, minParts, maxParts, activeParts } = this;
+            const { minParts, maxParts, activeParts } = this;
             /**
              * When setting the active parts, it is possible
              * to set invalid data. For example,
@@ -256,7 +311,10 @@ export class Datetime {
              */
             const validatedParts = validateParts(parts, minParts, maxParts);
             this.setWorkingParts(validatedParts);
-            if (multiple) {
+            if (this.isRangeMode) {
+                this.setActivePartsRange(validatedParts);
+            }
+            else if (this.isMultipleMode) {
                 const activePartsArray = Array.isArray(activeParts) ? activeParts : [activeParts];
                 if (removeDate) {
                     this.activeParts = activePartsArray.filter((p) => !isSameDay(p, validatedParts));
@@ -276,6 +334,25 @@ export class Datetime {
             }
             this.confirm();
         };
+        /**
+         * Handles range selection logic when a day is clicked.
+         *
+         * Creating a new range: first click sets start, second sets end.
+         * Modifying an existing range:
+         *   - Before range → new start
+         *   - Within range → new end
+         *   - After range → new end
+         * If the resulting span contains a disabled date, start a new range instead.
+         */
+        this.setActivePartsRange = (parts) => {
+            const current = this.rangeParts;
+            if (!current || isBefore(parts, current.start) || this.rangeContainsDisabledDate(current.start, parts)) {
+                this.activeParts = { start: parts };
+            }
+            else {
+                this.activeParts = { start: current.start, end: parts };
+            }
+        };
         this.initializeKeyboardListeners = () => {
             const calendarBodyRef = this.calendarBodyRef;
             if (!calendarBodyRef) {
@@ -687,6 +764,57 @@ export class Datetime {
             if (hasValue) {
                 warnIfValueOutOfBounds(valueToProcess, minParts, maxParts);
             }
+            /**
+             * Range mode: convert the value array into DatetimeRangeParts.
+             */
+            if (this.isRangeMode) {
+                /**
+                 * The calendar navigates to the start of the range, or to the default
+                 * date when there is nothing selected, so that an empty range mode
+                 * opens on the same month as the other selection modes.
+                 */
+                let navigateTo;
+                if (hasValue && Array.isArray(valueToProcess)) {
+                    let rangeValues = valueToProcess;
+                    // If more than 2 entries, use first and last
+                    if (rangeValues.length > 2) {
+                        rangeValues = [rangeValues[0], rangeValues[rangeValues.length - 1]];
+                    }
+                    let startParts = rangeValues[0];
+                    let endParts = rangeValues.length > 1 ? rangeValues[1] : undefined;
+                    // Normalize reversed pairs so earlier date is start
+                    if (endParts && isAfter(startParts, endParts)) {
+                        const temp = startParts;
+                        startParts = endParts;
+                        endParts = temp;
+                    }
+                    this.activeParts = endParts ? { start: startParts, end: endParts } : { start: startParts };
+                    /**
+                     * Stay on the end date's month when it is already showing, such as
+                     * right after the user picks it, instead of jumping back to the start.
+                     */
+                    navigateTo = startParts;
+                    if (endParts && endParts.month === workingParts.month && endParts.year === workingParts.year) {
+                        navigateTo = endParts;
+                    }
+                }
+                else {
+                    this.activeParts = [];
+                    navigateTo = Array.isArray(valueToProcess) ? valueToProcess[0] : valueToProcess;
+                }
+                const targetValue = clampDate(navigateTo, minParts, maxParts);
+                const { month, day, year } = targetValue;
+                const didChangeMonth = (month !== undefined && month !== workingParts.month) || (year !== undefined && year !== workingParts.year);
+                const bodyIsVisible = el.classList.contains('datetime-ready');
+                const { isGridStyle, showMonthAndYear } = this;
+                if (isGridStyle && didChangeMonth && bodyIsVisible && !showMonthAndYear) {
+                    this.animateToDate(targetValue);
+                }
+                else {
+                    this.setWorkingParts({ month, day, year, hour: 0, minute: 0, ampm: 'am' });
+                }
+                return;
+            }
             /**
              * If there are multiple values, clamp to the last one.
              * This is because the last value is the one that the user
@@ -848,6 +976,27 @@ export class Datetime {
         const hasDatePresentation = presentation === 'date' || presentation === 'date-time' || presentation === 'time-date';
         return hasDatePresentation && !preferWheel;
     }
+    get isMultipleMode() {
+        return this.selectionMode === 'multiple' || (this.selectionMode === undefined && this.multiple);
+    }
+    get isRangeMode() {
+        return this.selectionMode === 'range';
+    }
+    /**
+     * Type guard: returns true if the given activeParts is a DatetimeRangeParts object.
+     */
+    isRangeParts(parts) {
+        return this.isRangeMode && parts !== null && typeof parts === 'object' && !Array.isArray(parts) && 'start' in parts;
+    }
+    /**
+     * Returns the current range parts if in range mode, or undefined otherwise.
+     */
+    get rangeParts() {
+        if (this.isRangeParts(this.activeParts)) {
+            return this.activeParts;
+        }
+        return undefined;
+    }
     yearValuesChanged() {
         this.parsedYearValues = convertToArrayOfNumbers(this.yearValues);
     }
@@ -883,6 +1032,19 @@ export class Datetime {
      */
     async confirm(closeOverlay = false) {
         const { isCalendarPicker, activeParts, preferWheel, workingParts } = this;
+        /**
+         * In range mode, only confirm when both start and end are selected.
+         */
+        if (this.isRangeMode) {
+            if (!this.isRangeParts(activeParts) || !activeParts.end) {
+                return;
+            }
+            this.setValue([convertDataToISO(activeParts.start), convertDataToISO(activeParts.end)]);
+            if (closeOverlay) {
+                this.closeParentOverlay(CONFIRM_ROLE);
+            }
+            return;
+        }
         /**
          * We only update the value if the presentation is not a calendar picker.
          */
@@ -918,6 +1080,23 @@ export class Datetime {
      * @param startDate A valid [ISO-8601 string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format) to reset the datetime state to.
      */
     async reset(startDate) {
+        if (this.isRangeMode) {
+            /**
+             * In range mode, reset clears the full range. If a startDate
+             * is provided, the calendar navigates to that month without
+             * selecting anything so the user begins a fresh selection.
+             */
+            this.activeParts = [];
+            this.hasUnconfirmedSelection = false;
+            if (startDate) {
+                const parsed = parseDate(startDate);
+                if (parsed) {
+                    const target = Array.isArray(parsed) ? parsed[0] : parsed;
+                    this.setWorkingParts(clampDate(target, this.minParts, this.maxParts));
+                }
+            }
+            return;
+        }
         this.processValue(startDate);
     }
     /**
@@ -1153,8 +1332,11 @@ export class Datetime {
         });
     }
     componentWillLoad() {
-        const { el, formatOptions, highlightedDates, multiple, presentation, preferWheel } = this;
-        if (multiple) {
+        const { el, formatOptions, highlightedDates, multiple, selectionMode, presentation, preferWheel } = this;
+        if (selectionMode === undefined && multiple) {
+            printIonWarning('[ion-datetime] - The "multiple" property is deprecated. Use selectionMode="multiple" instead.', el);
+        }
+        if (this.isMultipleMode) {
             if (presentation !== 'date') {
                 printIonWarning('[ion-datetime] - Multiple date selection is only supported for presentation="date".', el);
             }
@@ -1162,6 +1344,17 @@ export class Datetime {
                 printIonWarning('[ion-datetime] - Multiple date selection is not supported with preferWheel="true".', el);
             }
         }
+        if (this.isRangeMode) {
+            if (presentation !== 'date') {
+                printIonWarning('[ion-datetime] - Range selection is only supported for presentation="date".', el);
+            }
+            if (preferWheel) {
+                printIonWarning('[ion-datetime] - Range selection is not supported with preferWheel="true".', el);
+            }
+        }
+        if (selectionMode !== undefined && multiple) {
+            printIonWarning('[ion-datetime] - Both "selectionMode" and "multiple" are set. "selectionMode" takes precedence.', el);
+        }
         if (highlightedDates !== undefined) {
             if (presentation !== 'date' && presentation !== 'date-time' && presentation !== 'time-date') {
                 printIonWarning('[ion-datetime] - The highlightedDates property is only supported with the date, date-time, and time-date presentations.', el);
@@ -1216,6 +1409,12 @@ export class Datetime {
          * is disabled or readonly.
          */
         const isButtonDisabled = disabled || readonly;
+        /**
+         * In range mode, the confirm button should be disabled until
+         * both a start and end date have been selected.
+         */
+        const isRangeIncomplete = this.isRangeMode && (!this.isRangeParts(this.activeParts) || !this.activeParts.end);
+        const isConfirmDisabled = isButtonDisabled || isRangeIncomplete;
         const confirmFill = theme === 'ionic' ? 'solid' : undefined;
         const hasSlottedButtons = this.el.querySelector('[slot="buttons"]') !== null;
         if (!hasSlottedButtons && !showDefaultButtons && !showClearButton) {
@@ -1235,7 +1434,7 @@ export class Datetime {
         return (h("div", { class: "datetime-footer" }, h("div", { class: "datetime-buttons" }, h("div", { class: {
                 ['datetime-action-buttons']: true,
                 ['has-clear-button']: this.showClearButton,
-            } }, h("slot", { name: "buttons" }, showDefaultButtons && (h("ion-button", { id: "cancel-button", color: this.color, onClick: () => this.cancel(true), disabled: isButtonDisabled }, this.cancelText)), h("div", { class: "datetime-action-buttons-container" }, showClearButton && (h("ion-button", { id: "clear-button", color: this.color, onClick: () => clearButtonClick(), disabled: isButtonDisabled }, this.clearText)), showDefaultButtons && (h("ion-button", { id: "confirm-button", fill: confirmFill, color: this.color, onClick: () => this.confirm(true), disabled: isButtonDisabled }, this.doneText))))))));
+            } }, h("slot", { name: "buttons" }, showDefaultButtons && (h("ion-button", { id: "cancel-button", color: this.color, onClick: () => this.cancel(true), disabled: isButtonDisabled }, this.cancelText)), h("div", { class: "datetime-action-buttons-container" }, showClearButton && (h("ion-button", { id: "clear-button", color: this.color, onClick: () => clearButtonClick(), disabled: isButtonDisabled }, this.clearText)), showDefaultButtons && (h("ion-button", { id: "confirm-button", fill: confirmFill, color: this.color, onClick: () => this.confirm(true), disabled: isConfirmDisabled }, this.doneText))))))));
     }
     /**
      * Wheel picker render methods
@@ -1424,8 +1623,8 @@ export class Datetime {
                     ...this.workingParts,
                     month: ev.detail.value,
                 });
-                // Month wheel is navigation-only in multi-select mode as a fix for https://github.com/ionic-team/ionic-framework/issues/29673
-                if (!this.multiple) {
+                // Month wheel is navigation-only in multi-select and range modes as a fix for https://github.com/ionic-team/ionic-framework/issues/29673
+                if (!this.isMultipleMode && !this.isRangeMode) {
                     this.setActiveParts({
                         ...activePart,
                         month: ev.detail.value,
@@ -1446,8 +1645,8 @@ export class Datetime {
                     ...this.workingParts,
                     year: ev.detail.value,
                 });
-                // Year wheel is navigation-only in multi-select mode as a fix for https://github.com/ionic-team/ionic-framework/issues/29673
-                if (!this.multiple) {
+                // Year wheel is navigation-only in multi-select and range modes as a fix for https://github.com/ionic-team/ionic-framework/issues/29673
+                if (!this.isMultipleMode && !this.isRangeMode) {
                     this.setActiveParts({
                         ...activePart,
                         year: ev.detail.value,
@@ -1591,7 +1790,7 @@ export class Datetime {
                 'calendar-month-disabled': !isWorkingMonth && swipeDisabled,
             } }, h("div", { class: "calendar-month-grid" }, getDaysOfMonth(month, year, this.firstDayOfWeek % 7, this.showAdjacentDays).map((dateObject, index) => {
             const { day, dayOfWeek, isAdjacentDay } = dateObject;
-            const { el, highlightedDates, isDateEnabled, multiple, showAdjacentDays } = this;
+            const { el, highlightedDates, isDateEnabled, showAdjacentDays } = this;
             let _month = month;
             let _year = year;
             if (showAdjacentDays && isAdjacentDay && day !== null) {
@@ -1620,7 +1819,7 @@ export class Datetime {
             }
             const referenceParts = { month: _month, day, year: _year, isAdjacentDay };
             const isCalendarPadding = day === null;
-            const { isActive, isToday, ariaLabel, ariaSelected, disabled: isDayDisabled, text, } = getCalendarDayState(this.locale, referenceParts, this.activeParts, this.todayParts, this.minParts, this.maxParts, this.parsedDayValues);
+            const { isActive, isToday, ariaLabel, ariaSelected, disabled: isDayDisabled, isRangeStart, isRangeEnd, isInRange, text, } = getCalendarDayState(this.locale, referenceParts, this.isRangeParts(this.activeParts) ? [] : this.activeParts, this.todayParts, this.minParts, this.maxParts, this.parsedDayValues, this.rangeParts);
             const dateIsoString = convertDataToISO(referenceParts);
             let isCalDayDisabled = isCalMonthDisabled || isDayDisabled;
             if (!isCalDayDisabled && isDateEnabled !== undefined) {
@@ -1643,24 +1842,57 @@ export class Datetime {
              */
             const isCalDayConstrained = isCalDayDisabled && isDatetimeDisabled;
             const isButtonDisabled = isCalDayDisabled || isDatetimeDisabled;
+            /**
+             * Determine if this day is part of the range selection.
+             * Range styling takes priority over highlightedDates.
+             */
+            const isPartOfRange = isRangeStart || isRangeEnd || isInRange;
             let dateStyle = undefined;
             /**
-             * Custom highlight styles should not override the style for selected dates,
-             * nor apply to "filler days" at the start of the grid.
+             * Custom highlight styles should not override the style for selected dates
+             * or range selection, nor apply to "filler days" at the start of the grid.
              */
-            if (highlightedDates !== undefined && !isActive && day !== null && !isAdjacentDay) {
+            if (highlightedDates !== undefined && !isActive && !isPartOfRange && day !== null && !isAdjacentDay) {
                 dateStyle = getHighlightStyles(highlightedDates, dateIsoString, el);
             }
             let dateParts = undefined;
             // "Filler days" at the beginning of the grid should not get the calendar day
             // CSS parts added to them
             if (!isCalendarPadding && !isAdjacentDay) {
-                dateParts = `calendar-day${isActive ? ' active' : ''}${isToday ? ' today' : ''}${isCalDayDisabled ? ' disabled' : ''}`;
+                dateParts = `calendar-day${isActive || isRangeStart || isRangeEnd ? ' active' : ''}${isToday ? ' today' : ''}${isCalDayDisabled ? ' disabled' : ''}${isRangeStart ? ' range-start range-selection' : ''}${isRangeEnd ? ' range-end range-selection' : ''}${isInRange ? ' range-selection' : ''}`;
             }
             else if (isAdjacentDay) {
-                dateParts = `calendar-day${isCalDayDisabled ? ' disabled' : ''}`;
+                /**
+                 * Adjacent days skip 'active' and 'today' parts but still
+                 * include range parts so ::part() styling is consistent
+                 * with the visual range track rendering.
+                 */
+                dateParts = `calendar-day${isCalDayDisabled ? ' disabled' : ''}${isRangeStart ? ' range-start range-selection' : ''}${isRangeEnd ? ' range-end range-selection' : ''}${isInRange ? ' range-selection' : ''}`;
+            }
+            /**
+             * Build the wrapper's shadow part attribute for range track styling.
+             */
+            const hasCompleteRange = this.rangeParts?.end !== undefined;
+            const wrapperParts = isPartOfRange && hasCompleteRange && !isCalendarPadding ? 'range-track' : undefined;
+            /**
+             * Build the aria-label for range mode accessibility.
+             */
+            let rangeAriaLabel = ariaLabel;
+            if (this.isRangeMode && ariaLabel) {
+                if (isRangeStart) {
+                    rangeAriaLabel += `, ${this.startDateLabel}`;
+                }
+                if (isRangeEnd) {
+                    rangeAriaLabel += `, ${this.endDateLabel}`;
+                }
             }
-            return (h("div", { class: "calendar-day-wrapper" }, h("button", {
+            return (h("div", { class: {
+                    'calendar-day-wrapper': true,
+                    // A start without an end is only the circle until the range is complete
+                    'calendar-day-wrapper-range-start': isRangeStart && this.rangeParts?.end !== undefined,
+                    'calendar-day-wrapper-in-range': isInRange,
+                    'calendar-day-wrapper-range-end': isRangeEnd,
+                }, part: wrapperParts }, h("button", {
                 // We need to use !important for the inline styles here because
                 // otherwise the CSS shadow parts will override these styles.
                 // See https://github.com/WICG/webcomponents/issues/847
@@ -1676,28 +1908,45 @@ export class Datetime {
                 }, tabindex: "-1", "data-day": day, "data-month": _month, "data-year": _year, "data-index": index, "data-day-of-week": dayOfWeek, disabled: isButtonDisabled, class: {
                     'calendar-day-padding': isCalendarPadding,
                     'calendar-day': true,
-                    'calendar-day-active': isActive,
+                    'calendar-day-active': isActive || isRangeStart || isRangeEnd,
                     'calendar-day-constrained': isCalDayConstrained,
                     'calendar-day-today': isToday,
                     'calendar-day-adjacent-day': isAdjacentDay,
-                }, part: dateParts, "aria-hidden": isCalendarPadding ? 'true' : null, "aria-selected": ariaSelected, "aria-label": ariaLabel, onClick: () => {
+                    'calendar-day-range-start': isRangeStart,
+                    'calendar-day-range-end': isRangeEnd,
+                    'calendar-day-in-range': isInRange,
+                }, part: dateParts, "aria-hidden": isCalendarPadding ? 'true' : null, "aria-selected": isActive || isRangeStart || isRangeEnd ? 'true' : ariaSelected, "aria-label": rangeAriaLabel, onClick: () => {
                     if (isCalendarPadding) {
                         return;
                     }
                     if (isAdjacentDay) {
                         // The user selected a day outside the current month. Ignore this button, as the month will be re-rendered.
                         this.el.blur();
-                        this.activeParts = { ...activePart, ...referenceParts };
-                        this.animateToDate(referenceParts);
-                        this.confirm();
+                        if (!this.isRangeMode) {
+                            this.activeParts = { ...activePart, ...referenceParts };
+                        }
+                        if (this.isRangeMode) {
+                            /**
+                             * Wait for the calendar to reach the adjacent month before
+                             * updating the range. setActiveParts also moves workingParts,
+                             * which would make the scroll overshoot by a month.
+                             */
+                            this.animateToDate(referenceParts).then(() => this.setActiveParts(referenceParts));
+                        }
+                        else {
+                            this.animateToDate(referenceParts);
+                            this.confirm();
+                        }
                     }
                     else {
                         this.setWorkingParts({
                             ...this.workingParts,
                             ...referenceParts,
                         });
-                        // Multiple only needs date info so we can wipe out other fields like time.
-                        if (multiple) {
+                        if (this.isRangeMode) {
+                            this.setActiveParts(referenceParts);
+                        }
+                        else if (this.isMultipleMode) {
                             this.setActiveParts(referenceParts, isActive);
                         }
                         else {
@@ -1717,7 +1966,7 @@ export class Datetime {
         })));
     }
     renderCalendar(theme) {
-        return (h("div", { class: "datetime-calendar", key: "datetime-calendar" }, this.renderCalendarHeader(theme), this.renderCalendarBody()));
+        return (h("div", { class: "datetime-calendar", key: "datetime-calendar" }, this.renderCalendarHeader(theme), this.renderCalendarBody(), this.isRangeMode && (h("div", { class: "datetime-range-announcement", "aria-live": "polite", role: "status" }, this.getHeaderSelectedDateText()))));
     }
     renderTimeLabel() {
         const hasSlottedTimeLabel = this.el.querySelector('[slot="time-label"]') !== null;
@@ -1770,10 +2019,23 @@ export class Datetime {
         ];
     }
     getHeaderSelectedDateText() {
-        const { activeParts, formatOptions, multiple, titleSelectedDatesFormatter } = this;
+        const { activeParts, formatOptions, titleSelectedDatesFormatter } = this;
         const isArray = Array.isArray(activeParts);
+        const dateFormatOptions = formatOptions?.date ?? { weekday: 'short', month: 'short', day: 'numeric' };
         let headerText;
-        if (multiple && isArray && activeParts.length !== 1) {
+        if (this.isRangeMode) {
+            headerText = this.getRangeHeaderText(formatOptions?.date ?? { month: 'short', day: 'numeric' });
+            if (titleSelectedDatesFormatter !== undefined) {
+                try {
+                    const rangeValues = this.getRangeValueArray();
+                    headerText = titleSelectedDatesFormatter(rangeValues);
+                }
+                catch (e) {
+                    printIonError('[ion-datetime] - Exception in provided `titleSelectedDatesFormatter`:', e);
+                }
+            }
+        }
+        else if (this.isMultipleMode && isArray && activeParts.length !== 1) {
             headerText = `${activeParts.length} days`; // default/fallback for multiple selection
             if (titleSelectedDatesFormatter !== undefined) {
                 try {
@@ -1786,10 +2048,37 @@ export class Datetime {
         }
         else {
             // for exactly 1 day selected (multiple set or not), show a formatted version of that
-            headerText = getLocalizedDateTime(this.locale, this.getActivePartsWithFallback(), formatOptions?.date ?? { weekday: 'short', month: 'short', day: 'numeric' });
+            headerText = getLocalizedDateTime(this.locale, this.getActivePartsWithFallback(), dateFormatOptions);
         }
         return headerText;
     }
+    /**
+     * Returns the formatted range header text.
+     * Shows "Start date - End date" with placeholders from startDateLabel/endDateLabel.
+     */
+    getRangeHeaderText(dateFormatOptions) {
+        const range = this.rangeParts;
+        if (!range) {
+            return `${this.startDateLabel} - ${this.endDateLabel}`;
+        }
+        const startText = getLocalizedDateTime(this.locale, range.start, dateFormatOptions);
+        const endText = range.end ? getLocalizedDateTime(this.locale, range.end, dateFormatOptions) : this.endDateLabel;
+        return `${startText} - ${endText}`;
+    }
+    /**
+     * Returns the current range value as an ISO string array for
+     * titleSelectedDatesFormatter and ionChange.
+     */
+    getRangeValueArray() {
+        const range = this.rangeParts;
+        if (!range) {
+            return [];
+        }
+        if (!range.end) {
+            return [convertDataToISO(range.start)];
+        }
+        return [convertDataToISO(range.start), convertDataToISO(range.end)];
+    }
     renderHeader(showExpandedHeader = true) {
         const hasSlottedTitle = this.el.querySelector('[slot="title"]') !== null;
         if (!hasSlottedTitle && !this.showDefaultTitle) {
@@ -1913,7 +2202,7 @@ export class Datetime {
         const hasDatePresentation = presentation === 'date' || presentation === 'date-time' || presentation === 'time-date';
         const hasWheelVariant = hasDatePresentation && preferWheel;
         renderHiddenInput(true, el, name, formatValue(value), disabled);
-        return (h(Host, { key: '6ee2389238b42b0d10c5f5254a8ba61bfc53c677', "aria-disabled": disabled ? 'true' : null, onFocus: this.onFocus, onBlur: this.onBlur, class: {
+        return (h(Host, { key: '2510c26c29afd1a34d6ee71a9ffa00b4a7dd716e', "aria-disabled": disabled ? 'true' : null, onFocus: this.onFocus, onBlur: this.onBlur, class: {
                 ...createColorClasses(color, {
                     [theme]: true,
                     ['datetime-readonly']: readonly,
@@ -1924,8 +2213,9 @@ export class Datetime {
                     [`datetime-size-${size}`]: true,
                     [`datetime-prefer-wheel`]: hasWheelVariant,
                     [`datetime-grid`]: isGridStyle,
+                    [`datetime-range`]: this.isRangeMode,
                 }),
-            } }, h("div", { key: '531803dfb77fa3d694c90b6fc45e71e304876fa8', class: "intersection-tracker", ref: (el) => (this.intersectionTrackerRef = el) }), this.renderDatetime(theme)));
+            } }, h("div", { key: 'b245de6585c7dc5ccfa6f0f8be8474206380acfe', class: "intersection-tracker", ref: (el) => (this.intersectionTrackerRef = el) }), this.renderDatetime(theme)));
     }
     static get is() { return "ion-datetime"; }
     static get encapsulation() { return "shadow"; }
@@ -2371,7 +2661,7 @@ export class Datetime {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "A callback used to format the header text that shows how many\ndates are selected. Only used if there are 0 or more than 1\nselected (i.e. unused for exactly 1). By default, the header\ntext is set to \"numberOfDates days\".\n\nSee https://ionicframework.com/docs/troubleshooting/runtime#accessing-this\nif you need to access `this` from within the callback."
+                    "text": "A callback used to format the header text that shows how many\ndates are selected. In multiple mode this is only used when\nthere are 0 or more than 1 selected. In range mode it is\nalways called with `[startDate]` or `[startDate, endDate]`.\nBy default, the header text is set to \"numberOfDates days\".\n\nSee https://ionicframework.com/docs/troubleshooting/runtime#accessing-this\nif you need to access `this` from within the callback."
                 },
                 "getter": false,
                 "setter": false
@@ -2387,7 +2677,10 @@ export class Datetime {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `selectionMode=\"multiple\"` instead."
+                        }],
                     "text": "If `true`, multiple dates can be selected at once. Only\napplies to `presentation=\"date\"` and `preferWheel=\"false\"`."
                 },
                 "getter": false,
@@ -2396,6 +2689,65 @@ export class Datetime {
                 "attribute": "multiple",
                 "defaultValue": "false"
             },
+            "selectionMode": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'multiple' | 'range'",
+                    "resolved": "\"multiple\" | \"range\" | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Controls the date selection behavior.\n`'multiple'` enables selecting multiple individual dates.\n`'range'` enables selecting a start and end date range.\nWhen unset, single-date selection is used.\n\nRange selection only works with `presentation=\"date\"` and `preferWheel=\"false\"`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "selection-mode"
+            },
+            "startDateLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "The text shown in the datetime header when the start of the range\nis empty, also used by screen readers to announce the start date.\nOnly applies when `selectionMode=\"range\"`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "start-date-label",
+                "defaultValue": "'Start date'"
+            },
+            "endDateLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "The text shown in the datetime header when the end of the range\nis empty, also used by screen readers to announce the end date.\nOnly applies when `selectionMode=\"range\"`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "end-date-label",
+                "defaultValue": "'End date'"
+            },
             "highlightedDates": {
                 "type": "unknown",
                 "mutable": false,
@@ -2438,7 +2790,7 @@ export class Datetime {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "The value of the datetime as a valid ISO 8601 datetime string.\nThis should be an array of strings only when `multiple=\"true\"`."
+                    "text": "The value of the datetime as a valid ISO 8601 datetime string.\nShould be an array of strings when using `multiple=\"true\"` or\n`selectionMode=\"range\"`. For range mode the array contains\n`[startDate, endDate]`, or `[startDate]` for a partial selection."
                 },
                 "getter": false,
                 "setter": false,
@@ -2754,6 +3106,12 @@ export class Datetime {
                         "Promise": {
                             "location": "global",
                             "id": "global::Promise"
+                        },
+                        "DatetimeParts": {
+                            "location": "import",
+                            "path": "./datetime-interface",
+                            "id": "src/components/datetime/datetime-interface.ts::DatetimeParts",
+                            "referenceLocation": "DatetimeParts"
                         }
                     },
                     "return": "Promise<void>"