@react-hive/honey-utils 3.14.0 → 3.16.0

package/dist/index.dev.cjs

@@ -230,7 +230,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   pipe: () => (/* binding */ pipe),
 /* harmony export */   unique: () => (/* binding */ unique)
 /* harmony export */ });
-/* harmony import */ var _guards__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./guards */ "./src/guards.ts");
+/* harmony import */ var _guards__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/guards */ "./src/guards.ts");
 
 /**
  * Checks if a value is an array.
@@ -1324,11 +1324,10 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   blobToFile: () => (/* binding */ blobToFile),
 /* harmony export */   fileListToFiles: () => (/* binding */ fileListToFiles),
 /* harmony export */   isFile: () => (/* binding */ isFile),
-/* harmony export */   parseFileName: () => (/* binding */ parseFileName),
 /* harmony export */   readFilesFromDataTransfer: () => (/* binding */ readFilesFromDataTransfer),
 /* harmony export */   traverseFileSystemDirectory: () => (/* binding */ traverseFileSystemDirectory)
 /* harmony export */ });
-/* harmony import */ var _async_async__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./async/async */ "./src/async/async.ts");
+/* harmony import */ var _async__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ~/async */ "./src/async/index.ts");
 
 /**
  * Checks if a value is a `File` object.
@@ -1338,29 +1337,6 @@ __webpack_require__.r(__webpack_exports__);
  * @returns `true` if the value is a `File` object; otherwise, `false`.
  */
 const isFile = (value) => value instanceof File;
-/**
- * Splits a file name into its base name and extension.
- *
- * Special cases:
- * - Files without a dot return `[fileName, ""]`
- * - Hidden files like `.gitignore` return `[".gitignore", ""]`
- * - Names ending with a trailing dot (e.g., `"file."`) return `["file.", ""]`
- * - Multi-dot names (e.g., `"archive.tar.gz"`) split on the last dot
- *
- * @param fileName - The full file name to parse.
- *
- * @returns A tuple where:
- *  - index 0 is the base name
- *  - index 1 is the file extension (lowercased), or an empty string if none exists
- */
-const parseFileName = (fileName) => {
-    const lastDotIndex = fileName.lastIndexOf('.');
-    // No dot or leading dot with no extension (e.g., ".gitignore")
-    if (lastDotIndex <= 0 || lastDotIndex === fileName.length - 1) {
-        return [fileName, ''];
-    }
-    return [fileName.slice(0, lastDotIndex), fileName.slice(lastDotIndex + 1).toLowerCase()];
-};
 /**
  * Converts a `FileList` object to an array of `File` objects.
  *
@@ -1450,7 +1426,7 @@ const traverseFileSystemDirectory = async (directoryEntry, { skipFiles = [
 ], } = {}) => {
     const skipFilesSet = new Set(skipFiles);
     const entries = await readFileSystemDirectoryEntries(directoryEntry);
-    const filePromises = await (0,_async_async__WEBPACK_IMPORTED_MODULE_0__.runParallel)(entries, async (entry) => {
+    const filePromises = await (0,_async__WEBPACK_IMPORTED_MODULE_0__.runParallel)(entries, async (entry) => {
         if (entry.isDirectory) {
             return traverseFileSystemDirectory(entry, {
                 skipFiles,
@@ -1640,6 +1616,110 @@ __webpack_require__.r(__webpack_exports__);
 const invokeIfFunction = (input, ...args) => (typeof input === 'function' ? input(...args) : input);
 
 
+/***/ }),
+
+/***/ "./src/geometry/apply-inertia-step.ts":
+/*!********************************************!*\
+  !*** ./src/geometry/apply-inertia-step.ts ***!
+  \********************************************/
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+__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");
+
+/**
+ * Advances a value by one inertia step using velocity, friction, and hard bounds.
+ *
+ * This utility models **inertial motion** (momentum + decay) on top of
+ * {@link resolveBoundedDelta}, which acts as the authoritative constraint layer.
+ *
+ * The function:
+ * - Integrates velocity over the elapsed time to produce a movement delta
+ * - Resolves that delta against fixed bounds
+ * - Applies exponential friction to gradually reduce velocity
+ * - Stops immediately when a bound is hit or velocity falls below a threshold
+ *
+ * ⚠️ This function performs **one step only** and is intended to be called
+ * repeatedly from an animation loop (e.g. `requestAnimationFrame`).
+ *
+ * ### Common use cases
+ * - Synthetic scrolling with momentum
+ * - Carousels and sliders
+ * - Timelines and scrubbers
+ * - Drag-to-scroll interactions with inertia
+ *
+ * @param value - Current value before applying inertia (e.g. translate position).
+ * @param min - Minimum allowed value (inclusive).
+ * @param max - Maximum allowed value (inclusive).
+ * @param velocity - Current velocity in units per millisecond (e.g. px/ms).
+ * @param deltaTime - Time elapsed since the previous step, in milliseconds.
+ * @param friction - Exponential friction coefficient controlling decay rate.
+ * @param minVelocity - Minimum velocity below which inertia stops.
+ *
+ * @returns An object containing the updated value and velocity,
+ *          or `null` when inertia has completed or movement is no longer possible.
+ *
+ * @example
+ * ```ts
+ * let value = translateX;
+ * let velocity = releaseVelocity; // px/ms from drag end
+ * let lastTime = performance.now();
+ *
+ * const step = (time: number) => {
+ *   const deltaTime = time - lastTime;
+ *   lastTime = time;
+ *
+ *   const result = applyInertiaStep({
+ *     value,
+ *     velocity,
+ *     min: -maxOverflow,
+ *     max: 0,
+ *     deltaTime,
+ *   });
+ *
+ *   if (!result) {
+ *     return; // inertia finished
+ *   }
+ *
+ *   value = result.value;
+ *   velocity = result.velocity;
+ *
+ *   container.style.transform = `translateX(${value}px)`;
+ *   requestAnimationFrame(step);
+ * };
+ *
+ * requestAnimationFrame(step);
+ * ```
+ */
+const applyInertiaStep = ({ value, min, max, velocity, deltaTime, friction = 0.002, minVelocity = 0.01, }) => {
+    if (Math.abs(velocity) < minVelocity) {
+        return null;
+    }
+    // Distance we want to move this frame
+    const delta = velocity * deltaTime;
+    const nextValue = (0,_geometry__WEBPACK_IMPORTED_MODULE_0__.resolveBoundedDelta)({
+        delta,
+        value,
+        min,
+        max,
+    });
+    // Hit a hard bound → stop inertia immediately
+    if (nextValue === null) {
+        return null;
+    }
+    // Apply exponential friction
+    const decay = Math.exp(-friction * deltaTime);
+    const nextVelocity = velocity * decay;
+    return {
+        value: nextValue,
+        velocity: nextVelocity,
+    };
+};
+
+
 /***/ }),
 
 /***/ "./src/geometry/index.ts":
