@react-hive/honey-layout 15.0.0 → 16.1.0

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

@@ -1,164 +0,0 @@
-interface UseHoneyRafFrameContext {
-    /**
-     * Immediately terminates the active `requestAnimationFrame` loop.
-     *
-     * 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.
-     *
-     * Typical use cases:
-     * - Inertia or momentum decay reaching a threshold
-     * - Animation or transition completion
-     * - Time- or state-based termination conditions
-     */
-    stop: () => void;
-}
-/**
- * Function invoked on every animation frame while the RAF loop is active.
- *
- * The handler is expected to be **side-effect driven** and may:
- * - Mutate refs
- * - Update React state
- * - Stop the RAF loop via `context.stop()`
- *
- * ⚠️ Referential stability
- * This handler **must be wrapped in `useCallback`** to avoid unnecessary
- * re-bindings and to ensure predictable behavior across renders.
- *
- * @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 lifecycle control context. See {@link UseHoneyRafFrameContext}.
- */
-export type UseHoneyRafOnFrameHandler = (deltaTimeMs: number, context: UseHoneyRafFrameContext) => 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;
-}
-/**
- * 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 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 onFrame - 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<HoneyRafOnFrameHandler>(
- *   (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: (onFrame: UseHoneyRafOnFrameHandler, { autoStart, resumeOnVisibility, maxDeltaMs, onError, }?: UseHoneyRafLoopOptions) => HoneyRafLoopApi;
-export {};

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

@@ -1,45 +0,0 @@
-export type UseHoneyResizeHandler = () => void;
-interface UseHoneyResizeOptions {
-    /**
-     * Whether to invoke the resize handler immediately on mount.
-     *
-     * Useful when initial layout measurements should be performed
-     * before any resize events occur.
-     *
-     * @default false
-     */
-    invokeOnMount?: boolean;
-    /**
-     * Throttle delay (in milliseconds) applied to the resize handler.
-     *
-     * When greater than `0`, the handler will be throttled using
-     * `lodash.throttle` to reduce invocation frequency.
-     *
-     * @default 0
-     */
-    throttleTime?: number;
-    /**
-     * Enables or disables the resize listener.
-     *
-     * @default true
-     */
-    enabled?: boolean;
-}
-/**
- * A hook that subscribes to the window `resize` event and invokes a handler function in response.
- *
- * The handler can be optionally throttled to limit execution frequency, which is useful
- * for expensive layout calculations or DOM measurements.
- *
- * @example
- * ```ts
- * useHoneyResize(() => {
- *   console.log('Window resized');
- * }, { throttleTime: 200 });
- * ```
- *
- * @param handler - Callback invoked when the window is resized.
- * @param options - Configuration options controlling invocation timing and performance.
- */
-export declare const useHoneyResize: (handler: UseHoneyResizeHandler, { invokeOnMount, throttleTime, enabled }?: UseHoneyResizeOptions) => void;
-export {};

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

@@ -1,19 +0,0 @@
-import type { UseHoneySyntheticScrollOptions } from './use-honey-synthetic-scroll';
-/**
- * Enables synthetic horizontal (X-axis) scrolling for a container element
- * using pointer-based drag interactions.
- *
- * This is a convenience wrapper around {@link useHoneySyntheticScroll} with
- * the axis fixed to `'x'`.
- *
- * All behavior, boundaries, and lifecycle guarantees are identical to the
- * base hook, but limited to horizontal movement only.
- *
- * @template Element - The HTML element type of the scrollable container.
- *
- * @param options - Configuration options forwarded to
- * {@link useHoneySyntheticScroll}, excluding the `axis` option.
- *
- * @returns A ref that must be attached to the scrollable container element.
- */
-export declare const useHoneySyntheticScrollX: <Element extends HTMLElement>(options?: Omit<UseHoneySyntheticScrollOptions<Element>, "axis">) => import("react").RefObject<import("..").Nullable<Element>>;

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

@@ -1,19 +0,0 @@
-import type { UseHoneySyntheticScrollOptions } from './use-honey-synthetic-scroll';
-/**
- * Enables synthetic vertical (Y-axis) scrolling for a container element
- * using pointer-based drag interactions.
- *
- * This is a convenience wrapper around {@link useHoneySyntheticScroll} with
- * the axis fixed to `'y'`.
- *
- * All behavior, boundaries, and lifecycle guarantees are identical to the
- * base hook, but limited to vertical movement only.
- *
- * @template Element - The HTML element type of the scrollable container.
- *
- * @param options - Configuration options forwarded to
- * {@link useHoneySyntheticScroll}, excluding the `axis` option.
- *
- * @returns A ref that must be attached to the scrollable container element.
- */
-export declare const useHoneySyntheticScrollY: <Element extends HTMLElement>(options?: Omit<UseHoneySyntheticScrollOptions<Element>, "axis">) => import("react").RefObject<import("..").Nullable<Element>>;

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

