From 9d31c502b8a26c60803820e3bd26dd64b7e4d535 Mon Sep 17 00:00:00 2001
From: Lebaud Antoine <lebaud.antoine131@gmail.com>
Date: Mon, 24 Jul 2023 22:11:56 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D(react)=20document=20date=20picker?=
 =?UTF-8?q?=20utils=20functions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add some docstring documentation to the newly updated utils
functions, to help understand what are their role and params.
User have a clear view of inputs and outputs timezone.
---
 .../src/components/Forms/DatePicker/utils.ts  | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/packages/react/src/components/Forms/DatePicker/utils.ts b/packages/react/src/components/Forms/DatePicker/utils.ts
index d2f906f..c38e554 100644
--- a/packages/react/src/components/Forms/DatePicker/utils.ts
+++ b/packages/react/src/components/Forms/DatePicker/utils.ts
@@ -9,6 +9,11 @@ import {
 import { DateRange } from "react-aria";
 import { DatePickerAuxSubProps } from ":/components/Forms/DatePicker/DatePickerAux";
 
+/**
+ * Checks if a given time zone is valid and supported by the environment.
+ * @param timezone The time zone to validate.
+ * @returns true if the time zone is valid and supported, false otherwise.
+ */
 export const isValidTimeZone = (timezone: string) => {
   try {
     // Check if Intl is available and supports time zones
@@ -26,6 +31,13 @@ export const isValidTimeZone = (timezone: string) => {
   }
 };
 
+/**
+ * Parses an ISO 8601 date and time string with a UTC offset or in UTC.
+ * @param rawDate - The raw date string to parse.
+ * @param timezone - (Optional) The timezone to use for parsing. If not provided, the local timezone will be used.
+ * @returns The parsed ZonedDateTime object or undefined if the input date is undefined.
+ * @throws {Error} - If an invalid date or timezone format is encountered.
+ */
 export const parseDateValue = (
   rawDate: string | undefined,
   timezone?: string,
@@ -46,6 +58,12 @@ export const parseDateValue = (
   }
 };
 
+/**
+ * Parses a range of ISO 8601 date and time string with a UTC offset or in UTC.
+ * @param rawRange - The range of raw date strings to parse.
+ * @param timezone - (Optional) The timezone to use for parsing. If not provided, the local timezone will be used.
+ * @returns The parsed DateRange object or undefined if the input date range is undefined or uncomplete.
+ */
 export const parseRangeDateValue = (
   rawRange: [string, string] | undefined,
   timezone?: string,
@@ -59,6 +77,13 @@ export const parseRangeDateValue = (
   };
 };
 
+/**
+ * Converts a DateValue object to an ISO 8601 formatted string in UTC.
+ * @param date - The DateValue object to convert.
+ * @param timezone - (Optional) The timezone to use for the conversion. If not provided, the local timezone will be used.
+ * @returns The string representation of the date or an empty string if the input date is null.
+ * @throws {Error} - If an invalid date or timezone format is encountered.
+ */
 export const convertDateValueToString = (
   date: DateValue | null,
   timezone?: string,