@react-hive/honey-layout 10.4.1 → 10.5.0

package/dist/index.dev.cjs

@@ -13725,6 +13725,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   useHoneyMediaQuery: () => (/* reexport safe */ _use_honey_media_query__WEBPACK_IMPORTED_MODULE_1__.useHoneyMediaQuery),
 /* harmony export */   useHoneyOnChange: () => (/* reexport safe */ _use_honey_on_change__WEBPACK_IMPORTED_MODULE_0__.useHoneyOnChange),
 /* harmony export */   useHoneyOverlay: () => (/* reexport safe */ _use_honey_overlay__WEBPACK_IMPORTED_MODULE_6__.useHoneyOverlay),
+/* harmony export */   useHoneyRafLoop: () => (/* reexport safe */ _use_honey_raf_loop__WEBPACK_IMPORTED_MODULE_11__.useHoneyRafLoop),
 /* harmony export */   useHoneyResize: () => (/* reexport safe */ _use_honey_resize__WEBPACK_IMPORTED_MODULE_7__.useHoneyResize),
 /* 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),
@@ -13742,6 +13743,8 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _use_honey_synthetic_scroll__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(/*! ./use-honey-synthetic-scroll */ "./src/hooks/use-honey-synthetic-scroll.ts");
 /* 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");
+
 
 
 
@@ -14166,6 +14169,149 @@ const useHoneyOverlay = (targetOverlayId, { onKeyUp } = {}) => {
 };
 
 
+/***/ },
+
+/***/ "./src/hooks/use-honey-raf-loop.ts"
+/*!*****************************************!*\
+  !*** ./src/hooks/use-honey-raf-loop.ts ***!
+  \*****************************************/
+(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   useHoneyRafLoop: () => (/* binding */ useHoneyRafLoop)
+/* 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__);
+
+/**
+ * A hook for running a controlled `requestAnimationFrame` loop.
+ *
+ * Features:
+ * - Explicit RAF lifecycle control (`start` / `stop`)
+ * - Delta time (`dt`) calculation with frame clamping
+ * - Automatic cleanup on unmounting
+ * - Conservative handling of tab visibility changes (mobile-safe)
+ * - Safe error handling (stops loop on exception)
+ *
+ * Visibility behavior:
+ * - The RAF loop is always stopped when the document becomes hidden
+ * - Automatic resume is disabled by default and must be explicitly enabled
+ *
+ * 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 options  - Optional configuration for the RAF loop.
+ *
+ * @returns Control helpers and RAF loop state.
+ *
+ * @example
+ * ```ts
+ * // Gesture-driven inertia (recommended usage)
+ * // The RAF loop stops itself when motion decays.
+ *
+ * const velocityRef = useRef({ x: 12, y: 4 });
+ *
+ * const onFrame = useCallback<HoneyRafCallback>(
+ *   (dtMs, { stop }) => {
+ *     velocityRef.current.x *= 0.94;
+ *     velocityRef.current.y *= 0.94;
+ *
+ *     setPosition(p => ({
+ *       x: p.x + velocityRef.current.x,
+ *       y: p.y + velocityRef.current.y,
+ *     }));
+ *
+ *     if (
+ *       Math.abs(velocityRef.current.x) < 0.1 &&
+ *       Math.abs(velocityRef.current.y) < 0.1
+ *     ) {
+ *       stop(); // terminate RAF loop
+ *     }
+ *   },
+ *   [],
+ * );
+ *
+ * useHoneyRafLoop(onFrame);
+ * ```
+ */
+const useHoneyRafLoop = (callback, { 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);
+    // Always keep the latest callback without restarting RAF
+    callbackRef.current = callback;
+    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;
+        }
+        let dt = time - lastTimeRef.current;
+        lastTimeRef.current = time;
+        // Clamp delta (prevents jumps after background tab / lag)
+        if (dt > maxDeltaMs) {
+            dt = maxDeltaMs;
+        }
+        try {
+            callbackRef.current(dt, {
+                stop: stopRafLoop,
+            });
+            rafIdRef.current = requestAnimationFrame(loop);
+        }
+        catch (e) {
+            stopRafLoop();
+            onError?.(e);
+        }
+    }, [maxDeltaMs, onError]);
+    const startRafLoop = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)(() => {
+        if (rafIdRef.current !== null) {
+            return;
+        }
+        lastTimeRef.current = null;
+        setIsRafLoopRunning(true);
+        rafIdRef.current = requestAnimationFrame(loop);
+    }, [loop]);
+    const stopRafLoop = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)(() => {
+        if (rafIdRef.current === null) {
+            return;
+        }
+        cancelAnimationFrame(rafIdRef.current);
+        rafIdRef.current = null;
+        lastTimeRef.current = null;
+        setIsRafLoopRunning(false);
+    }, []);
+    (0,react__WEBPACK_IMPORTED_MODULE_0__.useEffect)(() => {
+        if (autoStart) {
+            startRafLoop();
+        }
+        return stopRafLoop;
+    }, [autoStart, startRafLoop, stopRafLoop]);
+    // Pause when a tab is hidden (important for mobile)
+    (0,react__WEBPACK_IMPORTED_MODULE_0__.useEffect)(() => {
+        const onVisibilityChange = () => {
+            if (document.hidden) {
+                stopRafLoop();
+            }
+            else if (resumeOnVisibility && autoStart) {
+                startRafLoop();
+            }
+        };
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        return () => {
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        };
+    }, [autoStart, resumeOnVisibility, startRafLoop, stopRafLoop]);
+    return {
+        startRafLoop,
+        stopRafLoop,
+        isRafLoopRunning,
+    };
+};
+
+
 /***/ },
 
 /***/ "./src/hooks/use-honey-resize.ts"
@@ -15260,6 +15406,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   useHoneyOverlay: () => (/* reexport safe */ _hooks__WEBPACK_IMPORTED_MODULE_5__.useHoneyOverlay),
 /* harmony export */   useHoneyPopup: () => (/* reexport safe */ _components__WEBPACK_IMPORTED_MODULE_3__.useHoneyPopup),
 /* harmony export */   useHoneyPopupContext: () => (/* reexport safe */ _components__WEBPACK_IMPORTED_MODULE_3__.useHoneyPopupContext),
+/* harmony export */   useHoneyRafLoop: () => (/* reexport safe */ _hooks__WEBPACK_IMPORTED_MODULE_5__.useHoneyRafLoop),
 /* harmony export */   useHoneyResize: () => (/* reexport safe */ _hooks__WEBPACK_IMPORTED_MODULE_5__.useHoneyResize),
 /* harmony export */   useHoneySyntheticScroll: () => (/* reexport safe */ _hooks__WEBPACK_IMPORTED_MODULE_5__.useHoneySyntheticScroll),
 /* harmony export */   useHoneySyntheticScrollX: () => (/* reexport safe */ _hooks__WEBPACK_IMPORTED_MODULE_5__.useHoneySyntheticScrollX),