@vunset/vue 0.0.0-stage → 1.0.0-rc.2

package/dist/shared/use-menu.d.ts

@@ -0,0 +1,106 @@
+import { type ComputedRef, type MaybeRefOrGetter, type Ref, type WritableComputedRef } from 'vue';
+import { type TransitionStatus } from './use-transition-status';
+import { type Align, type Side, type UsePositioningOptions, type VirtualAnchor } from './use-positioning';
+export interface MenuParentContext {
+    /** The id of the submenu currently open within this menu, if any. */
+    openSubmenu: Ref<string | null>;
+    /** A submenu that replaced an already-open sibling, and so skips its animation. */
+    switchedInto: Ref<string | null>;
+    setOpenSubmenu: (id: string | null) => void;
+    /** Focuses this menu's trigger. Used when a submenu closes via ArrowLeft. */
+    focusTrigger: () => void;
+    /** Closes this menu and every ancestor above it. */
+    closeChain: () => void;
+    /** Keeps a hover-opened ancestor from closing while the pointer is inside a descendant of it. */
+    holdHover: () => void;
+    /** Releases the hold, letting the chain close after its delay. */
+    releaseHover: () => void;
+}
+export interface MenuState {
+    /**
+     * Whether the menu is open.
+     * @attribute `data-open` while open, `data-closed` otherwise
+     */
+    open: boolean;
+    /**
+     * The side of the trigger the menu ended up on.
+     * @attribute `data-side="…"`
+     */
+    side: Side;
+    /**
+     * How the menu lines up along that side.
+     * @attribute `data-align="…"`
+     */
+    align: Align;
+    /** Whether the trigger ignores interaction. */
+    disabled: boolean;
+    /**
+     * Where the menu is in its enter or exit animation.
+     * @attribute `data-enter-from` as it enters, `data-leave-to` as it leaves
+     */
+    transitionStatus: TransitionStatus;
+}
+export interface UseMenuOptions extends UsePositioningOptions {
+    open?: MaybeRefOrGetter<boolean | undefined>;
+    defaultOpen?: MaybeRefOrGetter<boolean | undefined>;
+    disabled?: MaybeRefOrGetter<boolean | undefined>;
+    /** Close the menu after an item is chosen. @default true */
+    closeOnSelect?: MaybeRefOrGetter<boolean | undefined>;
+    /** Open on hover rather than only on click. @default false */
+    openOnHover?: MaybeRefOrGetter<boolean | undefined>;
+    /** How long the pointer must rest on the trigger before it opens. @default 100 */
+    delay?: MaybeRefOrGetter<number | undefined>;
+    /** How long the menu waits after the pointer leaves before closing. @default 150 */
+    closeDelay?: MaybeRefOrGetter<number | undefined>;
+    /** Whether arrow keys wrap from the last item to the first. @default true */
+    loop?: MaybeRefOrGetter<boolean | undefined>;
+    onChange?: (open: boolean) => void;
+}
+export interface UseMenuReturn {
+    open: WritableComputedRef<boolean>;
+    state: ComputedRef<MenuState>;
+    present: Ref<boolean>;
+    triggerProps: ComputedRef<Record<string, unknown>>;
+    positionerProps: ComputedRef<Record<string, unknown>>;
+    popupProps: ComputedRef<Record<string, unknown>>;
+    arrowProps: ComputedRef<Record<string, unknown>>;
+    /** Builds props for one item. Call per item. */
+    getItemProps: (itemOptions?: MenuItemOptions) => Record<string, unknown>;
+    close: () => void;
+    /** Opens the menu and focuses its first item once it is placed, as the keyboard does. */
+    openAndFocusFirst: () => Promise<void>;
+    /** Anchors the menu to a point rather than to its trigger. Pass `null` to go back to the trigger. */
+    setAnchor: (anchor: VirtualAnchor | null) => void;
+    /** Where focus goes back to on close while there is no trigger element: a context menu's. */
+    setReturnFocus: (element: HTMLElement | null) => void;
+}
+export type MenuItemRole = 'menuitem' | 'menuitemcheckbox' | 'menuitemradio';
+export interface MenuItemOptions {
+    disabled?: boolean;
+    /** @default 'menuitem' */
+    role?: MenuItemRole;
+    checked?: boolean;
+    /** Whether choosing this item closes the menu. @default true */
+    closeOnClick?: boolean;
+    onSelect?: (event: Event) => void;
+}
+export declare function useMenu(options?: UseMenuOptions): UseMenuReturn;
+export declare const provideMenuContext: (value: UseMenuReturn) => UseMenuReturn, useMenuContext: () => UseMenuReturn;
+export type MenuRadioValue = string | number;
+export interface MenuRadioGroupContext {
+    value: Ref<MenuRadioValue | undefined>;
+    select: (value: MenuRadioValue, event: Event) => void;
+    disabled: () => boolean;
+}
+export declare const provideMenuRadioGroupContext: (value: MenuRadioGroupContext) => MenuRadioGroupContext, useMenuRadioGroupContext: () => MenuRadioGroupContext;
+export interface MenuGroupContext {
+    labelId: string;
+    registerLabel: () => () => void;
+}
+export declare const provideMenuGroupContext: (value: MenuGroupContext) => MenuGroupContext, useMenuGroupContext: () => MenuGroupContext;
+/** What a checkbox or radio item tells its indicator. */
+export interface MenuItemIndicatorContext {
+    checked: () => boolean;
+    disabled: () => boolean;
+}
+export declare const provideMenuItemIndicatorContext: (value: MenuItemIndicatorContext) => MenuItemIndicatorContext, useMenuItemIndicatorContext: () => MenuItemIndicatorContext;

