ropav 0.2.0 → 0.3.0

package/dist/composables/drag-manager.d.ts

@@ -0,0 +1,132 @@
+import type { DndStringKey } from "../i18n/dnd";
+import type { DragEndEvent, DragItem, DropActivateEvent, DropEnterEvent, DropEvent, DropExitEvent, DropOperation, DropTarget as DropTargetDescriptor } from "../utils/dnd-types";
+import type { LocalizedString, LocalizedStringFormatter } from "@internationalized/string";
+import type { ComputedRef, Ref, ShallowRef } from "vue";
+/**
+ * The keyboard and screen reader drag session, ported from React Aria's `dnd/DragManager.ts`.
+ *
+ * Native HTML drag and drop is pointer-only: there is no key that starts a `dragstart`, and a
+ * screen reader's synthetic click cannot express one either. This module is the parallel
+ * implementation for those users — it takes over the document, walks focus between the registered
+ * drop targets, and calls the same callbacks the native path calls.
+ *
+ * **Module-level singletons on purpose.** A drag is one global gesture, so there is exactly one
+ * session, one registry of drop targets and one of drop items per document. React Aria keeps
+ * these at module scope for the same reason and the port must too: making them reactive
+ * per-component state would let two collections disagree about whether a drag is in flight.
+ */
+/** Anything that can hold focus. Plain `HTMLElement`, as everywhere else in this package. */
+type FocusableElement = HTMLElement;
+export interface DragManagerDropTarget {
+    element: FocusableElement;
+    preventFocusOnDrop?: boolean;
+    getDropOperation?: (types: Set<string>, allowedOperations: DropOperation[]) => DropOperation;
+    onDropEnter?: (event: DropEnterEvent, dragTarget: DragManagerDragTarget) => void;
+    onDropExit?: (event: DropExitEvent) => void;
+    onDropTargetEnter?: (target: DropTargetDescriptor | null) => void;
+    onDropActivate?: (event: DropActivateEvent, target: DropTargetDescriptor | null) => void;
+    onDrop?: (event: DropEvent, target: DropTargetDescriptor | null) => void;
+    onKeyDown?: (event: KeyboardEvent, dragTarget: DragManagerDragTarget) => void;
+    activateButtonRef?: ShallowRef<FocusableElement | null>;
+}
+export interface DragManagerDropItem {
+    element: FocusableElement;
+    target: DropTargetDescriptor;
+    getDropOperation?: (types: Set<string>, allowedOperations: DropOperation[]) => DropOperation;
+    activateButtonRef?: ShallowRef<FocusableElement | null>;
+}
+/**
+ * The message table, resolved in the locale that applies.
+ *
+ * Threaded in from `useDrag` rather than resolved here: this module is a singleton with no Vue
+ * scope, so it cannot inject a locale — only a composable can. Held as a ref so a locale change
+ * mid-drag still reaches the announcements.
+ */
+export type DndStringFormatter = ComputedRef<LocalizedStringFormatter<DndStringKey, LocalizedString>>;
+export interface DragManagerDragTarget {
+    element: FocusableElement;
+    items: DragItem[];
+    allowedDropOperations: DropOperation[];
+    onDragEnd?: (event: DragEndEvent) => void;
+}
+/**
+ * Register a drop target for the duration of a drag session, returning the unregister.
+ *
+ * Registering mid-session is normal rather than exceptional — a collection that mounts while a
+ * drag is in flight must join it — so the valid target list is recomputed on both ends.
+ */
+export declare const registerDropTarget: (target: DragManagerDropTarget) => (() => void);
+/** Register an individual item within a droppable collection, returning the unregister. */
+export declare const registerDropItem: (item: DragManagerDropItem) => (() => void);
+/**
+ * Start a keyboard or screen reader drag.
+ *
+ * Throws when one is already in flight. That is deliberate upstream and kept here: two
+ * overlapping sessions would both own the document's event listeners, and the second teardown
+ * would strip the first session's, leaving the page permanently swallowing pointer events.
+ *
+ * Setup is deferred a frame because the drag typically starts from a keystroke that is still
+ * propagating — attaching the capture listeners synchronously would make the session swallow the
+ * tail of the very event that started it.
+ */
+export declare const beginDragging: (target: DragManagerDragTarget, stringFormatter: DndStringFormatter) => void;
+/** Whether a keyboard or screen reader drag is in flight. */
+export declare const isVirtualDragging: () => boolean;
+/** Whether an element is inside a registered drop target. */
+export declare const isValidDropTarget: (element: Element) => boolean;
+/**
+ * The session in flight, as a ref that updates when one starts or ends.
+ *
+ * React Aria subscribes with `useState` + `useEffect`; the Vue shape is a shallow ref fed by the
+ * same subscription set. Read-only, because the session is owned by this module — a component
+ * ends a drag by calling into it, never by assigning here.
+ */
+export declare const useDragSession: () => Readonly<Ref<DragSession | null>>;
+export declare class DragSession {
+    dragTarget: DragManagerDragTarget;
+    validDropTargets: DragManagerDropTarget[];
+    currentDropTarget: DragManagerDropTarget | null;
+    currentDropItem: DragManagerDropItem | null;
+    dropOperation: DropOperation | null;
+    private mutationObserver;
+    private restoreAriaHidden;
+    private isVirtualClick;
+    private initialFocused;
+    private stringFormatter;
+    constructor(target: DragManagerDragTarget, stringFormatter: DndStringFormatter);
+    setup(): void;
+    teardown(): void;
+    onKeyDown(event: KeyboardEvent): void;
+    onKeyUp(event: KeyboardEvent): void;
+    getCurrentActivateButton(): FocusableElement | null;
+    onFocus(event: FocusEvent): void;
+    onBlur(event: FocusEvent): void;
+    onClick(event: MouseEvent): void;
+    onPointerDown(event: PointerEvent): void;
+    cancelEvent(event: Event): void;
+    updateValidDropTargets(): void;
+    next(): void;
+    previous(): void;
+    /**
+     * At either end of the target list, hand focus back to the element the drag came from.
+     *
+     * That element is always reachable, so it gives a user with no Escape key — an iPad keyboard,
+     * for one — somewhere to land and cancel from. If it has itself been hidden, there is nowhere
+     * to go and the cycle wraps instead.
+     */
+    private wrapToDragTarget;
+    findNearestDropTarget(): number;
+    setCurrentDropTarget(dropTarget: DragManagerDropTarget | null, item?: DragManagerDropItem): void;
+    end(): void;
+    cancel(): void;
+    drop(item?: DragManagerDropItem): void;
+    activate(dropTarget: DragManagerDropTarget | null, dropItem: DragManagerDropItem | null | undefined): void;
+}
+/**
+ * The session in flight, read once.
+ *
+ * The imperative sibling of `useDragSession`, for callers that are not inside an effect scope —
+ * an event handler deciding whether a keystroke belongs to a drag, or a test ending one.
+ */
+export declare const getDragSession: () => DragSession | null;
+export {};

