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

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

@@ -0,0 +1 @@
+{"version":3,"file":"typeahead.js","names":[],"sources":["../../../src/utils/dom/typeahead.ts"],"sourcesContent":["/**\n * 类型搜索（WAI-ARIA 的 type-ahead）：在菜单、列表里直接按字母，焦点跳到以它开头的项。\n * 连续输入拼成一个词（“ex” 跳到 Export）；间隔超过 timeout 后重新开始；反复按同一个字母在以它开头的项之间轮换。\n * 菜单经 rovingFocus 的 typeahead 选项使用，Listbox、Select 经 useListState 用同一个匹配规则。\n */\n\n/** createTypeahead 返回的搜索器 */\nexport interface Typeahead {\n  /**\n   * 处理一次按键：key 是 KeyboardEvent.key，labels 是各项的文字，current 是当前项的序号（没有时 -1）。\n   * 返回该落到的项的序号；不是可打印字符、或没有匹配时返回 -1\n   */\n  next(key: string, labels: readonly string[], current: number): number;\n}\n\n/** 生成一个搜索器：每个菜单、列表各用一个，输入缓冲互不干扰 */\nexport function createTypeahead(timeout = 500): Typeahead {\n  let query = '';\n  let timer: ReturnType<typeof setTimeout> | undefined;\n\n  return {\n    next(key, labels, current) {\n      // 只认单个可打印字符；空格开头时不算（空格是激活键）\n      if (!/^.$/su.test(key) || (key === ' ' && !query)) return -1;\n      clearTimeout(timer);\n      timer = setTimeout(() => (query = ''), timeout);\n      query += key.toLocaleLowerCase();\n\n      const normalized = labels.map((label) => label.trim().toLocaleLowerCase());\n      // 同一个字母反复按：从下一项开始找以它开头的，轮换\n      const first = query.slice(0, key.length);\n      const repeated = query === first.repeat(query.length / first.length);\n      const search = repeated ? first : query;\n      const start = repeated ? current + 1 : Math.max(current, 0);\n      for (let offset = 0; offset < normalized.length; offset++) {\n        const index = (start + offset) % normalized.length;\n        if (normalized[index]!.startsWith(search)) return index;\n      }\n      return -1;\n    },\n  };\n}\n"],"mappings":";;AAgBA,SAAgB,gBAAgB,UAAU,KAAgB;CACxD,IAAI,QAAQ;CACZ,IAAI;CAEJ,OAAO,EACL,KAAK,KAAK,QAAQ,SAAS;EAEzB,IAAI,CAAC,QAAQ,KAAK,GAAG,KAAM,QAAQ,OAAO,CAAC,OAAQ,OAAO;EAC1D,aAAa,KAAK;EAClB,QAAQ,iBAAkB,QAAQ,IAAK,OAAO;EAC9C,SAAS,IAAI,kBAAkB;EAE/B,MAAM,aAAa,OAAO,KAAK,UAAU,MAAM,KAAK,CAAC,CAAC,kBAAkB,CAAC;EAEzE,MAAM,QAAQ,MAAM,MAAM,GAAG,IAAI,MAAM;EACvC,MAAM,WAAW,UAAU,MAAM,OAAO,MAAM,SAAS,MAAM,MAAM;EACnE,MAAM,SAAS,WAAW,QAAQ;EAClC,MAAM,QAAQ,WAAW,UAAU,IAAI,KAAK,IAAI,SAAS,CAAC;EAC1D,KAAK,IAAI,SAAS,GAAG,SAAS,WAAW,QAAQ,UAAU;GACzD,MAAM,SAAS,QAAQ,UAAU,WAAW;GAC5C,IAAI,WAAW,MAAM,CAAE,WAAW,MAAM,GAAG,OAAO;EACpD;EACA,OAAO;CACT,EACF;AACF"}

package/dist/utils/motion/active-indicator.d.ts

@@ -0,0 +1,24 @@
+/** 指示条沿哪个方向跟随 */
+export interface IndicatorAxes {
+    /** 横排：写 x 与宽度（下划线） */
+    horizontal: unknown;
+    /** 竖排：写 y 与高度（竖排的侧边线） */
+    vertical: unknown;
+    /** 两个方向：写 x、y 与宽高，盖住整个当前项（选中滑块） */
+    both: unknown;
+}
+/** useActiveIndicator 每次读取的选项 */
+export interface ActiveIndicatorOptions {
+    /** 各项所在的容器（指示条的定位容器）；还没挂载时为 null */
+    container: HTMLElement | null;
+    /** 指示条元素；不显示时为 null */
+    indicator: HTMLElement | null;
+    /** 在容器里找当前项的选择器 */
+    active: string;
+    /** 跟随方向 */
+    axis: keyof IndicatorAxes;
+    /** 当前选中的值：变化时滑到新的当前项 */
+    value: unknown;
+}
+/** 指示条跟着当前项（在 setup 里调用） */
+export declare function useActiveIndicator(read: () => ActiveIndicatorOptions): void;

package/dist/utils/motion/active-indicator.js

@@ -0,0 +1,58 @@
+import { useAnimate } from "./animation.js";
+import { batchLayout } from "../dom/layout-batch.js";
+import { useResizeObserver } from "../dom/resize.js";
+import { onMounted, onScopeDispose, watch } from "vue";
+import { utils } from "animejs";
+//#region src/utils/motion/active-indicator.ts
+/**
+* 跟着当前项走的指示条：Tabs 的下划线、ToggleGroup 的选中滑块。
+*
+*   useActiveIndicator(() => ({
+*     container: list, indicator, active: '[aria-selected="true"]', axis: 'horizontal', value: tabs.value,
+*   }));
+*
+* 量出当前项相对容器的位置写到指示条上（transform 与宽高）：value 变化时滑过去（取主题时长），
+* 挂载时与尺寸变化（字体加载、容器变宽）时直接对齐；axis 变了先清掉旧的内联样式。
+* 指示条按当前项的 offsetLeft / offsetTop 定位，容器要是它的定位容器（position: relative）。
+*/
+/** 指示条跟着当前项（在 setup 里调用） */
+function useActiveIndicator(read) {
+	const animate = useAnimate();
+	function place(animated) {
+		batchLayout(() => {
+			const { container, indicator, active, axis } = read();
+			const item = container?.querySelector(active);
+			if (!indicator || !item) return;
+			const target = {
+				x: axis === "vertical" ? 0 : item.offsetLeft,
+				y: axis === "horizontal" ? 0 : item.offsetTop
+			};
+			if (axis !== "vertical") target.width = item.offsetWidth;
+			if (axis !== "horizontal") target.height = item.offsetHeight;
+			return () => {
+				if (animated) animate(indicator, target);
+				else utils.set(indicator, target);
+			};
+		});
+	}
+	onMounted(() => place(false));
+	watch(() => read().value, () => place(true), { flush: "post" });
+	watch([() => read().axis, () => read().indicator], ([, indicator]) => {
+		for (const property of [
+			"width",
+			"height",
+			"transform"
+		]) indicator?.style.removeProperty(property);
+		place(false);
+	}, { flush: "post" });
+	let frame = 0;
+	useResizeObserver(() => read().container, () => {
+		cancelAnimationFrame(frame);
+		frame = requestAnimationFrame(() => place(false));
+	});
+	onScopeDispose(() => cancelAnimationFrame(frame));
+}
+//#endregion
+export { useActiveIndicator };
+
+//# sourceMappingURL=active-indicator.js.map

