react-day-picker 9.0.6 → 9.0.7

package/dist/esm/types/props.d.ts

@@ -12,8 +12,11 @@ export type DayPickerProps = PropsBase & (PropsSingle | PropsSingleRequired | Pr
     required?: undefined;
 });
 /**
- * Props used for customization of the calendar, localization, and event
- * handling.
+ * Props for customizing the calendar, handling localization, and managing
+ * events. These exclude the selection mode props.
+ *
+ * @group DayPicker
+ * @see https://daypicker.dev/api/interfaces/PropsBase
  */
 export interface PropsBase {
     /**
@@ -307,12 +310,17 @@ export interface PropsBase {
     /** Add the language tag to the container element. */
     lang?: HTMLDivElement["lang"];
     /**
-     * The date-fns locale object used to localize dates.
+     * The locale object used to localize dates. Pass a locale from `date-fns` to
+     * localize the calendar.
+     *
+     * @example
+     *   import { es } from "date-fns/locale";
+     *   <DayPicker locale={es} />
      *
-     * @defaultValue en-US
+     * @defaultValue enUS - The English locale default of `date-fns`.
      * @see https://daypicker.dev/docs/localization
      */
-    locale?: Locale | undefined;
+    locale?: Partial<Locale> | undefined;
     /**
      * The index of the first day of the week (0 - Sunday). Overrides the locale's
      * one.
@@ -436,7 +444,7 @@ export interface PropsSingleRequired {
     mode: "single";
     required: true;
     /** The selected date. */
-    selected: Date;
+    selected: Date | undefined;
     /** Event handler when a day is selected. */
     onSelect?: (selected: Date, triggerDate: Date, modifiers: Modifiers, e: React.MouseEvent | React.KeyboardEvent) => void | undefined;
 }