@@ -1,143 +0,0 @@
-import type { RefObject } from 'react';
-import type { Axis } from '@react-hive/honey-utils';
-import type { Nullable } from '../types';
-import type { UseHoneyDragHandlers } from './use-honey-drag';
-interface ResolveAxisTranslateOptions {
-    /**
-     * Drag delta for the axis (deltaX or deltaY).
-     */
-    delta: number;
-    /**
-     * Current translate value for the axis.
-     */
-    translate: number;
-    /**
-     * Visible container size for the axis (width or height).
-     */
-    containerSize: number;
-    /**
-     * Overflow size for the axis.
-     */
-    overflowSize: number;
-    /**
-     * Overscroll window percentage.
-     */
-    overscrollPct: number;
-}
-export declare const resolveAxisTranslate: ({ delta, translate, containerSize, overflowSize, overscrollPct, }: ResolveAxisTranslateOptions) => Nullable<number>;
-export interface UseHoneySyntheticScrollOptions<Element extends HTMLElement> extends Pick<UseHoneyDragHandlers<Element>, 'onStartDrag' | 'onEndDrag'> {
-    /**
-     * Axis along which synthetic scrolling is enabled.
-     *
-     * - `'x'` — horizontal only
-     * - `'y'` — vertical only
-     * - `'both'` — horizontal and vertical
-     *
-     * @default 'both'
-     */
-    axis?: Axis;
-    /**
-     * Percentage of the container size used as an overscroll buffer
-     * on each enabled axis.
-     *
-     * This allows limited dragging beyond the natural content bounds
-     * before movement is clamped.
-     *
-     * A value of `0` disables overscroll entirely.
-     *
-     * @default 0
-     */
-    overscrollPct?: number;
-    /**
-     * Controls how the hook applies scroll-related interaction styles
-     * (`touch-action` and `overscroll-behavior`) to the container.
-     *
-     * Synthetic scrolling often requires restricting native browser scrolling
-     * behavior to ensure consistent drag and wheel handling.
-     *
-     * However, in some embedded layouts (such as carousels placed inside a
-     * vertically scrollable page), applying these styles can unintentionally
-     * block natural page scrolling.
-     *
-     * ### Modes
-     * - `'default'` — Applies restrictive interaction styles:
-     *   - `overscroll-behavior: contain`
-     *   - Axis-aware `touch-action` (`pan-y`, `pan-x`, or `none`)
-     *
-     *   Recommended for standalone synthetic scroll containers.
-     *
-     * - `'embedded'` — Does not apply any interaction-blocking styles.
-     *
-     *   Recommended when the container is integrated into another scrollable
-     *   context (e.g. horizontal carousel inside a page), where native scroll
-     *   chaining must remain intact.
-     *
-     * @default 'default'
-     */
-    scrollMode?: 'default' | 'embedded';
-    /**
-     * Whether to clear any applied translation transforms when the window resizes.
-     *
-     * Useful to keep the layout state consistent after dimension changes.
-     *
-     * @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;
-    /**
-     * Master toggle for the synthetic scroll behavior.
-     *
-     * When `true`, the hook:
-     * - Enables drag-based translation via {@link useHoneyDrag}.
-     * - Optionally resets transforms on resize via {@link useHoneyResize}.
-     * - Applies overscroll and touch-action styles.
-     * - Intercepts wheel / trackpad scroll input if {@link enablePointerScroll} is enabled.
-     *
-     * When `false`, the hook becomes completely inert:
-     * - No drag or wheel listeners are attached.
-     * - No transforms are applied.
-     * - Native scrolling behavior is preserved.
-     *
-     * Useful for conditionally disabling synthetic scrolling
-     * (e.g. mobile layouts, reduced motion, or feature flags).
-     *
-     * @default true
-     */
-    enabled?: boolean;
-}
-/**
- * Enables synthetic scrolling for a container using pointer-based drag gestures.
- *
- * Instead of relying on native scrollbars, this hook translates the container
- * using CSS transforms in response to drag input.
- *
- * ### Key characteristics
- * - Dragging is only applied when content overflows the container on a given axis.
- * - Movement is clamped within calculated bounds, with optional overscroll allowance.
- * - Scroll position is stored purely in `transform: translate(...)`.
- * - Active transforms can be automatically cleared on window resize.
- *
- * ### Internals
- * - Uses {@link useHoneyDrag} to track mouse / touch movement.
- * - Uses {@link useHoneyResize} to optionally reset scroll state on resize.
- *
- * @template Element - The HTML element type of the scrollable container.
- *
- * @param options - Configuration controlling axes, boundaries, and lifecycle behavior.
- *
- * @returns A ref that must be attached to the scrollable container element.
- */
-export declare const useHoneySyntheticScroll: <Element extends HTMLElement>({ axis, overscrollPct, onStartDrag, onEndDrag, scrollMode, resetOnResize, enablePointerScroll, enabled, }?: UseHoneySyntheticScrollOptions<Element>) => RefObject<Nullable<Element>>;
-export {};

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

@@ -1,107 +0,0 @@
-/**
- * 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 {};