v-float 0.2.1 → 0.4.0

package/README.md

@@ -32,20 +32,19 @@ yarn add v-float
 ### Basic Tooltip
 
 ```vue
-
 <script setup lang="ts">
-  import { useTemplateRef } from "vue"
-  import { useFloating, useHover, offset } from "v-float"
+import { useTemplateRef } from "vue"
+import { useFloating, useHover, offset } from "v-float"
 
-  const anchorEl = useTemplateRef("anchorEl")
-  const floatingEl = useTemplateRef("floatingEl")
+const anchorEl = useTemplateRef("anchorEl")
+const floatingEl = useTemplateRef("floatingEl")
 
-  const context = useFloating(anchorEl, floatingEl, {
-    placement: "top",
-    middlewares: [offset(8)],
-  })
+const context = useFloating(anchorEl, floatingEl, {
+  placement: "top",
+  middlewares: [offset(8)],
+})
 
-  useHover(context)
+useHover(context)
 </script>
 
 <template>
@@ -60,21 +59,22 @@ yarn add v-float
 ### Dropdown Menu
 
 ```vue
-
 <script setup lang="ts">
-  import { useTemplateRef } from "vue"
-  import { useFloating, useClick, useDismiss, offset, flip, shift } from "v-float"
+import { useTemplateRef } from "vue"
+import { useFloating, useClick, useEscapeKey, offset, flip, shift } from "v-float"
 
-  const triggerEl = useTemplateRef("triggerEl")
-  const menuEl = useTemplateRef("menuEl")
+const triggerEl = useTemplateRef("triggerEl")
+const menuEl = useTemplateRef("menuEl")
 
-  const context = useFloating(triggerEl, menuEl, {
-    placement: "bottom-start",
-    middlewares: [offset(4), flip(), shift({ padding: 8 })],
-  })
+const context = useFloating(triggerEl, menuEl, {
+  placement: "bottom-start",
+  middlewares: [offset(4), flip(), shift({ padding: 8 })],
+})
 
-  useClick(context)
-  useDismiss(context)
+useClick(context)
+useEscapeKey({
+  onEscape: () => context.setOpen(false),
+})
 </script>
 
 <template>
@@ -88,6 +88,65 @@ yarn add v-float
 </template>
 ```
 
+### Tooltip with Arrow
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef } from "vue"
+import { useFloating, useHover, useArrow, offset, flip } from "v-float"
+
+const anchorEl = useTemplateRef("anchorEl")
+const tooltipEl = useTemplateRef("tooltipEl")
+const arrowEl = useTemplateRef("arrowEl")
+
+const context = useFloating(anchorEl, tooltipEl, {
+  placement: "top",
+  middlewares: [offset(8), flip()],
+})
+
+useHover(context)
+
+// Arrow middleware is automatically registered
+const { arrowStyles } = useArrow(arrowEl, context, {
+  offset: "-4px",
+})
+</script>
+
+<template>
+  <button ref="anchorEl">Hover me</button>
+
+  <div
+    v-if="context.open.value"
+    ref="tooltipEl"
+    :style="context.floatingStyles.value"
+    class="tooltip"
+  >
+    This is a tooltip with an arrow
+    <div ref="arrowEl" class="arrow" :style="arrowStyles"></div>
+  </div>
+</template>
+
+<style scoped>
+.tooltip {
+  background: white;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  padding: 8px 12px;
+  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
+}
+
+.arrow {
+  position: absolute;
+  width: 8px;
+  height: 8px;
+  background: white;
+  border: 1px solid #ddd;
+  transform: rotate(45deg);
+  z-index: -1;
+}
+</style>
+```
+
 ## Core Composables
 
 ### Positioning
@@ -101,7 +160,7 @@ yarn add v-float
 - **`useHover`**: Hover interactions with configurable delays
 - **`useFocus`**: Focus/blur event handling for keyboard navigation
 - **`useClick`**: Click event handling with toggle and dismiss options
-- **`useDismiss`**: Close on outside click, ESC key, or scroll events
+- **`useEscapeKey`**: Close on ESC key press with composition handling
 - **`useClientPoint`**: Position floating elements at cursor/touch coordinates
 
 ### Middleware