@@ -462,7 +470,7 @@ export interface PropsMultiRequired {
     mode: "multiple";
     required: true;
     /** The selected dates. */
-    selected: Date[];
+    selected: Date[] | undefined;
     /** Event handler when days are selected. */
     onSelect?: (selected: Date[], triggerDate: Date, modifiers: Modifiers, e: React.MouseEvent | React.KeyboardEvent) => void;
     /** The minimum number of selectable days. */
@@ -503,7 +511,7 @@ export interface PropsRangeRequired {
      */
     excludeDisabled?: boolean | undefined;
     /** The selected range. */
-    selected: DateRange;
+    selected: DateRange | undefined;
     /** Event handler when a range is selected. */
     onSelect?: (selected: DateRange, triggerDate: Date, modifiers: Modifiers, e: React.MouseEvent | React.KeyboardEvent) => void;
     /** The minimum number of days to include in the range. */

package/dist/esm/useCalendar.d.ts

@@ -45,4 +45,4 @@ export interface Calendar {
     goToDay: (day: CalendarDay) => void;
 }
 /** @private */
-export declare function useCalendar(props: DayPickerProps, dateLib: DateLib): Calendar;
+export declare function useCalendar(props: Pick<DayPickerProps, "captionLayout" | "endMonth" | "startMonth" | "today" | "fixedWeeks" | "ISOWeek" | "weekStartsOn" | "numberOfMonths" | "disableNavigation" | "onMonthChange" | "month" | "defaultMonth" | "fromMonth" | "fromYear" | "toMonth" | "toYear">, dateLib: DateLib): Calendar;

package/dist/esm/useCalendar.js

@@ -1,3 +1,4 @@
+import { useEffect, useState } from "react";
 import { getDates } from "./helpers/getDates.js";
 import { getDays } from "./helpers/getDays.js";
 import { getDisplayMonths } from "./helpers/getDisplayMonths.js";
@@ -7,14 +8,37 @@ import { getNavMonths } from "./helpers/getNavMonth.js";
 import { getNextMonth } from "./helpers/getNextMonth.js";
 import { getPreviousMonth } from "./helpers/getPreviousMonth.js";
 import { getWeeks } from "./helpers/getWeeks.js";
-import { useControlledValue } from "./helpers/useControlledValue.js";
 /** @private */
 export function useCalendar(props, dateLib) {
+    const { fromYear, toYear, startMonth, endMonth, today, numberOfMonths, month, defaultMonth } = props;
     const [navStart, navEnd] = getNavMonths(props, dateLib);
     const { startOfMonth, endOfMonth } = dateLib;
     const initialDisplayMonth = getInitialMonth(props, dateLib);
     // The first month displayed in the calendar
-    const [firstMonth, setFirstMonth] = useControlledValue(initialDisplayMonth, props.month ? startOfMonth(props.month) : undefined);
+    const [firstMonth, setFirstMonth] = useState(initialDisplayMonth);
+    useEffect(() => {
+        const initialDisplayMonth = getInitialMonth({
+            fromYear,
+            toYear,
+            startMonth,
+            endMonth,
+            month,
+            defaultMonth,
+            today,
+            numberOfMonths
+        }, dateLib);
+        setFirstMonth(initialDisplayMonth);
+    }, [
+        dateLib,
+        defaultMonth,
+        endMonth,
+        fromYear,
+        month,
+        numberOfMonths,
+        startMonth,
+        toYear,
+        today
+    ]);
     /** The months displayed in the calendar. */
     const displayMonths = getDisplayMonths(firstMonth, navEnd, props, dateLib);
     /** The dates displayed in the calendar. */

package/dist/esm/useCalendar.js.map

@@ -1 +1 @@
-{"version":3,"file":"useCalendar.js","sourceRoot":"","sources":["../../src/useCalendar.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useCalendar.js","sourceRoot":"","sources":["../../src/useCalendar.ts"],"names":[],"mappings":"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"}

package/dist/esm/useDayPicker.d.ts

@@ -3,6 +3,7 @@ import { CalendarMonth } from "./classes/CalendarMonth.js";
 import type { DayPickerProps } from "./types/props.js";
 import type { SelectedValue, SelectHandler } from "./types/selection.js";
 import { Modifiers } from "./types/shared.js";
+/** @private */
 export declare const dayPickerContext: import("react").Context<DayPickerContext<DayPickerProps> | undefined>;
 export type DayPickerContext<T extends DayPickerProps> = {
     /** The months displayed in the calendar. */

package/dist/esm/useDayPicker.js

@@ -1,5 +1,5 @@
 import { createContext, useContext } from "react";
-// Create a context with a default value
+/** @private */
 export const dayPickerContext = createContext(undefined);
 /**
  * Return the context to work with `<DayPicker />` inside custom components.

package/dist/esm/useDayPicker.js.map

@@ -1 +1 @@
-{"version":3,"file":"useDayPicker.js","sourceRoot":"","sources":["../../src/useDayPicker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAQlD,wCAAwC;AACxC,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAE3C,SAAS,CAAC,CAAC;AAqBb;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAA2B,KAAS;IAC9D,MAAM,OAAO,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAC7C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,OAA8B,CAAC;AACxC,CAAC"}
+{"version":3,"file":"useDayPicker.js","sourceRoot":"","sources":["../../src/useDayPicker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAQlD,eAAe;AACf,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAE3C,SAAS,CAAC,CAAC;AAqBb;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAA2B,KAAS;IAC9D,MAAM,OAAO,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAC7C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,OAA8B,CAAC;AACxC,CAAC"}

package/examples/SingleRequired.tsx

@@ -3,7 +3,7 @@ import React, { useState } from "react";
 import { DayPicker } from "react-day-picker";
 
 export function SingleRequired() {
-  const [selectedDay, setSelectedDay] = useState<Date>(new Date());
+  const [selectedDay, setSelectedDay] = useState<Date>();
 
   return (
     <DayPicker

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-day-picker",
-  "version": "9.0.6",
+  "version": "9.0.7",
   "description": "Customizable Date Picker for React",
   "author": "Giampaolo Bellavite <io@gpbl.dev>",
   "homepage": "https://daypicker.dev",
@@ -141,7 +141,7 @@
     "@testing-library/user-event": "^14.5.2",
     "@trivago/prettier-plugin-sort-imports": "^4.3.0",
     "@types/jest": "^29.5.12",
-    "@types/node": "^22.0.0",
+    "@types/node": "^22.1.0",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "@typescript-eslint/eslint-plugin": "^7.18.0",
@@ -152,7 +152,7 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-import-resolver-typescript": "^3.6.1",
     "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-jest": "^28.6.0",
+    "eslint-plugin-jest": "^28.7.0",
     "eslint-plugin-prettier": "^5.2.1",
     "eslint-plugin-react": "^7.35.0",
     "eslint-plugin-react-hooks": "^4.6.2",
@@ -166,7 +166,7 @@
     "react": "^18.3.1",
     "react-classnaming": "^0.16.4",
     "react-dom": "^18.3.1",
-    "ts-jest": "^29.2.3",
+    "ts-jest": "^29.2.4",
     "ts-node": "^10.9.2",
     "tslib": "^2.6.3",
     "typescript": "~5.5.4",

package/src/DayPicker.test.tsx

@@ -1,7 +1,7 @@
 import React from "react";
 
-import { fireEvent, render, screen } from "@testing-library/react";
-import { startOfDay, startOfMonth } from "date-fns";
+import { addMonths, startOfDay, startOfMonth } from "date-fns";
+import { defaultLocale } from "react-day-picker";
 
 import {
   activeElement,
@@ -10,11 +10,13 @@ import {
   nav,
   previousButton
 } from "@/test/elements";
+import { fireEvent, render, screen } from "@/test/render";
 import { user } from "@/test/user";
 
 import { DayPicker } from "./DayPicker";
 import { MonthProps } from "./components/Month";
 import { MonthsProps } from "./components/Months";
+import { labelGrid } from "./labels";
 
 const testId = "test";
 const dayPicker = () => screen.getByTestId(testId);
@@ -24,14 +26,14 @@ test("should render a date picker component", () => {
   expect(dayPicker()).toBeInTheDocument();
 });
 
-it("should render the navigation and month grids", () => {
+test("render the navigation and month grids", () => {
   render(<DayPicker data-testid={testId} />);
 
   expect(nav()).toBeInTheDocument();
   expect(grid()).toBeInTheDocument();
 });
 
-it("should apply classnames and style according to props", () => {
+test("apply classnames and style according to props", () => {
   render(
     <DayPicker
       data-testid={testId}
@@ -47,7 +49,7 @@ it("should apply classnames and style according to props", () => {
   expect(dayPicker()).toHaveStyle({ color: "red" });
 });
 
-it("should use custom components", () => {
+test("use custom components", () => {
   render(
     <DayPicker
       data-testid={testId}
@@ -131,3 +133,45 @@ describe("when a day is mouse entered", () => {
     expect(handleDayMouseLeave).toHaveBeenCalled();
   });
 });
+
+describe("when the `month` is changed programmatically", () => {
+  test("should update the calendar to reflect the new month", async () => {
+    const initialMonth = new Date(2023, 0, 1); // January 2023
+    const newMonth = new Date(2023, 1, 1); // February 2023
+    const { rerender } = render(
+      <DayPicker month={initialMonth} mode="single" />
+    );
+    expect(grid("January 2023")).toBeInTheDocument();
+    rerender(<DayPicker month={newMonth} mode="single" />);
+    expect(grid("February 2023")).toBeInTheDocument();
+  });
+});
+
+describe("when the `startMonth` is changed programmatically", () => {
+  test("should update the calendar to reflect the new month", async () => {
+    const initialStartMonth = new Date();
+    const newStartMonth = addMonths(new Date(), 2);
+    const { rerender } = render(
+      <DayPicker startMonth={initialStartMonth} mode="single" />
+    );
+    expect(grid(labelGrid(initialStartMonth))).toBeInTheDocument();
+    rerender(<DayPicker startMonth={newStartMonth} mode="single" />);
+    expect(grid(labelGrid(newStartMonth))).toBeInTheDocument();
+  });
+});
+
+test("extends the default locale", () => {
+  render(
+    <DayPicker
+      month={new Date(2024, 0)}
+      locale={{
+        localize: {
+          ...defaultLocale.localize,
+          month: () => "bar"
+        }
+      }}
+    />
+  );
+  // Check if the custom month name is rendered
+  expect(grid("bar 2024")).toBeInTheDocument();
+});

package/src/DayPicker.tsx

@@ -20,6 +20,7 @@ import { getWeekdays } from "./helpers/getWeekdays.js";
 import { getYearOptions } from "./helpers/getYearOptions.js";
 import * as defaultLabels from "./labels/index.js";
 import type { FormatOptions, LabelOptions } from "./lib/dateLib.js";
+import { enUS } from "./lib/locales.js";
 import type {
   DayPickerProps,
   Modifiers,
@@ -43,27 +44,29 @@ import { isDateRange } from "./utils/typeguards.js";
  * @see https://daypicker.dev
  */
 export function DayPicker(props: DayPickerProps) {
-  const { components, formatters, labels, dateLib, classNames } = useMemo(
-    () => ({
-      dateLib: getDateLib(props.dateLib),
-      components: getComponents(props.components),
-      formatters: getFormatters(props.formatters),
-      labels: { ...defaultLabels, ...props.labels },
-      classNames: { ...getDefaultClassNames(), ...props.classNames }
-    }),
-    [
-      props.classNames,
-      props.components,
-      props.dateLib,
-      props.formatters,
-      props.labels
-    ]
-  );
+  const { components, formatters, labels, dateLib, locale, classNames } =
+    useMemo(
+      () => ({
+        dateLib: getDateLib(props.dateLib),
+        components: getComponents(props.components),
+        formatters: getFormatters(props.formatters),
+        labels: { ...defaultLabels, ...props.labels },
+        locale: { ...enUS, ...props.locale },
+        classNames: { ...getDefaultClassNames(), ...props.classNames }
+      }),
+      [
+        props.classNames,
+        props.components,
+        props.dateLib,
+        props.formatters,
+        props.labels,
+        props.locale
+      ]
+    );
 
   const {
     captionLayout,
     firstWeekContainsDate,
-    locale,
     mode,
     onDayBlur,
     onDayClick,

package/src/index.ts

@@ -13,3 +13,5 @@ export * from "./utils/index.js";
 export * from "./UI.js";
 
 export * from "./useDayPicker.js";
+
+export { enUS as defaultLocale } from "./lib/locales.js";

package/src/selection/useMulti.tsx

@@ -22,14 +22,7 @@ export function useMulti<T extends DayPickerProps>(
     initiallySelected
   );
 
-  const { isSameDay, Date } = dateLib;
-
-  // Update the selected date if the required flag is set.
-  React.useEffect(() => {
-    if (required && selected === undefined) {
-      setSelected([new Date()]);
-    }
-  }, [required, selected, Date, mode]);
+  const { isSameDay } = dateLib;
 
   // Update the selected date if the selected value from props changes.
   React.useEffect(() => {

package/src/selection/useRange.tsx

@@ -16,7 +16,6 @@ export function useRange<T extends DayPickerProps>(
   dateLib: DateLib
 ): Selection<T> {
   const {
-    mode,
     disabled,
     excludeDisabled,
     selected: initiallySelected,
@@ -28,13 +27,6 @@ export function useRange<T extends DayPickerProps>(
     initiallySelected
   );
 
-  // Update the selected date if the required flag is set.
-  React.useEffect(() => {
-    if (required && selected === undefined) {
-      setSelected({ from: undefined, to: undefined });
-    }
-  }, [required, selected, mode]);
-
   // Update the selected date if the `selected` prop changes.
   React.useEffect(() => {
     setSelected(initiallySelected);

package/src/selection/useSingle.tsx

@@ -23,21 +23,14 @@ export function useSingle<T extends DayPickerProps>(
   const {
     selected: initiallySelected,
     required,
-    onSelect,
-    mode
+    onSelect
   } = props as PropsSingle;
 
   const [selected, setSelected] = React.useState<Date | undefined>(
     initiallySelected
   );
 
-  const { isSameDay, Date, startOfDay } = dateLib;
-  // Update the selected date if the required flag is set.
-  React.useEffect(() => {
-    if (required && selected === undefined) {
-      setSelected(startOfDay(new Date()));
-    }
-  }, [required, selected, Date, startOfDay, mode]);
+  const { isSameDay } = dateLib;
 
   // Update the selected date if the `selected` value changes.
   React.useEffect(() => {

package/src/types/props.test.tsx

@@ -2,6 +2,8 @@ import React from "react";
 
 import { DayPicker } from "../DayPicker";
 
+import { DateRange } from "./shared";
+
 const Test = () => {
   return (
     <>
@@ -23,15 +25,20 @@ const Test = () => {
         required
         onSelect={(date: Date | undefined) => {}}
       />
-      {/* @ts-expect-error selected should not be undefined. */}
+      {/* Allow undefined as initial selected value */}
       <DayPicker mode="single" required selected={undefined} />
       <DayPicker
         mode="multiple"
-        required={true}
-        // @ts-expect-error Missing `selected`
+        required
         selected={undefined}
         onSelect={(selected: Date[], date: Date, modifiers) => {}}
       />
+      <DayPicker
+        mode="range"
+        required
+        selected={undefined}
+        onSelect={(selected: DateRange, date: Date, modifiers) => {}}
+      />
       <DayPicker
         mode="multiple"
         required={false}

package/src/types/props.ts

@@ -37,8 +37,11 @@ export type DayPickerProps = PropsBase &
   );
 
 /**
- * Props used for customization of the calendar, localization, and event
- * handling.
+ * Props for customizing the calendar, handling localization, and managing
+ * events. These exclude the selection mode props.
+ *
+ * @group DayPicker
+ * @see https://daypicker.dev/api/interfaces/PropsBase
  */
 export interface PropsBase {
   /**
@@ -335,12 +338,17 @@ export interface PropsBase {
   /** Add the language tag to the container element. */
   lang?: HTMLDivElement["lang"];
   /**
-   * The date-fns locale object used to localize dates.
+   * The locale object used to localize dates. Pass a locale from `date-fns` to
+   * localize the calendar.
+   *
+   * @example
+   *   import { es } from "date-fns/locale";
+   *   <DayPicker locale={es} />
    *
-   * @defaultValue en-US
+   * @defaultValue enUS - The English locale default of `date-fns`.
    * @see https://daypicker.dev/docs/localization
    */
-  locale?: Locale | undefined;
+  locale?: Partial<Locale> | undefined;
   /**
    * The index of the first day of the week (0 - Sunday). Overrides the locale's
    * one.
@@ -470,7 +478,7 @@ export interface PropsSingleRequired {
   mode: "single";
   required: true;
   /** The selected date. */
-  selected: Date;
+  selected: Date | undefined;
   /** Event handler when a day is selected. */
   onSelect?: (
     selected: Date,
@@ -506,7 +514,7 @@ export interface PropsMultiRequired {
   mode: "multiple";
   required: true;
   /** The selected dates. */
-  selected: Date[];
+  selected: Date[] | undefined;
   /** Event handler when days are selected. */
   onSelect?: (
     selected: Date[],
@@ -557,7 +565,7 @@ export interface PropsRangeRequired {
    */
   excludeDisabled?: boolean | undefined;
   /** The selected range. */
-  selected: DateRange;
+  selected: DateRange | undefined;
   /** Event handler when a range is selected. */
   onSelect?: (
     selected: DateRange,

package/src/useCalendar.ts

@@ -1,3 +1,5 @@
+import { useEffect, useState } from "react";
+
 import type {
   CalendarWeek,
   CalendarDay,
@@ -12,7 +14,6 @@ import { getNavMonths } from "./helpers/getNavMonth.js";
 import { getNextMonth } from "./helpers/getNextMonth.js";
 import { getPreviousMonth } from "./helpers/getPreviousMonth.js";
 import { getWeeks } from "./helpers/getWeeks.js";
-import { useControlledValue } from "./helpers/useControlledValue.js";
 import type { DayPickerProps } from "./types/props.js";
 import type { DateLib } from "./types/shared.js";
 
@@ -64,7 +65,39 @@ export interface Calendar {
 }
 
 /** @private */
-export function useCalendar(props: DayPickerProps, dateLib: DateLib): Calendar {
+export function useCalendar(
+  props: Pick<
+    DayPickerProps,
+    | "captionLayout"
+    | "endMonth"
+    | "startMonth"
+    | "today"
+    | "fixedWeeks"
+    | "ISOWeek"
+    | "weekStartsOn"
+    | "numberOfMonths"
+    | "disableNavigation"
+    | "onMonthChange"
+    | "month"
+    | "defaultMonth"
+    // Deprecated:
+    | "fromMonth"
+    | "fromYear"
+    | "toMonth"
+    | "toYear"
+  >,
+  dateLib: DateLib
+): Calendar {
+  const {
+    fromYear,
+    toYear,
+    startMonth,
+    endMonth,
+    today,
+    numberOfMonths,
+    month,
+    defaultMonth
+  } = props;
   const [navStart, navEnd] = getNavMonths(props, dateLib);
 
   const { startOfMonth, endOfMonth } = dateLib;
@@ -72,10 +105,34 @@ export function useCalendar(props: DayPickerProps, dateLib: DateLib): Calendar {
   const initialDisplayMonth = getInitialMonth(props, dateLib);
 
   // The first month displayed in the calendar
-  const [firstMonth, setFirstMonth] = useControlledValue(
-    initialDisplayMonth,
-    props.month ? startOfMonth(props.month) : undefined
-  );
+  const [firstMonth, setFirstMonth] = useState(initialDisplayMonth);
+
+  useEffect(() => {
+    const initialDisplayMonth = getInitialMonth(
+      {
+        fromYear,
+        toYear,
+        startMonth,
+        endMonth,
+        month,
+        defaultMonth,
+        today,
+        numberOfMonths
+      },
+      dateLib
+    );
+    setFirstMonth(initialDisplayMonth);
+  }, [
+    dateLib,
+    defaultMonth,
+    endMonth,
+    fromYear,
+    month,
+    numberOfMonths,
+    startMonth,
+    toYear,
+    today
+  ]);
 
   /** The months displayed in the calendar. */
   const displayMonths = getDisplayMonths(firstMonth, navEnd, props, dateLib);

package/src/useDayPicker.ts

@@ -6,7 +6,7 @@ import type { DayPickerProps } from "./types/props.js";
 import type { SelectedValue, SelectHandler } from "./types/selection.js";
 import { Modifiers } from "./types/shared.js";
 
-// Create a context with a default value
+/** @private */
 export const dayPickerContext = createContext<
   DayPickerContext<DayPickerProps> | undefined
 >(undefined);

package/website/docs/docs/localization.mdx

@@ -41,6 +41,27 @@ import { es } from "date-fns/locale";
   <Examples.Spanish />
 </BrowserWindow>
 
+:::tip Customizing the Locale
+
+You can customize the locale by passing an object with the desired translations. Use the `defaultLocale` object for the default translations.
+
+```tsx
+import { DayPicker, defaultLocale } from "react-day-picker";
+
+<DayPicker
+  locale={{
+    localize: {
+      ...defaultLocale.localize,
+      day: (day) => "custom-localized-day"
+    }
+  }}
+  month={new Date(2023, 0, 1)}
+  mode="single"
+/>;
+```
+
+:::
+
 ## First Date of the Week
 
 Use the `weekStartsOn` prop to specify the starting day of the week.