package/dist/shared/use-menu.js

@@ -0,0 +1,329 @@
+import { dataAttrs } from "./data-attrs.js";
+import { useControlled } from "./use-controlled.js";
+import { createContext } from "./context.js";
+import { anchoredStateAttrs } from "./popup-state-attrs.js";
+import { useTransitionStatus } from "./use-transition-status.js";
+import { useExitAnimation } from "./use-exit-animation.js";
+import { provideSurface } from "./surface.js";
+import { usePositioning } from "./use-positioning.js";
+import { useDismiss } from "./use-dismiss.js";
+import { elementOf } from "./element-of.js";
+import { useTypeahead } from "./use-typeahead.js";
+import { useRovingFocus } from "./use-roving-focus.js";
+import { useMenubarContext } from "./use-menubar.js";
+import { computed, nextTick, onScopeDispose, ref, toValue, useId, watch } from "vue";
+//#region src/shared/use-menu.ts
+var { provideContext: provideMenuParent, useOptionalContext: useMenuParent } = createContext("MenuParent");
+var ITEM_SELECTOR = "[role=\"menuitem\"],[role=\"menuitemcheckbox\"],[role=\"menuitemradio\"]";
+function useMenu(options = {}) {
+	const menuId = useId();
+	const triggerId = useId();
+	const menubar = useMenubarContext();
+	const parent = useMenuParent();
+	const isSubmenu = parent !== null;
+	const disabled = () => (toValue(options.disabled) ?? false) || (menubar?.disabled() ?? false);
+	const localOpen = useControlled({
+		value: () => toValue(options.open),
+		defaultValue: () => toValue(options.defaultOpen) ?? false,
+		onChange: options.onChange,
+		prop: "open",
+		empty: false,
+		name: "useMenu",
+		label: "open"
+	});
+	const open = computed({
+		get() {
+			if (parent) return parent.openSubmenu.value === menuId;
+			if (menubar) return menubar.openMenu.value === menuId;
+			return localOpen.value;
+		},
+		set(value) {
+			if (parent) {
+				parent.setOpenSubmenu(value ? menuId : null);
+				options.onChange?.(value);
+			} else if (menubar) {
+				if (value) menubar.open(menuId);
+				else menubar.close();
+				options.onChange?.(value);
+			} else localOpen.value = value;
+		}
+	});
+	const openSubmenu = ref(null);
+	const submenuSwitchedInto = ref(null);
+	const { mounted, transitionStatus, setMounted } = useTransitionStatus(() => open.value, {
+		skipEnter: () => menubar?.switchedInto.value === menuId || parent?.switchedInto.value === menuId,
+		skipExit: () => {
+			const took = menubar?.switchedInto.value ?? parent?.switchedInto.value ?? null;
+			return took !== null && took !== menuId;
+		}
+	});
+	const positioning = usePositioning({
+		side: () => toValue(options.side) ?? (isSubmenu ? "right" : "bottom"),
+		align: () => toValue(options.align) ?? "start",
+		sideOffset: () => toValue(options.sideOffset) ?? (isSubmenu ? 0 : 4),
+		alignOffset: options.alignOffset,
+		collisionPadding: options.collisionPadding,
+		enabled: () => mounted.value
+	});
+	const triggerEl = positioning.anchorRef;
+	const popupEl = ref(null);
+	let returnFocus = null;
+	const focusTrigger = () => (triggerEl.value ?? returnFocus)?.focus();
+	const state = computed(() => ({
+		open: open.value,
+		side: positioning.renderedSide.value,
+		align: positioning.renderedAlign.value,
+		disabled: disabled(),
+		transitionStatus: transitionStatus.value
+	}));
+	const hooks = computed(() => dataAttrs(state.value, { ...anchoredStateAttrs }));
+	provideMenuParent({
+		openSubmenu,
+		switchedInto: submenuSwitchedInto,
+		setOpenSubmenu: (id) => {
+			submenuSwitchedInto.value = id !== null && openSubmenu.value !== null && openSubmenu.value !== id ? id : null;
+			openSubmenu.value = id;
+		},
+		focusTrigger,
+		holdHover,
+		releaseHover,
+		closeChain: () => {
+			open.value = false;
+			if (parent) parent.closeChain();
+			else focusTrigger();
+		}
+	});
+	const roving = useRovingFocus({
+		container: popupEl,
+		itemSelector: ITEM_SELECTOR,
+		orientation: "vertical",
+		loop: () => toValue(options.loop) ?? true
+	});
+	const typeahead = useTypeahead({ items: () => roving.items() });
+	function close(restoreFocus = true) {
+		open.value = false;
+		if (restoreFocus) focusTrigger();
+	}
+	useDismiss({
+		enabled: () => mounted.value,
+		elements: () => [popupEl.value, triggerEl.value],
+		onDismiss: (reason) => {
+			close(reason === "escape-key");
+		}
+	});
+	useExitAnimation({
+		open: () => open.value,
+		mounted,
+		setMounted,
+		element: popupEl
+	});
+	const hoverEnabled = () => !isSubmenu && ((toValue(options.openOnHover) ?? false) || (menubar?.openOnHover() ?? false));
+	let hoverTimer;
+	const pinned = ref(false);
+	watch(() => open.value, (isOpen) => {
+		if (!isOpen) pinned.value = false;
+	});
+	function cancelHover() {
+		if (hoverTimer !== void 0) {
+			clearTimeout(hoverTimer);
+			hoverTimer = void 0;
+		}
+	}
+	function scheduleHover(next) {
+		if (!next && pinned.value) return;
+		cancelHover();
+		const wait = next ? toValue(options.delay) ?? 100 : toValue(options.closeDelay) ?? 150;
+		if (wait <= 0) {
+			open.value = next;
+			return;
+		}
+		hoverTimer = setTimeout(() => {
+			hoverTimer = void 0;
+			if (!next && !open.value) return;
+			open.value = next;
+		}, wait);
+	}
+	function holdHover() {
+		if (hoverEnabled()) cancelHover();
+		parent?.holdHover();
+	}
+	function releaseHover() {
+		if (hoverEnabled()) scheduleHover(false);
+		parent?.releaseHover();
+	}
+	onScopeDispose(cancelHover);
+	async function openAndFocusFirst() {
+		open.value = true;
+		if (positioning.isPositioned.value) {
+			await nextTick();
+			roving.focusAt(0);
+			return;
+		}
+		focusFirstWhenPlaced = true;
+	}
+	let focusFirstWhenPlaced = false;
+	watch(() => positioning.isPositioned.value, async (placed) => {
+		if (!placed || !focusFirstWhenPlaced) return;
+		focusFirstWhenPlaced = false;
+		await nextTick();
+		roving.focusAt(0);
+	}, { flush: "post" });
+	const triggerProps = computed(() => ({
+		...hooks.value,
+		"data-part": "trigger",
+		id: triggerId,
+		type: "button",
+		role: menubar || isSubmenu ? "menuitem" : void 0,
+		"data-menubar-trigger": menubar && !isSubmenu ? menuId : void 0,
+		"data-submenu-trigger": isSubmenu ? menuId : void 0,
+		"aria-haspopup": "menu",
+		"aria-expanded": open.value,
+		"aria-controls": mounted.value ? menuId : void 0,
+		disabled: disabled() || void 0,
+		tabindex: isSubmenu ? -1 : menubar ? open.value || !menubar.isActive.value ? 0 : -1 : void 0,
+		ref: (el) => {
+			triggerEl.value = elementOf(el);
+		},
+		onClick(event) {
+			if (disabled()) return;
+			if (isSubmenu) {
+				event.stopPropagation();
+				open.value = true;
+				return;
+			}
+			if (hoverEnabled() && open.value && !pinned.value) {
+				cancelHover();
+				pinned.value = true;
+				return;
+			}
+			open.value = !open.value;
+		},
+		onPointerenter() {
+			if (disabled()) return;
+			if (isSubmenu) {
+				open.value = true;
+				return;
+			}
+			if (menubar?.isActive.value) {
+				menubar.open(menuId);
+				return;
+			}
+			if (hoverEnabled()) scheduleHover(true);
+		},
+		onPointerleave() {
+			if (hoverEnabled()) scheduleHover(false);
+		},
+		onKeydown(event) {
+			if (disabled()) return;
+			const openKey = isSubmenu ? "ArrowRight" : "ArrowDown";
+			if (event.key === openKey || event.key === "Enter" || event.key === " ") {
+				event.preventDefault();
+				event.stopPropagation();
+				openAndFocusFirst();
+			}
+		}
+	}));
+	const popupProps = computed(() => ({
+		...hooks.value,
+		id: menuId,
+		role: "menu",
+		"aria-labelledby": triggerId,
+		tabindex: -1,
+		ref: (el) => {
+			popupEl.value = el ?? null;
+		},
+		onPointerenter: holdHover,
+		onPointerleave: releaseHover,
+		onKeydown(event) {
+			if (roving.onKeydown(event)) return;
+			if (isSubmenu && event.key === "ArrowLeft") {
+				event.preventDefault();
+				event.stopPropagation();
+				close(true);
+				return;
+			}
+			if (menubar && !isSubmenu && (event.key === "ArrowLeft" || event.key === "ArrowRight")) {
+				event.preventDefault();
+				menubar.focusSibling(event.key === "ArrowRight" ? 1 : -1);
+				return;
+			}
+			if (event.key === "Tab") {
+				close(false);
+				return;
+			}
+			typeahead.onKeydown(event);
+		}
+	}));
+	const ITEM_PARTS = {
+		menuitem: "item",
+		menuitemcheckbox: "checkbox-item",
+		menuitemradio: "radio-item"
+	};
+	function getItemProps(itemOptions = {}) {
+		const itemDisabled = itemOptions.disabled ?? false;
+		const role = itemOptions.role ?? "menuitem";
+		const { checked } = itemOptions;
+		function select(event) {
+			if (itemDisabled) return;
+			itemOptions.onSelect?.(event);
+			if (!((itemOptions.closeOnClick ?? true) && (toValue(options.closeOnSelect) ?? true))) return;
+			if (parent) {
+				open.value = false;
+				parent.closeChain();
+			} else close();
+		}
+		return {
+			"data-part": ITEM_PARTS[role],
+			role,
+			tabindex: -1,
+			"aria-disabled": itemDisabled || void 0,
+			"aria-checked": role === "menuitem" ? void 0 : Boolean(checked),
+			"data-checked": checked === true ? "" : void 0,
+			"data-unchecked": checked === false ? "" : void 0,
+			"data-disabled": itemDisabled ? "" : void 0,
+			onClick: select,
+			onKeydown(event) {
+				if (event.key === "Enter" || event.key === " ") {
+					event.preventDefault();
+					const el = event.currentTarget;
+					if (el instanceof HTMLAnchorElement && el.hasAttribute("href") && !itemDisabled) el.click();
+					else select(event);
+				}
+			},
+			onPointermove(event) {
+				if (itemDisabled) return;
+				event.currentTarget.focus();
+				openSubmenu.value = null;
+			}
+		};
+	}
+	provideSurface({
+		present: mounted,
+		state,
+		popupProps,
+		positionerProps: positioning.positionerProps,
+		arrowProps: positioning.arrowProps
+	});
+	return {
+		open,
+		state,
+		present: mounted,
+		triggerProps,
+		positionerProps: positioning.positionerProps,
+		popupProps,
+		arrowProps: positioning.arrowProps,
+		getItemProps,
+		close,
+		openAndFocusFirst,
+		setAnchor: positioning.setVirtualAnchor,
+		setReturnFocus: (element) => {
+			returnFocus = element;
+		}
+	};
+}
+var { provideContext: provideMenuContext, useContext: useMenuContext } = createContext("Menu");
+var { provideContext: provideMenuRadioGroupContext, useContext: useMenuRadioGroupContext } = createContext("MenuRadioGroup");
+var { provideContext: provideMenuGroupContext, useContext: useMenuGroupContext } = createContext("MenuGroup");
+var { provideContext: provideMenuItemIndicatorContext, useContext: useMenuItemIndicatorContext } = createContext("MenuItemIndicator");
+//#endregion
+export { provideMenuContext, provideMenuGroupContext, provideMenuItemIndicatorContext, provideMenuRadioGroupContext, useMenu, useMenuContext, useMenuGroupContext, useMenuItemIndicatorContext, useMenuRadioGroupContext };