@@ -112,90 +171,137 @@ All [Floating UI middleware](https://floating-ui.com/docs/middleware) are suppor
 - **`flip`**: Flip placement when there's insufficient space
 - **`shift`**: Shift floating element to stay in view
 - **`hide`**: Hide floating element when anchor is not visible
-- **`arrow`**: Position arrow elements (via `useArrow`)
+
+**Arrow positioning** is handled by the [`useArrow`](/api/use-arrow) composable, which automatically registers the necessary middleware.
 
 ## Advanced Features
 
 ### Floating Trees
 
-For nested floating elements like submenus, you need to manage the tree structure explicitly. `useFloating` creates
-contexts for individual floating elements, and `useFloatingTree` manages their hierarchical relationship.
+For nested floating elements like submenus, use `useFloatingTree` to manage hierarchical structures with a streamlined API that eliminates redundant `useFloating` calls.
 
-Here's how you can set up a parent menu with a submenu:
+**Clear Separation of Concerns:**
 
-```vue
+- Use `useFloating` for isolated floating elements
+- Use `useFloatingTree` for hierarchical structures
+
+Here's how you can set up a parent menu with a submenu using the new API:
 
+```vue
 <script setup lang="ts">
-  import { useTemplateRef } from "vue";
-  import { useFloating, useFloatingTree, offset } from "v-float";
-
-  const parentTriggerEl = useTemplateRef("parentTriggerRef");
-  const parentMenuEl = useTemplateRef("parentMenuRef");
-
-  const submenuTriggerEl = useTemplateRef("submenuTriggerRef");
-  const submenuEl = useTemplateRef("submenuRef");
-
-  // 1. Create the floating context for the parent menu.
-  const parentContext = useFloating(parentTriggerEl, parentMenuEl, {
-    placement: "bottom-start",
-    middlewares: [offset(4)],
-  });
-
-  // 2. Create the floating tree, using the parent's context as the data for the root node.
-  //    useFloatingTree will create a root TreeNode whose `data` is parentContext.
-  const tree = useFloatingTree(parentContext);
-
-  // 3. Create the floating context for the submenu.
-  const submenuContext = useFloating(submenuTriggerEl, submenuEl, {
-    placement: "right-start",
-    middlewares: [offset(4)],
-  });
-
-  // 4. Add the submenu to the tree as a child of the parent menu.
-  //    tree.root refers to the TreeNode associated with parentContext.
-  const submenuNode = tree.addNode(submenuContext, tree.root.id);
-  // submenuNode is the TreeNode for the submenu. You can store it if needed.
+import { useTemplateRef, ref } from "vue"
+import { useFloatingTree, useHover, useClick, offset, flip, shift } from "v-float"
+
+const parentTriggerEl = useTemplateRef("parentTriggerRef")
+const parentMenuEl = useTemplateRef("parentMenuRef")
+const isParentOpen = ref(false)
+
+const submenuTriggerEl = useTemplateRef("submenuTriggerRef")
+const submenuEl = useTemplateRef("submenuRef")
+const isSubmenuOpen = ref(false)
+
+// 1. Create the floating tree with root context automatically
+const tree = useFloatingTree(parentTriggerEl, parentMenuEl, {
+  placement: "bottom-start",
+  open: isParentOpen,
+  middlewares: [offset(4), flip(), shift({ padding: 8 })],
+})
+
+// 2. Add submenu node - no separate useFloating call needed!
+const submenuNode = tree.addNode(submenuTriggerEl, submenuEl, {
+  placement: "right-start",
+  open: isSubmenuOpen,
+  middlewares: [offset(4), flip(), shift({ padding: 8 })],
+  parentId: tree.root.id, // Link to parent using parentId in options
+})
+
+// 3. Add interactions
+useClick(tree.root, { outsideClick: true })
+useHover(submenuNode, { delay: { open: 100, close: 300 } })
+
+// Access floating styles from the contexts
+const { floatingStyles: parentStyles } = tree.rootContext
+const { floatingStyles: submenuStyles } = submenuNode.data
 </script>
 
 <template>
   <!-- Parent Menu Trigger -->
-  <button ref="parentTriggerEl">Open Menu</button>
+  <button ref="parentTriggerEl" @click="isParentOpen = !isParentOpen">Open Menu</button>
 
-  <!-- Parent Menu Floating Element -->
-  <div
-    v-if="parentContext.open.value"
-    ref="parentMenuEl"
-    :style="parentContext.floatingStyles.value"
-    style="background-color: #f0f0f0; border: 1px solid #ccc; padding: 5px; z-index: 1000;"
-  >
-    <div>Parent Menu Item 1</div>
+  <!-- Parent Menu -->
+  <div v-if="isParentOpen" ref="parentMenuEl" :style="parentStyles" class="menu">
+    <div class="menu-item">Menu Item 1</div>
 
-    <!-- Submenu Trigger (an item within the parent menu) -->
+    <!-- Submenu Trigger -->
     <div
       ref="submenuTriggerEl"
-      style="padding: 5px; cursor: pointer; hover: background-color: #e0e0e0;"
-      @mouseenter="() => submenuContext?.setOpen(true)" @mouseleave="() => submenuContext?.setOpen(false)"
-    >
-    Parent Menu Item 2 (Hover for Submenu)
-
-    <!-- Submenu Floating Element -->
-    <div
-      v-if="submenuContext.open.value"
-      ref="submenuEl"
-      :style="submenuContext.floatingStyles.value"
-      style="background-color: #e0e0e0; border: 1px solid #bbb; padding: 5px; margin-left: 10px; z-index: 1010;"
+      class="menu-item menu-item--submenu"
+      @click="isSubmenuOpen = !isSubmenuOpen"
     >
-      <div>Submenu Item A</div>
-      <div>Submenu Item B</div>
+      Menu Item 2 (Has Submenu)
+
+      <!-- Submenu -->
+      <div v-if="isSubmenuOpen" ref="submenuEl" :style="submenuStyles" class="menu submenu">
+        <div class="menu-item">Submenu Item A</div>
+        <div class="menu-item">Submenu Item B</div>
+        <div class="menu-item">Submenu Item C</div>
+      </div>
     </div>
+
+    <div class="menu-item">Menu Item 3</div>
   </div>
 </template>
+
+<style scoped>
+.menu {
+  background: white;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  padding: 4px 0;
+  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
+  min-width: 160px;
+  z-index: 1000;
+}
+
+.submenu {
+  margin-left: 8px;
+  z-index: 1010;
+}
+
+.menu-item {
+  padding: 8px 12px;
+  cursor: pointer;
+  user-select: none;
+}
+
+.menu-item:hover {
+  background-color: #f5f5f5;
+}
+
+.menu-item--submenu {
+  position: relative;
+}
+</style>
+```
+
+**API Benefits:**
+
+```ts
+// Before: Required separate useFloating calls
+const parentContext = useFloating(parentEl, parentFloating, options)
+const tree = useFloatingTree(parentContext)
+const childContext = useFloating(childEl, childFloating, childOptions)
+const childNode = tree.addNode(childContext, parentContext.nodeId)
+
+// After: Streamlined API with internal context creation
+const tree = useFloatingTree(parentEl, parentFloating, options)
+const childNode = tree.addNode(childEl, childFloating, {
+  ...childOptions,
+  parentId: tree.root.id,
+})
 ```
 
-This example demonstrates the manual process of creating contexts and then linking them within the tree. For more
-complex scenarios, you would integrate interaction composables (`useClick`, `useHover`, `useDismiss`) to manage the
-`open` state of each context, potentially using tree methods like `tree.isTopmost()` or `tree.forEach()` to coordinate
-behavior (e.g., closing child menus when a parent closes).
+This approach eliminates redundant calls and provides a clearer separation between isolated floating elements (`useFloating`) and hierarchical structures (`useFloatingTree`).
 
 ## TypeScript Support
 

package/dist/composables/interactions/index.d.ts

@@ -1,6 +1,7 @@
 export * from './use-hover';
 export * from './use-focus';
 export * from './use-click';
-export * from './use-dismiss';
 export * from './use-client-point';
+export * from './use-escape-key';
+export * from './utils';
 //# sourceMappingURL=index.d.ts.map

package/dist/composables/interactions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,oBAAoB,CAAA;AAClC,cAAc,kBAAkB,CAAA;AAChC,cAAc,SAAS,CAAA"}

package/dist/composables/interactions/polygon.d.ts

@@ -1,4 +1,5 @@
-import { FloatingContext, FloatingElement, AnchorElement } from '../use-floating';
+import { TreeNode } from '../use-tree';
+import { AnchorElement, FloatingContext, FloatingElement } from '../use-floating';
 type Point = [number, number];
 type Polygon = Point[];
 export interface SafePolygonOptions {
@@ -17,12 +18,21 @@ export interface CreateSafePolygonHandlerContext {
     };
     buffer: number;
     onClose: () => void;
+    nodeId?: string;
+    tree?: {
+        nodes: Map<string, TreeNode<FloatingContext>>;
+    };
 }
 /**
  * Generates a safe polygon area that the user can traverse without closing the
  * floating element once leaving the reference element.
  * @see https://floating-ui.com/docs/useHover#safepolygon
  */
-export declare function safePolygon(options?: SafePolygonOptions): ({ x, y, placement, elements, buffer: contextBuffer, onClose, }: CreateSafePolygonHandlerContext) => (event: MouseEvent) => void;
+export declare function safePolygon(options?: SafePolygonOptions): {
+    (context: CreateSafePolygonHandlerContext): (event: MouseEvent) => void;
+    __options: {
+        blockPointerEvents: boolean;
+    };
+};
 export {};
 //# sourceMappingURL=polygon.d.ts.map

package/dist/composables/interactions/polygon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"polygon.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/polygon.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAGtF,KAAK,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAC7B,KAAK,OAAO,GAAG,KAAK,EAAE,CAAA;AAyCtB,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC7C;AAED,MAAM,WAAW,+BAA+B;IAC9C,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,SAAS,EAAE,eAAe,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAAA;IAChD,QAAQ,EAAE;QACR,YAAY,EAAE,aAAa,GAAG,IAAI,CAAA;QAClC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAA;KACjC,CAAA;IACD,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,oEAuCvD,+BAA+B,aASG,UAAU,UA6ShD"}
+{"version":3,"file":"polygon.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/polygon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAGtD,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAGtF,KAAK,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAC7B,KAAK,OAAO,GAAG,KAAK,EAAE,CAAA;AAoDtB,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC7C;AAED,MAAM,WAAW,+BAA+B;IAC9C,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,SAAS,EAAE,eAAe,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAAA;IAChD,QAAQ,EAAE;QACR,YAAY,EAAE,aAAa,GAAG,IAAI,CAAA;QAClC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAA;KACjC,CAAA;IACD,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE;QAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAA;KAAE,CAAA;CACzD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB;cAsCJ,+BAA+B,WAehD,UAAU;;;;EAiVhD"}

package/dist/composables/interactions/use-click.d.ts

@@ -1,23 +1,53 @@
-import { MaybeRefOrGetter } from 'vue';
 import { FloatingContext } from '..';
+import { TreeNode } from '../use-tree';
+import { MaybeRefOrGetter } from 'vue';
 /**
- * Enables showing/hiding the floating element when clicking the reference element.
+ * Enables showing/hiding the floating element when clicking the reference element
+ * and optionally when clicking outside both the reference and floating elements.
  *
- * This composable provides event handlers for click interactions with the reference element
- * to control the visibility of the floating element.
+ * This composable provides unified event handlers for both inside click interactions
+ * (to open/toggle floating elements) and outside click interactions (to close them).
  *
- * @param context - The floating context with open state and change handler.
+ * The composable supports both standalone usage with FloatingContext and tree-aware
+ * usage with TreeNode<FloatingContext> for complex nested floating UI structures.
+ *
+ * @param context - The floating context or tree node with open state and change handler.
  * @param options - Configuration options for click behavior.
  *
- * @example
+ * @example Basic standalone usage with outside click enabled
  * ```ts
  * const context = useFloating(...)
  * useClick(context, {
- *   event: "mousedown",
+ *   toggle: true,
+ *   outsideClick: true,
+ *   outsideEvent: 'pointerdown'
+ * })
+ * ```
+ *
+ * @example Tree-aware usage for nested floating elements
+ * ```ts
+ * const tree = useFloatingTree(rootContext)
+ * const parentNode = tree.root
+ * const childNode = tree.addNode(childContext, parentNode.id)
+ *
+ * // Tree-aware behavior: child won't close when clicked,
+ * // but will close when parent or outside is clicked
+ * useClick(childNode, { outsideClick: true })
+ * ```
+ *
+ * @example Custom outside click handler
+ * ```ts
+ * useClick(context, {
+ *   outsideClick: true,
+ *   onOutsideClick: (event, context) => {
+ *     if (confirm('Close dialog?')) {
+ *       context.setOpen(false)
+ *     }
+ *   }
  * })
  * ```
  */
-export declare function useClick(context: FloatingContext, options?: UseClickOptions): void;
+export declare function useClick(context: FloatingContext | TreeNode<FloatingContext>, options?: UseClickOptions): void;
 /**
  * Options for configuring the useClick behavior.
  */
@@ -44,9 +74,47 @@ export interface UseClickOptions {
      */
     ignoreMouse?: MaybeRefOrGetter<boolean>;
     /**
-     * Whether to add keyboard handlers (Enter and Space key functionality).
+     * Whether to ignore keyboard handlers (Enter and Space key functionality).
+     * @default false
+     */
+    ignoreKeyboard?: MaybeRefOrGetter<boolean>;
+    /**
+     * Whether to ignore touch events.
+     * @default false
+     */
+    ignoreTouch?: MaybeRefOrGetter<boolean>;
+    /**
+     * Whether to enable outside click detection to close the floating element.
+     * @default false
+     */
+    outsideClick?: MaybeRefOrGetter<boolean>;
+    /**
+     * The event to use for outside click detection.
+     * @default 'pointerdown'
+     */
+    outsideEvent?: MaybeRefOrGetter<"pointerdown" | "mousedown" | "click">;
+    /**
+     * Whether to use capture phase for document outside click listener.
+     * @default true
+     */
+    outsideCapture?: MaybeRefOrGetter<boolean>;
+    /**
+     * Custom function to handle outside clicks.
+     * If provided, this function will be called instead of the default behavior.
+     * The function receives the event and context as parameters.
+     * @param event - The mouse event that triggered the outside click
+     * @param context - The floating context containing refs and state
+     */
+    onOutsideClick?: (event: MouseEvent, context: FloatingContext) => void;
+    /**
+     * Whether to prevent clicks on scrollbars from triggering outside click.
+     * @default true
+     */
+    preventScrollbarClick?: MaybeRefOrGetter<boolean>;
+    /**
+     * Whether to handle drag events that start inside and end outside.
      * @default true
      */
-    keyboardHandlers?: MaybeRefOrGetter<boolean>;
+    handleDragEvents?: MaybeRefOrGetter<boolean>;
 }
 //# sourceMappingURL=use-click.d.ts.map

package/dist/composables/interactions/use-click.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-click.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/use-click.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,gBAAgB,EAA8C,MAAM,KAAK,CAAA;AACjG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAMpD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CA4HtF;AAqDD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEnC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,GAAG,WAAW,CAAC,CAAA;IAE/C;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAElC;;;OAGG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEvC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;CAC7C"}
+{"version":3,"file":"use-click.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/use-click.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAGtD,OAAO,EAAE,KAAK,gBAAgB,EAAwD,MAAM,KAAK,CAAA;AAkBjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,eAAe,GAAG,QAAQ,CAAC,eAAe,CAAC,EACpD,OAAO,GAAE,eAAoB,GAC5B,IAAI,CAiQN;AA0CD;;GAEG;AACH,MAAM,WAAW,eAAe;IAG9B;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEnC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,GAAG,WAAW,CAAC,CAAA;IAE/C;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAElC;;;OAGG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEvC;;;OAGG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAE1C;;;OAGG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAIvC;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAExC;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC,aAAa,GAAG,WAAW,GAAG,OAAO,CAAC,CAAA;IAEtE;;;OAGG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAE1C;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,KAAK,IAAI,CAAA;IAEtE;;;OAGG;IACH,qBAAqB,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEjD;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;CAC7C"}

package/dist/composables/interactions/use-client-point.d.ts

@@ -1,5 +1,5 @@
-import { MaybeRefOrGetter, Ref } from 'vue';
 import { FloatingContext } from '..';
+import { MaybeRefOrGetter, Ref } from 'vue';
 /**
  * Positions the floating element relative to a client point (mouse position).
  *

package/dist/composables/interactions/use-client-point.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-client-point.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/use-client-point.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,gBAAgB,EAGrB,KAAK,GAAG,EAIT,MAAM,KAAK,CAAA;AACZ,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAOpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,aAAa,EAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,EACtC,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CA4EtB;AAoGD,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEnC;;;OAGG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC,GAAG,GAAG,GAAG,GAAG,MAAM,CAAC,CAAA;IAE3C;;;OAGG;IACH,CAAC,CAAC,EAAE,gBAAgB,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEnC;;;OAGG;IACH,CAAC,CAAC,EAAE,gBAAgB,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,WAAW,EAAE,QAAQ,CAAC,GAAG,CAAC;QAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC,CAAA;IAClE;;OAEG;IACH,cAAc,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAC/C"}
+{"version":3,"file":"use-client-point.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/use-client-point.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAGpD,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,GAAG,EAOT,MAAM,KAAK,CAAA;AAOZ;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,aAAa,EAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,EACtC,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CA4EtB;AA8FD,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEnC;;;OAGG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC,GAAG,GAAG,GAAG,GAAG,MAAM,CAAC,CAAA;IAE3C;;;OAGG;IACH,CAAC,CAAC,EAAE,gBAAgB,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEnC;;;OAGG;IACH,CAAC,CAAC,EAAE,gBAAgB,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,WAAW,EAAE,QAAQ,CAAC,GAAG,CAAC;QAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC,CAAA;IAClE;;OAEG;IACH,cAAc,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAC/C"}

package/dist/composables/interactions/use-escape-key.d.ts

@@ -0,0 +1,24 @@
+import { MaybeRefOrGetter } from 'vue';
+export interface UseEscapeKeyOptions {
+    /**
+     * Condition to enable the escape key listener.
+     * @default true
+     */
+    enabled?: MaybeRefOrGetter<boolean>;
+    /**
+     * Whether to use capture phase for document event listeners.
+     * @default false
+     */
+    capture?: boolean;
+    /**
+     * Callback function to be executed when the escape key is pressed.
+     */
+    onEscape: (event: KeyboardEvent) => void;
+}
+/**
+ * A composable to handle the escape key press, with composition event handling.
+ *
+ * @param options - {@link UseEscapeKeyOptions}
+ */
+export declare function useEscapeKey(options: UseEscapeKeyOptions): void;
+//# sourceMappingURL=use-escape-key.d.ts.map

package/dist/composables/interactions/use-escape-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-escape-key.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/use-escape-key.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,gBAAgB,EAAgB,MAAM,KAAK,CAAA;AAMzD,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEnC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;CACzC;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAe/D"}

package/dist/composables/interactions/use-focus.d.ts

@@ -1,15 +1,40 @@
 import { FloatingContext } from '..';
+import { TreeNode } from '../use-tree';
 import { MaybeRefOrGetter } from 'vue';
 /**
  * Enables showing/hiding the floating element when focusing the reference element.
  *
  * This composable is responsible for KEYBOARD-ONLY interactions. For a complete user experience,
- * it should be composed with other hooks like `useClick`, `useHover`, and `useDismiss`.
+ * it should be composed with other hooks like `useClick`, `useHover`, and `useEscapeKey`.
  *
- * @param context - The floating context with open state and change handler.
+ * The composable supports both standalone usage with FloatingContext and tree-aware
+ * usage with TreeNode<FloatingContext> for complex nested floating UI structures.
+ *
+ * @param context - The floating context or tree node with open state and change handler.
  * @param options - Configuration options for focus behavior.
+ *
+ * @example Basic standalone usage
+ * ```ts
+ * const context = useFloating(...)
+ * useFocus(context, {
+ *   enabled: true,
+ *   requireFocusVisible: true
+ * })
+ * ```
+ *
+ * @example Tree-aware usage for nested floating elements
+ * ```ts
+ * const tree = useFloatingTree(rootContext)
+ * const parentNode = tree.root
+ * const childNode = tree.addNode(childContext, parentNode.id)
+ *
+ * // Tree-aware behavior: parent stays open when focus moves to child,
+ * // but closes when focus moves outside hierarchy
+ * useFocus(parentNode, { requireFocusVisible: true })
+ * useFocus(childNode, { requireFocusVisible: true })
+ * ```
  */
-export declare function useFocus(context: FloatingContext, options?: UseFocusOptions): UseFocusReturn;
+export declare function useFocus(context: FloatingContext | TreeNode<FloatingContext>, options?: UseFocusOptions): UseFocusReturn;
 export interface UseFocusOptions {
     /**
      * Whether focus event listeners are enabled

package/dist/composables/interactions/use-focus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-focus.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/use-focus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD,OAAO,EAEL,KAAK,gBAAgB,EAMtB,MAAM,KAAK,CAAA;AAMZ;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CA+HhG;AAMD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEnC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;CAChD;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,CAAA"}
+{"version":3,"file":"use-focus.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/use-focus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAEtD,OAAO,EACL,KAAK,gBAAgB,EAOtB,MAAM,KAAK,CAAA;AAgBZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,eAAe,GAAG,QAAQ,CAAC,eAAe,CAAC,EACpD,OAAO,GAAE,eAAoB,GAC5B,cAAc,CAwIhB;AAMD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEnC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;CAChD;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,CAAA"}

package/dist/composables/interactions/use-hover.d.ts

@@ -1,3 +1,4 @@
+import { TreeNode } from '../use-tree';
 import { MaybeRef } from 'vue';
 import { FloatingContext } from '../use-floating';
 import { SafePolygonOptions } from './polygon';
@@ -44,10 +45,13 @@ export interface UseHoverOptions {
  * with enhanced behaviors like delayed open/close, rest detection, and custom
  * exit handling.
  *
- * @param context - The floating context with open state and change handler
+ * The composable supports both standalone usage with FloatingContext and tree-aware
+ * usage with TreeNode<FloatingContext> for complex nested floating UI structures.
+ *
+ * @param context - The floating context or tree node with open state and change handler
  * @param options - Configuration options for hover behavior
  *
- * @example
+ * @example Basic standalone usage
  * ```ts
  * const context = useFloating(...)
  * useHover(context, {
@@ -55,6 +59,20 @@ export interface UseHoverOptions {
  *   restMs: 150
  * })
  * ```
+ *
+ * @example Tree-aware usage for nested floating elements
+ * ```ts
+ * const tree = useFloatingTree(rootContext)
+ * const parentNode = tree.root
+ * const childNode = tree.addNode(childContext, parentNode.id)
+ *
+ * // Tree-aware behavior: child hover won't end when hovering over child,
+ * // but will end when hovering outside the entire hierarchy
+ * useHover(childNode, {
+ *   delay: { close: 300 },
+ *   safePolygon: true
+ * })
+ * ```
  */
-export declare function useHover(context: FloatingContext, options?: UseHoverOptions): void;
+export declare function useHover(context: FloatingContext | TreeNode<FloatingContext>, options?: UseHoverOptions): void;
 //# sourceMappingURL=use-hover.d.ts.map

package/dist/composables/interactions/use-hover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-hover.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/use-hover.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,QAAQ,EAMd,MAAM,KAAK,CAAA;AACZ,OAAO,KAAK,EAAE,eAAe,EAAkC,MAAM,iBAAiB,CAAA;AACtF,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAQhE,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IAE3B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAE5D;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IAEzB;;;OAGG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IAE7B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,QAAQ,CAAC,OAAO,GAAG,kBAAkB,CAAC,CAAA;CACrD;AAqED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CA8LtF"}
+{"version":3,"file":"use-hover.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/use-hover.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAGtD,OAAO,EACL,KAAK,QAAQ,EAMd,MAAM,KAAK,CAAA;AACZ,OAAO,KAAK,EAAiB,eAAe,EAAmB,MAAM,iBAAiB,CAAA;AACtF,OAAO,EAAE,KAAK,kBAAkB,EAAe,MAAM,WAAW,CAAA;AAehE,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IAE3B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAE5D;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IAEzB;;;OAGG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IAE7B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,QAAQ,CAAC,OAAO,GAAG,kBAAkB,CAAC,CAAA;CACrD;AAiED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,eAAe,GAAG,QAAQ,CAAC,eAAe,CAAC,EACpD,OAAO,GAAE,eAAoB,GAC5B,IAAI,CA8ON"}