v-float 0.8.0 → 0.9.0

package/README.md

@@ -3,130 +3,130 @@
 [![status: WIP](https://img.shields.io/badge/status-WIP-orange.svg)](#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.
-
-A Vue 3 library for positioning floating UI elements like tooltips, popovers, dropdowns, and modals. Built on top
-of [VFloat](https://vfloat.pages.com/) with Vue 3 Composition API.
-
-## Features
-
-- **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
-- **TypeScript**: Full TypeScript support with comprehensive type definitions
-
-## Installation
-
-```bash
-# With pnpm (recommended)
-pnpm add v-float
-
-# With npm
-npm install v-float
-
-# With yarn
-yarn add v-float
-```
-
-## Quick Start
-
-### Basic Tooltip
-
-```vue
-<script setup lang="ts">
-import { useTemplateRef } from "vue"
-import { useFloating, useHover, offset } from "v-float"
-
-const anchorEl = useTemplateRef("anchorEl")
-const floatingEl = useTemplateRef("floatingEl")
-
-const context = useFloating(anchorEl, floatingEl, {
-  placement: "top",
-  middlewares: [offset(8)],
-})
-
-useHover(context)
-</script>
-
-<template>
-  <button ref="anchorEl">Hover me</button>
-
-  <div v-if="context.open.value" ref="floatingEl" :style="context.floatingStyles.value">
-    This is a tooltip
-  </div>
-</template>
-```
-
-### Dropdown Menu
-
-```vue
-<script setup lang="ts">
-import { useTemplateRef } from "vue"
-import { useFloating, useClick, useEscapeKey, offset, flip, shift } from "v-float"
-
-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({
-  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>Menu Item 1</div>
-    <div>Menu Item 2</div>
-    <div>Menu Item 3</div>
-  </div>
-</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>
+
+A Vue 3 library for positioning floating UI elements like tooltips, popovers, dropdowns, and modals. Built on top
+of [@floating-ui/dom](https://floating-ui.com/) with Vue 3 Composition API.
+
+## Features
+
+- **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
+- **TypeScript**: Full TypeScript support with comprehensive type definitions
+
+## Installation
+
+```bash
+# With pnpm (recommended)
+pnpm add v-float
+
+# With npm
+npm install v-float
+
+# With yarn
+yarn add v-float
+```
+
+## Quick Start
+
+### Basic Tooltip
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef } from "vue"
+import { useFloating, useHover, offset } from "v-float"
+
+const anchorEl = useTemplateRef("anchorEl")
+const floatingEl = useTemplateRef("floatingEl")
+
+const context = useFloating(anchorEl, floatingEl, {
+  placement: "top",
+  middlewares: [offset(8)],
+})
+
+useHover(context)
+</script>
+
+<template>
+  <button ref="anchorEl">Hover me</button>
+
+  <div v-if="context.open.value" ref="floatingEl" :style="context.floatingStyles.value">
+    This is a tooltip
+  </div>
+</template>
+```
+
+### Dropdown Menu
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef } from "vue"
+import { useFloating, useClick, useEscapeKey, offset, flip, shift } from "v-float"
+
+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({
+  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>Menu Item 1</div>
+    <div>Menu Item 2</div>
+    <div>Menu Item 3</div>
+  </div>
+</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>
 

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

@@ -2,4 +2,6 @@ export * from './use-click';
 export * from './use-escape-key';
 export * from './use-focus';
 export * from './use-hover';
+export * from './use-list-navigation';
+export * from './use-focus-trap';
 //# 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,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA"}

package/dist/composables/interactions/navigation-strategies.d.ts

@@ -0,0 +1,36 @@
+export type NavigationAction = {
+    type: "navigate";
+    index: number | null;
+} | {
+    type: "close";
+};
+export interface StrategyContext {
+    current: number | null;
+    items: Array<HTMLElement | null>;
+    isRtl: boolean;
+    loop: boolean;
+    allowEscape: boolean;
+    isVirtual: boolean;
+    cols: number;
+    nested: boolean;
+    isDisabled: (index: number) => boolean;
+    findNextEnabled: (start: number, dir: 1 | -1, wrap: boolean) => number | null;
+    getFirstEnabledIndex: () => number | null;
+    getLastEnabledIndex: () => number | null;
+}
+export interface NavigationStrategy {
+    handleKey(key: string, context: StrategyContext): NavigationAction | null;
+}
+export declare class VerticalNavigationStrategy implements NavigationStrategy {
+    handleKey(key: string, context: StrategyContext): NavigationAction | null;
+}
+export declare class HorizontalNavigationStrategy implements NavigationStrategy {
+    handleKey(key: string, context: StrategyContext): NavigationAction | null;
+}
+export declare class GridNavigationStrategy implements NavigationStrategy {
+    private fallbackToLinear;
+    private loopDirection;
+    constructor(fallbackToLinear?: boolean, loopDirection?: "row" | "next");
+    handleKey(key: string, context: StrategyContext): NavigationAction | null;
+}
+//# sourceMappingURL=navigation-strategies.d.ts.map

package/dist/composables/interactions/navigation-strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-strategies.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/navigation-strategies.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAA;AAE7F,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,KAAK,EAAE,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;IAChC,KAAK,EAAE,OAAO,CAAA;IACd,IAAI,EAAE,OAAO,CAAA;IACb,WAAW,EAAE,OAAO,CAAA;IACpB,SAAS,EAAE,OAAO,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;IACf,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAA;IACtC,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,CAAA;IAC7E,oBAAoB,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACzC,mBAAmB,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,CAAA;CAC1E;AAkCD,qBAAa,0BAA2B,YAAW,kBAAkB;IACnE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI;CAa1E;AAED,qBAAa,4BAA6B,YAAW,kBAAkB;IACrE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI;CAY1E;AAED,qBAAa,sBAAuB,YAAW,kBAAkB;IAE7D,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,aAAa;gBADb,gBAAgB,GAAE,OAAe,EACjC,aAAa,GAAE,KAAK,GAAG,MAAc;IAG/C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI;CA8K1E"}

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

@@ -0,0 +1,41 @@
+import { MaybeRefOrGetter } from 'vue';
+import { FloatingContext } from '../positioning/use-floating';
+import { TreeNode } from '../positioning/use-floating-tree';
+export interface UseFocusTrapOptions {
+    /** Enables the focus trap when true. @default true */
+    enabled?: MaybeRefOrGetter<boolean>;
+    /** When true, hides/inerts content outside the trap. @default false */
+    modal?: MaybeRefOrGetter<boolean>;
+    /** When true, inserts hidden focus guards to aid wrap-around. @default true */
+    guards?: MaybeRefOrGetter<boolean>;
+    /** Wrap order preference when cycling with Tab. @default ['content'] */
+    order?: MaybeRefOrGetter<Array<"content" | "reference" | "floating">>;
+    /** Initial focus target policy on activation. @default 'first' */
+    initialFocus?: MaybeRefOrGetter<number | HTMLElement | (() => HTMLElement | null) | "first" | "last">;
+    /** Returns focus to previously focused element on deactivate. @default true */
+    returnFocus?: MaybeRefOrGetter<boolean>;
+    /** Restores focus to nearest tabbable if active node disappears. @default false */
+    restoreFocus?: MaybeRefOrGetter<boolean>;
+    /** On non-modal, close when focus escapes the trap. @default false */
+    closeOnFocusOut?: MaybeRefOrGetter<boolean>;
+    /** Pass preventScroll to focus operations. @default true */
+    preventScroll?: MaybeRefOrGetter<boolean>;
+    /** Apply `inert` (when supported) to outside elements while modal. @default false */
+    outsideElementsInert?: MaybeRefOrGetter<boolean>;
+}
+export interface UseFocusTrapReturn {
+    cleanup: () => void;
+}
+/**
+ * Traps keyboard focus within the floating element, optionally in a modal manner.
+ *
+ * Supports nested traps; only the deepest open node activates trapping when used with a tree.
+ * Provides optional focus guards, initial focus, focus return, and close-on-escape behavior.
+ *
+ * @param context - FloatingContext or TreeNode<FloatingContext> to trap within
+ * @param options - Configuration options controlling trap behavior
+ * @returns Cleanup API
+ */
+export declare function useFocusTrap(context: FloatingContext | TreeNode<FloatingContext>, options?: UseFocusTrapOptions): UseFocusTrapReturn;
+export type { FloatingContext };
+//# sourceMappingURL=use-focus-trap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-focus-trap.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/use-focus-trap.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,gBAAgB,EAOtB,MAAM,KAAK,CAAA;AACZ,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAC7E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6CAA6C,CAAA;AAY3E,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,OAAO,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IACnC,uEAAuE;IACvE,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IACjC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAClC,wEAAwE;IACxE,KAAK,CAAC,EAAE,gBAAgB,CAAC,KAAK,CAAC,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC,CAAC,CAAA;IACrE,kEAAkE;IAClE,YAAY,CAAC,EAAE,gBAAgB,CAC7B,MAAM,GAAG,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,OAAO,GAAG,MAAM,CACrE,CAAA;IACD,+EAA+E;IAC/E,WAAW,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IACvC,mFAAmF;IACnF,YAAY,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IACxC,sEAAsE;IACtE,eAAe,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAC3C,4DAA4D;IAC5D,aAAa,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IACzC,qFAAqF;IACrF,oBAAoB,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;CACjD;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,eAAe,GAAG,QAAQ,CAAC,eAAe,CAAC,EACpD,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CA+cpB;AAMD,YAAY,EAAE,eAAe,EAAE,CAAA"}

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":"AACA,OAAO,EAEL,KAAK,gBAAgB,EAOtB,MAAM,KAAK,CAAA;AACZ,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAC7E,OAAO,KAAK,EAAE,IAAI,EAAY,MAAM,6CAA6C,CAAA;AAkBjF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,eAAoB,GAC5B,cAAc,CA8NhB;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;IAE/C;;OAEG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB"}
+{"version":3,"file":"use-focus.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/use-focus.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,gBAAgB,EAOtB,MAAM,KAAK,CAAA;AACZ,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAC7E,OAAO,KAAK,EAAE,IAAI,EAAY,MAAM,6CAA6C,CAAA;AAmBjF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,eAAoB,GAC5B,cAAc,CAsMhB;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;IAE/C;;OAEG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB"}

package/dist/composables/interactions/use-list-navigation.d.ts

@@ -0,0 +1,109 @@
+import { MaybeRefOrGetter, Ref } from 'vue';
+import { FloatingContext } from '../positioning/use-floating';
+import { TreeNode } from '../positioning/use-floating-tree';
+/**
+ * Options for configuring list-style keyboard/mouse navigation behavior.
+ *
+ * This interface drives how items in a floating list/grid are navigated,
+ * focused, and announced (including support for virtual focus).
+ */
+export interface UseListNavigationOptions {
+    /**
+     * Reactive collection of list item elements in DOM order.
+     * Null entries are allowed while items mount/unmount.
+     */
+    listRef: Ref<Array<HTMLElement | null>>;
+    /**
+     * The currently active (navigated) index. Null means no active item.
+     */
+    activeIndex?: MaybeRefOrGetter<number | null>;
+    /**
+     * Callback invoked when navigation sets a new active index.
+     */
+    onNavigate?: (index: number | null) => void;
+    /**
+     * Whether navigation behavior is enabled.
+     */
+    enabled?: MaybeRefOrGetter<boolean>;
+    /**
+     * If true, arrow-key navigation wraps from end-to-start and vice versa.
+     */
+    loop?: MaybeRefOrGetter<boolean>;
+    /**
+     * Primary navigation orientation.
+     * - "vertical": Up/Down to navigate
+     * - "horizontal": Left/Right to navigate
+     * - "both": Grid navigation (supports cols/itemSizes)
+     */
+    orientation?: MaybeRefOrGetter<"vertical" | "horizontal" | "both">;
+    /**
+     * Indices that should be treated as disabled and skipped by navigation.
+     * Can be an array of indices or a predicate.
+     */
+    disabledIndices?: Array<number> | ((index: number) => boolean);
+    /**
+     * If true, hovering an item moves the active index to that item.
+     */
+    focusItemOnHover?: MaybeRefOrGetter<boolean>;
+    /**
+     * If true, pressing an arrow key when closed opens and moves focus.
+     */
+    openOnArrowKeyDown?: MaybeRefOrGetter<boolean>;
+    /**
+     * Controls automatic scrolling when the active item changes.
+     * true for default "nearest" behavior or a custom ScrollIntoViewOptions.
+     */
+    scrollItemIntoView?: boolean | ScrollIntoViewOptions;
+    /**
+     * Index to prefer when opening (e.g., currently selected option).
+     */
+    selectedIndex?: MaybeRefOrGetter<number | null>;
+    /**
+     * Controls focusing an item when the list opens.
+     * - true: always focus an item
+     * - false: never focus an item
+     * - "auto": focus based on input modality/heuristics
+     */
+    focusItemOnOpen?: MaybeRefOrGetter<boolean | "auto">;
+    /**
+     * Whether this list is nested inside another navigable list.
+     * Affects cross-orientation close/open key handling.
+     */
+    nested?: MaybeRefOrGetter<boolean>;
+    /**
+     * Parent list orientation when nested, for cross-navigation behavior.
+     */
+    parentOrientation?: MaybeRefOrGetter<"vertical" | "horizontal" | "both">;
+    /**
+     * Right-to-left layout flag affecting horizontal arrow semantics.
+     */
+    rtl?: MaybeRefOrGetter<boolean>;
+    /**
+     * Enables virtual focus mode (aria-activedescendant) instead of DOM focus.
+     */
+    virtual?: MaybeRefOrGetter<boolean>;
+    /**
+     * Receives the HTMLElement corresponding to the virtual active item.
+     * Used for aria-activedescendant and screen reader announcement.
+     */
+    virtualItemRef?: Ref<HTMLElement | null>;
+    /**
+     * Column count for grid navigation when orientation is "both".
+     */
+    cols?: MaybeRefOrGetter<number>;
+    /**
+     * If true, allows escaping to a null active index via keyboard (e.g., ArrowDown on last).
+     */
+    allowEscape?: MaybeRefOrGetter<boolean>;
+    /**
+     * Defines the wrapping behavior for grid navigation when moving horizontally past the end of a row.
+     * - "row": Wraps to the start of the *same* row (default).
+     * - "next": Moves to the start of the *next* row (or previous row if moving left).
+     */
+    gridLoopDirection?: MaybeRefOrGetter<"row" | "next">;
+}
+export interface UseListNavigationReturn {
+    cleanup: () => void;
+}
+export declare function useListNavigation(context: FloatingContext | TreeNode<FloatingContext>, options: UseListNavigationOptions): UseListNavigationReturn;
+//# sourceMappingURL=use-list-navigation.d.ts.map

package/dist/composables/interactions/use-list-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-list-navigation.d.ts","sourceRoot":"","sources":["../../../src/composables/interactions/use-list-navigation.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,gBAAgB,EAErB,KAAK,GAAG,EAKT,MAAM,KAAK,CAAA;AACZ,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAC7E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6CAA6C,CAAA;AAY3E;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC,CAAA;IAEvC;;OAEG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAE7C;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAE3C;;OAEG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEnC;;OAEG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEhC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC,CAAA;IAElE;;;OAGG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAA;IAE9D;;OAEG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAE5C;;OAEG;IACH,kBAAkB,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAE9C;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,GAAG,qBAAqB,CAAA;IAEpD;;OAEG;IACH,aAAa,CAAC,EAAE,gBAAgB,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAE/C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,gBAAgB,CAAC,OAAO,GAAG,MAAM,CAAC,CAAA;IAEpD;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAElC;;OAEG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,CAAC,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC,CAAA;IAExE;;OAEG;IACH,GAAG,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAE/B;;OAEG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEnC;;;OAGG;IACH,cAAc,CAAC,EAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;IAExC;;OAEG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAA;IAE/B;;OAEG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAEvC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,CAAC,KAAK,GAAG,MAAM,CAAC,CAAA;CACrD;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,eAAe,GAAG,QAAQ,CAAC,eAAe,CAAC,EACpD,OAAO,EAAE,wBAAwB,GAChC,uBAAuB,CA+VzB"}

package/dist/composables/utils/is-using-keyboard.d.ts

@@ -0,0 +1,2 @@
+export declare const isUsingKeyboard: Readonly<import('vue').Ref<boolean, boolean>>;
+//# sourceMappingURL=is-using-keyboard.d.ts.map

package/dist/composables/utils/is-using-keyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-using-keyboard.d.ts","sourceRoot":"","sources":["../../../src/composables/utils/is-using-keyboard.ts"],"names":[],"mappings":"AAkCA,eAAO,MAAM,eAAe,+CAAuB,CAAA"}

package/dist/composables/utils/use-active-descendant.d.ts

@@ -0,0 +1,8 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+export interface UseActiveDescendantOptions {
+    virtual: MaybeRefOrGetter<boolean>;
+    open: Ref<boolean>;
+    virtualItemRef?: Ref<HTMLElement | null>;
+}
+export declare function useActiveDescendant(anchorEl: ComputedRef<HTMLElement | null>, listRef: Ref<Array<HTMLElement | null>>, activeIndex: MaybeRefOrGetter<number | null>, options: UseActiveDescendantOptions): void;
+//# sourceMappingURL=use-active-descendant.d.ts.map

package/dist/composables/utils/use-active-descendant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-active-descendant.d.ts","sourceRoot":"","sources":["../../../src/composables/utils/use-active-descendant.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,GAAG,EAAkB,MAAM,KAAK,CAAA;AAEjG,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAClC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;IAClB,cAAc,CAAC,EAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CACzC;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,WAAW,CAAC,WAAW,GAAG,IAAI,CAAC,EACzC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC,EACvC,WAAW,EAAE,gBAAgB,CAAC,MAAM,GAAG,IAAI,CAAC,EAC5C,OAAO,EAAE,0BAA0B,GAClC,IAAI,CAmBN"}