Merge branch 'main' of github.com:gpbl/react-day-picker

# Conflicts:
#	website/docs/upgrading.mdx

src/types-deprecated.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { Calendar } from "./components/Calendar";
-import { MonthCaption } from "./components/MonthCaption";
+import { MonthCaption, MonthCaptionProps } from "./components/MonthCaption";
 import { Week, type WeekProps } from "./components/Week";
 import { useCalendar } from "./contexts/calendar";
 import { PropsContext, useProps } from "./contexts/props";
@@ -44,11 +44,10 @@ export const Root = Calendar;
 export const Caption = MonthCaption;
 
 /**
- * @deprecated This type has been renamed. Use `Parameters<typeof
- *   MonthCaption>[0]` instead.
+ * @deprecated This type has been renamed. Use `MonthCaptionProps` instead.
  * @protected
  */
-export type CaptionProps = Parameters<typeof MonthCaption>[0];
+export type CaptionProps = MonthCaptionProps;
 
 /**
  * @deprecated This component has been removed.
@@ -134,22 +133,21 @@ export type SelectRangeEventHandler = SelectHandler<"range", false>;
 export type DayPickerProviderProps = any;
 
 /**
- * @deprecated This type has been renamed to `useProps`
+ * @deprecated This type has been renamed to `useProps`.
  * @protected
  * @group Hooks
  */
 export const useDayPicker = useProps;
 
 /**
- * @deprecated This type has been renamed to `useProps`
+ * @deprecated This type has been renamed to `useProps`.
  * @protected
  * @group Hooks
  */
 export const useNavigation = useCalendar;
 
 /**
- * @deprecated This hook has been removed. To customize the rendering of a day,
- *   use the `htmlAttributes` prop in a custom `Day` component.
+ * @deprecated This hook has been removed. Use a custom `Day` component instead.
  * @protected
  * @group Hooks
  * @see https://react-day-picker.js.org/advanced-guides/custom-components
@@ -187,53 +185,50 @@ export type WeekdayLabel = typeof labelWeekday;
 export type WeekNumberLabel = typeof labelWeekNumber;
 
 /**
- * @deprecated The event handler when a day is clicked. Use
- *   {@link DayMouseEventHandler} instead.
+ * @deprecated Use {@link DayMouseEventHandler} instead.
  * @protected
  */
 export type DayClickEventHandler = DayEventHandler<React.MouseEvent>;
 
 /**
- * @deprecated The event handler when a day is focused. This type will be
- *   removed. Use `DayEventHandler<React.FocusEvent | React.KeyboardEvent>`
- *   instead.
+ * @deprecated This type will be removed. Use `DayEventHandler<React.FocusEvent
+ *   | React.KeyboardEvent>` instead.
  * @protected
  */
 export type DayFocusEventHandler = DayEventHandler<
   React.FocusEvent | React.KeyboardEvent
 >;
 
 /**
- * @deprecated The event handler when a day gets a keyboard event. This type
- *   will be removed. Use `DayEventHandler<React.KeyboardEvent>` instead.
+ * @deprecated This type will be removed. Use
+ *   `DayEventHandler<React.KeyboardEvent>` instead.
  * @protected
  */
 export type DayKeyboardEventHandler = DayEventHandler<React.KeyboardEvent>;
 
 /**
- * @deprecated The event handler when a day gets a mouse event. This type will
- *   be removed. Use `DayEventHandler<React.MouseEvent>` instead.
+ * @deprecated This type will be removed. Use
+ *   `DayEventHandler<React.MouseEvent>` instead.
  * @protected
  */
 export type DayMouseEventHandler = DayEventHandler<React.MouseEvent>;
 
 /**
- * @deprecated The event handler when a day gets a pointer event. This type will
- *   be removed. Use `DayEventHandler<React.PointerEvent>` instead.
+ * @deprecated This type will be removed. Use
+ *   `DayEventHandler<React.PointerEvent>` instead.
  * @protected
  */
 export type DayPointerEventHandler = DayEventHandler<React.PointerEvent>;
 
 /**
- * @deprecated The event handler when a day gets a touch event. This type will
- *   be removed. Use `DayEventHandler<React.TouchEvent>` instead.
+ * @deprecated This type will be removed. Use
+ *   `DayEventHandler<React.TouchEvent>` instead.
  * @protected
  */
 export type DayTouchEventHandler = DayEventHandler<React.TouchEvent>;
 
 /**
- * @deprecated The type has been renamed and needs a `Mode` argument. Use
- *   `PropsContext` instead.
+ * @deprecated The type has been renamed. Use `PropsContext` instead.
  * @protected
  */
 export type DayPickerContext = PropsContext;

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

@@ -4,18 +4,24 @@ sidebar_position: 4
 
 # Custom Components
 
-Use the `components` prop to swap the components used to render DayPicker. A list of the components that can be customized is available in the [Components Reference](../api#components).
+Use the `components` prop to swap the components used to render DayPicker.
 
-:::tip Advanced Feature
+:::warning Advanced Feature
 
-- Custom components may not have a stable API yet and may break in a next release.
-- Get familiar with the [API reference](../api#components) and the [DayPicker Anatomy](../using-daypicker/anatomy.mdx) first.
+- This feature requires basic understanding of the output generated by DayPicker.
+- Get familiar with the [API Reference](../api#components) and the [DayPicker Anatomy](../using-daypicker/anatomy.mdx) first.
+- Make sure you don't break [accessibility](../using-daypicker/accessibility.mdx) when customizing components.
+- Custom components may not have a stable API yet and may break in a minor release.
 
-:::
+  :::
 
----
+## List of Custom Components
+
+See the [Components API Reference](../api#components) for a list of components you can customize.
 
-For example, if you need to customize the component displaying the date, you can replace the `Day` component with a custom implementation.
+## Example: Custom DayDate component
+
+For example, if you need to customize the component displaying the date, replace the [`DayDate`](../api/functions//DayDate.md) component:
 
 ```tsx title="./CustomDayDate.tsx"
 import { DayPicker, type DayDateProps } from "react-day-picker";
@@ -38,6 +44,28 @@ export function MyDatePicker() {
   <Examples.CustomDayDate />
 </BrowserWindow>
 
+### Extending the Default Components
+
+You can also import the default components to add custom behavior. Just make sure you pass the default component to the root.
+
+For example, to add a custom class to the `Day` component:
+
+```tsx title="./CustomDay.tsx"
+import { DayPicker, Day, type DayProps } from "react-day-picker";
+
+function CustomDay(props: DayProps) {
+  return (
+    <Day {...props}>
+      <div className="custom-day">{props.children}</div>
+    </Day>
+  );
+}
+
+export function MyDatePicker() {
+  return <DayPicker components={{ Day: CustomDay }} />;
+}
+```
+
 ## DayPicker Hooks
 
 When creating custom components, you will find useful the [DayPicker hooks](../api/index.md#hooks). These utilities provide access to the internal state and methods of the DayPicker component.