@react-hive/honey-layout 10.8.0 → 11.0.0

package/dist/hooks/index.d.ts

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

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

@@ -0,0 +1,142 @@
+/**
+ * Configuration options for {@link useHoneyDecay}.
+ */
+export interface UseHoneyDecayOptions {
+    /**
+     * Initial numeric value from which inertial motion starts.
+     *
+     * This typically represents a translated position  (e.g. scroll offset or `translateX` value),
+     * but may be any bounded numeric domain.
+     */
+    initialValue: number;
+    /**
+     * Lower bound for the value (inclusive).
+     *
+     * Movement beyond this boundary is not permitted.
+     */
+    min: number;
+    /**
+     * Upper bound for the value (inclusive).
+     *
+     * Movement beyond this boundary is not permitted.
+     */
+    max: number;
+    /**
+     * Exponential friction coefficient applied per millisecond.
+     *
+     * Controls how quickly velocity decays over time.
+     *
+     * Smaller values produce longer, floatier inertia;
+     * larger values result in a quicker stop.
+     *
+     * @default 0.002
+     */
+    friction?: number;
+    /**
+     * Minimum absolute velocity below which inertia is considered complete.
+     *
+     * This prevents unnecessary micro-updates and jitter near rest.
+     *
+     * @default 0.01
+     */
+    minVelocityPxMs?: number;
+}
+/**
+ * Public control API returned by {@link useHoneyDecay}.
+ *
+ * Exposes imperative controls for managing velocity-based inertial motion.
+ */
+export interface UseHoneyDecayApi {
+    /**
+     * Current value produced by the decay simulation.
+     *
+     * This value updates over time while inertia is active
+     * and always remains within the configured bounds.
+     */
+    value: number;
+    /**
+     * Indicates whether inertial motion is currently active.
+     */
+    isRunning: boolean;
+    /**
+     * Starts inertial motion from the current value using
+     * the provided initial velocity.
+     *
+     * The sign of the velocity determines a direction:
+     * - Positive → movement toward the upper bound
+     * - Negative → movement toward the lower bound
+     *
+     * @param velocityPxMs - Initial velocity expressed in pixels per millisecond (`px/ms`).
+     */
+    start: (velocityPxMs: number) => void;
+    /**
+     * Immediately stops inertial motion.
+     */
+    stop: () => void;
+    /**
+     * Immediately sets the value and cancels any active inertia.
+     *
+     * @param value - The value to apply immediately.
+     */
+    snapTo: (value: number) => void;
+}
+/**
+ * A bounded, velocity-based inertia (decay) hook built on top of {@link useHoneyRafLoop} and {@link applyInertiaStep}.
+ *
+ * This hook models **momentum-driven motion** where:
+ * - Motion starts with an initial velocity
+ * - Velocity decays exponentially over time
+ * - Movement is constrained by hard numeric bounds
+ * - Inertia stops naturally when velocity becomes negligible
+ *
+ * Unlike spring-based motion, this hook has **no target value**.
+ * Motion continues purely based on momentum until it decays
+ * or is blocked by a boundary.
+ *
+ * ---
+ *
+ * ### Key characteristics
+ * - Frame-rate independent (delta-time based)
+ * - Deterministic and interruptible
+ * - Direction-aware and bound-safe (no overshoot or jitter)
+ * - Closely matches native scroll and drag inertia behavior
+ *
+ * ---
+ *
+ * ### Visibility behavior
+ * This hook is a **simulation-based system**:
+ * - Inertia automatically pauses when the document becomes hidden
+ * - No time elapses while hidden
+ * - Motion resumes only when explicitly restarted
+ *
+ * This behavior is inherited from {@link useHoneyRafLoop} and is intentional.
+ *
+ * ---
+ *
+ * ### Common use cases
+ * - Scroll containers with momentum
+ * - Drag-to-scroll interactions
+ * - Carousels and sliders
+ * - Timelines and scrubbers
+ * - Kinetic panning and flinging
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * const decay = useHoneyDecay({
+ *   initialValue: 0,
+ *   min: -maxOverflow,
+ *   max: 0,
+ * });
+ *
+ * const onRelease = (velocityPxMs: number) => {
+ *   decay.start(velocityPxMs);
+ * };
+ *
+ * return (
+ *   <div style={{ transform: `translateX(${decay.value}px)` }} />
+ * );
+ * ```
+ */
+export declare const useHoneyDecay: ({ initialValue, min, max, friction, minVelocityPxMs, }: UseHoneyDecayOptions) => UseHoneyDecayApi;

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

