ropav 0.0.10 → 0.0.12

package/dist/useFocusTrap.js

@@ -0,0 +1,130 @@
+import { onBeforeUnmount, readonly, ref, shallowRef, toValue, watch } from "vue";
+import { createFocusTrap } from "focus-trap";
+//#region src/components/focus-trap/useFocusTrap.ts
+function hasContainers(containers) {
+	return Array.isArray(containers) ? containers.length > 0 : Boolean(containers);
+}
+function useFocusTrap(target, options = {}) {
+	const focusTrap = shallowRef(null);
+	const isActive = ref(false);
+	const isPaused = ref(false);
+	let shouldActivate = Boolean(options.immediate);
+	let shouldPause = false;
+	function syncState(trap) {
+		isActive.value = trap.active;
+		isPaused.value = trap.paused;
+	}
+	function createTrap(containers) {
+		const { immediate: _immediate, ...focusTrapOptions } = options;
+		const { onActivate, onDeactivate, onPause, onUnpause, onPostActivate, onPostDeactivate, onPostPause, onPostUnpause } = focusTrapOptions;
+		const trap = createFocusTrap(containers, {
+			...focusTrapOptions,
+			onActivate(parameters) {
+				syncState(parameters.trap);
+				onActivate?.(parameters);
+			},
+			onPostActivate(parameters) {
+				syncState(parameters.trap);
+				onPostActivate?.(parameters);
+			},
+			onDeactivate(parameters) {
+				syncState(parameters.trap);
+				onDeactivate?.(parameters);
+			},
+			onPostDeactivate(parameters) {
+				syncState(parameters.trap);
+				onPostDeactivate?.(parameters);
+			},
+			onPause(parameters) {
+				syncState(parameters.trap);
+				onPause?.(parameters);
+			},
+			onPostPause(parameters) {
+				syncState(parameters.trap);
+				onPostPause?.(parameters);
+			},
+			onUnpause(parameters) {
+				syncState(parameters.trap);
+				onUnpause?.(parameters);
+			},
+			onPostUnpause(parameters) {
+				syncState(parameters.trap);
+				onPostUnpause?.(parameters);
+			}
+		});
+		focusTrap.value = trap;
+		return trap;
+	}
+	function activate(activateOptions) {
+		shouldActivate = true;
+		shouldPause = false;
+		const trap = focusTrap.value;
+		if (!trap) return;
+		trap.activate(activateOptions);
+		syncState(trap);
+	}
+	function deactivate(deactivateOptions) {
+		shouldActivate = false;
+		shouldPause = false;
+		const trap = focusTrap.value;
+		if (!trap) return;
+		trap.deactivate(deactivateOptions);
+		syncState(trap);
+	}
+	function pause(pauseOptions) {
+		shouldPause = true;
+		const trap = focusTrap.value;
+		if (!trap) return;
+		trap.pause(pauseOptions);
+		syncState(trap);
+	}
+	function unpause(unpauseOptions) {
+		shouldPause = false;
+		const trap = focusTrap.value;
+		if (!trap) return;
+		trap.unpause(unpauseOptions);
+		syncState(trap);
+	}
+	function updateContainerElements(containers) {
+		const trap = focusTrap.value ?? createTrap(containers);
+		trap.updateContainerElements(containers);
+		syncState(trap);
+	}
+	watch(() => toValue(target), (containers) => {
+		if (!hasContainers(containers)) {
+			focusTrap.value?.deactivate({ returnFocus: false });
+			focusTrap.value = null;
+			isActive.value = false;
+			isPaused.value = false;
+			return;
+		}
+		const trap = focusTrap.value ?? createTrap(containers);
+		trap.updateContainerElements(containers);
+		if (shouldActivate && !trap.active) trap.activate();
+		if (shouldPause && trap.active && !trap.paused) trap.pause();
+		syncState(trap);
+	}, {
+		flush: "post",
+		immediate: true
+	});
+	onBeforeUnmount(() => {
+		shouldActivate = false;
+		shouldPause = false;
+		focusTrap.value?.deactivate();
+		focusTrap.value = null;
+		isActive.value = false;
+		isPaused.value = false;
+	});
+	return {
+		focusTrap,
+		isActive: readonly(isActive),
+		isPaused: readonly(isPaused),
+		activate,
+		deactivate,
+		pause,
+		unpause,
+		updateContainerElements
+	};
+}
+//#endregion
+export { useFocusTrap as t };

