feat(datetime): enable range selection

core/api.txt

@@ -694,6 +694,7 @@ ion-datetime,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "se
 ion-datetime,prop,dayValues,number | number[] | string | undefined,undefined,false,false
 ion-datetime,prop,disabled,boolean,false,false,false
 ion-datetime,prop,doneText,string,'Done',false,false
+ion-datetime,prop,endDateLabel,string,'End date',false,false
 ion-datetime,prop,firstDayOfWeek,number,0,false,false
 ion-datetime,prop,formatOptions,undefined | { date: DateTimeFormatOptions; time?: DateTimeFormatOptions | undefined; } | { date?: DateTimeFormatOptions | undefined; time: DateTimeFormatOptions; },undefined,false,false
 ion-datetime,prop,highlightedDates,((dateIsoString: string) => DatetimeHighlightStyle | undefined) | DatetimeHighlight[] | undefined,undefined,false,false
@@ -711,12 +712,14 @@ ion-datetime,prop,name,string,this.inputId,false,false
 ion-datetime,prop,preferWheel,boolean,false,false,false
 ion-datetime,prop,presentation,"date" | "date-time" | "month" | "month-year" | "time" | "time-date" | "year",'date-time',false,false
 ion-datetime,prop,readonly,boolean,false,false,false
+ion-datetime,prop,selectionMode,"multiple" | "range" | undefined,undefined,false,false
 ion-datetime,prop,showAdjacentDays,boolean,false,false,false
 ion-datetime,prop,showClearButton,boolean,false,false,false
 ion-datetime,prop,showDefaultButtons,boolean,false,false,false
 ion-datetime,prop,showDefaultTimeLabel,boolean,true,false,false
 ion-datetime,prop,showDefaultTitle,boolean,false,false,false
 ion-datetime,prop,size,"cover" | "fixed",'fixed',false,false
+ion-datetime,prop,startDateLabel,string,'Start date',false,false
 ion-datetime,prop,theme,"ios" | "md" | "ionic",undefined,false,false
 ion-datetime,prop,titleSelectedDatesFormatter,((selectedDates: string[]) => string) | undefined,undefined,false,false
 ion-datetime,prop,value,null | string | string[] | undefined,undefined,false,false
@@ -735,6 +738,9 @@ ion-datetime,css-prop,--background-rgb,ios
 ion-datetime,css-prop,--background-rgb,md
 ion-datetime,css-prop,--focus-ring-color,ionic
 ion-datetime,css-prop,--focus-ring-width,ionic
+ion-datetime,css-prop,--range-background,ionic
+ion-datetime,css-prop,--range-background,ios
+ion-datetime,css-prop,--range-background,md
 ion-datetime,css-prop,--title-color,ios
 ion-datetime,css-prop,--title-color,md
 ion-datetime,css-prop,--wheel-fade-background-rgb,ios
@@ -756,6 +762,10 @@ ion-datetime,part,month-year-button
 ion-datetime,part,navigation-button
 ion-datetime,part,next-button
 ion-datetime,part,previous-button
+ion-datetime,part,range-end
+ion-datetime,part,range-selection
+ion-datetime,part,range-start
+ion-datetime,part,range-track
 ion-datetime,part,time-button
 ion-datetime,part,time-button active
 ion-datetime,part,wheel

core/src/components.d.ts

