@ionic/core 9.0.10 → 9.0.11-dev.11793666452.109ac2a5

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

@@ -10,7 +10,7 @@ import { isRTL } from "../../utils/rtl/index";
 import { createColorClasses } from "../../utils/theme";
 import { caretDownSharp, caretUpSharp, chevronBack, chevronDown, chevronForward } from "ionicons/icons";
 import { config } from "../../global/config";
-import { getIonMode } from "../../global/ionic-global";
+import { getIonMode, getIonTheme } from "../../global/ionic-global";
 import { isSameDay, warnIfValueOutOfBounds, isBefore, isAfter } from "./utils/comparison";
 import { generateMonths, getDaysOfMonth, getDaysOfWeek, getToday, getMonthColumnData, getDayColumnData, getYearColumnData, getTimeColumnsData, getCombinedDateColumnData, } from "./utils/data";
 import { formatValue, getLocalizedDateTime, getLocalizedTime, getMonthAndYear } from "./utils/format";
@@ -20,7 +20,8 @@ import { clampDate, convertToArrayOfNumbers, getPartsFromCalendarDay, parseAmPm,
 import { getCalendarDayState, getHighlightStyles, isDayDisabled, isMonthDisabled, isNextMonthDisabled, isPrevMonthDisabled, } from "./utils/state";
 import { checkForPresentationFormatMismatch, warnIfTimeZoneProvided } from "./utils/validate";
 /**
- * @virtualProp {"ios" | "md"} mode - The mode determines which platform styles to use.
+ * @virtualProp {"ios" | "md"} mode - The mode determines the platform behaviors of the component.
+ * @virtualProp {"ios" | "md" | "ionic"} theme - The theme determines the visual appearance of the component.
  *
  * @slot title - The title of the datetime.
  * @slot buttons - The buttons in the datetime.
@@ -49,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.
@@ -129,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
@@ -183,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
@@ -193,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);
@@ -219,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) => {
@@ -233,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
@@ -242,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,
@@ -255,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));
@@ -275,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) {
@@ -686,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 =
+                        endParts && endParts.month === workingParts.month && endParts.year === workingParts.year
+                            ? endParts
+                            : startParts;
+                }
+                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
@@ -847,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);
     }
@@ -882,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.
          */
@@ -917,6 +1080,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);
     }
     /**
@@ -1152,8 +1331,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);
             }
@@ -1161,6 +1343,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);
@@ -1207,6 +1400,7 @@ export class Datetime {
      * are rendered independently of presentation.
      */
     renderFooter() {
+        const theme = getIonTheme(this);
         const { disabled, readonly, showDefaultButtons, showClearButton } = this;
         /**
          * The cancel, clear, and confirm buttons
@@ -1214,6 +1408,13 @@ 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) {
             return;
@@ -1232,7 +1433,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" }, h("ion-buttons", null, 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", 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
@@ -1421,8 +1622,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,
@@ -1443,8 +1644,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,
@@ -1546,10 +1747,8 @@ export class Datetime {
     /**
      * Grid Render Methods
      */
-    renderCalendarHeader(mode) {
-        const { disabled } = this;
-        const expandedIcon = mode === 'ios' ? chevronDown : caretUpSharp;
-        const collapsedIcon = mode === 'ios' ? chevronForward : caretDownSharp;
+    renderCalendarHeader(theme) {
+        const { disabled, datetimeNextIcon, datetimePreviousIcon, datetimeCollapsedIcon, datetimeExpandedIcon } = this;
         const prevMonthDisabled = disabled || isPrevMonthDisabled(this.workingParts, this.minParts, this.maxParts);
         const nextMonthDisabled = disabled || isNextMonthDisabled(this.workingParts, this.maxParts);
         const hostDir = isRTL(this.el) ? 'rtl' : 'ltr';
@@ -1557,7 +1756,7 @@ export class Datetime {
                 'calendar-month-year-toggle': true,
                 'ion-activatable': true,
                 'ion-focusable': true,
-            }, part: "month-year-button", disabled: disabled, "aria-label": this.showMonthAndYear ? 'Hide year picker' : 'Show year picker', onClick: () => this.toggleMonthAndYearView() }, h("span", { id: "toggle-wrapper" }, getMonthAndYear(this.locale, this.workingParts), h("ion-icon", { dir: hostDir, "aria-hidden": "true", icon: this.showMonthAndYear ? expandedIcon : collapsedIcon, lazy: false, flipRtl: true })), mode === 'md' && h("ion-ripple-effect", null))), h("div", { class: "calendar-next-prev" }, h("ion-buttons", null, h("ion-button", { "aria-label": "Previous month", disabled: prevMonthDisabled, onClick: () => this.prevMonth(), part: "navigation-button previous-button" }, h("ion-icon", { dir: hostDir, "aria-hidden": "true", slot: "icon-only", icon: chevronBack, lazy: false, flipRtl: true })), h("ion-button", { "aria-label": "Next month", disabled: nextMonthDisabled, onClick: () => this.nextMonth(), part: "navigation-button next-button" }, h("ion-icon", { dir: hostDir, "aria-hidden": "true", slot: "icon-only", icon: chevronForward, lazy: false, flipRtl: true }))))), h("div", { class: "calendar-days-of-week", "aria-hidden": "true", part: "calendar-days-of-week" }, getDaysOfWeek(this.locale, mode, this.firstDayOfWeek % 7).map((d) => {
+            }, part: "month-year-button", disabled: disabled, "aria-label": this.showMonthAndYear ? 'Hide year picker' : 'Show year picker', onClick: () => this.toggleMonthAndYearView() }, h("span", { id: "toggle-wrapper" }, getMonthAndYear(this.locale, this.workingParts), theme !== 'ionic' && (h("ion-icon", { dir: hostDir, "aria-hidden": "true", icon: this.showMonthAndYear ? datetimeExpandedIcon : datetimeCollapsedIcon, lazy: false, flipRtl: true }))), theme === 'md' && h("ion-ripple-effect", null))), h("div", { class: "calendar-next-prev" }, h("ion-button", { "aria-label": "Previous month", disabled: prevMonthDisabled, onClick: () => this.prevMonth(), part: "navigation-button previous-button" }, h("ion-icon", { dir: hostDir, "aria-hidden": "true", slot: "icon-only", icon: datetimePreviousIcon, lazy: false, flipRtl: true })), h("ion-button", { "aria-label": "Next month", disabled: nextMonthDisabled, onClick: () => this.nextMonth(), part: "navigation-button next-button" }, h("ion-icon", { dir: hostDir, "aria-hidden": "true", slot: "icon-only", icon: datetimeNextIcon, lazy: false, flipRtl: true })))), h("div", { class: "calendar-days-of-week", "aria-hidden": "true", part: "calendar-days-of-week" }, getDaysOfWeek(this.locale, theme, this.firstDayOfWeek % 7).map((d) => {
             return h("div", { class: "day-of-week" }, d);
         }))));
     }
