@webalternatif/js-core 1.6.3 → 1.6.4

package/docs/utils.md

@@ -14,23 +14,89 @@ import { utils } from '@webalternatif/js-core'
 <!-- GENERATED:utils -->
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+## equals
+
+[src/utils.js:35-77][1]
+
+Deeply compares two or more values for structural equality.
+
+All provided values must be deeply equal for the function to return `true`.
+Comparison is recursive and handles objects, arrays, and built-in types.
+
+### Parameters
+
+*   `values` **...any** Two or more values to compare.
+
+### Examples
+
+```javascript
+equals(1, 1) // => true
+equals(NaN, NaN) // => true
+equals([1, { a: 2 }], [1, { a: 2 }]) // => true
+equals({ a: 1 }, { a: 1, b: 2 }) // => false
+equals(
+  { a: { b: 1 } },
+  { a: { b: 1 } },
+  { a: { b: 1 } },
+) // => true
+
+const a = {}; a.self = a
+const b = {}; b.self = b
+equals(a, b) // => true
+
+equals(new Date(1000), new Date(1000)) // => true
+equals(new Date(1000), new Date(2000)) // => false
+
+equals(/abc/gi, /abc/gi) // => true
+equals(/abc/g, /abc/i)   // => false
+```
+
+Returns **[boolean][2]** `true` if all values are deeply equal, otherwise `false`.
+
+## noop
+
+[src/utils.js:84-84][3]
+
+No-operation function. Useful as a default callback or placeholder.
+
+Returns **void**&#x20;
+
+## sizeOf
+
+[src/utils.js:97-99][4]
+
+Returns the size of a collection. Can be an object, an array or string.
+
+### Parameters
+
+*   `v` **([Object][5] | [Array][6] | [string][7])** The value to count
+
+### Examples
+
+```javascript
+sizeOf([1, 2, 3])        // => 3
+sizeOf("hello")          // => 5
+sizeOf({ a: 1, b: 2 })   // => 2
+```
+
+Returns **[number][8]** The size of `v`
+
 ## flatten
 
-[src/utils.js:53-59][1]
+[src/utils.js:115-121][9]
 
-Recursively flattens an object or array into a single-level array.
+Recursively flattens values of an object or array into a single-level array.
 
 ### Parameters
 
-*   `o` **([Object][2] | [Array][3])** The object or array to flatten.
+*   `o` **([Object][5] | [Array][6])** The object or array to flatten.
 
 ### Examples
 
 Flatten an array of arrays
 
 ```javascript
-const result = flatten([1, [2, [3, 4]], 5]);
-console.log(result);
+const result = flatten([1, [2, [3, 4]], 5])
 // Output: [1, 2, 3, 4, 5]
 ```
 
@@ -38,38 +104,125 @@ Flatten an object
 
 ```javascript
 const result = flatten({ a: 1, b: [2, { c: 3 }], d: 4 });
-console.log(result);
 // Output: [1, 2, 3, 4]
 ```
 
-Returns **[Array][3]** A flattened array containing all the values from the input object or array.
+Returns **[Array][6]** A flattened array containing all the values from the input object or array.
+
+## strParseFloat
+
+[src/utils.js:134-140][10]
+
+Parses a number from a string.
+
+### Parameters
+
+*   `val` &#x20;
+
+### Examples
+
+```javascript
+strParseFloat("12.34")      // => 12.34
+strParseFloat("12,34")      // => 12.34
+strParseFloat(" 1 234,56 ") // => 1234.56
+```
+
+Returns **[number][8]**&#x20;
+
+## throttle
+
+[src/utils.js:165-188][11]
+
+Creates a throttled version of a function that only executes at most once
+every `wait` milliseconds.
+
+### Parameters
+
+*   `func` **[Function][12]** The function to throttle.
+*   `wait` **[number][8]** The number of milliseconds before execution of `func`.
+*   `leading` **[boolean][2]** if `true` run `func` a first time immediately. (optional, default `true`)
+*   `trailing` **[boolean][2]** if `true` run `func` one last time after timeout. (optional, default `true`)
+*   `context` **any** Optional `this` context to bind when invoking `func`. (optional, default `null`)
+
+### Examples
+
+```javascript
+const throttled = throttle(() => console.log('tick'), 1000)
+window.addEventListener('scroll', throttled)
+```
+
+```javascript
+// runs at the end
+const throttled = throttle(doSomething, 500, false, true)
+```
+
+```javascript
+// runs immediately
+const throttled = throttle(doSomething, 500, true, false)
+```
+
+Returns **[Function][12]** A throotled function
 
 ## debounce
 
-[src/utils.js:105-129][4]
+[src/utils.js:218-242][13]
 
 Creates a debounced function that delays the invocation of `func` until after `wait` milliseconds
 have elapsed since the last time the debounced function was invoked.
 
 ### Parameters
 