package/dist/composables/drag-manager.js

@@ -0,0 +1,443 @@
+import { ariaHideOutside } from "../utils/aria-hide-outside.js";
+import { isVirtualClick, isVirtualPointerEvent } from "./use-press.js";
+import { announce } from "../utils/live-announcer.js";
+import { getTypes } from "../utils/dnd-data-transfer.js";
+import { getDragModality } from "./drag-modality.js";
+import { onScopeDispose, readonly, shallowRef } from "vue";
+//#region src/composables/drag-manager.ts
+var dropTargets = /* @__PURE__ */ new Map();
+var dropItems = /* @__PURE__ */ new Map();
+var subscriptions = /* @__PURE__ */ new Set();
+var dragSession = null;
+/**
+* Every event a drag session swallows while it owns the document.
+*
+* The session is a modal state: a stray hover must not change a drop target, and a click must
+* not activate whatever is underneath. Focus events are included because focus is how the
+* session moves between targets, and it has to be the only thing moving it.
+*/
+var CANCELED_EVENTS = [
+	"pointerdown",
+	"pointermove",
+	"pointerenter",
+	"pointerleave",
+	"pointerover",
+	"pointerout",
+	"pointerup",
+	"mousedown",
+	"mousemove",
+	"mouseenter",
+	"mouseleave",
+	"mouseover",
+	"mouseout",
+	"mouseup",
+	"touchstart",
+	"touchmove",
+	"touchend",
+	"focusin",
+	"focusout"
+];
+/**
+* Swallowed but never `preventDefault`ed.
+*
+* Calling `preventDefault` on these would suppress the `click` that follows, and `click` is how
+* a screen reader's virtual drop arrives.
+*/
+var CLICK_EVENTS = [
+	"pointerup",
+	"mouseup",
+	"touchend"
+];
+/** Elements the session has hidden from assistive technology are also out of bounds for focus. */
+var HIDDEN_SELECTOR = "[aria-hidden=\"true\"], [inert]";
+var contains = (node, other) => node != null && other != null && node.contains(other);
+var centerOf = (element) => {
+	const rect = element.getBoundingClientRect();
+	return {
+		x: rect.left + rect.width / 2,
+		y: rect.top + rect.height / 2
+	};
+};
+var notifySubscribers = () => {
+	for (const callback of subscriptions) callback();
+};
+/**
+* Register a drop target for the duration of a drag session, returning the unregister.
+*
+* Registering mid-session is normal rather than exceptional — a collection that mounts while a
+* drag is in flight must join it — so the valid target list is recomputed on both ends.
+*/
+var registerDropTarget = (target) => {
+	dropTargets.set(target.element, target);
+	dragSession?.updateValidDropTargets();
+	return () => {
+		dropTargets.delete(target.element);
+		dragSession?.updateValidDropTargets();
+	};
+};
+/** Register an individual item within a droppable collection, returning the unregister. */
+var registerDropItem = (item) => {
+	dropItems.set(item.element, item);
+	return () => {
+		dropItems.delete(item.element);
+	};
+};
+/**
+* Start a keyboard or screen reader drag.
+*
+* Throws when one is already in flight. That is deliberate upstream and kept here: two
+* overlapping sessions would both own the document's event listeners, and the second teardown
+* would strip the first session's, leaving the page permanently swallowing pointer events.
+*
+* Setup is deferred a frame because the drag typically starts from a keystroke that is still
+* propagating — attaching the capture listeners synchronously would make the session swallow the
+* tail of the very event that started it.
+*/
+var beginDragging = (target, stringFormatter) => {
+	if (dragSession) throw new Error("Cannot begin dragging while already dragging");
+	dragSession = new DragSession(target, stringFormatter);
+	requestAnimationFrame(() => {
+		if (!dragSession) return;
+		dragSession.setup();
+		if (getDragModality() === "keyboard") dragSession.next();
+	});
+	notifySubscribers();
+};
+var endDragging = () => {
+	dragSession = null;
+	notifySubscribers();
+};
+/** Whether a keyboard or screen reader drag is in flight. */
+var isVirtualDragging = () => dragSession != null;
+/** Whether an element is inside a registered drop target. */
+var isValidDropTarget = (element) => {
+	for (const target of dropTargets.keys()) if (contains(target, element)) return true;
+	return false;
+};
+/**
+* The session in flight, as a ref that updates when one starts or ends.
+*
+* React Aria subscribes with `useState` + `useEffect`; the Vue shape is a shallow ref fed by the
+* same subscription set. Read-only, because the session is owned by this module — a component
+* ends a drag by calling into it, never by assigning here.
+*/
+var useDragSession = () => {
+	const session = shallowRef(dragSession);
+	const callback = () => {
+		session.value = dragSession;
+	};
+	subscriptions.add(callback);
+	onScopeDispose(() => {
+		subscriptions.delete(callback);
+	});
+	return readonly(session);
+};
+var findValidDropTargets = (target) => {
+	const types = getTypes(target.items);
+	return [...dropTargets.values()].filter((candidate) => {
+		if (candidate.element.closest(HIDDEN_SELECTOR)) return false;
+		if (typeof candidate.getDropOperation === "function") return candidate.getDropOperation(types, target.allowedDropOperations) !== "cancel";
+		return true;
+	});
+};
+var DragSession = class {
+	dragTarget;
+	validDropTargets = [];
+	currentDropTarget = null;
+	currentDropItem = null;
+	dropOperation = null;
+	mutationObserver = null;
+	restoreAriaHidden = null;
+	isVirtualClick = false;
+	initialFocused = false;
+	stringFormatter;
+	constructor(target, stringFormatter) {
+		this.dragTarget = target;
+		this.stringFormatter = stringFormatter;
+		this.onKeyDown = this.onKeyDown.bind(this);
+		this.onKeyUp = this.onKeyUp.bind(this);
+		this.onFocus = this.onFocus.bind(this);
+		this.onBlur = this.onBlur.bind(this);
+		this.onClick = this.onClick.bind(this);
+		this.onPointerDown = this.onPointerDown.bind(this);
+		this.cancelEvent = this.cancelEvent.bind(this);
+	}
+	setup() {
+		document.addEventListener("keydown", this.onKeyDown, true);
+		document.addEventListener("keyup", this.onKeyUp, true);
+		window.addEventListener("focus", this.onFocus, true);
+		window.addEventListener("blur", this.onBlur, true);
+		document.addEventListener("click", this.onClick, true);
+		document.addEventListener("pointerdown", this.onPointerDown, true);
+		for (const event of CANCELED_EVENTS) document.addEventListener(event, this.cancelEvent, true);
+		this.mutationObserver = new MutationObserver(() => this.updateValidDropTargets());
+		this.updateValidDropTargets();
+		announce(this.stringFormatter.value.format({
+			keyboard: "dragStartedKeyboard",
+			touch: "dragStartedTouch",
+			virtual: "dragStartedVirtual"
+		}[getDragModality()]));
+	}
+	teardown() {
+		document.removeEventListener("keydown", this.onKeyDown, true);
+		document.removeEventListener("keyup", this.onKeyUp, true);
+		window.removeEventListener("focus", this.onFocus, true);
+		window.removeEventListener("blur", this.onBlur, true);
+		document.removeEventListener("click", this.onClick, true);
+		document.removeEventListener("pointerdown", this.onPointerDown, true);
+		for (const event of CANCELED_EVENTS) document.removeEventListener(event, this.cancelEvent, true);
+		this.mutationObserver?.disconnect();
+		this.restoreAriaHidden?.();
+	}
+	onKeyDown(event) {
+		this.cancelEvent(event);
+		if (event.key === "Escape") {
+			this.cancel();
+			return;
+		}
+		if (event.key === "Tab" && !(event.metaKey || event.altKey || event.ctrlKey)) {
+			if (event.shiftKey) this.previous();
+			else this.next();
+		}
+		this.currentDropTarget?.onKeyDown?.(event, this.dragTarget);
+	}
+	onKeyUp(event) {
+		this.cancelEvent(event);
+		if (event.key !== "Enter") return;
+		if (event.altKey || contains(this.getCurrentActivateButton(), event.target)) this.activate(this.currentDropTarget, this.currentDropItem);
+		else this.drop();
+	}
+	getCurrentActivateButton() {
+		return this.currentDropItem?.activateButtonRef?.value ?? this.currentDropTarget?.activateButtonRef?.value ?? null;
+	}
+	onFocus(event) {
+		const activateButton = this.getCurrentActivateButton();
+		const eventTarget = event.target;
+		if (eventTarget === activateButton) {
+			this.cancelEvent(event);
+			return;
+		}
+		if (eventTarget !== this.dragTarget.element) this.cancelEvent(event);
+		if (!(eventTarget instanceof HTMLElement) || eventTarget === this.dragTarget.element) return;
+		const dropTarget = this.validDropTargets.find((target) => target.element === eventTarget) ?? this.validDropTargets.find((target) => contains(target.element, eventTarget));
+		if (!dropTarget) {
+			(this.currentDropTarget?.element ?? this.dragTarget.element).focus();
+			return;
+		}
+		this.setCurrentDropTarget(dropTarget, dropItems.get(eventTarget));
+	}
+	onBlur(event) {
+		const activateButton = this.getCurrentActivateButton();
+		if (activateButton && event.relatedTarget === activateButton) {
+			this.cancelEvent(event);
+			return;
+		}
+		if (event.target !== this.dragTarget.element) this.cancelEvent(event);
+		if (!event.relatedTarget || !(event.relatedTarget instanceof HTMLElement)) (this.currentDropTarget?.element ?? this.dragTarget.element).focus();
+	}
+	onClick(event) {
+		this.cancelEvent(event);
+		if (!isVirtualClick(event) && !this.isVirtualClick) return;
+		const eventTarget = event.target;
+		const item = [...dropItems.values()].find((candidate) => candidate.element === eventTarget || contains(candidate.activateButtonRef?.value, eventTarget));
+		const dropTarget = this.validDropTargets.find((target) => contains(target.element, eventTarget));
+		if (contains(item?.activateButtonRef?.value ?? dropTarget?.activateButtonRef?.value, eventTarget) && dropTarget) {
+			this.activate(dropTarget, item);
+			return;
+		}
+		if (eventTarget === this.dragTarget.element) {
+			this.cancel();
+			return;
+		}
+		if (dropTarget) {
+			this.setCurrentDropTarget(dropTarget, item);
+			this.drop(item);
+		}
+	}
+	onPointerDown(event) {
+		this.cancelEvent(event);
+		this.isVirtualClick = isVirtualPointerEvent(event);
+	}
+	cancelEvent(event) {
+		const eventTarget = event.target;
+		if ((event.type === "focusin" || event.type === "focusout") && (eventTarget === this.dragTarget.element || eventTarget === this.getCurrentActivateButton())) return;
+		if (!CLICK_EVENTS.includes(event.type)) event.preventDefault();
+		event.stopPropagation();
+		event.stopImmediatePropagation();
+	}
+	updateValidDropTargets() {
+		if (!this.mutationObserver) return;
+		this.mutationObserver.disconnect();
+		this.restoreAriaHidden?.();
+		this.validDropTargets = findValidDropTargets(this.dragTarget);
+		if (this.validDropTargets.length > 0) {
+			const nearestIndex = this.findNearestDropTarget();
+			this.validDropTargets = [...this.validDropTargets.slice(nearestIndex), ...this.validDropTargets.slice(0, nearestIndex)];
+		}
+		if (this.currentDropTarget && !this.validDropTargets.includes(this.currentDropTarget)) this.setCurrentDropTarget(this.validDropTargets[0] ?? null);
+		const types = getTypes(this.dragTarget.items);
+		const validDropItems = [...dropItems.values()].filter((item) => typeof item.getDropOperation === "function" ? item.getDropOperation(types, this.dragTarget.allowedDropOperations) !== "cancel" : true);
+		const visibleDropTargets = this.validDropTargets.filter((target) => !validDropItems.some((item) => contains(target.element, item.element)));
+		const withActivateButton = (entry) => entry.activateButtonRef?.value ? [entry.element, entry.activateButtonRef.value] : [entry.element];
+		this.restoreAriaHidden = ariaHideOutside([
+			this.dragTarget.element,
+			...validDropItems.flatMap(withActivateButton),
+			...visibleDropTargets.flatMap(withActivateButton)
+		], { shouldUseInert: true });
+		this.mutationObserver.observe(document.body, {
+			attributeFilter: ["aria-hidden", "inert"],
+			attributes: true,
+			subtree: true
+		});
+	}
+	next() {
+		if (!this.currentDropTarget) {
+			this.setCurrentDropTarget(this.validDropTargets[0] ?? null);
+			return;
+		}
+		const index = this.validDropTargets.indexOf(this.currentDropTarget);
+		if (index < 0) {
+			this.setCurrentDropTarget(this.validDropTargets[0] ?? null);
+			return;
+		}
+		if (index === this.validDropTargets.length - 1) this.wrapToDragTarget(0);
+		else this.setCurrentDropTarget(this.validDropTargets[index + 1] ?? null);
+	}
+	previous() {
+		const last = this.validDropTargets.length - 1;
+		if (!this.currentDropTarget) {
+			this.setCurrentDropTarget(this.validDropTargets[last] ?? null);
+			return;
+		}
+		const index = this.validDropTargets.indexOf(this.currentDropTarget);
+		if (index < 0) {
+			this.setCurrentDropTarget(this.validDropTargets[last] ?? null);
+			return;
+		}
+		if (index === 0) this.wrapToDragTarget(last);
+		else this.setCurrentDropTarget(this.validDropTargets[index - 1] ?? null);
+	}
+	/**
+	* At either end of the target list, hand focus back to the element the drag came from.
+	*
+	* That element is always reachable, so it gives a user with no Escape key — an iPad keyboard,
+	* for one — somewhere to land and cancel from. If it has itself been hidden, there is nowhere
+	* to go and the cycle wraps instead.
+	*/
+	wrapToDragTarget(fallbackIndex) {
+		if (this.dragTarget.element.closest(HIDDEN_SELECTOR)) {
+			this.setCurrentDropTarget(this.validDropTargets[fallbackIndex] ?? null);
+			return;
+		}
+		this.setCurrentDropTarget(null);
+		this.dragTarget.element.focus();
+	}
+	findNearestDropTarget() {
+		const dragTargetRect = this.dragTarget.element.getBoundingClientRect();
+		let minDistance = Infinity;
+		let nearest = -1;
+		let ancestor = -1;
+		for (let index = 0; index < this.validDropTargets.length; index++) {
+			const dropTarget = this.validDropTargets[index];
+			if (!dropTarget) continue;
+			if (ancestor < 0 && contains(dropTarget.element, this.dragTarget.element)) ancestor = index;
+			const rect = dropTarget.element.getBoundingClientRect();
+			const dx = rect.left - dragTargetRect.left;
+			const dy = rect.top - dragTargetRect.top;
+			const distance = dx * dx + dy * dy;
+			if (distance < minDistance) {
+				minDistance = distance;
+				nearest = index;
+			}
+		}
+		return ancestor >= 0 ? ancestor : nearest;
+	}
+	setCurrentDropTarget(dropTarget, item) {
+		if (dropTarget !== this.currentDropTarget) {
+			if (this.currentDropTarget?.onDropExit) this.currentDropTarget.onDropExit({
+				type: "dropexit",
+				...centerOf(this.currentDropTarget.element)
+			});
+			this.currentDropTarget = dropTarget;
+			if (dropTarget) {
+				dropTarget.onDropEnter?.({
+					type: "dropenter",
+					...centerOf(dropTarget.element)
+				}, this.dragTarget);
+				if (!item) dropTarget.element.focus();
+			}
+		}
+		if (item != null && item !== this.currentDropItem) {
+			this.currentDropTarget?.onDropTargetEnter?.(item.target);
+			item.element.focus();
+			this.currentDropItem = item;
+			if (!this.initialFocused) {
+				const label = item.element.getAttribute("aria-label");
+				if (label) announce(label, "polite");
+				this.initialFocused = true;
+			}
+		}
+	}
+	end() {
+		this.teardown();
+		endDragging();
+		if (this.dragTarget.onDragEnd) {
+			const target = this.currentDropTarget && this.dropOperation !== "cancel" ? this.currentDropTarget : this.dragTarget;
+			this.dragTarget.onDragEnd({
+				type: "dragend",
+				...centerOf(target.element),
+				dropOperation: this.dropOperation ?? "cancel"
+			});
+		}
+		if (this.currentDropTarget && !this.currentDropTarget.preventFocusOnDrop) document.activeElement?.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+		this.setCurrentDropTarget(null);
+	}
+	cancel() {
+		this.setCurrentDropTarget(null);
+		this.end();
+		if (!this.dragTarget.element.closest(HIDDEN_SELECTOR)) this.dragTarget.element.focus();
+		document.activeElement?.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+		announce(this.stringFormatter.value.format("dropCanceled"));
+	}
+	drop(item) {
+		if (!this.currentDropTarget) {
+			this.cancel();
+			return;
+		}
+		const types = getTypes(this.dragTarget.items);
+		if (typeof item?.getDropOperation === "function") this.dropOperation = item.getDropOperation(types, this.dragTarget.allowedDropOperations);
+		else if (typeof this.currentDropTarget.getDropOperation === "function") this.dropOperation = this.currentDropTarget.getDropOperation(types, this.dragTarget.allowedDropOperations);
+		else this.dropOperation = this.dragTarget.allowedDropOperations[0] ?? "cancel";
+		if (this.currentDropTarget.onDrop) {
+			const items = this.dragTarget.items.map((dragItem) => ({
+				getText: (type) => Promise.resolve(dragItem[type] ?? ""),
+				kind: "text",
+				types: new Set(Object.keys(dragItem))
+			}));
+			this.currentDropTarget.onDrop({
+				type: "drop",
+				...centerOf(this.currentDropTarget.element),
+				dropOperation: this.dropOperation,
+				items
+			}, item?.target ?? null);
+		}
+		this.end();
+		announce(this.stringFormatter.value.format("dropComplete"));
+	}
+	activate(dropTarget, dropItem) {
+		if (!dropTarget?.onDropActivate) return;
+		dropTarget.onDropActivate({
+			type: "dropactivate",
+			...centerOf(dropTarget.element)
+		}, dropItem?.target ?? null);
+	}
+};
+/**
+* The session in flight, read once.
+*
+* The imperative sibling of `useDragSession`, for callers that are not inside an effect scope —
+* an event handler deciding whether a keystroke belongs to a drag, or a test ending one.
+*/
+var getDragSession = () => dragSession;
+//#endregion
+export { DragSession, beginDragging, getDragSession, isValidDropTarget, isVirtualDragging, registerDropItem, registerDropTarget, useDragSession };

