chore: proofread and update jsdocs for consistency (#2760)

* chore: proofread and update jsdocs for consistency

Signed-off-by: Giampaolo Bellavite <[email protected]>

* Add jsdocs to components

Signed-off-by: Giampaolo Bellavite <[email protected]>

---------

Signed-off-by: Giampaolo Bellavite <[email protected]>

Author: gpbl

react-day-picker.code-workspace

@@ -5,7 +5,7 @@
       "orta.vscode-jest",
       "andys8.jest-snippets",
       "esbenp.prettier-vscode",
-      "streetsidesoftware.code-spell-checker",
+      "streetsidesoftware.code-spell-checker"
     ]
   },
   "folders": [
@@ -42,6 +42,9 @@
       "activityBar.inactiveForeground": "#d8d8d877",
       "activityBarBadge.background": "#dd006f",
       "activityBarBadge.foreground": "#e7e7e7"
+    },
+    "[typescript]": {
+      "editor.defaultFormatter": "esbenp.prettier-vscode"
     }
   }
 }

src/DayPicker.tsx

@@ -34,8 +34,10 @@ import { rangeIncludesDate } from "./utils/rangeIncludesDate.js";
 import { isDateRange } from "./utils/typeguards.js";
 
 /**
- * Render the date picker calendar.
+ * Renders the DayPicker calendar component.
  *
+ * @param initialProps - The props for the DayPicker component.
+ * @returns The rendered DayPicker component.
  * @group DayPicker
  * @see https://daypicker.dev
  */

src/UI.ts

