@zerodep-dev/vue-tsx-pro-ui 0.0.0-stage → 0.1.0

package/dist/utils/dom/floating.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 锚定浮层：Popover、Tooltip、Menu、Select 的弹出层贴着触发器显示。位置由 floating-ui 计算，
+ * 显示、隐藏、Esc、点击外部仍交给原生 popover；createAnchoredLayer 把两者串成打开、关闭的流程。
+ *
+ *   const anchored = anchorFloating(trigger, panel, { placement: 'bottom-start' });
+ *   await anchored.ready;   // 第一次定位完成、已经可见：这时才能把焦点移进去
+ *   anchored.stop();        // 关闭时停止跟随
+ *   sx: [floatingStyles.anchored, …]   // 浮层自己的样式：去掉原生 popover 默认的居中与外边距
+ *
+ * - 第一次算好位置之前浮层是 visibility: hidden，不会在默认位置闪一下；
+ * - 空间不够时翻到另一侧（flip）、贴着视口边缘挪回来（shift），滚动、缩放、锚点变化时自动重新定位（autoUpdate）；
+ * - start / end 对齐是逻辑方向，从右到左排版下自动镜像（floating-ui 读浮层的 direction）；
+ * - 最终方向写到 data-side / data-align，缩放原点（transform-origin）朝向锚点，进出场的 scale 过渡从锚点那侧展开。
+ */
+import { type Placement, type VirtualElement } from '@floating-ui/dom';
+import * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';
+import type { SxStyles } from '@zerodep-dev/vue-tsx-pro-tsx/styles';
+import { type TextSize } from '../style/typography';
+/** 弹出位置：主方向 + 对齐方式（start 对齐锚点的起始边，end 对齐结束边）；空间不够时自动翻转 */
+export interface FloatingPlacements {
+    /** 上方居中 */
+    top: unknown;
+    /** 上方，与锚点起始边对齐 */
+    'top-start': unknown;
+    /** 上方，与锚点结束边对齐 */
+    'top-end': unknown;
+    /** 下方居中 */
+    bottom: unknown;
+    /** 下方，与锚点起始边对齐 */
+    'bottom-start': unknown;
+    /** 下方，与锚点结束边对齐 */
+    'bottom-end': unknown;
+    /** 左侧居中 */
+    left: unknown;
+    /** 左侧，与锚点顶边对齐 */
+    'left-start': unknown;
+    /** 左侧，与锚点底边对齐 */
+    'left-end': unknown;
+    /** 右侧居中 */
+    right: unknown;
+    /** 右侧，与锚点顶边对齐 */
+    'right-start': unknown;
+    /** 右侧，与锚点底边对齐 */
+    'right-end': unknown;
+}
+/** 弹出位置 */
+export type FloatingPlacement = keyof FloatingPlacements & Placement;
+/**
+ * 锚点：元素，或只有位置的虚拟锚点（右键菜单从指针的位置弹出：`pointAnchor(x, y)`）。
+ * 虚拟锚点没有元素可以还焦点，关闭后焦点由组件自己安排
+ */
+export type FloatingAnchor = HTMLElement | VirtualElement;
+/** 视口里一个点（clientX / clientY）做锚点 */
+export declare function pointAnchor(x: number, y: number): VirtualElement;
+/** anchorFloating 的选项 */
+export interface FloatingOptions {
+    /** 弹出位置，默认 bottom-start */
+    placement?: FloatingPlacement;
+    /** 与锚点的距离（px），默认 6 */
+    offset?: number;
+    /** 至少与锚点一样宽：下拉框、组合框的选项列表 */
+    matchWidth?: boolean;
+    /** 最大高度限制在视口剩余空间内（浮层自己设 overflow 滚动）：菜单、选项列表 */
+    fitHeight?: boolean;
+    /** 箭头元素（浮层里的子元素，样式用 floatingStyles.arrow）：指向锚点，随翻转换边；距离自动加上箭头露出的一半 */
+    arrow?: HTMLElement | null;
+    /** 主方向与对侧都放不下时，再试垂直的两侧（窄屏上“右侧”的大卡片改到上下）：引导卡片 */
+    crossAxisFallback?: boolean;
+}
+/** anchorFloating 的返回值 */
+export interface Anchored {
+    /** 第一次定位完成、浮层已可见时完成；在这之前就 stop 时不会完成 */
+    readonly ready: Promise<void>;
+    /** 停止跟随锚点；关闭浮层时调用，重复调用无副作用 */
+    stop(): void;
+}
+/**
+ * 弹出面板（选项列表、树、日期面板）共用的样式：锚定定位、浮起的表面、缩放进出场；
+ * 面板渲染在顶层，不是输入框外壳的后代、不继承它的字号：按控件的 size 设置。ListPopover、TreeSelect、日期选择器用它
+ */
+export declare function anchoredPanelSx(size?: TextSize): SxStyles;
+/** 锚定浮层的基础样式：定位与表面 */
+export declare const floatingStyles: Readonly<{
+    anchored: css.CompiledStyles;
+    arrow: css.CompiledStyles;
+    scrollArea: css.CompiledStyles;
+    scrollPanel: css.CompiledStyles;
+    surface: css.CompiledStyles;
+    withArrow: css.CompiledStyles;
+}>;
+/** 把 floating 定位到 anchor 旁边并持续跟随；floating 需要已经显示（如 showPopover 之后） */
+export declare function anchorFloating(anchor: FloatingAnchor, floating: HTMLElement, { placement, offset: distance, matchWidth, fitHeight, arrow, crossAxisFallback, }?: FloatingOptions): Anchored;
+/** 关闭浮层时焦点还给谁：true 锚点，元素，或 false 不还 */
+export type RestoreFocus = boolean | HTMLElement | null;
+/** createAnchoredLayer 的返回值：一个原生 popover 浮层的打开与关闭 */
+export interface AnchoredLayer {
+    /** 是否显示着（show 之后、hide 之前） */
+    readonly visible: boolean;
+    /** 显示 panel（showPopover）并贴着 anchor 定位；返回第一次定位完成、可以移入焦点的 Promise。已显示时不重复 */
+    show(anchor: FloatingAnchor, panel: HTMLElement, options?: FloatingOptions): Promise<void>;
+    /**
+     * 停止定位并隐藏；焦点还在浮层里或已丢失时归还：restoreFocus 默认 true 还给锚点，给元素时还给它，false 不还。
+     * 未显示时什么也不做
+     */
+    hide(options?: {
+        restoreFocus?: RestoreFocus;
+    }): void;
+}
+/**
+ * 锚定浮层的生命周期（Popover、Menu、Tooltip 共用）：显示 → 定位 → 关闭时停止定位、归还焦点。
+ * 原生 popover="auto" 被 Esc、点击外部关闭（light dismiss）时浏览器先隐藏了它，组件在 toggle 事件里调用 hide 收尾。
+ */
+export declare function createAnchoredLayer(): AnchoredLayer;
+/** useAnchoredPopover 每次渲染后读取的状态 */
+export interface AnchoredPopoverState {
+    /** 是否打开 */
+    open: boolean;
+    /** 锚点（触发器、输入框外壳，或右键菜单的虚拟锚点） */
+    anchor: FloatingAnchor | null;
+    /** 浮层（popover 元素） */
+    panel: HTMLElement | null;
+    /** 定位选项 */
+    floating?: FloatingOptions;
+    /**
+     * 关闭时焦点还给谁：默认 true 还给锚点；锚点是输入框外壳时给打开按钮（DatePicker）；
+     * 焦点一直在锚点上的组件（Select、Combobox）设 false
+     */
+    restoreFocus?: RestoreFocus;
+}
+/** useAnchoredPopover 的回调 */
+export interface AnchoredPopoverEvents {
+    /** 浏览器关掉了浮层：按了 Esc，或点了外面（别的浮层打开也算）；组件把 open 写回 false */
+    close: (reason: 'escape' | 'outside', event: Event) => void;
+    /** 浮层打开并第一次定位完成（可见）：移入焦点等 */
+    shown?: (panel: HTMLElement) => void;
+}
+/**
+ * 原生 popover="auto" 的锚定浮层接到组件的 open 上（Popover、Menu、Select、Combobox 共用）：
+ * open 变化时显示或隐藏（DOM 更新之后），浏览器的 light dismiss 写回 open，卸载时收起。
+ * 返回要放到浮层元素上的 onToggle。在组件 setup 里调用。
+ *
+ *   const { onToggle } = useAnchoredPopover(
+ *     () => ({ open, anchor, panel, floating: { placement } }),
+ *     { close: (reason, event) => setOpen(false, reason, event), shown: focusFirst },
+ *   );
+ */
+export declare function useAnchoredPopover(read: () => AnchoredPopoverState, events: AnchoredPopoverEvents): {
+    onToggle: (event: Event) => void;
+};

