@react-hive/honey-layout 18.0.0 → 18.1.0

package/dist/index.dev.cjs

@@ -6022,41 +6022,49 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _hooks__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ../hooks */ "./src/hooks/index.ts");
 
 
+const subscribeToNothing = () => () => undefined;
 /**
- * Returns an active overlay by ID and optionally attaches overlay event listeners.
+ * Returns an active overlay by ID and optionally attaches a keyup event listener.
  *
- * 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.
+ * The hook reads the overlay through the external overlay store exposed by
+ * `HoneyLayoutProvider`. It subscribes to stack changes with `useSyncExternalStore`, but
+ * selects only the requested overlay. Consequently, unrelated overlay stack changes do not
+ * re-render the consuming component when the selected overlay instance remains unchanged.
  *
  * @param targetOverlayId - The ID of the active overlay to find.
- * @param options - Optional configuration for resolving the overlay and attaching event handlers.
+ * @param options - Optional configuration for resolving the overlay and handling keyup events.
  *
- * @returns The matching active overlay instance, or `null` when the hook is disabled
- * or the overlay is not currently registered.
+ * @returns The matching active overlay, or `null` when the hook is disabled or the overlay is
+ * not currently registered.
  *
  * @remarks
- * - 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.
+ * - The hook resolves only overlays that are currently registered.
+ * - If `enabled` is `false`, the snapshot is `null` and no keyup listener is attached.
+ * - If the target overlay is registered or unregistered, the consuming component is updated.
+ * - Changes to unrelated overlays do not cause a re-render when the selected snapshot is equal.
+ * - The `onKeyUp` listener is automatically cleaned up when its dependencies change.
  *
  * @example
  * ```tsx
  * const overlay = useHoneyOverlay('my-overlay-id', {
  *   enabled: isOpen,
- *   onKeyUp: (keyCode, overlay, e) => {
+ *   onKeyUp: keyCode => {
  *     if (keyCode === 'Escape') {
- *       // Handle Escape key.
+ *       closeOverlay();
  *     }
  *   },
  * });
  * ```
  */
 const useHoneyOverlay = (targetOverlayId, { enabled = true, onKeyUp } = {}) => {
-    const { overlays } = (0,_hooks__WEBPACK_IMPORTED_MODULE_1__.useHoneyLayout)();
-    const overlay = (0,react__WEBPACK_IMPORTED_MODULE_0__.useMemo)(() => (enabled ? (overlays.find(overlay => overlay.id === targetOverlayId) ?? null) : null), [enabled, overlays, targetOverlayId]);
+    const { getOverlaysSnapshot, subscribeOverlays } = (0,_hooks__WEBPACK_IMPORTED_MODULE_1__.useHoneyLayout)();
+    const getOverlaySnapshot = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)(() => {
+        if (!enabled) {
+            return null;
+        }
+        return getOverlaysSnapshot().find(overlay => overlay.id === targetOverlayId) ?? null;
+    }, [enabled, targetOverlayId]);
+    const overlay = (0,react__WEBPACK_IMPORTED_MODULE_0__.useSyncExternalStore)(enabled ? subscribeOverlays : subscribeToNothing, getOverlaySnapshot, getOverlaySnapshot);
     (0,react__WEBPACK_IMPORTED_MODULE_0__.useEffect)(() => {
         if (!overlay || !onKeyUp) {
             return;
@@ -6141,16 +6149,39 @@ __webpack_require__.r(__webpack_exports__);
 
 
 
+/**
+ * Provides Honey styling, responsive screen state, and overlay management to its descendants.
+ *
+ * Overlay state is held in a ref-backed external store. Registering or unregistering an overlay
+ * notifies subscribed overlay consumers without updating this provider's React state or context
+ * value. This prevents overlay stack changes from re-rendering the full layout subtree.
+ *
+ * The context value changes only when the theme or responsive screen state changes. Overlay
+ * consumers should read the store through `useHoneyOverlay` or `useSyncExternalStore` rather
+ * than attempting to read the overlay ref directly.
+ *
+ * @param props - The provider props, including the theme, children, style-provider options,
+ * and optional media-query configuration.
+ * @returns The configured Honey style and layout providers.
+ *
+ * @example
+ * ```tsx
+ * <HoneyLayoutProvider theme={theme} mediaQueryOptions={mediaQueryOptions}>
+ *   <App />
+ * </HoneyLayoutProvider>
+ * ```
+ */
 const HoneyLayoutProvider = ({ children, theme, mediaQueryOptions, ...props }) => {
     const screenState = (0,_hooks__WEBPACK_IMPORTED_MODULE_3__.useHoneyMediaQuery)(theme, mediaQueryOptions);
-    const { overlays, registerOverlay, unregisterOverlay } = (0,_hooks__WEBPACK_IMPORTED_MODULE_5__.useHoneyOverlays)();
+    const { getOverlaysSnapshot, registerOverlay, subscribeOverlays, unregisterOverlay } = (0,_hooks__WEBPACK_IMPORTED_MODULE_5__.useHoneyOverlays)();
     const contextValue = (0,react__WEBPACK_IMPORTED_MODULE_1__.useMemo)(() => ({
         theme,
         screenState,
-        overlays,
+        getOverlaysSnapshot,
         registerOverlay,
+        subscribeOverlays,
         unregisterOverlay,
-    }), [theme, screenState, overlays]);
+    }), [theme, screenState]);
     return ((0,react_jsx_runtime__WEBPACK_IMPORTED_MODULE_0__.jsx)(_react_hive_honey_style__WEBPACK_IMPORTED_MODULE_2__.HoneyStyleProvider, { theme: theme, ...props, children: (0,react_jsx_runtime__WEBPACK_IMPORTED_MODULE_0__.jsx)(_contexts__WEBPACK_IMPORTED_MODULE_4__.HoneyLayoutContext, { value: contextValue, children: children }) }));
 };
 
