@leapdevuk/component-toolbox 0.0.127 → 0.0.129

package/dist/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.0.128 (2025-07-16)
+
+### Documentation
+
+- Developer documentation add to date and time based Utility functions
+
 ## 0.0.127 (2025-07-16)
 
 ### Features

package/dist/components/datepicker/index.d.ts

@@ -1,10 +1,10 @@
 export { default as LCTDatePicker } from './DatePicker';
+export { dbDateOnlyFormat as lctDbDateOnlyFormat } from './utils';
+export { formatAsDBDate as lctFormatAsDBDate } from './utils';
 export { formatDate as lctFormatDate } from './utils';
-export { lctFormatDateTime as lctFormatDateTime } from '../datepicker/utils';
+export { formatDateTime as lctFormatDateTime } from './utils';
 export { formatReportDate as lctFormatReportDate } from './utils';
+export { convertLocalDateToUTCDateTime as lctConvertLocalDateToUTCDateTime } from './utils';
 export { getLocale as lctGetLocale } from './utils';
 export { parseDate as lctParseDate } from './utils';
 export { utcFormat as lctUTCFormat } from './utils';
-export { dbDateOnlyFormat as lctDbDateOnlyFormat } from './utils';
-export { formatAsDBDate as lctFormatAsDBDate } from './utils';
-export { getFormattedLocalDateTime as lctGetFormattedLocalDateTime } from './utils';

package/dist/components/datepicker/utils.d.ts

@@ -1,134 +1,204 @@
 import { Api, LeapContext } from '@leapdev/leap-host';
 import { Locale } from 'date-fns';
+/**
+ * This constant defines the date format used for database storage.
+ * It is used to ensure consistent date formatting across the application,
+ * especially when interacting with databases or APIs that require a specific date format.
+ */
+export declare const dbDateOnlyFormat = "yyyy-MM-dd";
+/**
+ * This constant defines the default date format used in the application.
+ * It is used for displaying dates in the user interface and for formatting dates in various components.
+ */
 export declare const defaultDateFormat = "dd/MM/yyyy";
+/**
+ * This constant defines the default date and time format used in the application.
+ * It is used for displaying both date and time in the user interface and for formatting datetime values
+ */
 export declare const defaultDateTimeFormat = "yyyy-MM-dd HH:mm:ss";
+/**
+ * This constant defines the minimum date that can be used in the application.
+ * It is set to January 1, 1900, and is used to ensure that date inputs do not go below this value.
+ * It is useful for setting a minimum date in date pickers or other date-related components.
+ */
 export declare const minDateAsObject: Date;
+/**
+ * This constant defines the timezone used in the application.
+ * It is derived from the user's system settings and is used for formatting dates and times in the user's local timezone.
+ * It ensures that date and time values are displayed correctly based on the user's timezone.
+ */
 export declare const timezone: string;
+/**
+ * This constant defines the UTC format used for date and time values in the application.
+ * It is used to ensure that date and time values are stored and displayed in a consistent UTC format.
+ */
 export declare const utcFormat = "yyyy-MM-dd HH:mm:ss";
-export declare const dbDateOnlyFormat = "yyyy-MM-dd";
 /**
- *  This function returns the minimum date as a string formatted in the default date format.
- *  It is useful for setting a minimum date in date pickers or other date-related components.
- *  @returns (string): The minimum date formatted as a string in the default date format.
- *  @example
- *  ```typescript
+ * This function returns the minimum date as a string formatted in the default date format.
+ * It is useful for setting a minimum date in date pickers or other date-related components.
+ * @returns (string): The minimum date formatted as a string in the default date format.
+ * @example
+ * ```typescript
  *    const minDate = getMinDate(); // Returns "01/01/1900"
- *  ```
+ * ```
  */
 export declare const minDate: string;
+/**
+ * This function returns a date that is one week from today, formatted as a string.
+ * It is useful for scenarios where you need to calculate a date one week in the future,
+ * such as setting deadlines or reminders.
+ * @returns (string): A formatted date string representing one week from today.
+ * It can be used in various contexts, such as displaying future dates in a user interface or calculating due dates.
+ * @example
+ * ```typescript
+ *    const oneWeekFromToday = getOneWeekFromToday(); // Returns "dd/MM/yyyy" format of the date one week from today
+ * ```
+ */
 export declare const oneWeek: string;