package/dist/utils/dom/floating.js

@@ -0,0 +1,262 @@
+import { fontSizeStyles } from "../style/typography.js";
+import { transitions } from "../style/transitions.js";
+import { returnFocus } from "./focus.js";
+import { onScopeDispose, watchPostEffect } from "vue";
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+import { arrow, autoUpdate, computePosition, flip, offset, shift, size } from "@floating-ui/dom";
+//#region src/utils/dom/floating.ts
+/**
+* 锚定浮层：Popover、Tooltip、Menu、Select 的弹出层贴着触发器显示。位置由 floating-ui 计算，
+* 显示、隐藏、Esc、点击外部仍交给原生 popover；createAnchoredLayer 把两者串成打开、关闭的流程。
+*
+*   const anchored = anchorFloating(trigger, panel, { placement: 'bottom-start' });
+*   await anchored.ready;   // 第一次定位完成、已经可见：这时才能把焦点移进去
+*   anchored.stop();        // 关闭时停止跟随
+*   sx: [floatingStyles.anchored, …]   // 浮层自己的样式：去掉原生 popover 默认的居中与外边距
+*
+* - 第一次算好位置之前浮层是 visibility: hidden，不会在默认位置闪一下；
+* - 空间不够时翻到另一侧（flip）、贴着视口边缘挪回来（shift），滚动、缩放、锚点变化时自动重新定位（autoUpdate）；
+* - start / end 对齐是逻辑方向，从右到左排版下自动镜像（floating-ui 读浮层的 direction）；
+* - 最终方向写到 data-side / data-align，缩放原点（transform-origin）朝向锚点，进出场的 scale 过渡从锚点那侧展开。
+*/
+/** 视口里一个点（clientX / clientY）做锚点 */
+function pointAnchor(x, y) {
+	return { getBoundingClientRect: () => new DOMRect(x, y, 0, 0) };
+}
+/** 缩放原点朝向锚点：弹出在下方时从上边缘展开 */
+var TRANSFORM_ORIGIN = {
+	top: "bottom",
+	right: "left",
+	bottom: "top",
+	left: "right"
+};
+/** 箭头贴着浮层的哪条边（与弹出方向相反） */
+var ARROW_EDGE = {
+	top: "bottom",
+	right: "left",
+	bottom: "top",
+	left: "right"
+};
+/** 箭头（画了右、下两条边的方块）转多少度才朝向锚点 */
+var ARROW_ROTATION = {
+	top: 45,
+	right: 135,
+	bottom: 225,
+	left: -45
+};
+/**
+* 弹出面板（选项列表、树、日期面板）共用的样式：锚定定位、浮起的表面、缩放进出场；
+* 面板渲染在顶层，不是输入框外壳的后代、不继承它的字号：按控件的 size 设置。ListPopover、TreeSelect、日期选择器用它
+*/
+function anchoredPanelSx(size) {
+	return [
+		floatingStyles.anchored,
+		floatingStyles.surface,
+		size && fontSizeStyles[size],
+		transitions.scale
+	];
+}
+/** 锚定浮层的基础样式：定位与表面 */
+var floatingStyles = css.create({
+	/** 原生 popover 默认居中显示、带外边距，改为由 anchorFloating 写入的 left / top 定位 */
+	anchored: {
+		position: "fixed",
+		inset: "auto",
+		margin: 0
+	},
+	/** 浮起的表面：边框、圆角、阴影（Popover、Menu、选项列表）；内边距各自定 */
+	surface: {
+		boxSizing: "border-box",
+		borderWidth: "_xs",
+		borderStyle: "solid",
+		borderColor: "_border",
+		borderRadius: "_lg",
+		backgroundColor: "_surfaceRaised",
+		color: "_text",
+		boxShadow: "_lg"
+	},
+	/**
+	* 箭头：一个小方块，只画右、下两条边，旋转后尖角朝向锚点；底色、边框跟随浮层（inherit）。
+	* 位置与旋转由 anchorFloating 写
+	*/
+	arrow: {
+		position: "absolute",
+		boxSizing: "border-box",
+		width: "0.625em",
+		height: "0.625em",
+		backgroundColor: "inherit",
+		borderStyle: "solid",
+		borderColor: "inherit",
+		borderWidth: 0,
+		borderRightWidth: "inherit",
+		borderBottomWidth: "inherit",
+		borderBottomRightRadius: "_borderWidths.sm",
+		pointerEvents: "none"
+	},
+	/** 有箭头的浮层：原生 popover 默认 overflow: auto 会把伸出去的箭头裁掉 */
+	withArrow: { overflow: "visible" },
+	/**
+	* 内容会滚动的浮层（选项列表、菜单）：打开时是竖向 flex、裁掉溢出，里面放 ScrollArea（scrollArea）撑满，
+	* 滚动条是浮层的；关闭时仍由浏览器隐藏（只在 :popover-open 时改 display）
+	*/
+	scrollPanel: {
+		display: {
+			default: null,
+			":popover-open": "flex"
+		},
+		flexDirection: "column",
+		overflow: "hidden",
+		padding: 0
+	},
+	/** scrollPanel 里的 ScrollArea：占满剩下的高度（最大高度由 anchorFloating 的 fitHeight 写在浮层上） */
+	scrollArea: {
+		flexGrow: 1,
+		minHeight: 0
+	}
+});
+/** 与视口边缘至少留出的距离（px） */
+var VIEWPORT_PADDING = 8;
+/** 把 floating 定位到 anchor 旁边并持续跟随；floating 需要已经显示（如 showPopover 之后） */
+function anchorFloating(anchor, floating, { placement = "bottom-start", offset: distance = 6, matchWidth, fitHeight, arrow: arrow$1, crossAxisFallback } = {}) {
+	const arrowSize = arrow$1?.offsetWidth ?? 0;
+	const middleware = [
+		offset(distance + arrowSize * .7),
+		flip({
+			padding: VIEWPORT_PADDING,
+			fallbackAxisSideDirection: crossAxisFallback ? "end" : "none"
+		}),
+		shift({ padding: VIEWPORT_PADDING })
+	];
+	if (arrow$1) middleware.push(arrow({
+		element: arrow$1,
+		padding: arrowSize
+	}));
+	if (matchWidth || fitHeight) middleware.push(size({
+		padding: VIEWPORT_PADDING,
+		apply({ rects, availableHeight, elements }) {
+			if (matchWidth) elements.floating.style.minWidth = `${rects.reference.width}px`;
+			if (fitHeight) elements.floating.style.maxHeight = `${Math.max(0, availableHeight)}px`;
+		}
+	}));
+	let stopped = false;
+	let resolveReady;
+	const ready = new Promise((resolve) => resolveReady = resolve);
+	floating.style.visibility = "hidden";
+	const update = () => void computePosition(anchor, floating, {
+		placement,
+		strategy: "fixed",
+		middleware
+	}).then(({ x, y, placement: final, middlewareData }) => {
+		if (stopped) return;
+		const [side, align = "center"] = final.split("-");
+		if (arrow$1 && middlewareData.arrow) {
+			const { x: arrowX, y: arrowY } = middlewareData.arrow;
+			Object.assign(arrow$1.style, {
+				left: arrowX != null ? `${arrowX}px` : "",
+				top: arrowY != null ? `${arrowY}px` : "",
+				right: "",
+				bottom: "",
+				[ARROW_EDGE[side]]: `${-arrowSize / 2}px`,
+				transform: `rotate(${ARROW_ROTATION[side]}deg)`
+			});
+		}
+		Object.assign(floating.style, {
+			left: `${x}px`,
+			top: `${y}px`,
+			visibility: "",
+			transformOrigin: TRANSFORM_ORIGIN[side]
+		});
+		floating.dataset.side = side;
+		floating.dataset.align = align;
+		resolveReady();
+	});
+	const cleanup = autoUpdate(anchor, floating, update);
+	return {
+		ready,
+		stop() {
+			if (stopped) return;
+			stopped = true;
+			cleanup();
+		}
+	};
+}
+/**
+* 锚定浮层的生命周期（Popover、Menu、Tooltip 共用）：显示 → 定位 → 关闭时停止定位、归还焦点。
+* 原生 popover="auto" 被 Esc、点击外部关闭（light dismiss）时浏览器先隐藏了它，组件在 toggle 事件里调用 hide 收尾。
+*/
+function createAnchoredLayer() {
+	let current;
+	let ready = Promise.resolve();
+	return {
+		get visible() {
+			return current != null;
+		},
+		show(anchor, panel, options) {
+			if (current) return ready;
+			if (!panel.matches(":popover-open")) panel.showPopover();
+			const anchored = anchorFloating(anchor, panel, options);
+			current = {
+				anchor,
+				panel,
+				anchored
+			};
+			ready = anchored.ready;
+			return ready;
+		},
+		hide({ restoreFocus = true } = {}) {
+			if (!current) return;
+			const { anchor, panel, anchored } = current;
+			current = void 0;
+			anchored.stop();
+			if (panel.matches(":popover-open")) panel.hidePopover();
+			const target = restoreFocus === true ? anchor : restoreFocus;
+			if (target instanceof HTMLElement) returnFocus(panel, target);
+		}
+	};
+}
+/**
+* 原生 popover="auto" 的锚定浮层接到组件的 open 上（Popover、Menu、Select、Combobox 共用）：
+* open 变化时显示或隐藏（DOM 更新之后），浏览器的 light dismiss 写回 open，卸载时收起。
+* 返回要放到浮层元素上的 onToggle。在组件 setup 里调用。
+*
+*   const { onToggle } = useAnchoredPopover(
+*     () => ({ open, anchor, panel, floating: { placement } }),
+*     { close: (reason, event) => setOpen(false, reason, event), shown: focusFirst },
+*   );
+*/
+function useAnchoredPopover(read, events) {
+	const layer = createAnchoredLayer();
+	trackEscape();
+	watchPostEffect(() => {
+		const { open, anchor, panel, floating, restoreFocus = true } = read();
+		if (!open) {
+			layer.hide({ restoreFocus });
+			return;
+		}
+		if (!anchor || !panel) return;
+		const opening = !layer.visible;
+		const ready = layer.show(anchor, panel, floating);
+		if (opening && events.shown) ready.then(() => events.shown(panel));
+	});
+	onScopeDispose(() => layer.hide({ restoreFocus: read().restoreFocus ?? true }));
+	return { onToggle(event) {
+		if (event.newState === "open") return;
+		const state = read();
+		if (state.open) events.close(closedByEscape(event) ? "escape" : "outside", event);
+		layer.hide({ restoreFocus: state.restoreFocus ?? true });
+	} };
+}
+var escapeAt = -Infinity;
+var trackingEscape = false;
+/** 开始记录 Esc（整页一个监听，第一个浮层组件 setup 时装上） */
+function trackEscape() {
+	if (trackingEscape || typeof window === "undefined") return;
+	trackingEscape = true;
+	window.addEventListener("keydown", (key) => key.key === "Escape" && (escapeAt = key.timeStamp), { capture: true });
+}
+/** toggle 事件紧跟在 Esc 之后（浏览器在按键后排队派发）就是 Esc 关的 */
+var closedByEscape = (event) => event.timeStamp - escapeAt < 250;
+//#endregion
+export { anchorFloating, anchoredPanelSx, createAnchoredLayer, floatingStyles, pointAnchor, useAnchoredPopover };
+
+//# sourceMappingURL=floating.js.map