@@ -1650,9 +1730,15 @@ const invokeIfFunction = (input, ...args) => (typeof input === 'function' ? inpu
 
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   calculateCenterOffset: () => (/* reexport safe */ _layout__WEBPACK_IMPORTED_MODULE_0__.calculateCenterOffset)
+/* harmony export */   applyInertiaStep: () => (/* reexport safe */ _apply_inertia_step__WEBPACK_IMPORTED_MODULE_2__.applyInertiaStep),
+/* harmony export */   calculateCenterOffset: () => (/* reexport safe */ _layout__WEBPACK_IMPORTED_MODULE_0__.calculateCenterOffset),
+/* harmony export */   resolveBoundedDelta: () => (/* reexport safe */ _resolve_bounded_delta__WEBPACK_IMPORTED_MODULE_1__.resolveBoundedDelta)
 /* harmony export */ });
 /* harmony import */ var _layout__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./layout */ "./src/geometry/layout/index.ts");
+/* harmony import */ var _resolve_bounded_delta__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ./resolve-bounded-delta */ "./src/geometry/resolve-bounded-delta.ts");
+/* harmony import */ var _apply_inertia_step__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(/*! ./apply-inertia-step */ "./src/geometry/apply-inertia-step.ts");
+
+
 
 
 
@@ -1706,6 +1792,83 @@ __webpack_require__.r(__webpack_exports__);
 
 
 
