feat(datetime): add showAdjacentDays to display days from the previous and next months (#30262)

Issue number: Internal


## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->
Adds a new property to datetime, showAdjacentDays, that when true will
show the last days of the previous month and the first days of the next
month. This will just occupy empty "cells" at the beginning of the month
"table" and add rows to the table until a maximum of 6 rows are
displayed.

## Changes
- add styles for adjacent day button
- add `showAdjacentDays` property to datetime component
- change month generation to respect new property
- add visual tests to new feature

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

## Other information


[Preview](https://ionic-framework-git-rou-11118v2-ionic1.vercel.app/src/components/datetime/test/show-adjacent-days)

---------

Co-authored-by: Brandy Smith <[email protected]>
Co-authored-by: Brandy Smith <[email protected]>
Co-authored-by: Maria Hutt <[email protected]>

Author: 3 people

core/api.txt

@@ -534,6 +534,7 @@ 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,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

core/src/components.d.ts

@@ -944,6 +944,10 @@ export namespace Components {
           * Resets the internal state of the datetime but does not update the value. Passing a valid ISO-8601 string will reset the state of the component to the provided date. If no value is provided, the internal state will be reset to the clamped value of the min, max and today.
          */
         "reset": (startDate?: string) => Promise<void>;
+        /**
+          * 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.
+         */
+        "showAdjacentDays": boolean;
         /**
           * If `true`, a "Clear" button will be rendered alongside the default "Cancel" and "OK" buttons at the bottom of the `ion-datetime` component. Developers can also use the `button` slot if they want to customize these buttons. If custom buttons are set in the `button` slot then the default buttons will not be rendered.
          */
@@ -5779,6 +5783,10 @@ declare namespace LocalJSX {
           * If `true`, the datetime appears normal but the selected date cannot be changed.
          */
         "readonly"?: boolean;
+        /**
+          * 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.
+         */
+        "showAdjacentDays"?: boolean;
         /**
           * If `true`, a "Clear" button will be rendered alongside the default "Cancel" and "OK" buttons at the bottom of the `ion-datetime` component. Developers can also use the `button` slot if they want to customize these buttons. If custom buttons are set in the `button` slot then the default buttons will not be rendered.
          */

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

@@ -15,6 +15,7 @@ export interface DatetimeParts {
   hour?: number;
   minute?: number;
   ampm?: 'am' | 'pm';
+  isAdjacentDay?: boolean;
 }
 
 export type DatetimePresentation = 'date-time' | 'time-date' | 'date' | 'time' | 'month' | 'year' | 'month-year';

core/src/components/datetime/datetime.ios.scss

@@ -267,6 +267,10 @@
   color: current-color(contrast);
 }
 
+:host .calendar-day.calendar-day-adjacent-day {
+  color: $text-color-step-700;
+}
+
 // Time / Header
 // -----------------------------------
 :host .datetime-time {

core/src/components/datetime/datetime.md.scss

@@ -121,12 +121,17 @@
   color: current-color(contrast);
 }
 
-.calendar-day.calendar-day-active {
+.calendar-day.calendar-day-active,
+.calendar-day.calendar-day-active:focus {
   border: 1px solid current-color(base);
 
   background: current-color(base);
 }
 
+:host .calendar-day.calendar-day-adjacent-day {
+  color: $text-color-step-500;
+}
+
 // Time / Header
 // -----------------------------------
 :host .datetime-time {

core/src/components/datetime/datetime.scss

@@ -364,7 +364,8 @@
   opacity: 0.4;
 }
 
-.calendar-day:focus {
+
+.calendar-day:not(.calendar-day-adjacent-day):focus {
   background: current-color(base, 0.2);
 
   box-shadow: 0px 0px 0px 4px current-color(base, 0.2);

core/src/components/datetime/datetime.tsx

@@ -139,6 +139,7 @@ export class Datetime implements ComponentInterface {
     hour: 13,
     minute: 52,
     ampm: 'pm',
+    isAdjacentDay: false,
   };
 
   @Element() el!: HTMLIonDatetimeElement;
@@ -207,6 +208,13 @@ export class Datetime implements ComponentInterface {
    */
   @Prop() isDateEnabled?: (dateIsoString: string) => boolean;
 
+  /**
+   * 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.
+   */
+  @Prop() showAdjacentDays = false;
+
   @Watch('disabled')
   protected disabledChanged() {
     this.emitStyle();
@@ -805,12 +813,17 @@ export class Datetime implements ComponentInterface {
 
   private focusWorkingDay = (currentMonth: Element) => {
     /**
-     * Get the number of padding days so
+     * Get the number of offset days so
      * we know how much to offset our next selector by
      * to grab the correct calendar-day element.
      */
-    const padding = currentMonth.querySelectorAll('.calendar-day-padding');
-    const { day } = this.workingParts;
+
+    const { day, month, year } = this.workingParts;
+    const firstOfMonth = new Date(`${month}/1/${year}`).getDay();
+    const offset =
+      firstOfMonth >= this.firstDayOfWeek
+        ? firstOfMonth - this.firstDayOfWeek
+        : 7 - (this.firstDayOfWeek - firstOfMonth);
 
     if (day === null) {
       return;
@@ -821,7 +834,7 @@ export class Datetime implements ComponentInterface {
      * and focus it.
      */
     const dayEl = currentMonth.querySelector(
-      `.calendar-day-wrapper:nth-of-type(${padding.length + day}) .calendar-day`
+      `.calendar-day-wrapper:nth-of-type(${offset + day}) .calendar-day`
     ) as HTMLElement | null;
     if (dayEl) {
       dayEl.focus();
@@ -2226,10 +2239,34 @@ export class Datetime implements ComponentInterface {
         }}
       >
         <div class="calendar-month-grid">
-          {getDaysOfMonth(month, year, this.firstDayOfWeek % 7).map((dateObject, index) => {
-            const { day, dayOfWeek } = dateObject;
-            const { el, highlightedDates, isDateEnabled, multiple } = this;
-            const referenceParts = { month, day, year };
+          {getDaysOfMonth(month, year, this.firstDayOfWeek % 7, this.showAdjacentDays).map((dateObject, index) => {
+            const { day, dayOfWeek, isAdjacentDay } = dateObject;
+            const { el, highlightedDates, isDateEnabled, multiple, showAdjacentDays } = this;
+            let _month = month;
+            let _year = year;
+            if (showAdjacentDays && isAdjacentDay && day !== null) {
+              if (day > 20) {
+                // Leading with the adjacent day from the previous month
+                // if its a adjacent day and is higher than '20' (last week even in feb)
+                if (month === 1) {
+                  _year = year - 1;
+                  _month = 12;
+                } else {
+                  _month = month - 1;
+                }
+              } else if (day < 15) {
+                // Leading with the adjacent day from the next month
+                // if its a adjacent day and is lower than '15' (first two weeks)
+                if (month === 12) {
+                  _year = year + 1;
+                  _month = 1;
+                } else {
+                  _month = month + 1;
+                }
+              }
+            }
+
+            const referenceParts = { month: _month, day, year: _year, isAdjacentDay };
             const isCalendarPadding = day === null;
             const {
               isActive,
@@ -2284,18 +2321,20 @@ export class Datetime implements ComponentInterface {
              * Custom highlight styles should not override the style for selected dates,
              * nor apply to "filler days" at the start of the grid.
              */
-            if (highlightedDates !== undefined && !isActive && day !== null) {
+            if (highlightedDates !== undefined && !isActive && 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) {
+            if (!isCalendarPadding && !isAdjacentDay) {
               dateParts = `calendar-day${isActive ? ' active' : ''}${isToday ? ' today' : ''}${
                 isCalDayDisabled ? ' disabled' : ''
               }`;
+            } else if (isAdjacentDay) {
+              dateParts = `calendar-day${isCalDayDisabled ? ' disabled' : ''}`;
             }
 
             return (
@@ -2319,8 +2358,8 @@ export class Datetime implements ComponentInterface {
                   }}
                   tabindex="-1"
                   data-day={day}
-                  data-month={month}
-                  data-year={year}
+                  data-month={_month}
+                  data-year={_year}
                   data-index={index}
                   data-day-of-week={dayOfWeek}
                   disabled={isButtonDisabled}
@@ -2330,6 +2369,7 @@ export class Datetime implements ComponentInterface {
                     'calendar-day-active': isActive,
                     'calendar-day-constrained': isCalDayConstrained,
                     'calendar-day-today': isToday,
+                    'calendar-day-adjacent-day': isAdjacentDay,
                   }}
                   part={dateParts}
                   aria-hidden={isCalendarPadding ? 'true' : null}
@@ -2340,29 +2380,37 @@ export class Datetime implements ComponentInterface {
                       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.setWorkingParts({
                       ...this.workingParts,
-                      month,
+                      month: _month,
                       day,
-                      year,
+                      year: _year,
+                      isAdjacentDay,
                     });
 
                     // multiple only needs date info, so we can wipe out other fields like time
                     if (multiple) {
                       this.setActiveParts(
                         {
-                          month,
+                          month: _month,
                           day,
-                          year,
+                          year: _year,
+                          isAdjacentDay,
                         },
                         isActive
                       );
                     } else {
                       this.setActiveParts({
                         ...activePart,
-                        month,
+                        month: _month,
                         day,
-                        year,
+                        year: _year,
+                        isAdjacentDay,
                       });
                     }
                   }}

core/src/components/datetime/test/basic/datetime.e2e.ts-snapshots/datetime-focus-selected-calendar-day-md-ltr-Mobile-Chrome-linux.png

@@ -0,0 +1,51 @@
+import { expect } from '@playwright/test';
+import { configs, test } from '@utils/test/playwright';
+
+/**
+ * This behavior does not vary across directions
+ */
+configs({ directions: ['ltr'] }).forEach(({ title, screenshot, config }) => {
+  test.describe(title('datetime: show adjacent days'), () => {
+    test('should not have visual regressions', async ({ page }) => {
+      await page.goto('/src/components/datetime/test/show-adjacent-days', config);
+      const datetime = page.locator('#default');
+      await expect(datetime).toHaveScreenshot(screenshot(`datetime-show-adjacent-days`));
+    });
+
+    test('should not have visual regressions with a custom styled calendar', async ({ page }) => {
+      await page.goto('/src/components/datetime/test/show-adjacent-days', config);
+      const datetime = page.locator('#custom-calendar-days');
+      await expect(datetime).toHaveScreenshot(screenshot(`datetime-show-adjacent-days-custom-calendar`));
+    });
+
+    test('should not have visual regressions with specific date disabled', async ({ page }) => {
+      await page.goto('/src/components/datetime/test/show-adjacent-days', config);
+      const datetime = page.locator('#specificDate');
+      await expect(datetime).toHaveScreenshot(screenshot(`datetime-show-adjacent-days-specific-date-disabled`));
+    });
+
+    test('should not have visual regressions with weekends disabled', async ({ page }) => {
+      await page.goto('/src/components/datetime/test/show-adjacent-days', config);
+      const datetime = page.locator('#weekends');
+      await expect(datetime).toHaveScreenshot(screenshot(`datetime-show-adjacent-days-weekends-disabled`));
+    });
+
+    test('should not have visual regressions with date range disabled', async ({ page }) => {
+      await page.goto('/src/components/datetime/test/show-adjacent-days', config);
+      const datetime = page.locator('#dateRange');
+      await expect(datetime).toHaveScreenshot(screenshot(`datetime-show-adjacent-days-date-range-disabled`));
+    });
+
+    test('should not have visual regressions with month disabled', async ({ page }) => {
+      await page.goto('/src/components/datetime/test/show-adjacent-days', config);
+      const datetime = page.locator('#month');
+      await expect(datetime).toHaveScreenshot(screenshot(`datetime-show-adjacent-days-month-disabled`));
+    });
+
+    test('should not have visual regressions with display specified', async ({ page }) => {
+      await page.goto('/src/components/datetime/test/show-adjacent-days', config);
+      const datetime = page.locator('#display');
+      await expect(datetime).toHaveScreenshot(screenshot(`datetime-show-adjacent-days-display`));
+    });
+  });
+});