@react-hive/honey-layout 11.1.0 → 11.2.0

package/dist/hooks/index.d.ts

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

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}.
@@ -61,9 +54,30 @@ export interface UseHoneyDecayApi {
     /**
      * Updates the hard bounds used by the decay simulation.
      *
-     * The current value is clamped implicitly on the next frame if it lies outside the new bounds.
+     * 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
      *
-     * This is intended for dynamic layouts where overflow can change (e.g. resize, content updates).
+     * ### 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)
@@ -81,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
@@ -150,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 {};