ropav 0.2.0 → 0.3.0

package/dist/composables/use-measured-height.d.ts

@@ -0,0 +1,25 @@
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseMeasuredHeightReturn {
+    /** The element's `scrollHeight`, or `undefined` until there is an element to measure. */
+    height: ComputedRef<number | undefined>;
+}
+/**
+ * An element's rendered height.
+ *
+ * `scrollHeight` rather than a `ResizeObserver` entry's box, because the caller needs the height
+ * the content *wants*: a toast that is not frontmost is clipped to the front one's height, so its
+ * own border box has already been overwritten by the very number this feeds.
+ *
+ * Two narrowings against the usual shape, both measured rather than assumed:
+ *
+ * 1. It measures directly on attach and then lets the observer take over, rather than relying on
+ *    the observer's first notification alone. jsdom *has* a `ResizeObserver` constructor but it
+ *    never notifies anything, so an observer-only reading is permanently absent there — and this
+ *    value drives an inline custom property that decides layout, which is exactly the kind of
+ *    thing a fast suite should be able to assert. In a real browser the two readings agree, and
+ *    the repeat is dropped, so the only difference is that the first one lands a frame earlier.
+ * 2. React also watches `aria-hidden` with a `MutationObserver`. That attribute never reaches the
+ *    DOM there — `react-aria-components` filters it off the toast — so the observer is dead code,
+ *    and this package renders no `aria-hidden` for it to watch either.
+ */
+export declare const useMeasuredHeight: (elementRef: MaybeRefOrGetter<HTMLElement | null | undefined>) => UseMeasuredHeightReturn;

package/dist/composables/use-measured-height.js

@@ -0,0 +1,48 @@
+import { computed, onScopeDispose, shallowRef, toValue, watch } from "vue";
+//#region src/composables/use-measured-height.ts
+/**
+* An element's rendered height.
+*
+* `scrollHeight` rather than a `ResizeObserver` entry's box, because the caller needs the height
+* the content *wants*: a toast that is not frontmost is clipped to the front one's height, so its
+* own border box has already been overwritten by the very number this feeds.
+*
+* Two narrowings against the usual shape, both measured rather than assumed:
+*
+* 1. It measures directly on attach and then lets the observer take over, rather than relying on
+*    the observer's first notification alone. jsdom *has* a `ResizeObserver` constructor but it
+*    never notifies anything, so an observer-only reading is permanently absent there — and this
+*    value drives an inline custom property that decides layout, which is exactly the kind of
+*    thing a fast suite should be able to assert. In a real browser the two readings agree, and
+*    the repeat is dropped, so the only difference is that the first one lands a frame earlier.
+* 2. React also watches `aria-hidden` with a `MutationObserver`. That attribute never reaches the
+*    DOM there — `react-aria-components` filters it off the toast — so the observer is dead code,
+*    and this package renders no `aria-hidden` for it to watch either.
+*/
+var useMeasuredHeight = (elementRef) => {
+	const height = shallowRef(void 0);
+	let observer;
+	const detach = () => {
+		observer?.disconnect();
+		observer = void 0;
+	};
+	watch(() => toValue(elementRef) ?? null, (element) => {
+		detach();
+		if (!element) return;
+		const measure = () => {
+			const next = element.scrollHeight;
+			if (height.value !== next) height.value = next;
+		};
+		measure();
+		if (typeof ResizeObserver === "undefined") return;
+		observer = new ResizeObserver(measure);
+		observer.observe(element);
+	}, {
+		flush: "post",
+		immediate: true
+	});
+	onScopeDispose(detach, true);
+	return { height: computed(() => height.value) };
+};
+//#endregion
+export { useMeasuredHeight };

package/dist/composables/use-media-query.d.ts

