@react-hive/honey-layout 10.3.0 → 10.5.0

package/dist/components/HoneyOverlay.d.ts

@@ -1,6 +1,6 @@
 import type { FastOmit } from '@react-hive/honey-style';
 import type { ReactNode } from 'react';
-import type { HoneyActiveOverlay, HoneyOverlayId, Nullable } from '../types';
+import type { HoneyActiveOverlay, HoneyOverlayId, Nullable } from '~/types';
 import type { HoneyFlexProps } from './HoneyFlex';
 export interface HoneyOverlayContext {
     /**

package/dist/hooks/index.d.ts

@@ -9,3 +9,4 @@ export * from './use-honey-resize';
 export * from './use-honey-synthetic-scroll';
 export * from './use-honey-synthetic-scroll-x';
 export * from './use-honey-synthetic-scroll-y';
+export * from './use-honey-raf-loop';

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

@@ -0,0 +1,144 @@
+interface HoneyRafCallbackContext {
+    /**
+     * Stops the currently running RAF loop.
+     *
+     * Calling this function immediately:
+     * - Cancels the next animation frame
+     * - Resets internal timing state
+     * - Sets `isRafLoopRunning` to `false`
+     *
+     * 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).
+     */
+    stop: () => void;
+}
+/**
+ * RAF callback invoked on every animation frame.
+ *
+ * The callback is invoked with the elapsed time since the previous
+ * frame and a control context for managing the RAF loop lifecycle.
+ *
+ * ⚠️ Callback stability
+ * The callback should be wrapped in `useCallback` to ensure
+ * referential stability and to make dependencies explicit.
+ *
+ * @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 context - RAF loop control helpers.
+ */
+export type HoneyRafCallback = (dtMs: number, context: HoneyRafCallbackContext) => void;
+/**
+ * Configuration options for {@link useHoneyRafLoop}.
+ */
+interface UseHoneyRafLoopOptions {
+    /**
+     * Automatically start the RAF loop on mount.
+     *
+     * This is useful for continuous loops (e.g. visualizers),
+     * but should generally be disabled for gesture- or intent-driven animations.
+     *
+     * @default false
+     */
+    autoStart?: boolean;
+    /**
+     * Whether the RAF loop should automatically resume when the
+     * document becomes visible again after being hidden.
+     *
+     * ⚠️ Important:
+     * - Visibility changes will ALWAYS stop the RAF loop
+     * - Resuming is **opt-in** and never happens implicitly
+     *
+     * This option should only be enabled for truly continuous
+     * systems (e.g. game loops, live visualizations).
+     *
+     * It is intentionally disabled by default to avoid restarting
+     * gesture-driven or state-sensitive animations with stale data.
+     *
+     * Requires `autoStart` to be enabled.
+     *
+     * @default false
+     */
+    resumeOnVisibility?: boolean;
+    /**
+     * Maximum allowed delta time between frames.
+     *
+     * This prevents physics, inertia, or animation logic from receiving large
+     * time steps after backgrounding, tab switches, or frame drops.
+     *
+     * @default 32
+     */
+    maxDeltaMs?: number;
+    /**
+     * Optional error handler invoked when the RAF callback throws.
+     *
+     * When an error occurs:
+     * - The RAF loop is immediately stopped
+     * - `isRafLoopRunning` is set to `false`
+     * - The error is passed to this handler
+     *
+     * @default undefined
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * 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);
+ * ```
+ */
+export declare const useHoneyRafLoop: (callback: HoneyRafCallback, { autoStart, resumeOnVisibility, maxDeltaMs, onError, }?: UseHoneyRafLoopOptions) => {
+    startRafLoop: () => void;
+    stopRafLoop: () => void;
+    isRafLoopRunning: boolean;
+};
+export {};

package/dist/hooks/use-honey-synthetic-scroll.d.ts

@@ -1,8 +1,8 @@
 import type { RefObject } from 'react';
-import type { Nullable } from '../types';
+import { Axis } from '@react-hive/honey-utils';
+import type { Nullable } from '~/types';
 import type { HoneyDragHandlers } from './use-honey-drag';
-type Axis = 'x' | 'y' | 'both';
-interface ApplyAxisScrollParams {
+interface ResolveAxisTranslateOptions {
     /**
      * Drag delta for the axis (deltaX or deltaY).
      */
@@ -10,7 +10,7 @@ interface ApplyAxisScrollParams {
     /**
      * Current translate value for the axis.
      */
-    currentTranslate: number;
+    translate: number;
     /**
      * Visible container size for the axis (width or height).
      */
@@ -24,13 +24,7 @@ interface ApplyAxisScrollParams {
      */
     overscrollPct: number;
 }
-/**
- * Calculates the next translate value for a single scroll axis
- * and determines whether movement is allowed within bounds.
- *
- * @returns The next translate value, or `null` if movement is not allowed.
- */
-export declare const applyAxisScroll: ({ delta, currentTranslate, containerSize, overflowSize, overscrollPct, }: ApplyAxisScrollParams) => Nullable<number>;
+export declare const resolveAxisTranslate: ({ delta, translate, containerSize, overflowSize, overscrollPct, }: ResolveAxisTranslateOptions) => Nullable<number>;
 export interface UseHoneySyntheticScrollOptions<Element extends HTMLElement> extends Pick<HoneyDragHandlers<Element>, 'onStartDrag' | 'onEndDrag'> {
     /**
      * Axis along which synthetic scrolling is enabled.
@@ -62,6 +56,19 @@ export interface UseHoneySyntheticScrollOptions<Element extends HTMLElement> ext
      * @default true
      */
     resetOnResize?: boolean;
+    /**
+     * Enables synthetic scrolling driven by pointer-based scroll input,
+     * such as mouse wheels and trackpads.
+     *
+     * When enabled, scroll input is intercepted and converted into bounded
+     * translation using the same logic as drag gestures.
+     *
+     * When disabled, native scrolling behavior is preserved and no scroll
+     * input is handled by this hook.
+     *
+     * @default true
+     */
+    enablePointerScroll?: boolean;
 }
 /**
  * Enables synthetic scrolling for a container using pointer-based drag gestures.
@@ -85,5 +92,5 @@ export interface UseHoneySyntheticScrollOptions<Element extends HTMLElement> ext
  *
  * @returns A ref that must be attached to the scrollable container element.
  */
-export declare const useHoneySyntheticScroll: <Element extends HTMLElement>({ axis, overscrollPct, onStartDrag, onEndDrag, resetOnResize, }?: UseHoneySyntheticScrollOptions<Element>) => RefObject<Nullable<Element>>;
+export declare const useHoneySyntheticScroll: <Element extends HTMLElement>({ axis, overscrollPct, onStartDrag, onEndDrag, resetOnResize, enablePointerScroll, }?: UseHoneySyntheticScrollOptions<Element>) => RefObject<Nullable<Element>>;
 export {};