@react-hive/honey-utils 4.2.0 → 5.0.0

package/dist/index.dev.cjs

@@ -12,7 +12,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   getFocusableHtmlElements: () => (/* binding */ getFocusableHtmlElements)
 /* harmony export */ });
-/* harmony import */ var _a11y__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/a11y */ "./src/a11y/index.ts");
+/* harmony import */ var _is_html_element_focusable__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./is-html-element-focusable */ "./src/a11y/focus/is-html-element-focusable.ts");
 
 /**
  * Collects all focusable descendant elements within a container.
@@ -25,7 +25,7 @@ __webpack_require__.r(__webpack_exports__);
  *
  * @returns An array of focusable HTMLElements in DOM order.
  */
-const getFocusableHtmlElements = (container) => Array.from(container.querySelectorAll('*')).filter(_a11y__WEBPACK_IMPORTED_MODULE_0__.isHtmlElementFocusable);
+const getFocusableHtmlElements = (container) => Array.from(container.querySelectorAll('*')).filter(_is_html_element_focusable__WEBPACK_IMPORTED_MODULE_0__.isHtmlElementFocusable);
 
 
 /***/ },
@@ -67,16 +67,26 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _dom__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/dom */ "./src/dom/index.ts");
 
 const FOCUSABLE_HTML_TAGS = ['INPUT', 'SELECT', 'TEXTAREA', 'BUTTON', 'A'];
+/**
+ * A `tabindex` attribute's value, read by the HTML rules for parsing integers - leading whitespace
+ * and a sign allowed, anything after the digits ignored - or `null` where there is none to read.
+ */
+const parseTabIndex = (value) => {
+    const match = value === null ? null : /^\s*([+-]?\d+)/.exec(value);
+    return match ? parseInt(match[1], 10) : null;
+};
 /**
  * Determines whether an HTMLElement is focusable under standard browser rules.
  *
  * The function checks a combination of factors:
- * - The element must be rendered (not `display: none` or `visibility: hidden`).
- * - Disabled form controls are never focusable.
- * - Elements with `tabindex="-1"` are intentionally removed from the focus order.
+ * - The element must be rendered: neither it nor an ancestor has `display: none`, and it is not
+ *   `visibility: hidden`.
+ * - Disabled form controls are never focusable - including those inside a disabled `<fieldset>`.
+ * - Elements with a negative `tabindex` are intentionally removed from the focus order.
+ * - Any element with a valid, non-negative `tabindex` is focusable. A `tabindex` that is not an
+ *   integer is ignored, as browsers ignore it.
  * - Certain native HTML elements are inherently focusable (e.g. inputs, buttons, anchors with `href`).
- * - Elements with `contenteditable="true"` are treated as focusable.
- * - Any element with a valid `tabindex` (not null) is considered focusable.
+ * - Editable elements (`contenteditable`) are treated as focusable.
  *
  * This logic approximates how browsers and the accessibility tree
  * determine real-world focusability—not just tabindex presence.
@@ -89,28 +99,30 @@ const isHtmlElementFocusable = (element) => {
     if (!element) {
         return false;
     }
-    const style = window.getComputedStyle(element);
-    if (style.visibility === 'hidden' || style.display === 'none') {
+    if (window.getComputedStyle(element).visibility === 'hidden') {
         return false;
     }
-    if ('disabled' in element && element.disabled) {
-        return false;
+    // `display: none` does not inherit, so a hidden ancestor has to be looked for
+    for (let node = element; node; node = node.parentElement) {
+        if (window.getComputedStyle(node).display === 'none') {
+            return false;
+        }
     }
-    // Explicitly removed from tab order
-    const tabIndex = element.getAttribute('tabindex');
-    if (tabIndex === '-1') {
+    // `:disabled` covers a control inside a disabled `<fieldset>`, which `element.disabled` does not
+    if (element.matches(':disabled')) {
         return false;
     }
+    const tabIndex = parseTabIndex(element.getAttribute('tabindex'));
+    if (tabIndex !== null) {
+        return tabIndex >= 0;
+    }
     if (FOCUSABLE_HTML_TAGS.includes(element.tagName)) {
         if ((0,_dom__WEBPACK_IMPORTED_MODULE_0__.isAnchorHtmlElement)(element)) {
             return element.href !== '';
         }
         return true;
     }
-    if ((0,_dom__WEBPACK_IMPORTED_MODULE_0__.isContentEditableHtmlElement)(element)) {
-        return true;
-    }
-    return tabIndex !== null;
+    return (0,_dom__WEBPACK_IMPORTED_MODULE_0__.isContentEditableHtmlElement)(element);
 };
 
 
@@ -126,7 +138,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   moveFocusWithinContainer: () => (/* binding */ moveFocusWithinContainer)
 /* harmony export */ });
-/* harmony import */ var _a11y__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/a11y */ "./src/a11y/index.ts");
+/* harmony import */ var _get_focusable_html_elements__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./get-focusable-html-elements */ "./src/a11y/focus/get-focusable-html-elements.ts");
 
 /**
  * Moves focus to the next or previous focusable element within a container.
@@ -158,7 +170,7 @@ const moveFocusWithinContainer = (direction, container = null, { wrap = true, ge
     if (!activeElement || !scope) {
         return;
     }
-    const focusableElements = (0,_a11y__WEBPACK_IMPORTED_MODULE_0__.getFocusableHtmlElements)(scope);
+    const focusableElements = (0,_get_focusable_html_elements__WEBPACK_IMPORTED_MODULE_0__.getFocusableHtmlElements)(scope);
     if (focusableElements.length === 0) {
         return;
     }
@@ -232,11 +244,14 @@ __webpack_require__.r(__webpack_exports__);
  * @template T - The type of the items in the array.
  *
  * @param array - The input array to be chunked.
- * @param size - The size of each chunk. Must be greater than 0.
+ * @param size - The size of each chunk. Must be a positive whole number.
  *
  * @returns An array of chunks, where each chunk is an array of the specified size
  *          (except possibly the last chunk, which may be smaller).
  *
+ * @throws {Error} When `size` is not a positive whole number - a fractional size would give
+ *         chunks of other sizes, and `Infinity` none at all.
+ *
  * @example
  * ```ts
  * chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
@@ -244,7 +259,7 @@ __webpack_require__.r(__webpack_exports__);
  * ```
  */
 const chunk = (array, size) => {
-    (0,_guards__WEBPACK_IMPORTED_MODULE_0__.assert)(size > 0, 'Chunk size must be greater than 0');
+    (0,_guards__WEBPACK_IMPORTED_MODULE_0__.assert)(Number.isInteger(size) && size > 0, 'Chunk size must be a positive whole number');
     return Array.from({ length: Math.ceil(array.length / size) }, (_, index) => array.slice(index * size, (index + 1) * size));
 };
 
