@cube-dev/ui-kit 0.190.8 → 0.191.0

package/dist/utils/react/usePopoverSync.js

@@ -1,7 +1,7 @@
-/** @license MIT | @cube-dev/ui-kit v0.190.8 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.191.0 | Cube Dev Team */
 import { EventBusContext, useEventBus } from "./useEventBus.js";
-import { c } from "react-compiler-runtime";
-import { useContext, useEffect, useRef } from "react";
+import { c } from "react/compiler-runtime";
+import { useContext, useEffect, useEffectEvent, useRef } from "react";
 
 //#region src/utils/react/usePopoverSync.ts
 /**
@@ -61,9 +61,9 @@ function isLogicalDescendantOf(target, ancestorMenuId, ancestorContainer) {
 * race that surfaces only under rapid trigger switching, which is hard to
 * reproduce in tests):
 *
-* 1. `isOpen` and `onClose` are read through refs inside the listener, so the
-*    subscription effect's dep array does NOT include `isOpen`/`onClose`. This
-*    keeps the listener identity stable across open/close transitions and
+* 1. Effect Events read current `isOpen`, `onClose` and container data, so the
+*    subscription effect's dep array includes only resource configuration. This
+*    keeps the existing subscriptions across open/close transitions and
 *    avoids the unsubscribe-emit-resubscribe window where an emit can be
 *    delivered to a stale listener (or no listener).
 * 2. The emit fires only on the `false -> true` transition, gated by
@@ -75,21 +75,21 @@ function isLogicalDescendantOf(target, ancestorMenuId, ancestorContainer) {
 *    `isOpen` is true at that moment.
 */
 function usePopoverSync(t0) {
-	const $ = c(28);
+	const $ = c(37);
 	const { menuId, isOpen, onClose, enabled: t1, triggerRef, containerRef, dismissOnInnerButtonPress: t2, closeOnPeerOpen: t3 } = t0;
 	const enabled = t1 === void 0 ? true : t1;
 	const dismissOnInnerButtonPress = t2 === void 0 ? true : t2;
 	const closeOnPeerOpen = t3 === void 0 ? true : t3;
 	const { emit, on } = useEventBus();
-	const isOpenRef = useRef(isOpen);
+	const containerRefRef = useRef(containerRef);
 	let t4;
 	let t5;
-	if ($[0] !== isOpen) {
+	if ($[0] !== containerRef) {
 		t4 = () => {
-			isOpenRef.current = isOpen;
+			containerRefRef.current = containerRef;
 		};
-		t5 = [isOpen];
-		$[0] = isOpen;
+		t5 = [containerRef];
+		$[0] = containerRef;
 		$[1] = t4;
 		$[2] = t5;
 	} else {
@@ -97,15 +97,15 @@ function usePopoverSync(t0) {
 		t5 = $[2];
 	}
 	useEffect(t4, t5);
-	const onCloseRef = useRef(onClose);
+	const triggerRefRef = useRef(triggerRef);
 	let t6;
 	let t7;
-	if ($[3] !== onClose) {
+	if ($[3] !== triggerRef) {
 		t6 = () => {
-			onCloseRef.current = onClose;
+			triggerRefRef.current = triggerRef;
 		};
-		t7 = [onClose];
-		$[3] = onClose;
+		t7 = [triggerRef];
+		$[3] = triggerRef;
 		$[4] = t6;
 		$[5] = t7;
 	} else {
@@ -113,85 +113,77 @@ function usePopoverSync(t0) {
 		t7 = $[5];
 	}
 	useEffect(t6, t7);
-	const containerRefRef = useRef(containerRef);
 	let t8;
-	let t9;
-	if ($[6] !== containerRef) {
-		t8 = () => {
-			containerRefRef.current = containerRef;
+	if ($[6] !== containerRef || $[7] !== isOpen || $[8] !== menuId || $[9] !== onClose) {
+		t8 = (data) => {
+			if (data.menuId === menuId || !isOpen) return;
+			const container = containerRef?.current ?? null;
+			if (isLogicalDescendantOf(data.triggerEl, menuId, container)) return;
+			onClose();
 		};
-		t9 = [containerRef];
 		$[6] = containerRef;
-		$[7] = t8;
-		$[8] = t9;
-	} else {
-		t8 = $[7];
-		t9 = $[8];
-	}
-	useEffect(t8, t9);
-	const triggerRefRef = useRef(triggerRef);
+		$[7] = isOpen;
+		$[8] = menuId;
+		$[9] = onClose;
+		$[10] = t8;
+	} else t8 = $[10];
+	const onPeerOpen = useEffectEvent(t8);
+	let t9;
+	if ($[11] !== containerRef || $[12] !== isOpen || $[13] !== onClose) {
+		t9 = (data_0) => {
+			if (!isOpen) return;
+			const container_0 = containerRef?.current;
+			const from = data_0?.from;
+			if (!container_0 || !from) return;
+			if (container_0.contains(from)) onClose();
+		};
+		$[11] = containerRef;
+		$[12] = isOpen;
+		$[13] = onClose;
+		$[14] = t9;
+	} else t9 = $[14];
+	const onDismissAncestor = useEffectEvent(t9);
 	let t10;
-	let t11;
-	if ($[9] !== triggerRef) {
+	if ($[15] !== closeOnPeerOpen || $[16] !== dismissOnInnerButtonPress || $[17] !== enabled || $[18] !== on || $[19] !== onDismissAncestor || $[20] !== onPeerOpen) {
 		t10 = () => {
-			triggerRefRef.current = triggerRef;
-		};
-		t11 = [triggerRef];
-		$[9] = triggerRef;
-		$[10] = t10;
-		$[11] = t11;
-	} else {
-		t10 = $[10];
-		t11 = $[11];
-	}
-	useEffect(t10, t11);
-	let t12;
-	let t13;
-	if ($[12] !== closeOnPeerOpen || $[13] !== dismissOnInnerButtonPress || $[14] !== enabled || $[15] !== menuId || $[16] !== on) {
-		t12 = () => {
 			if (!enabled) return;
-			const offOpen = closeOnPeerOpen ? on("popover:open", (data) => {
-				if (data.menuId === menuId || !isOpenRef.current) return;
-				const container = containerRefRef.current?.current ?? null;
-				if (isLogicalDescendantOf(data.triggerEl, menuId, container)) return;
-				onCloseRef.current();
-			}) : null;
-			const offDismiss = dismissOnInnerButtonPress ? on("popover:dismiss-ancestor", (data_0) => {
-				if (!isOpenRef.current) return;
-				const container_0 = containerRefRef.current?.current;
-				const from = data_0?.from;
-				if (!container_0 || !from) return;
-				if (container_0.contains(from)) onCloseRef.current();
-			}) : null;
+			const offOpen = closeOnPeerOpen ? on("popover:open", onPeerOpen) : null;
+			const offDismiss = dismissOnInnerButtonPress ? on("popover:dismiss-ancestor", onDismissAncestor) : null;
 			return () => {
 				offOpen?.();
 				offDismiss?.();
 			};
 		};
-		t13 = [
+		$[15] = closeOnPeerOpen;
+		$[16] = dismissOnInnerButtonPress;
+		$[17] = enabled;
+		$[18] = on;
+		$[19] = onDismissAncestor;
+		$[20] = onPeerOpen;
+		$[21] = t10;
+	} else t10 = $[21];
+	let t11;
+	if ($[22] !== closeOnPeerOpen || $[23] !== dismissOnInnerButtonPress || $[24] !== enabled || $[25] !== menuId || $[26] !== on) {
+		t11 = [
 			on,
 			menuId,
 			enabled,
 			dismissOnInnerButtonPress,
 			closeOnPeerOpen
 		];
-		$[12] = closeOnPeerOpen;
-		$[13] = dismissOnInnerButtonPress;
-		$[14] = enabled;
-		$[15] = menuId;
-		$[16] = on;
-		$[17] = t12;
-		$[18] = t13;
-	} else {
-		t12 = $[17];
-		t13 = $[18];
-	}
-	useEffect(t12, t13);
+		$[22] = closeOnPeerOpen;
+		$[23] = dismissOnInnerButtonPress;
+		$[24] = enabled;
+		$[25] = menuId;
+		$[26] = on;
+		$[27] = t11;
+	} else t11 = $[27];
+	useEffect(t10, t11);
 	const wasOpenRef = useRef(false);
-	let t14;
-	let t15;
-	if ($[19] !== emit || $[20] !== enabled || $[21] !== isOpen || $[22] !== menuId) {
-		t14 = () => {
+	let t12;
+	let t13;
+	if ($[28] !== emit || $[29] !== enabled || $[30] !== isOpen || $[31] !== menuId) {
+		t12 = () => {
 			if (!enabled) {
 				if (wasOpenRef.current) openPopovers.delete(menuId);
 				wasOpenRef.current = false;
@@ -212,38 +204,38 @@ function usePopoverSync(t0) {
 				openPopovers.delete(menuId);
 			}
 		};
-		t15 = [
+		t13 = [
 			isOpen,
 			emit,
 			menuId,
 			enabled
 		];
-		$[19] = emit;
-		$[20] = enabled;
-		$[21] = isOpen;
-		$[22] = menuId;
-		$[23] = t14;
-		$[24] = t15;
+		$[28] = emit;
+		$[29] = enabled;
+		$[30] = isOpen;
+		$[31] = menuId;
+		$[32] = t12;
+		$[33] = t13;
 	} else {
-		t14 = $[23];
-		t15 = $[24];
+		t12 = $[32];
+		t13 = $[33];
 	}
-	useEffect(t14, t15);
-	let t16;
-	let t17;
-	if ($[25] !== menuId) {
-		t16 = () => () => {
+	useEffect(t12, t13);
+	let t14;
+	let t15;
+	if ($[34] !== menuId) {
+		t14 = () => () => {
 			openPopovers.delete(menuId);
 		};
-		t17 = [menuId];
-		$[25] = menuId;
-		$[26] = t16;
-		$[27] = t17;
+		t15 = [menuId];
+		$[34] = menuId;
+		$[35] = t14;
+		$[36] = t15;
 	} else {
-		t16 = $[26];
-		t17 = $[27];
+		t14 = $[35];
+		t15 = $[36];
 	}
-	useEffect(t16, t17);
+	useEffect(t14, t15);
 }
 /**
 * Hook that returns a dispatcher to close the popover that contains a given

package/dist/utils/react/usePopoverSync.js.map

@@ -1 +1 @@
-{"version":3,"file":"usePopoverSync.js","names":["RefObject","useContext","useEffect","useRef","EventBusContext","useEventBus","UsePopoverSyncOptions","menuId","isOpen","onClose","enabled","triggerRef","HTMLElement","containerRef","dismissOnInnerButtonPress","closeOnPeerOpen","PopoverOpenPayload","triggerEl","Element","PopoverDismissAncestorPayload","from","PopoverRegistryEntry","getContainerEl","getTriggerEl","openPopovers","Map","findOwningPopover","target","entry","contains","isLogicalDescendantOf","ancestorMenuId","ancestorContainer","cur","visited","Set","owner","id","has","add","usePopoverSync","t0","$","_c","t1","t2","t3","undefined","emit","on","isOpenRef","t4","t5","current","onCloseRef","t6","t7","containerRefRef","t8","t9","triggerRefRef","t10","t11","t12","t13","offOpen","data","container","offDismiss","data_0","container_0","wasOpenRef","t14","t15","delete","set","t16","t17","useDismissParentPopover","bus"],"sources":["../../../src/utils/react/usePopoverSync.ts"],"sourcesContent":["import { RefObject, useContext, useEffect, useRef } from 'react';\n\nimport { EventBusContext, useEventBus } from './useEventBus';\n\nexport interface UsePopoverSyncOptions {\n  /** Stable identifier for this popover instance (typically a generateRandomId() memo). */\n  menuId: string;\n  /** Current open state of this popover. */\n  isOpen: boolean;\n  /** Called when another popover opens while this one is open. */\n  onClose: () => void;\n  /**\n   * When `false`, this popover does not participate in the sync (no listening,\n   * no emitting). Useful for \"dummy\" triggers that proxy a real one (see\n   * `MenuTrigger`'s `isDummy`). Defaults to `true`.\n   */\n  enabled?: boolean;\n  /**\n   * Ref to the popover's trigger element. When provided, the element is\n   * included in the `popover:open` emit payload so peers can detect whether\n   * the new opener is nested inside their own overlay (and skip closing in\n   * that case). Optional — omitting it preserves the legacy \"always close on\n   * peer open\" behaviour.\n   */\n  triggerRef?: RefObject<HTMLElement | null>;\n  /**\n   * Ref to the overlay/container element that hosts this popover's content.\n   * When provided, the listener performs a DOM `contains()` check on incoming\n   * peer triggers: peers whose trigger lives inside this container are\n   * considered nested children and do NOT close us.\n   */\n  containerRef?: RefObject<HTMLElement | null>;\n  /**\n   * Whether this overlay closes when a Button/ItemButton inside its container\n   * is pressed. Defaults to `true` (popover semantics — popovers are transient\n   * surfaces and any action inside them should dismiss them). Set to `false`\n   * for modals/trays/fullscreen dialogs — buttons inside a Dialog should not\n   * auto-close it. Requires `containerRef` to be set; without it the listener\n   * has no way to determine whether the dispatching button is \"inside\" this\n   * overlay and is effectively a no-op.\n   */\n  dismissOnInnerButtonPress?: boolean;\n  /**\n   * Whether this overlay closes when a peer popover opens. Defaults to `true`\n   * (popover semantics — only one popover open at a time). Set to `false` for\n   * modals/trays/fullscreen dialogs so a peer popover opening cannot bypass\n   * the dialog's own `isDismissable` / `onClose` handling and yank it shut.\n   *\n   * The host still EMITS `popover:open` regardless of this flag, so opening a\n   * modal/tray correctly dismisses any peer popover that was open before.\n   */\n  closeOnPeerOpen?: boolean;\n}\n\ninterface PopoverOpenPayload {\n  menuId: string;\n  triggerEl: Element | null;\n}\n\ninterface PopoverDismissAncestorPayload {\n  /** The DOM node of the button that requested the dismiss. */\n  from: Element | null;\n}\n\ninterface PopoverRegistryEntry {\n  getContainerEl: () => Element | null;\n  getTriggerEl: () => Element | null;\n}\n\n/**\n * Module-level registry of currently open popovers. Lets us resolve the\n * LOGICAL parent of an arbitrary element across portal boundaries.\n *\n * Popover content is portaled to a shared root (`document.body` by default —\n * see `Overlay.tsx`), so a grandchild popover's trigger lives inside a\n * sibling portal rather than physically inside its grandparent's container.\n * A naive `container.contains(triggerEl)` check therefore misses the\n * relationship and closes the grandparent — the bug that surfaces with 3+\n * levels of `SubMenuTrigger` nesting.\n *\n * The registry stores closures over the host's refs so reads always see the\n * latest `.current` value without forcing a re-register per render.\n */\nconst openPopovers = new Map<string, PopoverRegistryEntry>();\n\n/**\n * Find the open popover whose container directly contains `target`. Returns\n * `null` for elements that live outside every registered popover (e.g. a\n * top-level trigger button rendered next to its overlay root).\n */\nfunction findOwningPopover(\n  target: Element | null,\n): [string, PopoverRegistryEntry] | null {\n  if (!target) return null;\n  for (const entry of openPopovers) {\n    if (entry[1].getContainerEl()?.contains(target)) {\n      return entry;\n    }\n  }\n  return null;\n}\n\n/**\n * Returns `true` when `target` is nested inside the overlay identified by\n * `ancestorMenuId` — either as a direct DOM descendant of `ancestorContainer`\n * or as a descendant of a chain of popovers whose triggers eventually land\n * inside it. Used by `popover:open` peers to avoid closing themselves when a\n * grand-child overlay opens through a portal.\n */\nfunction isLogicalDescendantOf(\n  target: Element | null,\n  ancestorMenuId: string,\n  ancestorContainer: Element | null,\n): boolean {\n  if (ancestorContainer && target && ancestorContainer.contains(target)) {\n    return true;\n  }\n  let cur: Element | null = target;\n  const visited = new Set<string>();\n  while (cur) {\n    const owner = findOwningPopover(cur);\n    if (!owner) return false;\n    const [id, entry] = owner;\n    if (visited.has(id)) return false;\n    visited.add(id);\n    if (id === ancestorMenuId) return true;\n    cur = entry.getTriggerEl();\n  }\n  return false;\n}\n\n/**\n * Coordinates the \"only one popover open at a time\" invariant via the EventBus.\n *\n * - When `isOpen` flips `false -> true`, emits `popover:open` once.\n * - While open, listens for peers' `popover:open` events and calls `onClose`.\n *\n * Implementation notes (ALL of these matter — losing any one re-introduces a\n * race that surfaces only under rapid trigger switching, which is hard to\n * reproduce in tests):\n *\n * 1. `isOpen` and `onClose` are read through refs inside the listener, so the\n *    subscription effect's dep array does NOT include `isOpen`/`onClose`. This\n *    keeps the listener identity stable across open/close transitions and\n *    avoids the unsubscribe-emit-resubscribe window where an emit can be\n *    delivered to a stale listener (or no listener).\n * 2. The emit fires only on the `false -> true` transition, gated by\n *    `wasOpenRef`. A re-render where `isOpen` is still `true` must NOT\n *    re-emit, otherwise it could re-trigger listeners on peers that just\n *    opened in the same render flush.\n * 3. The `enabled` flag short-circuits both effects symmetrically. When it\n *    flips off, `wasOpenRef` is reset so re-enabling later still emits if\n *    `isOpen` is true at that moment.\n */\nexport function usePopoverSync({\n  menuId,\n  isOpen,\n  onClose,\n  enabled = true,\n  triggerRef,\n  containerRef,\n  dismissOnInnerButtonPress = true,\n  closeOnPeerOpen = true,\n}: UsePopoverSyncOptions): void {\n  const { emit, on } = useEventBus();\n\n  const isOpenRef = useRef(isOpen);\n  useEffect(() => {\n    isOpenRef.current = isOpen;\n  }, [isOpen]);\n\n  const onCloseRef = useRef(onClose);\n  useEffect(() => {\n    onCloseRef.current = onClose;\n  }, [onClose]);\n\n  // Track the latest containerRef via a stable ref-of-refs so the listener\n  // never resubscribes when callers pass freshly-created ref wrappers across\n  // renders. Same pattern as `onCloseRef` above — without this the listener's\n  // effect would churn for any caller that doesn't memoize its refs.\n  const containerRefRef = useRef(containerRef);\n  useEffect(() => {\n    containerRefRef.current = containerRef;\n  }, [containerRef]);\n\n  const triggerRefRef = useRef(triggerRef);\n  useEffect(() => {\n    triggerRefRef.current = triggerRef;\n  }, [triggerRef]);\n\n  useEffect(() => {\n    if (!enabled) return;\n\n    // `popover:open` listener — gated on `closeOnPeerOpen`. Modals/trays opt\n    // out so a peer popover opening cannot bypass the dialog's\n    // `isDismissable` / `onClose` handling and call `state.close()` directly.\n    // Note: the EMIT side (lower in this hook) still fires regardless, so\n    // opening a modal still correctly dismisses peer popovers.\n    const offOpen = closeOnPeerOpen\n      ? on('popover:open', (data: PopoverOpenPayload) => {\n          if (data.menuId === menuId || !isOpenRef.current) return;\n          const container = containerRefRef.current?.current ?? null;\n          // Nested-popover guard: stay open when the opening peer's trigger is\n          // a LOGICAL descendant of our overlay. Direct DOM containment only\n          // covers the first level — for grand-child popovers the trigger lives\n          // in a sibling portal, so we walk the registered popover chain back\n          // up via each parent's trigger element. Without this, opening a\n          // third-level `SubMenuTrigger` would close every ancestor menu.\n          if (isLogicalDescendantOf(data.triggerEl, menuId, container)) return;\n          onCloseRef.current();\n        })\n      : null;\n\n    // `popover:dismiss-ancestor` is emitted by `Button` / `ItemButton` (and any\n    // consumer using `useDismissParentPopover`) after their `onPress` runs.\n    // Only popover-type overlays subscribe; modals/trays opt out via\n    // `dismissOnInnerButtonPress: false` so a Button inside a Dialog content\n    // does NOT auto-close the Dialog.\n    const offDismiss = dismissOnInnerButtonPress\n      ? on(\n          'popover:dismiss-ancestor',\n          (data: PopoverDismissAncestorPayload) => {\n            if (!isOpenRef.current) return;\n            const container = containerRefRef.current?.current;\n            const from = data?.from;\n            // Require both a container and an originating element so we can do\n            // the contains-check. Hosts without `containerRef` (e.g.\n            // `use-anchored-menu`, `use-context-menu`) are silently no-op.\n            if (!container || !from) return;\n            if (container.contains(from)) onCloseRef.current();\n          },\n        )\n      : null;\n\n    return () => {\n      offOpen?.();\n      offDismiss?.();\n    };\n  }, [on, menuId, enabled, dismissOnInnerButtonPress, closeOnPeerOpen]);\n\n  const wasOpenRef = useRef(false);\n  useEffect(() => {\n    if (!enabled) {\n      if (wasOpenRef.current) {\n        openPopovers.delete(menuId);\n      }\n      wasOpenRef.current = false;\n      return;\n    }\n    if (isOpen && !wasOpenRef.current) {\n      wasOpenRef.current = true;\n      // Register BEFORE emitting so peers' listeners (deferred via the\n      // bus's `setTimeout(0)`) can already see us in the registry when\n      // they walk the logical chain.\n      openPopovers.set(menuId, {\n        getContainerEl: () => containerRefRef.current?.current ?? null,\n        getTriggerEl: () => triggerRefRef.current?.current ?? null,\n      });\n      emit<PopoverOpenPayload>('popover:open', {\n        menuId,\n        triggerEl: triggerRefRef.current?.current ?? null,\n      });\n    } else if (!isOpen && wasOpenRef.current) {\n      wasOpenRef.current = false;\n      openPopovers.delete(menuId);\n    }\n  }, [isOpen, emit, menuId, enabled]);\n\n  // Final cleanup on unmount: covers the case where a host unmounts while\n  // still flagged open (e.g. a parent unmount tears down a child popover\n  // before its close transition runs).\n  useEffect(() => {\n    return () => {\n      openPopovers.delete(menuId);\n    };\n  }, [menuId]);\n}\n\n/**\n * Hook that returns a dispatcher to close the popover that contains a given\n * DOM element. Used by `Button` / `ItemButton` to implement the default\n * \"press inside a popover closes the popover\" behaviour. Custom (non-Cube)\n * interactive controls can call this directly:\n *\n * ```tsx\n * const dismiss = useDismissParentPopover();\n * <MyCustomPressable onPress={(e) => { doThing(); dismiss(e.currentTarget); }} />\n * ```\n *\n * The actual dismiss is dispatched through the EventBus, which defers via\n * `setTimeout(0)` — so the user's synchronous handler (and any React state\n * updates it triggers) flushes BEFORE the popover closes. This is critical\n * for the \"open a hoisted modal from a popover footer\" case: the modal\n * mounts first, then the popover closes.\n *\n * Only popover-type containers (those that pass `dismissOnInnerButtonPress`\n * as `true`, the default) react to the event. Modal/tray/fullscreen Dialog\n * containers explicitly opt out so a Button inside their content does not\n * auto-close them.\n *\n * When called outside an `EventBusProvider` (e.g. in unit tests that render\n * a Button without wrapping in `<Root>`), the returned function is a no-op —\n * the dismiss flow gracefully degrades rather than throwing.\n */\nexport function useDismissParentPopover() {\n  // Read context defensively: `Button` / `ItemButton` use this hook\n  // unconditionally, but tests (and standalone usages outside `<Root>`) may\n  // mount them without an `EventBusProvider`. A throw would crash every\n  // Button render in those cases.\n  const bus = useContext(EventBusContext);\n  const emit = bus?.emit;\n  return (from: Element | null) => {\n    if (!from || !emit) return;\n    emit<PopoverDismissAncestorPayload>('popover:dismiss-ancestor', { from });\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"usePopoverSync.js","names":["RefObject","useContext","useEffect","useEffectEvent","useRef","EventBusContext","useEventBus","UsePopoverSyncOptions","menuId","isOpen","onClose","enabled","triggerRef","HTMLElement","containerRef","dismissOnInnerButtonPress","closeOnPeerOpen","PopoverOpenPayload","triggerEl","Element","PopoverDismissAncestorPayload","from","PopoverRegistryEntry","getContainerEl","getTriggerEl","openPopovers","Map","findOwningPopover","target","entry","contains","isLogicalDescendantOf","ancestorMenuId","ancestorContainer","cur","visited","Set","owner","id","has","add","usePopoverSync","t0","$","_c","t1","t2","t3","undefined","emit","on","containerRefRef","t4","t5","current","triggerRefRef","t6","t7","t8","data","container","onPeerOpen","t9","data_0","container_0","onDismissAncestor","t10","offOpen","offDismiss","t11","wasOpenRef","t12","t13","delete","set","t14","t15","useDismissParentPopover","bus"],"sources":["../../../src/utils/react/usePopoverSync.ts"],"sourcesContent":["import {\n  RefObject,\n  useContext,\n  useEffect,\n  useEffectEvent,\n  useRef,\n} from 'react';\n\nimport { EventBusContext, useEventBus } from './useEventBus';\n\nexport interface UsePopoverSyncOptions {\n  /** Stable identifier for this popover instance (typically a generateRandomId() memo). */\n  menuId: string;\n  /** Current open state of this popover. */\n  isOpen: boolean;\n  /** Called when another popover opens while this one is open. */\n  onClose: () => void;\n  /**\n   * When `false`, this popover does not participate in the sync (no listening,\n   * no emitting). Useful for \"dummy\" triggers that proxy a real one (see\n   * `MenuTrigger`'s `isDummy`). Defaults to `true`.\n   */\n  enabled?: boolean;\n  /**\n   * Ref to the popover's trigger element. When provided, the element is\n   * included in the `popover:open` emit payload so peers can detect whether\n   * the new opener is nested inside their own overlay (and skip closing in\n   * that case). Optional — omitting it preserves the legacy \"always close on\n   * peer open\" behaviour.\n   */\n  triggerRef?: RefObject<HTMLElement | null>;\n  /**\n   * Ref to the overlay/container element that hosts this popover's content.\n   * When provided, the listener performs a DOM `contains()` check on incoming\n   * peer triggers: peers whose trigger lives inside this container are\n   * considered nested children and do NOT close us.\n   */\n  containerRef?: RefObject<HTMLElement | null>;\n  /**\n   * Whether this overlay closes when a Button/ItemButton inside its container\n   * is pressed. Defaults to `true` (popover semantics — popovers are transient\n   * surfaces and any action inside them should dismiss them). Set to `false`\n   * for modals/trays/fullscreen dialogs — buttons inside a Dialog should not\n   * auto-close it. Requires `containerRef` to be set; without it the listener\n   * has no way to determine whether the dispatching button is \"inside\" this\n   * overlay and is effectively a no-op.\n   */\n  dismissOnInnerButtonPress?: boolean;\n  /**\n   * Whether this overlay closes when a peer popover opens. Defaults to `true`\n   * (popover semantics — only one popover open at a time). Set to `false` for\n   * modals/trays/fullscreen dialogs so a peer popover opening cannot bypass\n   * the dialog's own `isDismissable` / `onClose` handling and yank it shut.\n   *\n   * The host still EMITS `popover:open` regardless of this flag, so opening a\n   * modal/tray correctly dismisses any peer popover that was open before.\n   */\n  closeOnPeerOpen?: boolean;\n}\n\ninterface PopoverOpenPayload {\n  menuId: string;\n  triggerEl: Element | null;\n}\n\ninterface PopoverDismissAncestorPayload {\n  /** The DOM node of the button that requested the dismiss. */\n  from: Element | null;\n}\n\ninterface PopoverRegistryEntry {\n  getContainerEl: () => Element | null;\n  getTriggerEl: () => Element | null;\n}\n\n/**\n * Module-level registry of currently open popovers. Lets us resolve the\n * LOGICAL parent of an arbitrary element across portal boundaries.\n *\n * Popover content is portaled to a shared root (`document.body` by default —\n * see `Overlay.tsx`), so a grandchild popover's trigger lives inside a\n * sibling portal rather than physically inside its grandparent's container.\n * A naive `container.contains(triggerEl)` check therefore misses the\n * relationship and closes the grandparent — the bug that surfaces with 3+\n * levels of `SubMenuTrigger` nesting.\n *\n * The registry stores closures over the host's refs so reads always see the\n * latest `.current` value without forcing a re-register per render.\n */\nconst openPopovers = new Map<string, PopoverRegistryEntry>();\n\n/**\n * Find the open popover whose container directly contains `target`. Returns\n * `null` for elements that live outside every registered popover (e.g. a\n * top-level trigger button rendered next to its overlay root).\n */\nfunction findOwningPopover(\n  target: Element | null,\n): [string, PopoverRegistryEntry] | null {\n  if (!target) return null;\n  for (const entry of openPopovers) {\n    if (entry[1].getContainerEl()?.contains(target)) {\n      return entry;\n    }\n  }\n  return null;\n}\n\n/**\n * Returns `true` when `target` is nested inside the overlay identified by\n * `ancestorMenuId` — either as a direct DOM descendant of `ancestorContainer`\n * or as a descendant of a chain of popovers whose triggers eventually land\n * inside it. Used by `popover:open` peers to avoid closing themselves when a\n * grand-child overlay opens through a portal.\n */\nfunction isLogicalDescendantOf(\n  target: Element | null,\n  ancestorMenuId: string,\n  ancestorContainer: Element | null,\n): boolean {\n  if (ancestorContainer && target && ancestorContainer.contains(target)) {\n    return true;\n  }\n  let cur: Element | null = target;\n  const visited = new Set<string>();\n  while (cur) {\n    const owner = findOwningPopover(cur);\n    if (!owner) return false;\n    const [id, entry] = owner;\n    if (visited.has(id)) return false;\n    visited.add(id);\n    if (id === ancestorMenuId) return true;\n    cur = entry.getTriggerEl();\n  }\n  return false;\n}\n\n/**\n * Coordinates the \"only one popover open at a time\" invariant via the EventBus.\n *\n * - When `isOpen` flips `false -> true`, emits `popover:open` once.\n * - While open, listens for peers' `popover:open` events and calls `onClose`.\n *\n * Implementation notes (ALL of these matter — losing any one re-introduces a\n * race that surfaces only under rapid trigger switching, which is hard to\n * reproduce in tests):\n *\n * 1. Effect Events read current `isOpen`, `onClose` and container data, so the\n *    subscription effect's dep array includes only resource configuration. This\n *    keeps the existing subscriptions across open/close transitions and\n *    avoids the unsubscribe-emit-resubscribe window where an emit can be\n *    delivered to a stale listener (or no listener).\n * 2. The emit fires only on the `false -> true` transition, gated by\n *    `wasOpenRef`. A re-render where `isOpen` is still `true` must NOT\n *    re-emit, otherwise it could re-trigger listeners on peers that just\n *    opened in the same render flush.\n * 3. The `enabled` flag short-circuits both effects symmetrically. When it\n *    flips off, `wasOpenRef` is reset so re-enabling later still emits if\n *    `isOpen` is true at that moment.\n */\nexport function usePopoverSync({\n  menuId,\n  isOpen,\n  onClose,\n  enabled = true,\n  triggerRef,\n  containerRef,\n  dismissOnInnerButtonPress = true,\n  closeOnPeerOpen = true,\n}: UsePopoverSyncOptions): void {\n  const { emit, on } = useEventBus();\n\n  // Track the latest containerRef via a stable ref-of-refs so the\n  // registry getters always see newly supplied ref wrappers. These getters\n  // are retained outside effects and cannot use Effect Events.\n  const containerRefRef = useRef(containerRef);\n  useEffect(() => {\n    containerRefRef.current = containerRef;\n  }, [containerRef]);\n\n  const triggerRefRef = useRef(triggerRef);\n  useEffect(() => {\n    triggerRefRef.current = triggerRef;\n  }, [triggerRef]);\n\n  const onPeerOpen = useEffectEvent((data: PopoverOpenPayload) => {\n    if (data.menuId === menuId || !isOpen) return;\n    const container = containerRef?.current ?? null;\n    // Logical containment follows registry links across sibling portals.\n    if (isLogicalDescendantOf(data.triggerEl, menuId, container)) return;\n    onClose();\n  });\n\n  const onDismissAncestor = useEffectEvent(\n    (data: PopoverDismissAncestorPayload) => {\n      if (!isOpen) return;\n      const container = containerRef?.current;\n      const from = data?.from;\n      if (!container || !from) return;\n      if (container.contains(from)) onClose();\n    },\n  );\n\n  useEffect(() => {\n    if (!enabled) return;\n\n    const offOpen = closeOnPeerOpen ? on('popover:open', onPeerOpen) : null;\n    const offDismiss = dismissOnInnerButtonPress\n      ? on('popover:dismiss-ancestor', onDismissAncestor)\n      : null;\n\n    return () => {\n      offOpen?.();\n      offDismiss?.();\n    };\n  }, [on, menuId, enabled, dismissOnInnerButtonPress, closeOnPeerOpen]);\n\n  const wasOpenRef = useRef(false);\n  useEffect(() => {\n    if (!enabled) {\n      if (wasOpenRef.current) {\n        openPopovers.delete(menuId);\n      }\n      wasOpenRef.current = false;\n      return;\n    }\n    if (isOpen && !wasOpenRef.current) {\n      wasOpenRef.current = true;\n      // Register BEFORE emitting so peers' listeners (deferred via the\n      // bus's `setTimeout(0)`) can already see us in the registry when\n      // they walk the logical chain.\n      openPopovers.set(menuId, {\n        getContainerEl: () => containerRefRef.current?.current ?? null,\n        getTriggerEl: () => triggerRefRef.current?.current ?? null,\n      });\n      emit<PopoverOpenPayload>('popover:open', {\n        menuId,\n        triggerEl: triggerRefRef.current?.current ?? null,\n      });\n    } else if (!isOpen && wasOpenRef.current) {\n      wasOpenRef.current = false;\n      openPopovers.delete(menuId);\n    }\n  }, [isOpen, emit, menuId, enabled]);\n\n  // Final cleanup on unmount: covers the case where a host unmounts while\n  // still flagged open (e.g. a parent unmount tears down a child popover\n  // before its close transition runs).\n  useEffect(() => {\n    return () => {\n      openPopovers.delete(menuId);\n    };\n  }, [menuId]);\n}\n\n/**\n * Hook that returns a dispatcher to close the popover that contains a given\n * DOM element. Used by `Button` / `ItemButton` to implement the default\n * \"press inside a popover closes the popover\" behaviour. Custom (non-Cube)\n * interactive controls can call this directly:\n *\n * ```tsx\n * const dismiss = useDismissParentPopover();\n * <MyCustomPressable onPress={(e) => { doThing(); dismiss(e.currentTarget); }} />\n * ```\n *\n * The actual dismiss is dispatched through the EventBus, which defers via\n * `setTimeout(0)` — so the user's synchronous handler (and any React state\n * updates it triggers) flushes BEFORE the popover closes. This is critical\n * for the \"open a hoisted modal from a popover footer\" case: the modal\n * mounts first, then the popover closes.\n *\n * Only popover-type containers (those that pass `dismissOnInnerButtonPress`\n * as `true`, the default) react to the event. Modal/tray/fullscreen Dialog\n * containers explicitly opt out so a Button inside their content does not\n * auto-close them.\n *\n * When called outside an `EventBusProvider` (e.g. in unit tests that render\n * a Button without wrapping in `<Root>`), the returned function is a no-op —\n * the dismiss flow gracefully degrades rather than throwing.\n */\nexport function useDismissParentPopover() {\n  // Read context defensively: `Button` / `ItemButton` use this hook\n  // unconditionally, but tests (and standalone usages outside `<Root>`) may\n  // mount them without an `EventBusProvider`. A throw would crash every\n  // Button render in those cases.\n  const bus = useContext(EventBusContext);\n  const emit = bus?.emit;\n  return (from: Element | null) => {\n    if (!from || !emit) return;\n    emit<PopoverDismissAncestorPayload>('popover:dismiss-ancestor', { from });\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAyFA,MAAMyB,+BAAe,IAAIC,KAAmC;;;;;;AAO5D,SAASC,kBACPC,QACuC;AACvC,KAAI,CAACA,OAAQ,QAAO;AACpB,MAAK,MAAMC,SAASJ,aAClB,KAAII,MAAM,GAAGN,gBAAgB,EAAEO,SAASF,OAAO,CAC7C,QAAOC;AAGX,QAAO;;;;;;;;;AAUT,SAASE,sBACPH,QACAI,gBACAC,mBACS;AACT,KAAIA,qBAAqBL,UAAUK,kBAAkBH,SAASF,OAAO,CACnE,QAAO;CAET,IAAIM,MAAsBN;CAC1B,MAAMO,0BAAU,IAAIC,KAAa;AACjC,QAAOF,KAAK;EACV,MAAMG,QAAQV,kBAAkBO,IAAI;AACpC,MAAI,CAACG,MAAO,QAAO;EACnB,MAAM,CAACC,IAAIT,SAASQ;AACpB,MAAIF,QAAQI,IAAID,GAAG,CAAE,QAAO;AAC5BH,UAAQK,IAAIF,GAAG;AACf,MAAIA,OAAON,eAAgB,QAAO;AAClCE,QAAML,MAAML,cAAc;;AAE5B,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;AA0BT,SAAOiB,eAAAC,IAAA;CAAA,MAAAC,IAAAC,EAAA,GAAA;CAAwB,MAAA,EAAApC,QAAAC,QAAAC,SAAAC,SAAAkC,IAAAjC,YAAAE,cAAAC,2BAAA+B,IAAA9B,iBAAA+B,OAAAL;CAI7B,MAAA/B,UAAAkC,OAAAG,SAAA,OAAAH;CAGA,MAAA9B,4BAAA+B,OAAAE,SAAA,OAAAF;CACA,MAAA9B,kBAAA+B,OAAAC,SAAA,OAAAD;CAEA,MAAA,EAAAE,MAAAC,OAAqB5C,aAAa;CAKlC,MAAA6C,kBAAwB/C,OAAOU,aAAa;CAAC,IAAAsC;CAAA,IAAAC;AAAA,KAAAV,EAAA,OAAA7B,cAAA;AACnCsC,aAAA;AACRD,mBAAeG,UAAWxC;;AACzBuC,OAAA,CAACvC,aAAa;AAAA6B,IAAA,KAAA7B;AAAA6B,IAAA,KAAAS;AAAAT,IAAA,KAAAU;QAAA;AAAAD,OAAAT,EAAA;AAAAU,OAAAV,EAAA;;AAFjBzC,WAAUkD,IAEPC,GAAe;CAElB,MAAAE,gBAAsBnD,OAAOQ,WAAW;CAAC,IAAA4C;CAAA,IAAAC;AAAA,KAAAd,EAAA,OAAA/B,YAAA;AAC/B4C,aAAA;AACRD,iBAAaD,UAAW1C;;AACvB6C,OAAA,CAAC7C,WAAW;AAAA+B,IAAA,KAAA/B;AAAA+B,IAAA,KAAAa;AAAAb,IAAA,KAAAc;QAAA;AAAAD,OAAAb,EAAA;AAAAc,OAAAd,EAAA;;AAFfzC,WAAUsD,IAEPC,GAAa;CAAA,IAAAC;AAAA,KAAAf,EAAA,OAAA7B,gBAAA6B,EAAA,OAAAlC,UAAAkC,EAAA,OAAAnC,UAAAmC,EAAA,OAAAjC,SAAA;AAEkBgD,QAAAC,SAAA;AAChC,OAAIA,KAAInD,WAAYA,UAAhB,CAA2BC,OAAM;GACrC,MAAAmD,YAAkB9C,cAAYwC,WAAZ;AAElB,OAAIvB,sBAAsB4B,KAAIzC,WAAYV,QAAQoD,UAAU,CAAA;AAC5DlD,YAAS;;AACViC,IAAA,KAAA7B;AAAA6B,IAAA,KAAAlC;AAAAkC,IAAA,KAAAnC;AAAAmC,IAAA,KAAAjC;AAAAiC,IAAA,MAAAe;OAAAA,MAAAf,EAAA;CAND,MAAAkB,aAAmB1D,eAAeuD,GAMhC;CAAC,IAAAI;AAAA,KAAAnB,EAAA,QAAA7B,gBAAA6B,EAAA,QAAAlC,UAAAkC,EAAA,QAAAjC,SAAA;AAGDoD,QAAAC,WAAA;AACE,OAAI,CAACtD,OAAM;GACX,MAAAuD,cAAkBlD,cAAYwC;GAC9B,MAAAjC,OAAasC,QAAItC;AACjB,OAAI,CAACuC,eAAD,CAAevC,KAAI;AACvB,OAAIuC,YAAS9B,SAAUT,KAAK,CAAEX,UAAS;;AACxCiC,IAAA,MAAA7B;AAAA6B,IAAA,MAAAlC;AAAAkC,IAAA,MAAAjC;AAAAiC,IAAA,MAAAmB;OAAAA,MAAAnB,EAAA;CAPH,MAAAsB,oBAA0B9D,eACxB2D,GAOD;CAAC,IAAAI;AAAA,KAAAvB,EAAA,QAAA3B,mBAAA2B,EAAA,QAAA5B,6BAAA4B,EAAA,QAAAhC,WAAAgC,EAAA,QAAAO,MAAAP,EAAA,QAAAsB,qBAAAtB,EAAA,QAAAkB,YAAA;AAEQK,cAAA;AACR,OAAI,CAACvD,QAAO;GAEZ,MAAAwD,UAAgBnD,kBAAkBkC,GAAG,gBAAgBW,WAAkB,GAAvD;GAChB,MAAAO,aAAmBrD,4BACfmC,GAAG,4BAA4Be,kBAC3B,GAFW;AAEV,gBAEF;AACLE,eAAW;AACXC,kBAAc;;;AAEjBzB,IAAA,MAAA3B;AAAA2B,IAAA,MAAA5B;AAAA4B,IAAA,MAAAhC;AAAAgC,IAAA,MAAAO;AAAAP,IAAA,MAAAsB;AAAAtB,IAAA,MAAAkB;AAAAlB,IAAA,MAAAuB;OAAAA,OAAAvB,EAAA;CAAA,IAAA0B;AAAA,KAAA1B,EAAA,QAAA3B,mBAAA2B,EAAA,QAAA5B,6BAAA4B,EAAA,QAAAhC,WAAAgC,EAAA,QAAAnC,UAAAmC,EAAA,QAAAO,IAAA;AAAEmB,QAAA;GAACnB;GAAI1C;GAAQG;GAASI;GAA2BC;GAAgB;AAAA2B,IAAA,MAAA3B;AAAA2B,IAAA,MAAA5B;AAAA4B,IAAA,MAAAhC;AAAAgC,IAAA,MAAAnC;AAAAmC,IAAA,MAAAO;AAAAP,IAAA,MAAA0B;OAAAA,OAAA1B,EAAA;AAZpEzC,WAAUgE,KAYPG,IAAkE;CAErE,MAAAC,aAAmBlE,OAAO,MAAM;CAAC,IAAAmE;CAAA,IAAAC;AAAA,KAAA7B,EAAA,QAAAM,QAAAN,EAAA,QAAAhC,WAAAgC,EAAA,QAAAlC,UAAAkC,EAAA,QAAAnC,QAAA;AACvB+D,cAAA;AACR,OAAI,CAAC5D,SAAO;AACV,QAAI2D,WAAUhB,QACZ7B,cAAYgD,OAAQjE,OAAO;AAE7B8D,eAAUhB,UAAW;AAAH;;AAGpB,OAAI7C,UAAA,CAAW6D,WAAUhB,SAAQ;AAC/BgB,eAAUhB,UAAW;AAIrB7B,iBAAYiD,IAAKlE,QAAQ;KAAAe,sBACD4B,gBAAeG,SAAiBA,WAAhC;KAAwC9B,oBAC1C+B,cAAaD,SAAiBA,WAA9B;KACrB,CAAC;AACFL,SAAyB,gBAAgB;KAAAzC;KAAAU,WAE5BqC,cAAaD,SAAiBA,WAA9B;KACZ,CAAC;cACO,CAAC7C,UAAU6D,WAAUhB,SAAQ;AACtCgB,eAAUhB,UAAW;AACrB7B,iBAAYgD,OAAQjE,OAAO;;;AAE5BgE,QAAA;GAAC/D;GAAQwC;GAAMzC;GAAQG;GAAQ;AAAAgC,IAAA,MAAAM;AAAAN,IAAA,MAAAhC;AAAAgC,IAAA,MAAAlC;AAAAkC,IAAA,MAAAnC;AAAAmC,IAAA,MAAA4B;AAAA5B,IAAA,MAAA6B;QAAA;AAAAD,QAAA5B,EAAA;AAAA6B,QAAA7B,EAAA;;AAzBlCzC,WAAUqE,KAyBPC,IAAgC;CAAA,IAAAG;CAAA,IAAAC;AAAA,KAAAjC,EAAA,QAAAnC,QAAA;AAKzBmE,oBACD;AACLlD,gBAAYgD,OAAQjE,OAAO;;AAE5BoE,QAAA,CAACpE,OAAO;AAAAmC,IAAA,MAAAnC;AAAAmC,IAAA,MAAAgC;AAAAhC,IAAA,MAAAiC;QAAA;AAAAD,QAAAhC,EAAA;AAAAiC,QAAAjC,EAAA;;AAJXzC,WAAUyE,KAIPC,IAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6Bd,SAAOC,0BAAA;CAAA,MAAAlC,IAAAC,EAAA,EAAA;CAML,MAAAK,OADYhD,WAAWI,gBAAgB,EACvB4C;CAAO,IAAAP;AAAA,KAAAC,EAAA,OAAAM,MAAA;AAChBP,QAAArB,SAAA;AACL,OAAI,CAACA,QAAD,CAAU4B,KAAI;AAClBA,QAAoC,4BAA4B,EAAA5B,MAAQ,CAAC;;AAC1EsB,IAAA,KAAAM;AAAAN,IAAA,KAAAD;OAAAA,MAAAC,EAAA;AAAA,QAHMD"}

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.190.8 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.191.0 | Cube Dev Team */
 //#region src/utils/react/useQaProps.ts
 /**
 * Processes QA props.

package/dist/utils/react/useScheme.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.190.8 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.191.0 | Cube Dev Team */
 import { useSyncExternalStore } from "react";
 
 //#region src/utils/react/useScheme.ts

package/dist/utils/react/useViewportSize.js

@@ -1,5 +1,5 @@
-/** @license MIT | @cube-dev/ui-kit v0.190.8 | Cube Dev Team */
-import { c } from "react-compiler-runtime";
+/** @license MIT | @cube-dev/ui-kit v0.191.0 | Cube Dev Team */
+import { c } from "react/compiler-runtime";
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useViewportSize.ts

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.190.8 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.191.0 | Cube Dev Team */
 import { Fragment, isValidElement } from "react";
 
 //#region src/utils/react/wrapNodeIfPlain.ts

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.190.8 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.191.0 | Cube Dev Team */
 //#region src/utils/selection.ts
 /**
 * Deduplicate/toggle keys in a selection: if a key appears twice it is

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.190.8 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.191.0 | Cube Dev Team */
 import { isSelector, mergeStyles } from "@tenphi/tasty";
 
 //#region src/utils/styles.ts

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.190.8 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.191.0 | Cube Dev Team */
 //#region src/utils/tree.ts
 function toFlatTree(tree, includingFolders) {
 	return tree.reduce((result, node) => {

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.190.8 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.191.0 | Cube Dev Team */
 import { isDevEnvOrTest } from "./is-dev-env.js";
 
 //#region src/utils/warnings.ts

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.190.8 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.191.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.190.8";
+const VERSION = "0.191.0";
 const TASTY_VERSION = "3.9.9";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/CreateComponent.md

@@ -282,7 +282,7 @@ This demonstrates a basic component with:
 - Clean, minimal implementation
 
 ```tsx
-import { forwardRef } from 'react';
+import type { Ref } from 'react';
 import {
   AllBaseProps,
   CONTAINER_STYLES,
@@ -299,10 +299,12 @@ const BlockElement = tasty({
 });
 
 export interface CubeBlockProps
-  extends Omit<AllBaseProps, keyof ContainerStyleProps | 'as'>,
-    ContainerStyleProps {}
+  extends Omit<AllBaseProps, keyof ContainerStyleProps | 'as' | 'ref'>,
+    ContainerStyleProps {
+  ref?: Ref<HTMLDivElement>;
+}
 
-export const Block = forwardRef(function Block(props: CubeBlockProps, ref) {
+export function Block({ ref, ...props }: CubeBlockProps) {
   const styles = extractStyles(props, CONTAINER_STYLES);
 
   return (
@@ -312,7 +314,7 @@ export const Block = forwardRef(function Block(props: CubeBlockProps, ref) {
       styles={styles}
     />
   );
-});
+}
 ```
 
 ### Example 2: Action Component (Advanced)
@@ -325,8 +327,8 @@ This demonstrates advanced features:
 - Custom behavior logic
 
 ```tsx
-import { FocusableRef } from '@react-types/shared';
-import { forwardRef } from 'react';
+import type { Ref } from 'react';
+import { useObjectRef } from '@react-aria/utils';
 import { AriaButtonProps, useButton, useHover } from 'react-aria';
 import {
   AllBaseProps,
@@ -342,7 +344,7 @@ import {
 } from '@tenphi/tasty';
 
 export interface CubeActionProps<T extends TagName = 'button'>
-  extends Omit<AllBaseProps<T>, 'htmlType'>,
+  extends Omit<AllBaseProps<T>, 'htmlType' | 'ref'>,
     BaseStyleProps,
     ContainerStyleProps,
     TextStyleProps,
@@ -350,6 +352,7 @@ export interface CubeActionProps<T extends TagName = 'button'>
   to?: string;
   label?: string;
   htmlType?: 'button' | 'submit' | 'reset';
+  ref?: Ref<HTMLElement>;
 }
 
 const DEFAULT_ACTION_STYLES: Styles = {
@@ -371,7 +374,7 @@ const ActionElement = tasty({
 
 const STYLE_PROPS = [...CONTAINER_STYLES, ...TEXT_STYLES];
 
-export const Action = forwardRef(function Action(
+export function Action(
   {
     to,
     as = 'button',
@@ -381,11 +384,11 @@ export const Action = forwardRef(function Action(
     mods,
     onPress,
     isDisabled,
+    ref,
     ...props
   }: CubeActionProps,
-  ref: FocusableRef<HTMLElement>,
 ) {
-  const domRef = useRef();
+  const domRef = useObjectRef(ref);
   const { buttonProps, isPressed } = useButton(
     {
       'aria-label': label,
@@ -417,7 +420,7 @@ export const Action = forwardRef(function Action(
       styles={styles}
     />
   );
-});
+}
 ```
 
 ## Form Integration
@@ -446,18 +449,28 @@ For input components that need to integrate with forms, see the [Field documenta
 
 7. **Keep it simple when appropriate**: Not every component needs all features - use what makes sense for your use case
 
-8. **Use named React imports**: Import `useState`, `useRef`, `forwardRef` etc. directly from `'react'` instead of using `React.useState(...)`.
+8. **Use named React imports**: Import `useState`, `useRef`, `useEffectEvent` etc. directly from `'react'` instead of using `React.useState(...)`.
 
-   **Skip `useMemo` and `useCallback` for performance.** React Compiler memoizes compiled components and hooks at build time, so derived values, `mods` objects and handlers are plain expressions. Keep a manual memo where identity is part of the contract: callback refs, effect dependencies, `useSyncExternalStore` subscriptions, per-mount values, context provider values and imperative APIs. Tests run uncompiled source, and known compiler bailouts retain their existing memos. See [React Compiler](https://github.com/cube-js/cube-ui-kit/blob/main/AGENTS.md#react-compiler-skip-manual-memoization).
+   **Use plain derived values and handlers.** Follow the [React Compiler rules](https://github.com/cube-js/cube-ui-kit/blob/main/docs/rules/react-compiler.md). Manual memoization controls identity only when required; it does not own a persistent per-mount lifetime.
 
-9. **Use `useEvent` for stable callbacks**: When a callback doesn't need to trigger re-renders, prefer `useEvent` from `src/_internal/hooks/use-event` for a stable identity that always calls the latest implementation:
+9. **Choose callbacks by ownership**: Ordinary handlers are plain functions. Local effect-owned notifications use the canonical named `useEffectEvent` import. Keep resource configuration reactive and exclude Effect Events from dependencies. Retain internal `useEvent` only when a previously stored reference must keep its identity and call the latest committed implementation.
 
 ```tsx
-import { useEvent } from '../_internal/hooks/use-event';
+import { useEffect, useEffectEvent } from 'react';
 
-const handleClick = useEvent((e) => {
-  // always has latest closure, but stable identity
-});
+function Connection({ roomId, connect, notify, theme }) {
+  const handleClick = () => notify(theme);
+  const onConnected = useEffectEvent(() => notify(theme));
+
+  useEffect(() => {
+    const connection = connect(roomId);
+    connection.on('connected', onConnected);
+    connection.connect();
+    return () => connection.disconnect();
+  }, [connect, roomId]);
+
+  return <button onClick={handleClick}>Notify</button>;
+}
 ```
 
 10. **Use `variants` for theming, not sizing**: The `variants` option in `tasty()` defines mutually exclusive visual variations (e.g. `default`, `danger`, `outline`). CSS is only generated for variants actually rendered at runtime. Use modifiers for dimensions like `size`.
@@ -473,7 +486,7 @@ When creating a new component, consider:
 - [ ] Sub-element definitions for targeted styling
 - [ ] React Aria integration for accessibility
 - [ ] TypeScript interfaces following naming conventions
-- [ ] forwardRef for ref passing
+- [ ] Ref prop with the exposed DOM/imperative type and correct target; preserve generic inference and callback cleanup
 - [ ] Default styles and theme support
 - [ ] Documentation following UI Kit standards
 

package/docs/Usage.md

@@ -13,7 +13,7 @@ For styling engine internals see the [Tasty documentation](./tasty/usage.md). Ta
 
 ## React Compiler
 
-UI Kit ships components optimized with React Compiler and supports React 18 and 19. Your application does not need to enable Compiler to use this build. Adoption is incremental: functions with known compatibility diagnostics remain unoptimized, and the legacy form's mutable render paths are explicitly excluded.
+UI Kit ships components optimized with React Compiler and requires React and React DOM 19.3 or newer. Your application does not need to enable Compiler to use this build. Adoption is incremental: functions with known compatibility diagnostics remain unoptimized, and the legacy form's mutable render paths are explicitly excluded.
 
 Compiling UI Kit does not make mutable legacy form reads in your application reactive. When enabling Compiler in an application, migrate those consumers to the modern Form subscriptions (`Form.useValue`, `Form.useSelector`, or `Form.Subscribe`) or keep the affected consumer components uncompiled with `"use no memo"`. Forms without an explicit instance still use the legacy implementation.
 

package/docs/components/actions/CommandMenu.md

@@ -453,5 +453,5 @@ The CommandMenu supports enhanced search capabilities:
 ### Browser Support
 
 - Modern browsers with ES2018+ support
-- Requires React 18+ for concurrent features
+- Requires React and React DOM 19.3 or newer
 - Uses React Aria for cross-browser accessibility

package/docs/components/form/Form.md

@@ -160,7 +160,7 @@ A `Form` placed directly in a `Dialog`, wrapping its `Content` and `Footer`, lay
 
 ## React Compiler
 
-The modern controller, subscriptions, input binding, and dialog workflows are tested with React Compiler on React 18 and 19. The published library remains uncompiled. Consumer render code must use `Form.useValue`, `Form.useFieldState`, or selectors to subscribe; imperative getters do not subscribe. This does not make legacy mutable instance reads Compiler-safe.
+The modern controller, subscriptions, input binding, and dialog workflows are tested with React Compiler on React 19.3. The published library is compiled using React’s native compiler runtime; consumers do not need to enable Compiler. Consumer render code must use `Form.useValue`, `Form.useFieldState`, or selectors to subscribe; imperative getters do not subscribe. This does not make legacy mutable instance reads Compiler-safe.
 
 ## Accessibility
 

package/docs/modern-form-migration.md

@@ -2,7 +2,7 @@
 
 Modern Form is opt-in per form. Existing `Form.useForm()` calls, roots without a controller, and legacy wrappers continue to use the legacy engine. Start with a leaf form whose defaults, conditional fields, and submission payload are understood. Do not swap the backend of a mounted root: choose one component at a migration boundary and remount when changing that choice.
 
-The [compiled consumer examples](https://github.com/cube-js/cube-ui-kit/blob/main/typecheck/consumer/modern-form-examples.tsx) cover creation with a colocated selector, narrow descendant subscriptions, conditional fields, async defaults, a custom control, and cancellable validation. `pnpm build && pnpm test:types:consumer` checks those examples against the declarations consumers receive. The published library is compiled for React 18 and 19; CI checks adapters and packaged consumers both with and without React Compiler. See [the compiler guide](../scripts/compiler/README.md).
+The [compiled consumer examples](https://github.com/cube-js/cube-ui-kit/blob/main/typecheck/consumer/modern-form-examples.tsx) cover creation with a colocated selector, narrow descendant subscriptions, conditional fields, async defaults, a custom control, and cancellable validation. `pnpm build && pnpm test:types:consumer` checks those examples against the declarations consumers receive. The published library is compiled for React 19.3 or newer; CI checks adapters and packaged consumers both with and without React Compiler. See [the compiler guide](../scripts/compiler/README.md).
 
 ## Choose the backend explicitly
 
@@ -60,6 +60,6 @@ The [Modern Form guide](modern-form-guide.md) is the reference for implementing
 5. Adapt validators' success values and cancellation. Declare external captured inputs in `deps` and sibling form paths in `dependsOn`.
 6. Decide whether hidden fields are retained and whether submission uses active or all values. Verify the actual payload with conditional sections both visible and hidden.
 7. Test required/async errors, double submit, server failure, reset, unmount during requests, keyboard focus, and navigation guards. Modern Submit stays enabled after validation errors; pass `disableOnInvalid` to retain the legacy disabled-button behavior. Verify this visible change with QA. Confirm unaffected fields and the creator do not rerender on each keystroke.
-8. Run source and built-consumer type checks, the frozen legacy contract suite, React 18/19 compiler checks, and relevant browser checks. Review visual changes before merging.
+8. Run source and built-consumer type checks, the frozen legacy contract suite, React 19 source/compiled checks, and relevant browser checks. Review visual changes before merging.
 
 To revert a migrated form, render the preserved legacy component again and restore its legacy defaults/callback/validator contracts. Remount the boundary and deliberately transfer serializable draft values if needed. Do not cast the modern controller to a legacy instance or toggle hook implementations in place.

package/docs/modern-form-typecheck.md

@@ -8,7 +8,7 @@ The roots are the existing `NarrowForm`, `SAMLOptionsForm`, `LDAPOptionsForm`, `
 
 Build UI Kit with its pinned Node 24 environment, then run `node scripts/benchmark-cloud-form-types.mjs /path/to/cloud 3` under Cloud's Node 22.14. The script writes configs, candidate declaration copies, logs, and a JSON report to the OS temporary directory. It never installs dependencies, changes Cloud files, or writes Cloud's incremental cache. The script alternates installed/candidate order across three pairs and checks that diagnostics are stable across repeats.
 
-Both variants resolve through Cloud's installed dependency graph, including React 19.1.1, its React types, i18next 26.3.2, and Tasty 3.7.0. The candidate declaration copy has a temporary dependency-directory symlink outside the Cloud checkout. Reading UI Kit's `dist` in place would resolve its own React/i18next copies and introduce unrelated identity errors. This controlled comparison measures declaration compatibility and cost; it does not simulate a complete dependency installation or certify a Cloud release with newer Tasty. UI Kit's own source/consumer, React 18/19, and compiled adapter gates use its actual Tasty 3.9.2 dependency.
+Both variants resolve through Cloud's installed dependency graph, including React 19.1.1, its React types, i18next 26.3.2, and Tasty 3.7.0. The candidate declaration copy has a temporary dependency-directory symlink outside the Cloud checkout. Reading UI Kit's `dist` in place would resolve its own React/i18next copies and introduce unrelated identity errors. This controlled comparison measures declaration compatibility and cost; it does not simulate a complete dependency installation or certify a Cloud release with newer Tasty. At the time of this audit, UI Kit's source/consumer, React 18/19, and compiled adapter gates used Tasty 3.9.2. This is historical typecheck evidence; see [current compiler guidance](../scripts/compiler/README.md) for supported React versions.
 
 ## Results