@react-hive/honey-layout 17.4.0 → 17.6.0

package/dist/index.dev.cjs

@@ -4829,9 +4829,11 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! react */ "react");
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_1___default = /*#__PURE__*/__webpack_require__.n(react__WEBPACK_IMPORTED_MODULE_1__);
 /* harmony import */ var _react_hive_honey_utils__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(/*! @react-hive/honey-utils */ "./node_modules/.pnpm/@react-hive+honey-utils@4.0.0/node_modules/@react-hive/honey-utils/dist/index.mjs");
-/* harmony import */ var _hooks__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(/*! ../hooks */ "./src/hooks/index.ts");
-/* harmony import */ var _helpers__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(/*! ../helpers */ "./src/helpers/index.ts");
-/* harmony import */ var _HoneyFlex__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(/*! ./HoneyFlex */ "./src/components/HoneyFlex/index.ts");
+/* harmony import */ var _react_hive_honey_hooks__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(/*! @react-hive/honey-hooks */ "./node_modules/.pnpm/@react-hive+honey-hooks@3.1.0_react@19.2.7/node_modules/@react-hive/honey-hooks/dist/index.mjs");
+/* harmony import */ var _hooks__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(/*! ../hooks */ "./src/hooks/index.ts");
+/* harmony import */ var _helpers__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(/*! ../helpers */ "./src/helpers/index.ts");
+/* harmony import */ var _HoneyFlex__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(/*! ./HoneyFlex */ "./src/components/HoneyFlex/index.ts");
+
 
 
 
@@ -4841,9 +4843,14 @@ __webpack_require__.r(__webpack_exports__);
 /**
  * A reusable overlay component integrated with the `HoneyLayoutProvider` system.
  *
- * Automatically registers/unregisters itself with the layout system and handles key events.
+ * The component registers itself with the overlay system when active, provides
+ * overlay context to render-function children, and disables interaction with its
+ * content when inactive by applying the `inert` attribute.
  *
- * @param props - Component configuration.
+ * By default, releasing the Escape key deactivates the overlay. Custom key handling
+ * can be provided through `onKeyUp`.
+ *
+ * @param props - Overlay component props.
  *
  * @example
  * ```tsx
@@ -4859,21 +4866,42 @@ __webpack_require__.r(__webpack_exports__);
  *   )}
  * </HoneyOverlay>
  * ```
+ *
+ * @example
+ * ```tsx
+ * <HoneyOverlay
+ *   active={isOpen}
+ *   onDeactivate={() => setIsOpen(false)}
+ *   onKeyUp={(keyCode) => {
+ *     if (keyCode === 'Escape') {
+ *       setIsOpen(false);
+ *     }
+ *   }}
+ * >
+ *   Overlay content
+ * </HoneyOverlay>
+ * ```
  */
-const HoneyOverlay = ({ ref, children, active, overlayId, onDeactivate, ...props }) => {
-    const overlay = (0,_hooks__WEBPACK_IMPORTED_MODULE_3__.useRegisterHoneyOverlay)(active, {
+const HoneyOverlay = ({ ref, children, active, overlayId, onDeactivate, onKeyUp, ...props }) => {
+    const onKeyUpRef = (0,_react_hive_honey_hooks__WEBPACK_IMPORTED_MODULE_3__.useHoneyLatest)(onKeyUp);
+    const onDeactivateRef = (0,_react_hive_honey_hooks__WEBPACK_IMPORTED_MODULE_3__.useHoneyLatest)(onDeactivate);
+    const handleKeyUp = (0,react__WEBPACK_IMPORTED_MODULE_1__.useCallback)((keyCode, ...args) => {
+        if (onKeyUpRef.current) {
+            onKeyUpRef.current(keyCode, ...args);
+        }
+        else if (keyCode === 'Escape') {
+            onDeactivateRef.current();
+        }
+    }, []);
+    const overlay = (0,_hooks__WEBPACK_IMPORTED_MODULE_4__.useRegisterHoneyOverlay)(active, {
         id: overlayId,
-        onKeyUp: (0,react__WEBPACK_IMPORTED_MODULE_1__.useCallback)(keyCode => {
-            if (keyCode === 'Escape') {
-                onDeactivate();
-            }
-        }, [onDeactivate]),
+        onKeyUp: handleKeyUp,
     });
-    const mergedRef = (0,_helpers__WEBPACK_IMPORTED_MODULE_4__.mergeRefs)(overlay?.setContainerRef, ref);
-    return ((0,react_jsx_runtime__WEBPACK_IMPORTED_MODULE_0__.jsx)(_HoneyFlex__WEBPACK_IMPORTED_MODULE_5__.HoneyFlex, { ref: mergedRef, inert: !active, ...props, children: (0,_react_hive_honey_utils__WEBPACK_IMPORTED_MODULE_2__.invokeIfFunction)(children, {
+    const mergedRef = (0,_helpers__WEBPACK_IMPORTED_MODULE_5__.mergeRefs)(overlay?.setContainerRef, ref);
+    return ((0,react_jsx_runtime__WEBPACK_IMPORTED_MODULE_0__.jsx)(_HoneyFlex__WEBPACK_IMPORTED_MODULE_6__.HoneyFlex, { ref: mergedRef, inert: !active, ...props, children: (0,_react_hive_honey_utils__WEBPACK_IMPORTED_MODULE_2__.invokeIfFunction)(children, {
             overlay,
             isActive: active,
-            deactivateOverlay: onDeactivate,
+            deactivateOverlay: onDeactivateRef.current,
         }) }));
 };
 
@@ -5945,24 +5973,28 @@ __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.
+ *
+ * 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.
  *
- * @param targetOverlayId - The unique ID of the overlay you want to interact with.
- * @param options - Optional configuration such as event handlers (e.g., `onKeyUp`).
+ * @param targetOverlayId - The ID of the active overlay to find.
+ * @param options - Optional overlay event handlers.
  *
- * @returns The overlay instance matching the provided ID, or `undefined` if not found.
+ * @returns The matching active overlay instance, or `undefined` when the overlay is not 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 the overlay is inactive, unregistered, or already removed from the stack, `undefined` is returned.
+ * - The `onKeyUp` listener is attached only to the matched overlay.
+ * - Event listeners are automatically cleaned up when the overlay, handler, or component lifecycle changes.
  *
  * @example
  * ```tsx
  * const overlay = useHoneyOverlay('my-overlay-id', {
- *   onKeyUp: (keyCode, e) => {
+ *   onKeyUp: (keyCode, overlay, e) => {
  *     if (keyCode === 'Escape') {
- *       console.log('Escape key pressed!');
+ *      //
  *     }
  *   },
  * });
@@ -5970,7 +6002,7 @@ __webpack_require__.r(__webpack_exports__);
  */
 const useHoneyOverlay = (targetOverlayId, { 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)(() => overlays.find(overlay => overlay.id === targetOverlayId), [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) {
@@ -6147,16 +6179,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];
@@ -6166,13 +6211,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.
      *
-     * @param overlayConfig - The configuration for the overlay, including optional ID and event handlers.
+     * 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.
      *
-     * @returns The registered overlay object.
+     * @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 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)();
@@ -6183,18 +6234,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)) {
@@ -6207,19 +6294,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.
+     *
+     * This should usually be called when an overlay is deactivated or unmounted.
      *
-     * @param targetOverlayId - The ID of the overlay to be removed.
+     * @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,
     };