@@ -6232,17 +6263,51 @@ __webpack_require__.r(__webpack_exports__);
 
 
 /**
- * Manages the active overlay stack and global keyboard event dispatching.
+ * Manages the active overlay stack and dispatches global keyboard events.
  *
- * 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.
+ * Registered overlays are stored in a ref so adding or removing an overlay does not re-render
+ * the component that owns this hook. The hook exposes a snapshot getter and subscription
+ * function that consumers can use with `useSyncExternalStore` to react to stack changes.
  *
- * @returns An object containing the active overlays stack and helper methods for registering
- * and unregistering overlays.
+ * Overlays are kept in stack order. The most recently registered overlay is treated as the
+ * top-level overlay and is the only overlay that receives global keyboard events.
+ *
+ * @returns A stable overlay store containing methods for reading and subscribing to the stack,
+ * together with helpers for registering and unregistering overlays.
  */
 const useHoneyOverlays = () => {
     const overlaysRef = (0,react__WEBPACK_IMPORTED_MODULE_0__.useRef)([]);
+    const subscribersRef = (0,react__WEBPACK_IMPORTED_MODULE_0__.useRef)(new Set());
+    /**
+     * Returns the current overlay stack snapshot.
+     *
+     * The snapshot keeps the same array identity until the stack changes, making this getter
+     * compatible with `useSyncExternalStore`.
+     *
+     * @returns The current active overlays in registration order.
+     */
+    const getOverlaysSnapshot = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)(() => overlaysRef.current, []);
+    /**
+     * Subscribes to overlay stack changes.
+     *
+     * The subscriber is notified after an overlay is registered or successfully unregistered.
+     * Subscribing does not itself cause the component that owns this hook to re-render.
+     *
+     * @param subscriber - Callback invoked whenever the overlay stack snapshot changes.
+     * @returns A cleanup function that removes the subscriber.
+     */
+    const subscribeOverlays = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)((subscriber) => {
+        subscribersRef.current.add(subscriber);
+        return () => {
+            subscribersRef.current.delete(subscriber);
+        };
+    }, []);
+    /**
+     * Notifies every overlay stack subscriber that a new snapshot is available.
+     */
+    const notifyOverlaySubscribers = (0,react__WEBPACK_IMPORTED_MODULE_0__.useCallback)(() => {
+        subscribersRef.current.forEach(subscriber => subscriber());
+    }, []);
     (0,react__WEBPACK_IMPORTED_MODULE_0__.useEffect)(() => {
         /**
          * Handles global keyup events and forwards them to the top-level overlay.
@@ -6273,6 +6338,9 @@ const useHoneyOverlays = () => {
      * subscribing to overlay events, removing event listeners, and notifying registered
      * listeners when matching events occur.
      *
+     * Registering creates a new stack snapshot and notifies overlay stack subscribers without
+     * re-rendering the component that owns this hook.
+     *
      * @param overlayConfig - The overlay configuration, including an optional ID, optional keyup
      * handler, and optional list of keyboard codes the overlay should listen to.
      *
@@ -6348,23 +6416,30 @@ const useHoneyOverlays = () => {
             },
         };
         overlaysRef.current = [...overlaysRef.current, overlay];
+        notifyOverlaySubscribers();
         return overlay;
     }, []);
     /**
      * Unregisters an overlay by ID and removes it from the overlay stack.
      *
      * This should usually be called when an overlay is deactivated or unmounted.
+     * Subscribers are notified only when an overlay with the supplied ID was present.
      *
      * @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);
+        const nextOverlays = overlaysRef.current.filter(overlay => overlay.id !== targetOverlayId);
+        if (nextOverlays.length !== overlaysRef.current.length) {
+            overlaysRef.current = nextOverlays;
+            notifyOverlaySubscribers();
+        }
     }, []);
-    return {
-        overlays: overlaysRef.current,
+    return (0,react__WEBPACK_IMPORTED_MODULE_0__.useMemo)(() => ({
+        getOverlaysSnapshot,
         registerOverlay,
+        subscribeOverlays,
         unregisterOverlay,
-    };
+    }), []);
 };