package/dist/useFormControl.js

@@ -0,0 +1,107 @@
+import { computed, inject, provide, shallowRef, watch, watchEffect } from "vue";
+//#region src/composables/useControllableValue.ts
+function useControllableValue(options) {
+	const initialValue = options.defaultValue();
+	const uncontrolledValue = shallowRef(initialValue);
+	const isControlled = computed(() => options.modelValue() !== void 0);
+	watch(options.modelValue, (value) => {
+		if (value !== void 0) uncontrolledValue.value = value;
+	}, { immediate: true });
+	const value = computed(() => options.modelValue() ?? uncontrolledValue.value);
+	function setValue(nextValue) {
+		if (!isControlled.value) uncontrolledValue.value = nextValue;
+		options.onChange(nextValue);
+	}
+	function resetValue(nextValue = initialValue) {
+		if (!isControlled.value) uncontrolledValue.value = nextValue;
+	}
+	return {
+		initialValue,
+		isControlled,
+		value,
+		setValue,
+		resetValue
+	};
+}
+//#endregion
+//#region src/composables/useFormControl.ts
+var nestedFormControlOwnerKey = Symbol("nestedFormControlOwner");
+function provideNestedFormControlOwner() {
+	let claimed = false;
+	provide(nestedFormControlOwnerKey, () => {
+		if (claimed) return false;
+		claimed = true;
+		return true;
+	});
+}
+function claimNestedFormControlOwner() {
+	return inject(nestedFormControlOwnerKey, void 0)?.() ?? false;
+}
+function getElements(options) {
+	return options.elements().filter((element) => Boolean(element));
+}
+function useFormControl(options) {
+	const initialized = /* @__PURE__ */ new WeakSet();
+	watchEffect(() => {
+		const elements = getElements(options);
+		for (const [index, element] of elements.entries()) {
+			if (!initialized.has(element)) {
+				options.initializeDefault?.(element, index);
+				initialized.add(element);
+			}
+			element.setCustomValidity(options.validationMessage?.(element, index, elements) ?? "");
+		}
+	}, { flush: "post" });
+	watchEffect((onCleanup) => {
+		const documents = new Set(getElements(options).map((element) => element.ownerDocument));
+		if (documents.size === 0) return;
+		function onReset(event) {
+			const form = event.target;
+			if (!(form instanceof HTMLFormElement)) return;
+			const elements = getElements(options).filter((element) => element.form === form);
+			if (elements.length === 0) return;
+			queueMicrotask(() => {
+				if (options.isControlled()) options.syncControlledValue(elements);
+				else options.readResetValue(elements);
+			});
+		}
+		for (const document of documents) document.addEventListener("reset", onReset, true);
+		onCleanup(() => {
+			for (const document of documents) document.removeEventListener("reset", onReset, true);
+		});
+	}, { flush: "post" });
+}
+function useTextFormControl(element, controllable, validationMessage) {
+	useFormControl({
+		elements: () => [element()],
+		isControlled: () => controllable.isControlled.value,
+		initializeDefault(control) {
+			control.defaultValue = controllable.initialValue;
+		},
+		validationMessage,
+		readResetValue([control]) {
+			controllable.resetValue(control.value);
+		},
+		syncControlledValue([control]) {
+			control.value = controllable.value.value;
+		}
+	});
+}
+function useCheckedFormControl(element, controllable, validationMessage) {
+	useFormControl({
+		elements: () => [element()],
+		isControlled: () => controllable.isControlled.value,
+		initializeDefault(control) {
+			control.defaultChecked = controllable.initialValue;
+		},
+		validationMessage,
+		readResetValue([control]) {
+			controllable.resetValue(control.checked);
+		},
+		syncControlledValue([control]) {
+			control.checked = controllable.value.value;
+		}
+	});
+}
+//#endregion
+export { useTextFormControl as a, useFormControl as i, provideNestedFormControlOwner as n, useControllableValue as o, useCheckedFormControl as r, claimNestedFormControlOwner as t };

package/dist/useOverlayLayer.js