+/**
+ * This function returns today's date formatted as a string in the default date format.
+ * It is useful for displaying the current date in a user interface or for date calculations.
+ * @returns (string): Today's date formatted as a string in the default date format.
+ * It can be used in various contexts, such as displaying the current date in a user interface or calculating date differences.
+ * @example
+ * ```typescript
+ *    const todayDate = getTodayDate(); // Returns "dd/MM/yyyy" format of today's date
+ * ```
+ */
 export declare const today: string;
+/**
+ * This function returns a date that is one day from today, formatted as a string.
+ * It is useful for scenarios where you need to calculate a date one day in the future,
+ * such as setting deadlines or reminders.
+ * @returns (string): A formatted date string representing tomorrow's date.
+ * It can be used in various contexts, such as displaying future dates in a user interface or calculating due dates.
+ * @example
+ * ```typescript
+ *    const tomorrowDate = getTomorrowDate(); // Returns "dd/MM/yyyy" format of the date tomorrow
+ * ```
+ */
 export declare const tomorrow: string;
+/**
+ * This function returns a date that is two weeks from today, formatted as a string.
+ * It is useful for scenarios where you need to calculate a date two weeks in the future,
+ * such as setting deadlines or reminders.
+ * @returns (string): A formatted date string representing two weeks from today.
+ * It can be used in various contexts, such as displaying future dates in a user interface or calculating due dates.
+ * @example
+ * ```typescript
+ *    const twoWeeksFromToday = getTwoWeeksFromToday(); // Returns "dd/MM/yyyy" format of the date two weeks from today
+ * ```
+ */
 export declare const twoWeeks: string;
 /**
- *  This function returns the current date formatted as a string based on the provided format.
- *  @param formatString (optional) The format string to use for the date. Defaults to "dd/MM/yyyy".
- *  It is useful for getting the current date in a specific format, such as "dd/MM/yyyy" or "MM/dd/yyyy".
- *  If no format string is provided, it defaults to "dd/MM/yyyy".
- *  @returns  (string): The current date formatted as a string.
- *  It can be used in various contexts, such as displaying the current date in a user interface or storing it in a database.
- *  @example
- *  ```typescript
+ * This function returns the current date formatted as a string based on the provided format.
+ * @param formatString (optional) The format string to use for the date. Defaults to "dd/MM/yyyy".
+ * It is useful for getting the current date in a specific format, such as "dd/MM/yyyy" or "MM/dd/yyyy".
+ * If no format string is provided, it defaults to "dd/MM/yyyy".
+ * @returns  (string): The current date formatted as a string.
+ * It can be used in various contexts, such as displaying the current date in a user interface or storing it in a database.
+ * @example
+ * ```typescript
  *    const formattedDate = defaultDate(); // Returns the current date in "dd/MM/yyyy" format
  *    const formattedDateUS = defaultDate("MM/dd/yyyy"); // Returns the current date in "MM/dd/yyyy" format
- *  ```
+ * ```
  */
 export declare const defaultDate: (formatString?: string) => string;
 /**
- *  This function formats a date based on the provided parameters.
- *  It can format the date to the start or end of the day, handle UTC dates,
- *  and format it as a date-only string.
- *  It is useful for displaying dates in a specific format,
- *  such as in a date picker or when saving dates to a database.
- *  @param date (Date | null | undefined): The date to format. If null or undefined, it returns null.
- *  @param startOfDate (boolean): If true, formats the date to the start of the day.
- *  @param endOfDate (boolean): If true, formats the date to the end of the day.
- *  @param isUTC (boolean): If true, formats the date in UTC format.
- *  @param dateOnly (boolean): If true, formats the date as a date-only string (e.g., "yyyy-MM-dd").
- *  This is useful for scenarios where you need to display or store only the date part without the time.
- *  It can be used in various contexts, such as displaying dates in a user interface or saving them to a database.
- *  @example
- *  ```typescript
+ * This function formats a date based on the provided parameters.
+ * It can format the date to the start or end of the day, handle UTC dates,
+ * and format it as a date-only string.
+ * It is useful for displaying dates in a specific format,
+ * such as in a date picker or when saving dates to a database.
+ * @param date (Date | null | undefined): The date to format. If null or undefined, it returns null.
+ * @param startOfDate (boolean): If true, formats the date to the start of the day.
+ * @param endOfDate (boolean): If true, formats the date to the end of the day.
+ * @param isUTC (boolean): If true, formats the date in UTC format.
+ * @param dateOnly (boolean): If true, formats the date as a date-only string (e.g., "yyyy-MM-dd").
+ * This is useful for scenarios where you need to display or store only the date part without the time.
+ * It can be used in various contexts, such as displaying dates in a user interface or saving them to a database.
+ * @example
+ * ```typescript
  *    const formattedDate = formatDate(new Date(), true, false, false, true); // Formats the current date to the start of the day as a date-only string
  *    const formattedUTCDate = formatDate(new Date(), false, false, true); // Formats the current date in UTC format
  *    const formattedEndDate = formatDate(new Date(), false, true); // Formats the current date to the end of the day
- *  ```
- *  @returns (string | null): A formatted date string based on the provided parameters. If the input date is null or undefined, it returns null.
+ * ```
+ * @returns (string | null): A formatted date string based on the provided parameters. If the input date is null or undefined, it returns null.
  */
 export declare const formatDate: (date?: Date | null, startOfDate?: boolean, endOfDate?: boolean, isUTC?: boolean, dateOnly?: boolean) => string | null;
 /**
- *  This function parses a date string into a Date object based on the provided format.
- *  It splits the date string into parts (day, month, year) and constructs a Date object.
- *  If the date string is invalid or cannot be parsed, it returns null.
- *  It also handles two-digit years by converting them to four-digit years.
- *  @param date (any): The date string to parse. It can be in various formats (e.g., "dd/MM/yyyy", "MM/dd/yyyy").
- *  @param formatString (string): The format string to use for parsing the date.
- *  @param localDateformat (string): The local date format to use for parsing. It should match the format of the input date string.
- *  @param parseKeyboardVal (boolean): Whether to parse the date from a keyboard input. Defaults to false.
- *  @returns (string | null): Returns a formatted date string if parsing is successful, or null if the input is invalid.
- *  This function is useful for converting user input or string representations of dates into a Date object.
- *  It can handle various date formats and ensures that the resulting Date object is valid.
- *  If the input date string is invalid or cannot be parsed, it returns null.
- *  It also includes logic to handle two-digit years by converting them to four-digit years.
- *  @example
- *  ```typescript
+ * This function parses a date string into a Date object based on the provided format.
+ * It splits the date string into parts (day, month, year) and constructs a Date object.
+ * If the date string is invalid or cannot be parsed, it returns null.
+ * It also handles two-digit years by converting them to four-digit years.
+ * @param date (any): The date string to parse. It can be in various formats (e.g., "dd/MM/yyyy", "MM/dd/yyyy").
+ * @param formatString (string): The format string to use for parsing the date.
+ * @param localDateformat (string): The local date format to use for parsing. It should match the format of the input date string.
+ * @param parseKeyboardVal (boolean): Whether to parse the date from a keyboard input. Defaults to false.
+ * @returns (string | null): Returns a formatted date string if parsing is successful, or null if the input is invalid.
+ * This function is useful for converting user input or string representations of dates into a Date object.
+ * It can handle various date formats and ensures that the resulting Date object is valid.
+ * If the input date string is invalid or cannot be parsed, it returns null.
+ * It also includes logic to handle two-digit years by converting them to four-digit years.
+ * @example
+ * ```typescript
  *    const parsedDate = parseDate("25/12/2023", "dd/MM/yyyy", "dd/MM/yyyy");
  *    console.log(parsedDate); // Returns "2023-12-25" in the "yyyy-MM-dd" format
  *    const parsedDateUS = parseDate("12/25/23", "MM/dd/yyyy", "MM/dd/yyyy");
  *    console.log(parsedDateUS); // Returns "2023-12-25" in the "yyyy-MM-dd" format
  *    const parsedInvalidDate = parseDate("31/02/2023", "dd/MM/yyyy", "dd/MM/yyyy");
  *    console.log(parsedInvalidDate); // Returns null, as February 31st is invalid
- *  ```
+ * ```
  */
 export declare const parseDate: (date: any, formatString: string | undefined, localDateformat: string, parseKeyboardVal?: boolean) => string | null;
 /**
- *  This function returns a locale object based on the provided LeapContext.
- *  It checks the hostInfo.region and returns the corresponding locale with weekStartsOn set to 1.
- *  If the region is not recognized, it returns undefined.
- *  @param leapContext (LeapContext | undefined): The LeapContext object containing hostInfo with region information.
- *  @returns The function supports UK, US, AU (including NZ), and CA regions. If the region is not recognized, it returns undefined.
- *  @example
- *  ```typescript
+ * This function returns a locale object based on the provided LeapContext.
+ * It checks the hostInfo.region and returns the corresponding locale with weekStartsOn set to 1.
+ * If the region is not recognized, it returns undefined.
+ * @param leapContext (LeapContext | undefined): The LeapContext object containing hostInfo with region information.
+ * @returns The function supports UK, US, AU (including NZ), and CA regions. If the region is not recognized, it returns undefined.
+ * @example
+ * ```typescript
  *    const locale = getLocale(leapContext); // Returns the appropriate locale based on the region
  *    const localeUS = getLocale({ hostInfo: { region: "us" } }); // Returns enUS locale
  *    const localeUK = getLocale({ hostInfo: { region: "uk" } }); // Returns enGB locale
  *    const localeAU = getLocale({ hostInfo: { region: "au" } }); // Returns enAU locale
  *    const localeCA = getLocale({ hostInfo: { region: "ca" } }); // Returns enGB locale
- *  ```
+ * ```
  */
 export declare const getLocale: (leapContext?: LeapContext) => Locale | undefined;
 /**
- *  This function formats a date or datetime value into a string based on the provided locale.
- *  It supports both date-only and datetime formats, and can handle UTC dates.
- *  @param value (string | Date | undefined): The date or datetime value to format.
- *  @param locale (Locale | undefined): The locale to use for formatting. If undefined, it will not format the date.
- *  @param isUtc (boolean): Whether the date is in UTC format. Defaults to true.
- *  @param dateOnly (boolean): Whether to format the value as a date only.
- *  @param show24H (boolean): Whether to show the time in 24-hour format. Defaults to false.
- *  @returns (string): A formatted date or datetime string. If the input value is invalid or locale is undefined, it returns an empty string.
- *  @example
- *  ```typescript
+ * This function formats a date or datetime value into a string based on the provided locale.
+ * It supports both date-only and datetime formats, and can handle UTC dates.
+ * @param inputValue (string | Date | undefined): The date or datetime value to format.
+ * @param locale (Locale | undefined): The locale to use for formatting. If undefined, it will not format the date.
+ * @param outputAsUtc (boolean): Whether the date is in UTC format. Defaults to true.
+ * @param outputAsDateOnly (boolean): Whether to format the value as a date only.
+ * @param outputAs24H (boolean): Whether to show the time in 24-hour format. Defaults to false.
+ * @returns (string): A formatted date or datetime string. If the input value is invalid or locale is undefined, it returns an empty string.
+ * @example
+ * ```typescript
  *    const formattedDate = lctFormatDateTime(new Date(), enGB, true, false, true); // Returns "01/01/2023 14:30"
  *    const formattedDateTime = lctFormatDateTime("2023-01-01T14:30:00Z", enUS, true, false, false); // Returns "01/01/2023 02:30 PM"
  *    const formattedDateOnly = lctFormatDateTime("2023-01-01", enAU, false, true); // Returns "01/01/2023"
  *    const formattedInvalid = lctFormatDateTime(undefined, enGB); // Returns ""
  * ```
  */
