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

package/dist/utils/dom/hotkeys.js

@@ -0,0 +1,174 @@
+import { topModal } from "./overlay.js";
+import { useEventListener } from "./event-listener.js";
+//#region src/utils/dom/hotkeys.ts
+/**
+* 键盘快捷键：在 document 上监听，组件卸载时注销。
+*
+*   useHotkeys(() => ({ 'Mod+K': openSearch, 'Shift+?': showHelp, Escape: close, 'G I': goInbox }));
+*   formatHotkey('Mod+K')   // macOS 上 '⌘K'，其他系统 'Ctrl+K'：Menu 等显示用
+*
+* 写法：修饰键（Mod、Ctrl、Alt、Shift、Meta）加一个键，用 + 连接，不分大小写；
+* Mod 在 macOS 上是 ⌘（Meta），其他系统是 Ctrl。键名同 KeyboardEvent.key（Enter、ArrowUp、/）；
+* 字母按物理键也能匹配（macOS 上 Option 会改变 key）。没写的修饰键必须没按下；符号键（? ! 等）不检查 Shift。
+* 焦点在输入框、可编辑区域里时默认不触发，输入法组字时也不触发。
+*
+* 序列键用空格分隔（'G I'：先按 g 再按 i，两次之间不超过 1.5 秒，同 GitHub 的 hotkey）；序列比单键优先。
+* 所以组合键里的 + 两边不要加空格（写 'Mod+K'，不写 'Mod + K'）。
+* 作用域：默认在整个页面上监听，但有模态对话框打开时只认对话框里的按键（页面已经不可操作）；
+* target 让快捷键只在某个区域里有焦点时生效（编辑器、表格）。
+*/
+/** 是否 Apple 平台：Mod 取 ⌘ */
+function isApplePlatform() {
+	const nav = globalThis.navigator;
+	const platform = nav?.userAgentData?.platform ?? nav?.platform ?? "";
+	return /mac|iphone|ipad|ipod/i.test(platform);
+}
+var KEY_ALIASES = {
+	space: " ",
+	esc: "escape",
+	up: "arrowup",
+	down: "arrowdown",
+	left: "arrowleft",
+	right: "arrowright"
+};
+var parsed = /* @__PURE__ */ new Map();
+/** 'Mod+Shift+K' → 各修饰键与键名（小写）；同一个写法只解析一次 */
+function parseHotkey(combo) {
+	const key = `${isApplePlatform() ? "apple" : "other"}:${combo}`;
+	let hotkey = parsed.get(key);
+	if (!hotkey) parsed.set(key, hotkey = parse(combo));
+	return hotkey;
+}
+function parse(combo) {
+	const parts = combo.split("+").map((part) => part.trim());
+	const name = (combo.endsWith("++") ? "+" : parts.pop()).toLowerCase();
+	const key = KEY_ALIASES[name] ?? name;
+	const modifiers = new Set(parts.filter(Boolean).map((part) => part.toLowerCase()));
+	const apple = isApplePlatform();
+	return {
+		key,
+		ctrl: modifiers.has("ctrl") || modifiers.has("mod") && !apple,
+		alt: modifiers.has("alt") || modifiers.has("option"),
+		shift: modifiers.has("shift"),
+		meta: modifiers.has("meta") || modifiers.has("cmd") || modifiers.has("mod") && apple
+	};
+}
+/** 事件是否匹配这个快捷键 */
+function matchesHotkey(event, combo) {
+	const hotkey = typeof combo === "string" ? parseHotkey(combo) : combo;
+	const letter = /^[a-z]$/.test(hotkey.key);
+	const symbol = hotkey.key.length === 1 && !letter && !/^\d$/.test(hotkey.key);
+	if (event.ctrlKey !== hotkey.ctrl || event.altKey !== hotkey.alt || event.metaKey !== hotkey.meta) return false;
+	if (!symbol && event.shiftKey !== hotkey.shift) return false;
+	return event.key.toLowerCase() === hotkey.key || letter && event.code === `Key${hotkey.key.toUpperCase()}`;
+}
+var KEY_NAMES = {
+	" ": "Space",
+	arrowup: "ArrowUp",
+	arrowdown: "ArrowDown",
+	arrowleft: "ArrowLeft",
+	arrowright: "ArrowRight",
+	pageup: "PageUp",
+	pagedown: "PageDown"
+};
+var keyName = (key) => KEY_NAMES[key] ?? (key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1));
+var modifiersOf = (hotkey) => [
+	"ctrl",
+	"alt",
+	"shift",
+	"meta"
+].filter((name) => hotkey[name]);
+var SYMBOLS = {
+	ctrl: "⌃",
+	alt: "⌥",
+	shift: "⇧",
+	meta: "⌘"
+};
+var ARROWS = {
+	ArrowUp: "↑",
+	ArrowDown: "↓",
+	ArrowLeft: "←",
+	ArrowRight: "→"
+};
+/** 快捷键的显示文字：macOS 上用符号（⌘⇧K），其他系统用 Ctrl+Shift+K；方向键显示成箭头 */
+function formatHotkey(combo) {
+	return combo.trim().split(/\s+/).map(formatStep).join(" ");
+}
+function formatStep(combo) {
+	const hotkey = parseHotkey(combo);
+	const key = keyName(hotkey.key);
+	const shown = ARROWS[key] ?? key;
+	if (isApplePlatform()) return modifiersOf(hotkey).map((name) => SYMBOLS[name]).join("") + shown;
+	const names = {
+		ctrl: "Ctrl",
+		alt: "Alt",
+		shift: "Shift",
+		meta: "Win"
+	};
+	return [...modifiersOf(hotkey).map((name) => names[name]), shown].join("+");
+}
+/**
+* 快捷键的 aria-keyshortcuts 写法（读屏念出来）：'Mod+K' → 'Control+K'，macOS 上 'Meta+K'。
+* 显示快捷键的 Kbd 对读屏隐藏、改由这个属性提供时，按钮的名称与看得见的文字才对得上。
+* 序列键（'G I'）表达不了（aria-keyshortcuts 里空格表示“或”）：返回 undefined，显示的文字就别对读屏隐藏
+*/
+function ariaKeyShortcut(combo) {
+	if (/\s/.test(combo.trim())) return void 0;
+	const hotkey = parseHotkey(combo);
+	const names = {
+		ctrl: "Control",
+		alt: "Alt",
+		shift: "Shift",
+		meta: "Meta"
+	};
+	return [...modifiersOf(hotkey).map((name) => names[name]), keyName(hotkey.key)].join("+");
+}
+/**
+* 这次按键属于输入法的组合输入（拼音选词时的回车、方向键、空格）：快捷键与列表的键盘操作都不该处理它。
+* Chrome、Firefox 组合中是 isComposing；Safari 先派发 compositionend、再派发确认用的 keydown，只能看 keyCode 229
+*/
+function isComposingKey(event) {
+	return event.isComposing || event.keyCode === 229;
+}
+/** 事件目标是不是可编辑的元素（输入框、文本域、下拉、contenteditable）：方向键、字母键这时留给它 */
+function isEditable(target) {
+	if (!(target instanceof HTMLElement)) return false;
+	return target.isContentEditable || /^(input|textarea|select)$/i.test(target.tagName);
+}
+/** 序列键两次按键之间最多隔多久（毫秒） */
+var SEQUENCE_TIMEOUT = 1500;
+/** 注册快捷键（在 setup 里调用）；read 在按键时读取，处理函数总是最新的 */
+function useHotkeys(read, { inInputs = false, target } = {}) {
+	if (typeof document === "undefined") return;
+	let recent = [];
+	const onKeydown = (event) => {
+		if (isComposingKey(event) || event.defaultPrevented) return;
+		if (!inInputs && isEditable(event.target)) return;
+		const modal = topModal();
+		if (!target && modal && !(event.target instanceof Node && modal.contains(event.target))) return;
+		const now = performance.now();
+		recent = [...recent.filter((item) => now - item.at < SEQUENCE_TIMEOUT), {
+			event,
+			at: now
+		}].slice(-4);
+		const entries = Object.entries(read()).map(([combo, handler]) => ({
+			steps: combo.trim().split(/\s+/),
+			handler
+		}));
+		entries.sort((a, b) => b.steps.length - a.steps.length);
+		for (const { steps, handler } of entries) {
+			const tail = recent.slice(-steps.length);
+			if (tail.length < steps.length) continue;
+			if (!steps.every((step, index) => matchesHotkey(tail[index].event, step))) continue;
+			event.preventDefault();
+			recent = [];
+			handler(event);
+			return;
+		}
+	};
+	useEventListener(target ?? document, "keydown", onKeydown);
+}
+//#endregion
+export { ariaKeyShortcut, formatHotkey, isApplePlatform, isComposingKey, isEditable, matchesHotkey, parseHotkey, useHotkeys };
+
+//# sourceMappingURL=hotkeys.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hotkeys.js","names":[],"sources":["../../../src/utils/dom/hotkeys.ts"],"sourcesContent":["/**\n * 键盘快捷键：在 document 上监听，组件卸载时注销。\n *\n *   useHotkeys(() => ({ 'Mod+K': openSearch, 'Shift+?': showHelp, Escape: close, 'G I': goInbox }));\n *   formatHotkey('Mod+K')   // macOS 上 '⌘K'，其他系统 'Ctrl+K'：Menu 等显示用\n *\n * 写法：修饰键（Mod、Ctrl、Alt、Shift、Meta）加一个键，用 + 连接，不分大小写；\n * Mod 在 macOS 上是 ⌘（Meta），其他系统是 Ctrl。键名同 KeyboardEvent.key（Enter、ArrowUp、/）；\n * 字母按物理键也能匹配（macOS 上 Option 会改变 key）。没写的修饰键必须没按下；符号键（? ! 等）不检查 Shift。\n * 焦点在输入框、可编辑区域里时默认不触发，输入法组字时也不触发。\n *\n * 序列键用空格分隔（'G I'：先按 g 再按 i，两次之间不超过 1.5 秒，同 GitHub 的 hotkey）；序列比单键优先。\n * 所以组合键里的 + 两边不要加空格（写 'Mod+K'，不写 'Mod + K'）。\n * 作用域：默认在整个页面上监听，但有模态对话框打开时只认对话框里的按键（页面已经不可操作）；\n * target 让快捷键只在某个区域里有焦点时生效（编辑器、表格）。\n */\nimport { useEventListener } from './event-listener';\nimport { topModal } from './overlay';\n\n/** useHotkeys 的选项 */\nexport interface HotkeyOptions {\n  /** 焦点在输入框、文本框、下拉框、可编辑区域里时也触发，默认 false */\n  inInputs?: boolean;\n  /**\n   * 只在这个元素（或它里面）有焦点时生效；默认整个页面。getter 要读响应式的值（ref 存在 `_state.raw` 里），\n   * 元素挂上之后才会重新绑定：存在普通变量里时 getter 只在 setup 时读一次，拿到的是 null\n   */\n  target?: () => HTMLElement | null | undefined;\n}\n\n/** 快捷键 → 处理函数；匹配时先 preventDefault 再调用 */\nexport type HotkeyMap = Record<string, (event: KeyboardEvent) => void>;\n\ninterface Hotkey {\n  key: string;\n  ctrl: boolean;\n  alt: boolean;\n  shift: boolean;\n  meta: boolean;\n}\n\n/** 是否 Apple 平台：Mod 取 ⌘ */\nexport function isApplePlatform(): boolean {\n  const nav = globalThis.navigator as\n    (Navigator & { userAgentData?: { platform: string } }) | undefined;\n  const platform = nav?.userAgentData?.platform ?? nav?.platform ?? '';\n  return /mac|iphone|ipad|ipod/i.test(platform);\n}\n\n// 好写的别名 → KeyboardEvent.key\nconst KEY_ALIASES: Record<string, string> = {\n  space: ' ',\n  esc: 'escape',\n  up: 'arrowup',\n  down: 'arrowdown',\n  left: 'arrowleft',\n  right: 'arrowright',\n};\n\nconst parsed = new Map<string, Hotkey>();\n\n/** 'Mod+Shift+K' → 各修饰键与键名（小写）；同一个写法只解析一次 */\nexport function parseHotkey(combo: string): Hotkey {\n  // Mod 按平台解析：平台也算进键里\n  const key = `${isApplePlatform() ? 'apple' : 'other'}:${combo}`;\n  let hotkey = parsed.get(key);\n  if (!hotkey) parsed.set(key, (hotkey = parse(combo)));\n  return hotkey;\n}\n\nfunction parse(combo: string): Hotkey {\n  const parts = combo.split('+').map((part) => part.trim());\n  // 'Mod++' 这类以加号为键的写法：split 后末尾是两个空串\n  const name = (combo.endsWith('++') ? '+' : parts.pop()!).toLowerCase();\n  const key = KEY_ALIASES[name] ?? name;\n  const modifiers = new Set(parts.filter(Boolean).map((part) => part.toLowerCase()));\n  const apple = isApplePlatform();\n  return {\n    key,\n    ctrl: modifiers.has('ctrl') || (modifiers.has('mod') && !apple),\n    alt: modifiers.has('alt') || modifiers.has('option'),\n    shift: modifiers.has('shift'),\n    meta: modifiers.has('meta') || modifiers.has('cmd') || (modifiers.has('mod') && apple),\n  };\n}\n\n/** 事件是否匹配这个快捷键 */\nexport function matchesHotkey(event: KeyboardEvent, combo: string | Hotkey): boolean {\n  const hotkey = typeof combo === 'string' ? parseHotkey(combo) : combo;\n  const letter = /^[a-z]$/.test(hotkey.key);\n  const symbol = hotkey.key.length === 1 && !letter && !/^\\d$/.test(hotkey.key);\n  if (\n    event.ctrlKey !== hotkey.ctrl ||\n    event.altKey !== hotkey.alt ||\n    event.metaKey !== hotkey.meta\n  ) {\n    return false;\n  }\n  if (!symbol && event.shiftKey !== hotkey.shift) return false;\n  const key = event.key.toLowerCase();\n  return key === hotkey.key || (letter && event.code === `Key${hotkey.key.toUpperCase()}`);\n}\n\n// 小写的键名 → KeyboardEvent.key 的写法（多个单词的每个词首字母大写）\nconst KEY_NAMES: Record<string, string> = {\n  ' ': 'Space',\n  arrowup: 'ArrowUp',\n  arrowdown: 'ArrowDown',\n  arrowleft: 'ArrowLeft',\n  arrowright: 'ArrowRight',\n  pageup: 'PageUp',\n  pagedown: 'PageDown',\n};\nconst keyName = (key: string) =>\n  KEY_NAMES[key] ??\n  (key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1));\nconst modifiersOf = (hotkey: Hotkey) =>\n  (['ctrl', 'alt', 'shift', 'meta'] as const).filter((name) => hotkey[name]);\n\nconst SYMBOLS: Record<string, string> = { ctrl: '⌃', alt: '⌥', shift: '⇧', meta: '⌘' };\nconst ARROWS: Record<string, string> = {\n  ArrowUp: '↑',\n  ArrowDown: '↓',\n  ArrowLeft: '←',\n  ArrowRight: '→',\n};\n\n/** 快捷键的显示文字：macOS 上用符号（⌘⇧K），其他系统用 Ctrl+Shift+K；方向键显示成箭头 */\nexport function formatHotkey(combo: string): string {\n  return combo.trim().split(/\\s+/).map(formatStep).join(' ');\n}\n\nfunction formatStep(combo: string): string {\n  const hotkey = parseHotkey(combo);\n  const key = keyName(hotkey.key);\n  const shown = ARROWS[key] ?? key;\n  if (isApplePlatform())\n    return (\n      modifiersOf(hotkey)\n        .map((name) => SYMBOLS[name])\n        .join('') + shown\n    );\n  const names = { ctrl: 'Ctrl', alt: 'Alt', shift: 'Shift', meta: 'Win' };\n  return [...modifiersOf(hotkey).map((name) => names[name]), shown].join('+');\n}\n\n/**\n * 快捷键的 aria-keyshortcuts 写法（读屏念出来）：'Mod+K' → 'Control+K'，macOS 上 'Meta+K'。\n * 显示快捷键的 Kbd 对读屏隐藏、改由这个属性提供时，按钮的名称与看得见的文字才对得上。\n * 序列键（'G I'）表达不了（aria-keyshortcuts 里空格表示“或”）：返回 undefined，显示的文字就别对读屏隐藏\n */\nexport function ariaKeyShortcut(combo: string): string | undefined {\n  if (/\\s/.test(combo.trim())) return undefined;\n  const hotkey = parseHotkey(combo);\n  const names = { ctrl: 'Control', alt: 'Alt', shift: 'Shift', meta: 'Meta' };\n  return [...modifiersOf(hotkey).map((name) => names[name]), keyName(hotkey.key)].join('+');\n}\n\n/**\n * 这次按键属于输入法的组合输入（拼音选词时的回车、方向键、空格）：快捷键与列表的键盘操作都不该处理它。\n * Chrome、Firefox 组合中是 isComposing；Safari 先派发 compositionend、再派发确认用的 keydown，只能看 keyCode 229\n */\nexport function isComposingKey(event: KeyboardEvent): boolean {\n  return event.isComposing || event.keyCode === 229;\n}\n\n/** 事件目标是不是可编辑的元素（输入框、文本域、下拉、contenteditable）：方向键、字母键这时留给它 */\nexport function isEditable(target: EventTarget | null): boolean {\n  if (!(target instanceof HTMLElement)) return false;\n  return target.isContentEditable || /^(input|textarea|select)$/i.test(target.tagName);\n}\n\n/** 序列键两次按键之间最多隔多久（毫秒） */\nconst SEQUENCE_TIMEOUT = 1500;\n\n/** 注册快捷键（在 setup 里调用）；read 在按键时读取，处理函数总是最新的 */\nexport function useHotkeys(\n  read: () => HotkeyMap,\n  { inInputs = false, target }: HotkeyOptions = {},\n): void {\n  if (typeof document === 'undefined') return;\n  // 最近的按键（序列键用）：超过时限的丢掉\n  let recent: { event: KeyboardEvent; at: number }[] = [];\n  const onKeydown = (event: KeyboardEvent) => {\n    if (isComposingKey(event) || event.defaultPrevented) return;\n    if (!inInputs && isEditable(event.target)) return;\n    // 页面级的快捷键：模态对话框打开时只认对话框里的按键\n    const modal = topModal();\n    if (!target && modal && !(event.target instanceof Node && modal.contains(event.target))) return;\n    const now = performance.now();\n    recent = [\n      ...recent.filter((item) => now - item.at < SEQUENCE_TIMEOUT),\n      { event, at: now },\n    ].slice(-4);\n    const entries = Object.entries(read()).map(([combo, handler]) => ({\n      steps: combo.trim().split(/\\s+/),\n      handler,\n    }));\n    // 序列比单键优先：'G I' 按完时不再触发单独的 'I'\n    entries.sort((a, b) => b.steps.length - a.steps.length);\n    for (const { steps, handler } of entries) {\n      const tail = recent.slice(-steps.length);\n      if (tail.length < steps.length) continue;\n      if (!steps.every((step, index) => matchesHotkey(tail[index]!.event, step))) continue;\n      event.preventDefault();\n      recent = [];\n      handler(event);\n      return;\n    }\n  };\n  useEventListener(target ?? document, 'keydown', onKeydown);\n}\n"],"mappings":"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"}