@@ -0,0 +1,262 @@
+import { computed, inject, onBeforeUnmount, provide, readonly, ref, shallowRef, toValue, watch } from "vue";
+//#region src/composables/useOverlayLayer.ts
+var overlayLayerKey = Symbol("overlay-layer");
+var documentStates = /* @__PURE__ */ new WeakMap();
+var layerMetadata = /* @__PURE__ */ new WeakMap();
+function createState() {
+	return {
+		layers: [],
+		inertSnapshots: /* @__PURE__ */ new Map(),
+		originalBodyOverflow: "",
+		scrollLocked: false,
+		observer: null,
+		syncQueued: false
+	};
+}
+function getState(document) {
+	const existing = documentStates.get(document);
+	if (existing) return existing;
+	const state = createState();
+	documentStates.set(document, state);
+	return state;
+}
+function isDescendantLayer(layer, ancestor) {
+	let parent = layerMetadata.get(layer)?.parent ?? null;
+	while (parent) {
+		if (parent === ancestor) return true;
+		parent = layerMetadata.get(parent)?.parent ?? null;
+	}
+	return false;
+}
+function syncLayerZIndices(state) {
+	let highestZIndex = Number.NEGATIVE_INFINITY;
+	for (const layer of state.layers) {
+		const metadata = layerMetadata.get(layer);
+		if (!metadata) continue;
+		const zIndex = Math.max(metadata.baseZIndex, highestZIndex + 2);
+		metadata.setZIndex(zIndex);
+		highestZIndex = zIndex;
+	}
+}
+function isEventWithinElement(event, element) {
+	const path = event.composedPath();
+	if (path.length > 0) return path.some((entry) => entry === element || typeof Node !== "undefined" && entry instanceof Node && element.contains(entry));
+	return typeof Node !== "undefined" && event.target instanceof Node && element.contains(event.target);
+}
+function restoreInertBackground(state) {
+	for (const [element, snapshot] of state.inertSnapshots) {
+		element.inert = snapshot.inert;
+		if (snapshot.ariaHidden == null) element.removeAttribute("aria-hidden");
+		else element.setAttribute("aria-hidden", snapshot.ariaHidden);
+	}
+	state.inertSnapshots.clear();
+}
+function inertElement(state, element) {
+	if (!state.inertSnapshots.has(element)) state.inertSnapshots.set(element, {
+		ariaHidden: element.getAttribute("aria-hidden"),
+		inert: Boolean(element.inert)
+	});
+	element.inert = true;
+	element.setAttribute("aria-hidden", "true");
+}
+function inertUnprotectedBranches(state, parent, protectedRoots) {
+	for (const child of parent.children) {
+		if (!(child instanceof HTMLElement)) continue;
+		if (!protectedRoots.some((root) => child === root || child.contains(root))) {
+			inertElement(state, child);
+			continue;
+		}
+		if (!protectedRoots.includes(child)) inertUnprotectedBranches(state, child, protectedRoots);
+	}
+}
+function stopObserver(state) {
+	state.observer?.disconnect();
+	state.observer = null;
+	state.syncQueued = false;
+}
+function unlockScroll(document, state) {
+	if (!state.scrollLocked) return;
+	document.body.style.overflow = state.originalBodyOverflow;
+	state.scrollLocked = false;
+}
+function queueModalEffects(document, state) {
+	if (state.syncQueued) return;
+	state.syncQueued = true;
+	queueMicrotask(() => {
+		state.syncQueued = false;
+		syncModalEffects(document, state);
+	});
+}
+function startObserver(document, state) {
+	if (state.observer || typeof MutationObserver === "undefined") return;
+	state.observer = new MutationObserver(() => queueModalEffects(document, state));
+	state.observer.observe(document.body, {
+		childList: true,
+		subtree: true
+	});
+}
+function syncModalEffects(document, state) {
+	restoreInertBackground(state);
+	let modalIndex = -1;
+	for (let index = state.layers.length - 1; index >= 0; index -= 1) {
+		const layer = state.layers[index];
+		if (layer?.modalEffects && layer.modal.value) {
+			modalIndex = index;
+			break;
+		}
+	}
+	const shouldLock = state.layers.some((layer) => layer.modalEffects && layer.modal.value && layer.preventScroll.value);
+	if (shouldLock && !state.scrollLocked) {
+		state.originalBodyOverflow = document.body.style.overflow;
+		document.body.style.overflow = "hidden";
+		state.scrollLocked = true;
+	} else if (!shouldLock) unlockScroll(document, state);
+	if (modalIndex < 0) {
+		stopObserver(state);
+		return;
+	}
+	const protectedRoots = [];
+	for (const layer of state.layers.slice(modalIndex)) {
+		const element = layer.element.value;
+		if (element?.isConnected) protectedRoots.push(element);
+		for (const branch of layer.branches.value) if (branch.isConnected) protectedRoots.push(branch);
+	}
+	if (protectedRoots.length > 0) {
+		inertUnprotectedBranches(state, document.body, protectedRoots);
+		startObserver(document, state);
+	}
+}
+function removeLayer(layer, document, state) {
+	const index = state.layers.indexOf(layer);
+	if (index >= 0) state.layers.splice(index, 1);
+	syncLayerZIndices(state);
+	syncModalEffects(document, state);
+}
+function useOverlayLayer(options) {
+	const parent = inject(overlayLayerKey, null);
+	const active = computed(() => Boolean(toValue(options.active)));
+	const modal = computed(() => Boolean(toValue(options.modal ?? false)));
+	const preventScroll = computed(() => Boolean(toValue(options.preventScroll ?? true)));
+	const branches = shallowRef([]);
+	const focusBranches = shallowRef([]);
+	const branchSet = /* @__PURE__ */ new Set();
+	const focusBranchSet = /* @__PURE__ */ new Set();
+	const insideBranchSet = /* @__PURE__ */ new Set();
+	const zIndex = ref(options.baseZIndex ?? 100);
+	let registeredDocument = null;
+	let registeredElement = null;
+	let parentBranchCleanup;
+	function syncBranches() {
+		branches.value = [...branchSet];
+		focusBranches.value = [...focusBranchSet];
+		if (registeredDocument) syncModalEffects(registeredDocument, getState(registeredDocument));
+	}
+	function registerBranch(element, branchOptions = {}) {
+		branchSet.add(element);
+		if (branchOptions.focus !== false) focusBranchSet.add(element);
+		if (branchOptions.inside !== false) insideBranchSet.add(element);
+		const parentCleanup = parent?.registerBranch(element, branchOptions);
+		syncBranches();
+		return () => {
+			branchSet.delete(element);
+			focusBranchSet.delete(element);
+			insideBranchSet.delete(element);
+			parentCleanup?.();
+			syncBranches();
+		};
+	}
+	function replaceParentBranch(element) {
+		parentBranchCleanup?.();
+		parentBranchCleanup = element ? parent?.registerBranch(element) : void 0;
+	}
+	const context = {
+		id: Symbol("overlay-layer"),
+		element: options.element,
+		active,
+		modal,
+		modalEffects: options.modalEffects === true,
+		preventScroll,
+		branches,
+		focusBranches,
+		zIndex: readonly(zIndex),
+		isTopLayer() {
+			if (!registeredDocument) return false;
+			const layers = getState(registeredDocument).layers;
+			return layers[layers.length - 1] === context;
+		},
+		isInside(event, additional = []) {
+			return [
+				options.element.value,
+				...insideBranchSet,
+				...additional
+			].some((element) => element != null && isEventWithinElement(event, element));
+		},
+		registerBranch
+	};
+	layerMetadata.set(context, {
+		baseZIndex: options.baseZIndex ?? 100,
+		parent,
+		setZIndex(value) {
+			zIndex.value = value;
+		}
+	});
+	function unregister() {
+		replaceParentBranch(null);
+		if (!registeredDocument) return;
+		const document = registeredDocument;
+		registeredDocument = null;
+		registeredElement = null;
+		removeLayer(context, document, getState(document));
+	}
+	function register(element) {
+		const document = element.ownerDocument;
+		if (registeredDocument === document) {
+			if (registeredElement !== element) {
+				replaceParentBranch(element);
+				registeredElement = element;
+				syncModalEffects(document, getState(document));
+			}
+			return;
+		}
+		unregister();
+		const state = getState(document);
+		const currentIndex = state.layers.indexOf(context);
+		if (currentIndex >= 0) state.layers.splice(currentIndex, 1);
+		const descendantIndex = state.layers.findIndex((layer) => isDescendantLayer(layer, context));
+		if (descendantIndex >= 0) state.layers.splice(descendantIndex, 0, context);
+		else state.layers.push(context);
+		registeredDocument = document;
+		registeredElement = element;
+		replaceParentBranch(element);
+		syncLayerZIndices(state);
+		syncModalEffects(document, state);
+	}
+	watch([active, options.element], ([isActive, element]) => {
+		if (isActive && element?.isConnected) register(element);
+		else unregister();
+	}, {
+		flush: "post",
+		immediate: true
+	});
+	watch([modal, preventScroll], () => {
+		if (registeredDocument) syncModalEffects(registeredDocument, getState(registeredDocument));
+	});
+	onBeforeUnmount(unregister);
+	provide(overlayLayerKey, context);
+	return context;
+}
+function useOverlayLayerBranch(element, options = {}) {
+	const layer = inject(overlayLayerKey, null);
+	let cleanup;
+	watch(element, (nextElement) => {
+		cleanup?.();
+		cleanup = nextElement ? layer?.registerBranch(nextElement, options) : void 0;
+	}, {
+		flush: "post",
+		immediate: true
+	});
+	onBeforeUnmount(() => cleanup?.());
+	return layer;
+}
+//#endregion
+export { useOverlayLayerBranch as n, useOverlayLayer as t };

