@cube-dev/ui-kit 0.0.0-canary-1cd97ae → 0.0.0-canary-4396eae

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

@@ -1 +1 @@
-{"version":3,"file":"useEventBus.js","names":[],"sources":["../../../src/utils/react/useEventBus.ts"],"sourcesContent":["import React, {\n  createContext,\n  ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useRef,\n} from 'react';\n\nexport type EventBusListener<T = any> = (data: T) => void;\n\nexport interface EventBusContextValue {\n  emit: <T = any>(event: string, data?: T) => void;\n  emitSync: <T = any>(event: string, data?: T) => void;\n  on: <T = any>(event: string, listener: EventBusListener<T>) => () => void;\n  off: <T = any>(event: string, listener: EventBusListener<T>) => void;\n}\n\nconst EventBusContext = createContext<EventBusContextValue | null>(null);\n\nexport interface EventBusProviderProps {\n  children: ReactNode;\n}\n\n/**\n * EventBusProvider provides a global event system for the application.\n *\n * @example\n * ```tsx\n * function App() {\n *   return (\n *     <EventBusProvider>\n *       <YourComponents />\n *     </EventBusProvider>\n *   );\n * }\n * ```\n */\nexport function EventBusProvider({ children }: EventBusProviderProps) {\n  const listeners = useRef<Record<string, EventBusListener[]>>({});\n\n  const off = useCallback(\n    <T = any>(event: string, listener: EventBusListener<T>) => {\n      const eventListeners = listeners.current[event];\n      if (eventListeners) {\n        listeners.current[event] = eventListeners.filter((l) => l !== listener);\n\n        // Clean up empty event arrays\n        if (listeners.current[event].length === 0) {\n          delete listeners.current[event];\n        }\n      }\n    },\n    [],\n  );\n\n  const emitSync = useCallback(<T = any>(event: string, data?: T) => {\n    const eventListeners = listeners.current[event];\n    if (eventListeners) {\n      eventListeners.forEach((listener) => listener(data));\n    }\n  }, []);\n\n  const emit = useCallback(<T = any>(event: string, data?: T) => {\n    // Use setTimeout to ensure async emission after current render cycle\n    setTimeout(() => {\n      emitSync(event, data);\n    }, 0);\n  }, []);\n\n  const on = useCallback(\n    <T = any>(event: string, listener: EventBusListener<T>) => {\n      if (!listeners.current[event]) {\n        listeners.current[event] = [];\n      }\n      listeners.current[event].push(listener);\n\n      // Return cleanup function\n      return () => {\n        off(event, listener);\n      };\n    },\n    [off],\n  );\n\n  const contextValue: EventBusContextValue = {\n    emit,\n    emitSync,\n    on,\n    off,\n  };\n\n  return React.createElement(\n    EventBusContext.Provider,\n    { value: contextValue },\n    children,\n  );\n}\n\n/**\n * Hook to access the event bus functionality.\n * Must be used within an EventBusProvider.\n *\n * @example\n * ```tsx\n * function Component() {\n *   const { emit, emitSync, on } = useEventBus();\n *\n *   const handleClick = () => {\n *     emit('user-action', { type: 'click', target: 'button' });\n *   };\n *\n *   const handleSyncAction = () => {\n *     emitSync('sync-action', { immediate: true });\n *   };\n *\n *   useEffect(() => {\n *     const unsubscribe = on('data-updated', (data) => {\n *       console.log('Data updated:', data);\n *     });\n *\n *     return unsubscribe;\n *   }, [on]);\n *\n *   return (\n *     <div>\n *       <button onClick={handleClick}>Async Event</button>\n *       <button onClick={handleSyncAction}>Sync Event</button>\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useEventBus(): EventBusContextValue {\n  const context = useContext(EventBusContext);\n\n  if (!context) {\n    throw new Error('useEventBus must be used within an EventBusProvider');\n  }\n\n  return context;\n}\n\n/**\n * Convenience hook for subscribing to events with automatic cleanup.\n * The listener will be automatically unsubscribed when the component unmounts\n * or when the dependencies change.\n *\n * @param event - The event name to listen for\n * @param listener - The callback function to execute when the event is emitted\n * @param deps - Dependency array for the effect (similar to useEffect)\n *\n * @example\n * ```tsx\n * function NotificationComponent() {\n *   const [message, setMessage] = useState('');\n *\n *   useEventListener('notification', (data) => {\n *     setMessage(data.message);\n *   }, []);\n *\n *   return <div>{message}</div>;\n * }\n * ```\n */\nexport function useEventListener<T = any>(\n  event: string,\n  listener: EventBusListener<T>,\n  deps: React.DependencyList = [],\n) {\n  const { on } = useEventBus();\n\n  useEffect(() => {\n    const unsubscribe = on(event, listener);\n    return unsubscribe;\n  }, [event, on, ...deps]);\n}\n"],"mappings":";;;;AAkBA,MAAM,kBAAkB,cAA2C,KAAK;;;;;;;;;;;;;;;AAoBxE,SAAgB,iBAAiB,EAAE,YAAmC;CACpE,MAAM,YAAY,OAA2C,EAAE,CAAC;CAEhE,MAAM,MAAM,aACA,OAAe,aAAkC;EACzD,MAAM,iBAAiB,UAAU,QAAQ;AACzC,MAAI,gBAAgB;AAClB,aAAU,QAAQ,SAAS,eAAe,QAAQ,MAAM,MAAM,SAAS;AAGvE,OAAI,UAAU,QAAQ,OAAO,WAAW,EACtC,QAAO,UAAU,QAAQ;;IAI/B,EAAE,CACH;CAED,MAAM,WAAW,aAAsB,OAAe,SAAa;EACjE,MAAM,iBAAiB,UAAU,QAAQ;AACzC,MAAI,eACF,gBAAe,SAAS,aAAa,SAAS,KAAK,CAAC;IAErD,EAAE,CAAC;CAwBN,MAAM,eAAqC;EACzC,MAvBW,aAAsB,OAAe,SAAa;AAE7D,oBAAiB;AACf,aAAS,OAAO,KAAK;MACpB,EAAE;KACJ,EAAE,CAAC;EAmBJ;EACA,IAlBS,aACC,OAAe,aAAkC;AACzD,OAAI,CAAC,UAAU,QAAQ,OACrB,WAAU,QAAQ,SAAS,EAAE;AAE/B,aAAU,QAAQ,OAAO,KAAK,SAAS;AAGvC,gBAAa;AACX,QAAI,OAAO,SAAS;;KAGxB,CAAC,IAAI,CACN;EAMC;EACD;AAED,QAAO,MAAM,cACX,gBAAgB,UAChB,EAAE,OAAO,cAAc,EACvB,SACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCH,SAAgB,cAAoC;CAClD,MAAM,UAAU,WAAW,gBAAgB;AAE3C,KAAI,CAAC,QACH,OAAM,IAAI,MAAM,sDAAsD;AAGxE,QAAO;;;;;;;;;;;;;;;;;;;;;;;;AAyBT,SAAgB,iBACd,OACA,UACA,OAA6B,EAAE,EAC/B;CACA,MAAM,EAAE,OAAO,aAAa;AAE5B,iBAAgB;AAEd,SADoB,GAAG,OAAO,SAAS;IAEtC;EAAC;EAAO;EAAI,GAAG;EAAK,CAAC"}
+{"version":3,"file":"useEventBus.js","names":[],"sources":["../../../src/utils/react/useEventBus.ts"],"sourcesContent":["import React, {\n  createContext,\n  ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useRef,\n} from 'react';\n\nexport type EventBusListener<T = any> = (data: T) => void;\n\nexport interface EventBusContextValue {\n  emit: <T = any>(event: string, data?: T) => void;\n  emitSync: <T = any>(event: string, data?: T) => void;\n  on: <T = any>(event: string, listener: EventBusListener<T>) => () => void;\n  off: <T = any>(event: string, listener: EventBusListener<T>) => void;\n}\n\nexport const EventBusContext = createContext<EventBusContextValue | null>(null);\n\nexport interface EventBusProviderProps {\n  children: ReactNode;\n}\n\n/**\n * EventBusProvider provides a global event system for the application.\n *\n * @example\n * ```tsx\n * function App() {\n *   return (\n *     <EventBusProvider>\n *       <YourComponents />\n *     </EventBusProvider>\n *   );\n * }\n * ```\n */\nexport function EventBusProvider({ children }: EventBusProviderProps) {\n  // If we're already inside a parent EventBusProvider (e.g. the global Root\n  // one), DO NOT create a fresh bus — that would isolate listeners and\n  // emitters across the boundary. This matters because overlays (Popover,\n  // Modal, Tray) re-wrap their content with our `Provider` from\n  // `provider.tsx`, which transparently nests an EventBusProvider. Cross-\n  // overlay events such as `popover:dismiss-ancestor` (a Button inside a\n  // popover footer dismissing the popover host) only work when both sides\n  // share the same bus.\n  const parentBus = useContext(EventBusContext);\n\n  const listeners = useRef<Record<string, EventBusListener[]>>({});\n\n  const off = useCallback(\n    <T = any>(event: string, listener: EventBusListener<T>) => {\n      const eventListeners = listeners.current[event];\n      if (eventListeners) {\n        listeners.current[event] = eventListeners.filter((l) => l !== listener);\n\n        // Clean up empty event arrays\n        if (listeners.current[event].length === 0) {\n          delete listeners.current[event];\n        }\n      }\n    },\n    [],\n  );\n\n  const emitSync = useCallback(<T = any>(event: string, data?: T) => {\n    const eventListeners = listeners.current[event];\n    if (eventListeners) {\n      eventListeners.forEach((listener) => listener(data));\n    }\n  }, []);\n\n  const emit = useCallback(\n    <T = any>(event: string, data?: T) => {\n      setTimeout(() => {\n        emitSync(event, data);\n      }, 0);\n    },\n    [emitSync],\n  );\n\n  const on = useCallback(\n    <T = any>(event: string, listener: EventBusListener<T>) => {\n      if (!listeners.current[event]) {\n        listeners.current[event] = [];\n      }\n      listeners.current[event].push(listener);\n\n      // Return cleanup function\n      return () => {\n        off(event, listener);\n      };\n    },\n    [off],\n  );\n\n  // Always compute the local contextValue so hook order stays stable, then\n  // pick parent OR local. (`useMemo` keeps the local one stable for any\n  // descendants that DO end up using it.)\n\n  const localContextValue = useRef<EventBusContextValue>({\n    emit,\n    emitSync,\n    on,\n    off,\n  });\n  localContextValue.current = { emit, emitSync, on, off };\n\n  const contextValue = parentBus ?? localContextValue.current;\n\n  return React.createElement(\n    EventBusContext.Provider,\n    { value: contextValue },\n    children,\n  );\n}\n\n/**\n * Hook to access the event bus functionality.\n * Must be used within an EventBusProvider.\n *\n * @example\n * ```tsx\n * function Component() {\n *   const { emit, emitSync, on } = useEventBus();\n *\n *   const handleClick = () => {\n *     emit('user-action', { type: 'click', target: 'button' });\n *   };\n *\n *   const handleSyncAction = () => {\n *     emitSync('sync-action', { immediate: true });\n *   };\n *\n *   useEffect(() => {\n *     const unsubscribe = on('data-updated', (data) => {\n *       console.log('Data updated:', data);\n *     });\n *\n *     return unsubscribe;\n *   }, [on]);\n *\n *   return (\n *     <div>\n *       <button onClick={handleClick}>Async Event</button>\n *       <button onClick={handleSyncAction}>Sync Event</button>\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useEventBus(): EventBusContextValue {\n  const context = useContext(EventBusContext);\n\n  if (!context) {\n    throw new Error('useEventBus must be used within an EventBusProvider');\n  }\n\n  return context;\n}\n\n/**\n * Convenience hook for subscribing to events with automatic cleanup.\n * The listener will be automatically unsubscribed when the component unmounts\n * or when the dependencies change.\n *\n * @param event - The event name to listen for\n * @param listener - The callback function to execute when the event is emitted\n * @param deps - Dependency array for the effect (similar to useEffect)\n *\n * @example\n * ```tsx\n * function NotificationComponent() {\n *   const [message, setMessage] = useState('');\n *\n *   useEventListener('notification', (data) => {\n *     setMessage(data.message);\n *   }, []);\n *\n *   return <div>{message}</div>;\n * }\n * ```\n */\nexport function useEventListener<T = any>(\n  event: string,\n  listener: EventBusListener<T>,\n  deps: React.DependencyList = [],\n) {\n  const { on } = useEventBus();\n\n  useEffect(() => {\n    const unsubscribe = on(event, listener);\n    return unsubscribe;\n  }, [event, on, ...deps]);\n}\n"],"mappings":";;;;AAkBA,MAAa,kBAAkB,cAA2C,KAAK;;;;;;;;;;;;;;;AAoB/E,SAAgB,iBAAiB,EAAE,YAAmC;CASpE,MAAM,YAAY,WAAW,gBAAgB;CAE7C,MAAM,YAAY,OAA2C,EAAE,CAAC;CAEhE,MAAM,MAAM,aACA,OAAe,aAAkC;EACzD,MAAM,iBAAiB,UAAU,QAAQ;AACzC,MAAI,gBAAgB;AAClB,aAAU,QAAQ,SAAS,eAAe,QAAQ,MAAM,MAAM,SAAS;AAGvE,OAAI,UAAU,QAAQ,OAAO,WAAW,EACtC,QAAO,UAAU,QAAQ;;IAI/B,EAAE,CACH;CAED,MAAM,WAAW,aAAsB,OAAe,SAAa;EACjE,MAAM,iBAAiB,UAAU,QAAQ;AACzC,MAAI,eACF,gBAAe,SAAS,aAAa,SAAS,KAAK,CAAC;IAErD,EAAE,CAAC;CAEN,MAAM,OAAO,aACD,OAAe,SAAa;AACpC,mBAAiB;AACf,YAAS,OAAO,KAAK;KACpB,EAAE;IAEP,CAAC,SAAS,CACX;CAED,MAAM,KAAK,aACC,OAAe,aAAkC;AACzD,MAAI,CAAC,UAAU,QAAQ,OACrB,WAAU,QAAQ,SAAS,EAAE;AAE/B,YAAU,QAAQ,OAAO,KAAK,SAAS;AAGvC,eAAa;AACX,OAAI,OAAO,SAAS;;IAGxB,CAAC,IAAI,CACN;CAMD,MAAM,oBAAoB,OAA6B;EACrD;EACA;EACA;EACA;EACD,CAAC;AACF,mBAAkB,UAAU;EAAE;EAAM;EAAU;EAAI;EAAK;CAEvD,MAAM,eAAe,aAAa,kBAAkB;AAEpD,QAAO,MAAM,cACX,gBAAgB,UAChB,EAAE,OAAO,cAAc,EACvB,SACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCH,SAAgB,cAAoC;CAClD,MAAM,UAAU,WAAW,gBAAgB;AAE3C,KAAI,CAAC,QACH,OAAM,IAAI,MAAM,sDAAsD;AAGxE,QAAO;;;;;;;;;;;;;;;;;;;;;;;;AAyBT,SAAgB,iBACd,OACA,UACA,OAA6B,EAAE,EAC/B;CACA,MAAM,EAAE,OAAO,aAAa;AAE5B,iBAAgB;AAEd,SADoB,GAAG,OAAO,SAAS;IAEtC;EAAC;EAAO;EAAI,GAAG;EAAK,CAAC"}

