@react-hive/honey-layout 11.0.0 → 11.2.0

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

@@ -1,7 +1,8 @@
+import type { InertiaOptions } from '@react-hive/honey-utils';
 /**
  * Configuration options for {@link useHoneyDecay}.
  */
-export interface UseHoneyDecayOptions {
+export interface UseHoneyDecayOptions extends Pick<InertiaOptions, 'friction' | 'minVelocityPxMs' | 'emaAlpha'> {
     /**
      * Initial numeric value from which inertial motion starts.
      *
@@ -22,24 +23,16 @@ export interface UseHoneyDecayOptions {
      */
     max: number;
     /**
-     * Exponential friction coefficient applied per millisecond.
+     * Optional callback invoked exactly once when inertial motion terminates.
      *
-     * Controls how quickly velocity decays over time.
+     * Triggered when inertia ends due to:
+     * - velocity decaying below `minVelocityPxMs`
+     * - movement being blocked by bounds
+     * - an explicit call to `stop()`
      *
-     * 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
+     * Not invoked if inertia was never started.
      */
-    minVelocityPxMs?: number;
+    onStop?: () => void;
 }
 /**
  * Public control API returned by {@link useHoneyDecay}.
@@ -58,6 +51,38 @@ export interface UseHoneyDecayApi {
      * Indicates whether inertial motion is currently active.
      */
     isRunning: boolean;
+    /**
+     * Updates the hard bounds used by the decay simulation.
+     *
+     * This method is safe to call **at any time**, including while inertia is actively running.
+     *
+     * ### Behavior
+     * - If the current value lies **within** the new bounds:
+     *   - bounds are updated
+     *   - inertia (if running) continues uninterrupted
+     *
+     * - If the current value lies **outside** the new bounds:
+     *   - the value is immediately clamped to the nearest boundary
+     *   - internal velocity is reset to `0`
+     *   - any active inertia is **terminated immediately**
+     *   - `onStop` is invoked exactly once (if inertia was active)
+     *
+     * This deterministic behavior mirrors native scroll engines and ensures:
+     * - no overshoot
+     * - no extra inertia frames
+     * - consistent `onStop` semantics
+     *
+     * ### Intended usage
+     * - Responding to layout or content changes
+     * - Handling resize / orientation changes
+     * - Updating overscroll or overflow limits dynamically
+     *
+     * ⚠️ This method should **not** be called from inside the RAF frame handler.
+     *
+     * @param min - New lower bound (inclusive)
+     * @param max - New upper bound (inclusive)
+     */
+    setBounds: (min: number, max: number) => void;
     /**
      * Starts inertial motion from the current value using
      * the provided initial velocity.
@@ -70,18 +95,30 @@ export interface UseHoneyDecayApi {
      */
     start: (velocityPxMs: number) => void;
     /**
-     * Immediately stops inertial motion.
+     * Immediately sets the value and starts inertial motion from that value in a single atomic operation.
+     *
+     * This is the preferred way to hand off from a gesture (e.g. drag end) to inertia, as it:
+     * - avoids transient intermediate states
+     * - guarantees correct value/velocity ordering
+     * - ensures `onStop` semantics remain consistent
+     *
+     * @param value - Starting value for the inertia simulation
+     * @param velocityPxMs - Initial velocity in pixels per millisecond (`px/ms`)
      */
-    stop: () => void;
+    startFrom: (value: number, velocityPxMs: number) => void;
     /**
-     * Immediately sets the value and cancels any active inertia.
+     * Immediately stops inertial motion.
      *
-     * @param value - The value to apply immediately.
+     * If inertia is currently active, this will:
+     * - cancel the RAF loop
+     * - reset internal velocity
+     * - invoke `onStop` exactly once
      */
-    snapTo: (value: number) => void;
+    stop: () => void;
 }
 /**
- * A bounded, velocity-based inertia (decay) hook built on top of {@link useHoneyRafLoop} and {@link applyInertiaStep}.
+ * 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
@@ -139,4 +176,4 @@ export interface UseHoneyDecayApi {
  * );
  * ```
  */
-export declare const useHoneyDecay: ({ initialValue, min, max, friction, minVelocityPxMs, }: UseHoneyDecayOptions) => UseHoneyDecayApi;
+export declare const useHoneyDecay: ({ initialValue, min, max, friction, minVelocityPxMs, emaAlpha, onStop, }: UseHoneyDecayOptions) => UseHoneyDecayApi;

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

@@ -0,0 +1,18 @@
+import type { RefObject } from 'react';
+type UseHoneyLatest = {
+    <T>(value: T): RefObject<T>;
+    <T>(value: T | undefined): RefObject<T | undefined>;
+};
+/**
+ * Stores the latest value in a stable ref.
+ *
+ * Guarantees that:
+ * - `ref.current` always points to the latest value
+ * - the ref object identity never changes
+ *
+ * Overload behavior:
+ * - If a non-optional value is provided, `.current` is non-optional
+ * - If an optional value is provided, `.current` is optional
+ */
+export declare const useHoneyLatest: UseHoneyLatest;
+export {};

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

@@ -1,4 +1,4 @@
-interface HoneyRafOnFrameContext {
+interface HoneyRafFrameContext {
     /**
      * Immediately terminates the active `requestAnimationFrame` loop.
      *
@@ -29,9 +29,9 @@ interface HoneyRafOnFrameContext {
  *                      time steps caused by tab backgrounding, visibility changes,
  *                      or browser throttling.
  *
- * @param context - RAF lifecycle control context. See {@link HoneyRafOnFrameContext}.
+ * @param context - RAF lifecycle control context. See {@link HoneyRafFrameContext}.
  */
-export type HoneyRafOnFrameHandler = (deltaTimeMs: number, context: HoneyRafOnFrameContext) => void;
+export type HoneyRafFrameHandler = (deltaTimeMs: number, context: HoneyRafFrameContext) => void;
 /**
  * Configuration options for {@link useHoneyRafLoop}.
  */
@@ -160,5 +160,5 @@ export interface HoneyRafLoopApi {
  * useHoneyRafLoop(onFrame);
  * ```
  */
-export declare const useHoneyRafLoop: (onFrame: HoneyRafOnFrameHandler, { autoStart, resumeOnVisibility, maxDeltaMs, onError, }?: UseHoneyRafLoopOptions) => HoneyRafLoopApi;
+export declare const useHoneyRafLoop: (onFrame: HoneyRafFrameHandler, { autoStart, resumeOnVisibility, maxDeltaMs, onError, }?: UseHoneyRafLoopOptions) => HoneyRafLoopApi;
 export {};

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

@@ -5,7 +5,7 @@
  * - `countup` — increases time until it reaches `targetTimeMs` (if provided)
  */
 type UseHoneyTimerMode = 'countdown' | 'countup';
-type UseHoneyTimerOnEndHandler = () => void;
+type UseHoneyTimerEndHandler = () => void;
 export interface UseHoneyTimerOptions {
     /**
      * Initial timer value in milliseconds.
@@ -40,7 +40,7 @@ export interface UseHoneyTimerOptions {
     /**
      * Optional callback invoked exactly once when the timer reaches the target time.
      */
-    onEnd?: UseHoneyTimerOnEndHandler;
+    onEnd?: UseHoneyTimerEndHandler;
 }
 /**
  * Public control API returned by {@link useHoneyTimer}.