v-float 0.10.0 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # V-Float
 
-[![status: WIP](https://img.shields.io/badge/status-WIP-orange.svg)](#project-status)
+[status: WIP](#project-status)
 
 > Work in progress: This library is under active development. APIs may change without notice and breaking changes can land without deprecation windows or warnings. Not recommended for production use yet.
 
@@ -12,7 +12,6 @@ of [@floating-ui/dom](https://floating-ui.com/) with Vue 3 Composition API.
 - **Precise Positioning**: Pixel-perfect positioning with automatic collision detection
 - **Vue 3 Composables**: Reactive composables designed for the Composition API
 - **Interaction Handling**: Built-in hover, focus, click, and dismiss behaviors
-- **Nested Elements**: Support for floating element trees and hierarchies
 - **Arrow Positioning**: `useArrow` composable for positioning arrow elements
 - **Lightweight**: Tree-shakable with minimal bundle impact
 - **Cross-platform**: Works on desktop, mobile, and touch devices
@@ -37,24 +36,24 @@ yarn add v-float
 
 ```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)],
-})
+});
 
-useHover(context)
+useHover(context);
 </script>
 
 <template>
   <button ref="anchorEl">Hover me</button>
 
-  <div v-if="context.open.value" ref="floatingEl" :style="context.floatingStyles.value">
+  <div v-if="context.state.open.value" ref="floatingEl" :style="context.position.styles.value">
     This is a tooltip
   </div>
 </template>
@@ -64,27 +63,27 @@ useHover(context)
 
 ```vue
 <script setup lang="ts">
-import { useTemplateRef } from "vue"
-import { useFloating, useClick, useEscapeKey, 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 })],
-})
+});
 
-useClick(context)
-useEscapeKey({
+useClick(context);
+useEscapeKey(context, {
   onEscape: () => context.setOpen(false),
-})
+});
 </script>
 
 <template>
   <button ref="triggerEl">Open Menu</button>
 
-  <div v-if="context.open.value" ref="menuEl" :style="context.floatingStyles.value">
+  <div v-if="context.state.open.value" ref="menuEl" :style="context.position.styles.value">
     <div>Menu Item 1</div>
     <div>Menu Item 2</div>
     <div>Menu Item 3</div>
@@ -96,33 +95,33 @@ useEscapeKey({
 
 ```vue
 <script setup lang="ts">
-import { useTemplateRef } from "vue"
-import { useFloating, useHover, useArrow, offset, flip } from "v-float"
+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 anchorEl = useTemplateRef("anchorEl");
+const tooltipEl = useTemplateRef("tooltipEl");
+const arrowEl = useTemplateRef("arrowEl");
 
 const context = useFloating(anchorEl, tooltipEl, {
   placement: "top",
   middlewares: [offset(8), flip()],
-})
+});
 
-useHover(context)
+useHover(context);
 
-// Arrow middleware is automatically registered
-const { arrowStyles } = useArrow(arrowEl, context, {
+const { arrowStyles } = useArrow(context, {
+  element: arrowEl,
   offset: "-4px",
-})
+});
 </script>
 
 <template>
   <button ref="anchorEl">Hover me</button>
 
   <div
-    v-if="context.open.value"
+    v-if="context.state.open.value"
     ref="tooltipEl"
-    :style="context.floatingStyles.value"
+    :style="context.position.styles.value"
     class="tooltip"
   >
     This is a tooltip with an arrow
@@ -155,30 +154,29 @@ const { arrowStyles } = useArrow(arrowEl, context, {
 
 ### Positioning
 
-- **`useFloating`**: Core positioning logic with middleware support
-- **`useArrow`**: Position arrow elements pointing to the anchor
-- **`useFloatingTree`**: Manage nested floating element hierarchies
+- `**useFloating**`: Core positioning logic with middleware support
+- `**useArrow**`: Position arrow elements pointing to the anchor
 
 ### Interactions
 
-- **`useHover`**: Hover interactions with configurable delays
-- **`useFocus`**: Focus/blur event handling for keyboard navigation
-- **`useClick`**: Click event handling with toggle and dismiss options
-- **`useEscapeKey`**: Close on ESC key press with composition handling
-- **`useClientPoint`**: Position floating elements at cursor/touch coordinates
+- `**useHover**`: Hover interactions with configurable delays
+- `**useFocus**`: Focus/blur event handling for keyboard navigation
+- `**useClick**`: Click event handling with toggle and dismiss options
+- `**useEscapeKey**`: Close on ESC key press with composition handling
+- `**useClientPoint**`: Position floating elements at cursor/touch coordinates
 
 ### Middleware
 
 All [Floating UI middleware](https://floating-ui.com/docs/middleware) are supported:
 
-- **`offset`**: Add distance between anchor and floating element
-- **`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
-- **`autoPlacement`**: Automatically choose the best placement
-- **`size`**: Resize floating element to fit within viewport
+- `**offset**`: Add distance between anchor and floating element
+- `**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
+- `**autoPlacement**`: Automatically choose the best placement
+- `**size**`: Resize floating element to fit within viewport
 
-**Arrow positioning** is handled by the [`useArrow`](/api/use-arrow) composable, which automatically registers the necessary middleware.
+**Arrow positioning** is handled by the `[useArrow](/api/use-arrow)` composable, which owns arrow registration for the floating context.
 
 ## Project Status
 
@@ -186,135 +184,6 @@ All [Floating UI middleware](https://floating-ui.com/docs/middleware) are suppor
 - API, docs, and examples are subject to change and may be incomplete.
 - Feedback and contributions are welcome while the API stabilizes.
 
-## Advanced Features
-
-### Floating Trees
-
-For nested floating elements like submenus, use `useFloatingTree` to manage hierarchical structures with a streamlined API that eliminates redundant `useFloating` calls.
-
-**Clear Separation of Concerns:**
-
-- 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, 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" @click="isParentOpen = !isParentOpen">Open Menu</button>
-
-  <!-- Parent Menu -->
-  <div v-if="isParentOpen" ref="parentMenuEl" :style="parentStyles" class="menu">
-    <div class="menu-item">Menu Item 1</div>
-
-    <!-- Submenu Trigger -->
-    <div
-      ref="submenuTriggerEl"
-      class="menu-item menu-item--submenu"
-      @click="isSubmenuOpen = !isSubmenuOpen"
-    >
-      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 approach eliminates redundant calls and provides a clearer separation between isolated floating elements (`useFloating`) and hierarchical structures (`useFloatingTree`).
-
 ## TypeScript Support
 
 V-Float is built with TypeScript and provides comprehensive type definitions:
@@ -322,7 +191,7 @@ V-Float is built with TypeScript and provides comprehensive type definitions:
 ## Browser Support
 
 - **Modern browsers**: Chrome, Firefox, Safari, Edge
-- **Mobile browsers**: iOS Safari, Chrome Mobile, Samsung Internet
+- **Mobile browsers**: iOS Safari, Chrome Mobile
 - **Node.js**: SSR compatible (with proper hydration)
 
 ## Documentation