@@ -1,97 +1,130 @@
 import type { RefObject } from 'react';
 import type { Nullable } from '../types';
 /**
- * Handler triggered when a drag operation starts.
+ * Invoked when a drag gesture is about to start.
  *
- * @template Element - The type of the draggable element (must extend HTMLElement).
+ * This handler is called on the initial pointer-down interaction
+ * (mouse or touch) **before** drag tracking begins.
  *
- * @param draggableElement - The element being dragged.
- * @param e - The event that initiated the drag. Can be either a `MouseEvent` or a `TouchEvent`.
+ * It can be used to:
+ * - Conditionally allow or block dragging
+ * - Capture initial external state
+ * - Cancel dragging based on application logic
+ *
+ * @template Element - The draggable element type.
  *
- * @returns A Promise that resolves to a boolean:
- *          - `false` to cancel the drag.
- *          - `true` to proceed with the drag.
+ * @param draggableElement - The element that will be dragged.
+ * @param e - The initiating pointer event.
+ *
+ * @returns A promise resolving to:
+ * - `true` to allow the drag to begin
+ * - `false` to cancel the drag
  */
 export type HoneyDragOnStartHandler<Element extends HTMLElement> = (draggableElement: Element, e: MouseEvent | TouchEvent) => Promise<boolean>;
 /**
- * Context provided to the move handler, containing information about the drag's movement.
+ * Context describing pointer movement during an active drag gesture.
+ *
+ * All values are expressed in **pixels** and are relative
+ * to the drag start or previous frame as noted.
  */
 export interface HoneyDragMoveContext {
     /**
-     * The horizontal distance has moved since the last frame.
+     * Horizontal delta since the previous move event.
+     *
+     * Positive values indicate movement to the right.
      */
     deltaX: number;
     /**
-     * The vertical distance has moved since the last frame.
+     * Vertical delta since the previous move event.
+     *
+     * Positive values indicate movement downward.
      */
     deltaY: number;
     /**
-     * The total horizontal distance from the starting position to the current position.
+     * Total horizontal displacement from the drag start position.
      */
     distanceX: number;
     /**
-     * The total vertical distance from the starting position to the current position.
+     * Total vertical displacement from the drag start position.
      */
     distanceY: number;
-    /**
-     * The straight-line distance from the starting position to the current position.
-     */
-    euclideanDistance: number;
 }
 /**
- * Handler triggered during a drag operation.
+ * Handler invoked continuously while a drag gesture is active.
  *
- * @template Element - The type of the draggable element (must extend HTMLElement).
+ * This handler:
+ * - Is created once per drag start
+ * - Receives incremental movement data on each pointer move
+ * - Can synchronously or asynchronously decide whether dragging continues
  *
- * Behavior:
- * - The handler receives the draggable element and returns a function that is called on every move event.
- * - If the returned function resolves to `false`, the drag operation stops immediately.
+ * Returning `false` from the move callback immediately terminates the drag.
  *
- * This allows for real-time handling of drag events and asynchronous conditions during dragging.
+ * @template Element - The draggable element type.
  *
  * @param draggableElement - The element being dragged.
  *
- * @returns A function that handles move events and returns a Promise that resolves to `true`
- *          to continue dragging, or `false` to stop it.
+ * @returns A function invoked on every pointer move, receiving
+ *          {@link HoneyDragMoveContext}, and resolving to:
+ *          - `true` to continue dragging
+ *          - `false` to stop dragging immediately
  */
 export type HoneyDragOnMoveHandler<Element extends HTMLElement> = (draggableElement: Element) => (context: HoneyDragMoveContext) => Promise<boolean>;
 /**
- * Context provided to the end handler, containing information about the drag's end state.
+ * Context describing the final state of a completed drag gesture.
+ *
+ * This context exposes **release velocity**, which is suitable for
+ * inertia, momentum, or decay-based motion systems.
  */
 interface HoneyDragEndContext {
     /**
-     * The total horizontal movement from the starting position to the ending position.
+     * Total horizontal displacement from drag start to release.
      */
     deltaX: number;
     /**
-     * The total vertical movement from the starting position to the ending position.
+     * Total vertical displacement from drag start to release.
      */
     deltaY: number;
     /**
-     * The speed of movement in the horizontal direction (X axis).
+     * Horizontal release velocity in pixels per millisecond (`px/ms`).
+     *
+     * This value represents the **instantaneous velocity at release**
+     * and is suitable for inertia or momentum-based motion.
      */
-    movingSpeedX: number;
+    velocityXPxMs: number;
     /**
-     * The speed of movement in the vertical direction (Y axis).
+     * Vertical release velocity in pixels per millisecond (`px/ms`).
+     *
+     * This value represents the **instantaneous velocity at release**
+     * and is suitable for inertia or momentum-based motion.
      */
-    movingSpeedY: number;
+    velocityYPxMs: number;
 }
 /**
- * Handler triggered when a drag operation ends.
+ * Invoked when a drag gesture ends.
+ *
+ * This handler is called when:
+ * - The pointer is released
+ * - The drag is programmatically terminated (unless explicitly skipped)
  *
- * @template Element - The type of the draggable element (must extend HTMLElement).
+ * It provides final displacement and **release velocity**, making it
+ * ideal for triggering inertia or decay animations.
  *
- * @param context - The context containing details about the drag operation at its end.
- *                  Provides information such as the final position and drag result.
- * @param draggableElement - The element that was being dragged.
- * @param e - The event that ended the drag. Can be either a `MouseEvent` or a `TouchEvent`.
+ * @template Element - The draggable element type.
  *
- * @returns A Promise that resolves when the end handler completes its operations.
+ * @param context - Final drag metrics, including release velocity.
+ * @param draggableElement - The element that was dragged.
+ * @param e - The pointer event that finished the drag.
+ *
+ * @returns A promise that resolves when cleanup or follow-up logic completes.
  */
 export type HoneyDragOnEndHandler<Element extends HTMLElement> = (context: HoneyDragEndContext, draggableElement: Element, e: MouseEvent | TouchEvent) => Promise<void>;
 /**
- * A set of handlers that define the behavior of the drag operation at different stages.
- * These handlers are customizable for managing drag initialization, movement, and completion.
+ * Collection of handlers controlling the lifecycle of a drag gesture.
+ *
+ * Together, these handlers define:
+ * - Whether dragging is allowed
+ * - How movement is handled
+ * - What happens when dragging ends
  */
 export interface HoneyDragHandlers<Element extends HTMLElement> {
     /**
@@ -124,8 +157,10 @@ export interface HoneyDragHandlers<Element extends HTMLElement> {
     onEndDrag?: HoneyDragOnEndHandler<Element>;
 }
 /**
- * Configuration options for the drag functionality.
- * These options control the behavior of the drag hook and modify how the drag events are handled.
+ * Configuration options controlling drag behavior.
+ *
+ * These options affect lifecycle handling and enable/disable logic,
+ * but do not influence movement physics directly.
  */
 export interface HoneyDragOptions<Element extends HTMLElement> extends HoneyDragHandlers<Element> {
     /**
@@ -143,17 +178,23 @@ export interface HoneyDragOptions<Element extends HTMLElement> extends HoneyDrag
     enabled?: boolean;
 }
 /**
- * A hook that provides touch and mouse-based dragging functionality for an element.
- * It enables the ability to drag an element on both mouse and touch interfaces,
- * with customizable handlers for different stages of the drag.
+ * Enables high-precision mouse and touch dragging for an element.
+ *
+ * This hook:
+ * - Tracks pointer movement using `performance.now()`
+ * - Computes **instantaneous release velocity** (px/ms)
+ * - Emits deterministic drag lifecycle events
+ * - Supports both mouse and touch input
  *
- * @template Element - The type of the HTML element that is being dragged.
+ * Architectural notes:
+ * - Velocity is computed **during movement**, not at drag end
+ * - Release velocity is suitable for inertia / decay systems
+ * - No layout reads or writes are performed internally
  *
- * @param draggableElementRef - A reference to the element that can be dragged.
- * @param options - Handlers for different stages of the drag operation and configuration options
- *                  for controlling drag behavior.
+ * @template Element - The draggable HTML element type.
  *
- * @returns A cleanup function to remove event listeners when the component is unmounted.
+ * @param draggableElementRef - Ref pointing to the draggable element.
+ * @param options - Drag lifecycle handlers and configuration flags.
  */
 export declare const useHoneyDrag: <Element extends HTMLElement>(draggableElementRef: RefObject<Nullable<Element>>, { skipOnEndDragWhenStopped, enabled, onMoveDrag, onStartDrag, onEndDrag, }: HoneyDragOptions<Element>) => void;
 export {};