@cube-dev/ui-kit 0.141.0 → 0.142.0

package/dist/utils/react/usePopoverSync.js

@@ -1,9 +1,56 @@
-/** @license MIT | @cube-dev/ui-kit v0.141.0 | Cube Dev Team */
-import { useEventBus } from "./useEventBus.js";
-import { useEffect, useRef } from "react";
+/** @license MIT | @cube-dev/ui-kit v0.142.0 | Cube Dev Team */
+import { EventBusContext, useEventBus } from "./useEventBus.js";
+import { useCallback, useContext, useEffect, useRef } from "react";
 
 //#region src/utils/react/usePopoverSync.ts
 /**
+* Module-level registry of currently open popovers. Lets us resolve the
+* LOGICAL parent of an arbitrary element across portal boundaries.
+*
+* Popover content is portaled to a shared root (`document.body` by default —
+* see `Overlay.tsx`), so a grandchild popover's trigger lives inside a
+* sibling portal rather than physically inside its grandparent's container.
+* A naive `container.contains(triggerEl)` check therefore misses the
+* relationship and closes the grandparent — the bug that surfaces with 3+
+* levels of `SubMenuTrigger` nesting.
+*
+* The registry stores closures over the host's refs so reads always see the
+* latest `.current` value without forcing a re-register per render.
+*/
+const openPopovers = /* @__PURE__ */ new Map();
+/**
+* Find the open popover whose container directly contains `target`. Returns
+* `null` for elements that live outside every registered popover (e.g. a
+* top-level trigger button rendered next to its overlay root).
+*/
+function findOwningPopover(target) {
+	if (!target) return null;
+	for (const entry of openPopovers) if (entry[1].getContainerEl()?.contains(target)) return entry;
+	return null;
+}
+/**
+* Returns `true` when `target` is nested inside the overlay identified by
+* `ancestorMenuId` — either as a direct DOM descendant of `ancestorContainer`
+* or as a descendant of a chain of popovers whose triggers eventually land
+* inside it. Used by `popover:open` peers to avoid closing themselves when a
+* grand-child overlay opens through a portal.
+*/
+function isLogicalDescendantOf(target, ancestorMenuId, ancestorContainer) {
+	if (ancestorContainer && target && ancestorContainer.contains(target)) return true;
+	let cur = target;
+	const visited = /* @__PURE__ */ new Set();
+	while (cur) {
+		const owner = findOwningPopover(cur);
+		if (!owner) return false;
+		const [id, entry] = owner;
+		if (visited.has(id)) return false;
+		visited.add(id);
+		if (id === ancestorMenuId) return true;
+		cur = entry.getTriggerEl();
+	}
+	return false;
+}
+/**
 * Coordinates the "only one popover open at a time" invariant via the EventBus.
 *
 * - When `isOpen` flips `false -> true`, emits `popover:open` once.
@@ -26,7 +73,7 @@ import { useEffect, useRef } from "react";
 *    flips off, `wasOpenRef` is reset so re-enabling later still emits if
 *    `isOpen` is true at that moment.
 */
