@react-hive/honey-utils 3.17.0 → 3.19.0

package/dist/index.dev.cjs

@@ -1631,75 +1631,50 @@ __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.
+ * Applies a **single step** of bounded, velocity-based inertia.
  *
- * 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** by:
+ * - integrating velocity over elapsed time
+ * - applying exponential friction
+ * - optionally smoothing velocity using EMA
+ * - enforcing hard bounds via {@link resolveBoundedDelta}
  *
- * 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
+ * Boundary handling guarantees:
+ * - no overshoot
+ * - no oscillation at limits
+ * - deterministic stopping behavior
  *
- * ⚠️ 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
+ * ### Termination conditions
+ * Inertia ends immediately when:
+ * - the absolute velocity falls below `minVelocityPxMs`, or
+ * - movement in the current direction is blocked by a bound
  *
- * @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.
+ * ⚠️ **Single-step function**
+ * This function advances inertia **once only**.
+ * It must be invoked repeatedly from an animation loop
+ * (e.g. `requestAnimationFrame`) to produce continuous motion.
  *
- * @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);
- * };
+ * ### Common use cases
+ * - Synthetic scrolling with momentum
+ * - Drag-to-scroll interactions
+ * - Carousels and sliders
+ * - Timelines and scrubbers
  *
- * requestAnimationFrame(step);
- * ```
+ * @returns An {@link InertiaStepResult} while inertia remains active,
+ *          or `null` when inertia has completed or cannot proceed.
  */
-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, emaAlpha = 0.2, }) => {
+    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 +1686,15 @@ 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 pureVelocityPxMs = velocityPxMs * decay;
+    const nextVelocityPxMs = emaAlpha > 0 ? velocityPxMs * (1 - emaAlpha) + pureVelocityPxMs * emaAlpha : pureVelocityPxMs;
+    if (Math.abs(nextVelocityPxMs) < minVelocityPxMs) {
+        return null;
+    }
     return {
         value: nextValue,
-        velocity: nextVelocity,
+        velocityPxMs: nextVelocityPxMs,
     };
 };