package/dist/utils/motion/active-indicator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-indicator.js","names":[],"sources":["../../../src/utils/motion/active-indicator.ts"],"sourcesContent":["/**\n * 跟着当前项走的指示条：Tabs 的下划线、ToggleGroup 的选中滑块。\n *\n *   useActiveIndicator(() => ({\n *     container: list, indicator, active: '[aria-selected=\"true\"]', axis: 'horizontal', value: tabs.value,\n *   }));\n *\n * 量出当前项相对容器的位置写到指示条上（transform 与宽高）：value 变化时滑过去（取主题时长），\n * 挂载时与尺寸变化（字体加载、容器变宽）时直接对齐；axis 变了先清掉旧的内联样式。\n * 指示条按当前项的 offsetLeft / offsetTop 定位，容器要是它的定位容器（position: relative）。\n */\nimport { utils, type AnimationParams } from 'animejs';\nimport { onMounted, onScopeDispose, watch } from 'vue';\nimport { batchLayout } from '../dom/layout-batch';\nimport { useResizeObserver } from '../dom/resize';\nimport { useAnimate } from './animation';\n\n/** 指示条沿哪个方向跟随 */\nexport interface IndicatorAxes {\n  /** 横排：写 x 与宽度（下划线） */\n  horizontal: unknown;\n  /** 竖排：写 y 与高度（竖排的侧边线） */\n  vertical: unknown;\n  /** 两个方向：写 x、y 与宽高，盖住整个当前项（选中滑块） */\n  both: unknown;\n}\n\n/** useActiveIndicator 每次读取的选项 */\nexport interface ActiveIndicatorOptions {\n  /** 各项所在的容器（指示条的定位容器）；还没挂载时为 null */\n  container: HTMLElement | null;\n  /** 指示条元素；不显示时为 null */\n  indicator: HTMLElement | null;\n  /** 在容器里找当前项的选择器 */\n  active: string;\n  /** 跟随方向 */\n  axis: keyof IndicatorAxes;\n  /** 当前选中的值：变化时滑到新的当前项 */\n  value: unknown;\n}\n\n/** 指示条跟着当前项（在 setup 里调用） */\nexport function useActiveIndicator(read: () => ActiveIndicatorOptions): void {\n  const animate = useAnimate();\n\n  // 合并到这一轮的先读后写里：一页的标签、分段控件挂载时各量一次，合起来只排一次版\n  function place(animated: boolean) {\n    batchLayout(() => {\n      const { container, indicator, active, axis } = read();\n      const item = container?.querySelector<HTMLElement>(active);\n      if (!indicator || !item) return;\n      const x = axis === 'vertical' ? 0 : item.offsetLeft;\n      const y = axis === 'horizontal' ? 0 : item.offsetTop;\n      const target: AnimationParams = { x, y };\n      if (axis !== 'vertical') target.width = item.offsetWidth;\n      if (axis !== 'horizontal') target.height = item.offsetHeight;\n      return () => {\n        if (animated) void animate(indicator, target);\n        else void utils.set(indicator, target);\n      };\n    });\n  }\n\n  onMounted(() => place(false));\n  watch(\n    () => read().value,\n    () => place(true),\n    { flush: 'post' },\n  );\n  // 换了方向（或指示条重新渲染）：横排时写的宽度、竖排时写的高度不再适用，清掉后重新对齐\n  watch(\n    // 分开的两个来源：read 里别的字段（如 value）变化时不触发\n    [() => read().axis, () => read().indicator],\n    ([, indicator]) => {\n      for (const property of ['width', 'height', 'transform'])\n        indicator?.style.removeProperty(property);\n      place(false);\n    },\n    { flush: 'post' },\n  );\n  // 各项的位置会随字体加载、容器变宽而变：下一帧直接对齐（不在 ResizeObserver 回调里同步改样式）\n  let frame = 0;\n  useResizeObserver(\n    () => read().container,\n    () => {\n      cancelAnimationFrame(frame);\n      frame = requestAnimationFrame(() => place(false));\n    },\n  );\n  onScopeDispose(() => cancelAnimationFrame(frame));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AA0CA,SAAgB,mBAAmB,MAA0C;CAC3E,MAAM,UAAU,WAAW;CAG3B,SAAS,MAAM,UAAmB;EAChC,kBAAkB;GAChB,MAAM,EAAE,WAAW,WAAW,QAAQ,SAAS,KAAK;GACpD,MAAM,OAAO,WAAW,cAA2B,MAAM;GACzD,IAAI,CAAC,aAAa,CAAC,MAAM;GAGzB,MAAM,SAA0B;IAAE,GAFxB,SAAS,aAAa,IAAI,KAAK;IAEJ,GAD3B,SAAS,eAAe,IAAI,KAAK;GACJ;GACvC,IAAI,SAAS,YAAY,OAAO,QAAQ,KAAK;GAC7C,IAAI,SAAS,cAAc,OAAO,SAAS,KAAK;GAChD,aAAa;IACX,IAAI,UAAU,QAAa,WAAW,MAAM;SACvC,MAAW,IAAI,WAAW,MAAM;GACvC;EACF,CAAC;CACH;CAEA,gBAAgB,MAAM,KAAK,CAAC;CAC5B,YACQ,KAAK,CAAC,CAAC,aACP,MAAM,IAAI,GAChB,EAAE,OAAO,OAAO,CAClB;CAEA,MAEE,OAAO,KAAK,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,SAAS,IACzC,GAAG,eAAe;EACjB,KAAK,MAAM,YAAY;GAAC;GAAS;GAAU;EAAW,GACpD,WAAW,MAAM,eAAe,QAAQ;EAC1C,MAAM,KAAK;CACb,GACA,EAAE,OAAO,OAAO,CAClB;CAEA,IAAI,QAAQ;CACZ,wBACQ,KAAK,CAAC,CAAC,iBACP;EACJ,qBAAqB,KAAK;EAC1B,QAAQ,4BAA4B,MAAM,KAAK,CAAC;CAClD,CACF;CACA,qBAAqB,qBAAqB,KAAK,CAAC;AAClD"}

package/dist/utils/motion/animation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * JS 动画用 Anime.js（MIT）：animate、createTimeline、spring、stagger、createDraggable、createLayout 等直接从 'animejs' 导入，
+ * 这里只补一件 Anime.js 不知道的事 —— 时长、缓动、弹簧取主题 tokens 的当前值：
+ * 主题覆盖的时长照样生效；开启“减少动态效果”时 durations 为 0，JS 动画也就立即完成
+ * （Anime.js 不会自动处理 prefers-reduced-motion）。
+ *
+ *   animate(panel, { x: 0, ...themeTransition(panel, { duration: 'lg', ease: 'enter' }) })
+ *   animate(card, { scale: 1, ...themeTransition(card, { bounce: 0.3 }) })   // 弹簧
+ *
+ * 组件里用 useAnimate：同样取主题，另外在组件卸载时取消还在跑的动画。
+ *
+ * 进出场、展开收起能用 CSS 过渡的仍用 CSS：原生 popover / dialog 被 Esc、点击外部关闭时，JS 来不及介入。
+ */
+import { type AnimationParams, type EasingParam, type JSAnimation } from 'animejs';
+import { durations, easings } from '../../config/theme/tokens';
+/** themeTransition 的选项：取哪一档时长与缓动，或用弹簧 */
+export interface ThemeTransitionOptions {
+    /** 时长档位，默认 md */
+    duration?: keyof typeof durations & string;
+    /** 缓动曲线，默认 standard；给了 bounce 时不用 */
+    ease?: keyof typeof easings & string;
+    /** 弹簧的回弹程度（0 不回弹，越大越弹，建议不超过 0.5）：给了就用弹簧，时长档位作为弹簧的感知时长 */
+    bounce?: number;
+}
+/** themeTransition 的结果：展开到 Anime.js 的 animate、createLayout 等的参数里 */
+export interface ThemeTiming {
+    /** 时长（毫秒）；用弹簧时不给，由弹簧决定 */
+    duration?: number;
+    /** 缓动曲线或弹簧 */
+    ease?: EasingParam;
+}
+/** 按主题 tokens 生成 Anime.js 的时长与缓动参数，展开到 animate 的参数里；element 决定读哪个主题范围里的取值 */
+export declare function themeTransition(element: Element, { duration, ease, bounce }?: ThemeTransitionOptions): ThemeTiming;
+/** CSS 时长 → 毫秒：'200ms' / '0.2s' → 200；时长 token 读出来的值用它换算 */
+export declare function parseDuration(value: string): number;
+/** useAnimate 返回的函数：给元素（或任何 JS 对象）做一次取主题时长的动画，返回 Anime.js 的动画（可以 await） */
+export type ThemeAnimate = <Target extends object>(target: Target, params: AnimationParams, transition?: ThemeAnimateOptions) => JSAnimation;
+/** useAnimate 的时长选项：主题档位，加上按哪个元素读主题 */
+export interface ThemeAnimateOptions extends ThemeTransitionOptions {
+    /** 读这个元素上的主题取值；目标是元素时默认是它，否则（JS 对象、描线的代理）默认是根元素 */
+    scope?: Element;
+}
+/**
+ * 同 themeTransition，但读不到主题 token（页面没加载组件库的样式，如单元测试）时返回时长 0（直接到位），
+ * 不让动画报错打断交互。组件里的动画都用它。token 写错了格式（时长没带单位、缓动不是 cubic-bezier）照常报错：
+ * 那是主题的错，悄悄变成没有动画就发现不了
+ */
+export declare function themeTransitionOrInstant(element: Element, transition?: ThemeTransitionOptions): ThemeTiming;
+/**
+ * 组件里的 JS 动画（在 setup 里调用）：时长、缓动、弹簧取主题 tokens（themeTransition），组件卸载时取消还在跑的动画。
+ * 同一目标同一属性上的新动画会替换旧的（Anime.js 默认的 composition: 'replace'），快速连续触发不会互相打架；
+ * params 里写的 duration、ease 优先于主题。目标不是元素（JS 对象、描线的代理）时按 scope（默认根元素）读主题。
+ *
+ *   const animate = useAnimate();
+ *   animate(item, { x: 0, opacity: 1 }, { bounce: 0.35 });                       // 弹回
+ *   await animate(item, { x: width, opacity: 0 }, { duration: 'sm', ease: 'exit' }); // 滑出后再移除
+ */
+export declare function useAnimate(): ThemeAnimate;

package/dist/utils/motion/animation.js

@@ -0,0 +1,83 @@
+import { durations, easings } from "../../config/theme/tokens.js";
+import { readToken, tokenValue } from "../../config/theme/theme.js";
+import { onScopeDispose } from "vue";
+import { animate, cubicBezier, spring } from "animejs";
+//#region src/utils/motion/animation.ts
+/**
+* JS 动画用 Anime.js（MIT）：animate、createTimeline、spring、stagger、createDraggable、createLayout 等直接从 'animejs' 导入，
+* 这里只补一件 Anime.js 不知道的事 —— 时长、缓动、弹簧取主题 tokens 的当前值：
+* 主题覆盖的时长照样生效；开启“减少动态效果”时 durations 为 0，JS 动画也就立即完成
+* （Anime.js 不会自动处理 prefers-reduced-motion）。
+*
+*   animate(panel, { x: 0, ...themeTransition(panel, { duration: 'lg', ease: 'enter' }) })
+*   animate(card, { scale: 1, ...themeTransition(card, { bounce: 0.3 }) })   // 弹簧
+*
+* 组件里用 useAnimate：同样取主题，另外在组件卸载时取消还在跑的动画。
+*
+* 进出场、展开收起能用 CSS 过渡的仍用 CSS：原生 popover / dialog 被 Esc、点击外部关闭时，JS 来不及介入。
+*/
+/** 按主题 tokens 生成 Anime.js 的时长与缓动参数，展开到 animate 的参数里；element 决定读哪个主题范围里的取值 */
+function themeTransition(element, { duration = "md", ease = "standard", bounce } = {}) {
+	const milliseconds = parseDuration(readToken(element, durations[duration]));
+	if (milliseconds === 0) return { duration: 0 };
+	if (bounce != null) return { ease: spring({
+		bounce,
+		duration: milliseconds
+	}) };
+	return {
+		duration: milliseconds,
+		ease: cubicBezier(...parseEasing(readToken(element, easings[ease])))
+	};
+}
+/** CSS 时长 → 毫秒：'200ms' / '0.2s' → 200；时长 token 读出来的值用它换算 */
+function parseDuration(value) {
+	const match = /^([\d.]+)(ms|s)$/.exec(value);
+	if (!match) throw new Error(`无法识别的时长 token：${value}`);
+	return Number(match[1]) * (match[2] === "s" ? 1e3 : 1);
+}
+/** 'cubic-bezier(0.2, 0, 0, 1)' → [0.2, 0, 0, 1]；缓动 token 要写成 cubic-bezier，JS 才能复现同一条曲线 */
+function parseEasing(value) {
+	const points = /^cubic-bezier\(([^)]+)\)$/.exec(value)?.[1].split(",").map(Number);
+	if (points?.length !== 4 || points.some(Number.isNaN)) throw new Error(`缓动 token 要写成 cubic-bezier(…)：${value}`);
+	return points;
+}
+/**
+* 同 themeTransition，但读不到主题 token（页面没加载组件库的样式，如单元测试）时返回时长 0（直接到位），
+* 不让动画报错打断交互。组件里的动画都用它。token 写错了格式（时长没带单位、缓动不是 cubic-bezier）照常报错：
+* 那是主题的错，悄悄变成没有动画就发现不了
+*/
+function themeTransitionOrInstant(element, transition) {
+	if (!tokenValue(element, durations[transition?.duration ?? "md"])) return { duration: 0 };
+	return themeTransition(element, transition);
+}
+/**
+* 组件里的 JS 动画（在 setup 里调用）：时长、缓动、弹簧取主题 tokens（themeTransition），组件卸载时取消还在跑的动画。
+* 同一目标同一属性上的新动画会替换旧的（Anime.js 默认的 composition: 'replace'），快速连续触发不会互相打架；
+* params 里写的 duration、ease 优先于主题。目标不是元素（JS 对象、描线的代理）时按 scope（默认根元素）读主题。
+*
+*   const animate = useAnimate();
+*   animate(item, { x: 0, opacity: 1 }, { bounce: 0.35 });                       // 弹回
+*   await animate(item, { x: width, opacity: 0 }, { duration: 'sm', ease: 'exit' }); // 滑出后再移除
+*/
+function useAnimate() {
+	const running = /* @__PURE__ */ new Set();
+	onScopeDispose(() => {
+		for (const animation of running) animation.cancel();
+		running.clear();
+	});
+	return (target, params, transition) => {
+		const scope = transition?.scope ?? (target instanceof Element ? target : document.documentElement);
+		for (const animation of running) if (animation.completed || animation.cancelled) running.delete(animation);
+		const animation = animate(target, {
+			...themeTransitionOrInstant(scope, transition),
+			...params
+		});
+		if (animation.duration < 1) return animation.complete();
+		running.add(animation);
+		return animation;
+	};
+}
+//#endregion
+export { parseDuration, themeTransition, themeTransitionOrInstant, useAnimate };
+
+//# sourceMappingURL=animation.js.map

