feat(datetime): add selectionMode="range", monthNavigation="scroll", and monthYearPickerView="grid"

Introduces three new opt-in props to ion-datetime:

selectionMode="range"
- First tap sets the range start; second tap commits the range and
  emits ionChange with a two-element ISO array [start, end]
- Second tap before first auto-swaps if needed so start is always earlier
- Third tap resets and starts a new range
- Deprecates the `multiple` boolean in favour of selectionMode="multiple"
- Range state (isRangeStart, isInRange, isRangeEnd) flows through
  getCalendarDayState() and is exposed as CSS classes on day buttons and
  ::before pseudo-element track on their wrapper cells

monthNavigation="scroll"
- Replaces the horizontal 3-month swipe window with a free-scrolling
  vertical list of ~13 months (+-6 from the working month, clamped to
  min/max)
- Each month card renders its own heading and days-of-week row inline
- A debounced scroll listener updates workingParts and the visually-
  hidden aria-live region as the user scrolls
- Arrow buttons are hidden in this mode (display: none)

monthYearPickerView="grid"
- Replaces the wheel picker overlay with a month name grid (3 col x 4
  row) and a paginated year grid (4 col x 6 row, 24 years per page)
- Year pages are navigated with prev/next arrow buttons; the page resets
  to the one containing the working year each time the picker opens
- Also applied to month/month-year/year presentations which previously
  hardcoded the wheel picker regardless of the prop

Adds unit tests for the new range state logic and E2E test files with
index.html pages for all three features.

Author: OS-susmitabhowmik

core/src/components.d.ts

@@ -15,7 +15,7 @@ import { RouteID, RouterDirection, RouterEventDetail, RouteWrite } from "./compo
 import { BreadcrumbCollapsedClickEventDetail } from "./components/breadcrumb/breadcrumb-interface";
 import { CheckboxChangeEventDetail } from "./components/checkbox/checkbox-interface";
 import { ScrollBaseDetail, ScrollDetail } from "./components/content/content-interface";
-import { DatetimeChangeEventDetail, DatetimeHighlight, DatetimeHighlightCallback, DatetimeHourCycle, DatetimePresentation, FormatOptions, TitleSelectedDatesFormatter } from "./components/datetime/datetime-interface";
+import { DatetimeChangeEventDetail, DatetimeHighlight, DatetimeHighlightCallback, DatetimeHourCycle, DatetimeParts, DatetimePresentation, FormatOptions, TitleSelectedDatesFormatter } from "./components/datetime/datetime-interface";
 import { GalleryColumns, GalleryGap } from "./components/gallery/gallery-interface";
 import { SpinnerTypes } from "./components/spinner/spinner-configs";
 import { InputChangeEventDetail, InputInputEventDetail } from "./components/input/input-interface";
@@ -54,7 +54,7 @@ export { RouteID, RouterDirection, RouterEventDetail, RouteWrite } from "./compo
 export { BreadcrumbCollapsedClickEventDetail } from "./components/breadcrumb/breadcrumb-interface";
 export { CheckboxChangeEventDetail } from "./components/checkbox/checkbox-interface";
 export { ScrollBaseDetail, ScrollDetail } from "./components/content/content-interface";
-export { DatetimeChangeEventDetail, DatetimeHighlight, DatetimeHighlightCallback, DatetimeHourCycle, DatetimePresentation, FormatOptions, TitleSelectedDatesFormatter } from "./components/datetime/datetime-interface";
+export { DatetimeChangeEventDetail, DatetimeHighlight, DatetimeHighlightCallback, DatetimeHourCycle, DatetimeParts, DatetimePresentation, FormatOptions, TitleSelectedDatesFormatter } from "./components/datetime/datetime-interface";
 export { GalleryColumns, GalleryGap } from "./components/gallery/gallery-interface";
 export { SpinnerTypes } from "./components/spinner/spinner-configs";
 export { InputChangeEventDetail, InputInputEventDetail } from "./components/input/input-interface";
