@react-hive/honey-layout 10.6.0 → 10.7.0

package/dist/index.dev.cjs

@@ -13730,6 +13730,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   useHoneySyntheticScroll: () => (/* reexport safe */ _use_honey_synthetic_scroll__WEBPACK_IMPORTED_MODULE_8__.useHoneySyntheticScroll),
 /* harmony export */   useHoneySyntheticScrollX: () => (/* reexport safe */ _use_honey_synthetic_scroll_x__WEBPACK_IMPORTED_MODULE_9__.useHoneySyntheticScrollX),
 /* harmony export */   useHoneySyntheticScrollY: () => (/* reexport safe */ _use_honey_synthetic_scroll_y__WEBPACK_IMPORTED_MODULE_10__.useHoneySyntheticScrollY),
+/* harmony export */   useHoneyTimer: () => (/* reexport safe */ _use_honey_timer__WEBPACK_IMPORTED_MODULE_12__.useHoneyTimer),
 /* harmony export */   useRegisterHoneyOverlay: () => (/* reexport safe */ _use_register_honey_overlay__WEBPACK_IMPORTED_MODULE_5__.useRegisterHoneyOverlay)
 /* harmony export */ });
 /* harmony import */ var _use_honey_on_change__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./use-honey-on-change */ "./src/hooks/use-honey-on-change.ts");
@@ -13744,6 +13745,8 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _use_honey_synthetic_scroll_x__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(/*! ./use-honey-synthetic-scroll-x */ "./src/hooks/use-honey-synthetic-scroll-x.ts");
 /* harmony import */ var _use_honey_synthetic_scroll_y__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(/*! ./use-honey-synthetic-scroll-y */ "./src/hooks/use-honey-synthetic-scroll-y.ts");
 /* harmony import */ var _use_honey_raf_loop__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(/*! ./use-honey-raf-loop */ "./src/hooks/use-honey-raf-loop.ts");
+/* harmony import */ var _use_honey_timer__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(/*! ./use-honey-timer */ "./src/hooks/use-honey-timer.ts");
+
 
 
 
@@ -14203,7 +14206,7 @@ __webpack_require__.r(__webpack_exports__);
  * This hook is designed for gesture handling, inertia, physics simulations,
  * and animation loops that must not trigger React re-renders on every frame.
  *
- * @param callback - Function invoked on each animation frame.
+ * @param onFrame - Function invoked on each animation frame.
  * @param options  - Optional configuration for the RAF loop.
  *
  * @returns Control helpers and RAF loop state.
@@ -14215,7 +14218,7 @@ __webpack_require__.r(__webpack_exports__);
  *
  * const velocityRef = useRef({ x: 12, y: 4 });
  *
