@ionic/core 8.8.20-dev.11791573097.1f843ab0 → 8.8.20-dev.11792194859.16be5d7f

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

@@ -52,6 +52,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 calendar day wrapper element whose ::before pseudo-element draws the range highlight track.
+ *
  * @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.
@@ -141,8 +146,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
@@ -195,8 +214,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
@@ -205,7 +224,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);
@@ -232,6 +257,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) => {
@@ -243,6 +271,33 @@ export class Datetime {
         this.setWorkingParts = (parts) => {
             this.workingParts = Object.assign({}, 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, isDateEnabled } = this;
+            let cursor = getNextDay(start);
+            while (isBefore(cursor, end) || isSameDay(cursor, end)) {
+                if (isSameDay(cursor, end))
+                    break;
+                if (isDayDisabled(cursor, minParts, maxParts, parsedDayValues)) {
+                    return true;
+                }
+                if (isDateEnabled) {
+                    try {
+                        if (!isDateEnabled(convertDataToISO(cursor))) {
+                            return true;
+                        }
+                    }
+                    catch (_a) {
+                        // 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
@@ -251,7 +306,7 @@ export class Datetime {
             if (this.readonly) {
                 return;
             }
-            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,
@@ -264,7 +319,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));
@@ -282,6 +340,70 @@ 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) {
+                // No range yet — start a new one
+                this.activeParts = { start: parts };
+                return;
+            }
+            const { start, end } = current;
+            if (end) {
+                // A complete range exists
+                if (isBefore(parts, start)) {
+                    // Before range → new start
+                    this.activeParts = { start: parts };
+                }
+                else if (isSameDay(parts, start) || (isAfter(parts, start) && isBefore(parts, end))) {
+                    // Within range (including start) → set new end
+                    if (this.rangeContainsDisabledDate(start, parts)) {
+                        this.activeParts = { start: parts };
+                    }
+                    else {
+                        this.activeParts = { start, end: parts };
+                    }
+                }
+                else {
+                    // After or equal to end → new end
+                    if (this.rangeContainsDisabledDate(start, parts)) {
+                        this.activeParts = { start: parts };
+                    }
+                    else {
+                        this.activeParts = { start, end: parts };
+                    }
+                }
+            }
+            else {
+                // Only start date, no end yet
+                if (isSameDay(parts, start)) {
+                    // Same day → single-day range
+                    this.activeParts = { start, end: parts };
+                }
+                else if (isBefore(parts, start)) {
+                    // Before start → new start
+                    this.activeParts = { start: parts };
+                }
+                else {
+                    // After start → set end if no disabled dates in between
+                    if (this.rangeContainsDisabledDate(start, parts)) {
+                        this.activeParts = { start: parts };
+                    }
+                    else {
+                        this.activeParts = { start, end: parts };
+                    }
+                }
+            }
+        };
         this.initializeKeyboardListeners = () => {
             const calendarBodyRef = this.calendarBodyRef;
             if (!calendarBodyRef) {
@@ -679,6 +801,43 @@ export class Datetime {
             if (hasValue) {
                 warnIfValueOutOfBounds(valueToProcess, minParts, maxParts);
             }
+            /**
+             * Range mode: convert the value array into DatetimeRangeParts.
+             */
+            if (this.isRangeMode) {
+                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 };
+                    // Navigate calendar to the start date
+                    const targetValue = clampDate(startParts, 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' });
+                    }
+                }
+                else {
+                    this.activeParts = [];
+                }
+                return;
+            }
             /**
              * If there are multiple values, clamp to the last one.
              * This is because the last value is the one that the user
@@ -839,6 +998,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);
     }
@@ -874,6 +1054,18 @@ 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) {
+                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.
          */
@@ -908,6 +1100,22 @@ 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 = [];
+            if (startDate) {
+                const parsed = parseDate(startDate);
+                if (parsed) {
+                    const target = Array.isArray(parsed) ? parsed[0] : parsed;
+                    this.setWorkingParts(target);
+                }
+            }
+            return;
+        }
         this.processValue(startDate);
     }
     /**
@@ -919,6 +1127,14 @@ export class Datetime {
      * @param closeOverlay If `true`, closes the parent overlay. Defaults to `false`.
      */
     async cancel(closeOverlay = false) {
+        /**
+         * In range mode, clear the visible selection (including partial ranges)
+         * so the component returns to an empty state. The value property is
+         * left untouched, matching single/multiple mode behavior.
+         */
+        if (this.isRangeMode) {
+            this.activeParts = [];
+        }
         this.ionCancel.emit();
         if (closeOverlay) {
             this.closeParentOverlay(CANCEL_ROLE);
@@ -1099,8 +1315,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);
             }
@@ -1108,6 +1327,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);
@@ -1162,6 +1392,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) {
@@ -1181,7 +1417,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
@@ -1481,7 +1717,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) {
@@ -1510,7 +1746,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) {
@@ -1533,24 +1769,50 @@ 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' : ''}`;
             }