-export declare const lctFormatDateTime: (value?: string | Date, locale?: Locale, isUtc?: boolean, dateOnly?: boolean, show24H?: boolean) => string;
+export declare const formatDateTime: (inputValue?: string | Date, locale?: Locale, outputAsUtc?: boolean, outputAsDateOnly?: boolean, outputAs24H?: boolean) => string;
 /**
- *  This function formats a date string into a report-friendly format based on the provided locale.
- *  It handles both ISO date strings and strings in the format "yyyy-MM-dd".
+ * This function formats a date string into a report-friendly format based on the provided locale.
+ * It handles both ISO date strings and strings in the format "yyyy-MM-dd".
  *
- *  @param date (string | null): The date string to format. It can be in ISO format or "yyyy-MM-dd".
- *  @param locale (Locale | undefined): The locale to use for formatting. If undefined, it will not format the date.
- *  @returns (string): A formatted date string. If the input date is invalid or locale is undefined, it returns an empty string and logs a warning.
- *  @example
- *  ```typescript
+ * @param date (string | null): The date string to format. It can be in ISO format or "yyyy-MM-dd".
+ * @param locale (Locale | undefined): The locale to use for formatting. If undefined, it will not format the date.
+ * @returns (string): A formatted date string. If the input date is invalid or locale is undefined, it returns an empty string and logs a warning.
+ * @example
+ * ```typescript
  *    const formattedReportDate = formatReportDate("2023-12-25", enGB); // Returns "25-12-2023"
  *    const formattedReportDateISO = formatReportDate("2023-12-25T00:00:00Z", enUS); // Returns "12-25-2023"
  *    const formattedReportDateInvalid = formatReportDate("31-02-2023", enGB); // Returns "", logs warning
  *    const formattedReportDateNull = formatReportDate(null, enGB); // Returns "", logs warning
- *  ```
+ * ```
  */
 export declare const formatReportDate: (date: string | null, locale?: Locale) => string;
 /**
@@ -136,34 +206,53 @@ export declare const formatReportDate: (date: string | null, locale?: Locale) =>
  */
 export declare const getDateTimeWithOffset: (date: string) => Date;
 /**
- *  This function checks if a string is null or undefined.
- *  It returns true if the string is null, undefined, or an empty string.
- *  @param value (string | null | undefined): The string to check.
- *  @returns (boolean): Returns true if the string is null, undefined, or empty; otherwise, false.
- *  @example
- *  ```typescript
+ * This function checks if a string is null or undefined.
+ * It returns true if the string is null, undefined, or an empty string.
+ * @param value (string | null | undefined): The string to check.
+ * @returns (boolean): Returns true if the string is null, undefined, or empty; otherwise, false.
+ * @example
+ * ```typescript
  *    const isNullOrUndefined = isStringNullOrUndefined(null); // Returns true
  *    const isEmptyString = isStringNullOrUndefined(""); // Returns true
  *    const isValidString = isStringNullOrUndefined("Hello"); // Returns false
- *  ```
+ * ```
  */
 export declare const isStringNullOrUndefined: (value?: string | null) => boolean;
 /**
- *  This function formats a date as a string in the "yyyy-MM-dd" format, suitable for database storage.
- *  It takes a Date object as input and returns the formatted string.
- *  @param date (Date): The date to format.
- *  @returns (string): A formatted date string in the "yyyy-MM-dd" format.
- *  @example
- *  ```typescript
+ * This function formats a date as a string in the "yyyy-MM-dd" format, suitable for database storage.
+ * It takes a Date object as input and returns the formatted string.
+ * @param date (Date): The date to format.
+ * @returns (string): A formatted date string in the "yyyy-MM-dd" format.
+ * @example
+ * ```typescript
  *    const dbFormattedDate = formatAsDBDate(new Date()); // Returns "2023-12-25"
  *    const dbFormattedDateInvalid = formatAsDBDate(new Date("Invalid Date")); // Returns "Invalid date"
- *  ```
+ * ```
  */
 export declare const formatAsDBDate: (date: Date) => string;