package/dist/utils/react/useId.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { useEffect, useRef, useState } from "react";
 import { useSSRSafeId } from "@react-aria/ssr";

package/dist/utils/react/useIsDarwin.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | Cube Dev Team */
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useIsDarwin.ts

package/dist/utils/react/useKeySymbols.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | Cube Dev Team */
 import { useIsDarwin } from "./useIsDarwin.js";
 import { useMemo } from "react";
 

package/dist/utils/react/useLayoutEffect.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | Cube Dev Team */
 import * as React$1 from "react";
 
 //#region src/utils/react/useLayoutEffect.tsx

package/dist/utils/react/useLocalStorage.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { useCallback, useSyncExternalStore } from "react";
 

package/dist/utils/react/useMergeStyles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 

package/dist/utils/react/usePopoverSync.d.ts

@@ -0,0 +1,105 @@
+
+import { RefObject } from "react";
+
+//#region src/utils/react/usePopoverSync.d.ts
+interface UsePopoverSyncOptions {
+  /** Stable identifier for this popover instance (typically a generateRandomId() memo). */
+  menuId: string;
+  /** Current open state of this popover. */
+  isOpen: boolean;
+  /** Called when another popover opens while this one is open. */
+  onClose: () => void;
+  /**
+   * When `false`, this popover does not participate in the sync (no listening,
+   * no emitting). Useful for "dummy" triggers that proxy a real one (see
+   * `MenuTrigger`'s `isDummy`). Defaults to `true`.
+   */
+  enabled?: boolean;
+  /**
+   * Ref to the popover's trigger element. When provided, the element is
+   * included in the `popover:open` emit payload so peers can detect whether
+   * the new opener is nested inside their own overlay (and skip closing in
+   * that case). Optional — omitting it preserves the legacy "always close on
+   * peer open" behaviour.
+   */
+  triggerRef?: RefObject<HTMLElement | null>;
+  /**
+   * Ref to the overlay/container element that hosts this popover's content.
+   * When provided, the listener performs a DOM `contains()` check on incoming
+   * peer triggers: peers whose trigger lives inside this container are
+   * considered nested children and do NOT close us.
+   */
+  containerRef?: RefObject<HTMLElement | null>;
+  /**
+   * Whether this overlay closes when a Button/ItemButton inside its container
+   * is pressed. Defaults to `true` (popover semantics — popovers are transient
+   * surfaces and any action inside them should dismiss them). Set to `false`
+   * for modals/trays/fullscreen dialogs — buttons inside a Dialog should not
+   * auto-close it. Requires `containerRef` to be set; without it the listener
+   * has no way to determine whether the dispatching button is "inside" this
+   * overlay and is effectively a no-op.
+   */
+  dismissOnInnerButtonPress?: boolean;
+}
+/**
+ * Coordinates the "only one popover open at a time" invariant via the EventBus.
+ *
+ * - When `isOpen` flips `false -> true`, emits `popover:open` once.
+ * - While open, listens for peers' `popover:open` events and calls `onClose`.
+ *
+ * Implementation notes (ALL of these matter — losing any one re-introduces a
+ * 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
+ *    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
+ *    `wasOpenRef`. A re-render where `isOpen` is still `true` must NOT
+ *    re-emit, otherwise it could re-trigger listeners on peers that just
+ *    opened in the same render flush.
+ * 3. The `enabled` flag short-circuits both effects symmetrically. When it
+ *    flips off, `wasOpenRef` is reset so re-enabling later still emits if
+ *    `isOpen` is true at that moment.
+ */
+declare function usePopoverSync({
+  menuId,
+  isOpen,
+  onClose,
+  enabled,
+  triggerRef,
+  containerRef,
+  dismissOnInnerButtonPress
+}: UsePopoverSyncOptions): void;
+/**
+ * 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.
+ */
+declare function useDismissParentPopover(): (from: Element | null) => void;
+//#endregion
+export { UsePopoverSyncOptions, useDismissParentPopover, usePopoverSync };
+//# sourceMappingURL=usePopoverSync.d.ts.map

