@react-hive/honey-layout 14.2.0 → 16.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-hive/honey-layout",
-  "version": "14.2.0",
+  "version": "16.0.0",
   "description": "",
   "keywords": [
     "react",
@@ -33,14 +33,15 @@
     "!dist/**/jest*"
   ],
   "peerDependencies": {
-    "@react-hive/honey-style": "^3.0.0",
+    "@react-hive/honey-style": "^4.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@floating-ui/dom": "1.7.5",
-    "@floating-ui/react": "0.27.18",
-    "@react-hive/honey-utils": "3.24.0",
+    "@floating-ui/dom": "1.7.6",
+    "@floating-ui/react": "0.27.19",
+    "@react-hive/honey-hooks": "1.0.0",
+    "@react-hive/honey-utils": "3.26.0",
     "csstype": "3.2.3",
     "highlight.js": "11.11.1",
     "lodash.merge": "4.6.2",
@@ -57,12 +58,12 @@
     "@types/lodash.merge": "4.6.9",
     "@types/lodash.throttle": "4.1.9",
     "@types/mdx": "2.0.13",
-    "@types/node": "22.19.11",
+    "@types/node": "22.19.13",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "copy-webpack-plugin": "13.0.1",
     "css-loader": "7.1.4",
-    "eslint": "10.0.0",
+    "eslint": "10.0.3",
     "eslint-plugin-react": "7.37.5",
     "html-webpack-plugin": "5.6.6",
     "husky": "9.1.7",
@@ -75,9 +76,9 @@
     "ts-node": "10.9.2",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.56.0",
-    "webpack": "5.105.2",
-    "webpack-cli": "6.0.1",
+    "typescript-eslint": "8.57.0",
+    "webpack": "5.105.4",
+    "webpack-cli": "7.0.1",
     "webpack-dev-server": "5.2.3"
   },
   "jest": {

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

@@ -1,179 +0,0 @@
-import type { InertiaOptions } from '@react-hive/honey-utils';
-/**
- * Configuration options for {@link useHoneyDecay}.
- */
-export interface UseHoneyDecayOptions extends Pick<InertiaOptions, 'friction' | 'minVelocityPxMs' | 'emaAlpha'> {
-    /**
-     * 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;
-    /**
-     * Optional callback invoked exactly once when inertial motion terminates.
-     *
-     * Triggered when inertia ends due to:
-     * - velocity decaying below `minVelocityPxMs`
-     * - movement being blocked by bounds
-     * - an explicit call to `stop()`
-     *
-     * Not invoked if inertia was never started.
-     */
-    onStop?: () => void;
-}
-/**
- * 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;
-    /**
-     * 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.
-     *
-     * 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 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`)
-     */
-    startFrom: (value: number, velocityPxMs: number) => void;
-    /**
-     * Immediately stops inertial motion.
-     *
-     * If inertia is currently active, this will:
-     * - cancel the RAF loop
-     * - reset internal velocity
-     * - invoke `onStop` exactly once
-     */
-    stop: () => 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, emaAlpha, onStop, }: UseHoneyDecayOptions) => UseHoneyDecayApi;

package/dist/hooks/use-honey-document-key-up.d.ts

@@ -1,40 +0,0 @@
-import type { HoneyKeyboardEventCode } from '../types';
-export type UseHoneyDocumentOnKeyUpHandler = (keyCode: HoneyKeyboardEventCode, e: KeyboardEvent) => void;
-interface UseHoneyDocumentKeyUpOptions {
-    /**
-     * Whether the event listener should be active.
-     *
-     * @default true
-     */
-    enabled?: boolean;
-    /**
-     * Whether to call `preventDefault()` on matching keyup events.
-     *
-     * This is useful for suppressing default browser behavior (e.g., scrolling with Space key).
-     *
-     * @default true
-     */
-    preventDefault?: boolean;
-}
-/**
- * Hook for handling specific key up events on the `document` object.
- *
- * 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 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
- * useHoneyDocumentKeyUp(
- *   (keyCode, event) => {
- *     console.log('Key released:', keyCode);
- *   },
- *   ['Escape'],
- * );
- * ```
- */
-export declare const useHoneyDocumentKeyUp: (onKeyUp: UseHoneyDocumentOnKeyUpHandler, listenKeys: HoneyKeyboardEventCode[], { enabled, preventDefault }?: UseHoneyDocumentKeyUpOptions) => void;
-export {};

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

