@react-hive/honey-layout 17.5.0 → 17.7.0

package/dist/index.dev.cjs

@@ -5973,34 +5973,41 @@ __webpack_require__.r(__webpack_exports__);
 
 
 /**
- * Hook for interacting with an active overlay managed by `HoneyLayoutProvider`.
+ * Returns an active overlay by ID and optionally attaches overlay event listeners.
  *
- * @param targetOverlayId - The unique ID of the overlay you want to interact with.
- * @param options - Optional configuration such as event handlers (e.g., `onKeyUp`).
+ * This hook looks up an overlay registered in `HoneyLayoutProvider` by its ID.
+ * It can also subscribe to overlay-level events, such as `keyup`, for the matched overlay.
  *
- * @returns The overlay instance matching the provided ID, or `undefined` if not found.
+ * @param targetOverlayId - The ID of the active overlay to find.
+ * @param options - Optional configuration for resolving the overlay and attaching event handlers.
+ *
+ * @returns The matching active overlay instance, or `null` when the hook is disabled
+ * or the overlay is not currently registered.
  *
  * @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.
+ * - The hook only works with overlays that are currently active.
+ * - If `enabled` is `false`, the hook returns `null` and does not attach listeners.
+ * - If the overlay is inactive, unregistered, or already removed from the stack, `null` is returned.
+ * - The `onKeyUp` listener is attached only to the matched overlay while the hook is enabled.
+ * - Event listeners are automatically cleaned up when the overlay, handler, enabled state,
+ * or component lifecycle changes.
  *
  * @example
  * ```tsx
  * const overlay = useHoneyOverlay('my-overlay-id', {
- *   onKeyUp: (keyCode, e) => {
+ *   enabled: isOpen,
+ *   onKeyUp: (keyCode, overlay, e) => {
  *     if (keyCode === 'Escape') {
- *       console.log('Escape key pressed!');
+ *       // Handle Escape key.
  *     }
  *   },
  * });
  * ```
  */
