Change PlainDateRange shape

Author: connor-baer

.changeset/four-geckos-complain.md

@@ -0,0 +1,5 @@
+---
+'@sumup-oss/circuit-ui': major
+---
+
+Changed the `PlainDateRange` type from a tuple to an object with `start` and `end` properties. This affects the Calendar component's `selection` prop. Use the new `updatePlainDateRange` helper function to update a date range when a user selects a date.

packages/circuit-ui/components/Calendar/Calendar.mdx

@@ -12,22 +12,11 @@ The Calendar component displays a monthly date grid. This is a low-level compone
 <Story of={Stories.Base} />
 <Props />
 
-## Dependencies
-
-The Calendar component uses the experimental [`Temporal` API](https://tc39.es/proposal-temporal/docs/) which has reached [stage 3](https://github.com/tc39/proposals#stage-3) in the [ECMAScript proposal](https://github.com/tc39/proposal-temporal) process but isn't implemented in [most browsers](https://caniuse.com/temporal) yet. Circuit UI depends on a [polyfill](https://github.com/fullcalendar/temporal-polyfill) which you need to install to use the component in your application:
-
-```bash
-# npm
-npm install temporal-polyfill
-# yarn v1
-yarn add temporal-polyfill
-```
-
 ## Usage
 
 ### Selection
 
-Use the `selection` prop to set the currently selected date or date range and the `onSelect` prop to update the selection when a user picks a different date. Use the `minDate` and `maxDate` props to restrict the available date range or use [modifiers](#modifiers) to disable individual days.
+Use the `selection` prop to set the currently selected date or date range and the `onSelect` prop to update the selection when a user picks a different date. Use the exported `updatePlainDateRange` function to update a date range when a user selects a date. Use the `minDate` and `maxDate` props to restrict the available date range or use [modifiers](#modifiers) to disable individual days.
 
 <Story of={Stories.Range} />
 

packages/circuit-ui/components/Calendar/Calendar.spec.tsx

@@ -25,7 +25,6 @@ import {
   waitFor,
   act,
 } from '../../util/test-utils.js';
-import type { PlainDateRange } from '../../util/date.js';
 
 import { Calendar } from './Calendar.js';
 
@@ -224,10 +223,10 @@ describe('Calendar', () => {
     });
 
     it('should mark the selected date range', () => {
-      const selection = [
-        new Temporal.PlainDate(2020, 3, 15),
-        new Temporal.PlainDate(2020, 3, 25),
-      ] satisfies PlainDateRange;
+      const selection = {
+        start: new Temporal.PlainDate(2020, 3, 15),
+        end: new Temporal.PlainDate(2020, 3, 25),
+      };
       const { container } = render(
         <Calendar {...baseProps} selection={selection} />,
       );
@@ -236,8 +235,8 @@ describe('Calendar', () => {
       expect(selectedDays).toHaveLength(11);
 
       for (
-        let index = selection[0].day;
-        index <= selection[1].day;
+        let index = selection.start.day;
+        index <= selection.end.day;
         index += 1
       ) {
         const selectedDay = screen.getByRole('button', {

packages/circuit-ui/components/Calendar/Calendar.stories.tsx

@@ -18,7 +18,11 @@ import isChromatic from 'chromatic/isChromatic';
 import { Temporal } from 'temporal-polyfill';
 
 import { Stack } from '../../../../.storybook/components/index.js';
-import { getTodaysDate, type PlainDateRange } from '../../util/date.js';
+import {
+  getTodaysDate,
+  updatePlainDateRange,
+  type PlainDateRange,
+} from '../../util/date.js';
 
 import { Calendar, type CalendarProps } from './Calendar.js';
 
@@ -118,26 +122,17 @@ export const Range = (args: CalendarProps) => {
   const [selection, setSelection] = useState(args.selection as PlainDateRange);
 
   const handleSelect = (date: Temporal.PlainDate) => {
-    setSelection((prevSelection) => {
-      if (
-        // Nothing selected yet
-        prevSelection.length === 0 ||
-        // Full range already selected
-        prevSelection.length === 2 ||
-        // Selected date is before previous start date
-        Temporal.PlainDate.compare(prevSelection[0], date) > 0
-      ) {
-        return [date];
-      }
-      return [prevSelection[0], date];
-    });
+    setSelection((prevSelection) => updatePlainDateRange(prevSelection, date));
   };
 
   return <Calendar {...args} selection={selection} onSelect={handleSelect} />;
 };
 
 Range.args = {
   ...Base.args,
-  selection: [today.subtract({ days: 3 }), today.add({ days: 3 })],
+  selection: {
+    start: today.subtract({ days: 3 }),
+    end: today.add({ days: 3 }),
+  },
   numberOfMonths: 2,
 };