@react-hive/honey-layout 10.6.0 → 10.8.0

package/dist/hooks/use-honey-raf-loop.d.ts

@@ -1,36 +1,37 @@
-interface HoneyRafCallbackContext {
+interface HoneyRafOnFrameContext {
     /**
-     * Stops the currently running RAF loop.
+     * Immediately terminates the active `requestAnimationFrame` loop.
      *
-     * Calling this function immediately:
-     * - Cancels the next animation frame
-     * - Resets internal timing state
-     * - Sets `isRafLoopRunning` to `false`
+     * This method is **safe to call synchronously from within the frame handler**
+     * and is the **recommended mechanism** for ending frame-driven processes based on runtime conditions.
      *
-     * This function is safe to call from within the RAF callback
-     * and is the preferred way to terminate the loop based on
-     * frame-driven conditions (e.g. inertia decay, animation completion).
+     * Typical use cases:
+     * - Inertia or momentum decay reaching a threshold
+     * - Animation or transition completion
+     * - Time- or state-based termination conditions
      */
     stop: () => void;
 }
 /**
- * RAF callback invoked on every animation frame.
+ * Function invoked on every animation frame while the RAF loop is active.
  *
- * The callback is invoked with the elapsed time since the previous
- * frame and a control context for managing the RAF loop lifecycle.
+ * The handler is expected to be **side-effect driven** and may:
+ * - Mutate refs
+ * - Update React state
+ * - Stop the RAF loop via `context.stop()`
  *
- * ⚠️ Callback stability
- * The callback should be wrapped in `useCallback` to ensure
- * referential stability and to make dependencies explicit.
+ * ⚠️ Referential stability
+ * This handler **must be wrapped in `useCallback`** to avoid unnecessary
+ * re-bindings and to ensure predictable behavior across renders.
  *
- * @param dtMs - Delta time in milliseconds since the previous frame.
- *               The value is clamped to `maxDeltaMs` to avoid large jumps
- *               when the tab is inactive, backgrounded, or the browser
- *               throttles animation frames.
+ * @param deltaTimeMs - Time delta in milliseconds since the previous frame.
+ *                      This value is clamped to `maxDeltaMs` to prevent large
+ *                      time steps caused by tab backgrounding, visibility changes,
+ *                      or browser throttling.
  *
- * @param context - RAF loop control helpers.
+ * @param context - RAF lifecycle control context. See {@link HoneyRafOnFrameContext}.
  */
-export type HoneyRafCallback = (dtMs: number, context: HoneyRafCallbackContext) => void;
+export type HoneyRafOnFrameHandler = (deltaTimeMs: number, context: HoneyRafOnFrameContext) => void;
 /**
  * Configuration options for {@link useHoneyRafLoop}.
  */
@@ -84,12 +85,35 @@ interface UseHoneyRafLoopOptions {
      */
     onError?: (error: unknown) => void;
 }
+/**
+ * Public control API returned by {@link useHoneyRafLoop}.
+ */
+export interface HoneyRafLoopApi {
+    /**
+     * Indicates whether the RAF loop is currently running.
+     */
+    isRunning: boolean;
+    /**
+     * Starts the RAF loop.
+     *
+     * If the loop is already running, this call is ignored.
+     */
+    start: () => void;
+    /**
+     * Stops the RAF loop immediately.
+     *
+     * This method is safe to call:
+     * - From user code
+     * - From within the RAF frame handler
+     */
+    stop: () => void;
+}
 /**
  * A hook for running a controlled `requestAnimationFrame` loop.
  *
  * Features:
  * - Explicit RAF lifecycle control (`start` / `stop`)
- * - Delta time (`dt`) calculation with frame clamping
+ * - Delta time calculation with frame clamping
  * - Automatic cleanup on unmounting
  * - Conservative handling of tab visibility changes (mobile-safe)
  * - Safe error handling (stops loop on exception)
@@ -101,7 +125,7 @@ interface UseHoneyRafLoopOptions {
  * 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.
@@ -113,7 +137,7 @@ interface UseHoneyRafLoopOptions {
  *
  * 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;
@@ -136,9 +160,5 @@ interface UseHoneyRafLoopOptions {
  * useHoneyRafLoop(onFrame);
  * ```
  */
-export declare const useHoneyRafLoop: (callback: HoneyRafCallback, { autoStart, resumeOnVisibility, maxDeltaMs, onError, }?: UseHoneyRafLoopOptions) => {
-    startRafLoop: () => void;
-    stopRafLoop: () => void;
-    isRafLoopRunning: boolean;
-};
+export declare const useHoneyRafLoop: (onFrame: HoneyRafOnFrameHandler, { autoStart, resumeOnVisibility, maxDeltaMs, onError, }?: UseHoneyRafLoopOptions) => HoneyRafLoopApi;
 export {};

package/dist/hooks/use-honey-timer.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Timer operating mode.
+ *
+ * - `countdown` — decreases time until it reaches `targetTimeMs`
+ * - `countup` — increases time until it reaches `targetTimeMs` (if provided)
+ */
+type UseHoneyTimerMode = 'countdown' | 'countup';
+type UseHoneyTimerOnEndHandler = () => void;
+export interface UseHoneyTimerOptions {
+    /**
+     * Initial timer value in milliseconds.
+     *
+     * - Countdown: starting time
+     * - Count-up: initial offset
+     */
+    initialTimeMs: number;
+    /**
+     * Target time in milliseconds.
+     *
+     * - Countdown: usually `0`
+     * - Count-up: optional upper limit
+     *
+     * When reached, the timer stops and `onEnd` is invoked.
+     *
+     * @default 0
+     */
+    targetTimeMs?: number;
+    /**
+     * Direction in which the timer progresses.
+     *
+     * @default 'countdown'
+     */
+    mode?: UseHoneyTimerMode;
+    /**
+     * Whether the timer should automatically start on mount.
+     *
+     * @default false
+     */
+    autoStart?: boolean;
+    /**
+     * Optional callback invoked exactly once when the timer reaches the target time.
+     */
+    onEnd?: UseHoneyTimerOnEndHandler;
+}
+/**
+ * Public control API returned by {@link useHoneyTimer}.
+ */
+export interface UseHoneyTimerApi {
+    /**
+     * Current timer value in milliseconds.
+     *
+     * This value updates over time while the timer is running.
+     */
+    timeMs: number;
+    /**
+     * Indicates whether the timer is currently progressing.
+     */
+    isRunning: boolean;
+    /**
+     * Starts the timer from `initialTimeMs`, resetting any previous state.
+     */
+    start: () => void;
+    /**
+     * Pauses the timer while preserving the current time value.
+     */
+    pause: () => void;
+    /**
+     * Resumes the timer from its current time value.
+     *
+     * Has no effect if the timer is already running.
+     */
+    resume: () => void;
+    /**
+     * Resets the timer to a specific time value.
+     *
+     * @param timeMs - Optional new timer value. Defaults to `initialTimeMs`.
+     */
+    reset: (timeMs?: number) => void;
+}
+/**
+ * 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();
+ * ```
+ */
+export declare const useHoneyTimer: ({ initialTimeMs, targetTimeMs, mode, autoStart, onEnd, }: UseHoneyTimerOptions) => UseHoneyTimerApi;
+export {};