-const useHoneyOverlay = (targetOverlayId, { onKeyUp } = {}) => {
+const useHoneyOverlay = (targetOverlayId, { enabled = true, onKeyUp } = {}) => {
     const { overlays } = (0,_hooks__WEBPACK_IMPORTED_MODULE_1__.useHoneyLayout)();
-    const overlay = overlays.find(overlay => overlay.id === targetOverlayId);
+    const overlay = (0,react__WEBPACK_IMPORTED_MODULE_0__.useMemo)(() => (enabled ? (overlays.find(overlay => overlay.id === targetOverlayId) ?? null) : null), [enabled, overlays, targetOverlayId]);
     (0,react__WEBPACK_IMPORTED_MODULE_0__.useEffect)(() => {
-        // If no overlay is found or no `onKeyUp` handler is provided, skip setting up the listener
         if (!overlay || !onKeyUp) {
             return;
         }
@@ -6175,16 +6182,29 @@ __webpack_require__.r(__webpack_exports__);
 
 
 /**
- * Hook to manage a stack of overlays, allowing registration and unregistration of overlays,
- * as well as handling keyboard events for the topmost overlay.
+ * Manages the active overlay stack and global keyboard event dispatching.
+ *
+ * The hook keeps registered overlays in stack order, where the latest registered overlay
+ * is treated as the top-level overlay. Keyboard events are forwarded only to the top-level
+ * overlay, allowing nested or overlapping overlays to handle key interactions predictably.
+ *
+ * @returns An object containing the active overlays stack and helper methods for registering
+ * and unregistering overlays.
  */
 const useHoneyOverlays = () => {
-    const overlaysRef = (0,react__WEBPACK_IMPORTED_MODULE_0__.useRef)([]);
+    const [overlays, setOverlays] = (0,react__WEBPACK_IMPORTED_MODULE_0__.useState)([]);
     (0,react__WEBPACK_IMPORTED_MODULE_0__.useEffect)(() => {
+        /**
+         * Handles global keyup events and forwards them to the top-level overlay.
+         *
+         * Only the latest registered overlay receives keyboard events. This prevents inactive
+         * or visually hidden overlays lower in the stack from reacting to the same key press.
+         *
+         * @param e - The native keyboard event emitted by the document.
+         */
         const handleKeyUp = (e) => {
-            const overlays = overlaysRef.current;
             if (!overlays.length) {
-                // No overlays to handle key events
+                // No overlays to handle key events.
                 return;
             }
             const topLevelOverlay = overlays[overlays.length - 1];
@@ -6194,13 +6214,19 @@ const useHoneyOverlays = () => {
         return () => {
             document.removeEventListener('keyup', handleKeyUp);
         };
-    }, []);
+    }, [overlays]);
     /**
-     * Registers a new overlay and adds it to the stack.
+     * Registers a new overlay and adds it to the top of the overlay stack.
+     *
+     * If no custom ID is provided, an ephemeral ID is generated automatically.
+     * The returned overlay object exposes methods for storing its container element,
+     * subscribing to overlay events, removing event listeners, and notifying registered
+     * listeners when matching events occur.
      *
-     * @param overlayConfig - The configuration for the overlay, including optional ID and event handlers.
+     * @param overlayConfig - The overlay configuration, including an optional ID, optional keyup
+     * handler, and optional list of keyboard codes the overlay should listen to.
      *
-     * @returns The registered overlay object.
+     * @returns The registered active overlay instance.
      */
     const registerOverlay = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)(overlayConfig => {
         const overlayId = overlayConfig.id ?? (0,_react_hive_honey_utils__WEBPACK_IMPORTED_MODULE_1__.generateEphemeralId)();
@@ -6211,18 +6237,54 @@ const useHoneyOverlays = () => {
         const overlay = {
             containerRef,
             id: overlayId,
+            /**
+             * Stores the overlay container element reference.
+             *
+             * This allows consumers and overlay helpers to access the DOM element associated
+             * with the active overlay after it has been mounted.
+             *
+             * @param element - The overlay container element, or `null` when unavailable.
+             */
             setContainerRef: element => {
                 containerRef.current = element;
             },
+            /**
+             * Adds a listener for a supported overlay event.
+             *
+             * @param type - The overlay event type to listen for.
+             * @param handler - The event handler to call when the event is notified.
+             */
             addListener: (type, handler) => {
                 listeners.push([type, handler]);
             },
+            /**
+             * Removes a previously registered overlay event listener.
+             *
+             * The listener is removed only when both the event type and handler reference match.
+             *
+             * @param targetType - The event type of the listener to remove.
+             * @param targetHandler - The exact handler reference to remove.
+             */
             removeListener: (targetType, targetHandler) => {
                 const targetListenerIndex = listeners.findIndex(([type, listenerHandler]) => type === targetType && listenerHandler === targetHandler);
                 if (targetListenerIndex !== -1) {
                     listeners.splice(targetListenerIndex, 1);
                 }
             },
+            /**
+             * Notifies matching listeners for a specific overlay event.
+             *
+             * If `listenKeys` is provided in the overlay config, listeners are called only when
+             * the received key code is included in that list. When no `listenKeys` are provided,
+             * all key codes are accepted.
+             *
+             * The native event is prevented before listeners are called, ensuring handled overlay
+             * keyboard interactions do not trigger default browser behaviour.
+             *
+             * @param targetEventType - The event type being dispatched.
+             * @param keyCode - The keyboard code associated with the event.
+             * @param e - The native keyboard event.
+             */
             notifyListeners: (targetEventType, keyCode, e) => {
                 const listenKeys = overlayConfig.listenKeys ?? [];
                 if (!listenKeys.length || listenKeys.includes(keyCode)) {
@@ -6235,19 +6297,21 @@ const useHoneyOverlays = () => {
                 }
             },
         };
-        overlaysRef.current.push(overlay);
+        setOverlays(prevOverlays => [...prevOverlays, overlay]);
         return overlay;
     }, []);
     /**
-     * Unregisters an overlay by its ID and removes it from the stack.
+     * Unregisters an overlay by ID and removes it from the overlay stack.
      *
-     * @param targetOverlayId - The ID of the overlay to be removed.
+     * This should usually be called when an overlay is deactivated or unmounted.
+     *
+     * @param targetOverlayId - The ID of the overlay to remove.
      */
     const unregisterOverlay = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)(targetOverlayId => {
-        overlaysRef.current = overlaysRef.current.filter(overlay => overlay.id !== targetOverlayId);
+        setOverlays(prevOverlays => prevOverlays.filter(overlay => overlay.id !== targetOverlayId));
     }, []);
     return {
-        overlays: overlaysRef.current,
+        overlays,
         registerOverlay,
         unregisterOverlay,
     };