package/dist/utils/dom/hover-intent.d.ts

@@ -0,0 +1,47 @@
+import type { OpenChangeReasons, SetOpen } from './open-change';
+/** 一组悬停浮层共用的状态：正在显示的那个与上次关闭的时间 */
+export interface HoverGroup {
+    /** 正在显示的那个（同一时间只显示一个） */
+    shown: {
+        close: () => void;
+    } | undefined;
+    /** 上次关闭的时间（毫秒时间戳） */
+    lastClosed: number;
+    /** 刚关掉一个后多久之内，下一个直接打开（毫秒） */
+    readonly skipDelay: number;
+}
+/** 新建一组悬停浮层；skipDelay 默认 300（同 Radix 的 skipDelayDuration） */
+export declare function createHoverGroup(skipDelay?: number): HoverGroup;
+/** useHoverIntent 每次读取的选项 */
+export interface HoverIntentOptions {
+    /** 指针停留多久后打开（毫秒） */
+    delay: number;
+    /** 指针离开多久后关闭（毫秒）：留出移到浮层上的时间 */
+    closeDelay: number;
+    /** 不打开 */
+    disabled?: boolean;
+}
+/** useHoverIntent 的返回值 */
+export interface HoverIntent {
+    /** 展开到触发器上的事件 */
+    readonly trigger: {
+        onPointerenter: (event: PointerEvent) => void;
+        onPointerleave: (event: PointerEvent) => void;
+        onPointerdown: (event: PointerEvent) => void;
+        onFocus: (event: FocusEvent) => void;
+        onBlur: (event: FocusEvent) => void;
+    };
+    /** 展开到浮层上的事件：指针移到浮层上不关闭，离开浮层后再关闭 */
+    readonly panel: {
+        onPointerenter: () => void;
+        onPointerleave: (event: PointerEvent) => void;
+    };
+    /** 立即关闭：Esc、焦点离开 */
+    closeNow(reason: keyof OpenChangeReasons, event?: Event): void;
+    /** 浮层显示了：关掉同组正显示的另一个 */
+    opened(): void;
+    /** 浮层隐藏了：记下时间，供下一个跳过延迟 */
+    closed(): void;
+}
+/** 悬停、聚焦打开的时机（在 setup 里调用）；setOpen 写组件的 open 并带上原因（hover、focus、trigger） */
+export declare function useHoverIntent(group: HoverGroup, read: () => HoverIntentOptions, setOpen: SetOpen): HoverIntent;

