ropav 0.2.0 → 0.3.1

package/dist/utils/dnd-state.js

@@ -0,0 +1,48 @@
+import { DROP_OPERATION } from "./dnd-constants.js";
+//#region src/utils/dnd-state.ts
+var globalDndState = { draggingKeys: /* @__PURE__ */ new Set() };
+var setDraggingCollectionRef = (ref) => {
+	globalDndState.draggingCollectionRef = ref;
+};
+var setDraggingKeys = (keys) => {
+	globalDndState.draggingKeys = keys;
+};
+var setDropCollectionRef = (ref) => {
+	globalDndState.dropCollectionRef = ref;
+};
+var clearGlobalDnDState = () => {
+	globalDndState = { draggingKeys: /* @__PURE__ */ new Set() };
+};
+var setGlobalDnDState = (state) => {
+	globalDndState = state;
+};
+/**
+* Whether the drag in flight started in the same collection it is now over.
+*
+* This is the question that separates a reorder from an insert, and it cannot be answered from
+* the `DataTransfer` — a drag from another app and a drag from the list next door look identical
+* on the wire. Takes an optional ref for the case where the drop collection has not registered
+* itself globally yet, which happens on the very first `dragenter`.
+*/
+var isInternalDropOperation = (ref) => {
+	const { draggingCollectionRef, dropCollectionRef } = globalDndState;
+	return draggingCollectionRef?.value != null && draggingCollectionRef.value === (ref?.value ?? dropCollectionRef?.value);
+};
+/**
+* The `dropEffect` the drop target settled on, read back after the drag ends.
+*
+* Separate from the state object above because it outlives it: `dragend` fires after the drop
+* target has already torn its own state down, and the drag source still needs to know whether
+* to delete the items it just handed over.
+*/
+var globalDropEffect;
+var setGlobalDropEffect = (dropEffect) => {
+	globalDropEffect = dropEffect;
+};
+/** Operations the drag source said it would accept, as a `DROP_OPERATION` bitmask. */
+var globalAllowedDropOperations = DROP_OPERATION.none;
+var setGlobalAllowedDropOperations = (operations) => {
+	globalAllowedDropOperations = operations;
+};
+//#endregion
+export { clearGlobalDnDState, globalAllowedDropOperations, globalDndState, globalDropEffect, isInternalDropOperation, setDraggingCollectionRef, setDraggingKeys, setDropCollectionRef, setGlobalAllowedDropOperations, setGlobalDnDState, setGlobalDropEffect };

package/dist/utils/dnd-tree-drop-target-delegate.d.ts

@@ -0,0 +1,48 @@
+import type { DragCollection, DragKey, DropTarget, DropTargetDelegate } from "./dnd-types.js";
+export interface TreeDropTargetDelegateOptions {
+    /** The collection being dropped into, read at event time so expansion changes are seen. */
+    collection: () => DragCollection;
+    /** Which rows are open. A collapsed row's children are not in the collection at all. */
+    expandedKeys: () => Set<DragKey>;
+    /** @default "ltr" */
+    direction?: () => "ltr" | "rtl";
+}
+/**
+ * Resolves a pointer position inside a **tree** to a drop target, ported from React Aria
+ * Components' `TreeDropTargetDelegate`.
+ *
+ * Wraps a flat delegate rather than replacing it: finding which row the pointer is over is the
+ * same problem in a tree as in a list, and only what a position *means* differs.
+ *
+ * The problem it exists to solve: the gap under the last child of a subtree is not one place but
+ * several. Visually it is a single line, but it could mean "after the last child", "after that
+ * child's parent", or "after the grandparent" — every ancestor that ends there. Nothing in the
+ * pointer's Y position distinguishes them, so **X** does: moving left steps outwards to shallower
+ * levels, moving right steps back in. Both axes are hysteretic, so a hand that is not quite still
+ * does not make the target flicker between levels.
+ */
+export declare class TreeDropTargetDelegate implements DropTargetDelegate {
+    private delegate;
+    private options;
+    private tracking;
+    constructor(delegate: DropTargetDelegate, options: TreeDropTargetDelegateOptions);
+    private get collection();
+    private get direction();
+    getDropTargetFromPoint(x: number, y: number, isValidDropTarget: (target: DropTarget) => boolean): DropTarget | null;
+    private resolveDropTarget;
+    /**
+     * Every level the given gap could mean, innermost first.
+     *
+     * One entry for an unambiguous gap. Several when the gap sits at the end of one or more
+     * subtrees, in which case each ancestor that also ends there is a candidate.
+     */
+    private getPotentialTargets;
+    /**
+     * Which of several levels the pointer means.
+     *
+     * Y picks the starting level — arriving from below starts at the outermost, from above at the
+     * innermost — and X moves between them afterwards. Each axis resets the other's direction, so
+     * a diagonal drag settles on one intent instead of oscillating.
+     */
+    private selectTarget;
+}

