@react-hive/honey-utils 3.16.0 → 3.18.0

package/dist/index.dev.cjs

@@ -1631,75 +1631,47 @@ __webpack_require__.r(__webpack_exports__);
 /* 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.
+ * Advances a value by a single inertial step using velocity,
+ * elapsed time, exponential friction, and hard bounds.
  *
- * This utility models **inertial motion** (momentum + decay) on top of
- * {@link resolveBoundedDelta}, which acts as the authoritative constraint layer.
+ * This function models **momentum-driven motion** and delegates
+ * boundary enforcement to {@link resolveBoundedDelta}, which guarantees:
+ * - no overshoot
+ * - no jitter at bounds
+ * - deterministic stopping behavior
  *
- * 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`).
+ * ### Termination conditions
+ * Inertia stops immediately when:
+ * - the absolute velocity falls below `minVelocityPxMs`, or
+ * - movement in the current direction is blocked by a bound
+ *
+ * ---
+ *
+ * ⚠️ **Single-step function**
+ * This function performs **one inertia step only**.
+ * It must be called repeatedly from an animation loop
+ * (e.g. `requestAnimationFrame`) to produce continuous motion.
+ *
+ * ---
  *
  * ### Common use cases
  * - Synthetic scrolling with momentum
+ * - Drag-to-scroll interactions
  * - 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);
- * ```
+ * @returns An {@link InertiaStepResult} when inertia is still active,
+ *          or `null` when inertia has completed or further movement
+ *          is not possible.
  */
-const applyInertiaStep = ({ value, min, max, velocity, deltaTime, friction = 0.002, minVelocity = 0.01, }) => {
-    if (Math.abs(velocity) < minVelocity) {
+const applyInertiaStep = ({ value, min, max, velocityPxMs, deltaTimeMs, friction = 0.002, minVelocityPxMs = 0.01, }) => {
+    if (Math.abs(velocityPxMs) < minVelocityPxMs) {
         return null;
     }
     // Distance we want to move this frame
-    const delta = velocity * deltaTime;
+    const delta = velocityPxMs * deltaTimeMs;
     const nextValue = (0,_geometry__WEBPACK_IMPORTED_MODULE_0__.resolveBoundedDelta)({
         delta,
         value,
@@ -1711,11 +1683,11 @@ const applyInertiaStep = ({ value, min, max, velocity, deltaTime, friction = 0.0
         return null;
     }
     // Apply exponential friction
-    const decay = Math.exp(-friction * deltaTime);
-    const nextVelocity = velocity * decay;
+    const decay = Math.exp(-friction * deltaTimeMs);
+    const nextVelocityPxMs = velocityPxMs * decay;
     return {
         value: nextValue,
-        velocity: nextVelocity,
+        velocityPxMs: nextVelocityPxMs,
     };
 };
 
@@ -2471,20 +2443,20 @@ __webpack_require__.r(__webpack_exports__);
  * ⚠️ 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 input - 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) {
+const findCharIndices = (input, targetChar) => {
+    if (input.length === 0) {
         return [];
     }
     const targetCode = targetChar.charCodeAt(0);
     const indices = [];
-    for (let i = 0; i < inputString.length; i++) {
-        if (inputString.charCodeAt(i) === targetCode) {
+    for (let i = 0; i < input.length; i++) {
+        if (input.charCodeAt(i) === targetCode) {
             indices.push(i);
         }
     }
@@ -2534,6 +2506,43 @@ const forEachChar = (input, onChar, shouldSkipChar) => {
 };
 
 
+/***/ }),
+
+/***/ "./src/string/get-words-initials.ts":
+/*!******************************************!*\
+  !*** ./src/string/get-words-initials.ts ***!
+  \******************************************/
+/***/ ((__unused_webpack_module, __webpack_exports__, __webpack_require__) => {
+
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   getWordsInitials: () => (/* binding */ getWordsInitials)
+/* harmony export */ });
+/* harmony import */ var _split_string_into_words__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./split-string-into-words */ "./src/string/split-string-into-words.ts");
+
+/**
+ * Returns the uppercase initials of the words in a string.
+ *
+ * The first character of each word is extracted, concatenated, and uppercased.
+ *
+ * @param input - The input string.
+ * @param maxWords - Maximum number of words to include when generating initials.
+ *   Defaults to `Infinity`.
+ *
+ * @returns A string containing the uppercase initials of the selected words.
+ */
+const getWordsInitials = (input, maxWords = Infinity) => {
+    if (input.length === 0) {
+        return '';
+    }
+    return (0,_split_string_into_words__WEBPACK_IMPORTED_MODULE_0__.splitStringIntoWords)(input)
+        .slice(0, maxWords)
+        .map(word => word[0])
+        .join('')
+        .toUpperCase();
+};
+
+
 /***/ }),
 
 /***/ "./src/string/index.ts":
@@ -2548,6 +2557,7 @@ __webpack_require__.r(__webpack_exports__);
 /* 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 */   getWordsInitials: () => (/* reexport safe */ _get_words_initials__WEBPACK_IMPORTED_MODULE_9__.getWordsInitials),
 /* 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),
@@ -2563,6 +2573,8 @@ __webpack_require__.r(__webpack_exports__);
 /* 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");
+/* harmony import */ var _get_words_initials__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(/*! ./get-words-initials */ "./src/string/get-words-initials.ts");
+
 
 
 
@@ -2681,7 +2693,12 @@ __webpack_require__.r(__webpack_exports__);
  *
  * @returns An array of words from the input string.
  */
-const splitStringIntoWords = (input) => input.split(' ').filter(Boolean);
+const splitStringIntoWords = (input) => {
+    if (input.length === 0) {
+        return [];
+    }
+    return input.split(' ').filter(Boolean);
+};
 
 
 /***/ }),
@@ -2812,6 +2829,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   getElementOffsetRect: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.getElementOffsetRect),
 /* harmony export */   getFocusableHtmlElements: () => (/* reexport safe */ _a11y__WEBPACK_IMPORTED_MODULE_11__.getFocusableHtmlElements),
 /* harmony export */   getLocalStorageCapabilities: () => (/* reexport safe */ _env__WEBPACK_IMPORTED_MODULE_12__.getLocalStorageCapabilities),
+/* harmony export */   getWordsInitials: () => (/* reexport safe */ _string__WEBPACK_IMPORTED_MODULE_1__.getWordsInitials),
 /* harmony export */   getXOverflowWidth: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.getXOverflowWidth),
 /* harmony export */   getYOverflowHeight: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.getYOverflowHeight),
 /* harmony export */   hasXOverflow: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.hasXOverflow),