react-day-picker 9.0.4 → 9.0.6

package/src/utils/addToRange.test.ts

@@ -1,119 +1,117 @@
-import { addDays, subDays } from "date-fns";
+import { addToRange } from "./addToRange";
 
-import type { DateRange } from "../types";
+describe("addToRange", () => {
+  test("add a date to an undefined range", () => {
+    const date = new Date(2022, 0, 1);
+    const range = addToRange(date, undefined);
+    expect(range).toEqual({ from: date, to: date });
+  });
 
-import { addToRange } from "./addToRange";
+  test("add a date to an empty range", () => {
+    const date = new Date(2022, 0, 1);
+    const range = addToRange(date, { from: undefined, to: undefined });
+    expect(range).toEqual({ from: date, to: date });
+  });
 
-describe('when no "from" is the range', () => {
-  const range = { from: undefined };
-  const day = new Date();
-  let result: DateRange | undefined;
-  beforeAll(() => {
-    result = addToRange(day, range);
+  test("add a date to an incomplete range with same start date", () => {
+    const date = new Date(2022, 0, 1);
+    const range = addToRange(date, { from: date, to: undefined });
+    expect(range).toEqual(undefined);
   });
-  test('should set "from" as the given day', () => {
-    expect(result).toEqual({ from: day, to: undefined });
+
+  test("add a date to an incomplete range with earlier date", () => {
+    const from = new Date(2022, 0, 1);
+    const earlierDate = new Date(2021, 11, 31);
+    const range = addToRange(earlierDate, { from: from, to: undefined });
+    expect(range).toEqual({ from: earlierDate, to: from });
   });
-});
 
-describe('when no "to" is the range', () => {
-  const day = new Date();
-  const range = { from: day, to: undefined };
-  describe('and the day is the same as the "from" day', () => {
-    let result: DateRange | undefined;
-    beforeAll(() => {
-      result = addToRange(day, range);
-    });
-    test("should reset the range", () => {
-      expect(result).toEqual({ from: undefined, to: undefined });
-    });
-  });
-  describe('and the day is before "from" day', () => {
-    const day = subDays(range.from, 1);
-    let result: DateRange | undefined;
-    beforeAll(() => {
-      result = addToRange(day, range);
-    });
-    test('should set the day as the "from" range', () => {
-      expect(result).toEqual({ from: day, to: range.from });
-    });
-  });
-  describe('and the day is after the "from" day', () => {
-    const day = addDays(range.from, 1);
-    let result: DateRange | undefined;
-    beforeAll(() => {
-      result = addToRange(day, range);
-    });
-    test('should set the day as the "to" date', () => {
-      expect(result).toEqual({ from: range.from, to: day });
-    });
+  test("add a date to an incomplete range with later date", () => {
+    const from = new Date(2022, 0, 1);
+    const date = new Date(2022, 0, 2);
+    const range = addToRange(date, { from: from, to: undefined });
+    expect(range).toEqual({ from: from, to: date });
   });
-});
 
-describe('when "from", "to" and "day" are the same', () => {
-  const day = new Date();
-  const range = { from: day, to: day };
-  let result: DateRange | undefined;
-  beforeAll(() => {
-    result = addToRange(day, range);
+  test("add a date to a complete range with same start and end date", () => {
+    const date = new Date(2022, 0, 1);
+    const from = date;
+    const to = date;
+    const range = addToRange(date, { from, to }, 0, 0, false);
+    expect(range).toEqual(undefined);
   });
-  test("should return an undefined range (reset)", () => {
-    expect(result).toEqual({ from: undefined, to: undefined });
+
+  test("add a date to a complete range with same start date", () => {
+    const date = new Date(2022, 0, 1);
+    const to = new Date(2022, 0, 2);
+    const range = addToRange(date, { from: date, to: to });
+    expect(range).toEqual({ from: date, to: date });
   });
-});
 
-describe('when "to" and "day" are the same', () => {
-  const from = new Date();
-  const to = addDays(from, 4);
-  const day = to;
-  const range = { from, to };
-  let result: DateRange | undefined;
-  beforeAll(() => {
-    result = addToRange(day, range);
+  test("add a date to a complete range with same end date", () => {
+    const date = new Date(2022, 0, 2);
+    const from = new Date(2022, 0, 1);
+    const range = addToRange(date, { from: from, to: date });
+    expect(range).toEqual({ from: date, to: date });
   });
-  test('should set "to" to undefined', () => {
-    expect(result).toEqual({ from: to, to: undefined });
+
+  test("add a date when inside the range", () => {
+    const date = new Date(2022, 0, 1);
+    const from = new Date(2021, 11, 31);
+    const to = new Date(2022, 0, 2);
+    const range = addToRange(date, { from, to });
+    expect(range).toEqual({ from, to: date });
   });
-});
 
-describe('when "from" and "day" are the same', () => {
-  const from = new Date();
-  const to = addDays(from, 4);
-  const day = from;
-  const range = { from, to };
-  let result: DateRange | undefined;
-  beforeAll(() => {
-    result = addToRange(day, range);
+  test("add an earlier date to a complete range", () => {
+    const from = new Date(2022, 0, 1);
+    const to = new Date(2022, 0, 2);
+    const date = new Date(2021, 11, 31);
+    const range = addToRange(date, { from, to });
+    expect(range).toEqual({ from: date, to: to });
   });
-  test("should reset the range", () => {
-    expect(result).toEqual({ from: undefined, to: undefined });
+
+  test("add a later date to a complete range", () => {
+    const date = new Date(2022, 0, 2);
+    const from = new Date(2021, 11, 31);
+    const to = new Date(2022, 0, 1);
+    const range = addToRange(date, { from, to });
+    expect(range).toEqual({ from: from, to: date });
   });
-});
 
-describe('when "from" is after "day"', () => {
-  const day = new Date();
-  const from = addDays(day, 1);
-  const to = addDays(from, 4);
-  const range = { from, to };
-  let result: DateRange | undefined;
-  beforeAll(() => {
-    result = addToRange(day, range);
+  test("add a date with min > 0", () => {
+    const date = new Date(2022, 0, 1);
+    const range = addToRange(date, undefined, 1, 0, false);
+    expect(range).toEqual({ from: date, to: undefined });
   });
-  test('should set the day as "from"', () => {
-    expect(result).toEqual({ from: day, to: range.to });
+
+  test("add a date with max > 0", () => {
+    const date = new Date(2022, 0, 1);
+    const range = addToRange(date, undefined, 0, 1, false);
+    expect(range).toEqual({ from: date, to: date });
+  });
+
+  test("add a date with required set to true", () => {
+    const date = new Date(2022, 0, 1);
+    const range = addToRange(date, undefined, 0, 0, true);
+    expect(range).toEqual({ from: date, to: date });
+  });
+
+  test("when exceeding max, set the start of the range", () => {
+    const from = new Date(2022, 0, 1);
+    const to = new Date(2022, 0, 2);
+    const date = new Date(2022, 0, 4);
+    const max = 2;
+    const range = addToRange(date, { from, to }, 0, max, false);
+    expect(range).toEqual({ from: date, to: undefined });
   });
-});
 
-describe('when "from" is before "day"', () => {
-  const day = new Date();
-  const from = subDays(day, 1);
-  const to = addDays(from, 4);
-  const range = { from, to };
-  let result: DateRange | undefined;
-  beforeAll(() => {
-    result = addToRange(day, range);
-  });
-  test('should set the day as "to"', () => {
-    expect(result).toEqual({ from: range.from, to: day });
+  test("when below min, set the start of the range", () => {
+    const from = new Date(2021, 11, 20);
+    const to = new Date(2022, 0, 2);
+    const date = new Date(2021, 11, 21);
+    const min = 5;
+    const range = addToRange(date, { from, to }, min, 0, false);
+    expect(range).toEqual({ from: date, to: undefined });
   });
 });

package/src/utils/addToRange.ts

@@ -10,42 +10,78 @@ import type { DateRange, DateLib } from "../types/index.js";
  * @group Utilities
  */
 export function addToRange(
+  /** The date to add to the range. */
   date: Date,
-  range: DateRange | undefined,
+  /** The range where to add `date`. */
+  initialRange: DateRange | undefined,
+  min = 0,
+  max = 0,
+  required = false,
   /** @ignore */
   dateLib: DateLib = defaultDateLib
-): DateRange {
-  const { from, to } = range || {};
+): DateRange | undefined {
+  const { from, to } = initialRange || {};
   const { isSameDay, isAfter, isBefore } = dateLib;
-  if (from && to) {
-    if (isSameDay(to, date) && isSameDay(from, date)) {
-      return { from: undefined, to: undefined };
-    }
-    if (isSameDay(to, date)) {
-      return { from: to, to: undefined };
-    }
+
+  let range: DateRange | undefined;
+
+  if (!from && !to) {
+    // the range is empty, add the date
+    range = { from: date, to: min > 0 ? undefined : date };
+  } else if (from && !to) {
+    // adding date to an incomplete range
     if (isSameDay(from, date)) {
-      return { from: undefined, to: undefined };
+      // adding a date equal to the start of the range
+      if (required) {
+        range = { from, to: undefined };
+      } else {
+        range = undefined;
+      }
+    } else if (isBefore(date, from)) {
+      // adding a date before the start of the range
+      range = { from: date, to: from };
+    } else {
+      // adding a date after the start of the range
+      range = { from, to: date };
     }
-    if (isAfter(from, date)) {
-      return { from: date, to };
+  } else if (from && to) {
+    // adding date to a complete range
+    if (isSameDay(from, date) && isSameDay(to, date)) {
+      // adding a date that is equal to both start and end of the range
+      if (required) {
+        range = { from, to };
+      } else {
+        range = undefined;
+      }
+    } else if (isSameDay(from, date)) {
+      // adding a date equal to the the start of the range
+      range = { from, to: min > 0 ? undefined : date };
+    } else if (isSameDay(to, date)) {
+      // adding a dare equal to the end of the range
+      range = { from: date, to: min > 0 ? undefined : date };
+    } else if (isBefore(date, from)) {
+      // adding a date before the start of the range
+      range = { from: date, to: to };
+    } else if (isAfter(date, from)) {
+      // adding a date after the start of the range
+      range = { from, to: date };
+    } else if (isAfter(date, to)) {
+      // adding a date after the end of the range
+      range = { from, to: date };
+    } else {
+      throw new Error("Invalid range");
     }
-    return { from, to: date };
   }
-  if (to) {
-    if (isAfter(date, to)) {
-      return { from: to, to: date };
-    }
-    return { from: date, to };
-  }
-  if (from) {
-    if (isBefore(date, from)) {
-      return { from: date, to: from };
-    }
-    if (isSameDay(date, from)) {
-      return { from: undefined, to: undefined };
+
+  // check for min / max
+  if (range?.from && range?.to) {
+    const diff = dateLib.differenceInCalendarDays(range.to, range.from);
+    if (max > 0 && diff > max) {
+      range = { from: date, to: undefined };
+    } else if (min > 1 && diff < min) {
+      range = { from: date, to: undefined };
     }
-    return { from, to: date };
   }
-  return { from: date, to: undefined };
+
+  return range;
 }

package/website/docs/docs/accessibility.mdx

@@ -76,7 +76,7 @@ DayPicker supports keyboard navigation to make it easier for users to navigate t
 | Keys                         | Function                             |
 | ---------------------------- | ------------------------------------ |
 | <kbd>Arrow Top</kbd>         | Move focus to the previous week.     |
-| <kbd>Arrow Right</kbd>       | Move focus to the next da.y          |
+| <kbd>Arrow Right</kbd>       | Move focus to the next day.          |
 | <kbd>Arrow Bottom</kbd>      | Move focus to the next week.         |
 | <kbd>Arrow Left</kbd>        | Move focus to the previous day.      |
 | <kbd>Page Up</kbd>           | Move focus to the previous month.    |

package/website/docs/docs/selection-modes.mdx

@@ -40,23 +40,13 @@ When the `mode` prop is set to `"single"`, only one day can be selected.
 | `onSelect` | `(selected, triggerDate, modifiers, e) => void` | Event callback when a date is selected. |
 | `required` | `boolean`                                       | Make the selection required.            |
 
-The following code snippet will render a date picker with a single selected date. When a day is clicked, the `selectedDate` state is updated.
+Use the `selected` and `onSelect` props to control the selected date:
 
 ```tsx
-import { useState } from "react";
-
-import { DayPicker } from "react-day-picker";
-
 export function App() {
-  const initiallySelectedDate = new Date();
-  const [selectedDate, setSelectedDate] = useState(initiallySelectedDate);
-  return (
-    <DayPicker
-      mode="single"
-      selected={selectedDate}
-      onSelect={setSelectedDate}
-    />
-  );
+  const [selected, setSelected] = React.useState<Date | undefined>();
+
+  return <DayPicker mode="single" selected={selected} onSelect={setSelected} />;
 }
 ```
 
@@ -93,103 +83,89 @@ By setting the `mode` prop to `"multiple"`, DayPicker allows selecting multiple
 | `min`      | `number`                                        | The minimum dates that can be selected. |
 | `max`      | `number`                                        | The maximum dates that can be selected. |
 
-### Min and Max Dates
-
-Use the `min` and `max` props to limit the number of selectable dates.
+Use the `selected` and `onSelect` props to control the selected date:
 
 ```tsx
-import { addDays } from "date-fns";
-import { DayPicker } from "react-day-picker";
+export function App() {
+  const [selected, setSelected] = React.useState<Date[] | undefined>();
 
-export function MultipleMinMax() {
-  const defaultSelected = [new Date(), addDays(new Date(), 1)];
   return (
-    <DayPicker
-      defaultSelected={defaultSelected}
-      mode="multiple"
-      min={2}
-      max={5}
-    />
+    <DayPicker mode="multiple" selected={selected} onSelect={setSelected} />
   );
 }
 ```
 
+### Min and Max Dates
+
+Use the `min` and `max` props to limit the number of selectable dates.
+
+```tsx
+<DayPicker mode="multiple" min={2} max={5} />
+```
+
 <BrowserWindow>
   <Examples.MultipleMinMax />
 </BrowserWindow>
 
-## Range Mode
+### Required Selection
 
-When the `mode` prop is set to `"range"`, DayPicker allows selecting a continuous range of dates.
+By setting the `required` prop, DayPicker requires at least one date to be selected.
 
 ```tsx
-<DayPicker mode="range" />
+<DayPicker mode="multiple" required selected={[new Date()]} />
 ```
 
-| Prop Name  | Type                                            | Description                             |
-| ---------- | ----------------------------------------------- | --------------------------------------- |
-| `selected` | [`DateRange`](../api/type-aliases/DateRange.md) | The selected range.                     |
-| `onSelect` | `(selected, triggerDate, modifiers, e) => void` | Event callback when a date is selected. |
-| `min`      | `number`                                        | The minimum dates that can be selected. |
-| `max`      | `number`                                        | The maximum dates that can be selected. |
-
-```tsx
-import { addDays, format } from "date-fns";
-import { DateRange, DayPicker } from "react-day-picker";
+<BrowserWindow>
+  <Examples.MultipleRequired />
+</BrowserWindow>
 
-export function RangeExample() {
-  const defaultMonth = new Date(2020, 5, 15);
+## Range Mode
 
-  const defaultSelected: DateRange = {
-    from: defaultMonth,
-    to: addDays(defaultMonth, 4)
-  };
-  const [range, setRange] = React.useState<DateRange | undefined>(
-    defaultSelected
-  );
+When the `mode` prop is set to `"range"`, DayPicker allows selecting a continuous range of dates.
 
-  return (
-    <DayPicker
-      mode="range"
-      defaultMonth={defaultMonth}
-      selected={range}
-      onSelect={setRange}
-    />
-  );
-}
+```tsx
+<DayPicker mode="range" />
 ```
 
 <BrowserWindow>
   <Examples.Range />
 </BrowserWindow>
 
+### Range Mode Props
+
+| Prop Name         | Type                                            | Description                             |
+| ----------------- | ----------------------------------------------- | --------------------------------------- |
+| `selected`        | [`DateRange`](../api/type-aliases/DateRange.md) | The selected range.                     |
+| `onSelect`        | `(selected, triggerDate, modifiers, e) => void` | Event callback when a date is selected. |
+| `required`        | `boolean`                                       | Make the selection required.            |
+| `min`             | `number`                                        | The minimum dates that can be selected. |
+| `max`             | `number`                                        | The maximum dates that can be selected. |
+| `excludeDisabled` | `boolean`                                       | Exclude disabled dates from the range.  |
+
 ### Min and Max Dates
 
-Also in range mode, you can set the `min` and `max` props to limit the number of selectable dates.
+As default, a range can have length of 0 nights, thus the start date can be the same as the end date. Use the `min` prop to set the minimum number of nights. The range will stay "open" until at least `min` nights are selected.
+
+Similarly, you can se the `max` prop to set the maximum number of nights.
 
 ```tsx
-import { useState } from "react";
+<DayPicker mode="range" min={1} max={6} />
+```
 
-import { DateRange, DayPicker } from "react-day-picker";
+<BrowserWindow bodyStyle={{ justifyContent: "start" }}>
+  <Examples.RangeMinMax />
+</BrowserWindow>
 
-export function RangeMinMax() {
-  const [range, setRange] = useState<DateRange | undefined>();
+### Required Ranges
 
-  return (
-    <DayPicker
-      defaultMonth={new Date(2022, 8)}
-      mode="range"
-      min={3}
-      max={9}
-      selected={range}
-      onSelect={setRange}
-    />
-  );
-}
+By setting the `required` prop, a range must be selected. 
+
+```tsx
+<DayPicker mode="range" required />
 ```
 
 <BrowserWindow>
-  <Examples.RangeMinMax />
+  <Examples.RangeRequired />
 </BrowserWindow>
 
 ## Disabling Dates

package/website/docs/guides/custom-components.mdx

@@ -4,21 +4,31 @@ sidebar_position: 4
 
 # Custom Components
 
-Custom components allows to customize or replace the components rendering the DayPicker HTML elements.
+With the `components` prop, you can extend each of the rendered HTML elements by using your own components.
 
 | Prop Name    | Type                                                          | Description                            |
 | ------------ | ------------------------------------------------------------- | -------------------------------------- |
 | `components` | [`CustomComponents`](../api/type-aliases/CustomComponents.md) | Change the components of the calendar. |
 
-## When to use Custom Components
+You may need to use custom components in advanced applications, for example to:
 
-Custom components allow to enhance DayPicker to align it with your design system, to modify navigation behavior, or to present unique content within day cells.
+- Prevent default events from occurring
+- Add new event listeners, such as touch events
+- Display extra content, such as a calendar entry in the day cell
+- Implement buttons or dropdowns using your own design system components
+- Wrap an element with another element, like adding a tooltip to a day cell.
 
-Get familiar with the [API Reference](../api#components) and the [DayPicker Anatomy](../docs/anatomy.mdx) and make sure you don't break [accessibility](../docs/accessibility.mdx) when customizing components.
+When customizing the components, get familiar with the [API Reference](../api#components) and the [DayPicker Anatomy](../docs/anatomy.mdx). Make sure you don't break the [accessibility](../docs/accessibility.mdx).
 
-## How to Use Custom Components
+:::note Custom Components vs Formatters
 
-To use custom components, pass the `components` prop. The prop is an object with the components you want to customize:
+Custom components extends DayPicker more than the [formatters](../docs/translation.mdx#custom-formatters), which are used to format the content of the calendar.
+
+:::
+
+## Implementing a Custom Component
+
+Pass the components you want to customize to the `components` prop. This prop accepts any of the [`CustomComponents`](../api/type-aliases/CustomComponents.md).
 
 ```tsx
 <DayPicker
@@ -30,13 +40,6 @@ To use custom components, pass the `components` prop. The prop is an object with
 />
 ```
 
-Each component is the last step before actually rendering its element.
-
-- prevent default events to happen - e.g. prevent the click event on a day button to select a day
-- add new event listeners - e.g. add a touch event to select a day
-- display new content - e.g. add a new element to the day cell, such a calendar event.
-- wrap the element with a new component - e.g. wrap the day cell with a tooltip component
-
 <details>
   <summary>List of Customizable Components</summary>
 
@@ -124,78 +127,3 @@ The DayPicker context provides the current state of the calendar, such as the se
 | Function                                           | Return value                                                  | Description                                                                  |
 | :------------------------------------------------- | ------------------------------------------------------------- | :--------------------------------------------------------------------------- |
 | [`useDayPicker`](../api/functions/useDayPicker.md) | [`DayPickerContext`](../api/type-aliases/DayPickerContext.md) | Return the current state of DayPicker and functions to navigate the calendar |
-
-### Examples
-
-#### Range Selection with the <kbd>Shift</kbd> Key
-
-Implement a custom `Day` component to select ranges while pressing the <kbd>Shift</kbd> key.
-
-```tsx
-import React, { MouseEventHandler } from "react";
-
-import { isSameDay } from "date-fns";
-import {
-  DateRange,
-  DayButtonProps,
-  DayPicker,
-  useDayPicker
-} from "react-day-picker";
-
-function CustomDayButton(props: DayButtonProps) {
-  // Use the DayPicker hook to get the selected days
-  const { selected } = useDayPicker({ mode: "range" });
-
-  const handleClick: MouseEventHandler<HTMLButtonElement> = (e) => {
-    const requireShiftKey =
-      selected.from && // The start of the range is selected
-      !selected.to && // The second day is not selected
-      !isSameDay(props.day.date, selected.from); // User is not clicking the start ot the range again
-
-    if (!e.shiftKey && requireShiftKey) return;
-
-    // Call the original onClick event
-    props.onClick?.(e);
-  };
-
-  // Pick the button props
-  const { day, modifiers, ...buttonProps } = props;
-
-  return (
-    <button {...buttonProps} onClick={handleClick}>
-      {props.children}
-    </button>
-  );
-}
-
-export function RangeWithShiftKey() {
-  const [range, setRange] = React.useState<DateRange | undefined>({
-    from: undefined
-  });
-
-  let footer = "Please pick a day.";
-
-  if (range?.from && !range?.to) {
-    footer = "Press Shift to choose more days.";
-  } else if (range?.to) {
-    const formattedFrom = range.from?.toDateString();
-    const formattedTo = range.to.toDateString();
-    footer = `You selected the days between ${formattedFrom} and ${formattedTo}`;
-  }
-  return (
-    <DayPicker
-      components={{
-        DayButton: CustomDayButton
-      }}
-      mode="range"
-      selected={range}
-      onSelect={setRange}
-      footer={footer}
-    />
-  );
-}
-```
-
-<BrowserWindow>
-  <Examples.RangeShiftKey />
-</BrowserWindow>

package/website/docs/intro.mdx

@@ -16,7 +16,7 @@ DayPicker is a [React](https://react.dev) component to create date pickers, cale
 - 📅 Supports [selections](./docs/selection-modes.mdx) of single day, multiple days, ranges of days, or [custom selections](./guides/custom-selections.mdx).
 - 🌍 Can be [localized](./docs/localization.mdx) into any language, supports [ISO 8601 dates](./docs/localization.mdx#iso-week-dates), [UTC dates](./docs/localization.mdx#utc-dates), and [Jalali calendar](./docs/localization.mdx#jalali-calendar).
 - 🦮 Complies with WCAG 2.1 AA requirements for [accessibility](./docs/accessibility.mdx).
-- ⚙️ [Customizable components](./guides/custom-components.mdx) for complete customization.
+- ⚙️ [Customizable components](./guides/custom-components.mdx) to extend the rendered elements.
 - 🔤 Easy integration [with input fields](./guides/input-fields.mdx).
 
 DayPicker is written in TypeScript and compiled to CommonJS and ESM. It relies on [date-fns](https://date-fns.org) for date manipulation and formatting.