package/dist/shared/use-menubar.d.ts

@@ -0,0 +1,39 @@
+import { type ComputedRef, type MaybeRefOrGetter, type Ref } from 'vue';
+export interface MenubarContextValue {
+    openMenu: Ref<string | null>;
+    switchedInto: Ref<string | null>;
+    isActive: ComputedRef<boolean>;
+    open: (id: string) => void;
+    close: () => void;
+    containerRef: Ref<HTMLElement | null>;
+    /** Moves focus to the adjacent trigger, used when a menu handles Arrow keys. */
+    focusSibling: (delta: number) => void;
+    disabled: () => boolean;
+    openOnHover: () => boolean;
+    /** Props for a link in the bar, beside the menus: `MenubarLink`'s. */
+    getLinkProps: (link?: {
+        disabled?: boolean;
+    }) => Record<string, unknown>;
+}
+export declare const provideMenubarContext: (value: MenubarContextValue) => MenubarContextValue, useMenubarContext: () => MenubarContextValue | null;
+export interface UseMenubarOptions {
+    disabled?: MaybeRefOrGetter<boolean>;
+    loop?: MaybeRefOrGetter<boolean>;
+    /** Open the bar on hover, without a first click. @default false */
+    openOnHover?: MaybeRefOrGetter<boolean>;
+}
+export declare function useMenubar(options?: UseMenubarOptions): {
+    rootProps: ComputedRef<{
+        'data-part': string;
+        role: string;
+        'aria-orientation': "horizontal";
+        ref: (el: unknown) => void;
+        onKeydown(event: KeyboardEvent): void;
+    }>;
+    openMenu: Ref<string | null, string | null>;
+    isActive: ComputedRef<boolean>;
+    open: (id: string) => void;
+    close: () => void;
+    focusSibling: (delta: number) => void;
+    containerRef: Ref<HTMLElement | null, HTMLElement | null>;
+};

