@react-hive/honey-layout 5.2.0-beta → 5.6.0-beta

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

@@ -15,7 +15,7 @@ export type HoneyDragOnStartHandler<Element extends HTMLElement> = (draggableEle
 /**
  * Context provided to the move handler, containing information about the drag's movement.
  */
-interface HoneyDragMoveContext {
+export interface HoneyDragMoveContext {
     /**
      * The horizontal distance has moved since the last frame.
      */
@@ -88,52 +88,70 @@ interface HoneyDragEndContext {
  */
 export type HoneyDragOnEndHandler<Element extends HTMLElement> = (context: HoneyDragEndContext, draggableElement: Element) => Promise<void>;
 /**
- * Object containing the handlers for various stages of the drag operation.
- * These handlers can be customized to manage the behavior of the drag process.
+ * 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.
  */
 export interface HoneyDragHandlers<Element extends HTMLElement> {
     /**
      * Optional handler triggered when the drag operation starts.
-     * This can be used to capture the initial state or perform setup actions.
+     * 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?: HoneyDragOnStartHandler<Element>;
     /**
      * Required handler triggered continuously during the drag operation.
-     * This handles updating the drag state and typically tracks the element's movement.
+     * 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: HoneyDragOnMoveHandler<Element>;
     /**
      * Optional handler triggered when the drag operation ends.
-     * This can be used for cleanup or finalizing the state after the drag 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?: HoneyDragOnEndHandler<Element>;
 }
-export interface HoneyDragOptions {
+/**
+ * Configuration options for the drag functionality.
+ * These options control the behavior of the drag hook and modify how the drag events are handled.
+ */
+export interface HoneyDragOptions<Element extends HTMLElement> extends HoneyDragHandlers<Element> {
     /**
-     * Controls whether the `onEndDrag` handler should be skipped when the drag operation is forcibly stopped.
-     *
-     * When `true`, `onEndDrag` will not be called if dragging is interrupted due to movement restrictions
-     * or an early termination.
+     * 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
      */
-    isSkipOnEndDragWhenStopped?: boolean;
+    skipOnEndDragWhenStopped?: boolean;
     /**
-     * Determines whether the drag functionality is enabled or not.
+     * Determines if the drag functionality is enabled or disabled.
      *
      * @default true
      */
-    isEnabled?: boolean;
+    enabled?: boolean;
 }
 /**
  * A hook that provides touch and mouse-based dragging functionality for an element.
- * It tracks the movement of the element during the drag process and exposes handlers for each stage of the drag operation.
+ * It enables the ability to drag an element on both mouse and touch interfaces,
+ * with customizable handlers for different stages of the drag.
  *
  * @template Element - The type of the HTML element that is being dragged.
  *
  * @param draggableElementRef - A reference to the element that can be dragged.
- * @param handlers - The drag event handlers for different stages of the drag operation (start, move, end).
- * @param options - Configuration options.
+ * @param options - Handlers for different stages of the drag operation and configuration options
+ *                  for controlling drag behavior.
+ *
+ * @returns A cleanup function to remove event listeners when the component is unmounted.
  */
-export declare const useHoneyDrag: <Element extends HTMLElement>(draggableElementRef: RefObject<Nullable<Element>>, { onMoveDrag, onStartDrag, onEndDrag }: HoneyDragHandlers<Element>, { isSkipOnEndDragWhenStopped, isEnabled }?: HoneyDragOptions) => void;
+export declare const useHoneyDrag: <Element extends HTMLElement>(draggableElementRef: RefObject<Nullable<Element>>, { skipOnEndDragWhenStopped, enabled, onMoveDrag, onStartDrag, onEndDrag, }: HoneyDragOptions<Element>) => void;
 export {};

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

@@ -1,9 +1,8 @@
-import { HoneyLayoutContextValue } from '../contexts';
 /**
  * Custom hook to access the Honey layout context.
  *
  * @throws Will throw an error if the hook is used outside of a `HoneyLayoutProvider` component.
  *
- * @returns {HoneyLayoutContextValue} - The context value providing theming utilities and screen state.
+ * @returns The context value providing theming utilities and screen state.
  */
-export declare const useHoneyLayout: () => HoneyLayoutContextValue;
+export declare const useHoneyLayout: () => import('../contexts').HoneyLayoutContextValue;

package/dist/hooks/use-honey-on-change.d.ts

@@ -0,0 +1,27 @@
+import { 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
+ * ```tsx
+ * 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-overlay.d.ts

@@ -3,19 +3,24 @@ interface UseHoneyOverlayOptions {
     onKeyUp?: HoneyOverlayEventListenerHandler;
 }
 /**
- * Hook to interact with a specific overlay managed by the `HoneyLayoutProvider`.
+ * Hook for interacting with an active overlay managed by `HoneyLayoutProvider`.
  *
- * @param targetOverlayId - The unique identifier of the overlay to interact with.
- * @param options - Configuration options for the overlay, such as keyboard event handling.
+ * @param targetOverlayId - The unique ID of the overlay you want to interact with.
+ * @param options - Optional configuration such as event handlers (e.g., `onKeyUp`).
  *
- * @returns The overlay object associated with the provided `targetOverlayId`, or `undefined` if not found.
+ * @returns The overlay instance matching the provided ID, or `undefined` if not found.
+ *
+ * @remarks
+ * - This hook only works with overlays that are currently active.
+ * - If the overlay is not active or not registered, `undefined` will be returned.
+ * - Event handlers like `onKeyUp` are automatically registered and cleaned up for the overlay.
  *
  * @example
  * ```tsx
  * const overlay = useHoneyOverlay('my-overlay-id', {
  *   onKeyUp: (keyCode, e) => {
  *     if (keyCode === 'Escape') {
- *       console.log('Escape key pressed');
+ *       console.log('Escape key pressed!');
  *     }
  *   },
  * });