@@ -1590,7 +1789,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) {
@@ -1619,7 +1818,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) {
@@ -1642,24 +1841,60 @@ 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' : ''}`;
             }
-            return (h("div", { class: "calendar-day-wrapper" }, h("button", {
+            /**
+             * 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}`;
+                }
+                if (isInRange) {
+                    rangeAriaLabel += ', in range';
+                }
+            }
+            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
@@ -1675,28 +1910,40 @@ 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 };
+                        if (!this.isRangeMode) {
+                            this.activeParts = { ...activePart, ...referenceParts };
+                        }
                         this.animateToDate(referenceParts);
-                        this.confirm();
+                        if (this.isRangeMode) {
+                            this.setActiveParts(referenceParts);
+                        }
+                        else {
+                            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 {
@@ -1715,8 +1962,18 @@ export class Datetime {
             return this.renderMonth(month, year);
         })));
     }
-    renderCalendar(mode) {
-        return (h("div", { class: "datetime-calendar", key: "datetime-calendar" }, this.renderCalendarHeader(mode), this.renderCalendarBody()));
+    renderCalendar(theme) {
+        return (h("div", { class: "datetime-calendar", key: "datetime-calendar" }, this.renderCalendarHeader(theme), this.renderCalendarBody(), this.isRangeMode && this.rangeParts && !this.rangeParts.end && (h("div", { "aria-live": "polite", role: "status", style: {
+                position: 'absolute',
+                width: '1px',
+                height: '1px',
+                padding: '0',
+                margin: '-1px',
+                overflow: 'hidden',
+                clip: 'rect(0, 0, 0, 0)',
+                whiteSpace: 'nowrap',
+                border: '0',
+            } }, `${this.startDateLabel} selected, select ${this.endDateLabel.toLowerCase()}`))));
     }
     renderTimeLabel() {
         const hasSlottedTimeLabel = this.el.querySelector('[slot="time-label"]') !== null;
@@ -1769,10 +2026,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 {
@@ -1785,10 +2055,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) {
@@ -1823,7 +2120,7 @@ export class Datetime {
      * Render entry point
      * All presentation types are rendered from here.
      */
-    renderDatetime(mode) {
+    renderDatetime(theme) {
         const { presentation, preferWheel } = this;
         /**
          * Certain presentation types have separate grid and wheel displays.
@@ -1837,7 +2134,7 @@ export class Datetime {
             case 'date-time':
                 return [
                     this.renderHeader(),
-                    this.renderCalendar(mode),
+                    this.renderCalendar(theme),
                     this.renderCalendarViewMonthYearPicker(),
                     this.renderTime(),
                     this.renderFooter(),
@@ -1846,7 +2143,7 @@ export class Datetime {
                 return [
                     this.renderHeader(),
                     this.renderTime(),
-                    this.renderCalendar(mode),
+                    this.renderCalendar(theme),
                     this.renderCalendarViewMonthYearPicker(),
                     this.renderFooter(),
                 ];
@@ -1859,24 +2156,62 @@ export class Datetime {
             default:
                 return [
                     this.renderHeader(),
-                    this.renderCalendar(mode),
+                    this.renderCalendar(theme),
                     this.renderCalendarViewMonthYearPicker(),
                     this.renderFooter(),
                 ];
         }
     }
+    /**
+     * Get the icon to use for the next icon.
+     * Use the icon set in the config.
+     * If no icon is set in the config, use the default icon.
+     */
+    get datetimeNextIcon() {
+        return config.get('datetimeNextIcon', chevronForward);
+    }
+    /**
+     * Get the icon to use for the previous icon.
+     * Use the icon set in the config.
+     * If no icon is set in the config, use the default icon.
+     */
+    get datetimePreviousIcon() {
+        return config.get('datetimePreviousIcon', chevronBack);
+    }
+    /**
+     * Get the icon to use for the show month and year icon.
+     * Use the icon set in the config.
+     * If no icon is set in the config, use the default icon.
+     */
+    get datetimeCollapsedIcon() {
+        // Determine the theme and map to the default icon
+        const theme = getIonTheme(this);
+        const defaultIcon = theme === 'ios' ? chevronForward : caretDownSharp;
+        return config.get('datetimeCollapsedIcon', defaultIcon);
+    }
+    /**
+     * Get the icon to use for the hide month and year icon.
+     * Use the icon set in the config.
+     * If no icon is set in the config, use the default icon.
+     */
+    get datetimeExpandedIcon() {
+        // Determine the theme and map to the default icon
+        const theme = getIonTheme(this);
+        const defaultIcon = theme === 'ios' ? chevronDown : caretUpSharp;
+        return config.get('datetimeExpandedIcon', defaultIcon);
+    }
     render() {
         const { name, value, disabled, el, color, readonly, showMonthAndYear, preferWheel, presentation, size, isGridStyle, } = this;
-        const mode = getIonMode(this);
+        const theme = getIonTheme(this);
         const isMonthAndYearPresentation = presentation === 'year' || presentation === 'month' || presentation === 'month-year';
         const shouldShowMonthAndYear = showMonthAndYear || isMonthAndYearPresentation;
         const monthYearPickerOpen = showMonthAndYear && !isMonthAndYearPresentation;
         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: '465c9c22bccabc4a82ea4054c536c6086b85ddf9', "aria-disabled": disabled ? 'true' : null, onFocus: this.onFocus, onBlur: this.onBlur, class: {
+        return (h(Host, { key: 'bbda23db005004f03b23e39d1e8c622e588ba7c2', "aria-disabled": disabled ? 'true' : null, onFocus: this.onFocus, onBlur: this.onBlur, class: {
                 ...createColorClasses(color, {
-                    [mode]: true,
+                    [theme]: true,
                     ['datetime-readonly']: readonly,
                     ['datetime-disabled']: disabled,
                     'show-month-and-year': shouldShowMonthAndYear,
@@ -1885,21 +2220,24 @@ export class Datetime {
                     [`datetime-size-${size}`]: true,
                     [`datetime-prefer-wheel`]: hasWheelVariant,
                     [`datetime-grid`]: isGridStyle,
+                    [`datetime-range`]: this.isRangeMode,
                 }),
-            } }, h("div", { key: '9732b003440a0ca23520bc8a09e73125d88fd565', class: "intersection-tracker", ref: (el) => (this.intersectionTrackerRef = el) }), this.renderDatetime(mode)));
+            } }, h("div", { key: '788e47cd7e8b022a450c7938d713a7d50d43e4f7', class: "intersection-tracker", ref: (el) => (this.intersectionTrackerRef = el) }), this.renderDatetime(theme)));
     }
     static get is() { return "ion-datetime"; }
     static get encapsulation() { return "shadow"; }
     static get originalStyleUrls() {
         return {
             "ios": ["datetime.ios.scss"],
-            "md": ["datetime.md.scss"]
+            "md": ["datetime.md.scss"],
+            "ionic": ["datetime.ionic.scss"]
         };
     }
     static get styleUrls() {
         return {
             "ios": ["datetime.ios.css"],
-            "md": ["datetime.md.css"]
+            "md": ["datetime.md.css"],
+            "ionic": ["datetime.ionic.css"]
         };
     }
     static get properties() {
@@ -2346,7 +2684,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,
@@ -2355,6 +2696,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,
@@ -2713,6 +3113,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>"