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

package/src/_isType.ts

@@ -21,23 +21,54 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/**
+ * Check if a value is undefined.
+ * @param value - The value to check.
+ * @returns true if the value is undefined, false otherwise.
+ */
 export const isUndefined = (value: AnyObject): value is undefined => {
   return value === undefined;
 };
 
+/**
+ * Check if a value is null.
+ * @param value - The value to check.
+ * @returns true if the value is null, false otherwise.
+ */
 export const isNull = (value: AnyObject): value is null => {
   return value === null;
 };
 
-export const isNil = (val: AnyObject): val is undefined => {
+/**
+ * Check if a value is either null or undefined.
+ * @param val - The value to check.
+ * @returns true if the value is null or undefined, false otherwise.
+ */
+export const isNil = (val: AnyObject): val is null | undefined => {
   return val === undefined || val === null;
 };
+
+export const isDefined = (val: AnyObject): boolean => !isNil(val) && val !== "";
+
+/**
+ * Check if a value is empty.
+ * A value is considered empty if it is:
+ * - undefined
+ * - null
+ * - an empty string
+ * - an empty array
+ * - an empty object
+ * - an empty Map or Set
+ * - a boolean, number, or bigint (not empty)
+ * @param val - The value to check.
+ * @returns true if the value is empty, false otherwise.
+ */
 export const isEmpty = (val: AnyObject): val is undefined => {
   if (val instanceof Date) return false;
   if (isNil(val) || val === "") {
     return true;
   }
-  if (Array.isArray(val) && val.filter(Boolean).length === 0) {
+  if (Array.isArray(val) && val.filter(isDefined).length === 0) {
     return true;
   }
   if (val instanceof Map || val instanceof Set) return val.size === 0;
@@ -47,6 +78,16 @@ export const isEmpty = (val: AnyObject): val is undefined => {
   return !!val && typeof val === "object" && Object.entries(val).length === 0;
 };
 
+/**
+ * Check if a value is an object.
+ * An object is considered valid if it is:
+ * - not null or undefined
+ * - not a Date instance
+ * - of type 'object'
+ * - not an array
+ * @param val - The value to check.
+ * @returns true if the value is an object, false otherwise.
+ */
 export const isObject = (val: AnyObject): val is KeyValue => {
   return (
     !isNil(val) &&
@@ -55,21 +96,60 @@ export const isObject = (val: AnyObject): val is KeyValue => {
     !Array.isArray(val)
   );
 };
+
+/**
+ * Check if a value is an array.
+ * An array is considered valid if it is:
+ * - not null or undefined
+ * - an instance of Array
+ * @param val - The value to check.
+ * @returns true if the value is an array, false otherwise.
+ */
 export const isArray = <T = AnyObject>(val: AnyObject): val is T[] => {
   return Array.isArray(val);
 };
 
+/**
+ * Check if a value is a string.
+ * A string is considered valid if it is:
+ * - not null or undefined
+ * - of type 'string'
+ * @param value - The value to check.
+ * @returns true if the value is a string, false otherwise.
+ */
 export const isString = (value: AnyObject): value is string => {
   return typeof value === "string";
 };
 
+/**
+ * Check if a value is a number.
+ * A number is considered valid if it is:
+ * - not null or undefined
+ * - of type 'number'
+ * @param value - The value to check.
+ * @returns true if the value is a number, false otherwise.
+ */
 export const isNumber = (value: AnyObject): value is number => {
   return typeof value === "number";
 };
 
+/**
+ * Check if a value is a boolean.
+ * A boolean is considered valid if it is:
+ * - not null or undefined
+ * - of type 'boolean'
+ */
 export const isBoolean = (value: AnyObject): value is boolean => {
   return typeof value === "boolean";
 };
+
+/**
+ * Check if a value is a true.
+ * A value is considered true if it is:
+ * - strictly equal to true
+ * - equal to 1
+ * - a string that is "yes" or "true" (case insensitive)
+ */
 export const isTrue = (value: AnyObject = ""): value is true => {
   return (
     value === true ||
@@ -78,6 +158,14 @@ export const isTrue = (value: AnyObject = ""): value is true => {
     value?.toString().toLowerCase() === "true"
   );
 };
+
+/**
+ * Check if a value is false.
+ * A value is considered false if it is:
+ * - strictly equal to false
+ * - equal to 0
+ * - a string that is "no" or "false" (case insensitive)
+ */
 export const isFalse = (value: AnyObject = ""): value is false => {
   return (
     value === false ||
@@ -87,6 +175,17 @@ export const isFalse = (value: AnyObject = ""): value is false => {
   );
 };
 
+/**
+ * Check if a value is a valid color.
+ * A color is considered valid if it:
+ * - starts with a '#' (hex color)
+ * - starts with 'rgb' (RGB color)
+ * - starts with 'hsl' (HSL color)
+ * - starts with 'lab' (Lab color)
+ * - is equal to 'transparent'
+ * @param color - The value to check.
+ * @returns true if the value is a valid color, false otherwise.
+ */
 export const isColor = (color: string) =>
   color.startsWith?.("#") ||
   color.startsWith?.("rgb") ||
@@ -94,12 +193,27 @@ export const isColor = (color: string) =>
   color.startsWith?.("lab") ||
   color === "transparent";
 
+/**
+ * Check if a value is a valid SVG path.
+ * A valid SVG path is a string that:
+ * - starts with 'M' or 'm' (move to command)
+ * - contains at least one digit or decimal point
+ * - ends with 'Z' or 'z' (close path command)
+ * @param value - The value to check.
+ * @returns true if the value is a valid SVG path, false otherwise.
+ */
 export const isSvgPath = (value: AnyObject): value is string => {
   return (
     typeof value === "string" && value.match(/^[Mm][\d.].*[\dzZ]$/) !== null
   );
 };
 
+/**
+ * Check if the document is in RTL (Right-to-Left) mode.
+ * This function checks the computed style of the document's root element
+ * to determine if the direction is set to 'rtl'.
+ * @returns true if the document is in RTL mode, false otherwise.
+ */
 export const isRtl = () => {
   return getComputedStyle(document.documentElement).direction === "rtl";
 };

package/src/_lonlat.ts

@@ -0,0 +1,135 @@
+/*
+ * React Fabric
+ * @version: 1.0.0
+ *
+ *
+ * The MIT License (MIT)
+ * Copyright (c) 2025 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+ * and associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+ * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+import { isArray, isEmpty, isObject, isString } from "./_isType";
+
+export type LngLatLike =
+  | {
+      lng: number;
+      lat: number;
+    }
+  | {
+      lon: number;
+      lat: number;
+    }
+  | {
+      longitude: number;
+      latitude: number;
+    }
+  | [lon: number | string, lat: number | string]
+  | [lon: number | string, lat: number | string, z: number | string]
+  | string;
+
+export const getLatitudeLongitude = (
+  lonLat: LngLatLike,
+): { latitude: number; longitude: number } => {
+  const [lon, lat] = convertLatLng(lonLat);
+  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.
+ */
+export const convertLatLng = (
+  lonLat: LngLatLike,
+): [lon: number, lat: number] => {
+  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)) {
+    const [lat, lon] = lonLat.split(",");
+    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.
+ */
+const convertToDMS = (coord: number, isLat = false) => {
+  const degree = Math.floor(Math.abs(coord));
+  const hour = (Math.abs(coord) - degree) * 60;
+  const minute = (hour - Math.floor(hour)) * 60;
+
+  return `${degree}˚${Math.floor(hour)}'${minute.toFixed(2)}"${
+    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"
+ * ```
+ */
+export const getLocationAsText = (latlon: LngLatLike) => {
+  const [lon, lat] = convertLatLng(latlon);
+  return `${convertToDMS(lat, true)}, ${convertToDMS(lon)}`;
+};

package/src/_mergeRefs.ts

@@ -23,6 +23,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.
+ */
 export const mergeRefs =
   (...refs: AnyObject[]) =>
   (el: AnyObject) => {

package/src/_tokenize.ts

@@ -24,10 +24,14 @@
 import { isArray, isEmpty } from "./_isType";
 
 /**
- * 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].
  */
 export const tokenize = (str: string, keywords?: string | string[]) => {
   if (isEmpty(keywords)) {
@@ -57,6 +61,14 @@ export const tokenize = (str: string, keywords?: string | string[]) => {
   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.
+ */
 export const iconToken = (str: string) => {
   const split = str.trim().split(" ");
   const first = split[0];

package/src/getImageColorset.ts

@@ -23,6 +23,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.
+ */
 export const getImageColorset = (el: HTMLImageElement) => {
   // create canvas
   const canvas = document.createElement("canvas");
@@ -56,8 +71,8 @@ export const getImageColorset = (el: HTMLImageElement) => {
         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/src/index.ts

@@ -38,6 +38,7 @@ export * from "./_hash";
 export * from "./_interpolate";
 export * from "./_isEqual";
 export * from "./_isType";
+export * from "./_lonlat";
 export * from "./_mergeRefs";
 export * from "./_tokenize";
 export { getImageColorset } from "./getImageColorset";

package/src/useLogger.ts

@@ -198,7 +198,15 @@ const 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.
  */
 export const useLogger = (mod?: string) => ({
   timer(process: string) {