package/dist/utils/dom/floating.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"floating.js","names":["arrow","arrowMiddleware"],"sources":["../../../src/utils/dom/floating.ts"],"sourcesContent":["/**\n * 锚定浮层：Popover、Tooltip、Menu、Select 的弹出层贴着触发器显示。位置由 floating-ui 计算，\n * 显示、隐藏、Esc、点击外部仍交给原生 popover；createAnchoredLayer 把两者串成打开、关闭的流程。\n *\n *   const anchored = anchorFloating(trigger, panel, { placement: 'bottom-start' });\n *   await anchored.ready;   // 第一次定位完成、已经可见：这时才能把焦点移进去\n *   anchored.stop();        // 关闭时停止跟随\n *   sx: [floatingStyles.anchored, …]   // 浮层自己的样式：去掉原生 popover 默认的居中与外边距\n *\n * - 第一次算好位置之前浮层是 visibility: hidden，不会在默认位置闪一下；\n * - 空间不够时翻到另一侧（flip）、贴着视口边缘挪回来（shift），滚动、缩放、锚点变化时自动重新定位（autoUpdate）；\n * - start / end 对齐是逻辑方向，从右到左排版下自动镜像（floating-ui 读浮层的 direction）；\n * - 最终方向写到 data-side / data-align，缩放原点（transform-origin）朝向锚点，进出场的 scale 过渡从锚点那侧展开。\n */\nimport {\n  arrow as arrowMiddleware,\n  autoUpdate,\n  computePosition,\n  flip,\n  offset,\n  shift,\n  size,\n  type Middleware,\n  type Placement,\n  type VirtualElement,\n} from '@floating-ui/dom';\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport { onScopeDispose, watchPostEffect } from 'vue';\nimport type { SxStyles } from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport { transitions } from '../style/transitions';\nimport { fontSizeStyles, type TextSize } from '../style/typography';\nimport { returnFocus } from './focus';\n\n/** 弹出位置：主方向 + 对齐方式（start 对齐锚点的起始边，end 对齐结束边）；空间不够时自动翻转 */\nexport interface FloatingPlacements {\n  /** 上方居中 */\n  top: unknown;\n  /** 上方，与锚点起始边对齐 */\n  'top-start': unknown;\n  /** 上方，与锚点结束边对齐 */\n  'top-end': unknown;\n  /** 下方居中 */\n  bottom: unknown;\n  /** 下方，与锚点起始边对齐 */\n  'bottom-start': unknown;\n  /** 下方，与锚点结束边对齐 */\n  'bottom-end': unknown;\n  /** 左侧居中 */\n  left: unknown;\n  /** 左侧，与锚点顶边对齐 */\n  'left-start': unknown;\n  /** 左侧，与锚点底边对齐 */\n  'left-end': unknown;\n  /** 右侧居中 */\n  right: unknown;\n  /** 右侧，与锚点顶边对齐 */\n  'right-start': unknown;\n  /** 右侧，与锚点底边对齐 */\n  'right-end': unknown;\n}\n\n/** 弹出位置 */\nexport type FloatingPlacement = keyof FloatingPlacements & Placement;\n\n/**\n * 锚点：元素，或只有位置的虚拟锚点（右键菜单从指针的位置弹出：`pointAnchor(x, y)`）。\n * 虚拟锚点没有元素可以还焦点，关闭后焦点由组件自己安排\n */\nexport type FloatingAnchor = HTMLElement | VirtualElement;\n\n/** 视口里一个点（clientX / clientY）做锚点 */\nexport function pointAnchor(x: number, y: number): VirtualElement {\n  return { getBoundingClientRect: () => new DOMRect(x, y, 0, 0) };\n}\n\n/** anchorFloating 的选项 */\nexport interface FloatingOptions {\n  /** 弹出位置，默认 bottom-start */\n  placement?: FloatingPlacement;\n  /** 与锚点的距离（px），默认 6 */\n  offset?: number;\n  /** 至少与锚点一样宽：下拉框、组合框的选项列表 */\n  matchWidth?: boolean;\n  /** 最大高度限制在视口剩余空间内（浮层自己设 overflow 滚动）：菜单、选项列表 */\n  fitHeight?: boolean;\n  /** 箭头元素（浮层里的子元素，样式用 floatingStyles.arrow）：指向锚点，随翻转换边；距离自动加上箭头露出的一半 */\n  arrow?: HTMLElement | null;\n  /** 主方向与对侧都放不下时，再试垂直的两侧（窄屏上“右侧”的大卡片改到上下）：引导卡片 */\n  crossAxisFallback?: boolean;\n}\n\n/** anchorFloating 的返回值 */\nexport interface Anchored {\n  /** 第一次定位完成、浮层已可见时完成；在这之前就 stop 时不会完成 */\n  readonly ready: Promise<void>;\n  /** 停止跟随锚点；关闭浮层时调用，重复调用无副作用 */\n  stop(): void;\n}\n\ntype Side = 'top' | 'right' | 'bottom' | 'left';\n\n/** 缩放原点朝向锚点：弹出在下方时从上边缘展开 */\nconst TRANSFORM_ORIGIN: Record<Side, string> = {\n  top: 'bottom',\n  right: 'left',\n  bottom: 'top',\n  left: 'right',\n};\n\n/** 箭头贴着浮层的哪条边（与弹出方向相反） */\nconst ARROW_EDGE: Record<Side, Side> = {\n  top: 'bottom',\n  right: 'left',\n  bottom: 'top',\n  left: 'right',\n};\n/** 箭头（画了右、下两条边的方块）转多少度才朝向锚点 */\nconst ARROW_ROTATION: Record<Side, number> = { top: 45, right: 135, bottom: 225, left: -45 };\n\n/**\n * 弹出面板（选项列表、树、日期面板）共用的样式：锚定定位、浮起的表面、缩放进出场；\n * 面板渲染在顶层，不是输入框外壳的后代、不继承它的字号：按控件的 size 设置。ListPopover、TreeSelect、日期选择器用它\n */\nexport function anchoredPanelSx(size?: TextSize): SxStyles {\n  return [\n    floatingStyles.anchored,\n    floatingStyles.surface,\n    size && fontSizeStyles[size],\n    transitions.scale,\n  ] as SxStyles;\n}\n\n/** 锚定浮层的基础样式：定位与表面 */\nexport const floatingStyles = css.create({\n  /** 原生 popover 默认居中显示、带外边距，改为由 anchorFloating 写入的 left / top 定位 */\n  anchored: { position: 'fixed', inset: 'auto', margin: 0 },\n  /** 浮起的表面：边框、圆角、阴影（Popover、Menu、选项列表）；内边距各自定 */\n  surface: {\n    boxSizing: 'border-box',\n    borderWidth: '_xs',\n    borderStyle: 'solid',\n    borderColor: '_border',\n    borderRadius: '_lg',\n    backgroundColor: '_surfaceRaised',\n    color: '_text',\n    boxShadow: '_lg',\n  },\n  /**\n   * 箭头：一个小方块，只画右、下两条边，旋转后尖角朝向锚点；底色、边框跟随浮层（inherit）。\n   * 位置与旋转由 anchorFloating 写\n   */\n  arrow: {\n    position: 'absolute',\n    boxSizing: 'border-box',\n    width: '0.625em',\n    height: '0.625em',\n    backgroundColor: 'inherit',\n    borderStyle: 'solid',\n    borderColor: 'inherit',\n    borderWidth: 0,\n    borderRightWidth: 'inherit',\n    borderBottomWidth: 'inherit',\n    borderBottomRightRadius: '_borderWidths.sm',\n    pointerEvents: 'none',\n  },\n  /** 有箭头的浮层：原生 popover 默认 overflow: auto 会把伸出去的箭头裁掉 */\n  withArrow: { overflow: 'visible' },\n  /**\n   * 内容会滚动的浮层（选项列表、菜单）：打开时是竖向 flex、裁掉溢出，里面放 ScrollArea（scrollArea）撑满，\n   * 滚动条是浮层的；关闭时仍由浏览器隐藏（只在 :popover-open 时改 display）\n   */\n  scrollPanel: {\n    display: { default: null, ':popover-open': 'flex' },\n    flexDirection: 'column',\n    overflow: 'hidden',\n    // 去掉原生 popover 默认的 0.25em 内边距：滚动条贴着浮层边缘，内边距由里面的内容层给\n    padding: 0,\n  },\n  /** scrollPanel 里的 ScrollArea：占满剩下的高度（最大高度由 anchorFloating 的 fitHeight 写在浮层上） */\n  scrollArea: { flexGrow: 1, minHeight: 0 },\n});\n\n/** 与视口边缘至少留出的距离（px） */\nconst VIEWPORT_PADDING = 8;\n\n/** 把 floating 定位到 anchor 旁边并持续跟随；floating 需要已经显示（如 showPopover 之后） */\nexport function anchorFloating(\n  anchor: FloatingAnchor,\n  floating: HTMLElement,\n  {\n    placement = 'bottom-start',\n    offset: distance = 6,\n    matchWidth,\n    fitHeight,\n    arrow,\n    crossAxisFallback,\n  }: FloatingOptions = {},\n): Anchored {\n  // 箭头伸出浮层一半（旋转后的对角线的一半约等于边长的 0.7）：距离加上这一段，尖角才不压在锚点上\n  const arrowSize = arrow?.offsetWidth ?? 0;\n  const middleware: Middleware[] = [\n    offset(distance + arrowSize * 0.7),\n    flip({\n      padding: VIEWPORT_PADDING,\n      fallbackAxisSideDirection: crossAxisFallback ? 'end' : 'none',\n    }),\n    shift({ padding: VIEWPORT_PADDING }),\n  ];\n  // 箭头离浮层的圆角留出距离，不会画到圆角外面\n  if (arrow) middleware.push(arrowMiddleware({ element: arrow, padding: arrowSize }));\n  if (matchWidth || fitHeight) {\n    middleware.push(\n      size({\n        padding: VIEWPORT_PADDING,\n        apply({ rects, availableHeight, elements }) {\n          if (matchWidth) elements.floating.style.minWidth = `${rects.reference.width}px`;\n          if (fitHeight) elements.floating.style.maxHeight = `${Math.max(0, availableHeight)}px`;\n        },\n      }),\n    );\n  }\n\n  let stopped = false;\n  let resolveReady!: () => void;\n  const ready = new Promise<void>((resolve) => (resolveReady = resolve));\n  floating.style.visibility = 'hidden';\n\n  const update = () =>\n    void computePosition(anchor, floating, { placement, strategy: 'fixed', middleware }).then(\n      ({ x, y, placement: final, middlewareData }) => {\n        if (stopped) return;\n        const [side, align = 'center'] = final.split('-') as [Side, string?];\n        if (arrow && middlewareData.arrow) {\n          const { x: arrowX, y: arrowY } = middlewareData.arrow;\n          Object.assign(arrow.style, {\n            left: arrowX != null ? `${arrowX}px` : '',\n            top: arrowY != null ? `${arrowY}px` : '',\n            right: '',\n            bottom: '',\n            [ARROW_EDGE[side]]: `${-arrowSize / 2}px`,\n            transform: `rotate(${ARROW_ROTATION[side]}deg)`,\n          });\n        }\n        Object.assign(floating.style, {\n          left: `${x}px`,\n          top: `${y}px`,\n          visibility: '',\n          transformOrigin: TRANSFORM_ORIGIN[side],\n        });\n        floating.dataset.side = side;\n        floating.dataset.align = align;\n        resolveReady();\n      },\n    );\n  const cleanup = autoUpdate(anchor, floating, update);\n\n  return {\n    ready,\n    stop() {\n      if (stopped) return;\n      stopped = true;\n      cleanup();\n    },\n  };\n}\n\n/** 关闭浮层时焦点还给谁：true 锚点，元素，或 false 不还 */\nexport type RestoreFocus = boolean | HTMLElement | null;\n\n/** createAnchoredLayer 的返回值：一个原生 popover 浮层的打开与关闭 */\nexport interface AnchoredLayer {\n  /** 是否显示着（show 之后、hide 之前） */\n  readonly visible: boolean;\n  /** 显示 panel（showPopover）并贴着 anchor 定位；返回第一次定位完成、可以移入焦点的 Promise。已显示时不重复 */\n  show(anchor: FloatingAnchor, panel: HTMLElement, options?: FloatingOptions): Promise<void>;\n  /**\n   * 停止定位并隐藏；焦点还在浮层里或已丢失时归还：restoreFocus 默认 true 还给锚点，给元素时还给它，false 不还。\n   * 未显示时什么也不做\n   */\n  hide(options?: { restoreFocus?: RestoreFocus }): void;\n}\n\n/**\n * 锚定浮层的生命周期（Popover、Menu、Tooltip 共用）：显示 → 定位 → 关闭时停止定位、归还焦点。\n * 原生 popover=\"auto\" 被 Esc、点击外部关闭（light dismiss）时浏览器先隐藏了它，组件在 toggle 事件里调用 hide 收尾。\n */\nexport function createAnchoredLayer(): AnchoredLayer {\n  let current: { anchor: FloatingAnchor; panel: HTMLElement; anchored: Anchored } | undefined;\n  let ready: Promise<void> = Promise.resolve();\n  return {\n    get visible() {\n      return current != null;\n    },\n    show(anchor, panel, options) {\n      if (current) return ready;\n      if (!panel.matches(':popover-open')) panel.showPopover();\n      const anchored = anchorFloating(anchor, panel, options);\n      current = { anchor, panel, anchored };\n      ready = anchored.ready;\n      return ready;\n    },\n    hide({ restoreFocus = true } = {}) {\n      if (!current) return;\n      const { anchor, panel, anchored } = current;\n      current = undefined;\n      anchored.stop();\n      if (panel.matches(':popover-open')) panel.hidePopover();\n      const target = restoreFocus === true ? anchor : restoreFocus;\n      if (target instanceof HTMLElement) returnFocus(panel, target);\n    },\n  };\n}\n\n/** useAnchoredPopover 每次渲染后读取的状态 */\nexport interface AnchoredPopoverState {\n  /** 是否打开 */\n  open: boolean;\n  /** 锚点（触发器、输入框外壳，或右键菜单的虚拟锚点） */\n  anchor: FloatingAnchor | null;\n  /** 浮层（popover 元素） */\n  panel: HTMLElement | null;\n  /** 定位选项 */\n  floating?: FloatingOptions;\n  /**\n   * 关闭时焦点还给谁：默认 true 还给锚点；锚点是输入框外壳时给打开按钮（DatePicker）；\n   * 焦点一直在锚点上的组件（Select、Combobox）设 false\n   */\n  restoreFocus?: RestoreFocus;\n}\n\n/** useAnchoredPopover 的回调 */\nexport interface AnchoredPopoverEvents {\n  /** 浏览器关掉了浮层：按了 Esc，或点了外面（别的浮层打开也算）；组件把 open 写回 false */\n  close: (reason: 'escape' | 'outside', event: Event) => void;\n  /** 浮层打开并第一次定位完成（可见）：移入焦点等 */\n  shown?: (panel: HTMLElement) => void;\n}\n\n/**\n * 原生 popover=\"auto\" 的锚定浮层接到组件的 open 上（Popover、Menu、Select、Combobox 共用）：\n * open 变化时显示或隐藏（DOM 更新之后），浏览器的 light dismiss 写回 open，卸载时收起。\n * 返回要放到浮层元素上的 onToggle。在组件 setup 里调用。\n *\n *   const { onToggle } = useAnchoredPopover(\n *     () => ({ open, anchor, panel, floating: { placement } }),\n *     { close: (reason, event) => setOpen(false, reason, event), shown: focusFirst },\n *   );\n */\nexport function useAnchoredPopover(\n  read: () => AnchoredPopoverState,\n  events: AnchoredPopoverEvents,\n): { onToggle: (event: Event) => void } {\n  const layer = createAnchoredLayer();\n  trackEscape();\n\n  watchPostEffect(() => {\n    const { open, anchor, panel, floating, restoreFocus = true } = read();\n    if (!open) {\n      layer.hide({ restoreFocus });\n      return;\n    }\n    if (!anchor || !panel) return;\n    // 已经显示着（只是定位选项变了）时不再触发 shown，焦点不会被拉回第一项\n    const opening = !layer.visible;\n    const ready = layer.show(anchor, panel, floating);\n    if (opening && events.shown) void ready.then(() => events.shown!(panel));\n  });\n  onScopeDispose(() => layer.hide({ restoreFocus: read().restoreFocus ?? true }));\n\n  return {\n    onToggle(event) {\n      if ((event as ToggleEvent).newState === 'open') return;\n      const state = read();\n      if (state.open) events.close(closedByEscape(event) ? 'escape' : 'outside', event);\n      layer.hide({ restoreFocus: state.restoreFocus ?? true });\n    },\n  };\n}\n\n// 最近一次按 Esc 的时间：light dismiss 的 toggle 事件不说原因，按时间判断是不是 Esc 关的\nlet escapeAt = -Infinity;\nlet trackingEscape = false;\n\n/** 开始记录 Esc（整页一个监听，第一个浮层组件 setup 时装上） */\nfunction trackEscape() {\n  if (trackingEscape || typeof window === 'undefined') return;\n  trackingEscape = true;\n  window.addEventListener('keydown', (key) => key.key === 'Escape' && (escapeAt = key.timeStamp), {\n    capture: true,\n  });\n}\n\n/** toggle 事件紧跟在 Esc 之后（浏览器在按键后排队派发）就是 Esc 关的 */\nconst closedByEscape = (event: Event) => event.timeStamp - escapeAt < 250;\n"],"mappings":"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"}