@@ -0,0 +1,23 @@
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseMediaQueryOptions {
+    /**
+     * What to report where there is nothing to ask — the server, and any environment without
+     * `matchMedia`.
+     *
+     * @default false
+     */
+    defaultValue?: boolean;
+}
+/**
+ * Whether a media query currently matches.
+ *
+ * Reactive on two axes: the query itself may change, and so may the answer. Both go through the
+ * same subscribe step, so switching queries tears the old listener down rather than accumulating
+ * one per change.
+ *
+ * @example
+ * ```ts
+ * const isMobile = useMediaQuery("(max-width: 768px)");
+ * ```
+ */
+export declare const useMediaQuery: (query: MaybeRefOrGetter<string>, options?: UseMediaQueryOptions) => ComputedRef<boolean>;

package/dist/composables/use-media-query.js

@@ -0,0 +1,47 @@
+import { computed, onScopeDispose, shallowRef, toValue, watch } from "vue";
+//#region src/composables/use-media-query.ts
+/**
+* Whether a media query currently matches.
+*
+* Reactive on two axes: the query itself may change, and so may the answer. Both go through the
+* same subscribe step, so switching queries tears the old listener down rather than accumulating
+* one per change.
+*
+* @example
+* ```ts
+* const isMobile = useMediaQuery("(max-width: 768px)");
+* ```
+*/
+var useMediaQuery = (query, options = {}) => {
+	const fallback = options.defaultValue ?? false;
+	const matches = shallowRef(fallback);
+	let detach;
+	const subscribe = (next) => {
+		detach?.();
+		detach = void 0;
+		if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+			matches.value = fallback;
+			return;
+		}
+		const list = window.matchMedia(next);
+		const onChange = () => {
+			matches.value = list.matches;
+		};
+		onChange();
+		if (typeof list.addEventListener === "function") {
+			list.addEventListener("change", onChange);
+			detach = () => list.removeEventListener("change", onChange);
+		} else {
+			list.addListener(onChange);
+			detach = () => list.removeListener(onChange);
+		}
+	};
+	watch(() => toValue(query), subscribe, { immediate: true });
+	onScopeDispose(() => {
+		detach?.();
+		detach = void 0;
+	}, true);
+	return computed(() => matches.value);
+};
+//#endregion
+export { useMediaQuery };

package/dist/composables/use-menu-trigger.d.ts

@@ -0,0 +1,61 @@
+import type { PressResponder } from "./press-responder";
+import type { OverlayType } from "./use-overlay-trigger";
+import type { FocusStrategy, MenuTriggerState } from "./use-overlay-trigger-state";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+/** How the menu is opened. */
+export type MenuTriggerType = "press" | "longPress";
+export interface UseMenuTriggerOptions {
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    /** @default "press" */
+    trigger?: MaybeRefOrGetter<MenuTriggerType | undefined>;
+    /**
+     * What the trigger opens, which decides how `aria-haspopup` is announced.
+     *
+     * A select opens a listbox rather than a menu, and the two are announced differently — but the
+     * gesture is the same one, which is why React Aria's `useSelect` reaches for this hook instead
+     * of repeating it.
+     *
+     * @default "menu"
+     */
+    type?: OverlayType;
+    /**
+     * Told to assistive technology when the menu opens on a long press, which nothing on screen
+     * conveys.
+     *
+     * @default "Long press or press Alt + ArrowDown to open menu"
+     */
+    longPressDescription?: MaybeRefOrGetter<string | undefined>;
+}
+export interface UseMenuTriggerReturn {
+    /** Hand to `providePressResponder`, so the trigger element picks all of this up. */
+    responder: PressResponder;
+    /** The trigger's id, which the menu and its popover are labelled by. */
+    triggerId: ComputedRef<string>;
+    /** The overlay's id, which the menu carries. */
+    overlayId: ComputedRef<string>;
+    /** The trigger element, which the popover is positioned against. */
+    triggerElement: ComputedRef<HTMLElement | null>;
+    /** Where focus should land in the menu, given how it was opened. */
+    autoFocus: ComputedRef<boolean | FocusStrategy>;
+}
+export declare const DEFAULT_LONG_PRESS_DESCRIPTION = "Long press or press Alt + ArrowDown to open menu";
+/**
+ * Turn any pressable into a menu trigger, ported from React Aria's `useMenuTrigger`.
+ *
+ * The interesting part is that a menu opens at different moments depending on how it was reached,
+ * and each choice matches the platform. A mouse opens it on the way *down*, as every desktop menu
+ * does. Touch opens it on release, because a menu appearing under a finger still on the glass
+ * would land where the finger is about to lift. A keyboard opens it on the key that implies a
+ * direction — ArrowUp opens the menu with its last item focused — and a screen reader, which
+ * clicks with no pointer behind it, opens it focused on the first item, since there is no pointer
+ * to carry on with.
+ *
+ * @example
+ * ```ts
+ * const state = useMenuTriggerState({isOpen: () => props.isOpen});
+ * const trigger = useMenuTrigger({trigger: () => props.trigger}, state);
+ *
+ * providePressResponder(trigger.responder);
+ * ```
+ */
+export declare const useMenuTrigger: (options: UseMenuTriggerOptions, state: MenuTriggerState) => UseMenuTriggerReturn;