-*   `func` **[Function][5]** The function to debounce.
-*   `wait` **[number][6]** The number of milliseconds to delay.
-*   `immediate` **[boolean][7]** If true, execute `func` on the leading edge instead of the trailing. (optional, default `false`)
-*   `context` **[Object][2]** The context to bind to `func`. (optional, default `null`)
+*   `func` **[Function][12]** The function to debounce.
+*   `wait` **[number][8]** The number of milliseconds to delay.
+*   `immediate` **[boolean][2]** If true, execute `func` on the leading edge instead of the trailing. (optional, default `false`)
+*   `context` **any** The context to bind to `func`. (optional, default `null`)
+
+### Examples
+
+```javascript
+// Search input: only trigger search after user stops typing
+const debouncedSearch = debounce(query => {
+  api.search(query)
+}, 300)
+
+input.addEventListener('input', ev => {
+  debouncedSearch(ev.target.value)
+})
+```
+
+```javascript
+// Resize handler : run layout update only after resizing stops
+const debouncedResize = debounce(() => {
+  updateLayout()
+}, 500)
+
+window.addEventListener('resize', debouncedResize)
+```
+
+Returns **[Function][12]** The debounced function.
+
+[1]: https://github.com/webalternatif/js-core/blob/c59faf2628616256e5ee2499f03adb5e9a32460d/src/utils.js#L35-L77 "Source code on GitHub"
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+
+[3]: https://github.com/webalternatif/js-core/blob/c59faf2628616256e5ee2499f03adb5e9a32460d/src/utils.js#L84-L84 "Source code on GitHub"
+
+[4]: https://github.com/webalternatif/js-core/blob/c59faf2628616256e5ee2499f03adb5e9a32460d/src/utils.js#L97-L99 "Source code on GitHub"
+
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-Returns **[Function][5]** The debounced function.
+[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
 
-[1]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/utils.js#L53-L59 "Source code on GitHub"
+[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+[9]: https://github.com/webalternatif/js-core/blob/c59faf2628616256e5ee2499f03adb5e9a32460d/src/utils.js#L115-L121 "Source code on GitHub"
 
-[4]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/utils.js#L105-L129 "Source code on GitHub"
+[10]: https://github.com/webalternatif/js-core/blob/c59faf2628616256e5ee2499f03adb5e9a32460d/src/utils.js#L134-L140 "Source code on GitHub"
 
-[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+[11]: https://github.com/webalternatif/js-core/blob/c59faf2628616256e5ee2499f03adb5e9a32460d/src/utils.js#L165-L188 "Source code on GitHub"
 
-[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
 
-[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[13]: https://github.com/webalternatif/js-core/blob/c59faf2628616256e5ee2499f03adb5e9a32460d/src/utils.js#L218-L242 "Source code on GitHub"

package/package.json

@@ -12,11 +12,13 @@
     "name": "Ludovic Tarit",
     "email": "ludovic.tarit@webalternatif.com"
   },
-  "version": "1.6.3",
+  "version": "1.6.4",
   "type": "module",
   "types": "types/index.d.ts",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
+  "unpkg": "dist/umd/webf.umd.js",
+  "jsdelivr": "dist/umd/webf.umd.js",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
@@ -34,8 +36,9 @@
     "test:watch": "jest --watch",
     "build:esm": "babel src --out-dir dist/esm --extensions .js",
     "build:cjs": "cross-env BABEL_ENV=cjs babel src --out-dir dist/cjs --extensions .js",
-    "types": "tsc",
-    "build": "rm -rf dist && yarn build:esm && yarn build:cjs && yarn types",
+    "build:umd": "webpack --config webpack.config.cjs",
+    "build": "rm -rf dist && yarn build:esm && yarn build:cjs && yarn build:umd && yarn types",
+    "types": "rm -rf types && tsc",
     "docs": "node scripts/docs.js",
     "prepublishOnly": "yarn build",
     "prepare": "husky install"
@@ -63,10 +66,13 @@
     "lint-staged": "^16.2.7",
     "nodemon": "^3.1.9",
     "prettier": "^3.8.1",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "webpack": "^5.105.3",
+    "webpack-cli": "^6.0.1"
   },
   "files": [
     "dist",
+    "src",
     "types",
     "README.md",
     "docs",

package/src/Mouse.js

@@ -0,0 +1,73 @@
+import { isTouchDevice } from './is.js'
+
+class Mouse {
+    /**
+     * @param {Event} ev
+     * @param {Element} element
+     * @returns {{x: number, y: number}}
+     */
+    static getPosition(ev, element) {
+        ev = this.#getEvent(ev)
+        let rect = { left: 0, top: 0 }
+
+        if (element instanceof Element) {
+            const r = element.getBoundingClientRect()
+
+            rect = {
+                left: window.scrollX + r.left,
+                top: window.scrollY + r.top,
+            }
+        }
+
+        return {
+            x: ev.pageX - rect.left,
+            y: ev.pageY - rect.top,
+        }
+    }
+
+    /**
+     * @param {Event} ev
+     * @returns {{x: number, y: number}}
+     */
+    static getViewportPosition(ev) {
+        ev = this.#getEvent(ev)
+
+        return {
+            x: ev.clientX,
+            y: ev.clientY,
+        }
+    }
+
+    static getElement(ev) {
+        ev = this.#getEvent(ev)
+
+        return window.document.elementFromPoint(ev.clientX, ev.clientY)
+    }
+
+    /**
+     * @param {Event|{originalEvent?: Event}} ev
+     * @returns {Event}
+     */
+    static #getEvent(ev) {
+        ev = ev.originalEvent ?? ev
+
+        if (isTouchDevice()) {
+            const touch = ev.changedTouches?.[0] || ev.touches?.[0]
+
+            ev.clientX = touch.clientX
+            ev.clientY = touch.clientY
+            ev.pageX = touch.pageX
+            ev.pageY = touch.pageY
+        }
+
+        return ev
+    }
+}
+
+export default Mouse
+
+/* istanbul ignore else */
+if (typeof window !== 'undefined') {
+    window.webf = window.webf || {}
+    window.webf.mouse = Mouse
+}

package/src/Translator.js

@@ -0,0 +1,148 @@
+import { isFunction, isPlainObject } from './is.js'
+import { each, extend } from './traversal.js'
+
+/**
+ * @typedef {string|(()=>string)} TranslatorValue
+ */
+
+/**
+ * @typedef {Record<string,Record<string,Record<string,TranslatorValue>>>} TranslatorNsMapping
+ */
+
+/**
+ * @typedef {Record<string,Record<string,TranslatorValue>>} TranslatorCoreMapping
+ */
+
+/**
+ * @typedef {TranslatorNsMapping | TranslatorCoreMapping} TranslatorMapping
+ */
+
+class Translator {
+    /** @type string */
+    #lang
+
+    /** @type TranslatorMapping */
+    #mapping
+
+    /**
+     * @param {TranslatorMapping} mapping
+     * @param {string} [defaultLang]
+     */
+    constructor(mapping, defaultLang) {
+        this.#setMapping(mapping)
+        this.setLang(defaultLang)
+    }
+
+    #setMapping(mapping) {
+        let nsMapping = {},
+            coreMapping = {}
+
+        each(mapping, (ns, langs) => {
+            each(langs, (lang, trads) => {
+                if (isPlainObject(trads)) {
+                    if (undefined === nsMapping[ns]) nsMapping[ns] = {}
+                    nsMapping[ns][lang] = trads
+                } else {
+                    if (undefined === coreMapping[ns]) coreMapping[ns] = {}
+                    coreMapping[ns][lang] = trads
+                }
+            })
+        })
+
+        this.#mapping = extend(true, nsMapping, {
+            core: extend({}, nsMapping.core || {}, coreMapping),
+        })
+    }
+
+    /**
+     * @param {string} label
+     * @param {string} [lang]
+     * @param {string} [namespace='core']
+     * @returns {string}
+     */
+    translate(label, lang, namespace = 'core') {
+        lang = undefined === lang ? this.getLang() : lang
+
+        const translationExists =
+            undefined !== this.#mapping[namespace] &&
+            undefined !== this.#mapping[namespace][lang] &&
+            undefined !== this.#mapping[namespace][lang][label]
+
+        if (translationExists) {
+            const entry = this.#mapping[namespace][lang][label]
+            return this.#resolve(entry)
+        }
+
+        return 'en' !== lang ? this.translate(label, 'en', namespace) : label
+    }
+
+    /**
+     * @param {string} label
+     * @param {string} from - Language from.
+     * @param {string} to - Language to.
+     * @param {string} [namespace='core']
+     */
+    translateFrom(label, from, to, namespace = 'core') {
+        if (!label) return label
+
+        const mapNs = this.#mapping?.[namespace]
+        if (!mapNs) return label
+
+        const mapFrom = mapNs?.[from]
+        const mapTo = mapNs?.[to]
+        if (!mapFrom || !mapTo) return label
+
+        const key = this.#findKeyByValue(mapFrom, label)
+        if (!key) return label
+
+        const entryTo = mapTo[key]
+        const resolvedTo = this.#resolve(entryTo)
+
+        return resolvedTo ?? label
+    }
+
+    _(...args) {
+        return this.translate(...args)
+    }
+
+    getLang() {
+        return this.#lang
+    }
+
+    setLang(lang) {
+        if (!lang) {
+            if (typeof navigator !== 'undefined' && navigator.language) {
+                lang = navigator.language
+            } else if (typeof process !== 'undefined' && process.env) {
+                lang = process.env.LANG || process.env.LC_ALL || process.env.LC_MESSAGES
+            }
+        }
+
+        this.#lang = (lang || 'en').trim().toLowerCase().slice(0, 2)
+    }
+
+    #findKeyByValue(entries, label) {
+        for (const key in entries) {
+            const resolved = this.#resolve(entries[key])
+            if (resolved === label) return key
+        }
+
+        return null
+    }
+
+    #resolve(entry) {
+        if (isFunction(entry)) {
+            return entry()
+        }
+
+        return entry
+    }
+}
+
+export default Translator
+
+/* istanbul ignore next */
+if (typeof window !== 'undefined') {
+    window.webf = window.webf || {}
+    window.webf.Translator = Translator
+}