package/dist/utils/dnd-tree-drop-target-delegate.js

@@ -0,0 +1,197 @@
+//#region src/utils/dnd-tree-drop-target-delegate.ts
+/** How far the pointer must travel on each axis before it counts as a deliberate move. */
+var X_SWITCH_THRESHOLD = 10;
+var Y_SWITCH_THRESHOLD = 5;
+/**
+* Resolves a pointer position inside a **tree** to a drop target, ported from React Aria
+* Components' `TreeDropTargetDelegate`.
+*
+* Wraps a flat delegate rather than replacing it: finding which row the pointer is over is the
+* same problem in a tree as in a list, and only what a position *means* differs.
+*
+* The problem it exists to solve: the gap under the last child of a subtree is not one place but
+* several. Visually it is a single line, but it could mean "after the last child", "after that
+* child's parent", or "after the grandparent" — every ancestor that ends there. Nothing in the
+* pointer's Y position distinguishes them, so **X** does: moving left steps outwards to shallower
+* levels, moving right steps back in. Both axes are hysteretic, so a hand that is not quite still
+* does not make the target flicker between levels.
+*/
+var TreeDropTargetDelegate = class {
+	delegate;
+	options;
+	tracking = {
+		boundaryContext: null,
+		lastX: 0,
+		lastY: 0,
+		xDirection: null,
+		yDirection: null
+	};
+	constructor(delegate, options) {
+		this.delegate = delegate;
+		this.options = options;
+	}
+	get collection() {
+		return this.options.collection();
+	}
+	get direction() {
+		return this.options.direction?.() ?? "ltr";
+	}
+	getDropTargetFromPoint(x, y, isValidDropTarget) {
+		const baseTarget = this.delegate.getDropTargetFromPoint(x, y, isValidDropTarget);
+		if (!baseTarget || baseTarget.type === "root") return baseTarget;
+		return this.resolveDropTarget(baseTarget, x, y, isValidDropTarget);
+	}
+	resolveDropTarget(target, x, y, isValidDropTarget) {
+		const tracking = this.tracking;
+		const deltaY = y - tracking.lastY;
+		const deltaX = x - tracking.lastX;
+		let yMovement = tracking.yDirection;
+		let xMovement = tracking.xDirection;
+		if (Math.abs(deltaY) > Y_SWITCH_THRESHOLD) {
+			yMovement = deltaY > 0 ? "down" : "up";
+			tracking.yDirection = yMovement;
+			tracking.lastY = y;
+		}
+		if (Math.abs(deltaX) > X_SWITCH_THRESHOLD) {
+			xMovement = deltaX > 0 ? "right" : "left";
+			tracking.xDirection = xMovement;
+			tracking.lastX = x;
+		}
+		let resolved = target;
+		if (resolved.dropPosition === "before") {
+			let keyBefore = this.collection.getKeyBefore(resolved.key);
+			while (keyBefore != null) {
+				const node = this.collection.getItem(keyBefore);
+				if ((node?.type ?? "item") === "item") break;
+				keyBefore = node?.parentKey ?? null;
+			}
+			if (keyBefore != null) {
+				const converted = {
+					dropPosition: "after",
+					key: keyBefore,
+					type: "item"
+				};
+				if (isValidDropTarget(converted)) resolved = converted;
+			}
+		}
+		const potentialTargets = this.getPotentialTargets(resolved, isValidDropTarget);
+		if (potentialTargets.length === 0) return { type: "root" };
+		if (potentialTargets.length === 1) {
+			tracking.boundaryContext = null;
+			return potentialTargets[0];
+		}
+		return this.selectTarget(potentialTargets, resolved, x, y, yMovement, xMovement);
+	}
+	/**
+	* Every level the given gap could mean, innermost first.
+	*
+	* One entry for an unambiguous gap. Several when the gap sits at the end of one or more
+	* subtrees, in which case each ancestor that also ends there is a candidate.
+	*/
+	getPotentialTargets(originalTarget, isValidDropTarget) {
+		if (originalTarget.dropPosition === "on") return [originalTarget];
+		const collection = this.collection;
+		let target = originalTarget;
+		let currentItem = collection.getItem(target.key);
+		while (currentItem && (currentItem.type ?? "item") !== "item" && currentItem.nextKey != null) {
+			target = {
+				...target,
+				key: currentItem.nextKey
+			};
+			currentItem = collection.getItem(currentItem.nextKey);
+		}
+		/**
+		* The gap under an open parent is *inside* it, not after it.
+		*
+		* Dropping "after" a row that has visible children would put the item below the whole
+		* subtree, which is not where the line the user sees is drawn.
+		*/
+		if (currentItem && currentItem.hasChildItems && this.options.expandedKeys().has(currentItem.key) && target.dropPosition === "after") {
+			let firstChild = currentItem.firstChildKey != null ? collection.getItem(currentItem.firstChildKey) : null;
+			while (firstChild && (firstChild.type ?? "item") !== "item") firstChild = firstChild.nextKey != null ? collection.getItem(firstChild.nextKey) : null;
+			if (firstChild) {
+				const beforeFirstChild = {
+					dropPosition: "before",
+					key: firstChild.key,
+					type: "item"
+				};
+				return isValidDropTarget(beforeFirstChild) ? [beforeFirstChild] : [];
+			}
+		}
+		if (currentItem?.nextKey != null) return [originalTarget];
+		const potentialTargets = [target];
+		const ancestorTargets = [];
+		let parentKey = currentItem?.parentKey;
+		while (parentKey != null) {
+			const parentItem = collection.getItem(parentKey);
+			const nextItem = parentItem?.nextKey != null ? collection.getItem(parentItem.nextKey) : null;
+			if (!nextItem || nextItem.parentKey !== parentKey) {
+				const afterParent = {
+					dropPosition: "after",
+					key: parentKey,
+					type: "item"
+				};
+				if (isValidDropTarget(afterParent)) ancestorTargets.push(afterParent);
+				if (nextItem) break;
+			}
+			parentKey = parentItem?.parentKey;
+		}
+		potentialTargets.push(...ancestorTargets);
+		/**
+		* "After A" when the row below A is A's own child means "before that child" instead.
+		*
+		* Only when nothing was ambiguous: with several candidates the level is chosen by the
+		* pointer, and rewriting the innermost one here would take that choice away.
+		*/
+		if (potentialTargets.length === 1) {
+			const nextKey = collection.getKeyAfter(target.key);
+			const nextNode = nextKey != null ? collection.getItem(nextKey) : null;
+			if (nextKey != null && nextNode && currentItem && nextNode.level != null && currentItem.level != null && nextNode.level > currentItem.level) {
+				const beforeNext = {
+					dropPosition: "before",
+					key: nextKey,
+					type: "item"
+				};
+				if (isValidDropTarget(beforeNext)) return [beforeNext];
+			}
+		}
+		return potentialTargets.filter(isValidDropTarget);
+	}
+	/**
+	* Which of several levels the pointer means.
+	*
+	* Y picks the starting level — arriving from below starts at the outermost, from above at the
+	* innermost — and X moves between them afterwards. Each axis resets the other's direction, so
+	* a diagonal drag settles on one intent instead of oscillating.
+	*/
+	selectTarget(potentialTargets, originalTarget, x, y, yMovement, xMovement) {
+		const tracking = this.tracking;
+		const parentKey = this.collection.getItem(originalTarget.key)?.parentKey;
+		if (parentKey == null) return potentialTargets[0];
+		if (!tracking.boundaryContext || tracking.boundaryContext.parentKey !== parentKey) tracking.boundaryContext = {
+			lastSwitchX: x,
+			lastSwitchY: y,
+			parentKey,
+			preferredTargetIndex: tracking.yDirection === "up" ? potentialTargets.length - 1 : 0
+		};
+		const boundary = tracking.boundaryContext;
+		const movedX = Math.abs(x - boundary.lastSwitchX);
+		if (Math.abs(y - boundary.lastSwitchY) > Y_SWITCH_THRESHOLD && yMovement) {
+			const index = boundary.preferredTargetIndex ?? 0;
+			if (yMovement === "down" && index === 0) boundary.preferredTargetIndex = potentialTargets.length - 1;
+			else if (yMovement === "up" && index === potentialTargets.length - 1) boundary.preferredTargetIndex = 0;
+			tracking.xDirection = null;
+		}
+		if (movedX > X_SWITCH_THRESHOLD && xMovement) {
+			const next = (boundary.preferredTargetIndex ?? 0) + (xMovement === (this.direction === "ltr" ? "left" : "right") ? 1 : -1);
+			if (next >= 0 && next <= potentialTargets.length - 1) {
+				boundary.preferredTargetIndex = next;
+				boundary.lastSwitchX = x;
+			}
+			tracking.yDirection = null;
+		}
+		return potentialTargets[Math.max(0, Math.min(boundary.preferredTargetIndex ?? 0, potentialTargets.length - 1))];
+	}
+};
+//#endregion
+export { TreeDropTargetDelegate };