@@ -298,7 +313,7 @@ __webpack_require__.r(__webpack_exports__);
  * Composes multiple unary functions into a single function, applying them from **right to left**.
  *
  * Often used for building functional pipelines where the innermost function runs first.
- * Types are inferred up to 5 chained functions for full type safety.
+ * Types are inferred up to 5 chained functions for full type safety. Beyond that, it falls back to the unknown.
  *
  * @param fns - A list of unary functions to compose.
  *
@@ -412,6 +427,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   isArray: () => (/* reexport safe */ _is_array__WEBPACK_IMPORTED_MODULE_7__.isArray),
 /* harmony export */   isEmptyArray: () => (/* reexport safe */ _is_empty_array__WEBPACK_IMPORTED_MODULE_8__.isEmptyArray),
 /* harmony export */   pipe: () => (/* reexport safe */ _pipe__WEBPACK_IMPORTED_MODULE_0__.pipe),
+/* harmony export */   toMapBy: () => (/* reexport safe */ _to_map_by__WEBPACK_IMPORTED_MODULE_11__.toMapBy),
 /* harmony export */   toggleArrayItem: () => (/* reexport safe */ _toggle_array_item__WEBPACK_IMPORTED_MODULE_10__.toggleArrayItem),
 /* harmony export */   unique: () => (/* reexport safe */ _unique__WEBPACK_IMPORTED_MODULE_5__.unique)
 /* harmony export */ });
@@ -426,6 +442,8 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _is_empty_array__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(/*! ./is-empty-array */ "./src/array/is-empty-array.ts");
 /* harmony import */ var _get_adjacent_items__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(/*! ./get-adjacent-items */ "./src/array/get-adjacent-items.ts");
 /* harmony import */ var _toggle_array_item__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(/*! ./toggle-array-item */ "./src/array/toggle-array-item.ts");
+/* harmony import */ var _to_map_by__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(/*! ./to-map-by */ "./src/array/to-map-by.ts");
+
 
 
 
@@ -451,7 +469,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   intersection: () => (/* binding */ intersection)
 /* harmony export */ });
-/* harmony import */ var _array__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/array */ "./src/array/index.ts");
+/* harmony import */ var _unique__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./unique */ "./src/array/unique.ts");
 
 /**
  * Returns an array containing elements that exist in all provided arrays.
@@ -460,7 +478,8 @@ __webpack_require__.r(__webpack_exports__);
  *
  * @param arrays - Two or more arrays to find common elements from.
  *
- * @returns A new array containing only the elements that exist in all input arrays.
+ * @returns A new array containing only the elements that exist in all input arrays, each once, in
+ *          the order of the first array.
  *
  * @example
  * ```ts
@@ -472,11 +491,8 @@ const intersection = (...arrays) => {
     if (arrays.length === 0) {
         return [];
     }
-    if (arrays.length === 1) {
-        return [...arrays[0]];
-    }
     const [first, ...rest] = arrays;
-    const uniqueFirst = (0,_array__WEBPACK_IMPORTED_MODULE_0__.unique)(first);
+    const uniqueFirst = (0,_unique__WEBPACK_IMPORTED_MODULE_0__.unique)(first);
     return uniqueFirst.filter(item => rest.every(array => array.includes(item)));
 };
 
@@ -499,6 +515,12 @@ __webpack_require__.r(__webpack_exports__);
  * @param value - The value to check.
  *
  * @returns `true` if the value is an array; otherwise, `false`.
+ *
+ * @example
+ * ```ts
+ * isArray([1, 2]); // true
+ * isArray('12'); // false
+ * ```
  */
 const isArray = (value) => Array.isArray(value);
 
@@ -515,7 +537,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   isEmptyArray: () => (/* binding */ isEmptyArray)
 /* harmony export */ });
-/* harmony import */ var _array__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/array */ "./src/array/index.ts");
+/* harmony import */ var _is_array__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./is-array */ "./src/array/is-array.ts");
 
 /**
  * Checks if a value is an empty array.
@@ -523,8 +545,15 @@ __webpack_require__.r(__webpack_exports__);
  * @param value - The value to check.
  *
  * @returns `true` if the value is an empty array; otherwise, `false`.
+ *
+ * @example
+ * ```ts
+ * isEmptyArray([]); // true
+ * isEmptyArray([1]); // false
+ * isEmptyArray({}); // false
+ * ```
  */
-const isEmptyArray = (value) => (0,_array__WEBPACK_IMPORTED_MODULE_0__.isArray)(value) && value.length === 0;
+const isEmptyArray = (value) => (0,_is_array__WEBPACK_IMPORTED_MODULE_0__.isArray)(value) && value.length === 0;
 
 
 /***/ },
@@ -563,6 +592,31 @@ __webpack_require__.r(__webpack_exports__);
 const pipe = (...fns) => (arg) => fns.reduce((prev, fn) => fn(prev), arg);
 
 
+/***/ },
+
+/***/ "./src/array/to-map-by.ts"
+/*!********************************!*\
+  !*** ./src/array/to-map-by.ts ***!
+  \********************************/
+(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   toMapBy: () => (/* binding */ toMapBy)
+/* harmony export */ });
+/**
+ * Overloaded rather than given a default `Value`, which TypeScript would take from whatever type the
+ * result is assigned to - so a map of items could be declared a map of anything.
+ */
+function toMapBy(items, getKey, getValue) {
+    const map = new Map();
+    items.forEach((item, index) => {
+        map.set(getKey(item, index), getValue ? getValue(item, index) : item);
+    });
+    return map;
+}
+
+
 /***/ },
 
 /***/ "./src/array/toggle-array-item.ts"
@@ -663,9 +717,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   runSequential: () => (/* binding */ runSequential),
 /* harmony export */   someAsync: () => (/* binding */ someAsync)
 /* harmony export */ });
-/* harmony import */ var _array__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/array */ "./src/array/index.ts");
-/* harmony import */ var _function__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ~/function */ "./src/function/index.ts");
-
+/* harmony import */ var _function__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/function */ "./src/function/index.ts");
 
 /**
  * Checks if a value is a Promise.
@@ -676,7 +728,7 @@ __webpack_require__.r(__webpack_exports__);
  *
  * @returns `true` if the value is a Promise; otherwise, `false`.
  */
