feat: Add ability to control first month shown in date range picker

Author: gethinwebster

package-lock.json

@@ -27,6 +27,7 @@ interface DateRangePickerPageSettings {
   disabledDates?: DisabledDate;
   showDisabledReason?: boolean;
   hasValue?: boolean;
+  absoluteMultiGridStartPeriod?: DateRangePickerProps.StartPeriod;
 }
 
 const defaultSettings: Required<DateRangePickerPageSettings> = {
@@ -45,6 +46,7 @@ const defaultSettings: Required<DateRangePickerPageSettings> = {
   disabledDates: 'none',
   showDisabledReason: true,
   hasValue: true,
+  absoluteMultiGridStartPeriod: 'current',
 };
 
 export function useDateRangePickerSettings(
@@ -89,6 +91,7 @@ export function useDateRangePickerSettings(
   const disabledDates = urlParams.disabledDates ?? def('disabledDates');
   const showDisabledReason = parseBoolean(def('showDisabledReason'), urlParams.showDisabledReason);
   const hasValue = parseBoolean(def('hasValue'), urlParams.hasValue);
+  const absoluteMultiGridStartPeriod = urlParams.absoluteMultiGridStartPeriod ?? def('absoluteMultiGridStartPeriod');
   const settings: Required<DateRangePickerPageSettings> = {
     dateOnly,
     monthOnly,
@@ -105,6 +108,7 @@ export function useDateRangePickerSettings(
     disabledDates,
     showDisabledReason,
     hasValue,
+    absoluteMultiGridStartPeriod,
   };
   const setSettings = (settings: DateRangePickerPageSettings) => setUrlParams(settings);
 
@@ -256,6 +260,7 @@ export function Settings({
     disabledDates,
     showDisabledReason,
     hasValue,
+    absoluteMultiGridStartPeriod,
   },
   setSettings,
 }: {
@@ -274,6 +279,7 @@ export function Settings({
   const dateFormatOptions = [{ value: 'iso' }, { value: 'slashed' }, { value: 'long-localized' }];
   const inputDateFormat = [{ value: 'iso' }, { value: 'slashed' }];
   const timeFormatOptions = [{ value: 'hh:mm:ss' }, { value: 'hh:mm' }, { value: 'hh' }];
+  const absoluteMultiGridStartPeriodOptions = [{ value: 'current' }, { value: 'previous' }];
   return (
     <SpaceBetween size="m" direction="horizontal">
       <FormField label="Range selector mode">
@@ -332,6 +338,20 @@ export function Settings({
         />
       </FormField>
 
+      <FormField label="Start period">
+        <Select
+          options={absoluteMultiGridStartPeriodOptions}
+          selectedOption={
+            absoluteMultiGridStartPeriodOptions.find(o => o.value === absoluteMultiGridStartPeriod) ?? null
+          }
+          onChange={({ detail }) =>
+            setSettings({
+              absoluteMultiGridStartPeriod: detail.selectedOption.value as DateRangePickerProps.StartPeriod,
+            })
+          }
+        />
+      </FormField>
+
       <SpaceBetween direction="horizontal" size="s">
         <Checkbox checked={hasValue} onChange={({ detail }) => setSettings({ hasValue: detail.checked })}>
           Has initial value

pages/date-range-picker/common.tsx

@@ -36,6 +36,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [undefined],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   })),
   // Disabled dates
   {
@@ -45,6 +46,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [undefined],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
   // Date-only
   {
@@ -54,6 +56,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [undefined],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
   // Custom control
   {
@@ -62,6 +65,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [() => 'Custom control'],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
   // Date input formats
   {
@@ -71,6 +75,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     timeInputFormat: ['hh:mm:ss'] as const,
     dateInputFormat: ['iso', 'slashed'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
   // Time input formats
   {
@@ -79,6 +84,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [undefined],
     timeInputFormat: ['hh:mm', 'hh'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
 ]);
 

pages/date-range-picker/month-calendar-permutations.page.tsx

@@ -30,6 +30,7 @@ export default function RangeCalendarScenario() {
           customAbsoluteRangeControl={undefined}
           timeInputFormat="hh:mm:ss"
           absoluteFormat="slashed"
+          multiGridStartPeriod="current"
         />
 
         <Link id="focusable-after">Focusable element after</Link>

pages/date-range-picker/range-calendar.page.tsx

@@ -19,7 +19,7 @@ const intervals = [
   ['2022-02', '2022-03'], //next
   ['2021-01', '2021-03'], //q1
   ['2022-04', '2022-06'], //q2
-  ['2023-07', '2022-09'], //q3
+  ['2022-07', '2022-09'], //q3
   ['2024-10', '2024-12'], //q4
 ];
 
@@ -33,6 +33,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [undefined],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current', 'previous'] as const,
   })),
   // Disabled dates
   {
@@ -42,6 +43,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [undefined],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
   // Custom control
   {
@@ -50,6 +52,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     customAbsoluteRangeControl: [() => 'Custom control'],
     timeInputFormat: ['hh:mm:ss'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
   // Input date formats
   {
@@ -59,6 +62,7 @@ const permutations = createPermutations<DateRangePickerCalendarProps>([
     timeInputFormat: ['hh:mm:ss'] as const,
     dateInputFormat: ['iso', 'slashed'] as const,
     absoluteFormat: ['long-localized'] as const,
+    multiGridStartPeriod: ['current'] as const,
   },
 ]);
 

pages/date-range-picker/year-calendar-permutations.page.tsx

@@ -10816,6 +10816,22 @@ It can take the following values:
       "optional": true,
       "type": "string",
     },
+    {
+      "defaultValue": "'current'",
+      "description": "Specifies whether to start with the previous or current period (month or year)
+when multiple calendar grids are displayed in absolute mode.",
+      "inlineType": {
+        "name": "DateRangePickerProps.StartPeriod",
+        "type": "union",
+        "values": [
+          "current",
+          "previous",
+        ],
+      },
+      "name": "absoluteMultiGridStartPeriod",
+      "optional": true,
+      "type": "string",
+    },
     {
       "description": "Adds \`aria-describedby\` to the component. If you're using this component within a form field,
 don't set this property because the form field component automatically sets it.

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap

@@ -1154,6 +1154,71 @@ describe('Date range picker', () => {
         });
       });
 
+      describe('absoluteMultiGridStartPeriod', () => {
+        test('defaults to "current" - header shows start date period on the left grid', () => {
+          const { wrapper } = renderDateRangePicker({
+            ...defaultProps,
+            granularity,
+            value: { type: 'absolute', startDate: '2020-03-02T05:00:00+08:45', endDate: '2020-03-12T13:05:21+08:45' },
+          });
+
+          wrapper.findTrigger().click();
+
+          // Default "current" means the start date's month/year appears in the left grid
+          // For day: left=March 2020, right=April 2020, header shows "March 2020April 2020"
+          // For month: left=2020, right=2021, header shows "20202021"
+          const expectedResult = granularity === 'day' ? 'March 2020' : '20202021';
+          expect(wrapper.findDropdown()!.findHeader().getElement()).toHaveTextContent(expectedResult);
+        });
+
+        test('"current" explicitly set shows same as default', () => {
+          const { wrapper } = renderDateRangePicker({
+            ...defaultProps,
+            granularity,
+            absoluteMultiGridStartPeriod: 'current',
+            value: { type: 'absolute', startDate: '2020-03-02T05:00:00+08:45', endDate: '2020-03-12T13:05:21+08:45' },
+          });
+
+          wrapper.findTrigger().click();
+
+          const expectedResult = granularity === 'day' ? 'March 2020' : '20202021';
+          expect(wrapper.findDropdown()!.findHeader().getElement()).toHaveTextContent(expectedResult);
+        });
+
+        test('"previous" shows the previous period on the left grid', () => {
+          const { wrapper } = renderDateRangePicker({
+            ...defaultProps,
+            granularity,
+            absoluteMultiGridStartPeriod: 'previous',
+            value: { type: 'absolute', startDate: '2020-03-02T05:00:00+08:45', endDate: '2020-03-12T13:05:21+08:45' },
+          });
+
+          wrapper.findTrigger().click();
+
+          // "previous" means start date's month/year is shown on the right grid, previous on the left
+          // For day: left=February 2020, right=March 2020, header shows "February 2020March 2020"
+          // For month: left=2019, right=2020, header shows "20192020"
+          const expectedResult = granularity === 'day' ? 'February 2020' : '20192020';
+          expect(wrapper.findDropdown()!.findHeader().getElement()).toHaveTextContent(expectedResult);
+        });
+
+        test('"previous" allows start date to be visible in right grid', () => {
+          const { wrapper } = renderDateRangePicker({
+            ...defaultProps,
+            granularity,
+            absoluteMultiGridStartPeriod: 'previous',
+            value: { type: 'absolute', startDate: '2021-06-15T00:00:00+08:45', endDate: '2021-06-20T23:59:59+08:45' },
+          });
+
+          wrapper.findTrigger().click();
+
+          // For day: left=May 2021, right=June 2021
+          // For month: left=2020, right=2021
+          const expectedResult = granularity === 'day' ? 'May 2021' : '20202021';
+          expect(wrapper.findDropdown()!.findHeader().getElement()).toHaveTextContent(expectedResult);
+        });
+      });
+
       describe('i18n', () => {
         describe.each([true, false] as const)('With dateOnly of %s', dateOnly => {
           test('supports using absolute range with i18n defaults', () => {