package/src/array.js

@@ -0,0 +1,136 @@
+import { each, map } from './traversal.js'
+import { isArray, isInteger, isObject, isString, isUndefined } from './is.js'
+import { round } from './math.js'
+import { equals } from './utils.js'
+
+/**
+ * Checks if a value exists in an array or an object
+ *
+ * @param {any} value the searched value
+ * @param {Object|Array} arr the array
+ * @param {number} [index=0] if provided, search from this index
+ * @param {boolean} [strict=false] if true, search is done with strict equality
+ * @returns {boolean}
+ *
+ * @example
+ * inArray(2, [1, 2, 3]) => true
+ *
+ * @example
+ * inArray({a: 1}, {a: 1, b: 2}) // => true
+ *
+ * @example
+ * inArray(5, [1, 2, 3]) // => false
+ */
+export const inArray = function (value, arr, index = 0, strict = false) {
+    let ret = false
+
+    each(arr, (i, val) => {
+        if (i >= index) {
+            if (strict) {
+                if (val === value) {
+                    ret = true
+                    return false
+                }
+            } else {
+                if (isObject(value) && isObject(val)) {
+                    ret = equals(val, value)
+                    return false
+                } else if (isArray(value) && isObject(val)) {
+                    ret = equals(val, value)
+                    return false
+                    // eslint-disable-next-line eqeqeq
+                } else if (val == value) {
+                    ret = true
+                    return false
+                }
+            }
+        }
+    })
+
+    return ret
+}
+
+/**
+ * Returns the first index at which a given element can be found in an array or a string.
+ * or -1 if it is not present.
+ *
+ * @param {Array<any>|string} arr - The array to search in
+ * @param {any} elt - The element to search for
+ * @param {number} [from] - The index to start the search from. Can be negative.
+ * @returns {number} - The index of the element, or -1 if not found
+ */
+export const indexOf = function (arr, elt, from = 0) {
+    const a = isString(arr) ? map(arr, (_, a) => a) : arr
+
+    from = from < 0 ? Math.ceil(from) + a.length : Math.floor(from)
+
+    for (; from < a.length; from++) {
+        if (from in a && a[from] === elt) {
+            return from
+        }
+    }
+
+    return -1
+}
+
+/**
+ * Returns the last index at which a given element can be found in an array or a string.
+ * or -1 if it is not present.
+ *
+ * @param {Array<any>|string} arr - The array to search in
+ * @param {any} elt - The element to search for
+ * @param {number} [from] - The index to start the search from. Can be negative.
+ * @returns {number} - The index of the element, or -1 if not found
+ */
+export const lastIndexOf = function (arr, elt, from = -1) {
+    const a = isString(arr) ? map(arr, (_, a) => a) : arr
+
+    from = from < 0 ? a.length + Math.ceil(from) : Math.floor(from)
+
+    for (; from >= 0; from--) {
+        if (from in a && a[from] === elt) {
+            return from
+        }
+    }
+
+    return -1
+}
+
+export const arrayUnique = function (arr) {
+    return arr.filter((el, index, arr) => index === indexOf(arr, el))
+}
+
+export const array_unique = arrayUnique
+
+export const arrayDiff = (array1, array2, strict = false) => {
+    return array1.filter((item) => !inArray(item, array2, 0, strict))
+}
+
+export const array_diff = arrayDiff
+
+export const range = function (size, startAt = 0, step = 1) {
+    size = round(size)
+    step = round(step)
+
+    const rng = []
+
+    if (isUndefined(startAt) || size < 1 || step === 0 || size < Math.abs(step)) {
+        return rng
+    }
+
+    const end = size * step
+
+    if (isString(startAt)) {
+        startAt = startAt.charCodeAt(0)
+
+        for (let i = 0; step > 0 ? i < end : i > end; i += step) {
+            rng.push(String.fromCharCode(startAt + i))
+        }
+    } else if (isInteger(startAt)) {
+        for (let i = 0; step > 0 ? i < end : i > end; i += step) {
+            rng.push(startAt + i)
+        }
+    }
+
+    return rng
+}