-export declare const getFormattedLocalDateTime: (value?: string | Date, locale?: Locale, isUtc?: boolean, dateOnly?: boolean, show24H?: boolean, formatString?: string, formatStartOfDay?: boolean, formatEndOfDay?: boolean) => string;
 /**
- *  This enum defines the types of buttons available in the dialog.
- *  It is used to identify which button was clicked by the user.
+ * This function formats a date or datetime value into a string based on the provided locale.
+ * It supports both date-only and datetime formats, and can handle UTC dates.
+ * It also allows for formatting the start or end of the day.
+ * @param inputValue (string | Date | undefined): The date or datetime value to format.
+ * @param locale (Locale | undefined): The locale to use for formatting. If undefined, it will not format the date.
+ * @param outputAsStartOfDay (boolean): If true, formats the date to the start of the day.
+ * @param outputAsEndOfDay (boolean): If true, formats the date to the end of the day.
+ * @returns  (string): A formatted date or datetime string. If the input value is invalid or locale is undefined, it returns an empty string.
+ * @example
+ * ```typescript
+ *    const formattedDate = convertLocalDateToUTCDateTime(new Date(), enGB, true, false, true); // Returns "01/01/2023 14:30"
+ *    const formattedDateTime = convertLocalDateToUTCDateTime("2023-01-01T14:30:00Z", enUS, true, false, false); // Returns "01/01/2023 02:30 PM"
+ *    const formattedDateOnly = convertLocalDateToUTCDateTime("2023-01-01", enAU, false, true); // Returns "01/01/2023"
+ *    const formattedInvalid = convertLocalDateToUTCDateTime(undefined, enGB); // Returns ""
+ *    const outputAsStartOfDay = convertLocalDateToUTCDateTime(new Date(), enGB, true, false, true, undefined, true); // Returns "01/01/2023 00:00"
+ *    const outputAsEndOfDay = convertLocalDateToUTCDateTime(new Date(), enGB, true, false, true, undefined, false, true); // Returns "01/01/2023 23:59"
+ * ```
+ */
+export declare const convertLocalDateToUTCDateTime: (inputValue?: string | Date, locale?: Locale, outputAsStartOfDay?: boolean, outputAsEndOfDay?: boolean) => string;
+/**
+ * This enum defines the types of buttons available in the dialog.
+ * It is used to identify which button was clicked by the user.
  */
 export declare enum DialogButtonType {
     Confirm = 1,
@@ -171,19 +260,19 @@ export declare enum DialogButtonType {
     Cancel = 3
 }
 /**
- *  This function shows a 3-button alert dialog using the Leap SDK.
- *  It allows the user to confirm, refuse, or cancel an action.
- *  It takes a message, button texts, and callbacks for each action.
- *  @param message (string): The message to display in the dialog.
- *  @param confirmButtonText (string): The text for the confirm button.
- *  @param confirmCallback (function): The callback function to execute when the confirm button is clicked.
- *  @param refuseButtonText (string): The text for the refuse button. Optional.
- *  @param refuseCallback (function): The callback function to execute when the refuse button is clicked. Optional.
- *  @param cancelButtonText (string): The text for the cancel button. Optional.
- *  @param sdkApi (Api): The Leap SDK API instance to use for showing the dialog.
- *  @returns A promise that resolves when the dialog is closed.
- *  @example
- *  ```typescript
+ * This function shows a 3-button alert dialog using the Leap SDK.
+ * It allows the user to confirm, refuse, or cancel an action.
+ * It takes a message, button texts, and callbacks for each action.
+ * @param message (string): The message to display in the dialog.
+ * @param confirmButtonText (string): The text for the confirm button.
+ * @param confirmCallback (function): The callback function to execute when the confirm button is clicked.
+ * @param refuseButtonText (string): The text for the refuse button. Optional.
+ * @param refuseCallback (function): The callback function to execute when the refuse button is clicked. Optional.
+ * @param cancelButtonText (string): The text for the cancel button. Optional.
+ * @param sdkApi (Api): The Leap SDK API instance to use for showing the dialog.
+ * @returns A promise that resolves when the dialog is closed.
+ * @example
+ * ```typescript
  *    show3buttonAlert(
  *      "Are you sure you want to proceed?",
  *     "Yes",
@@ -193,6 +282,6 @@ export declare enum DialogButtonType {
  *    "Cancel",
  *     sdkApi
  *    );
- *  ```
+ * ```
  */
 export declare const show3buttonAlert: (message: string, confirmButtonText: string, confirmCallback: () => void, refuseButtonText?: string, refuseCallback?: () => void, cancelButtonText?: string, sdkApi?: Api) => Promise<void> | undefined;