package/dist/composables/use-menu-trigger.js

@@ -0,0 +1,119 @@
+import { useId as useId$1 } from "./use-id.js";
+import { useOverlayTrigger } from "./use-overlay-trigger.js";
+import { usePress } from "./use-press.js";
+import { useLongPress } from "./use-long-press.js";
+import { computed, shallowRef, toValue } from "vue";
+//#region src/composables/use-menu-trigger.ts
+var DEFAULT_LONG_PRESS_DESCRIPTION = "Long press or press Alt + ArrowDown to open menu";
+/**
+* Turn any pressable into a menu trigger, ported from React Aria's `useMenuTrigger`.
+*
+* The interesting part is that a menu opens at different moments depending on how it was reached,
+* and each choice matches the platform. A mouse opens it on the way *down*, as every desktop menu
+* does. Touch opens it on release, because a menu appearing under a finger still on the glass
+* would land where the finger is about to lift. A keyboard opens it on the key that implies a
+* direction — ArrowUp opens the menu with its last item focused — and a screen reader, which
+* clicks with no pointer behind it, opens it focused on the first item, since there is no pointer
+* to carry on with.
+*
+* @example
+* ```ts
+* const state = useMenuTriggerState({isOpen: () => props.isOpen});
+* const trigger = useMenuTrigger({trigger: () => props.trigger}, state);
+*
+* providePressResponder(trigger.responder);
+* ```
+*/
+var useMenuTrigger = (options, state) => {
+	const triggerId = useId$1();
+	const element = shallowRef(null);
+	const isDisabled = computed(() => Boolean(toValue(options.isDisabled)));
+	const triggerType = computed(() => toValue(options.trigger) ?? "press");
+	const isLongPress = computed(() => triggerType.value === "longPress");
+	const { overlayId, triggerAttributes } = useOverlayTrigger({ type: options.type ?? "menu" }, state);
+	/** Focus the trigger before opening, so focus has somewhere to come back to on close. */
+	const focusTrigger = () => {
+		element.value?.focus({ preventScroll: true });
+	};
+	const press = usePress({
+		isDisabled: () => isDisabled.value || isLongPress.value,
+		isPressed: () => state.isOpen.value,
+		onPress: (event) => {
+			if (event.pointerType !== "touch") return;
+			focusTrigger();
+			state.toggle();
+		},
+		onPressStart: (event) => {
+			if (event.pointerType === "touch" || event.pointerType === "keyboard") return;
+			focusTrigger();
+			state.open(event.pointerType === "virtual" ? "first" : null);
+		},
+		preventFocusOnPress: true
+	});
+	const longPress = useLongPress({
+		accessibilityDescription: () => toValue(options.longPressDescription) ?? "Long press or press Alt + ArrowDown to open menu",
+		isDisabled: () => isDisabled.value || !isLongPress.value,
+		onLongPress: () => state.open("first"),
+		onLongPressStart: () => state.close()
+	});
+	const open = (strategy) => {
+		focusTrigger();
+		state.toggle(strategy);
+	};
+	const onKeydown = (event) => {
+		if (isDisabled.value) return;
+		if (event.defaultPrevented && event.key !== "Enter" && event.key !== " ") return;
+		if (event.altKey && (event.key === "ArrowDown" || event.key === "ArrowUp")) {
+			event.preventDefault();
+			event.stopPropagation();
+			open(event.key === "ArrowDown" ? "first" : "last");
+			return;
+		}
+		if (isLongPress.value) return;
+		switch (event.key) {
+			case " ":
+			case "Enter":
+			case "ArrowDown":
+				event.preventDefault();
+				event.stopPropagation();
+				open("first");
+				return;
+			case "ArrowUp":
+				event.preventDefault();
+				event.stopPropagation();
+				open("last");
+				return;
+			default: return;
+		}
+	};
+	const responder = {
+		attrs: computed(() => ({
+			...triggerAttributes.value,
+			"aria-describedby": longPress.describedBy.value,
+			id: triggerId.value
+		})),
+		handlers: computed(() => {
+			const handlers = isLongPress.value ? longPress.handlers : press.handlers;
+			return {
+				...handlers,
+				onKeydown: (event) => {
+					handlers.onKeydown(event);
+					onKeydown(event);
+				}
+			};
+		}),
+		isPressed: press.isPressed,
+		registerElement: (next) => {
+			element.value = next;
+		}
+	};
+	return {
+		autoFocus: computed(() => state.focusStrategy.value ?? true),
+		overlayId,
+		responder,
+		triggerElement: computed(() => element.value),
+		triggerId
+	};
+};
+//#endregion
+export { DEFAULT_LONG_PRESS_DESCRIPTION, useMenuTrigger };

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