package/dist/shared/use-menubar.js

@@ -0,0 +1,94 @@
+import { createContext } from "./context.js";
+import { useRovingFocus } from "./use-roving-focus.js";
+import { computed, ref, toValue } from "vue";
+//#region src/shared/use-menubar.ts
+var BAR_ITEMS = "[data-menubar-trigger], [data-menubar-link]";
+var { provideContext: provideMenubarContext, useOptionalContext: useMenubarContext } = createContext("Menubar");
+function useMenubar(options = {}) {
+	const containerRef = ref(null);
+	const openMenu = ref(null);
+	const switchedInto = ref(null);
+	const disabled = () => toValue(options.disabled) ?? false;
+	const openOnHover = () => toValue(options.openOnHover) ?? false;
+	const isActive = computed(() => openMenu.value !== null);
+	const roving = useRovingFocus({
+		container: containerRef,
+		itemSelector: BAR_ITEMS,
+		orientation: "horizontal",
+		loop: () => toValue(options.loop) ?? true
+	});
+	function open(id) {
+		if (disabled()) return;
+		switchedInto.value = openMenu.value !== null && openMenu.value !== id ? id : null;
+		openMenu.value = id;
+	}
+	function close() {
+		openMenu.value = null;
+		switchedInto.value = null;
+	}
+	function focusSibling(delta) {
+		const list = roving.items();
+		if (list.length === 0) return;
+		let index = list.indexOf(document.activeElement);
+		if (index === -1 && openMenu.value) index = list.findIndex((el) => el.dataset.menubarTrigger === openMenu.value);
+		const target = list[index === -1 ? 0 : (index + delta + list.length) % list.length];
+		target.focus();
+		if (openMenu.value) {
+			const id = target.dataset.menubarTrigger;
+			if (id) open(id);
+			else close();
+		}
+	}
+	function getLinkProps(link = {}) {
+		const off = disabled() || (link.disabled ?? false);
+		return {
+			"data-part": "menubar-link",
+			"data-menubar-link": "",
+			role: "menuitem",
+			tabindex: isActive.value ? -1 : 0,
+			"aria-disabled": off || void 0,
+			"data-disabled": off ? "" : void 0,
+			onClick(event) {
+				if (off) event.preventDefault();
+				else close();
+			},
+			onPointerenter() {
+				if (isActive.value) close();
+			}
+		};
+	}
+	provideMenubarContext({
+		openMenu,
+		switchedInto,
+		isActive,
+		open,
+		close,
+		containerRef,
+		focusSibling,
+		disabled,
+		openOnHover,
+		getLinkProps
+	});
+	return {
+		rootProps: computed(() => ({
+			"data-part": "menubar",
+			role: "menubar",
+			"aria-orientation": "horizontal",
+			ref: (el) => {
+				containerRef.value = el ?? null;
+			},
+			onKeydown(event) {
+				if (!event.target?.matches(BAR_ITEMS)) return;
+				roving.onKeydown(event);
+			}
+		})),
+		openMenu,
+		isActive,
+		open,
+		close,
+		focusSibling,
+		containerRef
+	};
+}
+//#endregion
+export { provideMenubarContext, useMenubar, useMenubarContext };