package/dist/utils/dom/hover-intent.js

@@ -0,0 +1,72 @@
+import { onScopeDispose } from "vue";
+//#region src/utils/dom/hover-intent.ts
+/**
+* 悬停浮层的开关时机（Tooltip、HoverCard 共用）：指针停留 delay 后打开，离开 closeDelay 后关闭（可以移到浮层上），
+* 键盘聚焦（:focus-visible）立即打开，按下触发器、失焦时关闭，触屏不打开（没有悬停）。
+* 同一组（createHoverGroup）里同一时间只开一个；刚关掉一个（skipDelay 内）时下一个直接打开，在一排触发器上移动不用每次等。
+*
+*   const tooltips = createHoverGroup();              // 模块级：所有 Tooltip 一组
+*   const hover = useHoverIntent(tooltips, () => ({ delay, closeDelay: 100, disabled }), setOpen);   // setOpen 见 openSetter
+*   trigger({ ...hover.trigger }) / <div {...hover.panel}>
+*   hover.opened() / hover.closed()                   // 浮层真的显示、隐藏时告诉组（关掉同组的另一个、记下关闭时间）
+*/
+/** 新建一组悬停浮层；skipDelay 默认 300（同 Radix 的 skipDelayDuration） */
+function createHoverGroup(skipDelay = 300) {
+	return {
+		shown: void 0,
+		lastClosed: 0,
+		skipDelay
+	};
+}
+/** 悬停、聚焦打开的时机（在 setup 里调用）；setOpen 写组件的 open 并带上原因（hover、focus、trigger） */
+function useHoverIntent(group, read, setOpen) {
+	let timer;
+	let visible = false;
+	const self = { close: () => setOpen(false, "hover") };
+	function schedule(next, wait, reason, event) {
+		clearTimeout(timer);
+		if (wait <= 0) setOpen(next, reason, event);
+		else timer = setTimeout(() => setOpen(next, reason, event), wait);
+	}
+	const warm = () => group.shown != null || Date.now() - group.lastClosed < group.skipDelay;
+	const closeSoon = (event) => schedule(false, read().closeDelay, "hover", event);
+	const closeNow = (reason, event) => schedule(false, 0, reason, event);
+	onScopeDispose(() => {
+		clearTimeout(timer);
+		if (group.shown === self) group.shown = void 0;
+	});
+	return {
+		trigger: {
+			onPointerenter(event) {
+				if (read().disabled || event.pointerType === "touch") return;
+				schedule(true, warm() ? 0 : read().delay, "hover", event);
+			},
+			onPointerleave: closeSoon,
+			onPointerdown: (event) => closeNow("trigger", event),
+			onFocus(event) {
+				if (read().disabled) return;
+				if (event.target.matches(":focus-visible")) schedule(true, 0, "focus", event);
+			},
+			onBlur: (event) => closeNow("focus", event)
+		},
+		panel: {
+			onPointerenter: () => clearTimeout(timer),
+			onPointerleave: closeSoon
+		},
+		closeNow,
+		opened() {
+			visible = true;
+			if (group.shown !== self) group.shown?.close();
+			group.shown = self;
+		},
+		closed() {
+			if (visible) group.lastClosed = Date.now();
+			visible = false;
+			if (group.shown === self) group.shown = void 0;
+		}
+	};
+}
+//#endregion
+export { createHoverGroup, useHoverIntent };
+
+//# sourceMappingURL=hover-intent.js.map

