@react-hive/honey-layout 11.2.0 → 12.1.0

package/dist/components/HoneyLayerRegistry/HoneyLayerRegistry.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import type { PropsWithChildren } from 'react';
+/**
+ * Provides a stack-based registry for managing layered UI elements.
+ *
+ * This component is intentionally generic and UI-agnostic.
+ * It can be used to manage:
+ *  - curtains
+ *  - modals
+ *  - drawers
+ *  - tooltips
+ *  - popovers
+ *  - any ordered overlay system
+ *
+ * If a parent {@link HoneyLayerRegistry} already exists in the tree,
+ * this component becomes a no-op and does not create a nested registry.
+ */
+export declare const HoneyLayerRegistry: ({ children }: PropsWithChildren) => string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;

package/dist/components/HoneyLayerRegistry/HoneyLayerRegistry.types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Unique identifier for a registered layer.
+ *
+ * The ID is ephemeral and only guaranteed to be unique within the lifetime of the registry.
+ */
+export type HoneyLayerId = string;
+/**
+ * A single layer entry stored in the registry.
+ *
+ * @template TPayload - Optional payload associated with the layer.
+ */
+export interface HoneyLayerEntry<TPayload = undefined> {
+    /**
+     * Unique identifier of the layer.
+     */
+    id: HoneyLayerId;
+    /**
+     * Arbitrary payload associated with the layer.
+     *
+     * Can be used to store metadata such as:
+     *  - layer type
+     *  - priority
+     *  - owner component
+     *  - configuration data
+     */
+    payload: TPayload;
+}

package/dist/components/HoneyLayerRegistry/HoneyLayerRegistryContext.d.ts

@@ -0,0 +1,43 @@
+import type { HoneyLayerId, HoneyLayerEntry } from '~/components';
+/**
+ * Context value exposed by {@link HoneyLayerRegistry}.
+ *
+ * @template TPayload - Payload type associated with registered layers.
+ */
+export interface HoneyLayerRegistryContextValue<TPayload = undefined> {
+    /**
+     * Ordered list of currently registered layers.
+     *
+     * The order reflects the registration sequence:
+     * - earlier items are "below"
+     * - later items are "above"
+     */
+    layers: HoneyLayerEntry<TPayload>[];
+    /**
+     * Registers a new layer in the registry.
+     *
+     * @param payload - Optional payload associated with the layer.
+     *
+     * @returns The generated {@link HoneyLayerId}.
+     */
+    registerLayer: (payload?: TPayload) => HoneyLayerId;
+    /**
+     * Unregisters an existing layer.
+     *
+     * If the layer ID does not exist, this operation is a no-op.
+     *
+     * @param layerId - ID of the layer to remove.
+     */
+    unregisterLayer: (layerId: HoneyLayerId) => void;
+    /**
+     * Returns the zero-based index of a layer in the stack.
+     *
+     * @param layerId - ID of the layer.
+     *
+     * @returns
+     * - `0` or greater if the layer is registered
+     * - `-1` if the layer is not found
+     */
+    getLayerIndex: (layerId: HoneyLayerId) => number;
+}
+export declare const HoneyLayerRegistryContext: import("react").Context<HoneyLayerRegistryContextValue<undefined> | undefined>;

package/dist/components/HoneyLayerRegistry/hooks/index.d.ts

@@ -0,0 +1 @@
+export * from './use-honey-layer-registry-context';

package/dist/components/HoneyLayerRegistry/hooks/use-honey-layer-registry-context.d.ts

@@ -0,0 +1,9 @@
+import type { HoneyLayerRegistryContextValue } from '../HoneyLayerRegistryContext';
+/**
+ * Hook for accessing the nearest {@link HoneyLayerRegistry}.
+ *
+ * @template TPayload - Expected payload type of the registry.
+ *
+ * @throws If used outside of a {@link HoneyLayerRegistry} provider.
+ */
+export declare const useHoneyLayerRegistryContext: <TPayload>() => HoneyLayerRegistryContextValue<TPayload>;