package/dist/composables/drag-modality.d.ts

@@ -0,0 +1,41 @@
+import type { ComputedRef } from "vue";
+/**
+ * How a drag was started, which decides both the wording of every announcement and which keys
+ * or gestures end it.
+ */
+export type DragModality = "keyboard" | "touch" | "virtual";
+/**
+ * How the drag currently in flight is being driven.
+ *
+ * Ported from React Aria's `getDragModality`/`mapModality` in `dnd/utils.ts`. Not reactive on
+ * purpose, like the modality tracker it reads: call it inside the handler that needs it, so the
+ * answer is the one true at that moment rather than one a render captured.
+ *
+ * "Virtual" means a screen reader's synthetic click rather than a real pointer, and it is the
+ * fallback rather than a special case — anything that is not the keyboard is driven by something
+ * that cannot express a native drag, so it gets the click-to-drop flow. A coarse pointer narrows
+ * that to touch, which is announced differently ("double tap" rather than "click").
+ *
+ * One narrowing against React Aria, and it is visible in exactly one place. Its modality can also
+ * be `null` or `"virtual"`; this package's tracker produces neither — `InteractionModality` here
+ * is only `"keyboard" | "pointer"`, initialized to `"keyboard"` so a focus ring is painted before
+ * anything has happened. Upstream maps both of those to `"virtual"`, which is also where
+ * `"pointer"` lands, so once the user has done *anything* the two agree: a keydown gives
+ * `"keyboard"` on both sides, a pointer or a touch gives `"virtual"` on both.
+ *
+ * They differ only in the window before the first event, where upstream says `"virtual"` ("Click
+ * to start dragging") and this says `"keyboard"` ("Press Enter to start dragging"). Narrow in
+ * practice — a screen reader's browse-mode arrows fire `keydown`, and a tap fires `pointerdown`,
+ * so both settle it before anything is read out — and the wording it lands on still works, since
+ * Enter on the control produces the same click. Widening the tracker to a third state would touch
+ * every focus ring in the library for this one sentence, so it is recorded instead.
+ */
+export declare const getDragModality: () => DragModality;
+/**
+ * The drag modality as a reactive ref, for a description rendered into the DOM.
+ *
+ * The wording of "how to start a drag" differs per modality and lives in an `aria-describedby`
+ * node, so it has to be rewritten when the user switches input method — something the plain
+ * read above cannot do.
+ */
+export declare const useDragModality: () => ComputedRef<DragModality>;

