@react-hive/honey-layout 11.1.0 → 12.0.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}.
@@ -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-document-key-up-handler.d.ts → use-honey-document-key-up.d.ts}

@@ -1,6 +1,6 @@
-import type { HoneyKeyboardEventCode } from '../types';
-export type HoneyDocumentKeyUpHandler = (keyCode: HoneyKeyboardEventCode, e: KeyboardEvent) => void;
-interface UseHoneyDocumentKeyUpHandlerOptions {
+import type { HoneyKeyboardEventCode } from '~/types';
+export type UseHoneyDocumentOnKeyUpHandler = (keyCode: HoneyKeyboardEventCode, e: KeyboardEvent) => void;
+interface UseHoneyDocumentKeyUpOptions {
     /**
      * Whether the event listener should be active.
      *
@@ -22,13 +22,13 @@ interface UseHoneyDocumentKeyUpHandlerOptions {
  * This hook adds a `keyup` event listener at the document level and triggers the provided `keyUpHandler`
  * when one of the specified `listenKeys` is released.
  *
- * @param keyUpHandler - The callback function invoked when a matching key is released.
+ * @param onKeyUp - The callback function invoked when a matching key is released.
  * @param listenKeys - An array of key codes (`KeyboardEvent.code`) to listen for.
  * @param options - Optional configuration to control event behavior and listener activation.
  *
  * @example
  * ```tsx
- * useHoneyDocumentKeyUpHandler(
+ * useHoneyDocumentKeyUp(
  *   (keyCode, event) => {
  *     console.log('Key released:', keyCode);
  *   },
@@ -36,5 +36,5 @@ interface UseHoneyDocumentKeyUpHandlerOptions {
  * );
  * ```
  */
-export declare const useHoneyDocumentKeyUpHandler: (keyUpHandler: HoneyDocumentKeyUpHandler, listenKeys: HoneyKeyboardEventCode[], { enabled, preventDefault }?: UseHoneyDocumentKeyUpHandlerOptions) => void;
+export declare const useHoneyDocumentKeyUp: (onKeyUp: UseHoneyDocumentOnKeyUpHandler, listenKeys: HoneyKeyboardEventCode[], { enabled, preventDefault }?: UseHoneyDocumentKeyUpOptions) => void;
 export {};

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

@@ -1,5 +1,5 @@
 import type { RefObject } from 'react';
-import type { Nullable } from '../types';
+import type { Nullable } from '~/types';
 /**
  * Invoked when a drag gesture is about to start.
  *
@@ -20,14 +20,14 @@ import type { Nullable } from '../types';
  * - `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>;
+export type UseHoneyDragOnStartHandler<Element extends HTMLElement> = (draggableElement: Element, e: MouseEvent | TouchEvent) => Promise<boolean>;
 /**
  * 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 {
+export interface UseHoneyDragOnMoveContext {
     /**
      * Horizontal delta since the previous move event.
      *
@@ -64,18 +64,18 @@ export interface HoneyDragMoveContext {
  * @param draggableElement - The element being dragged.
  *
  * @returns A function invoked on every pointer move, receiving
- *          {@link HoneyDragMoveContext}, and resolving to:
+ *          {@link UseHoneyDragOnMoveContext}, and resolving to:
  *          - `true` to continue dragging
  *          - `false` to stop dragging immediately
  */
-export type HoneyDragOnMoveHandler<Element extends HTMLElement> = (draggableElement: Element) => (context: HoneyDragMoveContext) => Promise<boolean>;
+export type UseHoneyDragOnMoveHandler<Element extends HTMLElement> = (draggableElement: Element) => (context: UseHoneyDragOnMoveContext) => Promise<boolean>;
 /**
  * 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 {
+interface UseHoneyDragOnEndContext {
     /**
      * Total horizontal displacement from drag start to release.
      */
@@ -117,7 +117,7 @@ interface HoneyDragEndContext {
  *
  * @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>;
+export type UseHoneyDragOnEndHandler<Element extends HTMLElement> = (context: UseHoneyDragOnEndContext, draggableElement: Element, e: MouseEvent | TouchEvent) => Promise<void>;
 /**
  * Collection of handlers controlling the lifecycle of a drag gesture.
  *
@@ -126,7 +126,7 @@ export type HoneyDragOnEndHandler<Element extends HTMLElement> = (context: Honey
  * - How movement is handled
  * - What happens when dragging ends
  */
-export interface HoneyDragHandlers<Element extends HTMLElement> {
+export interface UseHoneyDragHandlers<Element extends HTMLElement> {
     /**
      * Optional handler triggered when the drag operation starts.
      * This is useful for capturing the initial state or performing any setup actions before the drag starts.
@@ -135,7 +135,7 @@ export interface HoneyDragHandlers<Element extends HTMLElement> {
      *
      * @returns A boolean or Promise resolving to a boolean indicating if the drag should proceed.
      */
-    onStartDrag?: HoneyDragOnStartHandler<Element>;
+    onStartDrag?: UseHoneyDragOnStartHandler<Element>;
     /**
      * Required handler triggered continuously during the drag operation.
      * This handler is responsible for updating the drag state and typically tracks the element's movement.
@@ -144,7 +144,7 @@ export interface HoneyDragHandlers<Element extends HTMLElement> {
      *
      * @returns A boolean or Promise resolving to a boolean indicating whether the drag should continue.
      */
-    onMoveDrag: HoneyDragOnMoveHandler<Element>;
+    onMoveDrag: UseHoneyDragOnMoveHandler<Element>;
     /**
      * Optional handler triggered when the drag operation ends.
      * This is commonly used for cleanup or finalizing the drag process.
@@ -154,7 +154,7 @@ export interface HoneyDragHandlers<Element extends HTMLElement> {
      *
      * @returns A Promise.
      */
-    onEndDrag?: HoneyDragOnEndHandler<Element>;
+    onEndDrag?: UseHoneyDragOnEndHandler<Element>;
 }
 /**
  * Configuration options controlling drag behavior.
@@ -162,7 +162,7 @@ export interface HoneyDragHandlers<Element extends HTMLElement> {
  * 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> {
+export interface UseHoneyDragOptions<Element extends HTMLElement> extends UseHoneyDragHandlers<Element> {
     /**
      * Controls whether the `onEndDrag` handler is skipped when the drag operation is forcibly stopped.
      * This can be useful when dragging is interrupted or terminated early due to movement restrictions.
@@ -196,5 +196,5 @@ export interface HoneyDragOptions<Element extends HTMLElement> extends HoneyDrag
  * @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 declare const useHoneyDrag: <Element extends HTMLElement>(draggableElementRef: RefObject<Nullable<Element>>, { skipOnEndDragWhenStopped, enabled, onMoveDrag, onStartDrag, onEndDrag, }: UseHoneyDragOptions<Element>) => void;
 export {};

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-layout.d.ts

@@ -5,4 +5,4 @@
  *
  * @returns The context value providing theming utilities and screen state.
  */
-export declare const useHoneyLayout: () => import("../contexts").HoneyLayoutContextValue;
+export declare const useHoneyLayout: () => import("~/contexts").HoneyLayoutContextValue;

package/dist/hooks/use-honey-media-query.d.ts

@@ -1,5 +1,5 @@
 import type { HoneyTheme } from '@react-hive/honey-style';
-import type { HoneyScreenState } from '../types';
+import type { HoneyScreenState } from '~/types';
 export interface UseHoneyMediaQueryOptions {
     /**
      * Throttle interval (in milliseconds) for the resize event handler.

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

@@ -1,4 +1,4 @@
-import type { HoneyOverlayId, HoneyOverlayEventListenerHandler } from '../types';
+import type { HoneyOverlayId, HoneyOverlayEventListenerHandler } from '~/types';
 interface UseHoneyOverlayOptions {
     onKeyUp?: HoneyOverlayEventListenerHandler;
 }
@@ -26,5 +26,5 @@ interface UseHoneyOverlayOptions {
  * });
  * ```
  */
-export declare const useHoneyOverlay: (targetOverlayId: HoneyOverlayId, { onKeyUp }?: UseHoneyOverlayOptions) => import("../types").HoneyActiveOverlay | undefined;
+export declare const useHoneyOverlay: (targetOverlayId: HoneyOverlayId, { onKeyUp }?: UseHoneyOverlayOptions) => import("~/types").HoneyActiveOverlay | undefined;
 export {};

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

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

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

@@ -1,7 +1,7 @@
 import type { RefObject } from 'react';
 import { Axis } from '@react-hive/honey-utils';
 import type { Nullable } from '~/types';
-import type { HoneyDragHandlers } from './use-honey-drag';
+import type { UseHoneyDragHandlers } from './use-honey-drag';
 interface ResolveAxisTranslateOptions {
     /**
      * Drag delta for the axis (deltaX or deltaY).
@@ -25,7 +25,7 @@ interface ResolveAxisTranslateOptions {
     overscrollPct: 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'> {
+export interface UseHoneySyntheticScrollOptions<Element extends HTMLElement> extends Pick<UseHoneyDragHandlers<Element>, 'onStartDrag' | 'onEndDrag'> {
     /**
      * Axis along which synthetic scrolling is enabled.
      *

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 UseHoneyTimerEndHandler = () => void;
+type UseHoneyTimerOnEndHandler = () => 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?: UseHoneyTimerEndHandler;
+    onEnd?: UseHoneyTimerOnEndHandler;
 }
 /**
  * Public control API returned by {@link useHoneyTimer}.

package/dist/hooks/use-register-honey-overlay.d.ts

@@ -1,4 +1,4 @@
-import type { HoneyActiveOverlay, HoneyOverlayConfig, Nullable } from '../types';
+import type { HoneyActiveOverlay, HoneyOverlayConfig, Nullable } from '~/types';
 /**
  * A hook for registering and managing an overlay in the layout system.
  *