package/dist/utils/dnd-types.d.ts

@@ -0,0 +1,266 @@
+/**
+ * The vocabulary of drag and drop, ported from `@react-types/shared`'s `dnd.d.ts`.
+ *
+ * These live in `utils/` rather than beside a composable because the non-reactive machinery
+ * — the drag manager, the data transfer codec, the drop target delegates — is written against
+ * them and must not reach up into `composables/`.
+ */
+/**
+ * The key identifying a draggable item.
+ *
+ * Structurally identical to `CollectionKey` and `VirtualizerKey`, and declared separately for
+ * the same reason those two are: `utils/` never imports from `composables/`, so the key type a
+ * drop target names cannot be the one `use-collection` declares. React Aria has a single `Key`
+ * because it has no such layering to keep.
+ */
+export type DragKey = string | number;
+/** What a drop should do with the dragged data. `"cancel"` means the drop is refused. */
+export type DropOperation = "copy" | "link" | "move" | "cancel";
+/**
+ * The native `DataTransfer.dropEffect` vocabulary.
+ *
+ * Nearly `DropOperation`, but the two disagree on how they spell refusal — the DOM says
+ * `"none"` where React Aria says `"cancel"` — which is the whole reason both types exist.
+ */
+export type DropEffect = "none" | "copy" | "link" | "move";
+/**
+ * One dragged item, as a map of mime type to serialized value.
+ *
+ * A single item carries several representations of itself at once — `text/plain` for a foreign
+ * app, a custom app type for a drop back into the same collection — and the drop side picks
+ * whichever it understands.
+ */
+export interface DragItem {
+    [type: string]: string;
+}
+/** A dropped item that came from text data rather than the file system. */
+export interface TextDropItem {
+    kind: "text";
+    /** Mime types this item can be read as. Often mime types, but app-specific types are allowed. */
+    types: Set<string>;
+    getText: (type: string) => Promise<string>;
+}
+/** A dropped item backed by a real file. */
+export interface FileDropItem {
+    kind: "file";
+    /** The file's mime type, or `GENERIC_TYPE` when the browser could not name one. */
+    type: string;
+    name: string;
+    getFile: () => Promise<File>;
+    getText: () => Promise<string>;
+}
+/** A dropped item backed by a directory. Its contents are read lazily. */
+export interface DirectoryDropItem {
+    kind: "directory";
+    name: string;
+    getEntries: () => AsyncIterable<FileDropItem | DirectoryDropItem>;
+}
+export type DropItem = DirectoryDropItem | FileDropItem | TextDropItem;
+/**
+ * A type a drag can be asked about. A symbol because `DIRECTORY_DRAG_TYPE` has no mime type
+ * of its own — a directory is only distinguishable from a file after the drop.
+ */
+export type DragType = string | symbol;
+/**
+ * What a drag carries, as far as a drop target is allowed to know **during** the drag.
+ *
+ * The browser withholds the data itself until drop, so this is the only question answerable
+ * while the pointer is still moving.
+ */
+export interface DragTypes {
+    has: (type: DragType | DragType[]) => boolean;
+}
+/**
+ * Renders the image that follows the pointer during a drag.
+ *
+ * Callback-shaped rather than returning the node, because `setDragImage` only has effect while
+ * the `dragstart` handler is still on the stack: the renderer must produce the node and hand it
+ * back within the same tick, and the callback is what enforces that.
+ */
+export type DragPreviewRenderer = (items: DragItem[], callback: (node: HTMLElement | null, x?: number, y?: number) => void) => void;
+/** Where a drop lands relative to an item: on it, or inserted to either side of it. */
+export type DropPosition = "after" | "before" | "on";
+/** A drop onto the collection as a whole rather than any item in it. */
+export interface RootDropTarget {
+    type: "root";
+}
+export interface ItemDropTarget {
+    type: "item";
+    key: DragKey;
+    dropPosition: DropPosition;
+}
+export type DropTarget = ItemDropTarget | RootDropTarget;
+/**
+ * Resolves a point to the drop target under it.
+ *
+ * A collection knows its own geometry better than a generic hit test does — a virtualized list
+ * can answer from its layout without the rows being in the DOM at all — so this is delegated
+ * rather than computed centrally.
+ */
+export interface DropTargetDelegate {
+    /**
+     * @param x - Horizontal offset from the collection container's top left corner.
+     * @param y - Vertical offset from the collection container's top left corner.
+     * @param isValidDropTarget - Whether a candidate would accept the drag currently in flight.
+     */
+    getDropTargetFromPoint: (x: number, y: number, isValidDropTarget: (target: DropTarget) => boolean) => DropTarget | null;
+}
+/** Coordinates every drag and drop event carries, relative to the target element. */
+export interface DragDropEvent {
+    x: number;
+    y: number;
+}
+export interface DragStartEvent extends DragDropEvent {
+    type: "dragstart";
+}
+export interface DragMoveEvent extends DragDropEvent {
+    type: "dragmove";
+}
+export interface DragEndEvent extends DragDropEvent {
+    type: "dragend";
+    dropOperation: DropOperation;
+}
+export interface DropEnterEvent extends DragDropEvent {
+    type: "dropenter";
+}
+export interface DropMoveEvent extends DragDropEvent {
+    type: "dropmove";
+}
+export interface DropActivateEvent extends DragDropEvent {
+    type: "dropactivate";
+}
+export interface DropExitEvent extends DragDropEvent {
+    type: "dropexit";
+}
+export interface DropEvent extends DragDropEvent {
+    type: "drop";
+    dropOperation: DropOperation;
+    items: DropItem[];
+}
+/**
+ * What the drag and drop state layer needs to know about one item.
+ *
+ * React Aria reads a full `Node` off its collection, which it can do because it builds the whole
+ * tree by rendering into a hidden pass. This package has no such pass — items register themselves
+ * — so instead of forcing every collection into a common node shape, the state layer names only
+ * the four facts it actually uses and each collection supplies them its own way.
+ */
+export interface DragCollectionNode<T = unknown> {
+    key: DragKey;
+    /**
+     * What the node is.
+     *
+     * Only `"item"` is a drop target. A collection may also hold rows that are not items — a
+     * load-more sentinel, a section header — and every traversal has to step over them rather
+     * than offer them as somewhere to drop.
+     */
+    type?: "item" | (string & {});
+    /** Depth in a tree, counting from 0. Flat collections may leave it undefined. */
+    level?: number;
+    /** The containing item in a tree, or `null` at the top level. */
+    parentKey?: DragKey | null;
+    /** The previous sibling, used to recognise two ways of naming the same gap between items. */
+    prevKey?: DragKey | null;
+    nextKey?: DragKey | null;
+    /** The last child, for stepping past a whole expanded subtree. */
+    lastChildKey?: DragKey | null;
+    /** The first child, for dropping at the top of an expanded subtree. */
+    firstChildKey?: DragKey | null;
+    /**
+     * Whether the item can contain others at all.
+     *
+     * Distinct from having any right now: a collapsed row's children are absent from the
+     * collection, and an empty expandable row still accepts a drop into it.
+     */
+    hasChildItems?: boolean;
+    /** The item's text, used to name it in a drop indicator's label. */
+    textValue?: string;
+    /** The caller's own data for this item, handed back when building drag items. */
+    value?: T;
+}
+/**
+ * The slice of a collection the drag and drop layer reads.
+ *
+ * `getKeyAfter`/`getKeyBefore` walk the collection in **document order**, descending into
+ * expanded children — which is a different question from `nextKey`/`prevKey` on a node, and both
+ * are needed: document order is how a drag steps down the list, sibling order is how it decides
+ * where a subtree ends.
+ */
+export interface DragCollection<T = unknown> {
+    getItem: (key: DragKey) => DragCollectionNode<T> | null | undefined;
+    getKeyAfter: (key: DragKey) => DragKey | null;
+    getKeyBefore: (key: DragKey) => DragKey | null;
+    /** Every key in document order. */
+    getKeys: () => Iterable<DragKey>;
+}
+/**
+ * Where the keyboard would move focus from a given key.
+ *
+ * Satisfied by this package's `useListKeyboard` and `useGridKeyboard`. Drag navigation asks it
+ * rather than walking the collection itself, so a drag moves through a grid the same way focus
+ * does — down a column, not along a row.
+ */
+export interface DragKeyboardDelegate {
+    getKeyBelow?: (key: DragKey) => DragKey | null;
+    getKeyAbove?: (key: DragKey) => DragKey | null;
+    getKeyLeftOf?: (key: DragKey) => DragKey | null;
+    getKeyRightOf?: (key: DragKey) => DragKey | null;
+    getFirstKey?: () => DragKey | null;
+    getLastKey?: () => DragKey | null;
+}
+export interface DroppableCollectionEnterEvent extends DropEnterEvent {
+    target: DropTarget;
+}
+export interface DroppableCollectionMoveEvent extends DropMoveEvent {
+    target: DropTarget;
+}
+export interface DroppableCollectionActivateEvent extends DropActivateEvent {
+    target: DropTarget;
+}
+export interface DroppableCollectionExitEvent extends DropExitEvent {
+    target: DropTarget;
+}
+export interface DroppableCollectionDropEvent extends DropEvent {
+    target: DropTarget;
+}
+/** Items from elsewhere dropped into a gap between two items. */
+export interface DroppableCollectionInsertDropEvent {
+    items: DropItem[];
+    dropOperation: DropOperation;
+    target: ItemDropTarget;
+}
+/** Items from elsewhere dropped on the collection itself rather than any item. */
+export interface DroppableCollectionRootDropEvent {
+    items: DropItem[];
+    dropOperation: DropOperation;
+}
+/** Items dropped onto an item — a folder, say — rather than between two. */
+export interface DroppableCollectionOnItemDropEvent {
+    items: DropItem[];
+    dropOperation: DropOperation;
+    isInternal: boolean;
+    target: ItemDropTarget;
+}
+/** Items from this same collection moved to a new position. */
+export interface DroppableCollectionReorderEvent {
+    keys: Set<DragKey>;
+    dropOperation: DropOperation;
+    target: ItemDropTarget;
+}
+export interface DraggableCollectionStartEvent extends DragStartEvent {
+    keys: Set<DragKey>;
+}
+export interface DraggableCollectionMoveEvent extends DragMoveEvent {
+    keys: Set<DragKey>;
+}
+export interface DraggableCollectionEndEvent extends DragEndEvent {
+    keys: Set<DragKey>;
+    /** Whether the drop landed in the collection the drag started from. */
+    isInternal: boolean;
+}
+/** Whether a drop item carries text data. */
+export declare const isTextDropItem: (dropItem: DropItem) => dropItem is TextDropItem;
+/** Whether a drop item is a file. */
+export declare const isFileDropItem: (dropItem: DropItem) => dropItem is FileDropItem;
+/** Whether a drop item is a directory. */
+export declare const isDirectoryDropItem: (dropItem: DropItem) => dropItem is DirectoryDropItem;

