@astryx-vue/core 0.2.5 → 0.3.0

package/dist/useInteractiveRole-Cn0Nd5GX.js

@@ -0,0 +1,25 @@
+import { computed, toValue } from "vue";
+//#region src/composables/useInteractiveRole.ts
+/**
+* 对应原版 Astryx 的 `hooks/useInteractiveRole`。
+*
+* 把「这个多态组件到底渲染成什么」收在一处决定：有 `href` 就是链接，
+* 没 `href` 但有 `onClick` 就是按钮，都没有就是一段普通内容。
+* 时而是链接、时而按钮、时而是纯内容的组件都该走这里，判断先后顺序才不会各写一套。
+*
+* 只有 `link` 才真的渲染 `a`，这样键盘、中键新开标签这些行为都是浏览器给的。
+*
+* 上游还会读父级给的「触发上下文」（Popover、DropdownMenu 之类），
+* 让组件自动成为新浮层的合法触发器。我们的浮层不支持子元素当触发器，
+* 没有这份上下文可读，所以这里停在 `onClick` 这一层。
+*/
+function useInteractiveRole(options) {
+	return { role: computed(() => {
+		const href = toValue(options.href);
+		if (!toValue(options.isDisabled ?? false) && href != null && href !== "") return "link";
+		if (toValue(options.hasOnClick ?? false)) return "button";
+		return "inert";
+	}) };
+}
+//#endregion
+export { useInteractiveRole as t };

package/dist/{useMenuDrillIn-BgjJcY3K.js → useMenuDrillIn-DzKGkTho.js}

@@ -1,5 +1,5 @@
 import { t as _sfc_main$4 } from "./Icon-bteSId7T.js";
-import { t as _sfc_main$5 } from "./Item-DrYJL1TG.js";
+import { t as _sfc_main$5 } from "./Item-KhFKX9St.js";
 import { t as _sfc_main$6 } from "./CheckboxIndicator-D37cm2Rh.js";
 import { Fragment, computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, createSlots, createTextVNode, createVNode, defineComponent, inject, mergeModels, openBlock, provide, ref, renderSlot, toDisplayString, unref, useModel, useSlots, watch, withCtx } from "vue";
 import "../styles/dropdown-menu.css";

package/dist/{useMenuPress-DUmEy4TB.js → useMenuPress-D-FRNrBW.js}

@@ -2,6 +2,13 @@ import { onBeforeUnmount, toValue } from "vue";
 //#region src/composables/useLongPress.ts
 const DEFAULT_DELAY_MS = 500;
 const DEFAULT_MOVE_CANCEL_PX = 10;