package/dist/components/HoneyLayerRegistry/index.d.ts

@@ -0,0 +1,3 @@
+export * from './hooks';
+export * from './HoneyLayerRegistry.types';
+export * from './HoneyLayerRegistry';

package/dist/components/HoneyPopup/HoneyPopupContent.d.ts

@@ -1,11 +1,10 @@
 import type { CSSProperties, ReactNode } from 'react';
 import type { ReferenceType, FloatingArrowProps, FloatingFocusManagerProps, MiddlewareData } from '@floating-ui/react';
 import type { FastOmit } from '@react-hive/honey-style';
+import type { HoneyPopupContextValue, HoneyOverlayProps } from '~/components';
 import type { HoneyPopupPortalProps } from './HoneyPopupPortal';
 import type { HoneyPopupStyledProps } from './HoneyPopupStyled';
-import type { HoneyPopupContextValue } from './HoneyPopupContext';
 import type { UseHoneyPopupOptions } from './hooks';
-import type { HoneyOverlayProps } from '../HoneyOverlay';
 type InheritedHoneyOverlayProps = FastOmit<HoneyOverlayProps, 'children' | 'active' | 'onDeactivate' | '$position'>;
 export interface HoneyPopupContentProps<Context, Reference extends ReferenceType, UseAutoSize extends boolean> extends UseHoneyPopupOptions<Reference, UseAutoSize> {
     children: ReactNode | ((context: HoneyPopupContextValue<Context, Reference>) => ReactNode);

package/dist/components/HoneyPopup/hooks/use-honey-popup-context.d.ts

@@ -1,3 +1,3 @@
 import type { ReferenceType } from '@floating-ui/react';
-import type { HoneyPopupContextValue } from '../HoneyPopupContext';
+import type { HoneyPopupContextValue } from '~/components';
 export declare const useHoneyPopupContext: <Context, Reference extends ReferenceType = ReferenceType>() => HoneyPopupContextValue<Context, Reference>;

package/dist/components/index.d.ts

@@ -8,3 +8,4 @@ export * from './HoneyLazyContent';
 export * from './HoneyOverlay';
 export * from './HoneyPopup';
 export * from './HoneyContextMenu';
+export * from './HoneyLayerRegistry';

package/dist/contexts/HoneyLayoutContext.d.ts

@@ -1,5 +1,5 @@
 import type { HoneyTheme } from '@react-hive/honey-style';
-import type { HoneyOverlayConfig, HoneyScreenState, HoneyOverlayId, HoneyActiveOverlay } from '../types';
+import type { HoneyOverlayConfig, HoneyScreenState, HoneyOverlayId, HoneyActiveOverlay } from '~/types';
 /**
  * Function to unregister a previously registered overlay.
  */

package/dist/hooks/index.d.ts

@@ -1,7 +1,7 @@
 export * from './use-honey-on-change';
 export * from './use-honey-media-query';
 export * from './use-honey-drag';
-export * from './use-honey-document-key-up-handler';
+export * from './use-honey-document-key-up';
 export * from './use-honey-layout';
 export * from './use-register-honey-overlay';
 export * from './use-honey-overlay';

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-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,10 +1,10 @@
-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.
  *
- * @param isRegister - A flag indicating whether the overlay should be registered.
+ * @param shouldRegister - A flag indicating whether the overlay should be registered.
  * @param overlayConfig - Configuration object specifying overlay behavior.
  *
  * @returns The registered overlay instance, or null if not registered.
  */
-export declare const useRegisterHoneyOverlay: (isRegister: boolean, overlayConfig: HoneyOverlayConfig) => Nullable<HoneyActiveOverlay>;
+export declare const useRegisterHoneyOverlay: (shouldRegister: boolean, overlayConfig: HoneyOverlayConfig) => Nullable<HoneyActiveOverlay>;