package/dist/composables/drag-modality.js

@@ -0,0 +1,47 @@
+import { getInteractionModality, useInteractionModality } from "./use-interaction-states.js";
+import { computed } from "vue";
+//#region src/composables/drag-modality.ts
+var mapModality = (modality) => {
+	if (modality === "keyboard") return "keyboard";
+	return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(pointer: coarse)").matches ? "touch" : "virtual";
+};
+/**
+* How the drag currently in flight is being driven.
+*
+* Ported from React Aria's `getDragModality`/`mapModality` in `dnd/utils.ts`. Not reactive on
+* purpose, like the modality tracker it reads: call it inside the handler that needs it, so the
+* answer is the one true at that moment rather than one a render captured.
+*
+* "Virtual" means a screen reader's synthetic click rather than a real pointer, and it is the
+* fallback rather than a special case — anything that is not the keyboard is driven by something
+* that cannot express a native drag, so it gets the click-to-drop flow. A coarse pointer narrows
+* that to touch, which is announced differently ("double tap" rather than "click").
+*
+* One narrowing against React Aria, and it is visible in exactly one place. Its modality can also
+* be `null` or `"virtual"`; this package's tracker produces neither — `InteractionModality` here
+* is only `"keyboard" | "pointer"`, initialized to `"keyboard"` so a focus ring is painted before
+* anything has happened. Upstream maps both of those to `"virtual"`, which is also where
+* `"pointer"` lands, so once the user has done *anything* the two agree: a keydown gives
+* `"keyboard"` on both sides, a pointer or a touch gives `"virtual"` on both.
+*
+* They differ only in the window before the first event, where upstream says `"virtual"` ("Click
+* to start dragging") and this says `"keyboard"` ("Press Enter to start dragging"). Narrow in
+* practice — a screen reader's browse-mode arrows fire `keydown`, and a tap fires `pointerdown`,
+* so both settle it before anything is read out — and the wording it lands on still works, since
+* Enter on the control produces the same click. Widening the tracker to a third state would touch
+* every focus ring in the library for this one sentence, so it is recorded instead.
+*/
+var getDragModality = () => mapModality(getInteractionModality());
+/**
+* The drag modality as a reactive ref, for a description rendered into the DOM.
+*
+* The wording of "how to start a drag" differs per modality and lives in an `aria-describedby`
+* node, so it has to be rewritten when the user switches input method — something the plain
+* read above cannot do.
+*/
+var useDragModality = () => {
+	const modality = useInteractionModality();
+	return computed(() => mapModality(modality.value));
+};
+//#endregion
+export { getDragModality, useDragModality };