+function touchPoint(event) {
+	const touch = event.touches?.[0] ?? event.changedTouches?.[0];
+	return touch == null ? null : {
+		x: touch.clientX,
+		y: touch.clientY
+	};
+}
 /**
 * 对应原版 Astryx 的 `hooks/useLongPress`。
 *
@@ -10,13 +17,19 @@ const DEFAULT_MOVE_CANCEL_PX = 10;
 * iOS Safari never synthesizes a `contextmenu` event for a held finger, so a
 * long press is the only touch affordance that can open a cursor-positioned
 * surface. The press is cancelled when the finger travels past the tolerance,
-* lifts, or the touch is cancelled.
+* lifts, a second finger lands, or the touch is cancelled.
+*
+* 两种绑法：自己接指针事件时用 `start` / `moveTo` / `cancel`；直接要触摸监听时
+* 把 `handlers` 摊到元素上。
 */
 function useLongPress(options) {
 	const delayMs = options.delayMs ?? DEFAULT_DELAY_MS;
 	const moveCancelPx = options.moveCancelPx ?? DEFAULT_MOVE_CANCEL_PX;
 	let timer = null;
 	let origin = null;
+	function isDisabled() {
+		return toValue(options.isDisabled) === true || toValue(options.disabled) === true;
+	}
 	function cancel() {
 		if (timer != null) {
 			clearTimeout(timer);
@@ -25,7 +38,7 @@ function useLongPress(options) {
 		origin = null;
 	}
 	function start(point) {
-		if (toValue(options.isDisabled)) return;
+		if (isDisabled()) return;
 		cancel();
 		origin = {
 			x: point.x,
@@ -49,9 +62,37 @@ function useLongPress(options) {
 		}
 		return true;
 	}
+	/**
+	* A press needs exactly one finger. A second one cancels it, the way a
+	* lift does.
+	*/
+	function onTouchStart(event) {
+		if ((event.touches?.length ?? 0) !== 1) {
+			cancel();
+			return;
+		}
+		const point = touchPoint(event);
+		if (point != null) start(point);
+	}
+	function onTouchMove(event) {
+		const point = touchPoint(event);
+		if (point != null) moveTo(point);
+	}
+	function onTouchEnd() {
+		cancel();
+	}
+	function onTouchCancel() {
+		cancel();
+	}
 	onBeforeUnmount(cancel);
 	return {
 		cancel,
+		handlers: {
+			onTouchCancel,
+			onTouchEnd,
+			onTouchMove,
+			onTouchStart
+		},
 		moveTo,
 		start
 	};
@@ -276,6 +317,8 @@ function useMenuNav(options) {
 //#region src/ContextMenu/useMenuPress.ts
 /** How long after a tracked release the browser's own click is still swallowed. */
 const STRAY_CLICK_MS = 400;
+/** How long a finger must rest on the trigger before the menu opens under it. */
+const DEFAULT_LONG_PRESS_MS = 500;
 let swallower = null;
 function disarmStrayClick() {
 	if (swallower == null) return;
@@ -334,23 +377,33 @@ function resetMenuPress() {
 * - A finger released outside leaves the menu open; a mouse released outside
 *   dismisses it.
 * - `pointercancel` and a second pointer end the gesture with nothing acting.
+*
+* 传了 `triggerRef` 和 `onTriggerPress` 之后，按压也可以从触发器开始：鼠标按下就开，
+* 手指按住到 `longPressDelayMs` 才开，开着的时候手指可以滑进菜单里挑行。
 */
 function useMenuPress(options) {
 	const { menuRef, isEnabled, onDismiss } = options;
 	let trackedId = null;
 	let trackedIsMouse = false;
+	let trackedFromTrigger = false;
+	let triggerOpened = false;
 	let highlighted = null;
 	let doc = null;
+	let longPressTimer = null;
+	let triggerPressAt = 0;
+	function rowsSelector() {
+		return options.itemSelector ?? MENU_ITEM_SELECTOR;
+	}
 	function isRowInsideMenu(row) {
 		const menu = menuRef.value;
 		return row instanceof HTMLElement && menu != null && menu.contains(row) && row.closest("[role=\"menu\"]") === menu;
 	}
 	function rowFromEvent(event) {
 		const hit = doc?.elementFromPoint?.(event.clientX, event.clientY) ?? null;
-		const fromPoint = hit instanceof Element ? hit.closest(MENU_ITEM_SELECTOR) : null;
+		const fromPoint = hit instanceof Element ? hit.closest(rowsSelector()) : null;
 		if (fromPoint != null && isRowInsideMenu(fromPoint)) return fromPoint;
 		const target = event.target;
-		const fromTarget = target instanceof Element ? target.closest(MENU_ITEM_SELECTOR) : null;
+		const fromTarget = target instanceof Element ? target.closest(rowsSelector()) : null;
 		return fromTarget != null && isRowInsideMenu(fromTarget) ? fromTarget : null;
 	}
 	function isEventInsideMenu(event) {
@@ -361,23 +414,67 @@ function useMenuPress(options) {
 		const target = event.target;
 		return target instanceof Node && menu.contains(target);
 	}
+	function isOverTrigger(event) {
+		const trigger = options.triggerRef?.value;
+		if (trigger == null) return false;
+		const hit = doc?.elementFromPoint?.(event.clientX, event.clientY) ?? null;
+		if (hit instanceof Node && trigger.contains(hit)) return true;
+		const target = event.target;
+		return target instanceof Node && trigger.contains(target);
+	}
 	function highlight(row) {
 		if (row === highlighted) return;
 		highlighted = row;
+		if (options.onHighlight != null) {
+			options.onHighlight(row);
+			return;
+		}
 		row?.focus({ preventScroll: true });
 	}
+	function activate(row, release) {
+		if (options.onActivate != null) {
+			options.onActivate(row, release);
+			return;
+		}
+		activateMenuItem(row, release);
+	}
+	function trackPointer(event, fromTrigger) {
+		const current = (options.menuRef.value ?? options.triggerRef?.value ?? null)?.ownerDocument ?? null;
+		if (current == null) return;
+		if (trackedId != null) endGesture();
+		doc = current;
+		trackedId = event.pointerId;
+		trackedIsMouse = event.pointerType === "mouse";
+		trackedFromTrigger = fromTrigger;
+		triggerOpened = false;
+		current.addEventListener("pointermove", onDocumentPointerMove, true);
+		current.addEventListener("pointerup", onDocumentPointerUp, true);
+		current.addEventListener("pointercancel", onDocumentPointerCancel, true);
+	}
 	function onDocumentPointerMove(event) {
 		if (event.pointerId !== trackedId) return;
+		if (trackedFromTrigger && !triggerOpened) return;
 		const row = rowFromEvent(event);
 		if (row != null) highlight(row);
 	}
 	function onDocumentPointerUp(event) {
 		if (event.pointerId !== trackedId) return;
 		const row = rowFromEvent(event);
+		const wasTrigger = trackedFromTrigger;
+		const wasMouse = trackedIsMouse;
+		const hadOpened = triggerOpened;
+		const overTrigger = wasTrigger && isOverTrigger(event);
+		const releasedOutside = !isEventInsideMenu(event);
 		endGesture();
-		if (row == null) return;
+		if (row == null) {
+			if (wasTrigger && hadOpened) {
+				triggerPressAt = Date.now();
+				if (wasMouse && !overTrigger && releasedOutside) onDismiss();
+			}
+			return;
+		}
 		if (doc != null) armStrayClick(doc);
-		activateMenuItem(row, event);
+		activate(row, event);
 	}
 	function onDocumentPointerCancel(event) {
 		if (event.pointerId !== trackedId) return;
@@ -388,7 +485,14 @@ function useMenuPress(options) {
 		endGesture();
 		if (!isInside) onDismiss();
 	}
+	function clearLongPress() {
+		if (longPressTimer != null) {
+			clearTimeout(longPressTimer);
+			longPressTimer = null;
+		}
+	}
 	function endGesture() {
+		clearLongPress();
 		const current = doc;
 		if (current != null) {
 			current.removeEventListener("pointermove", onDocumentPointerMove, true);
@@ -398,28 +502,72 @@ function useMenuPress(options) {
 		}
 		trackedId = null;
 		trackedIsMouse = false;
+		trackedFromTrigger = false;
+		triggerOpened = false;
 		highlighted = null;
 	}
 	function onPointerDown(event) {
 		if (!isEnabled()) return;
 		if (trackedId != null) endGesture();
 		const target = event.target;
-		const row = target instanceof Element ? target.closest(MENU_ITEM_SELECTOR) : null;
+		const row = target instanceof Element ? target.closest(rowsSelector()) : null;
 		if (row == null || !isRowInsideMenu(row)) return;
+		trackPointer(event, false);
 		highlighted = row;
-		trackedId = event.pointerId;
-		trackedIsMouse = event.pointerType === "mouse";
-		doc = menuRef.value?.ownerDocument ?? null;
 		if (trackedIsMouse) {
+			doc?.removeEventListener("pointermove", onDocumentPointerMove, true);
+			doc?.removeEventListener("pointerup", onDocumentPointerUp, true);
+			doc?.removeEventListener("pointercancel", onDocumentPointerCancel, true);
 			doc?.addEventListener("mouseup", onDocumentMouseUp, true);
+		}
+	}
+	function onTriggerPointerDown(event) {
+		const press = options.onTriggerPress;
+		if (press == null || !isEnabled()) return;
+		if ((event.button ?? 0) !== 0) return;
+		trackPointer(event, true);
+		if (trackedIsMouse) {
+			triggerOpened = press("mouse") === true;
+			triggerPressAt = Date.now();
+			if (!triggerOpened) endGesture();
 			return;
 		}
-		doc?.addEventListener("pointermove", onDocumentPointerMove, true);
-		doc?.addEventListener("pointerup", onDocumentPointerUp, true);
-		doc?.addEventListener("pointercancel", onDocumentPointerCancel, true);
+		const pointerType = event.pointerType === "pen" ? "pen" : "touch";
+		longPressTimer = setTimeout(() => {
+			longPressTimer = null;
+			triggerOpened = press(pointerType) === true;
+			triggerPressAt = Date.now();
+		}, options.longPressDelayMs ?? DEFAULT_LONG_PRESS_MS);
+	}
+	/**
+	* Only the browser's own menu for a held finger is suppressed; a mouse's
+	* right-click keeps its `contextmenu` route through the application.
+	*/
+	function onTriggerContextMenu(event) {
+		if (options.onTriggerPress == null) return;
+		if ((event instanceof PointerEvent ? event.pointerType : null) === "mouse") return;
+		event.preventDefault();
+	}
+	function isTriggerClickFromPress() {
+		return triggerPressAt !== 0 && Date.now() - triggerPressAt < STRAY_CLICK_MS;
+	}
+	function cancel() {
+		endGesture();
 	}
 	onBeforeUnmount(endGesture);
-	return { onPointerDown };
+	return {
+		cancel,
+		isTriggerClickFromPress,
+		menuProps: {
+			"data-astryx-menu-press": "",
+			onPointerDown
+		},
+		onPointerDown,
+		triggerProps: {
+			onContextMenu: onTriggerContextMenu,
+			onPointerDown: onTriggerPointerDown
+		}
+	};
 }
 //#endregion
 export { useLongPress as a, useMenuNav as i, useMenuPress as n, isModifiedClick as r, resetMenuPress as t };

package/dist/useMergedRefs-CfHHlCsn.js

@@ -0,0 +1,109 @@
+import { n as useDismiss, t as usePositionedLayer } from "./usePositionedLayer-Cru9_00b.js";
+import { computed, shallowRef, toValue, useId } from "vue";
+//#region src/composables/useLayer.ts
+/**
+* 对应原版 Astryx 的 `hooks/useLayer`：渲染浮层的最小内核。
+* 负责开合状态、锚点定位（或固定坐标）、点击外部关闭和延迟渲染。
+* `Popover`、`Tooltip`、`HoverCard` 都在它之上构建。
+*
+* 内容用 `Teleport` 送到 `body`，样式取自 `contentStyle`：
+*
+* ```vue
+* <button :ref="layer.anchorRef" @click="layer.show()">打开</button>
+* <Teleport to="body">
+*   <div v-if="layer.isMounted" v-show="layer.isOpen" :ref="layer.contentRef" :style="layer.contentStyle">
+*     ...
+*   </div>
+* </Teleport>
+* ```
+*/
+function useLayer(options) {
+	const isFixed = options.mode === "fixed";
+	const isOpen = shallowRef(options.isDefaultOpen === true);
+	const hasOpened = shallowRef(options.isDefaultOpen === true);
+	const internalAnchor = shallowRef(null);
+	const anchorRef = options.anchor ?? internalAnchor;
+	const contentRef = shallowRef(null);
+	const uid = useId();
+	const id = `astryx-layer-${uid}`;
+	const anchorId = `astryx-layer-anchor-${uid}`;
+	const placement = computed(() => toValue(options.placement) ?? "below");
+	const alignment = computed(() => toValue(options.alignment) ?? "center");
+	const positioned = isFixed ? null : usePositionedLayer({
+		anchor: anchorRef,
+		layer: contentRef,
+		isOpen,
+		placement,
+		alignment,
+		gap: options.gap ?? 4
+	});
+	const resolvedPlacement = computed(() => positioned?.position.value.placement ?? placement.value);
+	const contentStyle = computed(() => {
+		if (isFixed) return {
+			position: "fixed",
+			top: `${toValue(options.y) ?? 0}px`,
+			left: `${toValue(options.x) ?? 0}px`
+		};
+		const { top, left } = positioned?.position.value ?? {
+			top: 0,
+			left: 0
+		};
+		return {
+			top: `${top}px`,
+			left: `${left}px`
+		};
+	});
+	const isMounted = computed(() => !toValue(options.lazyMount) || hasOpened.value);
+	function show() {
+		if (isOpen.value) return;
+		hasOpened.value = true;
+		isOpen.value = true;
+		options.onShow?.();
+	}
+	function hide() {
+		if (!isOpen.value) return;
+		isOpen.value = false;
+		options.onHide?.();
+	}
+	useDismiss({
+		container: contentRef,
+		trigger: anchorRef,
+		isEnabled: computed(() => isOpen.value && toValue(options.lightDismiss) === true),
+		onDismiss: hide
+	});
+	return {
+		isOpen,
+		anchorRef,
+		contentRef,
+		contentStyle,
+		resolvedPlacement,
+		isMounted,
+		id,
+		anchorId,
+		show,
+		hide
+	};
+}
+//#endregion
+//#region src/composables/useMergedRefs.ts
+/**
+* 对应原版 Astryx 的 `hooks/useMergedRefs`。
+*
+* 把多个 `Ref` 和函数 ref 合成一个函数 ref，交给模板的 `:ref`。
+* 组件既要往外转发使用者给的 ref，又要自己留一份内部 ref 时用得上。
+*
+* 返回的函数在组合式函数的生命周期里只有一份。直接在模板里写
+* `:ref="value => { ... }"` 每次渲染都会造一个新函数，Vue 会先解绑再重新绑定，
+* 白白多做一轮解绑和挂载。
+*/
+function useMergedRefs(refs) {
+	return function mergedRef(value) {
+		for (const target of refs) {
+			if (target == null) continue;
+			if (typeof target === "function") target(value);
+			else target.value = value;
+		}
+	};
+}
+//#endregion
+export { useLayer as n, useMergedRefs as t };

package/dist/useNumberField-4-dIGVed.js

@@ -0,0 +1,128 @@
+import { computed, toValue, watch } from "vue";
+//#region src/composables/useNumberField.ts
+/** 小数位数。指数写法按尾数算，避免 1e-7 被当成 0 位。 */
+function decimalPlaces(value) {
+	const [coefficient, exponentText] = String(value).toLowerCase().split("e");
+	const fractionLength = coefficient.split(".")[1]?.length ?? 0;
+	const exponent = exponentText == null ? 0 : Number(exponentText);
+	return Math.max(0, fractionLength - exponent);
+}
+/**
+* 整数模式下非整数步长退回 1：按 0.5 走一步会落在 2.5，而字段只收整数。
+*/
+function effectiveStep(step, integerOnly) {
+	if (step == null || !Number.isFinite(step) || step <= 0) return 1;
+	if (integerOnly && !Number.isInteger(step)) return 1;
+	return step;
+}
+/**
+* 按步长网格走一格：以 min 为起点对齐，先取整再夹到范围内。
+*/
+function steppedValue(options) {
+	const { currentValue, direction, min, max, step, integerOnly } = options;
+	const stride = effectiveStep(step, integerOnly);
+	const stepBase = min != null && (!integerOnly || Number.isInteger(min)) ? min : 0;
+	let nextValue;
+	if (currentValue == null) {
+		nextValue = direction === 1 ? min ?? 0 : max ?? 0;
+		if (integerOnly) nextValue = direction === 1 ? Math.ceil(nextValue) : Math.floor(nextValue);
+	} else {
+		const stepPosition = (currentValue - stepBase) / stride;
+		const tolerance = Number.EPSILON * Math.max(1, Math.abs(stepPosition)) * 4;
+		nextValue = stepBase + (direction === 1 ? Math.floor(stepPosition + tolerance) + 1 : Math.ceil(stepPosition - tolerance) - 1) * stride;
+	}
+	const precision = Math.min(12, Math.max(decimalPlaces(stride), decimalPlaces(stepBase)));
+	nextValue = Number(nextValue.toFixed(precision));
+	if (min != null) nextValue = Math.max(min, nextValue);
+	if (max != null) nextValue = Math.min(max, nextValue);
+	if (!Number.isFinite(nextValue)) return currentValue;
+	if (integerOnly && !Number.isInteger(nextValue)) return currentValue;
+	return Object.is(nextValue, -0) ? 0 : nextValue;
+}
+/**
+* 数字输入框逻辑：步进、范围限制、整数限制、键盘增减。
+*/
+function useNumberField(options) {
+	const { value, onChange } = options;
+	const readMin = () => toValue(options.min) ?? null;
+	const readMax = () => toValue(options.max) ?? null;
+	const readStep = () => toValue(options.step);
+	const readDisabled = () => Boolean(toValue(options.disabled));
+	const readReadOnly = () => Boolean(toValue(options.readOnly));
+	const readIntegerOnly = () => Boolean(toValue(options.integerOnly));
+	const locked = () => readDisabled() || readReadOnly();
+	function nextValue(direction) {
+		return steppedValue({
+			currentValue: value.value,
+			direction,
+			min: readMin(),
+			max: readMax(),
+			step: readStep(),
+			integerOnly: readIntegerOnly()
+		});
+	}
+	const canIncrement = computed(() => nextValue(1) !== value.value);
+	const canDecrement = computed(() => nextValue(-1) !== value.value);
+	function step(direction) {
+		if (locked()) return false;
+		const next = nextValue(direction);
+		if (next == null || next === value.value) return false;
+		onChange(next);
+		return true;
+	}
+	function increment() {
+		step(1);
+	}
+	function decrement() {
+		step(-1);
+	}
+	function clamp(val, integerOnly) {
+		const rawMin = readMin();
+		const rawMax = readMax();
+		const min = rawMin == null ? null : integerOnly ? Math.ceil(rawMin) : rawMin;
+		const max = rawMax == null ? null : integerOnly ? Math.floor(rawMax) : rawMax;
+		let clamped = val;
+		if (min != null) clamped = Math.max(min, clamped);
+		if (max != null) clamped = Math.min(max, clamped);
+		return clamped;
+	}
+	function setValue(val) {
+		if (readDisabled()) return;
+		if (val === null) {
+			onChange(null);
+			return;
+		}
+		const integerOnly = readIntegerOnly();
+		const bounded = clamp(val, integerOnly);
+		if (integerOnly && !Number.isInteger(bounded)) return;
+		onChange(Object.is(bounded, -0) ? 0 : bounded);
+	}
+	function onKeyDown(event) {
+		if (locked()) return;
+		switch (event.key) {
+			case "ArrowUp":
+				event.preventDefault();
+				increment();
+				break;
+			case "ArrowDown":
+				event.preventDefault();
+				decrement();
+		}
+	}
+	watch(value, (val) => {
+		if (val == null) return;
+		const bounded = clamp(val, readIntegerOnly());
+		if (bounded !== val) onChange(Object.is(bounded, -0) ? 0 : bounded);
+	});
+	return {
+		canDecrement,
+		canIncrement,
+		decrement,
+		increment,
+		onKeyDown,
+		setValue,
+		step
+	};
+}
+//#endregion
+export { useNumberField as t };

package/dist/{usePositionedLayer-C1NBOsVT.js → usePositionedLayer-Cru9_00b.js}

@@ -1,6 +1,66 @@
-import { nextTick, ref, watch } from "vue";
+import { i as useLayerGutter, s as resolveLayerGutter } from "./context-M-er0-Rk.js";
+import { nextTick, onScopeDispose, ref, watch } from "vue";
+//#region src/composables/useDismiss.ts
+const escapeStack = [];
+/**
+* 统一处理浮层组件的关闭逻辑：点击外部和按 Escape 键。
+* 用于 Popover、Tooltip、DropdownMenu、ContextMenu 等。
+*
+* 设计决策：
+* - 使用 pointerdown 事件（包含 mouse 和 touch）
+* - 在 nextTick 后附加监听器，避免打开时的点击立即触发关闭
+* - Escape 键使用全局栈，确保最内层的浮层优先处理
+*/
+function useDismiss(options) {
+	const { container, trigger, isEnabled, enableEscape = { value: true }, onDismiss } = options;
+	let isAttached = false;
+	function dismissFromEscape() {
+		if (options.onEscape != null) options.onEscape();
+		else onDismiss();
+	}
+	function onClickOutside(event) {
+		if (!isEnabled.value) return;
+		const el = container.value;
+		if (!el) return;
+		const target = event.target;
+		if (el.contains(target)) return;
+		if ((trigger?.value)?.contains(target)) return;
+		onDismiss();
+	}
+	function onEscapeKey(event) {
+		if (!isEnabled.value || !enableEscape.value) return;
+		if (event.key === "Escape") {
+			if (escapeStack[escapeStack.length - 1] === dismissFromEscape) {
+				event.preventDefault();
+				dismissFromEscape();
+			}
+		}
+	}
+	async function setup() {
+		if (typeof document === "undefined" || isAttached) return;
+		await nextTick();
+		if (!isEnabled.value) return;
+		isAttached = true;
+		document.addEventListener("pointerdown", onClickOutside, true);
+		document.addEventListener("keydown", onEscapeKey, true);
+		if (enableEscape.value) escapeStack.push(dismissFromEscape);
+	}
+	function teardown() {
+		if (typeof document === "undefined" || !isAttached) return;
+		isAttached = false;
+		document.removeEventListener("pointerdown", onClickOutside, true);
+		document.removeEventListener("keydown", onEscapeKey, true);
+		const index = escapeStack.indexOf(dismissFromEscape);
+		if (index !== -1) escapeStack.splice(index, 1);
+	}
+	watch(isEnabled, (enabled) => {
+		if (enabled) setup();
+		else teardown();
+	}, { immediate: true });
+	onScopeDispose(teardown);
+}
+//#endregion
 //#region src/layer/position.ts
-const VIEWPORT_MARGIN = 8;
 function alignOnAxis(start, size, own, alignment) {
 	if (alignment === "start") return start;
 	if (alignment === "end") return start + size - own;
@@ -11,8 +71,9 @@ function clamp(value, min, max) {
 }
 /**
 * 计算浮层相对锚点的位置。空间不足时翻转到相反方向，最终位置保持在视口内。
+* `gutter` 是浮层离视口每条边的最小空隙，不传就按基础空隙加设备安全区算。
 */
-function computeLayerPosition(anchor, layer, viewport, placement, alignment, gap) {
+function computeLayerPosition(anchor, layer, viewport, placement, alignment, gap, gutter = resolveLayerGutter()) {
 	let resolved = placement;
 	if (resolved === "above" && anchor.top - gap - layer.height < 0) resolved = "below";
 	else if (resolved === "below" && anchor.bottom + gap + layer.height > viewport.height) resolved = "above";
@@ -33,8 +94,8 @@ function computeLayerPosition(anchor, layer, viewport, placement, alignment, gap
 		placement: resolved
 	};
 	return {
-		top: clamp(top, VIEWPORT_MARGIN, viewport.height - layer.height - VIEWPORT_MARGIN),
-		left: clamp(left, VIEWPORT_MARGIN, viewport.width - layer.width - VIEWPORT_MARGIN),
+		top: clamp(top, gutter.blockStart, viewport.height - layer.height - gutter.blockEnd),
+		left: clamp(left, gutter.inlineStart, viewport.width - layer.width - gutter.inlineEnd),
 		placement: resolved
 	};
 }
@@ -51,6 +112,7 @@ function usePositionedLayer(options) {
 		left: 0,
 		placement: placement.value
 	});
+	const gutter = useLayerGutter();
 	function update() {
 		const anchorEl = anchor.value;
 		const layerEl = layer.value;
@@ -61,7 +123,7 @@ function usePositionedLayer(options) {
 		}, {
 			width: window.innerWidth,
 			height: window.innerHeight
-		}, placement.value, alignment.value, gap);
+		}, placement.value, alignment.value, gap, gutter.value);
 	}
 	let pollId;
 	function geometryKey() {
@@ -104,6 +166,7 @@ function usePositionedLayer(options) {
 		} else detach();
 	});
 	watch([placement, alignment], update);
+	watch(gutter, update);
 	return {
 		position,
 		update,
@@ -111,4 +174,4 @@ function usePositionedLayer(options) {
 	};
 }
 //#endregion
-export { usePositionedLayer as t };
+export { useDismiss as n, usePositionedLayer as t };