@react-fabric/utilities 1.0.0-beta.6 → 1.0.0-beta.61

package/dist/esm/_lonlat.js

@@ -0,0 +1,100 @@
+'use client';
+
+import _slicedToArray from '@babel/runtime/helpers/slicedToArray';
+import { isEmpty, isArray, isObject, isString } from './_isType.js';
+
+var getLatitudeLongitude = function getLatitudeLongitude(lonLat) {
+  var _convertLatLng = convertLatLng(lonLat),
+    _convertLatLng2 = _slicedToArray(_convertLatLng, 2),
+    lon = _convertLatLng2[0],
+    lat = _convertLatLng2[1];
+  return {
+    latitude: lat,
+    longitude: lon
+  };
+};
+
+/**
+ * Convert various formats of longitude and latitude to a tuple of [lon, lat].
+ * This function supports:
+ * - Arrays with two or three elements (e.g., [lon, lat] or [lon, lat, alt])
+ * - Objects with properties `lng`, `lat`, `lon`, or `longitude` and `latitude`
+ * - Strings in the format "lat,lon"
+ * The function will return a tuple of numbers [lon, lat].
+ *
+ * @param {LngLatLike} lonLat - The input longitude and latitude in various formats.
+ * @returns { [lon: number, lat: number] } A tuple of [lon, lat] where lon and lat are numbers.
+ * @throws Error if the input is not a valid format.
+ */
+var convertLatLng = function convertLatLng(lonLat) {
+  if (isEmpty(lonLat)) {
+    throw Error("Invalid geo coordinates");
+  }
+  if (isArray(lonLat) && lonLat.length === 2 || isArray(lonLat) && lonLat.length === 3) {
+    return [Number(lonLat[0]), Number(lonLat[1])];
+  }
+  if (isObject(lonLat)) {
+    if ("longitude" in lonLat) {
+      return [lonLat.longitude, lonLat.latitude];
+    }
+    return ["lon" in lonLat ? lonLat.lon : lonLat.lng, lonLat.lat];
+  }
+  if (isString(lonLat)) {
+    var _lonLat$split = lonLat.split(","),
+      _lonLat$split2 = _slicedToArray(_lonLat$split, 2),
+      _lat = _lonLat$split2[0],
+      _lon = _lonLat$split2[1];
+    if (!isNaN(+_lat) && !isNaN(+_lon)) return [+_lon, +_lat];
+  }
+  throw Error("Invalid geo coordinates");
+};
+
+/**
+ * Convert a coordinate to Degrees, Minutes, Seconds (DMS) format.
+ * This function takes a coordinate and returns a string in the format "degrees˚minutes'seconds" with direction (N/S or E/W).
+ * It handles both latitude and longitude coordinates.
+ * This function assumes that the input coordinate is in decimal degrees format.
+ * It converts the coordinate to DMS format by calculating the degrees, minutes, and seconds,
+ * and then formatting the result as a string.
+ *
+ * @param {number} coord - The coordinate to convert.
+ * @param {boolean} isLat - Whether the coordinate is latitude (default is false for longitude).
+ * @returns {string} A string representation of the coordinate in DMS format.
+ */
+var convertToDMS = function convertToDMS(coord) {
+  var isLat = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+  var degree = Math.floor(Math.abs(coord));
+  var hour = (Math.abs(coord) - degree) * 60;
+  var minute = (hour - Math.floor(hour)) * 60;
+  return "".concat(degree, "\u02DA").concat(Math.floor(hour), "'").concat(minute.toFixed(2), "\"").concat(coord < 0 ? isLat ? "S" : "W" : isLat ? "N" : "E");
+};
+
+/**
+ * Convert a latitude and longitude to a human-readable text format.
+ * This function takes a latitude and longitude in various formats and
+ * returns a string in the format "degrees˚minutes'seconds" with direction (N/S, E/W).
+ *
+ * This function supports:
+ *
+ * - Objects with properties `lng`, `lat`, `lon`, or `longitude` and `latitude`
+ * - Arrays with two or three elements (e.g., [lon, lat] or [lon, lat, alt])
+ * - Strings in the format "lat,lon"
+ *
+ * @param {LngLatLike} latlon - The latitude and longitude in various formats.
+ * @returns {string} A string representation of the location in DMS format.
+ *
+ * @example
+ * ```jsx
+ * const location = getLocationAsText({ lat: 40.7128, lng: -74.0060 });
+ * console.log(location); // "40˚42'51.36"N, 74˚0'21.60"W"
+ * ```
+ */
+var getLocationAsText = function getLocationAsText(latlon) {
+  var _convertLatLng3 = convertLatLng(latlon),
+    _convertLatLng4 = _slicedToArray(_convertLatLng3, 2),
+    lon = _convertLatLng4[0],
+    lat = _convertLatLng4[1];
+  return "".concat(convertToDMS(lat, true), ", ").concat(convertToDMS(lon));
+};
+
+export { convertLatLng, getLatitudeLongitude, getLocationAsText };