-const isPromise = (value) => (0,_function__WEBPACK_IMPORTED_MODULE_1__.isFunction)(value?.then);
+const isPromise = (value) => (0,_function__WEBPACK_IMPORTED_MODULE_0__.isFunction)(value?.then);
 /**
  * Asynchronously iterates over an array and executes an async function on each item sequentially,
  * collecting the results.
@@ -789,12 +841,15 @@ const filterSequential = async (array, predicate) => {
  * ```
  */
 const filterParallel = async (array, predicate) => {
-    const results = await runParallel(array, async (item, index, array) => (await predicate(item, index, array)) ? item : false);
-    return (0,_array__WEBPACK_IMPORTED_MODULE_0__.compact)(results);
+    const keep = await runParallel(array, predicate);
+    return array.filter((_, index) => keep[index]);
 };
 /**
  * Asynchronously checks if at least one element in the array satisfies the async condition.
  *
+ * Runs one item at a time, in order, and stops at the first item that satisfies it - as
+ * `Array.prototype.some` does.
+ *
  * @param array - The array of items to check.
  * @param predicate - An async function that returns a boolean.
  *
@@ -811,6 +866,9 @@ const someAsync = async (array, predicate) => {
 /**
  * Asynchronously checks if all elements in the array satisfy the async condition.
  *
+ * Runs one item at a time, in order, and stops at the first item that fails it - as
+ * `Array.prototype.every` does.
+ *
  * @param array - The array of items to check.
  * @param predicate - An async function that returns a boolean.
  *
@@ -846,6 +904,9 @@ const reduceAsync = async (array, fn, initialValue) => {
 /**
  * Asynchronously finds the first element that satisfies the async condition.
  *
+ * Runs one item at a time, in order, and stops at the first match - as `Array.prototype.find`
+ * does.
+ *
  * @param array - The array of items to search.
  * @param predicate - An async function that returns a boolean.
  *
@@ -946,7 +1007,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   retry: () => (/* binding */ retry)
 /* harmony export */ });
-/* harmony import */ var _async__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/async */ "./src/async/index.ts");
+/* harmony import */ var _delay__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./delay */ "./src/async/delay.ts");
 
 /**
  * Wraps an asynchronous function with retry logic.
@@ -956,7 +1017,7 @@ __webpack_require__.r(__webpack_exports__);
  *
  * Useful for operations that may fail intermittently, such as network requests.
  *
- * @template Task - The type of the async function to wrap.
+ * @template Args - The arguments the async function takes.
  * @template TaskResult - The result type of the async function.
  *
  * @param task - The async function to wrap with retry logic.
@@ -990,18 +1051,19 @@ __webpack_require__.r(__webpack_exports__);
  * ```
  */
 const retry = (task, { maxAttempts = 3, delayMs = 300, backoff = true, onRetry } = {}) => {
+    const attempts = Math.max(1, maxAttempts);
     return async (...args) => {
         let lastError;
-        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        for (let attempt = 1; attempt <= attempts; attempt++) {
             try {
                 return await task(...args);
             }
             catch (e) {
                 lastError = e;
-                if (attempt < maxAttempts) {
+                if (attempt < attempts) {
                     onRetry?.(attempt, e);
                     const delayTime = backoff ? delayMs * 2 ** (attempt - 1) : delayMs;
-                    await (0,_async__WEBPACK_IMPORTED_MODULE_0__.delay)(delayTime);
+                    await (0,_delay__WEBPACK_IMPORTED_MODULE_0__.delay)(delayTime);
                 }
             }
         }
@@ -1022,8 +1084,6 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   timeout: () => (/* binding */ timeout)
 /* harmony export */ });
-/* harmony import */ var _async__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/async */ "./src/async/index.ts");
-
 /**
  * Wraps a promise with a timeout. If the promise does not settle within the specified time,
  * it will reject with a timeout error.
@@ -1047,15 +1107,18 @@ __webpack_require__.r(__webpack_exports__);
  * ```
  */
 const timeout = async (promise, timeoutMs, errorMessage = 'Operation timed out') => {
-    const timeoutId = null;
+    let timeoutId = null;
     try {
         return await Promise.race([
             promise,
-            (0,_async__WEBPACK_IMPORTED_MODULE_0__.delay)(timeoutMs).then(() => Promise.reject(new Error(errorMessage))),
+            new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(new Error(errorMessage)), timeoutMs);
+            }),
         ]);
     }
     finally {
-        if (timeoutId) {
+        // Cleared however the race ends, so a settled promise leaves no timer behind
+        if (timeoutId !== null) {
             clearTimeout(timeoutId);
         }
     }
@@ -1157,8 +1220,17 @@ const DATA_TRANSFER_JSON_MIME = 'application/json';
  *
  * Useful for drag-and-drop communication between elements.
  *
- * @param dataTransfer DataTransfer instance from a drag event.
- * @param data Data to serialize.
+ * @template T - The type of the data.
+ *
+ * @param dataTransfer - DataTransfer instance from a drag event.
+ * @param data - Data to serialize.
+ *
+ * @example
+ * ```ts
+ * element.addEventListener('dragstart', event => {
+ *   setDataTransferJson(event.dataTransfer, { id: 'card-1' });
+ * });
+ * ```
  */
 const setDataTransferJson = (dataTransfer, data) => {
     dataTransfer.setData(DATA_TRANSFER_JSON_MIME, JSON.stringify(data));
@@ -1166,9 +1238,18 @@ const setDataTransferJson = (dataTransfer, data) => {
 /**
  * Retrieves and parses JSON data from a DataTransfer object.
  *
- * @param dataTransfer DataTransfer instance from a drop event.
+ * @template Value - The type the JSON is expected to have.
+ *
+ * @param dataTransfer - DataTransfer instance from a drop event.
  *
  * @returns Parsed JSON value or null if not present or invalid.
+ *
+ * @example
+ * ```ts
+ * element.addEventListener('drop', event => {
+ *   const card = getDataTransferJson<{ id: string }>(event.dataTransfer);
+ * });
+ * ```
  */
 const getDataTransferJson = (dataTransfer) => {
     const rawData = dataTransfer.getData(DATA_TRANSFER_JSON_MIME);
@@ -1205,8 +1286,9 @@ const cloneBlob = (blob) => new Blob([blob], { type: blob.type });
 /**
  * Returns the bounding DOMRect of an element based on offset and client dimensions.
  *
- * This utility is useful when you need a stable, layout-based rect
- * without triggering a reflow via `getBoundingClientRect()`.
+ * Unlike `getBoundingClientRect()`, the rect is the element's layout box, before any CSS
+ * transform - so it stays put while the element or its container is being translated or scaled.
+ * Reading it still needs layout, as `getBoundingClientRect()` does.
  *
  * @param element - The target HTML element.
  * @returns A `DOMRect` representing the element’s offset position and size.
@@ -1228,14 +1310,18 @@ const isAnchorHtmlElement = (element) => element.tagName === 'A';
 /**
  * Checks whether an element is explicitly marked as contenteditable.
  *
- * Browsers treat elements with `contenteditable="true"` as focusable,
- * even if they are not normally keyboard-focusable.
+ * Browsers treat editable elements as focusable, even if they are not normally
+ * keyboard-focusable. An element is editable with `contenteditable` set to `""` (the bare
+ * attribute), `"true"` or `"plaintext-only"`, in any case.
  *
  * @param element - The element to inspect.
  *
- * @returns True if `contenteditable="true"` is set.
+ * @returns True if the element's own `contenteditable` makes it editable.
  */
-const isContentEditableHtmlElement = (element) => element.getAttribute('contenteditable') === 'true';
+const isContentEditableHtmlElement = (element) => {
+    const value = element.getAttribute('contenteditable');
+    return value !== null && ['', 'true', 'plaintext-only'].includes(value.toLowerCase());
+};
 
 
 /***/ },
@@ -1274,8 +1360,8 @@ __webpack_require__.r(__webpack_exports__);
  * @param options - Optional configuration controlling filename and link target.
  */
 const downloadFile = (file, { fileName, target } = {}) => {
-    // Browser guard (SSR / non-DOM environments)
-    if ((0,_guards__WEBPACK_IMPORTED_MODULE_1__.isUndefined)(document)) {
+    // Browser guard (SSR / non-DOM environments) - `typeof`, as reading an undeclared `document` throws
+    if (typeof document === 'undefined') {
         return;
     }
     const link = document.createElement('a');
@@ -1415,7 +1501,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   centerElementInContainer: () => (/* binding */ centerElementInContainer)
 /* harmony export */ });
-/* harmony import */ var _dom__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/dom */ "./src/dom/index.ts");
+/* harmony import */ var _overflow__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./overflow */ "./src/dom/layout/overflow.ts");
 /* harmony import */ var _geometry__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ~/geometry */ "./src/geometry/index.ts");
 
 
