docs: improve docs for selection modes, Modifiers

gpbl · Sep 22, 2024 · afb1f21 · afb1f21
1 parent cfd4075
commit afb1f21
Show file tree

Hide file tree

Showing 3 changed files with 48 additions and 27 deletions.
diff --git a/src/types/props.ts b/src/types/props.ts
@@ -485,7 +485,16 @@ export interface PropsBase {
  onDayTouchStart?: DayEventHandler<React.TouchEvent>;
 }
 
-/** Shared handler type for onSelect events */
+/**
+ * Shared handler type for `onSelect` callback when a selection mode is set.
+ *
+ * @template T - The type of the selected item.
+ * @callback OnSelectHandler
+ * @param {T} selected - The selected item after the event.
+ * @param {Date} triggerDate - The date when the event was triggered.
+ * @param {Modifiers} modifiers - The modifiers associated with the event.
+ * @param {React.MouseEvent | React.KeyboardEvent} e - The event object.
+ */
 export type OnSelectHandler<T> = (
  selected: T,
  triggerDate: Date,

diff --git a/src/types/shared.ts b/src/types/shared.ts
@@ -323,15 +323,27 @@ export type Styles = {
 };
 
 /**
- * The modifiers that are matching a day in the calendar.
+ * Represents the modifiers that match a specific day in the calendar.
+ *
+ * - Retrieve modifiers using the {@link OnSelectHandler} via the `onSelect` prop,
+ * or within custom components using the {@link useDayPicker} hook.
+ * - Includes built-in modifiers from {@link DayFlag} and {@link SelectionState}.
+ * - Add custom modifiers using the `modifiers` prop.
  *
  * @example
  * const modifiers: Modifiers = {
- * today: false, // the day is not today
- * selected: true, // the day is selected
- * weekend: false // the day is not in the weekend
- * // etc
+ * today: false, // the day is not today
+ * selected: true, // the day is selected
+ * disabled: false, // the day is not disabled
+ * outside: false, // the day is not outside the month
+ * focused: false, // the day is not focused
+ *
+ * weekend: false // custom modifier example for matching a weekend
+ * booked: true // custom modifier example for matching a booked day
+ * available: false // custom modifier example for matching an available day
  * };
+ *
+ * @see https://daypicker.dev/guides/custom-modifiers
  */
 export type Modifiers = Record<string, boolean>;
 

diff --git a/website/docs/docs/selection-modes.mdx b/website/docs/docs/selection-modes.mdx
@@ -18,7 +18,7 @@ The `mode` prop determines the selection mode. Use the `disabled` prop to preven
 | `disabled` | [`Matcher`](../api/type-aliases/Matcher.md) \| `Matcher[]` | Disabled days that cannot be selected. |
 | `selected` | `Date` \| `Date[]` \| [`DateRange`](../api/type-aliases/DateRange.md) \| `undefined` | The selected day(s). |
 | `required` | `boolean` | When `true`, the selection is required. |
-| `onSelect` | `(selected, triggerDate, modifiers, e) => void`  | Event callback when a date is selected. |
+| `onSelect` | [`OnSelectHandler`](../api/type-aliases/OnSelectHandler.md) | Event callback when a date is selected. |
 
 ## Single Mode
 
@@ -34,11 +34,11 @@ When the `mode` prop is set to `"single"`, only one day can be selected at a tim
 
 ### Single Mode Props
 
-| Prop Name | Type | Description |
-| ---------- | ----------------------------------------------- | --------------------------------------- |
-| `selected` | `Date \| undefined` | The selected date. |
-| `onSelect` | `(selected, triggerDate, modifiers, e) => void` | Event callback when a date is selected. |
-| `required` | `boolean` | Make the selection required. |
+| Prop Name | Type  | Description |
+| ---------- | ------------------------------------------------------------------------------ | --------------------------------------- |
+| `selected` | `Date \| undefined`  | The selected date. |
+| `onSelect` | [`OnSelectHandler<Date \| undefined>`](../api/type-aliases/OnSelectHandler.md) | Event callback when a date is selected. |
+| `required` | `boolean`  | Make the selection required. |
 
 ### Controlled Selections
 
@@ -81,13 +81,13 @@ Set the `mode` prop to `"multiple"` to enable the selection of multiple days in
 
 ### Multiple Mode Props
 
-| Prop Name | Type | Description |
-| ---------- | ---------------------------------------- | --------------------------------------- |
-| `selected` | `Date[] \| undefined` | The selected dates. |
-| `onSelect` | `(selected, date, 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. |
-| `required` | `boolean` | Make the selection required. |
+| Prop Name | Type  | Description |
+| ---------- | -------------------------------------------------------------------------------- | --------------------------------------- |
+| `selected` | `Date[] \| undefined`  | The selected dates. |
+| `onSelect` | [`OnSelectHandler<Date[] \| undefined>`](../api/type-aliases/OnSelectHandler.md) | 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. |
+| `required` | `boolean`  | Make the selection required. |
 
 Use the `selected` and `onSelect` props to manage the selected date:
 
@@ -139,14 +139,14 @@ Set the `mode` prop to `"range"` to enable the selection of a continuous range o
 
 ### 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. |
+| Prop Name | Type  | Description |
+| ----------------- | ----------------------------------------------------------------------------------- | --------------------------------------- |
+| `selected` | [`DateRange`](../api/type-aliases/DateRange.md)  | The selected range. |
+| `onSelect` | [`OnSelectHandler<DateRange \| undefined>`](../api/type-aliases/OnSelectHandler.md) | 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