package/dist/esm/_mergeRefs.js

@@ -25,6 +25,17 @@
 
 /* istanbul ignore file */
 
+/**
+ * Merge multiple refs into a single ref callback.
+ * This function allows you to combine multiple refs (either callback refs or React refs)
+ * into a single ref callback that can be used in React components.
+ * This is particularly useful when you want to assign a single element to multiple refs,
+ * such as when using third-party libraries that require refs or when you want to share refs between components.
+ * The function iterates over the provided refs and assigns the element to each ref.
+ *
+ * @param {AnyObject[]} refs - An array of refs to merge.
+ * @returns {function} A function that takes an element and assigns it to all provided refs.
+ */
 var mergeRefs = function mergeRefs() {
   for (var _len = arguments.length, refs = new Array(_len), _key = 0; _key < _len; _key++) {
     refs[_key] = arguments[_key];

package/dist/esm/_tokenize.js

@@ -27,10 +27,14 @@ import { isEmpty, isArray } from './_isType.js';
 
 
 /**
- * split text into array of tokens by word boundaries
- * @param str
- * @param keywords
- * @internal
+ * Tokenize a string based on provided keywords.
+ * This function splits the input string into tokens, where each token is an array containing
+ * the substring before the keyword and the keyword itself.
+ * If no keywords are provided, it returns the entire string as a single token.
+ *
+ * @param {string} str - The string to tokenize.
+ * @param {string | string[]} keywords - A string or an array of strings to use as keywords for tokenization.
+ * @returns {Array<[string, string]>} An array of tokens, where each token is an array of [substring, keyword].
  */
 var tokenize = function tokenize(str, keywords) {
   if (isEmpty(keywords)) {
@@ -56,6 +60,15 @@ var tokenize = function tokenize(str, keywords) {
   tokens.push([str.substring(lastIndex), ""]);
   return tokens;
 };
+
+/**
+ * Generate a token from a string.
+ * This function creates a token by taking the first letter of the first word and the first letter of the last word,
+ * or the first two letters of the first word if there is no last word.
+ *
+ * @param {string} str - The string to tokenize.
+ * @returns {string} A string token consisting of the first letters of the first and last words, or the first two letters of the first word.
+ */
 var iconToken = function iconToken(str) {
   var split = str.trim().split(" ");
   var first = split[0];

package/dist/esm/getImageColorset.js

@@ -25,6 +25,21 @@
 
 /* istanbul ignore file */
 
+/**
+ * Get the color set of an image element.
+ * This function analyzes the pixel data of an image to determine if it is predominantly light or dark.
+ * It returns "light", "dark", or "light_transparent"/"dark_transparent" based on the pixel analysis.
+ * It uses a canvas to draw the image and extract pixel data for analysis.
+ * * The function calculates the brightness of each pixel using the formula:
+ *  brightness = 0.2126 * R + 0.7152 * G + 0.0722 * B
+ * * It counts the number of light and dark pixels, and determines the overall color set based on the ratio of light to dark pixels.
+ * * If the image has transparent pixels, it appends "_transparent" to the result.
+ * * This function is useful for determining the color scheme of an image, which can be helpful for UI design,
+ *   theming, and accessibility considerations.
+ *
+ * @param {HTMLImageElement} el - The HTMLImageElement to analyze.
+ * @returns {string} A string indicating the color set of the image.
+ */
 var getImageColorset = function getImageColorset(el) {
   // create canvas
   var canvas = document.createElement("canvas");
@@ -45,8 +60,8 @@ var getImageColorset = function getImageColorset(el) {
         transparent = true;
         continue;
       }
-      if (transparent && data[x - 1] === 1) {
-        continue;
+      if (data[x + 3] < 1) {
+        transparent = true;
       }
       r = data[x];
       g = data[x + 1];

package/dist/esm/index.js

@@ -12,7 +12,8 @@ export { getByPath, getValue } from './_getByPath.js';
 export { hash, shortHash, uuid } from './_hash.js';
 export { interpolate, renderTemplate } from './_interpolate.js';
 export { compareValues, isEqual, matchString } from './_isEqual.js';
-export { isArray, isBoolean, isColor, isEmpty, isFalse, isNil, isNull, isNumber, isObject, isRtl, isString, isSvgPath, isTrue, isUndefined } from './_isType.js';
+export { isArray, isBoolean, isColor, isDefined, isEmpty, isFalse, isNil, isNull, isNumber, isObject, isRtl, isString, isSvgPath, isTrue, isUndefined } from './_isType.js';
+export { convertLatLng, getLatitudeLongitude, getLocationAsText } from './_lonlat.js';
 export { mergeRefs } from './_mergeRefs.js';
 export { iconToken, tokenize } from './_tokenize.js';
 export { getImageColorset } from './getImageColorset.js';

package/dist/esm/useLogger.js

@@ -207,7 +207,15 @@ var logger = function logger() {
 };
 
 /**
- * @internal
+ * useLogger is a custom hook that provides logging functionality.
+ * It allows you to log messages with different levels (log, debug, info, error, warning)
+ * and also provides a timer function to measure the duration of processes.
+ * The logs can include additional details such as the module name, process name, duration, and total time.
+ * It is designed to work in both Node.js and browser environments, adapting the log format accordingly.
+ * It uses ANSI escape codes for terminal colors in Node.js and CSS styles for console logs in the browser.
+ *
+ * @param mod - Optional module name to include in the log details.
+ * @returns An object with methods for logging messages and a timer function.
  */
 var useLogger = function useLogger(mod) {
   return {

package/dist/types/_ascii.d.ts

@@ -1,5 +1,10 @@
 /**
- * latin to ascii converter for convenient searching
- * @internal
+ * Converts a string to its ASCII representation by replacing
+ * special characters with their ASCII equivalents.
+ * This function is useful for normalizing strings for search or display purposes.
+ * It replaces characters like "Ä" with "Ae", "ß" with "ss", etc.
+ *
+ * @param {string} str - The input string to be converted.
+ * @returns {string} - The ASCII representation of the input string.
  */
 export declare const ascii: (str: string) => string;

package/dist/types/_boundingBox.d.ts

@@ -1,10 +1,22 @@
 /**
- * box "x,y,w,h" | [x,y,w,h]
- * returns canvas box [x,y,w,h]
+ * Get bounding box from a string or array.
+ * The box can be in the format "x,y,w,h" or [x,y,w,h].
+ * The box is adjusted to ensure that x and y are non-negative.
+ * The width and height are adjusted accordingly.
+ *
+ * @param box "x,y,w,h" | [x,y,w,h]
+ * @returns canvas box [x,y,w,h]
  */
 export declare const getBox: (box?: string | [number, number, number, number]) => [number, number, number, number];
 /**
- * box "x1,y1,x2,y2" | [x1,y1,x2,y2]
- * returns canvas box [x,y,w,h]
+ * Get bounding box from a string or array.
+ * The box can be in the format "x1,y1,x2,y2" or [x1,y1,x2,y2].
+ * The box is adjusted to ensure that x1 and y1 are non-negative.
+ * The width and height are calculated as x2 - x1 and y2 - y1 respectively.
+ * If x1 or y1 are negative, they are set to 0 and the width and height are adjusted accordingly.
+ * This is useful for ensuring that the bounding box is always within the canvas area.
+ *
+ * @param box "x1,y1,x2,y2" | [x1,y1,x2,y2]
+ * @returns canvas box [x,y,w,h]
  */
 export declare const getBoundingBox: (box?: string | [number, number, number, number]) => [number, number, number, number];

package/dist/types/_countries.d.ts

@@ -1,85 +1,112 @@
-/**
- * @internal
- */
-export interface Country {
-    continent: string;
-    iso2: string;
-    iso3: string;
-    alt?: string;
-    name: string;
+import { type Country as _Ctry } from "world-countries";
+export type Country = _Ctry & {
     alpha: string;
-    fullname: string;
-    capital: string;
-    tld: string;
-    currency: string;
     phone: string;
-    emoji: string;
-}
+    iconCode: string;
+    currency: {
+        code: string;
+        name?: string;
+        symbol?: string;
+    };
+};
 /**
- * country list with helper functions
+ * Country list with helper functions
+ * This is a list of all countries with their details.
+ * It includes information such as continent, ISO codes, name, full name, capital, top-level domain (TLD), currency, phone code, and emoji.
+ * This list can be used to retrieve country information based on various codes or names.
+ * @type {Country[]}
  */
 declare const _default: {
     /**
-     * Get iso2 code
-     * @param code
+     * Get ISO2 country code
+     *
+     * @param code - The country code to search for. It can be an ISO2 code, ISO3 code, or an alternative code.
+     * @return {string | undefined} - Returns the ISO2 country code if found, otherwise undefined.
      */
     toIso2(code: string): string | undefined;
     /**
-     * Get iso3 code
-     * @param code
+     * Get ISO3 country code
+     *
+     * @param code - The country code to search for. It can be an ISO2 code, ISO3 code, or an alternative code.
+     * @return {string | undefined} - Returns the ISO3 country code if found, otherwise undefined.
      */
     toIso3(code: string): string | undefined;
     /**
-     * Country flag emoji
-     * @param code
+     * Get country emoji
+     *
+     * @param code - The country code to search for. It can be an ISO2 code, ISO3 code, or an alternative code.
+     * @return {string} - Returns the emoji representation of the country if found, otherwise returns a default flag emoji.
      */
     emoji(code: string): string;
     /**
      * Get country name
-     * @param code
+     *
+     * @param code - The country code to search for. It can be an ISO2 code, ISO3 code, or an alternative code.
+     * @return {string} - Returns the name of the country if found, otherwise returns the code itself.
      */
     name: (code: string) => string;
     /**
-     * Find country by code
-     * @param code
-     * @return continent: string;
-     * @return iso2: string;
-     * @return iso3: string;
-     * @return name: string;
-     * @return fullname: string;
-     * @return capital: string;
-     * @return tld: string;
-     * @return currency: string;
-     * @return phone: string;
-     * @return emoji: string;
+     * This function searches for a country in the list by its code.
+     * It supports various formats:
+     * - ISO2 code (e.g., "US")
+     * - ISO3 code (e.g., "USA")
+     * - Alternative code (e.g., "US", "USA", "United States")
+     * It returns the first matching country object or undefined if not found.
+     * This function is useful for retrieving country details based on different code formats.
+     *
+     * @param code - The country code to search for. It can be an ISO2 code, ISO3 code, or an alternative code.
+     * @return {Country | undefined} - Returns the country object if found, otherwise undefined.
      */
     find(code: string): Country | undefined;
-    list: ({
-        continent: string;
-        iso2: string;
-        iso3: string;
-        alpha: string;
-        name: string;
-        fullname: string;
-        capital: string;
-        tld: string;
-        currency: string;
-        phone: string;
-        emoji: string;
-        alt?: undefined;
-    } | {
-        continent: string;
-        iso2: string;
-        iso3: string;
-        alt: string;
+    /**
+     * Country list
+     * This is a list of all countries with their details.
+     * It includes information such as continent, ISO codes, name, full name, capital, top-level domain (TLD), currency, phone code, and emoji.
+     * This list can be used to retrieve country information based on various codes or names.
+     *
+     * @type {Country[]}
+     */
+    list: {
+        iconCode: string;
         alpha: string;
-        name: string;
-        fullname: string;
-        capital: string;
-        tld: string;
-        currency: string;
         phone: string;
-        emoji: string;
-    })[];
+        currency: {
+            code: string;
+            name?: string | undefined;
+            symbol?: string | undefined;
+        };
+        name: import("world-countries").CountryName;
+        tld: string[];
+        cca2: string;
+        ccn3: string;
+        cca3: string;
+        cioc: string;
+        independent: boolean;
+        status: string;
+        unMember: boolean;
+        unRegionalGroup: "African Group" | "Asia and the Pacific Group" | "Eastern European Group" | "Latin American and Caribbean Group" | "Western European and Others Group" | "";
+        currencies: {
+            [currencyCode: string]: import("world-countries").Currency;
+        };
+        idd: import("world-countries").IntlDirectDialingCode;
+        capital: string[];
+        altSpellings: string[];
+        region: string;
+        subregion: string;
+        languages: {
+            [languageCode: string]: string;
+        };
+        translations: {
+            [languageCode: string]: import("world-countries").OfficialAndCommon;
+        };
+        latlng: [number, number];
+        demonyms: {
+            [languageCode: string]: import("world-countries").Demonyms;
+        };
+        landlocked: boolean;
+        borders: string[];
+        area: number;
+        flag: string;
+    }[];
 };
 export default _default;

package/dist/types/_debounce.d.ts

@@ -1,6 +1,12 @@
 /**
- * debounce callback
- * @internal
+ * Debounce function to limit the rate at which a function can fire.
+ * It will delay the execution of the function until after a specified timeout
+ * has elapsed since the last time the function was invoked.
+ *
+ * @param fn - The function to debounce.
+ * @param timeout - The number of milliseconds to wait before invoking the function.
+ * @returns A debounced version of the function that can be called with any arguments.
+ *          The debounced function also has a `cancel` method to clear the timeout.
  */
 export declare const debounce: (fn: (...rest: any) => any, timeout?: number) => {
     (...args: any): void;

package/dist/types/_dedupe.d.ts

@@ -1,4 +1,47 @@
-export declare const dedupe: (list: any[], key?: string) => any[];
-export declare const flatten: (list: any[]) => any[];
-export declare const flattenAndDedupe: (list?: any[], key?: string) => any[];
-export declare const groupBy: <T extends KeyValue<any>>(list: T[], prop: keyof T, missingKey?: string) => KeyValue<T[]>;
+/**
+ * Remove duplicates from a list of objects based on a key or the entire object.
+ * If a key is provided, it will deduplicate based on the value of that key.
+ * If no key is provided, it will deduplicate based on the entire object.
+ * This is useful for normalizing data structures that may have nested arrays or objects.
+ *
+ * @param list
+ * @param key
+ * @typedef {T} AnyObject - A generic type representing list items.
+ * @returns {T[]} - A new array with duplicates removed.
+ */
+export declare const dedupe: <T extends AnyObject>(list: T[], key?: keyof T) => T[];
+/**
+ * Flatten a list of objects, removing any empty objects.
+ * It will flatten up to 5 levels deep and filter out any empty objects.
+ * This is useful for normalizing data structures that may have nested arrays or objects.
+ *
+ * @param list
+ * @typedef {T} AnyObject - A generic type representing list items.
+ * @returns {T[]} - A flattened array of objects.
+ */
+export declare const flatten: <T extends AnyObject>(list: T[]) => (T extends readonly (infer InnerArr)[] ? InnerArr extends readonly (infer InnerArr)[] ? InnerArr extends readonly (infer InnerArr)[] ? InnerArr extends readonly (infer InnerArr)[] ? InnerArr extends readonly (infer InnerArr)[] ? InnerArr : InnerArr : InnerArr : InnerArr : InnerArr : T)[];
+/**
+ * Flatten a list of objects and remove duplicates based on a key or the entire object.
+ * If a key is provided, it will deduplicate based on the value of that key.
+ * If no key is provided, it will deduplicate based on the entire object.
+ * This is useful for normalizing data structures that may have nested arrays or objects.
+ * Flattening is done first, followed by deduplication.
+ *
+ * @param list
+ * @param key
+ * @typedef {T} AnyObject - A generic type representing list items.
+ * @returns {T[]} - A new array with duplicates removed.
+ */
+export declare const flattenAndDedupe: <T extends AnyObject>(list?: T[][], key?: keyof T) => T[];
+/**
+ * Group a list of objects by a specific property.
+ * If the property is not present in an object, it will use the `missingKey` value as the key.
+ * This is useful for organizing data into categories based on a specific property.
+ *
+ * @param list
+ * @param prop
+ * @param missingKey
+ * @typedef {T} KeyValue - A generic type representing list items with key-value pairs.
+ * @returns {KeyValue<T[]>} - An object mapping keys to arrays of items.
+ */
+export declare const groupBy: <T extends KeyValue>(list: T[], prop: keyof T, missingKey?: string) => KeyValue<T[]>;

package/dist/types/_fetch.d.ts

@@ -5,19 +5,22 @@ declare interface FetchOptions {
     signal?: string | AbortSignal;
 }
 /**
- * Fetch helper
- * @param method
- * @param url
- * @param options.headers
- * @param options.body
- * @param options.signal
- * @internal
+ * Fetch utility function to make HTTP requests.
+ * It supports GET, POST, PUT, and DELETE methods.
+ * It automatically handles JSON responses and error codes.
+ * It also supports aborting requests using an AbortController.
+ *
+ * @param method - The HTTP method to use (GET, POST, PUT, DELETE).
+ * @param url - The URL to send the request to.
+ * @param options.headers - Headers to include in the request.
+ * @param options.body - The body of the request (for POST and PUT requests).
+ * @param options.signal - An AbortSignal to cancel the request.
+ * @returns A promise that resolves to the JSON response from the server.
+ * @throws An error if the request fails or if the response contains an error code.
  */
 export declare const _fetch: {
     (method: METHODS, url: string, { headers, body, signal }: FetchOptions): Promise<any>;
-    /** ***************** attach isAborted helper to fetch method *******************/
     isAborted({ name }: Error): boolean;
-    /** ***************** attach abort helper to fetch method *******************/
     abort(signal: string): void;
 };
 export {};

package/dist/types/_fileType.d.ts

@@ -1,5 +1,21 @@
+/**
+ * File type utility to get the file type from a MIME type.
+ * This utility provides a mapping of common MIME types to their human-readable names.
+ * It can be used to display file types in a user-friendly manner.
+ */
 declare const _default: {
+    /**
+     * Get the human-readable file type from a MIME type.
+     * This method looks up the MIME type in a predefined list
+     * and returns a user-friendly name.
+     *
+     * @param mime MIME type string, e.g. "application/pdf"
+     * @returns {string} - The human-readable file type.
+     */
     mime(mime?: string): any;
+    /**
+     * List of common MIME types and their human-readable names.
+     */
     mimeList: {
         "application/x-tika-msoffice": string;
         "application/x-tika-ooxml": string;