package/dist/utils/dom/focus.d.ts

@@ -0,0 +1,28 @@
+/** 把焦点移到容器里第一个可聚焦的元素（有 autofocus 的优先）；没有时聚焦容器本身 */
+export declare function focusFirst(container: HTMLElement): void;
+/**
+ * 聚焦一个控件：它本身不能聚焦时（RadioGroup 的 radiogroup、一组分段输入的容器）聚焦里面第一个能聚焦的。
+ * 表单提交不通过时把焦点移到出错的控件上用它
+ */
+export declare function focusControl(element: HTMLElement): void;
+/** 打开弹层前的焦点来源，关闭时交给 returnFocus：当前焦点；焦点在 body 上时取最近一次按下的可聚焦元素 */
+export declare function focusOrigin(): Element | null;
+/**
+ * 关闭弹层后把焦点还给 target（触发器或打开前的元素）。焦点还在弹层里、或已经丢到 body 上时才还；
+ * 用户已经把焦点移到别处时不打扰。原生关闭后各浏览器不一致：Chromium 会还回去，
+ * WebKit 把焦点留在已隐藏的弹层里，所以统一由组件负责。
+ */
+export declare function returnFocus(overlay: HTMLElement, target: Element | null): void;
+/**
+ * 用户在 element 里点了移除或关闭（Tag 的移除、Alert 与 Toast 的关闭）时、调用回调之前调用：
+ * element 随后真的被移除、焦点随之掉到 body 上时，把焦点交给同组（父元素里）的下一个可聚焦元素，
+ * 没有就交给上一个，都没有时交给 fallback（同 React Aria TagGroup：移除后焦点落到相邻的项上）。
+ * 浏览器只保留 Tab 的起点，读屏用户却会被带回页面开头，所以由组件接住。
+ * 焦点已经移到别处、或 element 没被移除，都不打扰。
+ */
+export declare function focusAfterRemoval(element: HTMLElement, fallback?: HTMLElement | null): void;
+/**
+ * 模态里的焦点循环：在最后一个元素上按 Tab 回到第一个，在第一个上按 Shift+Tab 到最后一个。
+ * 原生模态 dialog 不做这一步（焦点会离开页面）。返回撤销函数。
+ */
+export declare function trapFocus(container: HTMLElement): () => void;