@@ -1447,7 +1533,7 @@ const centerElementInContainer = (containerElement, elementToCenter, { axis = 'b
             elementSize: elementToCenter.clientWidth,
         });
         translateX = shouldClamp
-            ? (0,_geometry__WEBPACK_IMPORTED_MODULE_1__.clampOffsetToOverflow)(offsetX, (0,_dom__WEBPACK_IMPORTED_MODULE_0__.getXOverflowWidth)(containerElement))
+            ? (0,_geometry__WEBPACK_IMPORTED_MODULE_1__.clampOffsetToOverflow)(offsetX, (0,_overflow__WEBPACK_IMPORTED_MODULE_0__.getXOverflowWidth)(containerElement))
             : offsetX;
     }
     if (axis === 'y' || axis === 'both') {
@@ -1457,7 +1543,7 @@ const centerElementInContainer = (containerElement, elementToCenter, { axis = 'b
             elementSize: elementToCenter.clientHeight,
         });
         translateY = shouldClamp
-            ? (0,_geometry__WEBPACK_IMPORTED_MODULE_1__.clampOffsetToOverflow)(offsetY, (0,_dom__WEBPACK_IMPORTED_MODULE_0__.getYOverflowHeight)(containerElement))
+            ? (0,_geometry__WEBPACK_IMPORTED_MODULE_1__.clampOffsetToOverflow)(offsetY, (0,_overflow__WEBPACK_IMPORTED_MODULE_0__.getYOverflowHeight)(containerElement))
             : offsetY;
     }
     containerElement.style.transform = `translate(${translateX}px, ${translateY}px)`;
@@ -1574,6 +1660,11 @@ __webpack_require__.r(__webpack_exports__);
  *
  * Only works with 2D transforms (i.e., `matrix(a, b, c, d, e, f)`).
  *
+ * The values are the matrix's own entries rather than decomposed angles and factors: `scaleX` is
+ * `a`, `skewY` is `b`, `skewX` is `c`, `scaleY` is `d`, and the translation is `e` and `f`. They read
+ * as scale and skew only for a transform with no rotation - `rotate(90deg)` gives `scaleX` and
+ * `scaleY` of 0 - and a skew is its tangent (`skewX(30deg)` gives `skewX` ≈ 0.577), not its angle.
+ *
  * @param element - The element with a CSS transform applied.
  * @returns An object with parsed transformation values.
  *