package/dist/utils/motion/animation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation.js","names":[],"sources":["../../../src/utils/motion/animation.ts"],"sourcesContent":["/**\n * JS 动画用 Anime.js（MIT）：animate、createTimeline、spring、stagger、createDraggable、createLayout 等直接从 'animejs' 导入，\n * 这里只补一件 Anime.js 不知道的事 —— 时长、缓动、弹簧取主题 tokens 的当前值：\n * 主题覆盖的时长照样生效；开启“减少动态效果”时 durations 为 0，JS 动画也就立即完成\n * （Anime.js 不会自动处理 prefers-reduced-motion）。\n *\n *   animate(panel, { x: 0, ...themeTransition(panel, { duration: 'lg', ease: 'enter' }) })\n *   animate(card, { scale: 1, ...themeTransition(card, { bounce: 0.3 }) })   // 弹簧\n *\n * 组件里用 useAnimate：同样取主题，另外在组件卸载时取消还在跑的动画。\n *\n * 进出场、展开收起能用 CSS 过渡的仍用 CSS：原生 popover / dialog 被 Esc、点击外部关闭时，JS 来不及介入。\n */\nimport {\n  animate,\n  cubicBezier,\n  spring,\n  type AnimationParams,\n  type EasingParam,\n  type JSAnimation,\n} from 'animejs';\nimport { onScopeDispose } from 'vue';\nimport { readToken, tokenValue } from '../../config/theme/theme';\nimport { durations, easings } from '../../config/theme/tokens';\n\n/** themeTransition 的选项：取哪一档时长与缓动，或用弹簧 */\nexport interface ThemeTransitionOptions {\n  /** 时长档位，默认 md */\n  duration?: keyof typeof durations & string;\n  /** 缓动曲线，默认 standard；给了 bounce 时不用 */\n  ease?: keyof typeof easings & string;\n  /** 弹簧的回弹程度（0 不回弹，越大越弹，建议不超过 0.5）：给了就用弹簧，时长档位作为弹簧的感知时长 */\n  bounce?: number;\n}\n\n/** themeTransition 的结果：展开到 Anime.js 的 animate、createLayout 等的参数里 */\nexport interface ThemeTiming {\n  /** 时长（毫秒）；用弹簧时不给，由弹簧决定 */\n  duration?: number;\n  /** 缓动曲线或弹簧 */\n  ease?: EasingParam;\n}\n\n/** 按主题 tokens 生成 Anime.js 的时长与缓动参数，展开到 animate 的参数里；element 决定读哪个主题范围里的取值 */\nexport function themeTransition(\n  element: Element,\n  { duration = 'md', ease = 'standard', bounce }: ThemeTransitionOptions = {},\n): ThemeTiming {\n  const milliseconds = parseDuration(readToken(element, durations[duration]));\n  if (milliseconds === 0) return { duration: 0 };\n  if (bounce != null) return { ease: spring({ bounce, duration: milliseconds }) };\n  return {\n    duration: milliseconds,\n    ease: cubicBezier(...parseEasing(readToken(element, easings[ease]))),\n  };\n}\n\n/** CSS 时长 → 毫秒：'200ms' / '0.2s' → 200；时长 token 读出来的值用它换算 */\nexport function parseDuration(value: string): number {\n  const match = /^([\\d.]+)(ms|s)$/.exec(value);\n  if (!match) throw new Error(`无法识别的时长 token：${value}`);\n  return Number(match[1]) * (match[2] === 's' ? 1000 : 1);\n}\n\n/** 'cubic-bezier(0.2, 0, 0, 1)' → [0.2, 0, 0, 1]；缓动 token 要写成 cubic-bezier，JS 才能复现同一条曲线 */\nfunction parseEasing(value: string): [number, number, number, number] {\n  const points = /^cubic-bezier\\(([^)]+)\\)$/.exec(value)?.[1]!.split(',').map(Number);\n  if (points?.length !== 4 || points.some(Number.isNaN)) {\n    throw new Error(`缓动 token 要写成 cubic-bezier(…)：${value}`);\n  }\n  return points as [number, number, number, number];\n}\n\n/** useAnimate 返回的函数：给元素（或任何 JS 对象）做一次取主题时长的动画，返回 Anime.js 的动画（可以 await） */\nexport type ThemeAnimate = <Target extends object>(\n  target: Target,\n  params: AnimationParams,\n  transition?: ThemeAnimateOptions,\n) => JSAnimation;\n\n/** useAnimate 的时长选项：主题档位，加上按哪个元素读主题 */\nexport interface ThemeAnimateOptions extends ThemeTransitionOptions {\n  /** 读这个元素上的主题取值；目标是元素时默认是它，否则（JS 对象、描线的代理）默认是根元素 */\n  scope?: Element;\n}\n\n/**\n * 同 themeTransition，但读不到主题 token（页面没加载组件库的样式，如单元测试）时返回时长 0（直接到位），\n * 不让动画报错打断交互。组件里的动画都用它。token 写错了格式（时长没带单位、缓动不是 cubic-bezier）照常报错：\n * 那是主题的错，悄悄变成没有动画就发现不了\n */\nexport function themeTransitionOrInstant(\n  element: Element,\n  transition?: ThemeTransitionOptions,\n): ThemeTiming {\n  if (!tokenValue(element, durations[transition?.duration ?? 'md'])) return { duration: 0 };\n  return themeTransition(element, transition);\n}\n\n/**\n * 组件里的 JS 动画（在 setup 里调用）：时长、缓动、弹簧取主题 tokens（themeTransition），组件卸载时取消还在跑的动画。\n * 同一目标同一属性上的新动画会替换旧的（Anime.js 默认的 composition: 'replace'），快速连续触发不会互相打架；\n * params 里写的 duration、ease 优先于主题。目标不是元素（JS 对象、描线的代理）时按 scope（默认根元素）读主题。\n *\n *   const animate = useAnimate();\n *   animate(item, { x: 0, opacity: 1 }, { bounce: 0.35 });                       // 弹回\n *   await animate(item, { x: width, opacity: 0 }, { duration: 'sm', ease: 'exit' }); // 滑出后再移除\n */\nexport function useAnimate(): ThemeAnimate {\n  const running = new Set<JSAnimation>();\n  onScopeDispose(() => {\n    for (const animation of running) void animation.cancel();\n    running.clear();\n  });\n  return (target, params, transition) => {\n    const scope =\n      transition?.scope ?? (target instanceof Element ? target : document.documentElement);\n    // 播完的、被新动画整个替换掉的不再需要取消\n    for (const animation of running) {\n      if (animation.completed || animation.cancelled) running.delete(animation);\n    }\n    const animation = animate(target, {\n      ...themeTransitionOrInstant(scope, transition),\n      ...params,\n    });\n    // 时长为 0（减少动态效果、读不到主题）时当场到位：不等下一帧，读取结果的代码不会先看到旧值\n    if (animation.duration < 1) return animation.complete();\n    running.add(animation);\n    return animation;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA4CA,SAAgB,gBACd,SACA,EAAE,WAAW,MAAM,OAAO,YAAY,WAAmC,CAAC,GAC7D;CACb,MAAM,eAAe,cAAc,UAAU,SAAS,UAAU,SAAS,CAAC;CAC1E,IAAI,iBAAiB,GAAG,OAAO,EAAE,UAAU,EAAE;CAC7C,IAAI,UAAU,MAAM,OAAO,EAAE,MAAM,OAAO;EAAE;EAAQ,UAAU;CAAa,CAAC,EAAE;CAC9E,OAAO;EACL,UAAU;EACV,MAAM,YAAY,GAAG,YAAY,UAAU,SAAS,QAAQ,KAAK,CAAC,CAAC;CACrE;AACF;;AAGA,SAAgB,cAAc,OAAuB;CACnD,MAAM,QAAQ,mBAAmB,KAAK,KAAK;CAC3C,IAAI,CAAC,OAAO,MAAM,IAAI,MAAM,iBAAiB,OAAO;CACpD,OAAO,OAAO,MAAM,EAAE,KAAK,MAAM,OAAO,MAAM,MAAO;AACvD;;AAGA,SAAS,YAAY,OAAiD;CACpE,MAAM,SAAS,4BAA4B,KAAK,KAAK,CAAC,GAAG,EAAE,CAAE,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM;CAClF,IAAI,QAAQ,WAAW,KAAK,OAAO,KAAK,OAAO,KAAK,GAClD,MAAM,IAAI,MAAM,gCAAgC,OAAO;CAEzD,OAAO;AACT;;;;;;AAoBA,SAAgB,yBACd,SACA,YACa;CACb,IAAI,CAAC,WAAW,SAAS,UAAU,YAAY,YAAY,KAAK,GAAG,OAAO,EAAE,UAAU,EAAE;CACxF,OAAO,gBAAgB,SAAS,UAAU;AAC5C;;;;;;;;;;AAWA,SAAgB,aAA2B;CACzC,MAAM,0BAAU,IAAI,IAAiB;CACrC,qBAAqB;EACnB,KAAK,MAAM,aAAa,SAAS,UAAe,OAAO;EACvD,QAAQ,MAAM;CAChB,CAAC;CACD,QAAQ,QAAQ,QAAQ,eAAe;EACrC,MAAM,QACJ,YAAY,UAAU,kBAAkB,UAAU,SAAS,SAAS;EAEtE,KAAK,MAAM,aAAa,SACtB,IAAI,UAAU,aAAa,UAAU,WAAW,QAAQ,OAAO,SAAS;EAE1E,MAAM,YAAY,QAAQ,QAAQ;GAChC,GAAG,yBAAyB,OAAO,UAAU;GAC7C,GAAG;EACL,CAAC;EAED,IAAI,UAAU,WAAW,GAAG,OAAO,UAAU,SAAS;EACtD,QAAQ,IAAI,SAAS;EACrB,OAAO;CACT;AACF"}

package/dist/utils/motion/delayed-loading.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 加载指示防闪烁：很快完成的加载不出现指示，出现了就至少显示一段时间（同 Ant Design Spin 的 delay、
+ * React Spectrum 的进度延迟）。只管视觉：aria-busy、禁止点击等仍按真实的 loading 立即生效。
+ *
+ *   const shown = useDelayedLoading(() => loading);   // 渲染里用 shown.value 决定显示骨架、进度条
+ *
+ * 挂载时已经在加载就立即显示（没有内容可看，空白比指示更糟）。
+ */
+import { type Ref } from 'vue';
+/** useDelayedLoading 的选项 */
+export interface DelayedLoadingOptions {
+    /** 开始加载后过多久才显示（毫秒），默认 200 */
+    delay?: number;
+    /** 显示后至少保持多久（毫秒），默认 500 */
+    minDuration?: number;
+}
+/** 加载指示是否显示（在 setup 里调用） */
+export declare function useDelayedLoading(read: () => boolean, { delay, minDuration }?: DelayedLoadingOptions): Readonly<Ref<boolean>>;

package/dist/utils/motion/delayed-loading.js

@@ -0,0 +1,38 @@
+import { onScopeDispose, shallowRef, watch } from "vue";
+//#region src/utils/motion/delayed-loading.ts
+/**
+* 加载指示防闪烁：很快完成的加载不出现指示，出现了就至少显示一段时间（同 Ant Design Spin 的 delay、
+* React Spectrum 的进度延迟）。只管视觉：aria-busy、禁止点击等仍按真实的 loading 立即生效。
+*
+*   const shown = useDelayedLoading(() => loading);   // 渲染里用 shown.value 决定显示骨架、进度条
+*
+* 挂载时已经在加载就立即显示（没有内容可看，空白比指示更糟）。
+*/
+/** 加载指示是否显示（在 setup 里调用） */
+function useDelayedLoading(read, { delay = 200, minDuration = 500 } = {}) {
+	const shown = shallowRef(read());
+	let shownAt = shown.value ? Date.now() : 0;
+	let timer;
+	const schedule = (wait, next) => {
+		clearTimeout(timer);
+		timer = setTimeout(() => {
+			shown.value = next;
+			if (next) shownAt = Date.now();
+		}, wait);
+	};
+	watch(read, (loading) => {
+		if (loading) {
+			if (shown.value) clearTimeout(timer);
+			else schedule(delay, true);
+			return;
+		}
+		if (!shown.value) return clearTimeout(timer);
+		schedule(Math.max(0, shownAt + minDuration - Date.now()), false);
+	});
+	onScopeDispose(() => clearTimeout(timer));
+	return shown;
+}
+//#endregion
+export { useDelayedLoading };
+
+//# sourceMappingURL=delayed-loading.js.map

package/dist/utils/motion/delayed-loading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delayed-loading.js","names":[],"sources":["../../../src/utils/motion/delayed-loading.ts"],"sourcesContent":["/**\n * 加载指示防闪烁：很快完成的加载不出现指示，出现了就至少显示一段时间（同 Ant Design Spin 的 delay、\n * React Spectrum 的进度延迟）。只管视觉：aria-busy、禁止点击等仍按真实的 loading 立即生效。\n *\n *   const shown = useDelayedLoading(() => loading);   // 渲染里用 shown.value 决定显示骨架、进度条\n *\n * 挂载时已经在加载就立即显示（没有内容可看，空白比指示更糟）。\n */\nimport { onScopeDispose, shallowRef, watch, type Ref } from 'vue';\n\n/** useDelayedLoading 的选项 */\nexport interface DelayedLoadingOptions {\n  /** 开始加载后过多久才显示（毫秒），默认 200 */\n  delay?: number;\n  /** 显示后至少保持多久（毫秒），默认 500 */\n  minDuration?: number;\n}\n\n/** 加载指示是否显示（在 setup 里调用） */\nexport function useDelayedLoading(\n  read: () => boolean,\n  { delay = 200, minDuration = 500 }: DelayedLoadingOptions = {},\n): Readonly<Ref<boolean>> {\n  const shown = shallowRef(read());\n  let shownAt = shown.value ? Date.now() : 0;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const schedule = (wait: number, next: boolean) => {\n    clearTimeout(timer);\n    timer = setTimeout(() => {\n      shown.value = next;\n      if (next) shownAt = Date.now();\n    }, wait);\n  };\n\n  watch(read, (loading) => {\n    if (loading) {\n      // 正在等着隐藏时又开始加载：取消隐藏，继续显示\n      if (shown.value) clearTimeout(timer);\n      else schedule(delay, true);\n      return;\n    }\n    if (!shown.value) return clearTimeout(timer);\n    schedule(Math.max(0, shownAt + minDuration - Date.now()), false);\n  });\n  onScopeDispose(() => clearTimeout(timer));\n  return shown;\n}\n"],"mappings":";;;;;;;;;;;AAmBA,SAAgB,kBACd,MACA,EAAE,QAAQ,KAAK,cAAc,QAA+B,CAAC,GACrC;CACxB,MAAM,QAAQ,WAAW,KAAK,CAAC;CAC/B,IAAI,UAAU,MAAM,QAAQ,KAAK,IAAI,IAAI;CACzC,IAAI;CACJ,MAAM,YAAY,MAAc,SAAkB;EAChD,aAAa,KAAK;EAClB,QAAQ,iBAAiB;GACvB,MAAM,QAAQ;GACd,IAAI,MAAM,UAAU,KAAK,IAAI;EAC/B,GAAG,IAAI;CACT;CAEA,MAAM,OAAO,YAAY;EACvB,IAAI,SAAS;GAEX,IAAI,MAAM,OAAO,aAAa,KAAK;QAC9B,SAAS,OAAO,IAAI;GACzB;EACF;EACA,IAAI,CAAC,MAAM,OAAO,OAAO,aAAa,KAAK;EAC3C,SAAS,KAAK,IAAI,GAAG,UAAU,cAAc,KAAK,IAAI,CAAC,GAAG,KAAK;CACjE,CAAC;CACD,qBAAqB,aAAa,KAAK,CAAC;CACxC,OAAO;AACT"}

package/dist/utils/motion/layout.d.ts

@@ -0,0 +1,17 @@
+import { type ThemeTransitionOptions } from './animation';
+/** useLayoutAnimation 的选项 */
+export interface LayoutAnimationOptions {
+    /** 参与动画的子元素（选择器），默认容器的所有后代 */
+    children?: string;
+    /** 时长档位，默认 md */
+    duration?: ThemeTransitionOptions['duration'];
+    /** 缓动曲线，默认 standard */
+    ease?: ThemeTransitionOptions['ease'];
+}
+/** useLayoutAnimation 的返回值 */
+export interface LayoutAnimation {
+    /** 记下位置 → 调用 mutate 改数据 → 等 DOM 更新后过渡到新位置；动画结束时完成 */
+    change(mutate: () => void): Promise<void>;
+}
+/** 容器里的子元素换位置时平移过去（在 setup 里调用）；container 读取容器（元素或组件实例），没挂载时为 null */
+export declare function useLayoutAnimation(container: () => unknown, { children, duration, ease }?: LayoutAnimationOptions): LayoutAnimation;

package/dist/utils/motion/layout.js

@@ -0,0 +1,43 @@
+import { themeTransitionOrInstant } from "./animation.js";
+import { toElement } from "../dom/element.js";
+import { nextTick, onScopeDispose } from "vue";
+import { createLayout } from "animejs";
+//#region src/utils/motion/layout.ts
+/**
+* 布局动画（FLIP）：改数据前记下子元素的位置，DOM 更新后从旧位置过渡到新位置（Anime.js 的 createLayout）。
+*
+*   const layout = useLayoutAnimation(() => list, { children: '[data-item]' });
+*   layout.change(() => items.splice(index, 1));   // 其余项平移补位，新项淡入
+*
+* 时长、缓动取主题；减少动态效果（时长为 0）时只改数据，不记录也不播。
+* 被 Vue 移除的元素直接消失：离场动画交给 usePresence，这里只管其余元素的位移。
+*/
+/** 容器里的子元素换位置时平移过去（在 setup 里调用）；container 读取容器（元素或组件实例），没挂载时为 null */
+function useLayoutAnimation(container, { children, duration, ease } = {}) {
+	let layout;
+	onScopeDispose(() => layout?.revert());
+	return { async change(mutate) {
+		const root = toElement(container());
+		const timing = root ? themeTransitionOrInstant(root, {
+			duration,
+			ease
+		}) : { duration: 0 };
+		if (!root || !timing.duration) {
+			mutate();
+			await nextTick();
+			return;
+		}
+		if (layout?.root !== root) {
+			layout?.revert();
+			layout = createLayout(root, children ? { children } : {});
+		}
+		layout.record();
+		mutate();
+		await nextTick();
+		await layout.animate(timing);
+	} };
+}
+//#endregion
+export { useLayoutAnimation };
+
+//# sourceMappingURL=layout.js.map

package/dist/utils/motion/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","names":[],"sources":["../../../src/utils/motion/layout.ts"],"sourcesContent":["/**\n * 布局动画（FLIP）：改数据前记下子元素的位置，DOM 更新后从旧位置过渡到新位置（Anime.js 的 createLayout）。\n *\n *   const layout = useLayoutAnimation(() => list, { children: '[data-item]' });\n *   layout.change(() => items.splice(index, 1));   // 其余项平移补位，新项淡入\n *\n * 时长、缓动取主题；减少动态效果（时长为 0）时只改数据，不记录也不播。\n * 被 Vue 移除的元素直接消失：离场动画交给 usePresence，这里只管其余元素的位移。\n */\nimport { createLayout, type AutoLayout } from 'animejs';\nimport { nextTick, onScopeDispose } from 'vue';\nimport { toElement } from '../dom/element';\nimport { themeTransitionOrInstant, type ThemeTransitionOptions } from './animation';\n\n/** useLayoutAnimation 的选项 */\nexport interface LayoutAnimationOptions {\n  /** 参与动画的子元素（选择器），默认容器的所有后代 */\n  children?: string;\n  /** 时长档位，默认 md */\n  duration?: ThemeTransitionOptions['duration'];\n  /** 缓动曲线，默认 standard */\n  ease?: ThemeTransitionOptions['ease'];\n}\n\n/** useLayoutAnimation 的返回值 */\nexport interface LayoutAnimation {\n  /** 记下位置 → 调用 mutate 改数据 → 等 DOM 更新后过渡到新位置；动画结束时完成 */\n  change(mutate: () => void): Promise<void>;\n}\n\n/** 容器里的子元素换位置时平移过去（在 setup 里调用）；container 读取容器（元素或组件实例），没挂载时为 null */\nexport function useLayoutAnimation(\n  container: () => unknown,\n  { children, duration, ease }: LayoutAnimationOptions = {},\n): LayoutAnimation {\n  let layout: AutoLayout | undefined;\n  onScopeDispose(() => layout?.revert());\n\n  return {\n    async change(mutate) {\n      const root = toElement(container());\n      const timing = root ? themeTransitionOrInstant(root, { duration, ease }) : { duration: 0 };\n      if (!root || !timing.duration) {\n        mutate();\n        await nextTick();\n        return;\n      }\n      // 容器换了（重新挂载）时重建\n      if (layout?.root !== root) {\n        layout?.revert();\n        layout = createLayout(root, children ? { children } : {});\n      }\n      layout.record();\n      mutate();\n      await nextTick();\n      await layout.animate(timing);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;AA+BA,SAAgB,mBACd,WACA,EAAE,UAAU,UAAU,SAAiC,CAAC,GACvC;CACjB,IAAI;CACJ,qBAAqB,QAAQ,OAAO,CAAC;CAErC,OAAO,EACL,MAAM,OAAO,QAAQ;EACnB,MAAM,OAAO,UAAU,UAAU,CAAC;EAClC,MAAM,SAAS,OAAO,yBAAyB,MAAM;GAAE;GAAU;EAAK,CAAC,IAAI,EAAE,UAAU,EAAE;EACzF,IAAI,CAAC,QAAQ,CAAC,OAAO,UAAU;GAC7B,OAAO;GACP,MAAM,SAAS;GACf;EACF;EAEA,IAAI,QAAQ,SAAS,MAAM;GACzB,QAAQ,OAAO;GACf,SAAS,aAAa,MAAM,WAAW,EAAE,SAAS,IAAI,CAAC,CAAC;EAC1D;EACA,OAAO,OAAO;EACd,OAAO;EACP,MAAM,SAAS;EACf,MAAM,OAAO,QAAQ,MAAM;CAC7B,EACF;AACF"}

package/dist/utils/motion/pointer.d.ts

@@ -0,0 +1,14 @@
+import { type SpringOptions } from './tween';
+/** usePointer 的返回值 */
+export interface PointerState {
+    /** 横向位置：元素左边 -1，右边 1（阻尼后） */
+    readonly x: number;
+    /** 纵向位置：元素底边 -1，顶边 1（阻尼后） */
+    readonly y: number;
+    /** 指针在元素上时趋向 1，离开后趋向 0（阻尼后） */
+    readonly strength: number;
+}
+/** usePointer 的选项 */
+export type PointerOptions = Pick<SpringOptions, 'bounce' | 'duration'>;
+/** 指针相对 scope 元素的阻尼位置（在 setup 里调用） */
+export declare function usePointer(scope: () => Element | null | undefined, { bounce, duration }?: PointerOptions): PointerState;

package/dist/utils/motion/pointer.js

@@ -0,0 +1,72 @@
+import { useEventListener } from "../dom/event-listener.js";
+import { useSpring } from "./tween.js";
+import { shallowRef } from "vue";
+//#region src/utils/motion/pointer.ts
+/**
+* 指针相对元素的位置（-1 到 1，向上为正，与 WebGL 的坐标一致），用弹簧（useSpring）做阻尼跟随。
+* 3D 效果（着色器的 uPointer）与倾斜卡片、聚光卡片共用：
+*
+*   const pointer = usePointer(() => host);
+*   uniforms.uPointer.value.set(pointer.x, pointer.y);    // 每帧读
+*   const left = (pointer.x + 1) * 50;                    // 换成 CSS 的百分比位置
+*   repel *= pointer.strength;                            // 指针离开元素时淡出
+*
+* 监听整个窗口：背景效果通常在内容下面，指针落在上层的文字、按钮上时也要跟随。
+* 减少动态效果时弹簧的时长为 0，位置直接到位（效果自己决定要不要停下交互）。
+*/
+/** 指针相对 scope 元素的阻尼位置（在 setup 里调用） */
+function usePointer(scope, { bounce = 0, duration = "xl" } = {}) {
+	const target = shallowRef({
+		x: 0,
+		y: 0,
+		inside: false
+	});
+	const spring = {
+		bounce,
+		duration,
+		scope
+	};
+	const x = useSpring(() => target.value.x, spring);
+	const y = useSpring(() => target.value.y, spring);
+	const strength = useSpring(() => target.value.inside ? 1 : 0, spring);
+	if (typeof window !== "undefined") {
+		const onMove = (event) => {
+			const rect = scope()?.getBoundingClientRect();
+			if (!rect || rect.width === 0 || rect.height === 0) return;
+			const inside = event.clientX >= rect.left && event.clientX <= rect.right && event.clientY >= rect.top && event.clientY <= rect.bottom;
+			if (!inside) {
+				if (target.value.inside) target.value = {
+					...target.value,
+					inside
+				};
+				return;
+			}
+			target.value = {
+				x: (event.clientX - rect.left) / rect.width * 2 - 1,
+				y: 1 - (event.clientY - rect.top) / rect.height * 2,
+				inside
+			};
+		};
+		const onLeave = () => target.value = {
+			...target.value,
+			inside: false
+		};
+		useEventListener(window, "pointermove", onMove, { passive: true });
+		useEventListener(document.documentElement, "pointerleave", onLeave);
+	}
+	return {
+		get x() {
+			return x.current;
+		},
+		get y() {
+			return y.current;
+		},
+		get strength() {
+			return strength.current;
+		}
+	};
+}
+//#endregion
+export { usePointer };
+
+//# sourceMappingURL=pointer.js.map

package/dist/utils/motion/pointer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.js","names":[],"sources":["../../../src/utils/motion/pointer.ts"],"sourcesContent":["/**\n * 指针相对元素的位置（-1 到 1，向上为正，与 WebGL 的坐标一致），用弹簧（useSpring）做阻尼跟随。\n * 3D 效果（着色器的 uPointer）与倾斜卡片、聚光卡片共用：\n *\n *   const pointer = usePointer(() => host);\n *   uniforms.uPointer.value.set(pointer.x, pointer.y);    // 每帧读\n *   const left = (pointer.x + 1) * 50;                    // 换成 CSS 的百分比位置\n *   repel *= pointer.strength;                            // 指针离开元素时淡出\n *\n * 监听整个窗口：背景效果通常在内容下面，指针落在上层的文字、按钮上时也要跟随。\n * 减少动态效果时弹簧的时长为 0，位置直接到位（效果自己决定要不要停下交互）。\n */\nimport { shallowRef } from 'vue';\nimport { useEventListener } from '../dom/event-listener';\nimport { useSpring, type SpringOptions } from './tween';\n\n/** usePointer 的返回值 */\nexport interface PointerState {\n  /** 横向位置：元素左边 -1，右边 1（阻尼后） */\n  readonly x: number;\n  /** 纵向位置：元素底边 -1，顶边 1（阻尼后） */\n  readonly y: number;\n  /** 指针在元素上时趋向 1，离开后趋向 0（阻尼后） */\n  readonly strength: number;\n}\n\n/** usePointer 的选项 */\nexport type PointerOptions = Pick<SpringOptions, 'bounce' | 'duration'>;\n\n/** 指针相对 scope 元素的阻尼位置（在 setup 里调用） */\nexport function usePointer(\n  scope: () => Element | null | undefined,\n  { bounce = 0, duration = 'xl' }: PointerOptions = {},\n): PointerState {\n  const target = shallowRef({ x: 0, y: 0, inside: false });\n  const spring = { bounce, duration, scope };\n  const x = useSpring(() => target.value.x, spring);\n  const y = useSpring(() => target.value.y, spring);\n  const strength = useSpring(() => (target.value.inside ? 1 : 0), spring);\n\n  if (typeof window !== 'undefined') {\n    const onMove = (event: PointerEvent) => {\n      const rect = scope()?.getBoundingClientRect();\n      if (!rect || rect.width === 0 || rect.height === 0) return;\n      const inside =\n        event.clientX >= rect.left &&\n        event.clientX <= rect.right &&\n        event.clientY >= rect.top &&\n        event.clientY <= rect.bottom;\n      // 离开元素时保持最后的位置，只让 strength 淡出：效果不会一下子跳回中心\n      if (!inside) {\n        if (target.value.inside) target.value = { ...target.value, inside };\n        return;\n      }\n      target.value = {\n        x: ((event.clientX - rect.left) / rect.width) * 2 - 1,\n        y: 1 - ((event.clientY - rect.top) / rect.height) * 2,\n        inside,\n      };\n    };\n    const onLeave = () => (target.value = { ...target.value, inside: false });\n    useEventListener(window, 'pointermove', onMove, { passive: true });\n    useEventListener(document.documentElement, 'pointerleave', onLeave);\n  }\n\n  return {\n    get x() {\n      return x.current;\n    },\n    get y() {\n      return y.current;\n    },\n    get strength() {\n      return strength.current;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA8BA,SAAgB,WACd,OACA,EAAE,SAAS,GAAG,WAAW,SAAyB,CAAC,GACrC;CACd,MAAM,SAAS,WAAW;EAAE,GAAG;EAAG,GAAG;EAAG,QAAQ;CAAM,CAAC;CACvD,MAAM,SAAS;EAAE;EAAQ;EAAU;CAAM;CACzC,MAAM,IAAI,gBAAgB,OAAO,MAAM,GAAG,MAAM;CAChD,MAAM,IAAI,gBAAgB,OAAO,MAAM,GAAG,MAAM;CAChD,MAAM,WAAW,gBAAiB,OAAO,MAAM,SAAS,IAAI,GAAI,MAAM;CAEtE,IAAI,OAAO,WAAW,aAAa;EACjC,MAAM,UAAU,UAAwB;GACtC,MAAM,OAAO,MAAM,CAAC,EAAE,sBAAsB;GAC5C,IAAI,CAAC,QAAQ,KAAK,UAAU,KAAK,KAAK,WAAW,GAAG;GACpD,MAAM,SACJ,MAAM,WAAW,KAAK,QACtB,MAAM,WAAW,KAAK,SACtB,MAAM,WAAW,KAAK,OACtB,MAAM,WAAW,KAAK;GAExB,IAAI,CAAC,QAAQ;IACX,IAAI,OAAO,MAAM,QAAQ,OAAO,QAAQ;KAAE,GAAG,OAAO;KAAO;IAAO;IAClE;GACF;GACA,OAAO,QAAQ;IACb,IAAK,MAAM,UAAU,KAAK,QAAQ,KAAK,QAAS,IAAI;IACpD,GAAG,KAAM,MAAM,UAAU,KAAK,OAAO,KAAK,SAAU;IACpD;GACF;EACF;EACA,MAAM,gBAAiB,OAAO,QAAQ;GAAE,GAAG,OAAO;GAAO,QAAQ;EAAM;EACvE,iBAAiB,QAAQ,eAAe,QAAQ,EAAE,SAAS,KAAK,CAAC;EACjE,iBAAiB,SAAS,iBAAiB,gBAAgB,OAAO;CACpE;CAEA,OAAO;EACL,IAAI,IAAI;GACN,OAAO,EAAE;EACX;EACA,IAAI,IAAI;GACN,OAAO,EAAE;EACX;EACA,IAAI,WAAW;GACb,OAAO,SAAS;EAClB;CACF;AACF"}

package/dist/utils/motion/presence.d.ts

@@ -0,0 +1,57 @@
+/** usePresence 的返回值 */
+export interface Presence {
+    /** 是否渲染：打开时，以及关闭后离场还没结束时 */
+    readonly mounted: boolean;
+    /** 打开还是正在离场（写到 data-state） */
+    readonly state: 'open' | 'closed';
+    /** 离场过渡所在的元素（或组件）的 ref：等它与子元素上的过渡结束 */
+    ref: (element: unknown) => void;
+}
+/** usePresence 的选项 */
+export interface PresenceOptions {
+    /** 离场结束、mounted 变为 false 之后调用 */
+    onExited?: () => void;
+    /** JS 离场动画（如 Anime.js）：关闭状态渲染后调用，等它结束；CSS 过渡不用写，会自动等 */
+    exit?: (element: HTMLElement) => PromiseLike<unknown> | void;
+}
+/** 关闭后等离场结束再卸载（在 setup 里调用） */
+export declare function usePresence(read: () => boolean, { onExited, exit }?: PresenceOptions): Presence;
+/** useDismissible 的返回值 */
+export interface Dismissible {
+    /** 正在离场：样式里写离场的终值与过渡 */
+    readonly dismissing: boolean;
+    /** 打开还是正在离场（写到 data-state） */
+    readonly state: 'open' | 'closed';
+    /** 根元素（或组件）的 ref */
+    ref: (element: unknown) => void;
+    /** 开始离场：焦点先移到相邻的可聚焦元素上（关闭按钮随它一起消失），离场结束调用 onDismiss；正在离场时什么也不做 */
+    readonly dismiss: () => void;
+}
+/**
+ * 先离场再移除：可关闭的标签、提示条、横幅共用（Tag、Alert、Banner）。数据由使用方控制：
+ * 离场结束才调用 onDismiss，使用方移除了就消失；没移除（如拒绝删除）时复位，元素重新出现。在 setup 里调用
+ *
+ *   const dismissible = useDismissible(() => onClose?.());
+ *   <div ref={dismissible.ref} data-state={dismissible.state} {...css.attrs(dismissible.dismissing && styles.leaving)}>
+ *     <CloseButton onClick={dismissible.dismiss} />
+ */
+export declare function useDismissible(onDismiss: () => void): Dismissible;
+/**
+ * 内容延迟渲染：lazy 时第一次打开前不渲染，打开过之后一直保留（再次打开、离场过渡都不必重建）。
+ * 在 setup 里调用，返回的函数在渲染时调用；渲染本来就读 open，打开时会重新渲染，所以不需要响应式状态。
+ *
+ *   const showContent = useLazyContent(() => open, () => lazy);
+ *   <div popover>{showContent() && children}</div>
+ *
+ * 浮层（Popover、HoverCard、Menu、对话框与抽屉）默认延迟：一百个关闭的菜单挂载 118ms → 12ms；
+ * Collapse、Tabs 默认不延迟（收起的内容页内搜索要找得到）。Tooltip 不延迟：它被触发器的 aria-describedby 引用。
+ */
+export declare function useLazyContent(open: () => boolean, lazy: () => boolean): () => boolean;
+/** 浮层的内容延迟渲染（Popover、HoverCard、Menu、对话框与抽屉共用） */
+export interface LazyContentOptions {
+    /**
+     * 第一次打开前不渲染内容，打开过后保留，默认 true。
+     * 内容要一直在 DOM 里（页内搜索、关闭时也要查询其中的元素）时设为 false
+     */
+    lazy?: boolean;
+}