package/dist/utils/dom/hover-intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hover-intent.js","names":[],"sources":["../../../src/utils/dom/hover-intent.ts"],"sourcesContent":["/**\n * 悬停浮层的开关时机（Tooltip、HoverCard 共用）：指针停留 delay 后打开，离开 closeDelay 后关闭（可以移到浮层上），\n * 键盘聚焦（:focus-visible）立即打开，按下触发器、失焦时关闭，触屏不打开（没有悬停）。\n * 同一组（createHoverGroup）里同一时间只开一个；刚关掉一个（skipDelay 内）时下一个直接打开，在一排触发器上移动不用每次等。\n *\n *   const tooltips = createHoverGroup();              // 模块级：所有 Tooltip 一组\n *   const hover = useHoverIntent(tooltips, () => ({ delay, closeDelay: 100, disabled }), setOpen);   // setOpen 见 openSetter\n *   trigger({ ...hover.trigger }) / <div {...hover.panel}>\n *   hover.opened() / hover.closed()                   // 浮层真的显示、隐藏时告诉组（关掉同组的另一个、记下关闭时间）\n */\nimport { onScopeDispose } from 'vue';\nimport type { OpenChangeReasons, SetOpen } from './open-change';\n\n/** 一组悬停浮层共用的状态：正在显示的那个与上次关闭的时间 */\nexport interface HoverGroup {\n  /** 正在显示的那个（同一时间只显示一个） */\n  shown: { close: () => void } | undefined;\n  /** 上次关闭的时间（毫秒时间戳） */\n  lastClosed: number;\n  /** 刚关掉一个后多久之内，下一个直接打开（毫秒） */\n  readonly skipDelay: number;\n}\n\n/** 新建一组悬停浮层；skipDelay 默认 300（同 Radix 的 skipDelayDuration） */\nexport function createHoverGroup(skipDelay = 300): HoverGroup {\n  return { shown: undefined, lastClosed: 0, skipDelay };\n}\n\n/** useHoverIntent 每次读取的选项 */\nexport interface HoverIntentOptions {\n  /** 指针停留多久后打开（毫秒） */\n  delay: number;\n  /** 指针离开多久后关闭（毫秒）：留出移到浮层上的时间 */\n  closeDelay: number;\n  /** 不打开 */\n  disabled?: boolean;\n}\n\n/** useHoverIntent 的返回值 */\nexport interface HoverIntent {\n  /** 展开到触发器上的事件 */\n  readonly trigger: {\n    onPointerenter: (event: PointerEvent) => void;\n    onPointerleave: (event: PointerEvent) => void;\n    onPointerdown: (event: PointerEvent) => void;\n    onFocus: (event: FocusEvent) => void;\n    onBlur: (event: FocusEvent) => void;\n  };\n  /** 展开到浮层上的事件：指针移到浮层上不关闭，离开浮层后再关闭 */\n  readonly panel: {\n    onPointerenter: () => void;\n    onPointerleave: (event: PointerEvent) => void;\n  };\n  /** 立即关闭：Esc、焦点离开 */\n  closeNow(reason: keyof OpenChangeReasons, event?: Event): void;\n  /** 浮层显示了：关掉同组正显示的另一个 */\n  opened(): void;\n  /** 浮层隐藏了：记下时间，供下一个跳过延迟 */\n  closed(): void;\n}\n\n/** 悬停、聚焦打开的时机（在 setup 里调用）；setOpen 写组件的 open 并带上原因（hover、focus、trigger） */\nexport function useHoverIntent(\n  group: HoverGroup,\n  read: () => HoverIntentOptions,\n  setOpen: SetOpen,\n): HoverIntent {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let visible = false;\n  // 同组的另一个打开了：算指针移走\n  const self = { close: () => setOpen(false, 'hover') };\n\n  function schedule(next: boolean, wait: number, reason: keyof OpenChangeReasons, event?: Event) {\n    clearTimeout(timer);\n    if (wait <= 0) setOpen(next, reason, event);\n    else timer = setTimeout(() => setOpen(next, reason, event), wait);\n  }\n  const warm = () => group.shown != null || Date.now() - group.lastClosed < group.skipDelay;\n  const closeSoon = (event: PointerEvent) => schedule(false, read().closeDelay, 'hover', event);\n  const closeNow = (reason: keyof OpenChangeReasons, event?: Event) =>\n    schedule(false, 0, reason, event);\n\n  onScopeDispose(() => {\n    clearTimeout(timer);\n    if (group.shown === self) group.shown = undefined;\n  });\n\n  return {\n    trigger: {\n      onPointerenter(event) {\n        if (read().disabled || event.pointerType === 'touch') return;\n        schedule(true, warm() ? 0 : read().delay, 'hover', event);\n      },\n      onPointerleave: closeSoon,\n      onPointerdown: (event) => closeNow('trigger', event),\n      onFocus(event) {\n        if (read().disabled) return;\n        // 只在键盘聚焦时打开；点击聚焦（按钮被按下）时不打开\n        if ((event.target as Element).matches(':focus-visible')) schedule(true, 0, 'focus', event);\n      },\n      onBlur: (event) => closeNow('focus', event),\n    },\n    panel: {\n      onPointerenter: () => clearTimeout(timer),\n      onPointerleave: closeSoon,\n    },\n    closeNow,\n    opened() {\n      visible = true;\n      if (group.shown !== self) group.shown?.close();\n      group.shown = self;\n    },\n    closed() {\n      if (visible) group.lastClosed = Date.now();\n      visible = false;\n      if (group.shown === self) group.shown = undefined;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;AAwBA,SAAgB,iBAAiB,YAAY,KAAiB;CAC5D,OAAO;EAAE,OAAO,KAAA;EAAW,YAAY;EAAG;CAAU;AACtD;;AAoCA,SAAgB,eACd,OACA,MACA,SACa;CACb,IAAI;CACJ,IAAI,UAAU;CAEd,MAAM,OAAO,EAAE,aAAa,QAAQ,OAAO,OAAO,EAAE;CAEpD,SAAS,SAAS,MAAe,MAAc,QAAiC,OAAe;EAC7F,aAAa,KAAK;EAClB,IAAI,QAAQ,GAAG,QAAQ,MAAM,QAAQ,KAAK;OACrC,QAAQ,iBAAiB,QAAQ,MAAM,QAAQ,KAAK,GAAG,IAAI;CAClE;CACA,MAAM,aAAa,MAAM,SAAS,QAAQ,KAAK,IAAI,IAAI,MAAM,aAAa,MAAM;CAChF,MAAM,aAAa,UAAwB,SAAS,OAAO,KAAK,CAAC,CAAC,YAAY,SAAS,KAAK;CAC5F,MAAM,YAAY,QAAiC,UACjD,SAAS,OAAO,GAAG,QAAQ,KAAK;CAElC,qBAAqB;EACnB,aAAa,KAAK;EAClB,IAAI,MAAM,UAAU,MAAM,MAAM,QAAQ,KAAA;CAC1C,CAAC;CAED,OAAO;EACL,SAAS;GACP,eAAe,OAAO;IACpB,IAAI,KAAK,CAAC,CAAC,YAAY,MAAM,gBAAgB,SAAS;IACtD,SAAS,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,OAAO,SAAS,KAAK;GAC1D;GACA,gBAAgB;GAChB,gBAAgB,UAAU,SAAS,WAAW,KAAK;GACnD,QAAQ,OAAO;IACb,IAAI,KAAK,CAAC,CAAC,UAAU;IAErB,IAAK,MAAM,OAAmB,QAAQ,gBAAgB,GAAG,SAAS,MAAM,GAAG,SAAS,KAAK;GAC3F;GACA,SAAS,UAAU,SAAS,SAAS,KAAK;EAC5C;EACA,OAAO;GACL,sBAAsB,aAAa,KAAK;GACxC,gBAAgB;EAClB;EACA;EACA,SAAS;GACP,UAAU;GACV,IAAI,MAAM,UAAU,MAAM,MAAM,OAAO,MAAM;GAC7C,MAAM,QAAQ;EAChB;EACA,SAAS;GACP,IAAI,SAAS,MAAM,aAAa,KAAK,IAAI;GACzC,UAAU;GACV,IAAI,MAAM,UAAU,MAAM,MAAM,QAAQ,KAAA;EAC1C;CACF;AACF"}

package/dist/utils/dom/hover-layer.d.ts

@@ -0,0 +1,36 @@
+import { type PartProps } from '../props';
+import { type FloatingPlacement } from './floating';
+import { type HoverGroup, type HoverIntent } from './hover-intent';
+import type { SetOpen } from './open-change';
+/** useHoverLayer 每次读取的选项 */
+export interface HoverLayerOptions {
+    /** 是否打开 */
+    open: boolean;
+    /** 不打开（触发器照常渲染） */
+    disabled: boolean;
+    /** 弹出位置 */
+    placement: FloatingPlacement;
+    /** 与触发器的距离 */
+    offset?: number;
+    /** 指针停留多久后打开（毫秒） */
+    delay: number;
+    /** 指针离开多久后关闭（毫秒）：留出移到浮层上的时间 */
+    closeDelay: number;
+}
+/** useHoverLayer 的返回值 */
+export interface HoverLayer {
+    /** 面板的 id：Tooltip 给触发器的 aria-describedby */
+    readonly id: string;
+    /** 开关时机：trigger 展开到触发器上，panel 展开到面板上 */
+    readonly hover: HoverIntent;
+    /** 触发器元素的 ref（定位的参照） */
+    anchorRef: (element: unknown) => void;
+    /** 面板元素的 ref */
+    panelRef: (element: unknown) => void;
+    /** 箭头节点的属性：样式、ref、对读屏隐藏，使用方的 propsArrow 合进去 */
+    arrowProps: (propsArrow?: PartProps<'span'>) => Record<string, unknown>;
+    /** 元素在触发器或面板里：焦点在两者之间移动时不关 */
+    contains: (target: EventTarget | null) => boolean;
+}
+/** 悬停浮层：停留后打开、锚定到触发器、Esc 关闭 */
+export declare function useHoverLayer(group: HoverGroup, read: () => HoverLayerOptions, setOpen: SetOpen): HoverLayer;

package/dist/utils/dom/hover-layer.js

@@ -0,0 +1,74 @@
+import { mergeAttrs } from "../props.js";
+import { toElement } from "./element.js";
+import { createAnchoredLayer, floatingStyles } from "./floating.js";
+import { useHoverIntent } from "./hover-intent.js";
+import { onScopeDispose, shallowRef, useId, watchEffect } from "vue";
+//#region src/utils/dom/hover-layer.ts
+/**
+* 悬停浮层的壳：Tooltip 与 HoverCard 共用。触发器、面板、箭头三个元素，停留后打开（useHoverIntent），
+* 打开时锚定到触发器（createAnchoredLayer），Esc 关闭，卸载时收起。在 setup 里调用。
+*
+*   const layer = useHoverLayer(tooltips, () => ({ open, disabled, placement, offset, delay, closeDelay }), setOpen);
+*   trigger({ ref: layer.anchorRef, ...layer.hover.trigger })
+*   <div {...mergeAttrs({ sx }, rest, { ref: layer.panelRef, id: layer.id, popover: 'manual', ...layer.hover.panel })}>
+*     {children}
+*     {arrow && <span {...layer.arrowProps(propsArrow)} />}
+*   </div>
+*
+* 面板用 popover="manual"：不是 auto，不会关掉正打开的菜单或弹出框；manual 没有原生的 Esc，所以这里处理。
+*/
+/** 悬停浮层：停留后打开、锚定到触发器、Esc 关闭 */
+function useHoverLayer(group, read, setOpen) {
+	const id = useId();
+	const anchor = shallowRef(null);
+	const panel = shallowRef(null);
+	const arrow = shallowRef(null);
+	const layer = createAnchoredLayer();
+	const hover = useHoverIntent(group, () => {
+		const { delay, closeDelay, disabled } = read();
+		return {
+			delay,
+			closeDelay,
+			disabled
+		};
+	}, setOpen);
+	function onKeydown(event) {
+		if (event.key !== "Escape" || !read().open) return;
+		event.preventDefault();
+		event.stopPropagation();
+		hover.closeNow("escape", event);
+	}
+	watchEffect((onCleanup) => {
+		const { open, disabled, placement, offset } = read();
+		if (!open || disabled) {
+			layer.hide({ restoreFocus: false });
+			hover.closed();
+			return;
+		}
+		if (!anchor.value || !panel.value) return;
+		hover.opened();
+		layer.show(anchor.value, panel.value, {
+			placement,
+			offset,
+			arrow: arrow.value
+		});
+		document.addEventListener("keydown", onKeydown, true);
+		onCleanup(() => document.removeEventListener("keydown", onKeydown, true));
+	}, { flush: "post" });
+	onScopeDispose(() => layer.hide({ restoreFocus: false }));
+	return {
+		id,
+		hover,
+		anchorRef: (element) => anchor.value = toElement(element),
+		panelRef: (element) => panel.value = toElement(element),
+		arrowProps: (propsArrow) => mergeAttrs({ sx: floatingStyles.arrow }, propsArrow, {
+			ref: (element) => arrow.value = toElement(element),
+			"aria-hidden": true
+		}),
+		contains: (target) => target instanceof Node && !!(anchor.value?.contains(target) || panel.value?.contains(target))
+	};
+}
+//#endregion
+export { useHoverLayer };
+
+//# sourceMappingURL=hover-layer.js.map

package/dist/utils/dom/hover-layer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hover-layer.js","names":[],"sources":["../../../src/utils/dom/hover-layer.ts"],"sourcesContent":["/**\n * 悬停浮层的壳：Tooltip 与 HoverCard 共用。触发器、面板、箭头三个元素，停留后打开（useHoverIntent），\n * 打开时锚定到触发器（createAnchoredLayer），Esc 关闭，卸载时收起。在 setup 里调用。\n *\n *   const layer = useHoverLayer(tooltips, () => ({ open, disabled, placement, offset, delay, closeDelay }), setOpen);\n *   trigger({ ref: layer.anchorRef, ...layer.hover.trigger })\n *   <div {...mergeAttrs({ sx }, rest, { ref: layer.panelRef, id: layer.id, popover: 'manual', ...layer.hover.panel })}>\n *     {children}\n *     {arrow && <span {...layer.arrowProps(propsArrow)} />}\n *   </div>\n *\n * 面板用 popover=\"manual\"：不是 auto，不会关掉正打开的菜单或弹出框；manual 没有原生的 Esc，所以这里处理。\n */\nimport { onScopeDispose, shallowRef, useId, watchEffect } from 'vue';\nimport { mergeAttrs, type PartProps } from '../props';\nimport { createAnchoredLayer, floatingStyles, type FloatingPlacement } from './floating';\nimport { useHoverIntent, type HoverGroup, type HoverIntent } from './hover-intent';\nimport type { SetOpen } from './open-change';\nimport { toElement } from './element';\n\n/** useHoverLayer 每次读取的选项 */\nexport interface HoverLayerOptions {\n  /** 是否打开 */\n  open: boolean;\n  /** 不打开（触发器照常渲染） */\n  disabled: boolean;\n  /** 弹出位置 */\n  placement: FloatingPlacement;\n  /** 与触发器的距离 */\n  offset?: number;\n  /** 指针停留多久后打开（毫秒） */\n  delay: number;\n  /** 指针离开多久后关闭（毫秒）：留出移到浮层上的时间 */\n  closeDelay: number;\n}\n\n/** useHoverLayer 的返回值 */\nexport interface HoverLayer {\n  /** 面板的 id：Tooltip 给触发器的 aria-describedby */\n  readonly id: string;\n  /** 开关时机：trigger 展开到触发器上，panel 展开到面板上 */\n  readonly hover: HoverIntent;\n  /** 触发器元素的 ref（定位的参照） */\n  anchorRef: (element: unknown) => void;\n  /** 面板元素的 ref */\n  panelRef: (element: unknown) => void;\n  /** 箭头节点的属性：样式、ref、对读屏隐藏，使用方的 propsArrow 合进去 */\n  arrowProps: (propsArrow?: PartProps<'span'>) => Record<string, unknown>;\n  /** 元素在触发器或面板里：焦点在两者之间移动时不关 */\n  contains: (target: EventTarget | null) => boolean;\n}\n\n/** 悬停浮层：停留后打开、锚定到触发器、Esc 关闭 */\nexport function useHoverLayer(\n  group: HoverGroup,\n  read: () => HoverLayerOptions,\n  setOpen: SetOpen,\n): HoverLayer {\n  const id = useId();\n  const anchor = shallowRef<HTMLElement | null>(null);\n  const panel = shallowRef<HTMLElement | null>(null);\n  const arrow = shallowRef<HTMLElement | null>(null);\n  const layer = createAnchoredLayer();\n  const hover = useHoverIntent(\n    group,\n    () => {\n      const { delay, closeDelay, disabled } = read();\n      return { delay, closeDelay, disabled };\n    },\n    setOpen,\n  );\n\n  // 浮层在对话框里时只关浮层，不让同一次 Esc 关掉对话框\n  function onKeydown(event: KeyboardEvent) {\n    if (event.key !== 'Escape' || !read().open) return;\n    event.preventDefault();\n    event.stopPropagation();\n    hover.closeNow('escape', event);\n  }\n\n  watchEffect(\n    (onCleanup) => {\n      const { open, disabled, placement, offset } = read();\n      if (!open || disabled) {\n        layer.hide({ restoreFocus: false });\n        hover.closed();\n        return;\n      }\n      if (!anchor.value || !panel.value) return;\n      hover.opened();\n      void layer.show(anchor.value, panel.value, { placement, offset, arrow: arrow.value });\n      document.addEventListener('keydown', onKeydown, true);\n      onCleanup(() => document.removeEventListener('keydown', onKeydown, true));\n    },\n    { flush: 'post' },\n  );\n  onScopeDispose(() => layer.hide({ restoreFocus: false }));\n\n  return {\n    id,\n    hover,\n    anchorRef: (element) => (anchor.value = toElement(element)),\n    panelRef: (element) => (panel.value = toElement(element)),\n    arrowProps: (propsArrow) =>\n      mergeAttrs<'span'>({ sx: floatingStyles.arrow }, propsArrow, {\n        ref: (element: unknown) => (arrow.value = toElement(element)),\n        'aria-hidden': true,\n      }),\n    contains: (target) =>\n      target instanceof Node && !!(anchor.value?.contains(target) || panel.value?.contains(target)),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqDA,SAAgB,cACd,OACA,MACA,SACY;CACZ,MAAM,KAAK,MAAM;CACjB,MAAM,SAAS,WAA+B,IAAI;CAClD,MAAM,QAAQ,WAA+B,IAAI;CACjD,MAAM,QAAQ,WAA+B,IAAI;CACjD,MAAM,QAAQ,oBAAoB;CAClC,MAAM,QAAQ,eACZ,aACM;EACJ,MAAM,EAAE,OAAO,YAAY,aAAa,KAAK;EAC7C,OAAO;GAAE;GAAO;GAAY;EAAS;CACvC,GACA,OACF;CAGA,SAAS,UAAU,OAAsB;EACvC,IAAI,MAAM,QAAQ,YAAY,CAAC,KAAK,CAAC,CAAC,MAAM;EAC5C,MAAM,eAAe;EACrB,MAAM,gBAAgB;EACtB,MAAM,SAAS,UAAU,KAAK;CAChC;CAEA,aACG,cAAc;EACb,MAAM,EAAE,MAAM,UAAU,WAAW,WAAW,KAAK;EACnD,IAAI,CAAC,QAAQ,UAAU;GACrB,MAAM,KAAK,EAAE,cAAc,MAAM,CAAC;GAClC,MAAM,OAAO;GACb;EACF;EACA,IAAI,CAAC,OAAO,SAAS,CAAC,MAAM,OAAO;EACnC,MAAM,OAAO;EACb,MAAW,KAAK,OAAO,OAAO,MAAM,OAAO;GAAE;GAAW;GAAQ,OAAO,MAAM;EAAM,CAAC;EACpF,SAAS,iBAAiB,WAAW,WAAW,IAAI;EACpD,gBAAgB,SAAS,oBAAoB,WAAW,WAAW,IAAI,CAAC;CAC1E,GACA,EAAE,OAAO,OAAO,CAClB;CACA,qBAAqB,MAAM,KAAK,EAAE,cAAc,MAAM,CAAC,CAAC;CAExD,OAAO;EACL;EACA;EACA,YAAY,YAAa,OAAO,QAAQ,UAAU,OAAO;EACzD,WAAW,YAAa,MAAM,QAAQ,UAAU,OAAO;EACvD,aAAa,eACX,WAAmB,EAAE,IAAI,eAAe,MAAM,GAAG,YAAY;GAC3D,MAAM,YAAsB,MAAM,QAAQ,UAAU,OAAO;GAC3D,eAAe;EACjB,CAAC;EACH,WAAW,WACT,kBAAkB,QAAQ,CAAC,EAAE,OAAO,OAAO,SAAS,MAAM,KAAK,MAAM,OAAO,SAAS,MAAM;CAC/F;AACF"}

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

@@ -0,0 +1,13 @@
+type Target = Element | null | undefined;
+/** 观察选项，同 IntersectionObserver */
+export interface IntersectionOptions {
+    /** 相交的参照：滚动容器；不写时是视口 */
+    root?: Element | Document | null;
+    /** 参照边界向外扩展，写法同 CSS 的 margin：`'0px 0px 200px'` 提前 200px 算作进入 */
+    rootMargin?: string;
+    /** 在哪些可见比例上回调：0 是进出，1 是完整可见 */
+    threshold?: number | number[];
+}
+/** 观察一个或几个元素与参照的相交；targets 与 options 在渲染后读取，读到 null 的目标跳过 */
+export declare function useIntersectionObserver(targets: () => Target | readonly Target[], onChange: (entries: IntersectionObserverEntry[]) => void, options?: () => IntersectionOptions): void;
+export {};

package/dist/utils/dom/intersection.js

@@ -0,0 +1,36 @@
+import { watch } from "vue";
+//#region src/utils/dom/intersection.ts
+/**
+* 元素与视口（或滚动容器）的相交变化时回调（IntersectionObserver）：目标或选项变了重建观察器，卸载时断开。
+* 在 setup 里调用。
+*
+*   // 吸底的栏没有完整可见，说明盖着下面的内容
+*   useIntersectionObserver(() => root, ([entry]) => (stuck = entry!.intersectionRatio < 1), () => ({
+*     threshold: [0, 1],
+*   }));
+*
+* 没有 IntersectionObserver 的环境（服务端、部分测试环境）什么也不做，调用方自己决定这时当作可见还是不可见。
+*/
+/** 观察一个或几个元素与参照的相交；targets 与 options 在渲染后读取，读到 null 的目标跳过 */
+function useIntersectionObserver(targets, onChange, options = () => ({})) {
+	watch(() => ({
+		elements: [targets()].flat().filter((element) => element != null),
+		...options()
+	}), ({ elements, root, rootMargin, threshold }, _, onCleanup) => {
+		if (!elements.length || typeof IntersectionObserver === "undefined") return;
+		const observer = new IntersectionObserver((entries) => onChange(entries), {
+			root,
+			rootMargin,
+			threshold
+		});
+		for (const element of elements) observer.observe(element);
+		onCleanup(() => observer.disconnect());
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+}
+//#endregion
+export { useIntersectionObserver };
+
+//# sourceMappingURL=intersection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"intersection.js","names":[],"sources":["../../../src/utils/dom/intersection.ts"],"sourcesContent":["/**\n * 元素与视口（或滚动容器）的相交变化时回调（IntersectionObserver）：目标或选项变了重建观察器，卸载时断开。\n * 在 setup 里调用。\n *\n *   // 吸底的栏没有完整可见，说明盖着下面的内容\n *   useIntersectionObserver(() => root, ([entry]) => (stuck = entry!.intersectionRatio < 1), () => ({\n *     threshold: [0, 1],\n *   }));\n *\n * 没有 IntersectionObserver 的环境（服务端、部分测试环境）什么也不做，调用方自己决定这时当作可见还是不可见。\n */\nimport { watch } from 'vue';\n\ntype Target = Element | null | undefined;\n\n/** 观察选项，同 IntersectionObserver */\nexport interface IntersectionOptions {\n  /** 相交的参照：滚动容器；不写时是视口 */\n  root?: Element | Document | null;\n  /** 参照边界向外扩展，写法同 CSS 的 margin：`'0px 0px 200px'` 提前 200px 算作进入 */\n  rootMargin?: string;\n  /** 在哪些可见比例上回调：0 是进出，1 是完整可见 */\n  threshold?: number | number[];\n}\n\n/** 观察一个或几个元素与参照的相交；targets 与 options 在渲染后读取，读到 null 的目标跳过 */\nexport function useIntersectionObserver(\n  targets: () => Target | readonly Target[],\n  onChange: (entries: IntersectionObserverEntry[]) => void,\n  options: () => IntersectionOptions = () => ({}),\n): void {\n  watch(\n    () => ({\n      elements: [targets()].flat().filter((element): element is Element => element != null),\n      ...options(),\n    }),\n    ({ elements, root, rootMargin, threshold }, _, onCleanup) => {\n      if (!elements.length || typeof IntersectionObserver === 'undefined') return;\n      const observer = new IntersectionObserver((entries) => onChange(entries), {\n        root,\n        rootMargin,\n        threshold,\n      });\n      for (const element of elements) observer.observe(element);\n      onCleanup(() => observer.disconnect());\n    },\n    { immediate: true, flush: 'post' },\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;AA0BA,SAAgB,wBACd,SACA,UACA,iBAA4C,CAAC,IACvC;CACN,aACS;EACL,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,QAAQ,YAAgC,WAAW,IAAI;EACpF,GAAG,QAAQ;CACb,KACC,EAAE,UAAU,MAAM,YAAY,aAAa,GAAG,cAAc;EAC3D,IAAI,CAAC,SAAS,UAAU,OAAO,yBAAyB,aAAa;EACrE,MAAM,WAAW,IAAI,sBAAsB,YAAY,SAAS,OAAO,GAAG;GACxE;GACA;GACA;EACF,CAAC;EACD,KAAK,MAAM,WAAW,UAAU,SAAS,QAAQ,OAAO;EACxD,gBAAgB,SAAS,WAAW,CAAC;CACvC,GACA;EAAE,WAAW;EAAM,OAAO;CAAO,CACnC;AACF"}

package/dist/utils/dom/layout-batch.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 先读后写：当前任务里登记的读取在一个微任务里依次执行，全部读完再依次执行它们返回的写入。
+ * 各组件挂载后、尺寸变化时各自“读布局 → 写样式”，一个写完下一个读就要重新布局；
+ * 合并后一整轮只布局一次（同 fastdom 的 measure / mutate）。
+ *
+ *   batchLayout(() => {
+ *     const width = item.offsetWidth;                      // 读
+ *     return () => (bar.style.width = `${width}px`);       // 写
+ *   });
+ */
+type Read = () => (() => void) | void;
+/** 登记一次读取（返回写入）：这一轮的读取都执行完，再执行写入 */
+export declare function batchLayout(read: Read): void;
+export {};

package/dist/utils/dom/layout-batch.js

@@ -0,0 +1,26 @@
+//#region src/utils/dom/layout-batch.ts
+var reads = [];
+/** 一个读取或写入出错：报出来（下一个微任务里抛出），这一轮别的读写照常执行 */
+function safely(task) {
+	try {
+		return task();
+	} catch (error) {
+		queueMicrotask(() => {
+			throw error;
+		});
+		return;
+	}
+}
+function flush() {
+	const writes = reads.splice(0).map((read) => safely(read));
+	for (const write of writes) if (write) safely(write);
+}
+/** 登记一次读取（返回写入）：这一轮的读取都执行完，再执行写入 */
+function batchLayout(read) {
+	reads.push(read);
+	if (reads.length === 1) queueMicrotask(flush);
+}
+//#endregion
+export { batchLayout };
+
+//# sourceMappingURL=layout-batch.js.map

package/dist/utils/dom/layout-batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-batch.js","names":[],"sources":["../../../src/utils/dom/layout-batch.ts"],"sourcesContent":["/**\n * 先读后写：当前任务里登记的读取在一个微任务里依次执行，全部读完再依次执行它们返回的写入。\n * 各组件挂载后、尺寸变化时各自“读布局 → 写样式”，一个写完下一个读就要重新布局；\n * 合并后一整轮只布局一次（同 fastdom 的 measure / mutate）。\n *\n *   batchLayout(() => {\n *     const width = item.offsetWidth;                      // 读\n *     return () => (bar.style.width = `${width}px`);       // 写\n *   });\n */\n\ntype Read = () => (() => void) | void;\n\nconst reads: Read[] = [];\n\n/** 一个读取或写入出错：报出来（下一个微任务里抛出），这一轮别的读写照常执行 */\nfunction safely<T>(task: () => T): T | undefined {\n  try {\n    return task();\n  } catch (error) {\n    queueMicrotask(() => {\n      throw error;\n    });\n    return undefined;\n  }\n}\n\nfunction flush() {\n  const writes = reads.splice(0).map((read) => safely(read));\n  for (const write of writes) if (write) safely(write);\n}\n\n/** 登记一次读取（返回写入）：这一轮的读取都执行完，再执行写入 */\nexport function batchLayout(read: Read): void {\n  reads.push(read);\n  if (reads.length === 1) queueMicrotask(flush);\n}\n"],"mappings":";AAaA,IAAM,QAAgB,CAAC;;AAGvB,SAAS,OAAU,MAA8B;CAC/C,IAAI;EACF,OAAO,KAAK;CACd,SAAS,OAAO;EACd,qBAAqB;GACnB,MAAM;EACR,CAAC;EACD;CACF;AACF;AAEA,SAAS,QAAQ;CACf,MAAM,SAAS,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,SAAS,OAAO,IAAI,CAAC;CACzD,KAAK,MAAM,SAAS,QAAQ,IAAI,OAAO,OAAO,KAAK;AACrD;;AAGA,SAAgB,YAAY,MAAkB;CAC5C,MAAM,KAAK,IAAI;CACf,IAAI,MAAM,WAAW,GAAG,eAAe,KAAK;AAC9C"}

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

@@ -0,0 +1,18 @@
+/** 这次点击该不该交给路由：只拦普通左键点击同源、在当前窗口打开、不是下载的链接 */
+export declare function shouldRouteClick(event: MouseEvent, anchor: HTMLAnchorElement): boolean;
+/** 外部链接（external）的属性：新窗口打开，不把本页交给对方（window.opener）、不带来源地址 */
+export declare const externalLinkAttrs: {
+    readonly target: '_blank';
+    readonly rel: 'noopener noreferrer';
+};
+/** 链接的路由能力：渲染的地址、点击处理（展开到 <a> 的 onClick）与“是不是当前页” */
+export interface RouterLink {
+    /** 渲染到 <a href> 上的地址：站内链接经路由的 resolve 补上 base 与 hash 模式的 #；没有 resolve 时原样 */
+    href: (href: string) => string;
+    /** 站内链接的普通点击改由路由跳转，交给路由的是写在组件上的原文 href；没有配置路由时什么也不做 */
+    onClick: (event: MouseEvent, href: string) => void;
+    /** href 是不是当前页；没有配置 isActive 时为 false。在渲染里调用以跟随路由变化 */
+    isActive: (href: string | undefined) => boolean;
+}
+/** 在组件 setup 里调用 */
+export declare function useRouterLink(): RouterLink;

package/dist/utils/dom/link.js

@@ -0,0 +1,44 @@
+import { useConfig } from "../../config/context.js";
+//#region src/utils/dom/link.ts
+/**
+* 链接与路由适配（config 的 router，参考 React Aria 的 RouterProvider）：
+* 组件渲染真正的 <a href>（右键菜单、新标签页打开、读屏都正常），普通左键点击站内链接时交给路由跳转。
+* Link、LinkButton、导航组件共用。
+*/
+/** 这次点击该不该交给路由：只拦普通左键点击同源、在当前窗口打开、不是下载的链接 */
+function shouldRouteClick(event, anchor) {
+	if (event.defaultPrevented || event.button !== 0) return false;
+	if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return false;
+	if (anchor.target && anchor.target !== "_self") return false;
+	if (anchor.hasAttribute("download")) return false;
+	return anchor.origin === window.location.origin;
+}
+/** 外部链接（external）的属性：新窗口打开，不把本页交给对方（window.opener）、不带来源地址 */
+var externalLinkAttrs = {
+	target: "_blank",
+	rel: "noopener noreferrer"
+};
+/** 外部链接（带协议、// 开头）与页内锚点（#…）不经过路由 */
+var isRoutable = (href) => !/^([a-z][\w+.-]*:|\/\/|#)/i.test(href);
+/** 在组件 setup 里调用 */
+function useRouterLink() {
+	const config = useConfig();
+	return {
+		href: (href) => {
+			const resolve = config.router?.resolve;
+			return resolve && isRoutable(href) ? resolve(href) : href;
+		},
+		onClick(event, href) {
+			const router = config.router;
+			const anchor = event.currentTarget;
+			if (!router || !(anchor instanceof HTMLAnchorElement) || !shouldRouteClick(event, anchor)) return;
+			event.preventDefault();
+			router.navigate(href);
+		},
+		isActive: (href) => href != null && config.router?.isActive?.(href) || false
+	};
+}
+//#endregion
+export { externalLinkAttrs, shouldRouteClick, useRouterLink };
+
+//# sourceMappingURL=link.js.map