@@ -1162,6 +1162,11 @@ export namespace Components {
           * @default 'Done'
          */
         "doneText": string;
+        /**
+          * 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"`.
+          * @default 'End date'
+         */
+        "endDateLabel": string;
         /**
           * The first day of the week to use for `ion-datetime`. The default value is `0` and represents Sunday.
           * @default 0
@@ -1218,6 +1223,7 @@ export namespace Components {
         "monthValues"?: number[] | number | string;
         /**
           * If `true`, multiple dates can be selected at once. Only applies to `presentation="date"` and `preferWheel="false"`.
+          * @deprecated Use `selectionMode="multiple"` instead.
           * @default false
          */
         "multiple": boolean;
@@ -1246,6 +1252,10 @@ export namespace Components {
           * @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.
          */
         "reset": (startDate?: string) => Promise<void>;
+        /**
+          * Controls the date selection behavior. `'multiple'` enables selecting multiple individual dates. `'range'` enables selecting a start and end date range. When unset, single-date selection is used.  Range selection only works with `presentation="date"` and `preferWheel="false"`.
+         */
+        "selectionMode"?: 'multiple' | 'range';
         /**
           * If `true`, the datetime calendar displays a six-week (42-day) layout, including days from the previous and next months to fill the grid. These adjacent days are selectable unless disabled.
           * @default false
@@ -1276,6 +1286,11 @@ export namespace Components {
           * @default 'fixed'
          */
         "size": 'cover' | 'fixed';
+        /**
+          * 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"`.
+          * @default 'Start date'
+         */
+        "startDateLabel": string;
         /**
           * The theme determines the visual appearance of the component.
          */
@@ -7070,6 +7085,11 @@ declare namespace LocalJSX {
           * @default 'Done'
          */
         "doneText"?: string;
+        /**
+          * 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"`.
+          * @default 'End date'
+         */
+        "endDateLabel"?: string;
         /**
           * The first day of the week to use for `ion-datetime`. The default value is `0` and represents Sunday.
           * @default 0
@@ -7122,6 +7142,7 @@ declare namespace LocalJSX {
         "monthValues"?: number[] | number | string;
         /**
           * If `true`, multiple dates can be selected at once. Only applies to `presentation="date"` and `preferWheel="false"`.
+          * @deprecated Use `selectionMode="multiple"` instead.
           * @default false
          */
         "multiple"?: boolean;
@@ -7173,6 +7194,10 @@ declare namespace LocalJSX {
           * @default false
          */
         "readonly"?: boolean;
+        /**
+          * Controls the date selection behavior. `'multiple'` enables selecting multiple individual dates. `'range'` enables selecting a start and end date range. When unset, single-date selection is used.  Range selection only works with `presentation="date"` and `preferWheel="false"`.
+         */
+        "selectionMode"?: 'multiple' | 'range';
         /**
           * If `true`, the datetime calendar displays a six-week (42-day) layout, including days from the previous and next months to fill the grid. These adjacent days are selectable unless disabled.
           * @default false
@@ -7203,6 +7228,11 @@ declare namespace LocalJSX {
           * @default 'fixed'
          */
         "size"?: 'cover' | 'fixed';
+        /**
+          * 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"`.
+          * @default 'Start date'
+         */
+        "startDateLabel"?: string;
         /**
           * The theme determines the visual appearance of the component.
          */
@@ -10721,6 +10751,9 @@ declare namespace LocalJSX {
         "locale": string;
         "firstDayOfWeek": number;
         "multiple": boolean;
+        "selectionMode": 'multiple' | 'range';
+        "startDateLabel": string;
+        "endDateLabel": string;
         "value": string | string[] | null;
         "showDefaultTitle": boolean;
         "showDefaultButtons": boolean;

core/src/components/datetime-button/datetime-button.tsx

@@ -7,6 +7,7 @@ import { createColorClasses } from '@utils/theme';
 import { getIonTheme } from '../../global/ionic-global';
 import type { Color } from '../../interface';
 import type { DatetimePresentation } from '../datetime/datetime-interface';
+import { isAfter } from '../datetime/utils/comparison';
 import { getLocalizedDateTime, getLocalizedTime } from '../datetime/utils/format';
 import { getHourCycle } from '../datetime/utils/helpers';
 import { parseDate } from '../datetime/utils/parse';
@@ -197,7 +198,16 @@ export class DatetimeButton implements ComponentInterface {
       return;
     }
 
-    const { value, locale, formatOptions, hourCycle, preferWheel, multiple, titleSelectedDatesFormatter } = datetimeEl;
+    const {
+      value,
+      locale,
+      formatOptions,
+      hourCycle,
+      preferWheel,
+      multiple,
+      selectionMode,
+      titleSelectedDatesFormatter,
+    } = datetimeEl;
 
     const parsedValues = this.getParsedDateValues(value);
 
@@ -213,6 +223,9 @@ export class DatetimeButton implements ComponentInterface {
       return;
     }
 
+    const isRangeMode = selectionMode === 'range';
+    const isMultipleMode = selectionMode === 'multiple' || (selectionMode === undefined && multiple);
+
     /**
      * If developers incorrectly use multiple="true"
      * with non "date" datetimes, then just select
@@ -222,17 +235,14 @@ export class DatetimeButton implements ComponentInterface {
      */
     const firstParsedDatetime = parsedDatetimes[0];
     const computedHourCycle = getHourCycle(locale, hourCycle);
+    const dateFormatOptions = formatOptions?.date ?? { month: 'short', day: 'numeric', year: 'numeric' };
 
     this.dateText = this.timeText = undefined;
 
     switch (datetimePresentation) {
       case 'date-time':
       case 'time-date':
-        const dateText = getLocalizedDateTime(
-          locale,
-          firstParsedDatetime,
-          formatOptions?.date ?? { month: 'short', day: 'numeric', year: 'numeric' }
-        );
+        const dateText = getLocalizedDateTime(locale, firstParsedDatetime, dateFormatOptions);
         const timeText = getLocalizedTime(locale, firstParsedDatetime, computedHourCycle, formatOptions?.time);
         if (preferWheel) {
           this.dateText = `${dateText} ${timeText}`;
@@ -242,7 +252,29 @@ export class DatetimeButton implements ComponentInterface {
         }
         break;
       case 'date':
-        if (multiple && parsedValues.length !== 1) {
+        if (isRangeMode && parsedValues.length >= 2) {
+          /**
+           * Use the first and last entries in date order, matching
+           * how ion-datetime reads a range value.
+           */
+          let startIndex = 0;
+          let endIndex = parsedValues.length - 1;
+          if (isAfter(parsedDatetimes[startIndex], parsedDatetimes[endIndex])) {
+            [startIndex, endIndex] = [endIndex, startIndex];
+          }
+          const rangeValues = [parsedValues[startIndex], parsedValues[endIndex]];
+          const startDate = getLocalizedDateTime(locale, parsedDatetimes[startIndex], dateFormatOptions);
+          const endDate = getLocalizedDateTime(locale, parsedDatetimes[endIndex], dateFormatOptions);
+          let rangeText = `${startDate} - ${endDate}`;
+          if (titleSelectedDatesFormatter !== undefined) {
+            try {
+              rangeText = titleSelectedDatesFormatter(rangeValues);
+            } catch (e) {
+              printIonError('[ion-datetime-button] - Exception in provided `titleSelectedDatesFormatter`:', e);
+            }
+          }
+          this.dateText = rangeText;
+        } else if (isMultipleMode && parsedValues.length !== 1) {
           let headerText = `${parsedValues.length} days`; // default/fallback for multiple selection
           if (titleSelectedDatesFormatter !== undefined) {
             try {
@@ -253,11 +285,7 @@ export class DatetimeButton implements ComponentInterface {
           }
           this.dateText = headerText;
         } else {
-          this.dateText = getLocalizedDateTime(
-            locale,
-            firstParsedDatetime,
-            formatOptions?.date ?? { month: 'short', day: 'numeric', year: 'numeric' }
-          );
+          this.dateText = getLocalizedDateTime(locale, firstParsedDatetime, dateFormatOptions);
         }
         break;
       case 'time':

core/src/components/datetime-button/test/basic/datetime-button.e2e.ts

@@ -229,6 +229,26 @@ configs({ modes: ['md'], directions: ['ltr'] }).forEach(({ title, config }) => {
     });
   });
 
+  test.describe(title('datetime-button: range mode'), () => {
+    test('should normalize a reversed range value to chronological order', async ({ page }) => {
+      await page.setContent(
+        `
+        <ion-datetime-button locale="en-US" datetime="datetime"></ion-datetime-button>
+        <ion-datetime id="datetime" presentation="date" selection-mode="range"></ion-datetime>
+        <script>
+          const datetime = document.querySelector('ion-datetime');
+          datetime.value = ['2023-10-31', '2023-10-23'];
+        </script>
+      `,
+        config
+      );
+      await page.locator('.datetime-ready').waitFor();
+
+      const dateButton = page.locator('#date-button');
+      await expect(dateButton).toContainText('Oct 23, 2023 - Oct 31, 2023');
+    });
+  });
+
   test.describe(title('datetime-button: wheel'), () => {
     test('should only show a single date button when presentation="date-time" and prefer-wheel="true"', async ({
       page,

core/src/components/datetime/datetime-interface.ts

@@ -36,6 +36,11 @@ export type DatetimeHighlight = { date: string } & DatetimeHighlightStyle;
 
 export type DatetimeHighlightCallback = (dateIsoString: string) => DatetimeHighlightStyle | undefined;
 
+export interface DatetimeRangeParts {
+  start: DatetimeParts;
+  end?: DatetimeParts;
+}
+
 export type DatetimeHourCycle = 'h11' | 'h12' | 'h23' | 'h24';
 
 /**

core/src/components/datetime/datetime.common.scss

@@ -273,6 +273,8 @@
 :host .calendar-day-wrapper {
   display: flex;
 
+  position: relative;
+
   align-items: center;
   justify-content: center;
 
@@ -285,6 +287,105 @@
   min-height: 0;
 
   overflow: visible;
+
+  /**
+   * Create a stacking context so the range track
+   * (::before with z-index: -1) stays behind the
+   * day button but above the host background.
+   */
+  z-index: 0;
+}
+
+// Range Selection Track
+// -----------------------------------
+
+/**
+ * Each day in the range draws its own piece of the track with a
+ * ::before. In-range days fill the cell, while the start and end
+ * caps cover the half between the pill center and the next day.
+ *
+ * Grid columns are `1fr`, so cell edges land on fractional pixels
+ * and a cell's track can fall a hairline short of its neighbor's.
+ * Each day therefore extends 1px toward the next day in the range,
+ * which the next day paints over except inside such a gap.
+ *
+ * @prop --range-background: The background color of the range selection track.
+ */
+:host .calendar-day-wrapper-in-range::before,
+:host .calendar-day-wrapper-range-start::before,
+:host .calendar-day-wrapper-range-end::before {
+  position: absolute;
+
+  top: 50%;
+
+  inset-inline-start: 0;
+  inset-inline-end: 0;
+
+  height: var(--range-track-height);
+
+  transform: translateY(-50%);
+
+  /**
+   * `--range-background` is translucent by default, so it is layered
+   * over the datetime background to paint an opaque track. Where two
+   * days overlap, the color stays the same instead of doubling up
+   * into a darker line.
+   */
+  background: linear-gradient(var(--range-background), var(--range-background)),
+    linear-gradient(var(--background), var(--background));
+
+  content: "";
+
+  z-index: -1;
+}
+
+:host .calendar-day-wrapper-range-start::before {
+  inset-inline-start: 50%;
+}
+
+:host .calendar-day-wrapper-range-end::before {
+  inset-inline-end: 50%;
+}
+
+:host .calendar-day-wrapper-range-start:not(:nth-child(7n)):has(+ .calendar-day-wrapper-range-end)::before {
+  inset-inline-end: -1px;
+}
+
+/**
+ * A range that continues onto the next week runs the track
+ * through the grid padding to the edge of the calendar.
+ */
+:host .calendar-day-wrapper-in-range:nth-child(7n)::before,
+:host .calendar-day-wrapper-range-start:nth-child(7n)::before {
+  inset-inline-end: calc(var(--range-track-edge-overflow, 0px) * -1);
+}
+
+:host .calendar-day-wrapper-in-range:nth-child(7n + 1)::before,
+:host .calendar-day-wrapper-range-end:nth-child(7n + 1)::before {
+  inset-inline-start: calc(var(--range-track-edge-overflow, 0px) * -1);
+}
+
+/**
+ * When a single day is both the start and end of the range,
+ * do not show a track since there is nothing to connect.
+ */
+:host .calendar-day-wrapper-range-start.calendar-day-wrapper-range-end::before {
+  display: none;
+}
+
+/**
+ * When the component is disabled, fade the whole grid once instead of
+ * fading each day. Fading a day makes it its own compositing group, so
+ * the 1px that each day extends toward the next would be painted twice
+ * and read as a darker seam. The day buttons drop their own disabled
+ * opacity so the grid is the only thing applying it.
+ */
+:host(.datetime-disabled.datetime-range) .calendar-month-grid {
+  opacity: 0.4;
+}
+
+:host(.datetime-disabled.datetime-range) .calendar-month-grid .calendar-day[disabled] {
+  opacity: 1;
 }
 
 /**