package/dist/utils/dnd-types.js

@@ -0,0 +1,9 @@
+//#region src/utils/dnd-types.ts
+/** Whether a drop item carries text data. */
+var isTextDropItem = (dropItem) => dropItem.kind === "text";
+/** Whether a drop item is a file. */
+var isFileDropItem = (dropItem) => dropItem.kind === "file";
+/** Whether a drop item is a directory. */
+var isDirectoryDropItem = (dropItem) => dropItem.kind === "directory";
+//#endregion
+export { isDirectoryDropItem, isFileDropItem, isTextDropItem };

package/dist/utils/focus.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Controls that can hold focus, in the order the browser would visit them.
+ *
+ * Deliberately not `[tabindex]` on its own: a `tabindex="-1"` element is focusable
+ * programmatically but is not a tab stop, and counting it would make one arrow press appear
+ * to land nowhere.
+ */
+export declare const FOCUSABLE_SELECTOR: string;
+/**
+ * Whether an element is visible enough to take focus.
+ *
+ * `checkVisibility()` is the only reliable read of this — `offsetParent` is always `null` in
+ * jsdom, and a `display: none` ancestor is invisible to a bounding-rect check. jsdom does not
+ * implement `checkVisibility` either, so there everything else counts, which is what tests
+ * exercising key order want anyway.
+ *
+ * `hidden` is read separately because it needs no layout and is the one case that matters even in
+ * jsdom: a field's hidden input sits among the segments a picker moves focus through, and moving
+ * onto something no browser will focus would leave focus where it was instead of moving on.
+ */
+export declare const isElementVisible: (element: HTMLElement) => boolean;
+/** The focusable controls inside `element`, in document order, skipping hidden ones. */
+export declare const focusableIn: (element: HTMLElement) => HTMLElement[];
+/**
+ * The controls inside `element` that Tab actually visits.
+ *
+ * Narrower than {@link focusableIn}, and the difference matters: the selector cannot express
+ * "not `tabindex="-1"`" for an element that is focusable by its tag alone, so a
+ * `<button tabindex="-1">` matches `button:not([disabled])` and counts as focusable. That is
+ * right for anything moving focus itself — a collection with a roving tab index holds every item
+ * at `-1` and still has to page through them — and wrong for anything modelling the tab order,
+ * where such a button is deliberately not a stop.
+ */
+export declare const tabbableIn: (element: HTMLElement) => HTMLElement[];
+/**
+ * Whether an element scrolls its own content.
+ *
+ * Ported from React Aria's `isScrollable`. Paging keys need this: in a list that does not
+ * scroll there is no page to move by, so Page Up and Page Down collapse to the ends instead.
+ * The document's scrolling element is a special case — it scrolls despite defaulting to
+ * `overflow: visible`.
+ */
+export declare const isScrollable: (element: Element | null) => boolean;
+/**
+ * The nearest ancestor that scrolls its own content, or `null` when nothing up to the root does.
+ *
+ * Ported from React Aria's `getScrollParent`. Anything that watches for the edge of a list coming
+ * into view has to observe against that box rather than the viewport, or a list inside a scrolling
+ * panel would never report anything.
+ */
+export declare const getScrollParent: (element: HTMLElement | null) => HTMLElement | null;
+export interface FocusManagerOptions {
+    /** Where to move from, when it should not be whatever holds focus right now. */
+    from?: Element | null;
+    /** Whether running off one end continues at the other. */
+    wrap?: boolean;
+}
+export interface CreateFocusManagerOptions {
+    /**
+     * Which focusable elements count as stops.
+     *
+     * A range picker's group holds the button that opens its popover between the two rows of
+     * segments, and moving along the row must not step onto it.
+     */
+    accept?: (element: HTMLElement) => boolean;
+}
+export interface FocusManager {
+    /** Move focus to the first stop inside the root, and return it. */
+    focusFirst: () => HTMLElement | null;
+    focusLast: () => HTMLElement | null;
+    focusNext: (options?: FocusManagerOptions) => HTMLElement | null;
+    focusPrevious: (options?: FocusManagerOptions) => HTMLElement | null;
+}
+/**
+ * Move focus around inside an element from the outside.
+ *
+ * Ported from React Aria's `createFocusManager`. A date field needs this because typing into one
+ * segment moves focus to the next: the segment knows it is finished, but only its field knows what
+ * comes after it.
+ *
+ * Takes a getter rather than an element so it can be built before the element exists, which is the
+ * order a component sets things up in.
+ *
+ * React walks the tree with a `TreeWalker` and stops on anything focusable; this reads the list
+ * {@link focusableIn} already builds. The two agree wherever nothing is held at `tabindex="-1"`,
+ * which no field of segments does.
+ */
+export declare const createFocusManager: (getRoot: () => HTMLElement | null | undefined, options?: CreateFocusManagerOptions) => FocusManager;