-function usePopoverSync({ menuId, isOpen, onClose, enabled = true }) {
+function usePopoverSync({ menuId, isOpen, onClose, enabled = true, triggerRef, containerRef, dismissOnInnerButtonPress = true, closeOnPeerOpen = true }) {
 	const { emit, on } = useEventBus();
 	const isOpenRef = useRef(isOpen);
 	useEffect(() => {
@@ -36,34 +83,107 @@ function usePopoverSync({ menuId, isOpen, onClose, enabled = true }) {
 	useEffect(() => {
 		onCloseRef.current = onClose;
 	}, [onClose]);
+	const containerRefRef = useRef(containerRef);
+	useEffect(() => {
+		containerRefRef.current = containerRef;
+	}, [containerRef]);
+	const triggerRefRef = useRef(triggerRef);
+	useEffect(() => {
+		triggerRefRef.current = triggerRef;
+	}, [triggerRef]);
 	useEffect(() => {
 		if (!enabled) return;
-		return on("popover:open", (data) => {
-			if (data.menuId !== menuId && isOpenRef.current) onCloseRef.current();
-		});
+		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) => {
+			if (!isOpenRef.current) return;
+			const container = containerRefRef.current?.current;
+			const from = data?.from;
+			if (!container || !from) return;
+			if (container.contains(from)) onCloseRef.current();
+		}) : null;
+		return () => {
+			offOpen?.();
+			offDismiss?.();
+		};
 	}, [
 		on,
 		menuId,
-		enabled
+		enabled,
+		dismissOnInnerButtonPress,
+		closeOnPeerOpen
 	]);
 	const wasOpenRef = useRef(false);
 	useEffect(() => {
 		if (!enabled) {
+			if (wasOpenRef.current) openPopovers.delete(menuId);
 			wasOpenRef.current = false;
 			return;
 		}
 		if (isOpen && !wasOpenRef.current) {
 			wasOpenRef.current = true;
-			emit("popover:open", { menuId });
-		} else if (!isOpen) wasOpenRef.current = false;
+			openPopovers.set(menuId, {
+				getContainerEl: () => containerRefRef.current?.current ?? null,
+				getTriggerEl: () => triggerRefRef.current?.current ?? null
+			});
+			emit("popover:open", {
+				menuId,
+				triggerEl: triggerRefRef.current?.current ?? null
+			});
+		} else if (!isOpen && wasOpenRef.current) {
+			wasOpenRef.current = false;
+			openPopovers.delete(menuId);
+		}
 	}, [
 		isOpen,
 		emit,
 		menuId,
 		enabled
 	]);
+	useEffect(() => {
+		return () => {
+			openPopovers.delete(menuId);
+		};
+	}, [menuId]);
+}
+/**
+* Hook that returns a dispatcher to close the popover that contains a given
+* DOM element. Used by `Button` / `ItemButton` to implement the default
+* "press inside a popover closes the popover" behaviour. Custom (non-Cube)
+* interactive controls can call this directly:
+*
+* ```tsx
+* const dismiss = useDismissParentPopover();
+* <MyCustomPressable onPress={(e) => { doThing(); dismiss(e.currentTarget); }} />
+* ```
+*
+* The actual dismiss is dispatched through the EventBus, which defers via
+* `setTimeout(0)` — so the user's synchronous handler (and any React state
+* updates it triggers) flushes BEFORE the popover closes. This is critical
+* for the "open a hoisted modal from a popover footer" case: the modal
+* mounts first, then the popover closes.
+*
+* Only popover-type containers (those that pass `dismissOnInnerButtonPress`
+* as `true`, the default) react to the event. Modal/tray/fullscreen Dialog
+* containers explicitly opt out so a Button inside their content does not
+* auto-close them.
+*
+* When called outside an `EventBusProvider` (e.g. in unit tests that render
+* a Button without wrapping in `<Root>`), the returned function is a no-op —
+* the dismiss flow gracefully degrades rather than throwing.
+*/
+function useDismissParentPopover() {
+	const emit = useContext(EventBusContext)?.emit;
+	return useCallback((from) => {
+		if (!from || !emit) return;
+		emit("popover:dismiss-ancestor", { from });
+	}, [emit]);
 }
 
 //#endregion
-export { usePopoverSync };
+export { useDismissParentPopover, usePopoverSync };
 //# sourceMappingURL=usePopoverSync.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"usePopoverSync.js","names":[],"sources":["../../../src/utils/react/usePopoverSync.ts"],"sourcesContent":["import { useEffect, useRef } from 'react';\n\nimport { 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\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}: 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  useEffect(() => {\n    if (!enabled) return;\n    return on('popover:open', (data: { menuId: string }) => {\n      if (data.menuId !== menuId && isOpenRef.current) {\n        onCloseRef.current();\n      }\n    });\n  }, [on, menuId, enabled]);\n\n  const wasOpenRef = useRef(false);\n  useEffect(() => {\n    if (!enabled) {\n      wasOpenRef.current = false;\n      return;\n    }\n    if (isOpen && !wasOpenRef.current) {\n      wasOpenRef.current = true;\n      emit('popover:open', { menuId });\n    } else if (!isOpen) {\n      wasOpenRef.current = false;\n    }\n  }, [isOpen, emit, menuId, enabled]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,SAAgB,eAAe,EAC7B,QACA,QACA,SACA,UAAU,QACoB;CAC9B,MAAM,EAAE,MAAM,OAAO,aAAa;CAElC,MAAM,YAAY,OAAO,OAAO;AAChC,iBAAgB;AACd,YAAU,UAAU;IACnB,CAAC,OAAO,CAAC;CAEZ,MAAM,aAAa,OAAO,QAAQ;AAClC,iBAAgB;AACd,aAAW,UAAU;IACpB,CAAC,QAAQ,CAAC;AAEb,iBAAgB;AACd,MAAI,CAAC,QAAS;AACd,SAAO,GAAG,iBAAiB,SAA6B;AACtD,OAAI,KAAK,WAAW,UAAU,UAAU,QACtC,YAAW,SAAS;IAEtB;IACD;EAAC;EAAI;EAAQ;EAAQ,CAAC;CAEzB,MAAM,aAAa,OAAO,MAAM;AAChC,iBAAgB;AACd,MAAI,CAAC,SAAS;AACZ,cAAW,UAAU;AACrB;;AAEF,MAAI,UAAU,CAAC,WAAW,SAAS;AACjC,cAAW,UAAU;AACrB,QAAK,gBAAgB,EAAE,QAAQ,CAAC;aACvB,CAAC,OACV,YAAW,UAAU;IAEtB;EAAC;EAAQ;EAAM;EAAQ;EAAQ,CAAC"}
+{"version":3,"file":"usePopoverSync.js","names":[],"sources":["../../../src/utils/react/usePopoverSync.ts"],"sourcesContent":["import { RefObject, useCallback, 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 useCallback(\n    (from: Element | null) => {\n      if (!from || !emit) return;\n      emit<PopoverDismissAncestorPayload>('popover:dismiss-ancestor', { from });\n    },\n    [emit],\n  );\n}\n"],"mappings":"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"}

package/dist/utils/react/useQaProps.js

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

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.141.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.0 | Cube Dev Team */
 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.141.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.0 | Cube Dev Team */
 import { isValidElement } from "react";
 import { isFragment } from "react-is";
 

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.141.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.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.141.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.0 | Cube Dev Team */
 //#region src/utils/styles.ts
 /**
 * Split properties into style and non-style properties.

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.141.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.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.141.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.0 | Cube Dev Team */
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {
 	disabled: "isDisabled",

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.141.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.142.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.141.0";
+const VERSION = "0.142.0";
 const TASTY_VERSION = "2.6.2";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/components/actions/Button.md

@@ -41,6 +41,7 @@ Supports [Base properties](../../BaseProperties.md)
 Customises the root element of the component.
 
 **Sub-elements:**
+
 - `Icon` – wrapper around the leading icon
 - `RightIcon` – wrapper around the trailing icon
 - `Label` – the button text content
@@ -114,27 +115,35 @@ The `mods` prop accepts the following modifiers you can override:
 ```jsx
 import { IconPlus } from '@tabler/icons-react';
 
-{/* Standard icon */}
-<Button icon={<IconPlus />} aria-label="Add item" />
-
-{/* Empty slot (reserves space but shows nothing) */}
-<Button icon={true} aria-label="Empty slot" />
-
-{/* Dynamic icon based on mods */}
-<Button 
-  icon={({ loading }) => loading ? <SpinnerIcon /> : <IconPlus />}
+{
+  /* Standard icon */
+}
+<Button icon={<IconPlus />} aria-label="Add item" />;
+
+{
+  /* Empty slot (reserves space but shows nothing) */
+}
+<Button icon={true} aria-label="Empty slot" />;
+
+{
+  /* Dynamic icon based on mods */
+}
+<Button
+  icon={({ loading }) => (loading ? <SpinnerIcon /> : <IconPlus />)}
   aria-label="Dynamic icon"
 >
   Save
-</Button>
+</Button>;
 
-{/* Return true from function for empty slot */}
-<Button 
-  icon={({ selected }) => selected ? <CheckIcon /> : true}
+{
+  /* Return true from function for empty slot */
+}
+<Button
+  icon={({ selected }) => (selected ? <CheckIcon /> : true)}
   aria-label="Conditional icon"
 >
   Option
-</Button>
+</Button>;
 ```
 
 ### Link Button
@@ -159,21 +168,31 @@ import { IconPlus } from '@tabler/icons-react';
 ### With Tooltip
 
 ```jsx
-{/* Simple tooltip text */}
-<Button icon={<IconPlus />} tooltip="Add new item" aria-label="Add" />
-
-{/* Auto tooltip on overflow */}
-<Button tooltip={true} width="100px">This text will be truncated</Button>
+{
+  /* Simple tooltip text */
+}
+<Button icon={<IconPlus />} tooltip="Add new item" aria-label="Add" />;
+
+{
+  /* Auto tooltip on overflow */
+}
+<Button tooltip={true} width="100px">
+  This text will be truncated
+</Button>;
 ```
 
 ### Custom Size
 
 ```jsx
-{/* Using a number (pixels) */}
-<Button size={64}>Large Custom</Button>
-
-{/* Using a string multiplier */}
-<Button size="8x">8x Size</Button>
+{
+  /* Using a number (pixels) */
+}
+<Button size={64}>Large Custom</Button>;
+
+{
+  /* Using a string multiplier */
+}
+<Button size="8x">8x Size</Button>;
 ```
 
 ## Accessibility
@@ -195,6 +214,65 @@ import { IconPlus } from '@tabler/icons-react';
 - `aria-pressed` – Managed automatically when `isSelected` is used.
 - Additional ARIA attributes supported by React Aria's `useButton`.
 
+## Behaviour Inside Popovers
+
+By default, pressing a `Button` inside an open popover (any overlay that
+uses `usePopoverSync` — including the popovers rendered by `FilterPicker`,
+`Picker`, `ComboBox`, `Select`, `MenuTrigger`, and
+`DialogTrigger type="popover"`) **dismisses that popover** after the user's
+`onPress` runs. This matches the common UX where a popover is a transient
+surface: any action inside it should close it.
+
+Modal / tray / fullscreen Dialogs are **not** affected — a Button inside a
+modal Dialog does not auto-close it.
+
+### Opt-outs
+
+There are three ways to keep the popover open when a Button is pressed:
+
+1. **Automatic for popover triggers.** Buttons that act as popover triggers
+   already carry `data-popover-trigger` (applied by `MenuTrigger`,
+   `DialogTrigger type="popover"`, `FilterPicker`, `Picker`, `ComboBox`,
+   `Select`). Modal-type `DialogTrigger` children are **not** marked, so they
+   correctly dismiss the parent popover and let the modal take over.
+2. **Manual via `data-popover-keep`.** Add the attribute to the button
+   (toggle case) or to any ancestor element (subtree case — useful when a
+   custom inline editor inside a popover footer should not collapse on
+   every interaction):
+
+   ```jsx
+   <Button data-popover-keep onPress={() => setMode((m) => !m)}>
+     Toggle
+   </Button>
+
+   <div data-popover-keep>
+     {/* All Buttons inside this wrapper opt out. */}
+   </div>
+   ```
+
+3. **Custom non-Cube triggers.** Call `useDismissParentPopover()` yourself if
+   your control should dismiss the popover but does not extend `Button` /
+   `ItemButton`:
+   ```jsx
+   const dismiss = useDismissParentPopover();
+   <MyCustomPressable
+     onPress={(e) => {
+       doThing();
+       dismiss(e.currentTarget);
+     }}
+   />;
+   ```
+
+### Async `onPress`
+
+The dismiss is dispatched via the EventBus, which defers with `setTimeout(0)`.
+This means synchronous `onPress` handlers (and any React state updates they
+trigger) flush **before** the popover closes — including the common case of
+opening a hoisted modal via `useDialogContainer` from a popover footer (the
+modal mounts first, then the popover closes behind it). If your `onPress` is
+async and `await`s before opening another overlay, the popover will close
+first and the new overlay will appear after — usually fine, but worth noting.
+
 ## Best Practices
 
 1. **Do**: Provide a label for icon-only buttons

package/docs/components/actions/ItemButton.md

@@ -74,7 +74,7 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 ### Sizes
 
 - `xsmall` - Extra small size for compact interfaces
-- `small` - Small size for dense layouts  
+- `small` - Small size for dense layouts
 - `medium` - Default size for most use cases
 - `large` - Large size for prominent actions
 - `xlarge` - Extra large size for hero actions
@@ -84,15 +84,13 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 ### Basic Button
 
 ```jsx
-<ItemButton onPress={() => console.log('Clicked')}>
-  Click me
-</ItemButton>
+<ItemButton onPress={() => console.log('Clicked')}>Click me</ItemButton>
 ```
 
 ### Button with Icons
 
 ```jsx
-<ItemButton 
+<ItemButton
   icon={<IconFile />}
   rightIcon={<IconExternalLink />}
   onPress={handleOpen}
@@ -104,19 +102,13 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 ### Link Button
 
 ```jsx
-<ItemButton to="/docs">
-  Go to Documentation
-</ItemButton>
+<ItemButton to="/docs">Go to Documentation</ItemButton>
 ```
 
 ### Button with Hotkey
 
 ```jsx
-<ItemButton 
-  hotkeys="cmd+s"
-  onPress={handleSave}
-  type="primary"
->
+<ItemButton hotkeys="cmd+s" onPress={handleSave} type="primary">
   Save Document
 </ItemButton>
 ```
@@ -124,11 +116,7 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 ### Form Submit Button
 
 ```jsx
-<ItemButton 
-  htmlType="submit"
-  type="primary"
-  icon={<IconCheck />}
->
+<ItemButton htmlType="submit" type="primary" icon={<IconCheck />}>
   Submit Form
 </ItemButton>
 ```
@@ -136,10 +124,7 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 ### Button with Selection State
 
 ```jsx
-<ItemButton 
-  isSelected={isSelected}
-  onPress={() => setIsSelected(!isSelected)}
->
+<ItemButton isSelected={isSelected} onPress={() => setIsSelected(!isSelected)}>
   Toggle Selection
 </ItemButton>
 ```
@@ -149,12 +134,20 @@ Inherits all modifiers from [Item](../content/Item.md) plus:
 ItemButton supports inline actions that appear on the right side. Use the `ItemButton.Action` compound component for consistent styling:
 
 ```jsx
-<ItemButton 
+<ItemButton
   icon={<IconFile />}
   actions={
     <>
-      <ItemButton.Action icon={<IconEdit />} aria-label="Edit" onPress={handleEdit} />
-      <ItemButton.Action icon={<IconTrash />} aria-label="Delete" onPress={handleDelete} />
+      <ItemButton.Action
+        icon={<IconEdit />}
+        aria-label="Edit"
+        onPress={handleEdit}
+      />
+      <ItemButton.Action
+        icon={<IconTrash />}
+        aria-label="Delete"
+        onPress={handleDelete}
+      />
     </>
   }
   onPress={handleOpen}
@@ -188,9 +181,41 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
 - `aria-pressed` - Indicates toggle state for toggle buttons
 - `role` - Automatically set to "button" or "link" based on props
 
+## Behaviour Inside Popovers
+
+Like `Button`, an `ItemButton` press inside an open popover **dismisses
+that popover** by default — popovers are transient surfaces and any action
+inside them should close them. Modals/trays/fullscreen Dialogs are not
+affected.
+
+### Opt-outs
+
+- **Automatic for popover triggers** — `MenuTrigger`, `DialogTrigger
+type="popover"`, and the picker components (`FilterPicker`, `Picker`,
+  `ComboBox`, `Select`) mark their trigger ItemButtons with
+  `data-popover-trigger` so they don't dismiss the popover they themselves
+  live in.
+- **Manual via `data-popover-keep`** — add to the ItemButton (toggle) or
+  any ancestor (whole subtree):
+  ```jsx
+  <ItemButton data-popover-keep onPress={() => setMode((m) => !m)}>
+    Toggle Mode
+  </ItemButton>
+  ```
+- **Custom non-Cube triggers** — call `useDismissParentPopover()` directly
+  if you build a control on top of something other than `Button` /
+  `ItemButton`.
+
+The dismiss is dispatched via the EventBus, which defers with `setTimeout(0)`
+— so synchronous `onPress` handlers (and the React state updates they
+trigger) flush BEFORE the popover closes. This makes the "open a hoisted
+modal from a popover footer" pattern work without flicker: the modal mounts
+first, then the popover closes behind it.
+
 ## Best Practices
 
 1. **Do**: Use clear, action-oriented text
+
    ```jsx
    <ItemButton onPress={handleSave} type="primary">
      Save Changes
@@ -198,6 +223,7 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
    ```
 
 2. **Do**: Add hotkeys for frequently used actions
+
    ```jsx
    <ItemButton hotkeys="cmd+s" onPress={handleSave}>
      Save Document
@@ -205,6 +231,7 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
    ```
 
 3. **Do**: Use appropriate button types for forms
+
    ```jsx
    <ItemButton htmlType="submit" type="primary">
      Submit Form
@@ -212,8 +239,9 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
    ```
 
 4. **Do**: Use `ItemButton.Action` for inline actions
+
    ```jsx
-   <ItemButton 
+   <ItemButton
      icon={<IconFile />}
      actions={
        <>
@@ -228,15 +256,21 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
    ```
 
 5. **Don't**: Use vague or unclear button text
+
    ```jsx
-   {/* Avoid this - unclear what "OK" does */}
-   <ItemButton onPress={handleAction}>OK</ItemButton>
+   {
+     /* Avoid this - unclear what "OK" does */
+   }
+   <ItemButton onPress={handleAction}>OK</ItemButton>;
    ```
 
 6. **Don't**: Add too many actions (limit to 2-3 for clarity)
+
    ```jsx
-   {/* Avoid this - too many action buttons */}
-   <ItemButton 
+   {
+     /* Avoid this - too many action buttons */
+   }
+   <ItemButton
      actions={
        <>
          <ItemButton.Action icon={<IconEdit />} aria-label="Edit" />
@@ -247,13 +281,16 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
      }
    >
      Button with too many actions
-   </ItemButton>
+   </ItemButton>;
    ```
 
 7. **Don't**: Overcrowd buttons with too many visual elements
+
    ```jsx
-   {/* Avoid this - too many competing elements */}
-   <ItemButton 
+   {
+     /* Avoid this - too many competing elements */
+   }
+   <ItemButton
      icon={<IconA />}
      rightIcon={<IconB />}
      prefix="Pre"
@@ -261,7 +298,7 @@ Actions automatically inherit the parent button's `type` prop and adjust their s
      description="Long description"
    >
      Overcrowded Button
-   </ItemButton>
+   </ItemButton>;
    ```
 
 8. **Accessibility**: Always ensure buttons have clear, descriptive labels, proper keyboard support, and provide `aria-label` for action buttons