@@ -0,0 +1,61 @@
+import type { CollectionKey } from "./use-collection";
+import type { FocusStrategy } from "./use-overlay-trigger-state";
+import type { CollectionSelection, DisabledBehavior, SelectionBehavior, SelectionMode } from "./use-selection-manager";
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+export interface UseMenuOptions {
+    /** Overrides the menu's id, which a trigger's `aria-controls` points at. */
+    id?: MaybeRefOrGetter<string | undefined>;
+    /** The id of the element naming the menu, normally the trigger. */
+    labelledBy?: MaybeRefOrGetter<string | undefined>;
+    selectionMode?: MaybeRefOrGetter<SelectionMode | undefined>;
+    selectionBehavior?: MaybeRefOrGetter<SelectionBehavior | undefined>;
+    selectedKeys?: MaybeRefOrGetter<"all" | Iterable<CollectionKey> | undefined>;
+    defaultSelectedKeys?: "all" | Iterable<CollectionKey>;
+    disallowEmptySelection?: MaybeRefOrGetter<boolean | undefined>;
+    disabledKeys?: MaybeRefOrGetter<Iterable<CollectionKey> | undefined>;
+    disabledBehavior?: MaybeRefOrGetter<DisabledBehavior | undefined>;
+    /** Whether choosing an item closes the menu. @default true */
+    shouldCloseOnSelect?: MaybeRefOrGetter<boolean | undefined>;
+    /**
+     * Where focus lands when the menu appears. `"first"`/`"last"` pick an end, `true` focuses the
+     * menu itself, and a selected item wins over any of them.
+     */
+    autoFocus?: MaybeRefOrGetter<boolean | FocusStrategy | undefined>;
+    onAction?: (key: CollectionKey) => void;
+    onSelectionChange?: (keys: CollectionSelection) => void;
+    /** Closes the menu, and every menu above it. */
+    onClose?: () => void;
+}
+export interface UseMenuReturn {
+    /** Assign the menu element to this. */
+    element: ShallowRef<HTMLElement | null>;
+    menuId: ComputedRef<string>;
+    collectionId: ComputedRef<string>;
+    /** Attributes the menu element renders, beside its own class and `data-slot`. */
+    menuAttributes: ComputedRef<Record<string, string | number | boolean | undefined>>;
+    onKeydown: (event: KeyboardEvent) => void;
+    onKeydownCapture: (event: KeyboardEvent) => void;
+    onFocusin: (event: FocusEvent) => void;
+    onFocusout: (event: FocusEvent) => void;
+    isEmpty: ComputedRef<boolean>;
+    selectionMode: ComputedRef<SelectionMode>;
+}
+/**
+ * The behaviour of a menu, ported from React Aria's `useMenu`.
+ *
+ * Separated from the component because two components render a menu — the standalone one and the
+ * one inside a dropdown — and they differ only in the class and `data-slot` they carry. React
+ * splits them the same way, over a shared primitive.
+ *
+ * Two things differ from a listbox and both matter. Arrow keys wrap, because a menu is a short
+ * list of actions where running off the end is a dead end rather than a boundary worth feeling.
+ * And Enter and Space are left to the items: a menu's sections can each hold their own selection,
+ * so only the item knows which one it belongs to.
+ *
+ * @example
+ * ```ts
+ * const menu = useMenu({labelledBy: () => triggerId, onClose: state.close});
+ * // <div ref="element" v-bind="menu.menuAttributes.value" @keydown="menu.onKeydown">
+ * ```
+ */
+export declare const useMenu: (options?: UseMenuOptions) => UseMenuReturn;

