@leapdevuk/component-toolbox 0.0.125 → 0.0.127

package/dist/CHANGELOG.md

@@ -1,62 +1,69 @@
 # Changelog
 
-## 0.0.125 (2025-07-09)
+## 0.0.127 (2025-07-16)
 
 ### Features
 
-- Utility function formatReportDate now accepts a locale object, replacing the previous locale code string
+- Utility function to format date as regional local time getFormattedLocalDateTime
 
-## 0.0.124 (2025-07-08)
+## 0.0.126 (2025-07-09)
 
 ### Features
 
-- Added utility function formatReportDate to regionally format dates for reporting
+- 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.112 (2025-04-15)
+## 0.0.125 (2025-07-09)
 
-### Release
+### Features
 
-- Test verions release 0.0.111-test.5
+- Utility function formatReportDate now accepts a locale object, replacing the previous locale code string
 
-## 0.0.111-test.5 (2025-04-15)
+## 0.0.124 (2025-07-08)
 
 ### Features
 
-- Added support for change log.
+- Added utility function formatReportDate to regionally format dates for reporting
+
+## 0.0.122 (2025-06-20)
 
 ### Bug Fixes
 
-- 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)
+- Updated size of the preview icon
 
-## 0.0.113 (2025-05-14)
+## 0.0.121 (2025-04-15)
 
-### Features
+### Release 0.0.121
 
-- Added property on AccordionTable to support component props on grid (row: onMouseOver, onMouseLeave ect.)
+- Release of Test verion 0.0.121-test.1
 
-## 0.0.114 (2025-05-21)
+## 0.0.120 (2025-05-30)
 
 ### Features
 
-- Added parameter on getLocalDisplayFormattedDateTime to specify if time should be adjusted on local time zone
+- Updated DateRangePicker to use sdk alerts for validation
 
-## 0.0.115 (2025-05-22)
+## 0.0.120 (2025-05-29)
 
-### Removed
+### Bug Fixes
 
-- getLocalDisplayFormattedDateTime
+- Fixed issue with revert being called early on calendar selection
 
-### Added
+## 0.0.119 (2025-05-29)
 
-- lctFormatDateTime supporting 24 hours, UTC & DateOnly
+### Bug Fixes
 
-## 0.0.116 (2025-05-22)
+- Fixed Calendar reverting to the original year instead of the selected one
 
 ### Features
 
-- Added property on NumberDisplay 'noValueText' to work alongside 'hideNoValue' to display an alternative character on zero values
+- Updated DatePicker to use sdk alerts for validation
+
+## 0.0.118 (2025-05-23)
+
+### Bug Fixes
+
+- Updated DatePicker to not show calendar icon when disabled
 
 ## 0.0.117 (2025-05-23)
 
@@ -64,42 +71,48 @@
 
 - Added formatAsDBDate for use in apps (accepts Date, returns string formatted "yyyy-MM-dd")
 
-## 0.0.118 (2025-05-23)
+## 0.0.116 (2025-05-22)
 
-### Bug Fixes
+### Features
 
-- Updated DatePicker to not show calendar icon when disabled
+- Added property on NumberDisplay 'noValueText' to work alongside 'hideNoValue' to display an alternative character on zero values
 
-## 0.0.119 (2025-05-29)
+## 0.0.115 (2025-05-22)
 
-### Bug Fixes
+### Removed
 
-- Fixed Calendar reverting to the original year instead of the selected one
+- getLocalDisplayFormattedDateTime
 
-### Features
+### Added
 
-- Updated DatePicker to use sdk alerts for validation
+- lctFormatDateTime supporting 24 hours, UTC & DateOnly
 
-## 0.0.120 (2025-05-29)
+## 0.0.114 (2025-05-21)
 
-### Bug Fixes
+### Features
 
-- Fixed issue with revert being called early on calendar selection
+- Added parameter on getLocalDisplayFormattedDateTime to specify if time should be adjusted on local time zone
 
-## 0.0.120 (2025-05-30)
+## 0.0.113 (2025-05-14)
 
 ### Features
 
-- Updated DateRangePicker to use sdk alerts for validation
+- Added property on AccordionTable to support component props on grid (row: onMouseOver, onMouseLeave ect.)
 
-## 0.0.121 (2025-04-15)
+## 0.0.112 (2025-04-15)
 
-### Release 0.0.121
+### Release
 
-- Release of Test verion 0.0.121-test.1
+- Test verions release 0.0.111-test.5
 
-## 0.0.122 (2025-06-20)
+## 0.0.111-test.5 (2025-04-15)
+
+### Features
+
+- 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

@@ -7,3 +7,4 @@ 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

@@ -6,26 +6,193 @@ export declare const minDateAsObject: Date;
 export declare const timezone: string;
 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;
 export declare const oneWeek: string;
 export declare const today: string;
 export declare const tomorrow: string;
 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;
+/**
+ *  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 lctFormatDateTime: (value?: string | Date, locale?: Locale, isUtc?: boolean, dateOnly?: boolean, show24H?: boolean) => string;
-export declare const formatReportDate: (date: string | null, locale: Locale) => 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;
+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;