@@ -1628,6 +1719,27 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _decode_base64__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ./decode-base64 */ "./src/encoding/decode-base64.ts");
 
 
+/**
+ * Decodes a base64 string and parses the JSON it holds - the reverse of `encodeBase64Json`.
+ *
+ * Never throws: a value that is not valid base64, or does not decode to valid JSON, gives `null`.
+ * The result is only cast to `Value`, not checked against it.
+ *
+ * @template Value - The type the JSON is expected to have.
+ *
+ * @param value - The base64 string to decode.
+ *
+ * @returns The parsed value, or `null` when the value cannot be decoded or parsed.
+ *
+ * @example
+ * ```ts
+ * decodeBase64Json<{ name: string; age: number }>('eyJuYW1lIjoiTWlrZSIsImFnZSI6MzN9');
+ * // ➜ { name: 'Mike', age: 33 }
+ *
+ * decodeBase64Json('SGVsbG8=');
+ * // ➜ null - "Hello" is not JSON
+ * ```
+ */
 const decodeBase64Json = (value) => {
     const decodedValue = (0,_decode_base64__WEBPACK_IMPORTED_MODULE_1__.decodeBase64)(value);
     if (decodedValue === null) {
@@ -1664,12 +1776,37 @@ const decodeBase64Bytes = (value) => {
     }
     return bytes;
 };
+/**
+ * Decodes a base64 string to the UTF-8 text it encodes - the reverse of `encodeBase64`.
+ *
+ * Never throws: a value that is not padded base64 of the standard alphabet, or whose bytes are not
+ * valid UTF-8, decodes to `null`.
+ *
+ * Uses `Uint8Array.fromBase64` where the runtime has it, Node's `Buffer` otherwise, and `atob`
+ * last.
+ *
+ * @param value - The base64 string to decode.
+ *
+ * @returns The decoded text, or `null` when the value is not valid base64 of UTF-8 text.
+ *
+ * @example
+ * ```ts
+ * decodeBase64('SGVsbG8=');
+ * // ➜ 'Hello'
+ *
+ * decodeBase64('not base64!');
+ * // ➜ null
+ * ```
+ */
 const decodeBase64 = (value) => {
     if (!BASE64_PATTERN.test(value)) {
         return null;
     }
     try {
-        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(decodeBase64Bytes(value));
+        return new TextDecoder('utf-8', {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(decodeBase64Bytes(value));
     }
     catch {
         return null;
@@ -1691,6 +1828,22 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ });
 /* harmony import */ var _encode_base64__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./encode-base64 */ "./src/encoding/encode-base64.ts");
 
+/**
+ * Serialises a value as JSON and encodes it as base64 - a structured value carried in a URL query
+ * parameter, a cookie or a header.
+ *
+ * @template Value - The type of the value.
+ *
+ * @param value - Any JSON-serialisable value.
+ *
+ * @returns The base64 encoding of the value's JSON.
+ *
+ * @example
+ * ```ts
+ * encodeBase64Json({ name: 'Mike', age: 33 });
+ * // ➜ 'eyJuYW1lIjoiTWlrZSIsImFnZSI6MzN9'
+ * ```
+ */
 const encodeBase64Json = (value) => (0,_encode_base64__WEBPACK_IMPORTED_MODULE_0__.encodeBase64)(JSON.stringify(value));
 
 
@@ -1719,6 +1872,26 @@ const encodeBase64Bytes = (bytes) => {
     }
     return btoa(binary);
 };
+/**
+ * Encodes a string as base64, by its UTF-8 bytes - so text outside Latin-1 (accents, emoji, any
+ * script), which `btoa` throws on, encodes as well.
+ *
+ * Uses `Uint8Array.prototype.toBase64` where the runtime has it, Node's `Buffer` otherwise, and
+ * `btoa` last.
+ *
+ * @param value - The string to encode.
+ *
+ * @returns The base64 encoding of the string's UTF-8 bytes.
+ *
+ * @example
+ * ```ts
+ * encodeBase64('Hello');
+ * // ➜ 'SGVsbG8='
+ *
+ * encodeBase64('Привіт');
+ * // ➜ '0J/RgNC40LLRltGC'
+ * ```
+ */
 const encodeBase64 = (value) => encodeBase64Bytes(new TextEncoder().encode(value));
 
 
@@ -1758,7 +1931,9 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   getLocalStorageCapabilities: () => (/* reexport safe */ _storage__WEBPACK_IMPORTED_MODULE_0__.getLocalStorageCapabilities),
-/* harmony export */   isLocalStorageReadable: () => (/* reexport safe */ _storage__WEBPACK_IMPORTED_MODULE_0__.isLocalStorageReadable)
+/* harmony export */   isLocalStorageReadable: () => (/* reexport safe */ _storage__WEBPACK_IMPORTED_MODULE_0__.isLocalStorageReadable),
+/* harmony export */   readLocalStorageJson: () => (/* reexport safe */ _storage__WEBPACK_IMPORTED_MODULE_0__.readLocalStorageJson),
+/* harmony export */   writeLocalStorageJson: () => (/* reexport safe */ _storage__WEBPACK_IMPORTED_MODULE_0__.writeLocalStorageJson)
 /* harmony export */ });
 /* harmony import */ var _storage__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./storage */ "./src/env/storage/index.ts");
 
@@ -1775,10 +1950,75 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   getLocalStorageCapabilities: () => (/* reexport safe */ _local_storage__WEBPACK_IMPORTED_MODULE_0__.getLocalStorageCapabilities),
-/* harmony export */   isLocalStorageReadable: () => (/* reexport safe */ _local_storage__WEBPACK_IMPORTED_MODULE_0__.isLocalStorageReadable)
+/* harmony export */   isLocalStorageReadable: () => (/* reexport safe */ _local_storage__WEBPACK_IMPORTED_MODULE_0__.isLocalStorageReadable),
+/* harmony export */   readLocalStorageJson: () => (/* reexport safe */ _local_storage_json__WEBPACK_IMPORTED_MODULE_1__.readLocalStorageJson),
+/* harmony export */   writeLocalStorageJson: () => (/* reexport safe */ _local_storage_json__WEBPACK_IMPORTED_MODULE_1__.writeLocalStorageJson)
 /* harmony export */ });
 /* harmony import */ var _local_storage__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./local-storage */ "./src/env/storage/local-storage.ts");
+/* harmony import */ var _local_storage_json__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ./local-storage-json */ "./src/env/storage/local-storage-json.ts");
+
+
+
+
+/***/ },
+
+/***/ "./src/env/storage/local-storage-json.ts"
+/*!***********************************************!*\
+  !*** ./src/env/storage/local-storage-json.ts ***!
+  \***********************************************/
+(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   readLocalStorageJson: () => (/* binding */ readLocalStorageJson),
+/* harmony export */   writeLocalStorageJson: () => (/* binding */ writeLocalStorageJson)
+/* harmony export */ });
+/* harmony import */ var _json__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/json */ "./src/json/index.ts");
 