package/dist/composables/use-menu.js

@@ -0,0 +1,108 @@
+import { useId as useId$1 } from "./use-id.js";
+import { useCollection } from "./use-collection.js";
+import { useSelectionManager } from "./use-selection-manager.js";
+import { useCollectionAutoFocus } from "./use-collection-auto-focus.js";
+import { useListKeyboard } from "./use-list-keyboard.js";
+import { useTypeahead } from "./use-typeahead.js";
+import { provideMenuItemPopupContext } from "../components/menu-item/menu-item.context.js";
+import { provideMenuContext } from "../components/menu/menu.context.js";
+import { computed, shallowRef, toValue } from "vue";
+//#region src/composables/use-menu.ts
+/**
+* The behaviour of a menu, ported from React Aria's `useMenu`.
+*
+* Separated from the component because two components render a menu — the standalone one and the
+* one inside a dropdown — and they differ only in the class and `data-slot` they carry. React
+* splits them the same way, over a shared primitive.
+*
+* Two things differ from a listbox and both matter. Arrow keys wrap, because a menu is a short
+* list of actions where running off the end is a dead end rather than a boundary worth feeling.
+* And Enter and Space are left to the items: a menu's sections can each hold their own selection,
+* so only the item knows which one it belongs to.
+*
+* @example
+* ```ts
+* const menu = useMenu({labelledBy: () => triggerId, onClose: state.close});
+* // <div ref="element" v-bind="menu.menuAttributes.value" @keydown="menu.onKeydown">
+* ```
+*/
+var useMenu = (options = {}) => {
+	const menuId = useId$1(options.id);
+	const collectionId = useId$1();
+	const element = shallowRef(null);
+	const collection = useCollection();
+	const selection = useSelectionManager({
+		collection,
+		defaultSelectedKeys: options.defaultSelectedKeys,
+		disabledBehavior: options.disabledBehavior,
+		disabledKeys: options.disabledKeys,
+		disallowEmptySelection: options.disallowEmptySelection,
+		onSelectionChange: options.onSelectionChange,
+		selectedKeys: options.selectedKeys,
+		selectionBehavior: options.selectionBehavior,
+		selectionMode: options.selectionMode
+	});
+	const keyboard = useListKeyboard({
+		collection,
+		disallowActivation: true,
+		element,
+		selection,
+		shouldFocusWrap: true
+	});
+	const typeahead = useTypeahead({
+		focusedKey: () => selection.focusedKey.value,
+		getKeyForSearch: keyboard.getKeyForSearch,
+		onSearchMatch: (key) => keyboard.focusKey(key, { scroll: true })
+	});
+	const shouldCloseOnSelect = computed(() => toValue(options.shouldCloseOnSelect) ?? true);
+	/**
+	* Cleared here, at every menu.
+	*
+	* A submenu trigger provides it for the one item that opens the submenu, and that item sits in
+	* the menu *above*. The submenu's own items are deeper in the same tree, so without clearing it
+	* they would each read as opening the same submenu — and each would claim to be its trigger,
+	* the last one winning and closing the submenu the moment it appeared.
+	*/
+	provideMenuItemPopupContext(null);
+	provideMenuContext({
+		collection,
+		collectionId,
+		element,
+		keyboard,
+		menuId,
+		onAction: options.onAction,
+		onClose: options.onClose,
+		selection,
+		shouldCloseOnSelect
+	});
+	useCollectionAutoFocus({
+		autoFocus: options.autoFocus,
+		element,
+		keyboard,
+		selection
+	});
+	return {
+		collectionId,
+		element,
+		isEmpty: computed(() => collection.size.value === 0),
+		menuAttributes: computed(() => ({
+			"aria-labelledby": toValue(options.labelledBy),
+			"data-collection": collectionId.value,
+			"data-empty": collection.size.value === 0 ? "true" : void 0,
+			id: menuId.value,
+			role: "menu",
+			tabindex: keyboard.collectionTabIndex.value
+		})),
+		menuId,
+		onFocusin: keyboard.onFocusin,
+		onFocusout: keyboard.onFocusout,
+		onKeydown: (event) => {
+			typeahead.onKeydown(event);
+			if (!event.defaultPrevented) keyboard.onKeydown(event);
+		},
+		onKeydownCapture: typeahead.onKeydownCapture,
+		selectionMode: selection.selectionMode
+	};
+};
+//#endregion
+export { useMenu };