package/dist/shared/use-part-props.d.ts

@@ -0,0 +1,8 @@
+import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
+/**
+ * Merges a composable's prop bag with the caller's fallthrough attrs.
+ *
+ * Components using it must declare `inheritAttrs: false`, or Vue applies the
+ * attrs a second time and the merge is bypassed.
+ */
+export declare function usePartProps(bag: MaybeRefOrGetter<Record<string, unknown>>): ComputedRef<Record<string, unknown>>;

package/dist/shared/use-part-props.js

@@ -0,0 +1,15 @@
+import { mergeProps as mergeProps$1 } from "./merge-props.js";
+import { computed, toValue, useAttrs } from "vue";
+//#region src/shared/use-part-props.ts
+/**
+* Merges a composable's prop bag with the caller's fallthrough attrs.
+*
+* Components using it must declare `inheritAttrs: false`, or Vue applies the
+* attrs a second time and the merge is bypassed.
+*/
+function usePartProps(bag) {
+	const attrs = useAttrs();
+	return computed(() => mergeProps$1(toValue(bag), attrs));
+}
+//#endregion
+export { usePartProps };

package/dist/shared/use-positioning.d.ts

@@ -0,0 +1,48 @@
+import { type ComputedRef, type MaybeRefOrGetter, type Ref } from 'vue';
+export type Side = 'top' | 'right' | 'bottom' | 'left';
+export type Align = 'start' | 'center' | 'end';
+export interface UsePositioningOptions {
+    /** Which side of the anchor to place the popup on. */
+    side?: MaybeRefOrGetter<Side | undefined>;
+    /** How the popup aligns along that side. */
+    align?: MaybeRefOrGetter<Align | undefined>;
+    /** Distance from the anchor, in pixels. */
+    sideOffset?: MaybeRefOrGetter<number | undefined>;
+    /** Shift along the alignment axis, in pixels. */
+    alignOffset?: MaybeRefOrGetter<number | undefined>;
+    /** Minimum distance from the viewport edge. */
+    collisionPadding?: MaybeRefOrGetter<number | undefined>;
+    /** Keep the popup anchored even when it would overflow, rather than flipping. */
+    sticky?: MaybeRefOrGetter<boolean | undefined>;
+    /** Sides to try, in order, when the preferred one does not fit. */
+    fallbackSides?: MaybeRefOrGetter<Side[] | undefined>;
+    /** Whether a popup may move to the perpendicular axis as a last resort @default true */
+    fallbackAxis?: MaybeRefOrGetter<boolean | undefined>;
+    /** `fixed` escapes clipping ancestors; `absolute` performs better. */
+    positionMethod?: MaybeRefOrGetter<'absolute' | 'fixed' | undefined>;
+    /** Distance the arrow keeps from the popup's corners. */
+    arrowPadding?: MaybeRefOrGetter<number | undefined>;
+    /** Whether positioning is active. Disabled while closed to avoid needless work. */
+    enabled?: MaybeRefOrGetter<boolean | undefined>;
+}
+export interface VirtualAnchor {
+    getBoundingClientRect: () => DOMRect;
+}
+export interface UsePositioningReturn {
+    anchorRef: Ref<HTMLElement | null>;
+    /** Anchors to a point instead. Pass `null` to go back to the element. */
+    setVirtualAnchor: (anchor: VirtualAnchor | null) => void;
+    popupRef: Ref<HTMLElement | null>;
+    arrowRef: Ref<HTMLElement | null>;
+    /** Bind to the element that owns the position. Keep animations off this one. */
+    positionerProps: ComputedRef<Record<string, unknown>>;
+    arrowProps: ComputedRef<Record<string, unknown>>;
+    /** The side actually used, which may differ from the request after a flip. */
+    renderedSide: ComputedRef<Side>;
+    renderedAlign: ComputedRef<Align>;
+    /** Whether the anchor has been scrolled out of view. */
+    hidden: ComputedRef<boolean>;
+    /** Whether the popup has been placed yet. */
+    isPositioned: Readonly<Ref<boolean>>;
+}
+export declare function usePositioning(options?: UsePositioningOptions): UsePositioningReturn;