+/**
+ * Reads the value stored as JSON under a key in `localStorage`.
+ *
+ * Never throws: storage that cannot be read at all (SSR, disabled storage, sandboxed iframes, strict
+ * privacy modes) reads as nothing stored, as does a value that is not JSON.
+ *
+ * The value is only cast to `Value`, not checked against it - something stored by an older version
+ * of the app, or by hand, can be of any shape, so check it before relying on it.
+ *
+ * @param key - The `localStorage` key to read.
+ *
+ * @returns The parsed value, or `null` when nothing is stored under the key, what is stored is not
+ *          valid JSON, or storage cannot be read.
+ */
+const readLocalStorageJson = (key) => {
+    try {
+        const value = window.localStorage.getItem(key);
+        return value === null ? null : (0,_json__WEBPACK_IMPORTED_MODULE_0__.parseJson)(value);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Stores a value under a key in `localStorage`, as JSON.
+ *
+ * Never throws: a write that fails - storage full (`QuotaExceededError`), Safari Private Mode,
+ * security-restricted contexts, SSR, or a value `JSON.stringify()` cannot serialise (a circular
+ * reference, a `BigInt`) - reports `false` instead.
+ *
+ * @param key - The `localStorage` key to write.
+ * @param value - Any JSON-serialisable value.
+ *
+ * @returns `true` once the value is stored, `false` when it could not be.
+ */
+const writeLocalStorageJson = (key, value) => {
+    try {
+        window.localStorage.setItem(key, JSON.stringify(value));
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
 
 
 /***/ },
@@ -1806,10 +2046,14 @@ __webpack_require__.r(__webpack_exports__);
  *          throw; otherwise `false`.
  */
 const isLocalStorageReadable = () => {
-    if (typeof window === 'undefined' || !window.localStorage) {
+    if (typeof window === 'undefined') {
         return false;
     }
+    // Inside the `try`: in a sandboxed iframe, or with storage blocked, reading the property throws
     try {
+        if (!window.localStorage) {
+            return false;
+        }
         window.localStorage.getItem('__non_existing_key__');
         return true;
     }
@@ -1958,7 +2202,8 @@ const readFileSystemDirectoryEntries = async (directoryEntry) => {
  *
  * This function walks through all subdirectories, resolving each file into a `File` object.
  * Directories themselves are not returned. To avoid unnecessary noise, certain system or
- * OS-generated files can be excluded via the `skipFiles` option.
+ * OS-generated files and folders can be excluded via the `skipFiles` option - a folder named there
+ * is not entered.
  *
  * @param directoryEntry - The starting directory entry to traverse.
  * @param options - Optional settings that control traversal behavior.
@@ -1978,18 +2223,18 @@ const traverseFileSystemDirectory = async (directoryEntry, { skipFiles = [
     const skipFilesSet = new Set(skipFiles);
     const entries = await readFileSystemDirectoryEntries(directoryEntry);
     const filePromises = await (0,_async__WEBPACK_IMPORTED_MODULE_0__.runParallel)(entries, async (entry) => {
+        if (skipFilesSet.has(entry.name)) {
+            return [];
+        }
         if (entry.isDirectory) {
             return traverseFileSystemDirectory(entry, {
                 skipFiles,
             });
         }
-        else if (!skipFilesSet.has(entry.name)) {
-            const file = await new Promise((resolve, reject) => {
-                entry.file(resolve, reject);
-            });
-            return [file];
-        }
-        return [];
+        const file = await new Promise((resolve, reject) => {
+            entry.file(resolve, reject);
+        });
+        return [file];
     });
     return filePromises.flat();
 };
@@ -2059,6 +2304,17 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   not: () => (/* binding */ not),
 /* harmony export */   once: () => (/* binding */ once)
 /* harmony export */ });
+/**
+ * A function that does nothing and returns `undefined` - a default for an optional callback, so the
+ * caller can call it without checking it is there.
+ *
+ * @example
+ * ```ts
+ * const { onClose = noop } = props;
+ *
+ * onClose();
+ * ```
+ */
 const noop = () => { };
 /**
  * Checks if a value is a function.
@@ -2067,6 +2323,7 @@ const noop = () => { };
  *
  * @returns `true` if the value is a function; otherwise, `false`.
  */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type -- what `typeof value === 'function'` narrows `unknown` to
 const isFunction = (value) => typeof value === 'function';
 /**
  * Creates a function that negates the result of the given predicate function.
@@ -2091,6 +2348,7 @@ const not = (fn) => (...args) => !fn(...args);
  * Wraps a function so that it can only be executed once.
  * The wrapped function remembers (caches) the result of the first invocation
  * and returns that same result for all subsequent calls, regardless of the arguments provided.
+ * Where the first invocation throws, every call throws that same error - `fn` is not run again.
  *
  * Common use cases include:
  * - initializing singletons
@@ -2108,10 +2366,21 @@ const not = (fn) => (...args) => !fn(...args);
 const once = (fn) => {
     let called = false;
     let result;
+    let hasThrown = false;
+    let error;
     return function (...args) {
         if (!called) {
             called = true;
-            result = fn.apply(this, args);
+            try {
+                result = fn.apply(this, args);
+            }
+            catch (e) {
+                hasThrown = true;
+                error = e;
+            }
+        }
+        if (hasThrown) {
+            throw error;
         }
         return result;
     };
@@ -2179,7 +2448,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   applyInertiaStep: () => (/* binding */ applyInertiaStep)
 /* harmony export */ });
-/* harmony import */ var _geometry__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/geometry */ "./src/geometry/index.ts");
+/* harmony import */ var _resolve_bounded_delta__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./resolve-bounded-delta */ "./src/geometry/resolve-bounded-delta.ts");
 
 /**
  * Applies a **single step** of bounded, velocity-based inertia.
@@ -2224,7 +2493,7 @@ const applyInertiaStep = ({ value, min, max, velocityPxMs, deltaTimeMs, friction
     if (Math.abs(velocityPxMs) < minVelocityPxMs) {
         return null;
     }
-    const nextValue = (0,_geometry__WEBPACK_IMPORTED_MODULE_0__.resolveBoundedDelta)({
+    const nextValue = (0,_resolve_bounded_delta__WEBPACK_IMPORTED_MODULE_0__.resolveBoundedDelta)({
         delta: velocityPxMs * deltaTimeMs,
         value,
         min,
@@ -2289,13 +2558,24 @@ __webpack_require__.r(__webpack_exports__);
 /**
  * Calculates the raw offset required to center an element within a container along a single axis.
  *
- * @returns A negative offset value suitable for use in a CSS `translate` transform.
+ * @param options - The container's visible size, and the element's offset and size, along the axis.
+ *
+ * @returns The offset to translate the container by: negative for an element past the container's
+ *          centre, positive for one before it, and `0` for one already centred. Clamp it with
+ *          `clampOffsetToOverflow` to keep the container within its overflow.
+ *
+ * @example
+ * ```ts
+ * calculateCenterOffset({ containerSize: 100, elementOffset: 200, elementSize: 20 });
+ * // -160
+ * ```
  */
 const calculateCenterOffset = ({ containerSize, elementOffset, elementSize, }) => {
     const containerCenter = containerSize / 2;
     const elementCenter = elementOffset + elementSize / 2;
     const targetOffset = elementCenter - containerCenter;
-    return -targetOffset;
+    // `|| 0` turns the `-0` of an element already centred into `0`
+    return -targetOffset || 0;
 };
 
 
@@ -2318,6 +2598,12 @@ __webpack_require__.r(__webpack_exports__);
  * @param overflowSize - Maximum overflow size along the axis.
  *
  * @returns Clamped negative offset, or `0` when no overflow exists.
+ *
+ * @example
+ * ```ts
+ * clampOffsetToOverflow(-160, 100); // -100
+ * clampOffsetToOverflow(40, 100); // 0
+ * ```
  */
 const clampOffsetToOverflow = (offset, overflowSize) => {
     if (overflowSize <= 0) {
@@ -2455,6 +2741,26 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   isUndefined: () => (/* binding */ isUndefined),
 /* harmony export */   isValidDate: () => (/* binding */ isValidDate)
 /* harmony export */ });
+/**
+ * Asserts that a condition holds, narrowing it for the code after the call.
+ *
+ * A `function` declaration rather than an arrow, which TypeScript needs for an `asserts` signature
+ * to narrow at the call site.
+ *
+ * @param condition - The condition expected to be truthy.
+ * @param message - The message of the error thrown when it is not.
+ *
+ * @throws {Error} When `condition` is falsy.
+ *
+ * @example
+ * ```ts
+ * const user = users.find(user => user.id === id);
+ *
+ * assert(user, `User ${id} not found`);
+ *
+ * user.name; // `user` is no longer `undefined` here
+ * ```
+ */
 function assert(condition, message) {
     if (!condition) {
         throw new Error(message);
@@ -2509,21 +2815,23 @@ const isNumber = (value) => typeof value === 'number';
  */
 const isBool = (value) => typeof value === 'boolean';
 /**
- * Checks if a value is an object.
+ * Checks if a value is an object - anything `typeof` calls `'object'` (plain objects, arrays,
+ * dates, maps, class instances), except `null`.
  *
  * @param value - The value to check.
  *
- * @returns `true` if the value is an object; otherwise, `false`.
+ * @returns `true` if the value is a non-null object; otherwise, `false`.
  */
-const isObject = (value) => typeof value === 'object';
+const isObject = (value) => typeof value === 'object' && value !== null;
 /**
- * Checks if a value is an empty object (no own enumerable properties).
+ * Checks if a value is an empty object (no own enumerable properties, symbol-keyed ones included).
  *
  * @param value - The value to check.
  *
  * @returns `true` if the value is an empty object; otherwise, `false`.
  */
-const isEmptyObject = (value) => isObject(value) && !isNull(value) && Object.keys(value).length === 0;
+const isEmptyObject = (value) => isObject(value) &&
+    Reflect.ownKeys(value).every(key => !Object.prototype.propertyIsEnumerable.call(value, key));
 /**
  * Checks if a value is a Date object.
  *
@@ -2762,13 +3070,23 @@ __webpack_require__.r(__webpack_exports__);
  * @param sourceRect - The rectangle used to measure overlap against the target.
  * @param targetRect - The rectangle whose covered area is measured.
  *
- * @returns A number between `0` and `1` representing the intersection ratio.
+ * @returns A number between `0` and `1` representing the intersection ratio - `0` for a target
+ *          with no area, which nothing can cover.
+ *
+ * @example
+ * ```ts
+ * getDOMRectIntersectionRatio(new DOMRect(0, 0, 100, 100), new DOMRect(50, 0, 100, 100));
+ * // 0.5
+ * ```
  */
 const getDOMRectIntersectionRatio = (sourceRect, targetRect) => {
     const xOverlap = Math.max(0, Math.min(sourceRect.right, targetRect.right) - Math.max(sourceRect.left, targetRect.left));
     const yOverlap = Math.max(0, Math.min(sourceRect.bottom, targetRect.bottom) - Math.max(sourceRect.top, targetRect.top));
     const intersectionArea = xOverlap * yOverlap;
     const targetArea = targetRect.width * targetRect.height;
+    if (targetArea <= 0) {
+        return 0;
+    }
     return intersectionArea / targetArea;
 };
 
@@ -2830,26 +3148,35 @@ __webpack_require__.r(__webpack_exports__);
  * @param options - Resolution behavior configuration.
  *
  * @returns A normalized, axis-aligned delta suitable for further scroll or movement processing.
+ *
+ * @example
+ * ```ts
+ * // A vertical wheel scrolling a horizontal list
+ * resolveAxisDelta({ deltaX: 0, deltaY: 40 }, 'x');
+ * // { deltaX: -40, deltaY: 0 }
+ * ```
  */
 const resolveAxisDelta = (delta, axis, { allowFallback = true, invert = true } = {}) => {
     const sign = invert ? -1 : 1;
+    // `|| 0` keeps an inverted zero `0` rather than `-0`
+    const resolve = (value) => sign * value || 0;
     switch (axis) {
         case 'x': {
             const value = delta.deltaX !== 0 ? delta.deltaX : allowFallback ? delta.deltaY : 0;
             return {
-                deltaX: sign * value,
+                deltaX: resolve(value),
                 deltaY: 0,
             };
         }
         case 'y':
             return {
                 deltaX: 0,
-                deltaY: sign * delta.deltaY,
+                deltaY: resolve(delta.deltaY),
             };
         default:
             return {
-                deltaX: sign * delta.deltaX,
-                deltaY: sign * delta.deltaY,
+                deltaX: resolve(delta.deltaX),
+                deltaY: resolve(delta.deltaY),
             };
     }
 };
@@ -2883,6 +3210,27 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   parseJson: () => (/* binding */ parseJson)
 /* harmony export */ });
+/**
+ * Parses a JSON string without throwing.
+ *
+ * The result is only cast to `Value`, not checked against it - check its shape before relying on
+ * it where the string comes from outside the program.
+ *
+ * @template Value - The type the JSON is expected to have.
+ *
+ * @param value - The JSON string to parse.
+ *
+ * @returns The parsed value, or `null` when the string is not valid JSON.
+ *
+ * @example
+ * ```ts
+ * parseJson<{ name: string }>('{"name":"Mike"}');
+ * // ➜ { name: 'Mike' }
+ *
+ * parseJson('{name:"Mike"}');
+ * // ➜ null
+ * ```
+ */
 const parseJson = (value) => {
     try {
         return JSON.parse(value);
@@ -2958,7 +3306,7 @@ __webpack_require__.r(__webpack_exports__);
  * @example
  * ```ts
  * const className = hashString('background-color: red;');
- * // → 'e4k1z0x'
+ * // → '1s0s409'
  * ```
  */
 const hashString = (input) => {
@@ -3017,6 +3365,11 @@ __webpack_require__.r(__webpack_exports__);
  * @param endY - The Y coordinate of the ending point.
  *
  * @returns The Euclidean distance between the two points.
+ *
+ * @example
+ * ```ts
+ * calculateEuclideanDistance(0, 0, 3, 4); // 5
+ * ```
  */
 const calculateEuclideanDistance = (startX, startY, endX, endY) => {
     const deltaX = endX - startX;
@@ -3029,7 +3382,13 @@ const calculateEuclideanDistance = (startX, startY, endX, endY) => {
  * @param distance - The distance.
  * @param elapsedTime - The time taken to move the distance.
  *
- * @returns The calculated speed, which is the absolute value of delta divided by elapsed time.
+ * @returns The calculated speed, which is the absolute value of delta divided by elapsed time -
+ *          `Infinity` for a distance covered in no time, and `NaN` for none covered in none.
+ *
+ * @example
+ * ```ts
+ * calculateMovingSpeed(-120, 60); // 2
+ * ```
  */
 const calculateMovingSpeed = (distance, elapsedTime) => Math.abs(distance / elapsedTime);
 /**
@@ -3039,6 +3398,11 @@ const calculateMovingSpeed = (distance, elapsedTime) => Math.abs(distance / elap
  * @param percentage - The percentage to calculate.
  *
  * @returns The calculated percentage of the value.
+ *
+ * @example
+ * ```ts
+ * calculatePercentage(200, 15); // 30
+ * ```
  */
 const calculatePercentage = (value, percentage) => (value * percentage) / 100;
 
@@ -3070,12 +3434,19 @@ __webpack_require__.r(__webpack_exports__);
  *
  * @returns A new object containing only keys whose runtime values are not `undefined`.
  */
-const definedProps = (obj) => Object.entries(obj).reduce((result, [key, value]) => {
-    if (value !== undefined) {
-        result[key] = value;
-    }
+const definedProps = (obj) => {
+    const result = {};
+    Reflect.ownKeys(obj).forEach(key => {
+        if (!Object.prototype.propertyIsEnumerable.call(obj, key)) {
+            return;
+        }
+        const value = obj[key];
+        if (value !== undefined) {
+            result[key] = value;
+        }
+    });
     return result;
-}, {});
+};
 
 
 /***/ },
@@ -3116,7 +3487,7 @@ const camelToDashCase = (input) => {
     // Convert the first character to the lowercase without adding a hyphen
     const firstCharProcessed = firstChar.toLowerCase();
     // Process the rest of the string normally, adding hyphens before uppercase letters
-    const restProcessed = restOfString.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`);
+    const restProcessed = restOfString.replace(/\p{Lu}/gu, letter => `-${letter.toLowerCase()}`);
     return firstCharProcessed + restProcessed;
 };
 
@@ -3151,7 +3522,7 @@ __webpack_require__.r(__webpack_exports__);
  * camelToWords('userIDNumber'); // → 'user ID Number'
  * ```
  */
-const camelToWords = (input) => input.replace(/([a-z0-9])([A-Z])/g, '$1 $2');
+const camelToWords = (input) => input.replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, '$1 $2').replace(/(\p{Lu})(\p{Lu}\p{Ll})/gu, '$1 $2');
 
 
 /***/ },
@@ -3268,7 +3639,7 @@ const getWordsInitials = (input, maxWords = Infinity) => {
     }
     return (0,_split_string_into_words__WEBPACK_IMPORTED_MODULE_0__.splitStringIntoWords)(input)
         .slice(0, maxWords)
-        .map(word => word[0])
+        .map(word => String.fromCodePoint(word.codePointAt(0)))
         .join('')
         .toUpperCase();
 };
@@ -3515,7 +3886,7 @@ __webpack_require__.r(__webpack_exports__);
  * toKebabCase('hello123World'); // → 'hello123-world'
  * ```
  */
-const toKebabCase = (input) => input.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+const toKebabCase = (input) => input.replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, '$1-$2').toLowerCase();
 
 
 /***/ },
@@ -3982,6 +4353,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   parseJson: () => (/* reexport safe */ _json__WEBPACK_IMPORTED_MODULE_17__.parseJson),
 /* harmony export */   pipe: () => (/* reexport safe */ _array__WEBPACK_IMPORTED_MODULE_1__.pipe),
 /* harmony export */   readFilesFromDataTransfer: () => (/* reexport safe */ _file__WEBPACK_IMPORTED_MODULE_5__.readFilesFromDataTransfer),
+/* harmony export */   readLocalStorageJson: () => (/* reexport safe */ _env__WEBPACK_IMPORTED_MODULE_4__.readLocalStorageJson),
 /* harmony export */   reduceAsync: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_2__.reduceAsync),
 /* harmony export */   replaceHistorySearchParams: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_3__.replaceHistorySearchParams),
 /* harmony export */   resolveAxisDelta: () => (/* reexport safe */ _intersection__WEBPACK_IMPORTED_MODULE_10__.resolveAxisDelta),
@@ -3996,9 +4368,11 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   splitStringIntoWords: () => (/* reexport safe */ _string__WEBPACK_IMPORTED_MODULE_13__.splitStringIntoWords),
 /* harmony export */   timeout: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_2__.timeout),
 /* harmony export */   toKebabCase: () => (/* reexport safe */ _string__WEBPACK_IMPORTED_MODULE_13__.toKebabCase),
+/* harmony export */   toMapBy: () => (/* reexport safe */ _array__WEBPACK_IMPORTED_MODULE_1__.toMapBy),
 /* harmony export */   toggleArrayItem: () => (/* reexport safe */ _array__WEBPACK_IMPORTED_MODULE_1__.toggleArrayItem),
 /* harmony export */   traverseFileSystemDirectory: () => (/* reexport safe */ _file__WEBPACK_IMPORTED_MODULE_5__.traverseFileSystemDirectory),
-/* harmony export */   unique: () => (/* reexport safe */ _array__WEBPACK_IMPORTED_MODULE_1__.unique)
+/* harmony export */   unique: () => (/* reexport safe */ _array__WEBPACK_IMPORTED_MODULE_1__.unique),
+/* harmony export */   writeLocalStorageJson: () => (/* reexport safe */ _env__WEBPACK_IMPORTED_MODULE_4__.writeLocalStorageJson)
 /* harmony export */ });
 /* harmony import */ var _a11y__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./a11y */ "./src/a11y/index.ts");
 /* harmony import */ var _array__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ./array */ "./src/array/index.ts");