- * const onFrame = useCallback<HoneyRafCallback>(
+ * const onFrame = useCallback<HoneyRafOnFrameHandler>(
  *   (dtMs, { stop }) => {
  *     velocityRef.current.x *= 0.94;
  *     velocityRef.current.y *= 0.94;
@@ -14238,27 +14241,27 @@ __webpack_require__.r(__webpack_exports__);
  * useHoneyRafLoop(onFrame);
  * ```
  */
-const useHoneyRafLoop = (callback, { autoStart = false, resumeOnVisibility = false, maxDeltaMs = 32, // ~30fps clamp
+const useHoneyRafLoop = (onFrame, { autoStart = false, resumeOnVisibility = false, maxDeltaMs = 32, // ~30fps clamp
 onError, } = {}) => {
     const rafIdRef = (0,react__WEBPACK_IMPORTED_MODULE_0__.useRef)(null);
-    const lastTimeRef = (0,react__WEBPACK_IMPORTED_MODULE_0__.useRef)(null);
-    const callbackRef = (0,react__WEBPACK_IMPORTED_MODULE_0__.useRef)(callback);
+    const lastTimeMsRef = (0,react__WEBPACK_IMPORTED_MODULE_0__.useRef)(null);
+    const onFrameRef = (0,react__WEBPACK_IMPORTED_MODULE_0__.useRef)(onFrame);
     // Always keep the latest callback without restarting RAF
-    callbackRef.current = callback;
+    onFrameRef.current = onFrame;
     const [isRafLoopRunning, setIsRafLoopRunning] = (0,react__WEBPACK_IMPORTED_MODULE_0__.useState)(false);
-    const loop = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)(time => {
-        if (lastTimeRef.current === null) {
-            lastTimeRef.current = time;
+    const loop = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)(timeMs => {
+        if (lastTimeMsRef.current === null) {
+            lastTimeMsRef.current = timeMs;
         }
-        let dt = time - lastTimeRef.current;
-        lastTimeRef.current = time;
+        let deltaTimeMs = timeMs - lastTimeMsRef.current;
+        lastTimeMsRef.current = timeMs;
         // Clamp delta (prevents jumps after background tab / lag)
-        if (dt > maxDeltaMs) {
-            dt = maxDeltaMs;
+        if (deltaTimeMs > maxDeltaMs) {
+            deltaTimeMs = maxDeltaMs;
         }
         try {
-            callbackRef.current(dt, {
-                stop: stopRafLoop,
+            onFrameRef.current(deltaTimeMs, {
+                stopRafLoop,
             });
             rafIdRef.current = requestAnimationFrame(loop);
         }
@@ -14271,7 +14274,7 @@ onError, } = {}) => {
         if (rafIdRef.current !== null) {
             return;
         }
-        lastTimeRef.current = null;
+        lastTimeMsRef.current = null;
         setIsRafLoopRunning(true);
         rafIdRef.current = requestAnimationFrame(loop);
     }, [loop]);
@@ -14281,7 +14284,7 @@ onError, } = {}) => {
         }
         cancelAnimationFrame(rafIdRef.current);
         rafIdRef.current = null;
-        lastTimeRef.current = null;
+        lastTimeMsRef.current = null;
         setIsRafLoopRunning(false);
     }, []);
     (0,react__WEBPACK_IMPORTED_MODULE_0__.useEffect)(() => {
@@ -14306,9 +14309,9 @@ onError, } = {}) => {
         };
     }, [autoStart, resumeOnVisibility, startRafLoop, stopRafLoop]);
     return {
+        isRafLoopRunning,
         startRafLoop,
         stopRafLoop,
-        isRafLoopRunning,
     };
 };
 
@@ -14618,6 +14621,120 @@ const useHoneySyntheticScroll = ({ axis = 'both', overscrollPct = 0, onStartDrag
 };
 
 
+/***/ },
+
+/***/ "./src/hooks/use-honey-timer.ts"
+/*!**************************************!*\
+  !*** ./src/hooks/use-honey-timer.ts ***!
+  \**************************************/
+(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   useHoneyTimer: () => (/* binding */ useHoneyTimer)
+/* harmony export */ });
+/* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! react */ "react");
+/* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0___default = /*#__PURE__*/__webpack_require__.n(react__WEBPACK_IMPORTED_MODULE_0__);
+/* harmony import */ var _use_honey_raf_loop__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ./use-honey-raf-loop */ "./src/hooks/use-honey-raf-loop.ts");
+
+
+/**
+ * A high-precision timer hook built on top of {@link useHoneyRafLoop}.
+ *
+ * Features:
+ * - Frame-accurate time progression using `requestAnimationFrame`
+ * - Supports countdown and count-up modes
+ * - Explicit lifecycle control (start / pause / resume / reset)
+ * - Drift-free timing using delta-based updates
+ * - Safe completion handling via `onEnd`
+ *
+ * Architectural notes:
+ * - Time progression is handled imperatively via refs to avoid stale closures and unnecessary re-renders.
+ * - React state is updated only with the derived timer value.
+ * - RAF lifecycle is fully delegated to `useHoneyRafLoop`.
+ *
+ * @example
+ * ```ts
+ * const timer = useHoneyTimer({
+ *   initialTimeMs: 10_000,
+ *   targetTimeMs: 0,
+ *   onEnd: () => console.log('Done'),
+ * });
+ *
+ * timer.startTimer();
+ * ```
+ */
+const useHoneyTimer = ({ initialTimeMs, targetTimeMs = 0, mode = 'countdown', autoStart = false, onEnd, }) => {
+    const [timeMs, setTimeMs] = (0,react__WEBPACK_IMPORTED_MODULE_0__.useState)(initialTimeMs);
+    const timeRef = (0,react__WEBPACK_IMPORTED_MODULE_0__.useRef)(timeMs);
+    timeRef.current = timeMs;
+    const onEndRef = (0,react__WEBPACK_IMPORTED_MODULE_0__.useRef)(onEnd);
+    onEndRef.current = onEnd;
+    /**
+     * RAF frame handler responsible for advancing the timer.
+     *
+     * - Computes the next timer value based on `deltaTimeMs`
+     * - Detects completion and stops the RAF loop
+     * - Updates React state with the derived value
+     */
+    const onFrameHandler = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)((deltaTimeMs, { stopRafLoop }) => {
+        let nextTime = mode === 'countdown' ? timeRef.current - deltaTimeMs : timeRef.current + deltaTimeMs;
+        let finished = false;
+        if (mode === 'countdown') {
+            if (nextTime <= targetTimeMs) {
+                nextTime = targetTimeMs;
+                finished = true;
+            }
+        }
+        else if (targetTimeMs > 0 && nextTime >= targetTimeMs) {
+            nextTime = targetTimeMs;
+            finished = true;
+        }
+        timeRef.current = nextTime;
+        setTimeMs(nextTime);
+        if (finished) {
+            stopRafLoop();
+            onEndRef.current?.();
+        }
+    }, [mode, targetTimeMs]);
+    const { startRafLoop, stopRafLoop, isRafLoopRunning } = (0,_use_honey_raf_loop__WEBPACK_IMPORTED_MODULE_1__.useHoneyRafLoop)(onFrameHandler, {
+        autoStart,
+    });
+    const startTimer = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)(() => {
+        timeRef.current = initialTimeMs;
+        setTimeMs(initialTimeMs);
+        startRafLoop();
+    }, [initialTimeMs, startRafLoop]);
+    const pauseTimer = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)(() => {
+        stopRafLoop();
+    }, [stopRafLoop]);
+    const resumeTimer = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)(() => {
+        if (!isRafLoopRunning) {
+            startRafLoop();
+        }
+    }, [isRafLoopRunning, startRafLoop]);
+    const resetTimer = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)((nextTimeMs = initialTimeMs) => {
+        stopRafLoop();
+        timeRef.current = nextTimeMs;
+        setTimeMs(nextTimeMs);
+    }, [initialTimeMs, stopRafLoop]);
+    (0,react__WEBPACK_IMPORTED_MODULE_0__.useEffect)(() => {
+        if (autoStart) {
+            startTimer();
+        }
+    }, [autoStart, startTimer]);
+    return {
+        timerTimeMs: timeMs,
+        isTimerRunning: isRafLoopRunning,
+        startTimer,
+        pauseTimer,
+        resumeTimer,
+        resetTimer,
+    };
+};
+
+
 /***/ },
 
 /***/ "./src/hooks/use-register-honey-overlay.ts"
@@ -15412,6 +15529,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   useHoneySyntheticScroll: () => (/* reexport safe */ _hooks__WEBPACK_IMPORTED_MODULE_5__.useHoneySyntheticScroll),
 /* harmony export */   useHoneySyntheticScrollX: () => (/* reexport safe */ _hooks__WEBPACK_IMPORTED_MODULE_5__.useHoneySyntheticScrollX),
 /* harmony export */   useHoneySyntheticScrollY: () => (/* reexport safe */ _hooks__WEBPACK_IMPORTED_MODULE_5__.useHoneySyntheticScrollY),
+/* harmony export */   useHoneyTimer: () => (/* reexport safe */ _hooks__WEBPACK_IMPORTED_MODULE_5__.useHoneyTimer),
 /* harmony export */   useRegisterHoneyOverlay: () => (/* reexport safe */ _hooks__WEBPACK_IMPORTED_MODULE_5__.useRegisterHoneyOverlay),
 /* harmony export */   warnOnce: () => (/* reexport safe */ _utils__WEBPACK_IMPORTED_MODULE_6__.warnOnce)
 /* harmony export */ });