+/***/ }),
+
+/***/ "./src/geometry/resolve-bounded-delta.ts":
+/*!***********************************************!*\
+  !*** ./src/geometry/resolve-bounded-delta.ts ***!
+  \***********************************************/
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   resolveBoundedDelta: () => (/* binding */ resolveBoundedDelta)
+/* harmony export */ });
+/**
+ * Resolves the next value by consuming a delta within fixed numeric bounds.
+ *
+ * This function applies **bounded delta consumption** rather than naive clamping:
+ *
+ * - The delta is applied in the given direction as long as movement is possible.
+ * - If the delta would overshoot a bound, it is partially consumed so the
+ *   resulting value lands exactly on the boundary.
+ * - If movement in the given direction is no longer possible, `null` is returned.
+ *
+ * This behavior mirrors how native scroll engines and drag constraints
+ * handle fast input without jitter or overshoot.
+ *
+ * ### Key characteristics
+ * - Direction-aware (positive and negative deltas behave independently)
+ * - Prevents overshoot while preserving remaining movement
+ * - Does **not** clamp unconditionally
+ * - Side-effect free and fully deterministic
+ *
+ * ### Common use cases
+ * - Synthetic scrolling
+ * - Drag constraints
+ * - Sliders and carousels
+ * - Timelines and scrubbers
+ * - Inertia and momentum systems
+ *
+ * @param delta - Incremental change to apply to the current value.
+ *               The sign determines the movement direction.
+ * @param value - Current numeric value before applying the delta.
+ * @param min - Minimum allowed value (inclusive).
+ * @param max - Maximum allowed value (inclusive).
+ *
+ * @returns The next resolved value after applying the delta,
+ *          or `null` if movement in the given direction is not possible.
+ *
+ * @example
+ * ```ts
+ * // Simple bounded movement
+ * resolveBoundedDelta({ value: 10, delta: -5, min: 0, max: 100 });
+ * // → 5
+ *
+ * // Overshoot is clamped to the boundary
+ * resolveBoundedDelta({ value: 2, delta: -10, min: 0, max: 100 });
+ * // → 0
+ *
+ * // Movement blocked at the boundary
+ * resolveBoundedDelta({ value: 0, delta: -5, min: 0, max: 100 });
+ * // → null
+ * ```
+ */
+const resolveBoundedDelta = ({ delta, value, min, max, }) => {
+    if (delta === 0) {
+        return null;
+    }
+    const candidate = value + delta;
+    if (delta < 0) {
+        return value <= min ? null : Math.max(candidate, min);
+    }
+    if (delta > 0) {
+        return value >= max ? null : Math.min(candidate, max);
+    }
+    return null;
+};
+
+
 /***/ }),
 
 /***/ "./src/guards.ts":
@@ -2288,6 +2451,89 @@ __webpack_require__.r(__webpack_exports__);
 const camelToWords = (input) => input.replace(/([a-z0-9])([A-Z])/g, '$1 $2');
 
 
+/***/ }),
+
+/***/ "./src/string/find-char-indices.ts":
+/*!*****************************************!*\
+  !*** ./src/string/find-char-indices.ts ***!
+  \*****************************************/
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   findCharIndices: () => (/* binding */ findCharIndices)
+/* harmony export */ });
+/**
+ * Finds all zero-based indices where a given single character occurs in a string.
+ *
+ * The string is scanned once from start to end and each matching character position is collected.
+ *
+ * ⚠️ Character comparison is performed at the UTF-16 code unit level
+ * (`String.charCodeAt`), not by Unicode grapheme clusters.
+ *
+ * @param inputString - The string to scan.
+ * @param targetChar - A single character to search for.
+ *
+ * @returns An array of zero-based indices for each occurrence of `targetChar`.
+ *  Returns an empty array if no matches are found.
+ */
+const findCharIndices = (inputString, targetChar) => {
+    if (inputString.length === 0) {
+        return [];
+    }
+    const targetCode = targetChar.charCodeAt(0);
+    const indices = [];
+    for (let i = 0; i < inputString.length; i++) {
+        if (inputString.charCodeAt(i) === targetCode) {
+            indices.push(i);
+        }
+    }
+    return indices;
+};
+
+
+/***/ }),
+
+/***/ "./src/string/for-each-char.ts":
+/*!*************************************!*\
+  !*** ./src/string/for-each-char.ts ***!
+  \*************************************/
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   forEachChar: () => (/* binding */ forEachChar)
+/* harmony export */ });
+/**
+ * Iterates over each character of a string and invokes a callback for each one.
+ *
+ * Iteration is performed over UTF-16 code units (not Unicode grapheme clusters).
+ * Characters may be conditionally skipped using an optional predicate.
+ *
+ * @param input - The string to iterate over.
+ * @param onChar - Invoked for each character that is not skipped.
+ * @param shouldSkipChar - Optional predicate; returning `true` skips the character.
+ */
+const forEachChar = (input, onChar, shouldSkipChar) => {
+    if (input.length === 0) {
+        return;
+    }
+    const length = input.length;
+    for (let charIndex = 0; charIndex < length; charIndex++) {
+        const char = input[charIndex];
+        const context = {
+            charIndex,
+            prevChar: charIndex > 0 ? input[charIndex - 1] : null,
+            nextChar: charIndex < length - 1 ? input[charIndex + 1] : null,
+        };
+        if (shouldSkipChar?.(char, context)) {
+            continue;
+        }
+        onChar(char, context);
+    }
+};
+
+
 /***/ }),
 
 /***/ "./src/string/index.ts":