@@ -1,200 +0,0 @@
-import type { RefObject } from 'react';
-import type { Nullable } from '../types';
-/**
- * Invoked when a drag gesture is about to start.
- *
- * This handler is called on the initial pointer-down interaction
- * (mouse or touch) **before** drag tracking begins.
- *
- * 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.
- *
- * @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 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 UseHoneyDragOnMoveContext {
-    /**
-     * Horizontal delta since the previous move event.
-     *
-     * Positive values indicate movement to the right.
-     */
-    deltaX: number;
-    /**
-     * Vertical delta since the previous move event.
-     *
-     * Positive values indicate movement downward.
-     */
-    deltaY: number;
-    /**
-     * Total horizontal displacement from the drag start position.
-     */
-    distanceX: number;
-    /**
-     * Total vertical displacement from the drag start position.
-     */
-    distanceY: number;
-}
-/**
- * Handler invoked continuously while a drag gesture is active.
- *
- * This handler:
- * - Is created once per drag start
- * - Receives incremental movement data on each pointer move
- * - Can synchronously or asynchronously decide whether dragging continues
- *
- * Returning `false` from the move callback immediately terminates the drag.
- *
- * @template Element - The draggable element type.
- *
- * @param draggableElement - The element being dragged.
- *
- * @returns A function invoked on every pointer move, receiving
- *          {@link UseHoneyDragOnMoveContext}, and resolving to:
- *          - `true` to continue dragging
- *          - `false` to stop dragging immediately
- */
-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 UseHoneyDragOnEndContext {
-    /**
-     * Total horizontal displacement from drag start to release.
-     */
-    deltaX: number;
-    /**
-     * Total vertical displacement from drag start to release.
-     */
-    deltaY: number;
-    /**
-     * 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.
-     */
-    velocityXPxMs: number;
-    /**
-     * 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.
-     */
-    velocityYPxMs: number;
-}
-/**
- * Invoked when a drag gesture ends.
- *
- * This handler is called when:
- * - The pointer is released
- * - The drag is programmatically terminated (unless explicitly skipped)
- *
- * It provides final displacement and **release velocity**, making it
- * ideal for triggering inertia or decay animations.
- *
- * @template Element - The draggable element type.
- *
- * @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 UseHoneyDragOnEndHandler<Element extends HTMLElement> = (context: UseHoneyDragOnEndContext, draggableElement: Element, e: MouseEvent | TouchEvent) => Promise<void>;
-/**
- * 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 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.
-     *
-     * @param element - The element being dragged.
-     *
-     * @returns A boolean or Promise resolving to a boolean indicating if the drag should proceed.
-     */
-    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.
-     *
-     * @param element - The element being dragged.
-     *
-     * @returns A boolean or Promise resolving to a boolean indicating whether the drag should continue.
-     */
-    onMoveDrag: UseHoneyDragOnMoveHandler<Element>;
-    /**
-     * Optional handler triggered when the drag operation ends.
-     * This is commonly used for cleanup or finalizing the drag process.
-     *
-     * @param context - Contains information about the drag operation, such as distance and speed.
-     * @param element - The element being dragged.
-     *
-     * @returns A Promise.
-     */
-    onEndDrag?: UseHoneyDragOnEndHandler<Element>;
-}
-/**
- * Configuration options controlling drag behavior.
- *
- * These options affect lifecycle handling and enable/disable logic,
- * but do not influence movement physics directly.
- */
-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.
-     *
-     * @default false
-     */
-    skipOnEndDragWhenStopped?: boolean;
-    /**
-     * Determines if the drag functionality is enabled or disabled.
-     *
-     * @default true
-     */
-    enabled?: boolean;
-}
-/**
- * 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
- *
- * 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
- *
- * @template Element - The draggable HTML element type.
- *
- * @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, }: UseHoneyDragOptions<Element>) => void;
-export {};

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

@@ -1,18 +0,0 @@
-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-on-change.d.ts

@@ -1,27 +0,0 @@
-import type { EffectCallback } from 'react';
-/**
- * A hook that invokes a callback function whenever the provided `state` value changes.
- *
- * This hook stores the previous value internally and performs a shallow comparison with the current value.
- * If a change is detected, it executes the `onChange` callback. If the callback returns a cleanup function,
- * it will be invoked before the next change or when the component unmounts, similar to standard `useEffect` behavior.
- *
- * @template T - The type of the state being observed.
- *
- * @param state - The value to monitor for changes. Can be of any type.
- * @param onChange - A function called whenever `state` changes. It may return a cleanup function.
- *
- * @returns void
- *
- * @example
- * ```ts
- * useHoneyOnChange(someValue, (newValue) => {
- *   console.log('Value changed to:', newValue);
- *
- *   return () => {
- *     console.log('Cleanup for value:', newValue);
- *   };
- * });
- * ```
- */
-export declare const useHoneyOnChange: <T>(state: T, onChange: (newState: T) => ReturnType<EffectCallback>) => void;

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 {};