package/dist/utils/react/usePopoverSync.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-1cd97ae | Cube Dev Team */
-import { useEventBus } from "./useEventBus.js";
-import { useEffect, useRef } from "react";
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | Cube Dev Team */
+import { EventBusContext, useEventBus } from "./useEventBus.js";
+import { useCallback, useContext, useEffect, useRef } from "react";
 
 //#region src/utils/react/usePopoverSync.ts
 /**
@@ -26,7 +26,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 }) {
 	const { emit, on } = useEventBus();
 	const isOpenRef = useRef(isOpen);
 	useEffect(() => {
@@ -36,15 +36,40 @@ 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 = on("popover:open", (data) => {
+			if (data.menuId === menuId || !isOpenRef.current) return;
+			const container = containerRefRef.current?.current;
+			const triggerEl = data.triggerEl;
+			if (container && triggerEl && container.contains(triggerEl)) return;
+			onCloseRef.current();
+		});
+		if (!dismissOnInnerButtonPress) return offOpen;
+		const offDismiss = 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();
 		});
+		return () => {
+			offOpen();
+			offDismiss();
+		};
 	}, [
 		on,
 		menuId,
-		enabled
+		enabled,
+		dismissOnInnerButtonPress
 	]);
 	const wasOpenRef = useRef(false);
 	useEffect(() => {
@@ -54,7 +79,10 @@ function usePopoverSync({ menuId, isOpen, onClose, enabled = true }) {
 		}
 		if (isOpen && !wasOpenRef.current) {
 			wasOpenRef.current = true;
-			emit("popover:open", { menuId });
+			emit("popover:open", {
+				menuId,
+				triggerEl: triggerRefRef.current?.current ?? null
+			});
 		} else if (!isOpen) wasOpenRef.current = false;
 	}, [
 		isOpen,
@@ -63,7 +91,40 @@ function usePopoverSync({ menuId, isOpen, onClose, enabled = true }) {
 		enabled
 	]);
 }
+/**
+* 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\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\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}: 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    const offOpen = on('popover:open', (data: PopoverOpenPayload) => {\n      if (data.menuId === menuId || !isOpenRef.current) return;\n      const container = containerRefRef.current?.current;\n      const triggerEl = data.triggerEl;\n      // Nested-popover guard: if the peer's trigger lives inside our own\n      // overlay, treat the open as a child interaction and stay open.\n      if (container && triggerEl && container.contains(triggerEl)) return;\n      onCloseRef.current();\n    });\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    if (!dismissOnInnerButtonPress) {\n      return offOpen;\n    }\n\n    const offDismiss = 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\n    return () => {\n      offOpen();\n      offDismiss();\n    };\n  }, [on, menuId, enabled, dismissOnInnerButtonPress]);\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<PopoverOpenPayload>('popover:open', {\n        menuId,\n        triggerEl: triggerRefRef.current?.current ?? null,\n      });\n    } else if (!isOpen) {\n      wasOpenRef.current = false;\n    }\n  }, [isOpen, emit, menuId, enabled]);\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6EA,SAAgB,eAAe,EAC7B,QACA,QACA,SACA,UAAU,MACV,YACA,cACA,4BAA4B,QACE;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;CAMb,MAAM,kBAAkB,OAAO,aAAa;AAC5C,iBAAgB;AACd,kBAAgB,UAAU;IACzB,CAAC,aAAa,CAAC;CAElB,MAAM,gBAAgB,OAAO,WAAW;AACxC,iBAAgB;AACd,gBAAc,UAAU;IACvB,CAAC,WAAW,CAAC;AAEhB,iBAAgB;AACd,MAAI,CAAC,QAAS;EAEd,MAAM,UAAU,GAAG,iBAAiB,SAA6B;AAC/D,OAAI,KAAK,WAAW,UAAU,CAAC,UAAU,QAAS;GAClD,MAAM,YAAY,gBAAgB,SAAS;GAC3C,MAAM,YAAY,KAAK;AAGvB,OAAI,aAAa,aAAa,UAAU,SAAS,UAAU,CAAE;AAC7D,cAAW,SAAS;IACpB;AAOF,MAAI,CAAC,0BACH,QAAO;EAGT,MAAM,aAAa,GACjB,6BACC,SAAwC;AACvC,OAAI,CAAC,UAAU,QAAS;GACxB,MAAM,YAAY,gBAAgB,SAAS;GAC3C,MAAM,OAAO,MAAM;AAInB,OAAI,CAAC,aAAa,CAAC,KAAM;AACzB,OAAI,UAAU,SAAS,KAAK,CAAE,YAAW,SAAS;IAErD;AAED,eAAa;AACX,YAAS;AACT,eAAY;;IAEb;EAAC;EAAI;EAAQ;EAAS;EAA0B,CAAC;CAEpD,MAAM,aAAa,OAAO,MAAM;AAChC,iBAAgB;AACd,MAAI,CAAC,SAAS;AACZ,cAAW,UAAU;AACrB;;AAEF,MAAI,UAAU,CAAC,WAAW,SAAS;AACjC,cAAW,UAAU;AACrB,QAAyB,gBAAgB;IACvC;IACA,WAAW,cAAc,SAAS,WAAW;IAC9C,CAAC;aACO,CAAC,OACV,YAAW,UAAU;IAEtB;EAAC;EAAQ;EAAM;EAAQ;EAAQ,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BrC,SAAgB,0BAA0B;CAMxC,MAAM,OADM,WAAW,gBAAgB,EACrB;AAClB,QAAO,aACJ,SAAyB;AACxB,MAAI,CAAC,QAAQ,CAAC,KAAM;AACpB,OAAoC,4BAA4B,EAAE,MAAM,CAAC;IAE3E,CAAC,KAAK,CACP"}

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | 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.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | 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.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | 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.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | 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.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | 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.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | 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.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | 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.0.0-canary-1cd97ae | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-4396eae | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.0.0-canary-1cd97ae";
+const VERSION = "0.0.0-canary-4396eae";
 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