@@ -2300,8 +2546,11 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   camelToDashCase: () => (/* reexport safe */ _camel_to_dash_case__WEBPACK_IMPORTED_MODULE_2__.camelToDashCase),
 /* harmony export */   camelToWords: () => (/* reexport safe */ _camel_to_words__WEBPACK_IMPORTED_MODULE_3__.camelToWords),
+/* harmony export */   findCharIndices: () => (/* reexport safe */ _find_char_indices__WEBPACK_IMPORTED_MODULE_7__.findCharIndices),
+/* harmony export */   forEachChar: () => (/* reexport safe */ _for_each_char__WEBPACK_IMPORTED_MODULE_8__.forEachChar),
 /* harmony export */   isNilOrEmptyString: () => (/* reexport safe */ _is_nil_or_empty_string__WEBPACK_IMPORTED_MODULE_5__.isNilOrEmptyString),
 /* harmony export */   isString: () => (/* reexport safe */ _is_string__WEBPACK_IMPORTED_MODULE_0__.isString),
+/* harmony export */   parseFileName: () => (/* reexport safe */ _parse_file_name__WEBPACK_IMPORTED_MODULE_6__.parseFileName),
 /* harmony export */   splitStringIntoWords: () => (/* reexport safe */ _split_string_into_words__WEBPACK_IMPORTED_MODULE_4__.splitStringIntoWords),
 /* harmony export */   toKebabCase: () => (/* reexport safe */ _to_kebab_case__WEBPACK_IMPORTED_MODULE_1__.toKebabCase)
 /* harmony export */ });
@@ -2311,6 +2560,12 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _camel_to_words__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(/*! ./camel-to-words */ "./src/string/camel-to-words.ts");
 /* harmony import */ var _split_string_into_words__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(/*! ./split-string-into-words */ "./src/string/split-string-into-words.ts");
 /* harmony import */ var _is_nil_or_empty_string__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(/*! ./is-nil-or-empty-string */ "./src/string/is-nil-or-empty-string.ts");
+/* harmony import */ var _parse_file_name__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(/*! ./parse-file-name */ "./src/string/parse-file-name.ts");
+/* harmony import */ var _find_char_indices__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(/*! ./find-char-indices */ "./src/string/find-char-indices.ts");
+/* harmony import */ var _for_each_char__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(/*! ./for-each-char */ "./src/string/for-each-char.ts");
+
+
+
 
 
 
@@ -2370,6 +2625,43 @@ __webpack_require__.r(__webpack_exports__);
 const isString = (value) => typeof value === 'string';
 
 