package/dist/utils/dom/focus.js

@@ -0,0 +1,105 @@
+import { tabbable } from "tabbable";
+//#region src/utils/dom/focus.ts
+/**
+* 焦点工具：弹层的焦点进出（focusFirst、focusOrigin、returnFocus、trapFocus）与元素被移除后焦点的去向
+* （focusAfterRemoval）。浏览器在这些地方不做或各家不一致，组件统一用这里的实现。
+* 漫游焦点（一组项里方向键移动）见 roving-focus.ts。
+*/
+/** 把焦点移到容器里第一个可聚焦的元素（有 autofocus 的优先）；没有时聚焦容器本身 */
+function focusFirst(container) {
+	(container.querySelector("[autofocus]") ?? tabbable(container)[0] ?? container).focus();
+}
+/**
+* 聚焦一个控件：它本身不能聚焦时（RadioGroup 的 radiogroup、一组分段输入的容器）聚焦里面第一个能聚焦的。
+* 表单提交不通过时把焦点移到出错的控件上用它
+*/
+function focusControl(element) {
+	(element.matches(FOCUSABLE) ? element : tabbable(element)[0])?.focus();
+}
+var FOCUSABLE = "button, a[href], input, select, textarea, summary, [tabindex]";
+/** Safari 点击按钮不会聚焦它：记下最近一次按下的可聚焦元素，作为焦点来源的备选 */
+var lastPressed = null;
+if (typeof document !== "undefined") document.addEventListener("pointerdown", (event) => lastPressed = event.target.closest?.(FOCUSABLE) ?? null, true);
+/** 打开弹层前的焦点来源，关闭时交给 returnFocus：当前焦点；焦点在 body 上时取最近一次按下的可聚焦元素 */
+function focusOrigin() {
+	const active = document.activeElement;
+	return active && active !== document.body ? active : lastPressed;
+}
+/**
+* 关闭弹层后把焦点还给 target（触发器或打开前的元素）。焦点还在弹层里、或已经丢到 body 上时才还；
+* 用户已经把焦点移到别处时不打扰。原生关闭后各浏览器不一致：Chromium 会还回去，
+* WebKit 把焦点留在已隐藏的弹层里，所以统一由组件负责。
+*/
+function returnFocus(overlay, target) {
+	const active = document.activeElement;
+	if ((!active || active === document.body || overlay.contains(active)) && target instanceof HTMLElement && target.isConnected) target.focus();
+}
+/**
+* 用户在 element 里点了移除或关闭（Tag 的移除、Alert 与 Toast 的关闭）时、调用回调之前调用：
+* element 随后真的被移除、焦点随之掉到 body 上时，把焦点交给同组（父元素里）的下一个可聚焦元素，
+* 没有就交给上一个，都没有时交给 fallback（同 React Aria TagGroup：移除后焦点落到相邻的项上）。
+* 浏览器只保留 Tab 的起点，读屏用户却会被带回页面开头，所以由组件接住。
+* 焦点已经移到别处、或 element 没被移除，都不打扰。
+*/
+function focusAfterRemoval(element, fallback) {
+	const group = element.parentElement;
+	if (!group || !element.contains(document.activeElement)) return;
+	const others = tabbable(group).filter((item) => !element.contains(item));
+	const following = others.filter((item) => element.compareDocumentPosition(item) & Node.DOCUMENT_POSITION_FOLLOWING);
+	const preceding = others.filter((item) => !following.includes(item)).reverse();
+	const candidates = fallback ? [
+		...following,
+		...preceding,
+		fallback
+	] : [...following, ...preceding];
+	const stop = () => {
+		observer.disconnect();
+		element.removeEventListener("focusout", onFocusOut);
+	};
+	const onFocusOut = (event) => {
+		const next = event.relatedTarget;
+		if (next instanceof Node && !element.contains(next)) stop();
+	};
+	const observer = new MutationObserver(() => {
+		if (element.isConnected) return;
+		stop();
+		const active = document.activeElement;
+		if (active && active !== document.body) return;
+		candidates.find((item) => item.isConnected)?.focus();
+	});
+	observer.observe(document.body, {
+		childList: true,
+		subtree: true
+	});
+	element.addEventListener("focusout", onFocusOut);
+}
+/**
+* 模态里的焦点循环：在最后一个元素上按 Tab 回到第一个，在第一个上按 Shift+Tab 到最后一个。
+* 原生模态 dialog 不做这一步（焦点会离开页面）。返回撤销函数。
+*/
+function trapFocus(container) {
+	const onKeydown = (event) => {
+		if (event.key !== "Tab") return;
+		const items = tabbable(container);
+		if (!items.length) {
+			event.preventDefault();
+			return;
+		}
+		const first = items[0];
+		const last = items.at(-1);
+		const active = document.activeElement;
+		if (event.shiftKey && (active === first || active === container)) {
+			event.preventDefault();
+			last.focus();
+		} else if (!event.shiftKey && active === last) {
+			event.preventDefault();
+			first.focus();
+		}
+	};
+	container.addEventListener("keydown", onKeydown);
+	return () => container.removeEventListener("keydown", onKeydown);
+}
+//#endregion
+export { focusAfterRemoval, focusControl, focusFirst, focusOrigin, returnFocus, trapFocus };
+
+//# sourceMappingURL=focus.js.map