package/dist/composables/use-modal-overlay.d.ts

@@ -0,0 +1,62 @@
+import type { PageSize, ViewportSize } from "./use-viewport-size";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseModalOverlayOptions {
+    /**
+     * The modal itself: the boundary an outside interaction is measured against, and the one subtree
+     * left visible to assistive technology.
+     *
+     * Not the backdrop. React Aria passes the container for the same reason — a press on the backdrop
+     * beside the dialog is *outside* the modal and has to dismiss it.
+     */
+    modalRef: MaybeRefOrGetter<HTMLElement | null | undefined>;
+    isOpen: MaybeRefOrGetter<boolean>;
+    onClose: () => void;
+    /** Whether an interaction outside the modal dismisses it. @default false */
+    isDismissable?: MaybeRefOrGetter<boolean | undefined>;
+    /** @default false */
+    isKeyboardDismissDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    /** Filters which outside elements dismiss the modal. */
+    shouldCloseOnInteractOutside?: (element: Element) => boolean;
+}
+export interface UseModalOverlayReturn {
+    /**
+     * Bind to the **container**, not the backdrop.
+     *
+     * React Aria puts Escape on the same element, and it has to be one focus can reach from inside
+     * the dialog — a key pressed in the dialog bubbles through the container and nowhere near the
+     * backdrop, which is a sibling of nothing on that path.
+     */
+    onKeydown: (event: KeyboardEvent) => void;
+    /** Publish on the backdrop as inline custom properties the stylesheet reads. */
+    viewportStyle: ComputedRef<Record<string, string>>;
+    viewport: ComputedRef<ViewportSize>;
+    page: ComputedRef<PageSize>;
+}
+/**
+ * Everything a modal overlay does besides render, ported from React Aria's `useModalOverlay` and
+ * the `Overlay` layer around it.
+ *
+ * Four things happen while a modal is open, and **the order they are set up in is the contract**,
+ * not an implementation detail. Cleanups run in the order their watchers were created, so:
+ *
+ * 1. dismissal — Escape and outside presses;
+ * 2. hiding the rest of the page from assistive technology, with `inert`;
+ * 3. containing focus, and giving it back on close;
+ * 4. holding the page still.
+ *
+ * Two and three cannot be swapped. Focus is restored to the trigger when the scope tears down, and
+ * a trigger inside an `inert` subtree cannot take focus — so the page has to be made live again
+ * first. Getting this wrong leaves a keyboard user at the top of the document with no indication
+ * anything happened, and nothing in jsdom notices.
+ *
+ * @example
+ * ```ts
+ * const overlay = useModalOverlay({
+ *   isDismissable: () => props.isDismissable,
+ *   isOpen: () => state.isOpen.value,
+ *   modalRef: containerElement,
+ *   onClose: state.close,
+ * });
+ * ```
+ */
+export declare const useModalOverlay: (options: UseModalOverlayOptions) => UseModalOverlayReturn;