@@ -1204,15 +1204,22 @@ export namespace Components {
          */
         "minuteValues"?: number[] | number | string;
         /**
-          * The mode determines the platform behaviors of the component.
+          * Controls the month navigation mode when using a grid-style layout.  - `"arrows"` (default) preserves the existing prev/next button behaviour. - `"scroll"` swaps the horizontal scroll axis to vertical. The   `previous-button` and `next-button` shadow parts remain in the DOM   and keyboard-focusable in both modes.
+          * @default 'arrows'
          */
-        "mode"?: "ios" | "md";
+        "monthNavigation": 'arrows' | 'scroll';
         /**
           * Values used to create the list of selectable months. By default the month values range from `1` to `12`. However, to control exactly which months to display, the `monthValues` input can take a number, an array of numbers, or a string of comma separated numbers. For example, if only summer months should be shown, then this input value would be `monthValues="6,7,8"`. Note that month numbers do *not* have a zero-based index, meaning January's value is `1`, and December's is `12`.
          */
         "monthValues"?: number[] | number | string;
+        /**
+          * Controls the month/year picker overlay style when using a grid-style layout.  - `"wheel"` (default) preserves the existing `ion-picker-column` behaviour. - `"grid"` replaces the wheel columns with a month name grid and a year grid   shown simultaneously inside the existing toggle overlay.
+          * @default 'wheel'
+         */
+        "monthYearPickerView": 'wheel' | 'grid';
         /**
           * 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;
@@ -1241,6 +1248,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 date selection behaviour when using a grid-style layout.  - `"multiple"` enables toggling of individual dates (replaces the deprecated `multiple` boolean). - `"range"` enables start/end date range selection. `value` will emit a two-element ISO 8601   string array `[startDate, endDate]` once both dates are selected.  Only applies to `presentation="date"` and `preferWheel="false"`. Logs a warning if used with any other `presentation` or with `preferWheel="true"`.
+         */
+        "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
@@ -1271,10 +1282,6 @@ export namespace Components {
           * @default 'fixed'
          */
         "size": 'cover' | 'fixed';
-        /**
-          * The theme determines the visual appearance of the component.
-         */
-        "theme"?: "ios" | "md" | "ionic";
         /**
           * A callback used to format the header text that shows how many dates are selected. Only used if there are 0 or more than 1 selected (i.e. unused for exactly 1). By default, the header text is set to "numberOfDates days".  See https://ionicframework.com/docs/troubleshooting/runtime#accessing-this if you need to access `this` from within the callback.
          */
@@ -7258,15 +7265,22 @@ declare namespace LocalJSX {
          */
         "minuteValues"?: number[] | number | string;
         /**
-          * The mode determines the platform behaviors of the component.
+          * Controls the month navigation mode when using a grid-style layout.  - `"arrows"` (default) preserves the existing prev/next button behaviour. - `"scroll"` swaps the horizontal scroll axis to vertical. The   `previous-button` and `next-button` shadow parts remain in the DOM   and keyboard-focusable in both modes.
+          * @default 'arrows'
          */
-        "mode"?: "ios" | "md";
+        "monthNavigation"?: 'arrows' | 'scroll';
         /**
           * Values used to create the list of selectable months. By default the month values range from `1` to `12`. However, to control exactly which months to display, the `monthValues` input can take a number, an array of numbers, or a string of comma separated numbers. For example, if only summer months should be shown, then this input value would be `monthValues="6,7,8"`. Note that month numbers do *not* have a zero-based index, meaning January's value is `1`, and December's is `12`.
          */
         "monthValues"?: number[] | number | string;
+        /**
+          * Controls the month/year picker overlay style when using a grid-style layout.  - `"wheel"` (default) preserves the existing `ion-picker-column` behaviour. - `"grid"` replaces the wheel columns with a month name grid and a year grid   shown simultaneously inside the existing toggle overlay.
+          * @default 'wheel'
+         */
+        "monthYearPickerView"?: 'wheel' | 'grid';
         /**
           * 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;
@@ -7318,6 +7332,10 @@ declare namespace LocalJSX {
           * @default false
          */
         "readonly"?: boolean;
+        /**
+          * Controls date selection behaviour when using a grid-style layout.  - `"multiple"` enables toggling of individual dates (replaces the deprecated `multiple` boolean). - `"range"` enables start/end date range selection. `value` will emit a two-element ISO 8601   string array `[startDate, endDate]` once both dates are selected.  Only applies to `presentation="date"` and `preferWheel="false"`. Logs a warning if used with any other `presentation` or with `preferWheel="true"`.
+         */
+        "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
@@ -7348,10 +7366,6 @@ declare namespace LocalJSX {
           * @default 'fixed'
          */
         "size"?: 'cover' | 'fixed';
-        /**
-          * The theme determines the visual appearance of the component.
-         */
-        "theme"?: "ios" | "md" | "ionic";
         /**
           * A callback used to format the header text that shows how many dates are selected. Only used if there are 0 or more than 1 selected (i.e. unused for exactly 1). By default, the header text is set to "numberOfDates days".  See https://ionicframework.com/docs/troubleshooting/runtime#accessing-this if you need to access `this` from within the callback.
          */
@@ -10967,6 +10981,9 @@ declare namespace LocalJSX {
         "locale": string;
         "firstDayOfWeek": number;
         "multiple": boolean;
+        "selectionMode": 'multiple' | 'range';
+        "monthNavigation": 'arrows' | 'scroll';
+        "monthYearPickerView": 'wheel' | 'grid';
         "value": string | string[] | null;
         "showDefaultTitle": boolean;
         "showDefaultButtons": boolean;

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

@@ -38,6 +38,23 @@ export type DatetimeHighlightCallback = (dateIsoString: string) => DatetimeHighl
 
 export type DatetimeHourCycle = 'h11' | 'h12' | 'h23' | 'h24';
 
+export type DatetimeSelectionMode = 'multiple' | 'range';
+
+export type DatetimeMonthNavigation = 'arrows' | 'scroll';
+
+export type DatetimeMonthYearPickerView = 'wheel' | 'grid';
+
+/**
+ * Represents the active parts when selectionMode="range".
+ * `start` is always set once the user picks a first date.
+ * `end` is set once the user picks the second date (or `start` is set again
+ * when a complete range is reset).
+ */
+export interface DatetimeRangeParts {
+  start: DatetimeParts;
+  end?: DatetimeParts;
+}
+
 /**
  * FormatOptions must include date and/or time; it cannot be an empty object
  */

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

@@ -271,6 +271,13 @@
 }
 
 :host .calendar-day-wrapper {
+  /**
+   * position: relative is required so that the ::before pseudo-element used for
+   * the range-selection highlight track is positioned relative to the wrapper,
+   * not the scroll container.
+   */
+  position: relative;
+
   display: flex;
 
   align-items: center;
@@ -384,3 +391,220 @@
 
   align-items: center;
 }
+
+// Accessibility: visually-hidden aria-live region
+// -----------------------------------
+
+/**
+ * The `.calendar-month-year-announce` element is a visually-hidden live region
+ * that announces the current month/year to screen readers whenever `workingParts`
+ * changes. This is especially important in `monthNavigation="scroll"` mode where
+ * the scroll gesture alone is insufficient for AT users to detect the change.
+ *
+ * The clip/clip-path technique is preferred over display:none or visibility:hidden
+ * because those hide the element from the accessibility tree as well.
+ */
+:host .calendar-month-year-announce {
+  position: absolute;
+
+  width: 1px;
+  height: 1px;
+
+  @include padding(0px);
+  @include margin(0px);
+
+  overflow: hidden;
+
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+
+  white-space: nowrap;
+}
+
+// Feature: monthNavigation="scroll" (vertical month scroll)
+// -----------------------------------
+
+/**
+ * When `monthNavigation="scroll"`, all months in the valid range are rendered
+ * in a single continuous vertical list. There is no virtual window or
+ * scroll-snap — the user scrolls freely through months.
+ *
+ * The shared calendar header (month/year toggle + prev/next arrows) is hidden;
+ * each month card renders its own heading instead.
+ */
+:host(.datetime-month-navigation-scroll) .calendar-header {
+  /**
+   * Keep the element in the DOM for the aria-live region (screen reader
+   * announcements) but remove all visual space.
+   */
+  position: absolute;
+
+  pointer-events: none;
+}
+
+:host(.datetime-month-navigation-scroll) .calendar-body {
+  flex-direction: column;
+
+  overflow-x: hidden;
+  overflow-y: scroll;
+
+  /**
+   * Cap the scroll container so roughly 1.5 months are visible at a time.
+   * When the datetime is inside a modal/popover the parent constrains the
+   * height anyway and this max-height has no effect.
+   */
+  max-height: 460px;
+}
+
+/**
+ * Per-month heading shown at the top of each month card in scroll mode.
+ * Styled to match the image reference: prominent left-aligned text in the
+ * primary colour.
+ */
+:host(.datetime-month-navigation-scroll) .calendar-month-scroll-heading {
+  @include padding(16px, 16px, 4px);
+
+  font-size: 18px;
+  font-weight: 600;
+
+  color: current-color(base);
+}
+
+// Feature: monthYearPickerView="grid"
+// -----------------------------------
+
+/**
+ * Grid-based month/year picker overlay.
+ * Shown inside the existing .datetime-year toggle overlay when
+ * `monthYearPickerView="grid"`. The toggle mechanism and `month-year-button`
+ * shadow part are fully preserved.
+ */
+:host .month-year-grid-container {
+  display: flex;
+
+  flex-direction: column;
+
+  overflow: auto;
+
+  @include padding(8px);
+}
+
+:host .month-year-grid {
+  display: grid;
+
+  /* Month grid: 3 columns × 4 rows */
+  grid-template-columns: repeat(3, 1fr);
+
+  gap: 8px;
+
+  margin-bottom: 16px;
+}
+
+/**
+ * Year section: wraps the prev/next nav row and the year grid.
+ */
+:host .month-year-grid-year-section {
+  display: flex;
+
+  flex-direction: column;
+}
+
+/**
+ * Nav row that holds the prev/next year-page arrow buttons.
+ * Buttons are pushed to the inline-end so they sit at the right (LTR) / left (RTL).
+ */
+:host .month-year-grid-year-nav {
+  display: flex;
+
+  justify-content: flex-end;
+
+  @include margin-horizontal(0px);
+}
+
+/**
+ * Year grid: 4 columns (no scroll — pagination is handled by the nav arrows).
+ */
+:host .month-year-grid-years {
+  /* 4 columns to match the reference design */
+  grid-template-columns: repeat(4, 1fr);
+}
+
+:host .month-year-grid-cell {
+  display: flex;
+
+  align-items: center;
+  justify-content: center;
+
+  @include padding(8px, 4px);
+
+  border: none;
+
+  border-radius: 8px;
+
+  background: none;
+
+  color: currentColor;
+
+  font-family: inherit;
+  font-size: inherit;
+
+  cursor: pointer;
+
+  appearance: none;
+}
+
+:host .month-year-grid-cell[disabled] {
+  opacity: 0.3;
+
+  pointer-events: none;
+}
+
+// Feature: selectionMode="range" — range highlight track
+// -----------------------------------
+
+/**
+ * The range-selection track is rendered as a ::before pseudo-element on the
+ * `.calendar-day-wrapper` rather than on the `.calendar-day` button itself.
+ * This is necessary because the button element has a fixed circular size that
+ * does not span the full grid cell, so a background on the button alone would
+ * produce gaps in the highlight track between adjacent days.
+ *
+ * The track is split into three parts:
+ *   - `range-start`: right half of the cell only (connecting to the next day)
+ *   - `in-range`:    full cell width
+ *   - `range-end`:   left half of the cell only (connecting from the previous day)
+ *
+ * Logical properties (`inset-inline-start/end`) are used so that RTL layouts
+ * automatically reverse the direction of the connecting fill.
+ */
+:host .calendar-day-wrapper-range-start::before,
+:host .calendar-day-wrapper-in-range::before,
+:host .calendar-day-wrapper-range-end::before {
+  content: '';
+
+  position: absolute;
+
+  inset-block: 0;
+
+  background: current-color(base, 0.15);
+
+  z-index: 0;
+}
+
+:host .calendar-day-wrapper-range-start::before {
+  /* Connect only to the inline-end (right in LTR, left in RTL) */
+  inset-inline-start: 50%;
+  inset-inline-end: 0;
+}
+
+:host .calendar-day-wrapper-in-range::before {
+  /* Full cell width */
+  inset-inline-start: 0;
+  inset-inline-end: 0;
+}
+
+:host .calendar-day-wrapper-range-end::before {
+  /* Connect only from the inline-start (left in LTR, right in RTL) */
+  inset-inline-start: 0;
+  inset-inline-end: 50%;
+}