@react-hive/honey-layout 18.0.0 → 18.1.0

package/dist/providers/HoneyLayoutProvider.d.ts

@@ -3,7 +3,32 @@ import type { PropsWithChildren } from 'react';
 import type { HoneyStyleProviderProps } from '@react-hive/honey-style';
 import type { UseHoneyMediaQueryOptions } from '../hooks';
 interface HoneyLayoutProviderProps extends HoneyStyleProviderProps {
+    /**
+     * Options used to derive the responsive screen state from the active theme.
+     */
     mediaQueryOptions?: UseHoneyMediaQueryOptions;
 }
+/**
+ * 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>
+ * ```
+ */
 export declare const HoneyLayoutProvider: ({ children, theme, mediaQueryOptions, ...props }: PropsWithChildren<HoneyLayoutProviderProps>) => React.JSX.Element;
 export {};

package/dist/providers/hooks/use-honey-overlays.d.ts

@@ -1,17 +1,21 @@
 import type { HoneyActiveOverlay } from '../../types';
 import type { HoneyRegisterOverlay, HoneyUnregisterOverlay } from '../../contexts';
 /**
- * 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.
  */
 export declare const useHoneyOverlays: () => {
-    overlays: HoneyActiveOverlay[];
+    getOverlaysSnapshot: () => HoneyActiveOverlay[];
     registerOverlay: HoneyRegisterOverlay;
+    subscribeOverlays: (subscriber: () => void) => () => void;
     unregisterOverlay: HoneyUnregisterOverlay;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-hive/honey-layout",
-  "version": "18.0.0",
+  "version": "18.1.0",
   "description": "",
   "keywords": [
     "react",