+/***/ }),
+
+/***/ "./src/string/parse-file-name.ts":
+/*!***************************************!*\
+  !*** ./src/string/parse-file-name.ts ***!
+  \***************************************/
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   parseFileName: () => (/* binding */ parseFileName)
+/* harmony export */ });
+/**
+ * Splits a file name into its base name and extension.
+ *
+ * Special cases:
+ * - Files without a dot return `[fileName, ""]`
+ * - Hidden files like `.gitignore` return `[".gitignore", ""]`
+ * - Names ending with a trailing dot (e.g., `"file."`) return `["file.", ""]`
+ * - Multi-dot names (e.g., `"archive.tar.gz"`) split on the last dot
+ *
+ * @param fileName - The full file name to parse.
+ *
+ * @returns A tuple where:
+ *  - index 0 is the base name
+ *  - index 1 is the file extension (lowercased), or an empty string if none exists
+ */
+const parseFileName = (fileName) => {
+    const lastDotIndex = fileName.lastIndexOf('.');
+    // No dot or leading dot with no extension (e.g., ".gitignore")
+    if (lastDotIndex <= 0 || lastDotIndex === fileName.length - 1) {
+        return [fileName, ''];
+    }
+    return [fileName.slice(0, lastDotIndex), fileName.slice(lastDotIndex + 1).toLowerCase()];
+};
+
+
 /***/ }),
 
 /***/ "./src/string/split-string-into-words.ts":
@@ -2491,6 +2783,7 @@ var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   FOCUSABLE_HTML_TAGS: () => (/* reexport safe */ _a11y__WEBPACK_IMPORTED_MODULE_11__.FOCUSABLE_HTML_TAGS),
+/* harmony export */   applyInertiaStep: () => (/* reexport safe */ _geometry__WEBPACK_IMPORTED_MODULE_9__.applyInertiaStep),
 /* harmony export */   assert: () => (/* reexport safe */ _guards__WEBPACK_IMPORTED_MODULE_4__.assert),
 /* harmony export */   blobToFile: () => (/* reexport safe */ _file__WEBPACK_IMPORTED_MODULE_7__.blobToFile),
 /* harmony export */   calculateCenterOffset: () => (/* reexport safe */ _geometry__WEBPACK_IMPORTED_MODULE_9__.calculateCenterOffset),
@@ -2513,6 +2806,8 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   filterParallel: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_0__.filterParallel),
 /* harmony export */   filterSequential: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_0__.filterSequential),
 /* harmony export */   findAsync: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_0__.findAsync),
+/* harmony export */   findCharIndices: () => (/* reexport safe */ _string__WEBPACK_IMPORTED_MODULE_1__.findCharIndices),
+/* harmony export */   forEachChar: () => (/* reexport safe */ _string__WEBPACK_IMPORTED_MODULE_1__.forEachChar),
 /* harmony export */   getDOMRectIntersectionRatio: () => (/* reexport safe */ _intersection__WEBPACK_IMPORTED_MODULE_10__.getDOMRectIntersectionRatio),
 /* harmony export */   getElementOffsetRect: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.getElementOffsetRect),
 /* harmony export */   getFocusableHtmlElements: () => (/* reexport safe */ _a11y__WEBPACK_IMPORTED_MODULE_11__.getFocusableHtmlElements),
@@ -2559,11 +2854,12 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   not: () => (/* reexport safe */ _function__WEBPACK_IMPORTED_MODULE_3__.not),
 /* harmony export */   once: () => (/* reexport safe */ _function__WEBPACK_IMPORTED_MODULE_3__.once),
 /* harmony export */   parse2DMatrix: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.parse2DMatrix),
-/* harmony export */   parseFileName: () => (/* reexport safe */ _file__WEBPACK_IMPORTED_MODULE_7__.parseFileName),
+/* harmony export */   parseFileName: () => (/* reexport safe */ _string__WEBPACK_IMPORTED_MODULE_1__.parseFileName),
 /* harmony export */   pipe: () => (/* reexport safe */ _array__WEBPACK_IMPORTED_MODULE_2__.pipe),
 /* harmony export */   readFilesFromDataTransfer: () => (/* reexport safe */ _file__WEBPACK_IMPORTED_MODULE_7__.readFilesFromDataTransfer),
 /* harmony export */   reduceAsync: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_0__.reduceAsync),
 /* harmony export */   resolveAxisDelta: () => (/* reexport safe */ _intersection__WEBPACK_IMPORTED_MODULE_10__.resolveAxisDelta),
+/* harmony export */   resolveBoundedDelta: () => (/* reexport safe */ _geometry__WEBPACK_IMPORTED_MODULE_9__.resolveBoundedDelta),
 /* harmony export */   retry: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_0__.retry),
 /* harmony export */   runParallel: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_0__.runParallel),
 /* harmony export */   runSequential: () => (/* reexport safe */ _async__WEBPACK_IMPORTED_MODULE_0__.runSequential),