@leapdevuk/component-toolbox 0.0.126 → 0.0.128

package/dist/CHANGELOG.md

@@ -1,11 +1,23 @@
 # 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
+
+- Utility function to format date as regional local time getFormattedLocalDateTime
+
 ## 0.0.126 (2025-07-09)
 
 ### Features
 
-- Utility function formatReportDate now accepts an undefined locale object for when creating state date objects when the locale is not yet available.
-  Will return a console warn and an empty string
+- Utility function formatReportDate now accepts an undefined locale object when creating state data objects when the locale is not yet available.
+  If not present, it will return a console warning and an empty string.
 
 ## 0.0.125 (2025-07-09)
 
@@ -19,45 +31,51 @@
 
 - Added utility function formatReportDate to regionally format dates for reporting
 
-## 0.0.112 (2025-04-15)
+## 0.0.122 (2025-06-20)
 
-### Release
+### Bug Fixes
 
-- Test verions release 0.0.111-test.5
+- Updated size of the preview icon
 
-## 0.0.111-test.5 (2025-04-15)
+## 0.0.121 (2025-04-15)
+
+### Release 0.0.121
+
+- Release of Test verion 0.0.121-test.1
+
+## 0.0.120 (2025-05-30)
 
 ### Features
 
-- Added support for change log.
+- Updated DateRangePicker to use sdk alerts for validation
 
-### Bug Fixes
+## 0.0.120 (2025-05-29)
 
-- DateRangePicker: Split update property to fromDate and toDate (was initially a combined function)
-- DateRangePicker: Fixed dateTime when region is summer/winter time (checking against local dateTime)
-- DatePicker: Fixed dateTime when region is summer/winter time (checking against local dateTime)
+### Bug Fixes
 
-## 0.0.113 (2025-05-14)
+- Fixed issue with revert being called early on calendar selection
 
-### Features
+## 0.0.119 (2025-05-29)
 
-- Added property on AccordionTable to support component props on grid (row: onMouseOver, onMouseLeave ect.)
+### Bug Fixes
 
-## 0.0.114 (2025-05-21)
+- Fixed Calendar reverting to the original year instead of the selected one
 
 ### Features
 
-- Added parameter on getLocalDisplayFormattedDateTime to specify if time should be adjusted on local time zone
+- Updated DatePicker to use sdk alerts for validation
 
-## 0.0.115 (2025-05-22)
+## 0.0.118 (2025-05-23)
 
-### Removed
+### Bug Fixes
 
-- getLocalDisplayFormattedDateTime
+- Updated DatePicker to not show calendar icon when disabled
+
+## 0.0.117 (2025-05-23)
 
 ### Added
 
-- lctFormatDateTime supporting 24 hours, UTC & DateOnly
+- Added formatAsDBDate for use in apps (accepts Date, returns string formatted "yyyy-MM-dd")
 
 ## 0.0.116 (2025-05-22)
 
@@ -65,48 +83,42 @@
 
 - Added property on NumberDisplay 'noValueText' to work alongside 'hideNoValue' to display an alternative character on zero values
 
-## 0.0.117 (2025-05-23)
+## 0.0.115 (2025-05-22)
 
-### Added
+### Removed
 
-- Added formatAsDBDate for use in apps (accepts Date, returns string formatted "yyyy-MM-dd")
+- getLocalDisplayFormattedDateTime
 
-## 0.0.118 (2025-05-23)
+### Added
 
-### Bug Fixes
+- lctFormatDateTime supporting 24 hours, UTC & DateOnly
 
-- Updated DatePicker to not show calendar icon when disabled
+## 0.0.114 (2025-05-21)
 
-## 0.0.119 (2025-05-29)
+### Features
 
-### Bug Fixes
+- Added parameter on getLocalDisplayFormattedDateTime to specify if time should be adjusted on local time zone
 
-- Fixed Calendar reverting to the original year instead of the selected one
+## 0.0.113 (2025-05-14)
 
 ### Features
 
-- Updated DatePicker to use sdk alerts for validation
+- Added property on AccordionTable to support component props on grid (row: onMouseOver, onMouseLeave ect.)
 
-## 0.0.120 (2025-05-29)
+## 0.0.112 (2025-04-15)
 
-### Bug Fixes
+### Release
 
-- Fixed issue with revert being called early on calendar selection
+- Test verions release 0.0.111-test.5
 
-## 0.0.120 (2025-05-30)
+## 0.0.111-test.5 (2025-04-15)
 
 ### Features
 
-- Updated DateRangePicker to use sdk alerts for validation
-
-## 0.0.121 (2025-04-15)
-
-### Release 0.0.121
-
-- Release of Test verion 0.0.121-test.1
-
-## 0.0.122 (2025-06-20)
+- Added support for change log.
 
 ### Bug Fixes
 
-- Updated size of the preview icon
+- DateRangePicker: Split update property to fromDate and toDate (was initially a combined function)
+- DateRangePicker: Fixed dateTime when region is summer/winter time (checking against local dateTime)
+- DatePicker: Fixed dateTime when region is summer/winter time (checking against local dateTime)

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

@@ -1,9 +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 { getFormattedLocalDateTime as lctGetFormattedLocalDateTime } 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';

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

@@ -1,31 +1,291 @@
 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
+ *    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
+ *    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
+ *    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.
+ */
 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
+ *    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
+ *    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;
-export declare const lctFormatDateTime: (value?: string | Date, locale?: Locale, isUtc?: boolean, dateOnly?: boolean, show24H?: boolean) => string;
+/**
+ * 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
+ *    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 formatDateTime: (value?: string | Date, locale?: Locale, isUtc?: boolean, dateOnly?: boolean, show24H?: 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".
+ *
+ * @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;
 /**
  * @deprecated The method should not be used
  */
 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
+ *    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
+ *    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;
+/**
+ * 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 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.
+ * @param formatString (string): The format string to use for formatting the date. If not provided, it defaults to the locale's short date format.
+ * @param formatStartOfDay (boolean): If true, formats the date to the start of the day.
+ * @param formatEndOfDay (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 = getFormattedLocalDateTime(new Date(), enGB, true, false, true); // Returns "01/01/2023 14:30"
+ *    const formattedDateTime = getFormattedLocalDateTime("2023-01-01T14:30:00Z", enUS, true, false, false); // Returns "01/01/2023 02:30 PM"
+ *    const formattedDateOnly = getFormattedLocalDateTime("2023-01-01", enAU, false, true); // Returns "01/01/2023"
+ *    const formattedInvalid = getFormattedLocalDateTime(undefined, enGB); // Returns ""
+ *    const formattedStartOfDay = getFormattedLocalDateTime(new Date(), enGB, true, false, true, undefined, true); // Returns "01/01/2023 00:00"
+ *    const formattedEndOfDay = getFormattedLocalDateTime(new Date(), enGB, true, false, true, undefined, false, true); // Returns "01/01/2023 23:59"
+ * ```
+ */
+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.
+ */
 export declare enum DialogButtonType {
     Confirm = 1,
     Refuse = 2,
     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
+ *    show3buttonAlert(
+ *      "Are you sure you want to proceed?",
+ *     "Yes",
+ *     () => console.log("Confirmed"),
+ *     "No",
+ *     () => console.log("Refused"),
+ *    "Cancel",
+ *     sdkApi
+ *    );
+ * ```
+ */
 export declare const show3buttonAlert: (message: string, confirmButtonText: string, confirmCallback: () => void, refuseButtonText?: string, refuseCallback?: () => void, cancelButtonText?: string, sdkApi?: Api) => Promise<void> | undefined;