package/dist/utils/dom/focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus.js","names":[],"sources":["../../../src/utils/dom/focus.ts"],"sourcesContent":["/**\n * 焦点工具：弹层的焦点进出（focusFirst、focusOrigin、returnFocus、trapFocus）与元素被移除后焦点的去向\n * （focusAfterRemoval）。浏览器在这些地方不做或各家不一致，组件统一用这里的实现。\n * 漫游焦点（一组项里方向键移动）见 roving-focus.ts。\n */\nimport { tabbable } from 'tabbable';\n\n/** 把焦点移到容器里第一个可聚焦的元素（有 autofocus 的优先）；没有时聚焦容器本身 */\nexport function focusFirst(container: HTMLElement): void {\n  const target =\n    container.querySelector<HTMLElement>('[autofocus]') ?? tabbable(container)[0] ?? container;\n  target.focus();\n}\n\n/**\n * 聚焦一个控件：它本身不能聚焦时（RadioGroup 的 radiogroup、一组分段输入的容器）聚焦里面第一个能聚焦的。\n * 表单提交不通过时把焦点移到出错的控件上用它\n */\nexport function focusControl(element: HTMLElement): void {\n  // 先看能不能聚焦，而不是聚焦后再看 activeElement：有的环境（happy-dom）让任何元素都能拿到焦点\n  const target = element.matches(FOCUSABLE) ? element : tabbable(element)[0];\n  target?.focus();\n}\n\nconst FOCUSABLE = 'button, a[href], input, select, textarea, summary, [tabindex]';\n\n/** Safari 点击按钮不会聚焦它：记下最近一次按下的可聚焦元素，作为焦点来源的备选 */\nlet lastPressed: Element | null = null;\nif (typeof document !== 'undefined') {\n  document.addEventListener(\n    'pointerdown',\n    (event) => (lastPressed = (event.target as Element).closest?.(FOCUSABLE) ?? null),\n    true,\n  );\n}\n\n/** 打开弹层前的焦点来源，关闭时交给 returnFocus：当前焦点；焦点在 body 上时取最近一次按下的可聚焦元素 */\nexport function focusOrigin(): Element | null {\n  const active = document.activeElement;\n  return active && active !== document.body ? active : lastPressed;\n}\n\n/**\n * 关闭弹层后把焦点还给 target（触发器或打开前的元素）。焦点还在弹层里、或已经丢到 body 上时才还；\n * 用户已经把焦点移到别处时不打扰。原生关闭后各浏览器不一致：Chromium 会还回去，\n * WebKit 把焦点留在已隐藏的弹层里，所以统一由组件负责。\n */\nexport function returnFocus(overlay: HTMLElement, target: Element | null): void {\n  const active = document.activeElement;\n  const lost = !active || active === document.body || overlay.contains(active);\n  if (lost && target instanceof HTMLElement && target.isConnected) target.focus();\n}\n\n/**\n * 用户在 element 里点了移除或关闭（Tag 的移除、Alert 与 Toast 的关闭）时、调用回调之前调用：\n * element 随后真的被移除、焦点随之掉到 body 上时，把焦点交给同组（父元素里）的下一个可聚焦元素，\n * 没有就交给上一个，都没有时交给 fallback（同 React Aria TagGroup：移除后焦点落到相邻的项上）。\n * 浏览器只保留 Tab 的起点，读屏用户却会被带回页面开头，所以由组件接住。\n * 焦点已经移到别处、或 element 没被移除，都不打扰。\n */\nexport function focusAfterRemoval(element: HTMLElement, fallback?: HTMLElement | null): void {\n  const group = element.parentElement;\n  if (!group || !element.contains(document.activeElement)) return;\n  const others = tabbable(group).filter((item) => !element.contains(item));\n  const following = others.filter(\n    (item) => element.compareDocumentPosition(item) & Node.DOCUMENT_POSITION_FOLLOWING,\n  );\n  const preceding = others.filter((item) => !following.includes(item)).reverse();\n  const candidates = fallback\n    ? [...following, ...preceding, fallback]\n    : [...following, ...preceding];\n\n  const stop = () => {\n    observer.disconnect();\n    element.removeEventListener('focusout', onFocusOut);\n  };\n  // 焦点被用户移到 element 外面：不再接管\n  const onFocusOut = (event: FocusEvent) => {\n    const next = event.relatedTarget;\n    if (next instanceof Node && !element.contains(next)) stop();\n  };\n  // 移除发生在 Vue 更新 DOM 时；MutationObserver 的回调在这之后的微任务里运行\n  const observer = new MutationObserver(() => {\n    if (element.isConnected) return;\n    stop();\n    const active = document.activeElement;\n    if (active && active !== document.body) return;\n    candidates.find((item) => item.isConnected)?.focus();\n  });\n  observer.observe(document.body, { childList: true, subtree: true });\n  element.addEventListener('focusout', onFocusOut);\n}\n\n/**\n * 模态里的焦点循环：在最后一个元素上按 Tab 回到第一个，在第一个上按 Shift+Tab 到最后一个。\n * 原生模态 dialog 不做这一步（焦点会离开页面）。返回撤销函数。\n */\nexport function trapFocus(container: HTMLElement): () => void {\n  const onKeydown = (event: KeyboardEvent) => {\n    if (event.key !== 'Tab') return;\n    const items = tabbable(container);\n    if (!items.length) {\n      event.preventDefault();\n      return;\n    }\n    const first = items[0]!;\n    const last = items.at(-1)!;\n    const active = document.activeElement;\n    if (event.shiftKey && (active === first || active === container)) {\n      event.preventDefault();\n      last.focus();\n    } else if (!event.shiftKey && active === last) {\n      event.preventDefault();\n      first.focus();\n    }\n  };\n  container.addEventListener('keydown', onKeydown);\n  return () => container.removeEventListener('keydown', onKeydown);\n}\n"],"mappings":";;;;;;;;AAQA,SAAgB,WAAW,WAA8B;CAGvD,CADE,UAAU,cAA2B,aAAa,KAAK,SAAS,SAAS,CAAC,CAAC,MAAM,UAAA,CAC5E,MAAM;AACf;;;;;AAMA,SAAgB,aAAa,SAA4B;CAGvD,CADe,QAAQ,QAAQ,SAAS,IAAI,UAAU,SAAS,OAAO,CAAC,CAAC,GAAA,EAChE,MAAM;AAChB;AAEA,IAAM,YAAY;;AAGlB,IAAI,cAA8B;AAClC,IAAI,OAAO,aAAa,aACtB,SAAS,iBACP,gBACC,UAAW,cAAe,MAAM,OAAmB,UAAU,SAAS,KAAK,MAC5E,IACF;;AAIF,SAAgB,cAA8B;CAC5C,MAAM,SAAS,SAAS;CACxB,OAAO,UAAU,WAAW,SAAS,OAAO,SAAS;AACvD;;;;;;AAOA,SAAgB,YAAY,SAAsB,QAA8B;CAC9E,MAAM,SAAS,SAAS;CAExB,KADa,CAAC,UAAU,WAAW,SAAS,QAAQ,QAAQ,SAAS,MAAM,MAC/D,kBAAkB,eAAe,OAAO,aAAa,OAAO,MAAM;AAChF;;;;;;;;AASA,SAAgB,kBAAkB,SAAsB,UAAqC;CAC3F,MAAM,QAAQ,QAAQ;CACtB,IAAI,CAAC,SAAS,CAAC,QAAQ,SAAS,SAAS,aAAa,GAAG;CACzD,MAAM,SAAS,SAAS,KAAK,CAAC,CAAC,QAAQ,SAAS,CAAC,QAAQ,SAAS,IAAI,CAAC;CACvE,MAAM,YAAY,OAAO,QACtB,SAAS,QAAQ,wBAAwB,IAAI,IAAI,KAAK,2BACzD;CACA,MAAM,YAAY,OAAO,QAAQ,SAAS,CAAC,UAAU,SAAS,IAAI,CAAC,CAAC,CAAC,QAAQ;CAC7E,MAAM,aAAa,WACf;EAAC,GAAG;EAAW,GAAG;EAAW;CAAQ,IACrC,CAAC,GAAG,WAAW,GAAG,SAAS;CAE/B,MAAM,aAAa;EACjB,SAAS,WAAW;EACpB,QAAQ,oBAAoB,YAAY,UAAU;CACpD;CAEA,MAAM,cAAc,UAAsB;EACxC,MAAM,OAAO,MAAM;EACnB,IAAI,gBAAgB,QAAQ,CAAC,QAAQ,SAAS,IAAI,GAAG,KAAK;CAC5D;CAEA,MAAM,WAAW,IAAI,uBAAuB;EAC1C,IAAI,QAAQ,aAAa;EACzB,KAAK;EACL,MAAM,SAAS,SAAS;EACxB,IAAI,UAAU,WAAW,SAAS,MAAM;EACxC,WAAW,MAAM,SAAS,KAAK,WAAW,CAAC,EAAE,MAAM;CACrD,CAAC;CACD,SAAS,QAAQ,SAAS,MAAM;EAAE,WAAW;EAAM,SAAS;CAAK,CAAC;CAClE,QAAQ,iBAAiB,YAAY,UAAU;AACjD;;;;;AAMA,SAAgB,UAAU,WAAoC;CAC5D,MAAM,aAAa,UAAyB;EAC1C,IAAI,MAAM,QAAQ,OAAO;EACzB,MAAM,QAAQ,SAAS,SAAS;EAChC,IAAI,CAAC,MAAM,QAAQ;GACjB,MAAM,eAAe;GACrB;EACF;EACA,MAAM,QAAQ,MAAM;EACpB,MAAM,OAAO,MAAM,GAAG,EAAE;EACxB,MAAM,SAAS,SAAS;EACxB,IAAI,MAAM,aAAa,WAAW,SAAS,WAAW,YAAY;GAChE,MAAM,eAAe;GACrB,KAAK,MAAM;EACb,OAAO,IAAI,CAAC,MAAM,YAAY,WAAW,MAAM;GAC7C,MAAM,eAAe;GACrB,MAAM,MAAM;EACd;CACF;CACA,UAAU,iBAAiB,WAAW,SAAS;CAC/C,aAAa,UAAU,oBAAoB,WAAW,SAAS;AACjE"}

package/dist/utils/dom/fullscreen.d.ts

@@ -0,0 +1,11 @@
+/** useFullscreen 的返回值 */
+export interface Fullscreen {
+    /** 这个元素正在全屏 */
+    readonly active: boolean;
+    /** 浏览器支持全屏 */
+    readonly supported: boolean;
+    /** 进入或退出全屏 */
+    toggle(): Promise<void>;
+}
+/** 元素的全屏状态与切换 */
+export declare function useFullscreen(target: () => HTMLElement | null | undefined): Fullscreen;