@react-hive/honey-layout 18.0.0 → 18.1.0

package/dist/contexts/HoneyLayoutContext.d.ts

@@ -1,34 +1,60 @@
 import type { HoneyTheme } from '@react-hive/honey-style';
 import type { HoneyOverlayConfig, HoneyScreenState, HoneyOverlayId, HoneyActiveOverlay } from '../types';
 /**
- * Function to unregister a previously registered overlay.
+ * Returns the current active overlay stack snapshot.
+ *
+ * The returned array keeps the same identity until the overlay stack changes, allowing it to
+ * be consumed safely by `useSyncExternalStore`. Consumers must not mutate the snapshot.
+ *
+ * @returns The active overlays in registration order.
+ */
+export type HoneyGetOverlaysSnapshot = () => readonly HoneyActiveOverlay[];
+/**
+ * Subscribes to active overlay stack changes.
+ *
+ * @param subscriber - Callback invoked when a new overlay stack snapshot is available.
+ * @returns A cleanup function that removes the subscriber.
+ */
+export type HoneySubscribeOverlays = (subscriber: () => void) => () => void;
+/**
+ * Unregisters a previously registered overlay.
+ *
+ * @param targetOverlayId - The ID of the overlay to unregister.
  */
 export type HoneyUnregisterOverlay = (targetOverlayId: HoneyOverlayId) => void;
 /**
- * Function to register a new overlay and manage its lifecycle.
+ * Registers a new active overlay.
  *
- * @param overlayConfig - Configuration object for the overlay.
+ * @param overlayConfig - Configuration for the overlay.
+ * @returns The registered active overlay instance.
  */
 export type HoneyRegisterOverlay = (overlayConfig: HoneyOverlayConfig) => HoneyActiveOverlay;
+/**
+ * Values and overlay-store operations exposed by `HoneyLayoutProvider`.
+ */
 export interface HoneyLayoutContextValue {
     /**
-     * Represents the theme object.
+     * The active Honey theme.
      */
     theme: HoneyTheme;
     /**
-     * Represents the current state of the screen.
+     * The current responsive screen state.
      */
     screenState: HoneyScreenState;
     /**
-     * Active overlays.
+     * Returns the current overlay stack snapshot without subscribing the caller to changes.
+     */
+    getOverlaysSnapshot: HoneyGetOverlaysSnapshot;
+    /**
+     * Subscribes a consumer to overlay stack changes without re-rendering the layout provider.
      */
-    overlays: HoneyActiveOverlay[];
+    subscribeOverlays: HoneySubscribeOverlays;
     /**
-     * Function to register a new overlay.
+     * Registers an overlay and publishes a new overlay stack snapshot.
      */
     registerOverlay: HoneyRegisterOverlay;
     /**
-     * Function to unregister an overlay.
+     * Unregisters an overlay and publishes a new snapshot when the overlay existed.
      */
     unregisterOverlay: HoneyUnregisterOverlay;
 }

package/dist/hooks/use-honey-overlay.d.ts

@@ -1,49 +1,51 @@
-import type { HoneyOverlayId, HoneyOverlayEventListenerHandler, HoneyActiveOverlay, Nullable } from '../types';
+import type { HoneyOverlayId, HoneyOverlayEventListenerHandler, Nullable, HoneyActiveOverlay } from '../types';
 interface UseHoneyOverlayOptions {
     /**
      * Whether the hook should resolve the overlay and attach event listeners.
      *
-     * When `false`, the hook returns `null` and does not register any listeners.
+     * When `false`, the hook returns `null`, does not subscribe to overlay stack changes,
+     * and does not attach an overlay event listener.
      *
      * @default true
      */
     enabled?: boolean;
     /**
-     * Callback fired when the active target overlay receives a keyup event.
+     * Callback fired when the target overlay receives a keyup event.
      *
-     * The handler is registered only while the target overlay is active, the hook is enabled,
-     * and the handler is provided. It is automatically removed when the overlay changes,
-     * the handler changes, the hook is disabled, or the component unmounts.
+     * The handler is attached only while the target overlay is active and the hook is enabled.
+     * It is automatically removed when the overlay or handler changes, the hook is disabled,
+     * or the component unmounts.
      */
     onKeyUp?: HoneyOverlayEventListenerHandler;
 }
 /**
- * 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();
  *     }
  *   },
  * });