-            return (h("div", { class: "calendar-day-wrapper" }, h("button", {
+            /**
+             * Build the wrapper's shadow part attribute for range track styling.
+             */
+            const wrapperParts = isPartOfRange && !isCalendarPadding && !isAdjacentDay ? 'range-track' : undefined;
+            /**
+             * Build the aria-label for range mode accessibility.
+             */
+            let rangeAriaLabel = ariaLabel;
+            if (this.isRangeMode && ariaLabel) {
+                if (isRangeStart) {
+                    rangeAriaLabel = `${ariaLabel}, ${this.startDateLabel}`;
+                }
+                if (isRangeEnd) {
+                    rangeAriaLabel = `${ariaLabel}, ${this.endDateLabel}`;
+                }
+            }
+            return (h("div", { class: {
+                    'calendar-day-wrapper': true,
+                    'calendar-day-wrapper-range-start': isRangeStart,
+                    '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
@@ -1566,25 +1828,37 @@ 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 = Object.assign(Object.assign({}, activePart), referenceParts);
+                        if (!this.isRangeMode) {
+                            this.activeParts = Object.assign(Object.assign({}, activePart), referenceParts);
+                        }
                         this.animateToDate(referenceParts);
-                        this.confirm();
+                        if (this.isRangeMode) {
+                            this.setActiveParts(referenceParts);
+                        }
+                        else {
+                            this.confirm();
+                        }
                     }
                     else {
                         this.setWorkingParts(Object.assign(Object.assign({}, 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 {
@@ -1655,10 +1929,23 @@ export class Datetime {
     }
     getHeaderSelectedDateText() {
         var _a;
-        const { activeParts, formatOptions, multiple, titleSelectedDatesFormatter } = this;
+        const { activeParts, formatOptions, titleSelectedDatesFormatter } = this;
         const isArray = Array.isArray(activeParts);
+        const dateFormatOptions = (_a = formatOptions === null || formatOptions === void 0 ? void 0 : formatOptions.date) !== null && _a !== void 0 ? _a : { weekday: 'short', month: 'short', day: 'numeric' };
         let headerText;
-        if (multiple && isArray && activeParts.length !== 1) {
+        if (this.isRangeMode) {
+            headerText = this.getRangeHeaderText(dateFormatOptions);
+            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 {
@@ -1671,10 +1958,35 @@ 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(), (_a = formatOptions === null || formatOptions === void 0 ? void 0 : formatOptions.date) !== null && _a !== void 0 ? _a : { 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) {
@@ -1832,7 +2144,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: '04fb1740b1d722d20cdbb32b19d9a3b7d3334db0', "aria-disabled": disabled ? 'true' : null, onFocus: this.onFocus, onBlur: this.onBlur, class: Object.assign({}, createColorClasses(color, {
+        return (h(Host, { key: '8ec46f2a5bc855c3d6210f72305b66655ad59b93', "aria-disabled": disabled ? 'true' : null, onFocus: this.onFocus, onBlur: this.onBlur, class: Object.assign({}, createColorClasses(color, {
                 [theme]: true,
                 ['datetime-readonly']: readonly,
                 ['datetime-disabled']: disabled,
@@ -1842,7 +2154,7 @@ export class Datetime {
                 [`datetime-size-${size}`]: true,
                 [`datetime-prefer-wheel`]: hasWheelVariant,
                 [`datetime-grid`]: isGridStyle,
-            })) }, h("div", { key: '0cbb85b4c71e521c81b37a98da0123a1c3a15fac', class: "intersection-tracker", ref: (el) => (this.intersectionTrackerRef = el) }), this.renderDatetime(theme)));
+            })) }, h("div", { key: 'b7bf9b1e681b8d1a5a24a27c758a528c03a203fc', class: "intersection-tracker", ref: (el) => (this.intersectionTrackerRef = el) }), this.renderDatetime(theme)));
     }
     static get is() { return "ion-datetime"; }
     static get encapsulation() { return "shadow"; }
@@ -2305,7 +2617,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,
@@ -2314,6 +2629,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,
@@ -2672,6 +3046,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>"