package/dist/useTeleportTarget.js

@@ -0,0 +1,40 @@
+import { computed, inject, isRef, provide, toValue } from "vue";
+//#region src/components/teleport-provider/useTeleportTarget.ts
+var teleportTargetKey = Symbol("teleport-target");
+function readTeleportTarget(target) {
+	return isRef(target) ? target.value : target;
+}
+function hasTarget(target) {
+	return target != null && target !== "";
+}
+function provideTeleportTarget(props, positioningKey) {
+	const parentContext = inject(teleportTargetKey, void 0);
+	const target = computed(() => {
+		const ownTarget = readTeleportTarget(props.teleportTo);
+		if (hasTarget(ownTarget)) return ownTarget;
+		return parentContext?.target.value ?? "body";
+	});
+	provide(teleportTargetKey, {
+		target,
+		positioningKey: computed(() => [
+			target.value,
+			toValue(positioningKey),
+			parentContext?.positioningKey.value
+		])
+	});
+	return target;
+}
+function useTeleportTarget(target) {
+	const providedContext = inject(teleportTargetKey, void 0);
+	return computed(() => {
+		const ownTarget = readTeleportTarget(toValue(target));
+		if (hasTarget(ownTarget)) return ownTarget;
+		return providedContext?.target.value ?? "body";
+	});
+}
+function useTeleportPositioningKey() {
+	const providedContext = inject(teleportTargetKey, void 0);
+	return computed(() => providedContext?.positioningKey.value);
+}
+//#endregion
+export { useTeleportPositioningKey as n, useTeleportTarget as r, provideTeleportTarget as t };