package/dist/composables/use-modal-overlay.js

@@ -0,0 +1,77 @@
+import { ariaHideOutside } from "../utils/aria-hide-outside.js";
+import { useFocusScope } from "./use-focus-scope.js";
+import { useDismissable } from "./use-dismissable.js";
+import { usePreventScroll } from "./use-prevent-scroll.js";
+import { usePageSize, useViewportSize } from "./use-viewport-size.js";
+import { computed, toValue, watch } from "vue";
+//#region src/composables/use-modal-overlay.ts
+/**
+* Everything a modal overlay does besides render, ported from React Aria's `useModalOverlay` and
+* the `Overlay` layer around it.
+*
+* Four things happen while a modal is open, and **the order they are set up in is the contract**,
+* not an implementation detail. Cleanups run in the order their watchers were created, so:
+*
+* 1. dismissal — Escape and outside presses;
+* 2. hiding the rest of the page from assistive technology, with `inert`;
+* 3. containing focus, and giving it back on close;
+* 4. holding the page still.
+*
+* Two and three cannot be swapped. Focus is restored to the trigger when the scope tears down, and
+* a trigger inside an `inert` subtree cannot take focus — so the page has to be made live again
+* first. Getting this wrong leaves a keyboard user at the top of the document with no indication
+* anything happened, and nothing in jsdom notices.
+*
+* @example
+* ```ts
+* const overlay = useModalOverlay({
+*   isDismissable: () => props.isDismissable,
+*   isOpen: () => state.isOpen.value,
+*   modalRef: containerElement,
+*   onClose: state.close,
+* });
+* ```
+*/
+var useModalOverlay = (options) => {
+	const isOpen = () => toValue(options.isOpen);
+	const dismissable = useDismissable({
+		isDismissable: options.isDismissable,
+		isKeyboardDismissDisabled: options.isKeyboardDismissDisabled,
+		isOpen,
+		onClose: options.onClose,
+		overlayRef: options.modalRef,
+		shouldCloseOnInteractOutside: options.shouldCloseOnInteractOutside
+	});
+	watch([isOpen, () => toValue(options.modalRef)], ([open, modal], _previous, onCleanup) => {
+		if (!open || !modal) return;
+		onCleanup(ariaHideOutside([modal], { shouldUseInert: true }));
+	}, {
+		flush: "post",
+		immediate: true
+	});
+	useFocusScope({
+		contain: true,
+		isActive: isOpen,
+		restoreFocus: true,
+		scopeRef: options.modalRef
+	});
+	usePreventScroll({ isDisabled: () => !isOpen() });
+	const viewport = useViewportSize();
+	const page = usePageSize();
+	return {
+		onKeydown: dismissable.onKeydown,
+		page: computed(() => page.value),
+		viewport: computed(() => viewport.value),
+		viewportStyle: computed(() => {
+			const style = {
+				"--visual-viewport-height": `${viewport.value.height}px`,
+				"--visual-viewport-width": `${viewport.value.width}px`
+			};
+			if (page.value.width !== void 0) style["--page-width"] = `${page.value.width}px`;
+			if (page.value.height !== void 0) style["--page-height"] = `${page.value.height}px`;
+			return style;
+		})
+	};
+};
+//#endregion
+export { useModalOverlay };