@@ -3,11 +3,10 @@ import { CSSProperties } from "react";
 import type { CustomComponents, ClassNames, Styles } from "./types/index.js";
 
 /**
- * The UI elements composing DayPicker. These elements are mapped to
- * {@link CustomComponents}, the {@link ClassNames} and the {@link Styles} used by
- * DayPicker.
+ * Enum representing the UI elements composing DayPicker. These elements are
+ * mapped to {@link CustomComponents}, {@link ClassNames}, and {@link Styles}.
  *
- * Some of these elements are extended by flags and modifiers.
+ * Some elements are extended by flags and modifiers.
  */
 export enum UI {
   /** The root component displaying the months and the navigation bar. */
@@ -71,7 +70,7 @@ export enum UI {
   YearsDropdown = "years_dropdown"
 }
 
-/** The flags for the {@link UI.Day}. */
+/** Enum representing flags for the {@link UI.Day} element. */
 export enum DayFlag {
   /** The day is disabled. */
   disabled = "disabled",
@@ -86,8 +85,8 @@ export enum DayFlag {
 }
 
 /**
- * The state that can be applied to the {@link UI.Day} element when in selection
- * mode.
+ * Enum representing selection states that can be applied to the {@link UI.Day}
+ * element in selection mode.
  */
 export enum SelectionState {
   /** The day is at the end of a selected range. */
@@ -100,7 +99,6 @@ export enum SelectionState {
   selected = "selected"
 }
 
-/** CSS classes used for animating months and captions. */
 /**
  * Enum representing different animation states for transitioning between
  * months.
@@ -125,25 +123,15 @@ export enum Animation {
 }
 
 /**
- * Deprecated UI elements and flags.
+ * Deprecated UI elements and flags from previous versions of DayPicker.
  *
- * These elements were used in previous version of DayPicker and are kept here
- * to help the transition to the new {@link UI | UI elements}.
- *
- * ```diff
- *   <DayPicker classNames={{
- * -  cell: "my-cell",
- * +  day: "my-cell",
- * -  day: "my-day",
- * +  day_button: "my-day",
- * -  day_disabled: "my-day_disabled",
- * +  disabled: "my-day_disabled",
- *    // etc.
- *   }}/>
- * ```
+ * These elements are kept for backward compatibility and to assist in
+ * transitioning to the new {@link UI} elements.
  *
  * @deprecated
  * @since 9.0.1
+ * @template T - The type of the deprecated UI element (e.g., CSS class or
+ *   style).
  * @see https://daypicker.dev/upgrading
  * @see https://daypicker.dev/docs/styling
  */

src/classes/CalendarDay.ts

@@ -1,11 +1,11 @@
 import { type DateLib, defaultDateLib } from "./DateLib.js";
 
 /**
- * Represent the day displayed in the calendar.
+ * Represents a day displayed in the calendar.
  *
- * In DayPicker, a `Day` is a `Date` that can be displayed in the calendar. It
- * is used as extension of the native `Date` object to provide additional
- * information about the day.
+ * In DayPicker, a `CalendarDay` is a wrapper around a `Date` object that
+ * provides additional information about the day, such as whether it belongs to
+ * the displayed month.
  */
 export class CalendarDay {
   constructor(
@@ -22,35 +22,38 @@ export class CalendarDay {
   }
 
   /**
-   * The utility functions to manipulate dates.
+   * Utility functions for manipulating dates.
    *
    * @private
    */
   readonly dateLib: DateLib;
 
   /**
-   * Whether the day is not belonging to the displayed month.
+   * Indicates whether the day does not belong to the displayed month.
    *
-   * When `outside` is `true`, use `displayMonth` to know to which month the day
-   * belongs.
+   * If `outside` is `true`, use `displayMonth` to determine the month to which
+   * the day belongs.
    */
   readonly outside: boolean;
 
   /**
-   * The months where the day is displayed.
+   * The month that is currently displayed in the calendar.
    *
-   * In DayPicker, days can fall out the displayed months (e.g. when
-   * `showOutsideDays` is `true`). This property is useful to know if the day is
-   * in the same month of the displayed month.
+   * This property is useful for determining if the day belongs to the same
+   * month as the displayed month, especially when `showOutsideDays` is
+   * enabled.
    */
   readonly displayMonth: Date;
 
   /** The date represented by this day. */
   readonly date: Date;
 
   /**
-   * Check if the day is the same as the given day: considering if it is in the
-   * same display month.
+   * Checks if this day is equal to another `CalendarDay`, considering both the
+   * date and the displayed month.
+   *
+   * @param day The `CalendarDay` to compare with.
+   * @returns `true` if the days are equal, otherwise `false`.
    */
   isEqualTo(day: CalendarDay) {
     return (

src/classes/CalendarMonth.ts

@@ -1,15 +1,20 @@
 import { CalendarWeek } from "./CalendarWeek.js";
 
-/** Represent a month in a calendar year. Contains the weeks within the month. */
+/**
+ * Represents a month in a calendar year.
+ *
+ * A `CalendarMonth` contains the weeks within the month and the date of the
+ * month.
+ */
 export class CalendarMonth {
   constructor(month: Date, weeks: CalendarWeek[]) {
     this.date = month;
     this.weeks = weeks;
   }
 
-  /** The date of the month. */
+  /** The date representing the first day of the month. */
   date: Date;
 
-  /** The weeks within the month. */
+  /** The weeks that belong to this month. */
   weeks: CalendarWeek[];
 }

src/classes/CalendarWeek.ts

@@ -1,13 +1,19 @@
 import { CalendarDay } from "./CalendarDay.js";
 
-/** Represent a week in a calendar month. */
+/**
+ * Represents a week in a calendar month.
+ *
+ * A `CalendarWeek` contains the days within the week and the week number.
+ */
 export class CalendarWeek {
   constructor(weekNumber: number, days: CalendarDay[]) {
     this.days = days;
     this.weekNumber = weekNumber;
   }
+
   /** The number of the week within the year. */
   weekNumber: number;
-  /** The days within the week. */
+
+  /** The days that belong to this week. */
   days: CalendarDay[];
 }

src/classes/DateLib.ts

@@ -94,26 +94,26 @@ export interface DateLibOptions
 }
 
 /**
- * A wrapper class around [date-fns](http://date-fns.org) sharing the same
- * options.
+ * A wrapper class around [date-fns](http://date-fns.org) that provides utility
+ * methods for date manipulation and formatting.
  *
  * @since 9.2.0
  * @example
  *   const dateLib = new DateLib({ locale: es });
  *   const newDate = dateLib.addDays(new Date(), 5);
  */
 export class DateLib {
-  /** The options for the date library. */
+  /** The options for configuring the date library. */
   readonly options: DateLibOptions;
 
-  /** Overrides for the date library functions. */
+  /** Overrides for the default date library functions. */
   readonly overrides?: Partial<typeof DateLib.prototype>;
 
   /**
-   * Creates an instance of DateLib.
+   * Creates an instance of `DateLib`.
    *
-   * @param options The options for the date library.
-   * @param overrides Overrides for the date library functions.
+   * @param options Configuration options for the date library.
+   * @param overrides Custom overrides for the date library functions.
    */
   constructor(
     options?: DateLibOptions,
@@ -124,9 +124,11 @@ export class DateLib {
   }
 
   /**
-   * Generate digit map dynamically using Intl.NumberFormat.
+   * Generates a mapping of Arabic digits (0-9) to the target numbering system
+   * digits.
    *
    * @since 9.5.0
+   * @returns A record mapping Arabic digits to the target numerals.
    */
   private getDigitMap(): Record<string, string> {
     const { numerals = "latn" } = this.options;
@@ -146,21 +148,23 @@ export class DateLib {
   }
 
   /**
-   * Replace Arabic digits with the target numbering system digits.
+   * Replaces Arabic digits in a string with the target numbering system digits.
    *
    * @since 9.5.0
+   * @param input The string containing Arabic digits.
+   * @returns The string with digits replaced.
    */
   private replaceDigits(input: string): string {
     const digitMap = this.getDigitMap();
     return input.replace(/\d/g, (digit) => digitMap[digit] || digit);
   }
 
   /**
-   * Format number using the custom numbering system.
+   * Formats a number using the configured numbering system.
    *
    * @since 9.5.0
    * @param value The number to format.
-   * @returns The formatted number.
+   * @returns The formatted number as a string.
    */
   formatNumber(value: number | string): string {
     return this.replaceDigits(value.toString());
@@ -174,10 +178,10 @@ export class DateLib {
   Date: typeof Date = Date;
 
   /**
-   * Creates a new date object to the today's date.
+   * Creates a new `Date` object representing today's date.
    *
    * @since 9.5.0
-   * @returns The new date object.
+   * @returns A `Date` object for today's date.
    */
   today = (): Date => {
     if (this.overrides?.today) {
@@ -190,13 +194,13 @@ export class DateLib {
   };
 
   /**
-   * Creates a new date object with the specified year, month and date.
+   * Creates a new `Date` object with the specified year, month, and day.
    *
    * @since 9.5.0
    * @param year The year.
    * @param monthIndex The month (0-11).
    * @param date The day of the month.
-   * @returns The new date object.
+   * @returns A new `Date` object.
    */
   newDate = (year: number, monthIndex: number, date: number): Date => {
     if (this.overrides?.newDate) {

src/components/Day.tsx

@@ -4,11 +4,11 @@ import type { CalendarDay } from "../classes/index.js";
 import type { Modifiers } from "../types/index.js";
 
 /**
- * Render the gridcell of a day in the calendar and handle the interaction and
- * the focus with they day.
+ * Render a grid cell for a specific day in the calendar.
  *
- * If you need to just change the content of the day cell, consider swapping the
- * `DayButton` component instead.
+ * Handles interaction and focus for the day. If you only need to change the
+ * content of the day cell, consider swapping the `DayButton` component
+ * instead.
  *
  * @group Components
  * @see https://daypicker.dev/guides/custom-components

src/components/DayButton.tsx

@@ -4,7 +4,7 @@ import type { CalendarDay } from "../classes/index.js";
 import type { Modifiers } from "../types/index.js";
 
 /**
- * Render the button for a day in the calendar.
+ * Render a button for a specific day in the calendar.
  *
  * @group Components
  * @see https://daypicker.dev/guides/custom-components
@@ -13,7 +13,7 @@ export function DayButton(
   props: {
     /** The day to render. */
     day: CalendarDay;
-    /** The modifiers for the day. */
+    /** The modifiers to apply to the day. */
     modifiers: Modifiers;
   } & ButtonHTMLAttributes<HTMLButtonElement>
 ) {

src/components/Dropdown.tsx

@@ -9,23 +9,20 @@ export type DropdownOption = {
   value: number;
   /** The label of the option. */
   label: string;
-  /**
-   * The dropdown option is disabled when it cannot be selected because out of
-   * the calendar range.
-   */
+  /** Whether the dropdown option is disabled (e.g., out of the calendar range). */
   disabled: boolean;
 };
 
 /**
- * Render a dropdown component to use in the navigation bar.
+ * Render a dropdown component for navigation in the calendar.
  *
  * @group Components
  * @see https://daypicker.dev/guides/custom-components
  */
 export function Dropdown(
   props: {
     /**
-     * @deprecated Use{@link useDayPicker} hook to get the list of internal
+     * @deprecated Use {@link useDayPicker} hook to get the list of internal
      *   components.
      */
     components: CustomComponents;
@@ -34,6 +31,7 @@ export function Dropdown(
      *   class names.
      */
     classNames: ClassNames;
+    /** The options to display in the dropdown. */
     options?: DropdownOption[] | undefined;
   } & Omit<SelectHTMLAttributes<HTMLSelectElement>, "children">
 ) {