package/docs/public-floating-api.md

@@ -0,0 +1,148 @@
+# Public floating API
+
+`useFloatingPosition` provides Ropav's positioning behavior without rendering component DOM or
+styles. It applies the same offset, flip, shift and collision defaults used by Ropav overlays.
+
+```vue
+<template>
+  <button
+    ref="reference"
+    type="button"
+    aria-haspopup="dialog"
+    :aria-expanded="open"
+    @click="open = !open"
+  >
+    Toggle card
+  </button>
+
+  <Teleport :to="teleportTo" :disabled="!teleport">
+    <section v-if="open" ref="floating" :style="floatingStyle" :data-placement="actualPlacement">
+      Custom content
+      <span ref="arrow" :style="arrowStyle" aria-hidden="true" />
+    </section>
+  </Teleport>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useFloatingPosition } from 'ropav/floating';
+import { useTeleportTarget } from 'ropav/teleport-provider';
+
+const reference = ref<HTMLElement | null>(null);
+const floating = ref<HTMLElement | null>(null);
+const arrow = ref<HTMLElement | null>(null);
+const open = ref(false);
+const teleport = ref(true);
+const teleportTo = useTeleportTarget();
+
+const { actualPlacement, arrowStyle, floatingStyle } = useFloatingPosition({
+  reference,
+  floating,
+  arrow,
+  open,
+  placement: 'bottom-start',
+  offset: 8,
+  restartKey: () => [teleport.value, teleportTo.value],
+});
+</script>
+```
+
+The composable accepts plain values, refs, computed refs or getters for reactive options.
+
+| Option             | Default    | Description                                                    |
+| ------------------ | ---------- | -------------------------------------------------------------- |
+| `reference`        | required   | Element or virtual element used as the anchor.                 |
+| `floating`         | required   | Floating HTML element.                                         |
+| `arrow`            | —          | Optional arrow HTML element.                                   |
+| `open`             | `true`     | Suspends positioning and auto-updates when false.              |
+| `placement`        | `bottom`   | Preferred side and optional alignment.                         |
+| `strategy`         | `absolute` | CSS positioning strategy: `absolute` or `fixed`.               |
+| `offset`           | `8`        | Main/cross-axis distance from the reference.                   |
+| `flip`             | `true`     | Tries the opposite side when space is insufficient.            |
+| `shift`            | `true`     | Keeps the floating element inside the collision boundary.      |
+| `collisionPadding` | `8`        | Padding between the floating element and viewport boundary.    |
+| `restartKey`       | —          | Rebinds auto-update observers when its reactive value changes. |
+
+The return value contains readonly `actualPlacement`, `floatingStyle`, `arrowStyle` and
+`isPositioned` refs, plus an async `update()` method for content-driven layout changes.
+
+`useTeleportTarget()` resolves the nearest `TeleportProvider` target and falls back to `body`. Pass
+a target value, ref or getter to override the provider for one floating element. Include the
+resolved target and the Teleport enabled state in `restartKey` whenever either can change while the
+floating element is open.
+
+Positioning does not add interaction or accessibility behavior. Custom overlays remain responsible
+for keyboard handling, focus management, roles, labels, outside interaction and dismissal.
+
+## Hover disclosure interactions
+
+`useHoverDisclosure` manages hover and focus state without rendering DOM or positioning content. It
+coordinates the trigger and floating content, so a close delay started when the pointer leaves the
+trigger is cancelled when the pointer enters the content.
+
+```vue
+<template>
+  <a ref="reference" href="/people/ada" v-bind="triggerProps">Ada Lovelace</a>
+
+  <Teleport to="body">
+    <section
+      v-if="isOpen"
+      ref="floating"
+      v-bind="contentProps"
+      :style="floatingStyle"
+      :data-placement="actualPlacement"
+    >
+      Mathematician and writer
+    </section>
+  </Teleport>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useFloatingPosition, useHoverDisclosure } from 'ropav/floating';
+
+const reference = ref<HTMLElement | null>(null);
+const floating = ref<HTMLElement | null>(null);
+
+const { isOpen, triggerProps, contentProps } = useHoverDisclosure({
+  openDelay: 600,
+  closeDelay: 150,
+});
+
+const { actualPlacement, floatingStyle } = useFloatingPosition({
+  reference,
+  floating,
+  open: isOpen,
+  placement: 'bottom-start',
+});
+</script>
+```
+
+Focus opens immediately by default. Hover uses `openDelay`; leaving the combined trigger/content
+area uses `closeDelay`. Escape dismisses an open disclosure even when keyboard focus is elsewhere.
+The return value also contains `state`, `isDisabled`, and immediate `open()`, `close()` and
+`toggle()` controls.
+
+| Option              | Default | Description                                                                 |
+| ------------------- | ------- | --------------------------------------------------------------------------- |
+| `open`              | —       | Controlled open state. Omit it for internal state.                          |
+| `defaultOpen`       | `false` | Initial internal state.                                                     |
+| `openDelay`         | `0`     | Delay in milliseconds before pointer hover opens the disclosure.            |
+| `closeDelay`        | `0`     | Delay before closing after pointer and focus leave trigger and content.     |
+| `disabled`          | `false` | Prevents opening and closes pending/open internal state.                    |
+| `openOnFocus`       | `true`  | Opens immediately when focus enters the trigger.                            |
+| `closeOnEscape`     | `true`  | Allows Escape to dismiss the disclosure.                                    |
+| `touchBehavior`     | `none`  | `toggle` opts into tap-to-toggle and prevents the activating click default. |
+| `interactionTarget` | —       | External element, selector or virtual reference that owns trigger events.   |
+| `contentTarget`     | —       | External element or selector that owns content events.                      |
+| `onOpenChange`      | —       | Receives the requested state and its interaction reason.                    |
+
+When `interactionTarget` or `contentTarget` is supplied, the composable attaches the corresponding
+listeners directly; do not also bind the matching props to that same element. An element reference
+is used directly. A virtual reference uses its `contextElement` for events. A virtual reference
+without `contextElement` cannot receive pointer or focus events, so control it with `open` or the
+imperative methods instead.
+
+The composable only owns disclosure interaction. Consumers remain responsible for content roles,
+labels and deciding whether the revealed information is appropriate for hover/focus. Interactive
+dialogs and focus-trapped content should use `Popover` or `Dialog` instead.