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

package/dist/utils/motion/presence.js

@@ -0,0 +1,100 @@
+import { afterTransitions } from "../style/transitions.js";
+import { focusAfterRemoval } from "../dom/focus.js";
+import { toElement } from "../dom/element.js";
+import { computed, nextTick, onScopeDispose, shallowRef, watch } from "vue";
+//#region src/utils/motion/presence.ts
+/**
+* 离场动画的统一流程：关闭后先保持挂载、写 data-state="closed"，等离场（CSS 过渡或 Anime.js）结束再卸载。
+*
+*   const presence = usePresence(() => open, { onExited: () => emit('removed') });
+*   return () => presence.mounted && <div ref={presence.ref} data-state={presence.state} … />;
+*   // 样式里按 state 写离场的终值与过渡：presence.state === 'closed' && styles.leaving
+*
+* 离场中又打开了就停在打开状态，不卸载、不调用 onExited。元素自己决定是否卸载时（Toast、Tag）只用 state 与 onExited。
+*/
+/** 关闭后等离场结束再卸载（在 setup 里调用） */
+function usePresence(read, { onExited, exit } = {}) {
+	const open = computed(read);
+	const mounted = shallowRef(open.value);
+	let element = null;
+	let generation = 0;
+	onScopeDispose(() => generation++);
+	watch(open, async (value) => {
+		const current = ++generation;
+		if (value) {
+			mounted.value = true;
+			return;
+		}
+		await nextTick();
+		if (element) {
+			await exit?.(element);
+			await afterTransitions(element);
+		}
+		if (current !== generation) return;
+		mounted.value = false;
+		onExited?.();
+	});
+	return {
+		get mounted() {
+			return mounted.value;
+		},
+		get state() {
+			return open.value ? "open" : "closed";
+		},
+		ref: (value) => element = toElement(value)
+	};
+}
+/**
+* 先离场再移除：可关闭的标签、提示条、横幅共用（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} />
+*/
+function useDismissible(onDismiss) {
+	const dismissing = shallowRef(false);
+	let element = null;
+	const presence = usePresence(() => !dismissing.value, { onExited: () => {
+		dismissing.value = false;
+		onDismiss();
+	} });
+	return {
+		get dismissing() {
+			return dismissing.value;
+		},
+		get state() {
+			return presence.state;
+		},
+		ref: (value) => {
+			element = toElement(value);
+			presence.ref(value);
+		},
+		dismiss: () => {
+			if (dismissing.value) return;
+			if (element) focusAfterRemoval(element);
+			dismissing.value = true;
+		}
+	};
+}
+/**
+* 内容延迟渲染：lazy 时第一次打开前不渲染，打开过之后一直保留（再次打开、离场过渡都不必重建）。
+* 在 setup 里调用，返回的函数在渲染时调用；渲染本来就读 open，打开时会重新渲染，所以不需要响应式状态。
+*
+*   const showContent = useLazyContent(() => open, () => lazy);
+*   <div popover>{showContent() && children}</div>
+*
+* 浮层（Popover、HoverCard、Menu、对话框与抽屉）默认延迟：一百个关闭的菜单挂载 118ms → 12ms；
+* Collapse、Tabs 默认不延迟（收起的内容页内搜索要找得到）。Tooltip 不延迟：它被触发器的 aria-describedby 引用。
+*/
+function useLazyContent(open, lazy) {
+	let opened = false;
+	return () => {
+		if (open()) opened = true;
+		return opened || !lazy();
+	};
+}
+//#endregion
+export { useDismissible, useLazyContent, usePresence };
+
+//# sourceMappingURL=presence.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"presence.js","names":[],"sources":["../../../src/utils/motion/presence.ts"],"sourcesContent":["/**\n * 离场动画的统一流程：关闭后先保持挂载、写 data-state=\"closed\"，等离场（CSS 过渡或 Anime.js）结束再卸载。\n *\n *   const presence = usePresence(() => open, { onExited: () => emit('removed') });\n *   return () => presence.mounted && <div ref={presence.ref} data-state={presence.state} … />;\n *   // 样式里按 state 写离场的终值与过渡：presence.state === 'closed' && styles.leaving\n *\n * 离场中又打开了就停在打开状态，不卸载、不调用 onExited。元素自己决定是否卸载时（Toast、Tag）只用 state 与 onExited。\n */\nimport { computed, nextTick, onScopeDispose, shallowRef, watch } from 'vue';\nimport { toElement } from '../dom/element';\nimport { focusAfterRemoval } from '../dom/focus';\nimport { afterTransitions } from '../style/transitions';\n\n/** usePresence 的返回值 */\nexport interface Presence {\n  /** 是否渲染：打开时，以及关闭后离场还没结束时 */\n  readonly mounted: boolean;\n  /** 打开还是正在离场（写到 data-state） */\n  readonly state: 'open' | 'closed';\n  /** 离场过渡所在的元素（或组件）的 ref：等它与子元素上的过渡结束 */\n  ref: (element: unknown) => void;\n}\n\n/** usePresence 的选项 */\nexport interface PresenceOptions {\n  /** 离场结束、mounted 变为 false 之后调用 */\n  onExited?: () => void;\n  /** JS 离场动画（如 Anime.js）：关闭状态渲染后调用，等它结束；CSS 过渡不用写，会自动等 */\n  exit?: (element: HTMLElement) => PromiseLike<unknown> | void;\n}\n\n/** 关闭后等离场结束再卸载（在 setup 里调用） */\nexport function usePresence(\n  read: () => boolean,\n  { onExited, exit }: PresenceOptions = {},\n): Presence {\n  const open = computed(read);\n  const mounted = shallowRef(open.value);\n  let element: HTMLElement | null = null;\n  // 每次开关换一个编号：离场途中又打开（或组件卸载）时，旧的离场流程作废\n  let generation = 0;\n  onScopeDispose(() => generation++);\n\n  watch(open, async (value) => {\n    const current = ++generation;\n    if (value) {\n      mounted.value = true;\n      return;\n    }\n    // 等关闭状态写进 DOM，过渡才开始\n    await nextTick();\n    if (element) {\n      await exit?.(element);\n      await afterTransitions(element);\n    }\n    if (current !== generation) return;\n    mounted.value = false;\n    onExited?.();\n  });\n\n  return {\n    get mounted() {\n      return mounted.value;\n    },\n    get state() {\n      return open.value ? 'open' : 'closed';\n    },\n    ref: (value) => (element = toElement(value)),\n  };\n}\n\n/** useDismissible 的返回值 */\nexport interface Dismissible {\n  /** 正在离场：样式里写离场的终值与过渡 */\n  readonly dismissing: boolean;\n  /** 打开还是正在离场（写到 data-state） */\n  readonly state: 'open' | 'closed';\n  /** 根元素（或组件）的 ref */\n  ref: (element: unknown) => void;\n  /** 开始离场：焦点先移到相邻的可聚焦元素上（关闭按钮随它一起消失），离场结束调用 onDismiss；正在离场时什么也不做 */\n  readonly dismiss: () => void;\n}\n\n/**\n * 先离场再移除：可关闭的标签、提示条、横幅共用（Tag、Alert、Banner）。数据由使用方控制：\n * 离场结束才调用 onDismiss，使用方移除了就消失；没移除（如拒绝删除）时复位，元素重新出现。在 setup 里调用\n *\n *   const dismissible = useDismissible(() => onClose?.());\n *   <div ref={dismissible.ref} data-state={dismissible.state} {...css.attrs(dismissible.dismissing && styles.leaving)}>\n *     <CloseButton onClick={dismissible.dismiss} />\n */\nexport function useDismissible(onDismiss: () => void): Dismissible {\n  const dismissing = shallowRef(false);\n  let element: HTMLElement | null = null;\n  const presence = usePresence(() => !dismissing.value, {\n    onExited: () => {\n      dismissing.value = false;\n      onDismiss();\n    },\n  });\n  return {\n    get dismissing() {\n      return dismissing.value;\n    },\n    get state() {\n      return presence.state;\n    },\n    ref: (value) => {\n      element = toElement(value);\n      presence.ref(value);\n    },\n    dismiss: () => {\n      if (dismissing.value) return;\n      if (element) focusAfterRemoval(element);\n      dismissing.value = true;\n    },\n  };\n}\n\n/**\n * 内容延迟渲染：lazy 时第一次打开前不渲染，打开过之后一直保留（再次打开、离场过渡都不必重建）。\n * 在 setup 里调用，返回的函数在渲染时调用；渲染本来就读 open，打开时会重新渲染，所以不需要响应式状态。\n *\n *   const showContent = useLazyContent(() => open, () => lazy);\n *   <div popover>{showContent() && children}</div>\n *\n * 浮层（Popover、HoverCard、Menu、对话框与抽屉）默认延迟：一百个关闭的菜单挂载 118ms → 12ms；\n * Collapse、Tabs 默认不延迟（收起的内容页内搜索要找得到）。Tooltip 不延迟：它被触发器的 aria-describedby 引用。\n */\nexport function useLazyContent(open: () => boolean, lazy: () => boolean): () => boolean {\n  let opened = false;\n  return () => {\n    if (open()) opened = true;\n    return opened || !lazy();\n  };\n}\n\n/** 浮层的内容延迟渲染（Popover、HoverCard、Menu、对话框与抽屉共用） */\nexport interface LazyContentOptions {\n  /**\n   * 第一次打开前不渲染内容，打开过后保留，默认 true。\n   * 内容要一直在 DOM 里（页内搜索、关闭时也要查询其中的元素）时设为 false\n   */\n  lazy?: boolean;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAiCA,SAAgB,YACd,MACA,EAAE,UAAU,SAA0B,CAAC,GAC7B;CACV,MAAM,OAAO,SAAS,IAAI;CAC1B,MAAM,UAAU,WAAW,KAAK,KAAK;CACrC,IAAI,UAA8B;CAElC,IAAI,aAAa;CACjB,qBAAqB,YAAY;CAEjC,MAAM,MAAM,OAAO,UAAU;EAC3B,MAAM,UAAU,EAAE;EAClB,IAAI,OAAO;GACT,QAAQ,QAAQ;GAChB;EACF;EAEA,MAAM,SAAS;EACf,IAAI,SAAS;GACX,MAAM,OAAO,OAAO;GACpB,MAAM,iBAAiB,OAAO;EAChC;EACA,IAAI,YAAY,YAAY;EAC5B,QAAQ,QAAQ;EAChB,WAAW;CACb,CAAC;CAED,OAAO;EACL,IAAI,UAAU;GACZ,OAAO,QAAQ;EACjB;EACA,IAAI,QAAQ;GACV,OAAO,KAAK,QAAQ,SAAS;EAC/B;EACA,MAAM,UAAW,UAAU,UAAU,KAAK;CAC5C;AACF;;;;;;;;;AAsBA,SAAgB,eAAe,WAAoC;CACjE,MAAM,aAAa,WAAW,KAAK;CACnC,IAAI,UAA8B;CAClC,MAAM,WAAW,kBAAkB,CAAC,WAAW,OAAO,EACpD,gBAAgB;EACd,WAAW,QAAQ;EACnB,UAAU;CACZ,EACF,CAAC;CACD,OAAO;EACL,IAAI,aAAa;GACf,OAAO,WAAW;EACpB;EACA,IAAI,QAAQ;GACV,OAAO,SAAS;EAClB;EACA,MAAM,UAAU;GACd,UAAU,UAAU,KAAK;GACzB,SAAS,IAAI,KAAK;EACpB;EACA,eAAe;GACb,IAAI,WAAW,OAAO;GACtB,IAAI,SAAS,kBAAkB,OAAO;GACtC,WAAW,QAAQ;EACrB;CACF;AACF;;;;;;;;;;;AAYA,SAAgB,eAAe,MAAqB,MAAoC;CACtF,IAAI,SAAS;CACb,aAAa;EACX,IAAI,KAAK,GAAG,SAAS;EACrB,OAAO,UAAU,CAAC,KAAK;CACzB;AACF"}

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

@@ -0,0 +1,9 @@
+/** 圆形展开的起点（视口坐标，px） */
+export interface RevealOrigin {
+    /** 横坐标 */
+    x: number;
+    /** 纵坐标 */
+    y: number;
+}
+/** 执行 update（改主题、换页面），能过渡时从 origin 圆形展开新画面；返回过渡开始后兑现的 Promise */
+export declare function revealTransition(update: () => void, origin?: RevealOrigin): Promise<void>;

package/dist/utils/motion/reveal.js

@@ -0,0 +1,68 @@
+import { durations, easings } from "../../config/theme/tokens.js";
+import { readToken } from "../../config/theme/theme.js";
+import { parseDuration } from "./animation.js";
+import { nextTick } from "vue";
+//#region src/utils/motion/reveal.ts
+/**
+* 整页切换的过渡（View Transitions API）：从一个点圆形展开新画面，用于切换主题这类整页变化。
+*
+*   revealTransition(() => (theme = next), { x: event.clientX, y: event.clientY });
+*
+* 浏览器不支持 View Transitions、或开启了“减少动态效果”时直接更新；没给起点时是浏览器默认的淡入淡出。
+* 时长与缓动取主题 tokens（durations.lg、easings.standard）。
+*/
+/**
+* 圆形展开时去掉浏览器默认的淡入淡出：只插入一次，只对带 data-vtp-reveal 的根元素生效（转场期间才带），
+* 不影响宿主自己的 View Transitions
+*/
+var styleInserted = false;
+function insertRevealStyle() {
+	if (styleInserted) return;
+	styleInserted = true;
+	const style = document.createElement("style");
+	style.dataset.vtpReveal = "";
+	style.textContent = ":root[data-vtp-reveal]::view-transition-old(root),:root[data-vtp-reveal]::view-transition-new(root){animation:none;mix-blend-mode:normal}";
+	document.head.append(style);
+}
+/** 执行 update（改主题、换页面），能过渡时从 origin 圆形展开新画面；返回过渡开始后兑现的 Promise */
+async function revealTransition(update, origin) {
+	const doc = typeof document === "undefined" ? void 0 : document;
+	const reduced = globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+	if (!doc?.startViewTransition || reduced) {
+		update();
+		return;
+	}
+	const root = doc.documentElement;
+	if (origin) {
+		insertRevealStyle();
+		root.dataset.vtpReveal = "";
+	}
+	let failed = false;
+	const transition = doc.startViewTransition(async () => {
+		try {
+			update();
+		} catch (error) {
+			failed = true;
+			throw error;
+		}
+		await nextTick();
+	});
+	transition.finished.finally(() => delete root.dataset.vtpReveal).catch(() => {});
+	try {
+		await transition.ready;
+	} catch (error) {
+		if (failed) throw error;
+		return;
+	}
+	if (!origin) return;
+	const radius = Math.hypot(Math.max(origin.x, innerWidth - origin.x), Math.max(origin.y, innerHeight - origin.y));
+	root.animate({ clipPath: [`circle(0px at ${origin.x}px ${origin.y}px)`, `circle(${radius}px at ${origin.x}px ${origin.y}px)`] }, {
+		duration: parseDuration(readToken(root, durations.lg)),
+		easing: readToken(root, easings.standard),
+		pseudoElement: "::view-transition-new(root)"
+	});
+}
+//#endregion
+export { revealTransition };
+
+//# sourceMappingURL=reveal.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reveal.js","names":[],"sources":["../../../src/utils/motion/reveal.ts"],"sourcesContent":["/**\n * 整页切换的过渡（View Transitions API）：从一个点圆形展开新画面，用于切换主题这类整页变化。\n *\n *   revealTransition(() => (theme = next), { x: event.clientX, y: event.clientY });\n *\n * 浏览器不支持 View Transitions、或开启了“减少动态效果”时直接更新；没给起点时是浏览器默认的淡入淡出。\n * 时长与缓动取主题 tokens（durations.lg、easings.standard）。\n */\nimport { nextTick } from 'vue';\nimport { durations, easings } from '../../config/theme/tokens';\nimport { readToken } from '../../config/theme/theme';\nimport { parseDuration } from './animation';\n\n/** 圆形展开的起点（视口坐标，px） */\nexport interface RevealOrigin {\n  /** 横坐标 */\n  x: number;\n  /** 纵坐标 */\n  y: number;\n}\n\ntype ViewTransitionDocument = Document & {\n  startViewTransition?: (update: () => Promise<void>) => {\n    ready: Promise<void>;\n    finished: Promise<void>;\n  };\n};\n\n/**\n * 圆形展开时去掉浏览器默认的淡入淡出：只插入一次，只对带 data-vtp-reveal 的根元素生效（转场期间才带），\n * 不影响宿主自己的 View Transitions\n */\nlet styleInserted = false;\nfunction insertRevealStyle() {\n  if (styleInserted) return;\n  styleInserted = true;\n  const style = document.createElement('style');\n  style.dataset.vtpReveal = '';\n  style.textContent =\n    ':root[data-vtp-reveal]::view-transition-old(root),:root[data-vtp-reveal]::view-transition-new(root){animation:none;mix-blend-mode:normal}';\n  document.head.append(style);\n}\n\n/** 执行 update（改主题、换页面），能过渡时从 origin 圆形展开新画面；返回过渡开始后兑现的 Promise */\nexport async function revealTransition(update: () => void, origin?: RevealOrigin): Promise<void> {\n  const doc = typeof document === 'undefined' ? undefined : (document as ViewTransitionDocument);\n  const reduced = globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches;\n  if (!doc?.startViewTransition || reduced) {\n    update();\n    return;\n  }\n  const root = doc.documentElement;\n  if (origin) {\n    insertRevealStyle();\n    root.dataset.vtpReveal = '';\n  }\n  let failed = false;\n  const transition = doc.startViewTransition(async () => {\n    try {\n      update();\n    } catch (error) {\n      failed = true;\n      throw error;\n    }\n    // 等 Vue 把新主题写进 DOM，浏览器才截到新画面\n    await nextTick();\n  });\n  void transition.finished.finally(() => delete root.dataset.vtpReveal).catch(() => {});\n  try {\n    await transition.ready;\n  } catch (error) {\n    // update 出错照常抛给调用方；转场被跳过（又开始了一个）时没有动画可做，不算错误\n    if (failed) throw error;\n    return;\n  }\n  if (!origin) return;\n  const radius = Math.hypot(\n    Math.max(origin.x, innerWidth - origin.x),\n    Math.max(origin.y, innerHeight - origin.y),\n  );\n  root.animate(\n    {\n      clipPath: [\n        `circle(0px at ${origin.x}px ${origin.y}px)`,\n        `circle(${radius}px at ${origin.x}px ${origin.y}px)`,\n      ],\n    },\n    {\n      duration: parseDuration(readToken(root, durations.lg)),\n      easing: readToken(root, easings.standard),\n      pseudoElement: '::view-transition-new(root)',\n    },\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAgCA,IAAI,gBAAgB;AACpB,SAAS,oBAAoB;CAC3B,IAAI,eAAe;CACnB,gBAAgB;CAChB,MAAM,QAAQ,SAAS,cAAc,OAAO;CAC5C,MAAM,QAAQ,YAAY;CAC1B,MAAM,cACJ;CACF,SAAS,KAAK,OAAO,KAAK;AAC5B;;AAGA,eAAsB,iBAAiB,QAAoB,QAAsC;CAC/F,MAAM,MAAM,OAAO,aAAa,cAAc,KAAA,IAAa;CAC3D,MAAM,UAAU,WAAW,aAAa,kCAAkC,CAAC,CAAC;CAC5E,IAAI,CAAC,KAAK,uBAAuB,SAAS;EACxC,OAAO;EACP;CACF;CACA,MAAM,OAAO,IAAI;CACjB,IAAI,QAAQ;EACV,kBAAkB;EAClB,KAAK,QAAQ,YAAY;CAC3B;CACA,IAAI,SAAS;CACb,MAAM,aAAa,IAAI,oBAAoB,YAAY;EACrD,IAAI;GACF,OAAO;EACT,SAAS,OAAO;GACd,SAAS;GACT,MAAM;EACR;EAEA,MAAM,SAAS;CACjB,CAAC;CACD,WAAgB,SAAS,cAAc,OAAO,KAAK,QAAQ,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC;CACpF,IAAI;EACF,MAAM,WAAW;CACnB,SAAS,OAAO;EAEd,IAAI,QAAQ,MAAM;EAClB;CACF;CACA,IAAI,CAAC,QAAQ;CACb,MAAM,SAAS,KAAK,MAClB,KAAK,IAAI,OAAO,GAAG,aAAa,OAAO,CAAC,GACxC,KAAK,IAAI,OAAO,GAAG,cAAc,OAAO,CAAC,CAC3C;CACA,KAAK,QACH,EACE,UAAU,CACR,iBAAiB,OAAO,EAAE,KAAK,OAAO,EAAE,MACxC,UAAU,OAAO,QAAQ,OAAO,EAAE,KAAK,OAAO,EAAE,IAClD,EACF,GACA;EACE,UAAU,cAAc,UAAU,MAAM,UAAU,EAAE,CAAC;EACrD,QAAQ,UAAU,MAAM,QAAQ,QAAQ;EACxC,eAAe;CACjB,CACF;AACF"}

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

@@ -0,0 +1,34 @@
+import { type ThemeTransitionOptions } from './animation';
+/** useTween / useSpring 的返回值 */
+export interface Tweened {
+    /** 当前值：过渡中逐帧变化，响应式 */
+    readonly current: number;
+    /** 目标值：read 的最新结果 */
+    readonly target: number;
+}
+/** useTween 的选项 */
+export interface TweenOptions {
+    /** 时长档位，默认 md */
+    duration?: ThemeTransitionOptions['duration'];
+    /** 缓动曲线，默认 standard */
+    ease?: ThemeTransitionOptions['ease'];
+    /** 挂载时从这个值过渡到第一个目标；不给时第一个目标直接显示 */
+    from?: number;
+    /** 读哪个元素上的主题时长（子树里覆盖了主题时），默认根元素 */
+    scope?: () => Element | null | undefined;
+}
+/** useSpring 的选项 */
+export interface SpringOptions {
+    /** 回弹程度（0 不回弹，越大越弹，建议不超过 0.5），默认 0.25 */
+    bounce?: number;
+    /** 弹簧的感知时长档位，默认 md */
+    duration?: ThemeTransitionOptions['duration'];
+    /** 挂载时从这个值过渡到第一个目标；不给时第一个目标直接显示 */
+    from?: number;
+    /** 读哪个元素上的主题时长，默认根元素 */
+    scope?: () => Element | null | undefined;
+}
+/** 数值变化时按主题时长与缓动过渡（在 setup 里调用） */
+export declare function useTween(read: () => number, { from, scope, ...transition }?: TweenOptions): Tweened;
+/** 数值变化时用弹簧过渡（在 setup 里调用） */
+export declare function useSpring(read: () => number, { from, bounce, duration, scope }?: SpringOptions): Tweened;

package/dist/utils/motion/tween.js

@@ -0,0 +1,50 @@
+import { useAnimate } from "./animation.js";
+import { computed, shallowRef, watch } from "vue";
+//#region src/utils/motion/tween.ts
+/**
+* 跟随数值的过渡（对标 Svelte 5 的 Tween / Spring）：read 的结果变化时，current 从当前值过渡到新值。
+*
+*   const shown = useTween(() => value, { duration: 'lg' });   // 渲染里读 shown.current
+*   const scale = useSpring(() => (pressed ? 0.95 : 1));
+*
+* 用 Anime.js 驱动一个普通对象，逐帧写进 shallowRef；时长、缓动、弹簧取主题（useAnimate），
+* 减少动态效果时当场到位。过渡中目标又变了，从当时的值接着过渡到新目标。
+*/
+/** 数值变化时按主题时长与缓动过渡（在 setup 里调用） */
+function useTween(read, { from, scope, ...transition } = {}) {
+	return useTweened(read, from, transition, scope);
+}
+/** 数值变化时用弹簧过渡（在 setup 里调用） */
+function useSpring(read, { from, bounce = .25, duration, scope } = {}) {
+	return useTweened(read, from, {
+		bounce,
+		duration
+	}, scope);
+}
+function useTweened(read, from, transition, scope) {
+	const animate = useAnimate();
+	const target = computed(read);
+	const state = { value: from ?? target.value };
+	const current = shallowRef(state.value);
+	watch(target, (value) => {
+		animate(state, {
+			value,
+			onUpdate: () => current.value = state.value
+		}, {
+			...transition,
+			scope: scope?.() ?? void 0
+		});
+	}, { immediate: from != null });
+	return {
+		get current() {
+			return current.value;
+		},
+		get target() {
+			return target.value;
+		}
+	};
+}
+//#endregion
+export { useSpring, useTween };
+
+//# sourceMappingURL=tween.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tween.js","names":[],"sources":["../../../src/utils/motion/tween.ts"],"sourcesContent":["/**\n * 跟随数值的过渡（对标 Svelte 5 的 Tween / Spring）：read 的结果变化时，current 从当前值过渡到新值。\n *\n *   const shown = useTween(() => value, { duration: 'lg' });   // 渲染里读 shown.current\n *   const scale = useSpring(() => (pressed ? 0.95 : 1));\n *\n * 用 Anime.js 驱动一个普通对象，逐帧写进 shallowRef；时长、缓动、弹簧取主题（useAnimate），\n * 减少动态效果时当场到位。过渡中目标又变了，从当时的值接着过渡到新目标。\n */\nimport { computed, shallowRef, watch } from 'vue';\nimport { useAnimate, type ThemeTransitionOptions } from './animation';\n\n/** useTween / useSpring 的返回值 */\nexport interface Tweened {\n  /** 当前值：过渡中逐帧变化，响应式 */\n  readonly current: number;\n  /** 目标值：read 的最新结果 */\n  readonly target: number;\n}\n\n/** useTween 的选项 */\nexport interface TweenOptions {\n  /** 时长档位，默认 md */\n  duration?: ThemeTransitionOptions['duration'];\n  /** 缓动曲线，默认 standard */\n  ease?: ThemeTransitionOptions['ease'];\n  /** 挂载时从这个值过渡到第一个目标；不给时第一个目标直接显示 */\n  from?: number;\n  /** 读哪个元素上的主题时长（子树里覆盖了主题时），默认根元素 */\n  scope?: () => Element | null | undefined;\n}\n\n/** useSpring 的选项 */\nexport interface SpringOptions {\n  /** 回弹程度（0 不回弹，越大越弹，建议不超过 0.5），默认 0.25 */\n  bounce?: number;\n  /** 弹簧的感知时长档位，默认 md */\n  duration?: ThemeTransitionOptions['duration'];\n  /** 挂载时从这个值过渡到第一个目标；不给时第一个目标直接显示 */\n  from?: number;\n  /** 读哪个元素上的主题时长，默认根元素 */\n  scope?: () => Element | null | undefined;\n}\n\n/** 数值变化时按主题时长与缓动过渡（在 setup 里调用） */\nexport function useTween(\n  read: () => number,\n  { from, scope, ...transition }: TweenOptions = {},\n): Tweened {\n  return useTweened(read, from, transition, scope);\n}\n\n/** 数值变化时用弹簧过渡（在 setup 里调用） */\nexport function useSpring(\n  read: () => number,\n  { from, bounce = 0.25, duration, scope }: SpringOptions = {},\n): Tweened {\n  return useTweened(read, from, { bounce, duration }, scope);\n}\n\nfunction useTweened(\n  read: () => number,\n  from: number | undefined,\n  transition: ThemeTransitionOptions,\n  scope?: () => Element | null | undefined,\n): Tweened {\n  const animate = useAnimate();\n  const target = computed(read);\n  // Anime.js 改的是这个普通对象，每帧再同步给响应式的 current\n  const state = { value: from ?? target.value };\n  const current = shallowRef(state.value);\n  watch(\n    target,\n    (value) => {\n      void animate(\n        state,\n        { value, onUpdate: () => (current.value = state.value) },\n        { ...transition, scope: scope?.() ?? undefined },\n      );\n    },\n    { immediate: from != null },\n  );\n  return {\n    get current() {\n      return current.value;\n    },\n    get target() {\n      return target.value;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;AA6CA,SAAgB,SACd,MACA,EAAE,MAAM,OAAO,GAAG,eAA6B,CAAC,GACvC;CACT,OAAO,WAAW,MAAM,MAAM,YAAY,KAAK;AACjD;;AAGA,SAAgB,UACd,MACA,EAAE,MAAM,SAAS,KAAM,UAAU,UAAyB,CAAC,GAClD;CACT,OAAO,WAAW,MAAM,MAAM;EAAE;EAAQ;CAAS,GAAG,KAAK;AAC3D;AAEA,SAAS,WACP,MACA,MACA,YACA,OACS;CACT,MAAM,UAAU,WAAW;CAC3B,MAAM,SAAS,SAAS,IAAI;CAE5B,MAAM,QAAQ,EAAE,OAAO,QAAQ,OAAO,MAAM;CAC5C,MAAM,UAAU,WAAW,MAAM,KAAK;CACtC,MACE,SACC,UAAU;EACT,QACE,OACA;GAAE;GAAO,gBAAiB,QAAQ,QAAQ,MAAM;EAAO,GACvD;GAAE,GAAG;GAAY,OAAO,QAAQ,KAAK,KAAA;EAAU,CACjD;CACF,GACA,EAAE,WAAW,QAAQ,KAAK,CAC5B;CACA,OAAO;EACL,IAAI,UAAU;GACZ,OAAO,QAAQ;EACjB;EACA,IAAI,SAAS;GACX,OAAO,OAAO;EAChB;CACF;AACF"}

package/dist/utils/props.d.ts

@@ -0,0 +1,84 @@
+import type { IntrinsicProps, JSX } from '@zerodep-dev/vue-tsx-pro-tsx/jsx-runtime';
+import '../config/theme/tokens';
+import type { StyleAttrs, SxStyles } from '@zerodep-dev/vue-tsx-pro-tsx/styles';
+import type { VNodeChild } from 'vue';
+/**
+ * 原生元素部件的 props：该元素的属性加上 sx；去掉组件管理的属性与 children（内容走组件自己的 prop）。
+ * 形如 `propsInput?: PartProps<'input', 'value' | 'aria-invalid'>`。
+ */
+export type PartProps<Tag extends keyof JSX.IntrinsicElements, Managed extends string = never> = Omit<IntrinsicProps<Tag>, Managed | 'children'> & {
+    sx?: SxStyles;
+};
+/**
+ * 展开收起类组件（Collapsible、Popover）交给触发器的属性：展开到任意可聚焦元素上，
+ * 形如 `trigger={(props) => <Button {...props}>更多</Button>}`。弹层另外加上 id、ref、aria-haspopup。
+ */
+export interface TriggerProps {
+    /** 切换展开与收起 */
+    onClick: (event: MouseEvent) => void;
+    /** 当前是否展开，读屏据此播报“已展开 / 已折叠” */
+    'aria-expanded': boolean;
+    /** 被控制的内容区的 id */
+    'aria-controls': string;
+    /** 不可用：组件设了 disabled 时为 true，展开到按钮上就是原生的 disabled */
+    disabled?: boolean;
+}
+/**
+ * data-* 属性写进对象字面量（部件属性、mergeAttrs 的各层）：元素的属性类型不收 data-* 键，
+ * 用它包一层再展开。JSX 上直接写 data-* 不需要它。
+ *
+ *   mergeAttrs<'td'>(defaults, user, { role: 'gridcell', ...dataAttrs({ 'data-in-range': inRange || undefined }) })
+ */
+export declare const dataAttrs: (attrs: Record<`data-${string}`, string | number | boolean | undefined>) => Record<`data-${string}`, string | number | boolean | undefined>;
+type Props = Record<string, unknown>;
+/**
+ * 一层属性：Target 是标签名（'svg'）时为该元素的属性加 sx，是 props 类型（IconProps）时就是它。
+ * 标签名的联合（'h1' | 'h2'，一个工厂生成的几个组件共用实现时）取这些标签共有的属性，所以这里不按联合分配
+ */
+type PropsLayer<Target> = Partial<[
+    Target
+] extends [keyof JSX.IntrinsicElements] ? PartProps<Target> : Target>;
+/**
+ * 合并部件的三层属性：组件默认、使用方传入、组件受管，规则见文件开头。
+ * 用类型参数写明属性落到哪里，三层的对象字面量才有补全、悬停说明与类型检查：
+ *   mergeProps<IconProps>({ sx: … }, propsIcon)；原生元素用 mergeAttrs<'svg'>(默认, rest, 受管)
+ *
+ * 渲染里每个部件每次都要合并，按最常见的情况走捷径：只有默认层时原样返回；
+ * 只有两层以上都给了同名事件时才包一层回调。
+ */
+export declare function mergeProps<Target = Props>(defaults: PropsLayer<Target>, user?: PropsLayer<Target>, managed?: PropsLayer<Target>): PropsLayer<Target>;
+/**
+ * 子组件部件的合并：mergeProps 的规则，但默认层要写齐子组件的必填 props（如 Icon 的 icon），
+ * 返回完整的 props 类型，展开到子组件上不必再断言：
+ *   <Icon {...mergePartProps<IconProps>({ icon: X, sx: styles.icon }, propsIcon)} />
+ */
+export declare function mergePartProps<P extends object>(defaults: P, user?: Partial<P>, managed?: Partial<P>): P;
+/**
+ * 原生元素部件的合并：mergeProps 的规则，再把 sx 换成 class 与 style（elementProps），结果直接展开到元素上：
+ *   <svg {...mergeAttrs<'svg'>({ sx: styles.icon }, rest, { 'aria-hidden': true })} />
+ */
+export declare function mergeAttrs<Tag extends keyof JSX.IntrinsicElements>(defaults: PropsLayer<Tag>, user?: PropsLayer<Tag>, managed?: PropsLayer<Tag>): Omit<PropsLayer<Tag>, 'sx' | 'children'>;
+/**
+ * 原生元素部件：把 sx 换成样式引擎生成的 class 与 style，再与已有的 class、style 合并。
+ * 去掉 children：它是内容不是元素属性（组件的 ...rest 里带着它，转交给子组件时要用）。
+ */
+export declare function elementProps<P extends object>(props: P): Omit<P, 'sx' | 'children'>;
+/**
+ * 默认的 aria-labelledby（Field 的标签、弹层的触发器）：使用方写的 aria-labelledby 优先；使用方写了 aria-label 时
+ * 不加默认的（aria-labelledby 会盖过 aria-label，使用方写的名称就白写了）
+ */
+export declare function defaultLabelledBy(attrs: {
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+}, fallback: string | undefined): string | undefined;
+/**
+ * 内容（插槽、标题、说明、错误这类 VNodeChild）有没有东西：null、undefined、空字符串与布尔都算没有。
+ * 使用方常写 `error={cond && '…'}`、`aside={wide && <Panel />}`，条件不成立时是 false，不该渲染出空的外层
+ */
+export declare function hasContent(node: VNodeChild): boolean;
+/**
+ * 把 css.attrs 的结果写到命令式创建的元素上（波纹、量取主题的探针）：class 与行内样式，
+ * 自定义属性（动态样式的变量）名字原样、用 setProperty
+ */
+export declare function applyStyleAttrs(element: HTMLElement, { class: className, style }: StyleAttrs): void;
+export {};

package/dist/utils/props.js

@@ -0,0 +1,189 @@
+import "../config/theme/tokens.js";
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+//#region src/utils/props.ts
+/**
+* 部件 props 的类型与合并规则（COMPONENTS.md §2）。
+*
+* 组件给部件的属性分两层：可被使用方覆盖的默认属性（defaults），以及组件状态决定、
+* 不允许覆盖的受管属性（managed，如 role、aria-expanded）。合并规则：
+*   - sx：默认在前、使用方其次、受管最后，后者覆盖前者
+*   - class、style：依次排列成数组，交给 Vue 统一处理（它们也可能是数组或对象）
+*   - 事件 onXxx：使用方先执行，调用了 event.preventDefault() 就跳过组件自己的处理
+*   - ref：各方都拿到元素
+*   - 其他属性：受管 > 使用方 > 默认
+*/
+/**
+* data-* 属性写进对象字面量（部件属性、mergeAttrs 的各层）：元素的属性类型不收 data-* 键，
+* 用它包一层再展开。JSX 上直接写 data-* 不需要它。
+*
+*   mergeAttrs<'td'>(defaults, user, { role: 'gridcell', ...dataAttrs({ 'data-in-range': inRange || undefined }) })
+*/
+var dataAttrs = (attrs) => attrs;
+/**
+* 合并部件的三层属性：组件默认、使用方传入、组件受管，规则见文件开头。
+* 用类型参数写明属性落到哪里，三层的对象字面量才有补全、悬停说明与类型检查：
+*   mergeProps<IconProps>({ sx: … }, propsIcon)；原生元素用 mergeAttrs<'svg'>(默认, rest, 受管)
+*
+* 渲染里每个部件每次都要合并，按最常见的情况走捷径：只有默认层时原样返回；
+* 只有两层以上都给了同名事件时才包一层回调。
+*/
+function mergeProps(defaults, user, managed) {
+	const base = defaults;
+	const own = hasKeys(user) ? user : void 0;
+	const fixed = hasKeys(managed) ? managed : void 0;
+	if (!own && !fixed) return defaults;
+	const merged = {
+		...base,
+		...own,
+		...fixed
+	};
+	for (const key of LISTED_KEYS) {
+		const values = present3(base[key], own?.[key], fixed?.[key]);
+		if (values) merged[key] = values;
+	}
+	const refs = present3(base.ref, own?.ref, fixed?.ref);
+	if (refs && refs.length > 1) merged.ref = (element) => refs.forEach((ref) => setRef(ref, element));
+	if (own) for (const key in own) {
+		if (!isHandlerKey(key)) continue;
+		if (base[key] == null && fixed?.[key] == null) {
+			merged[key] = own[key];
+			continue;
+		}
+		merged[key] = mergeHandlers(own[key], [base[key], fixed?.[key]]) ?? fixed?.[key] ?? base[key];
+	}
+	if (fixed) for (const key in fixed) {
+		if (!isHandlerKey(key) || base[key] == null || own && key in own) continue;
+		const handler = mergeHandlers(void 0, [base[key], fixed[key]]);
+		if (handler) merged[key] = handler;
+	}
+	return merged;
+}
+/**
+* 子组件部件的合并：mergeProps 的规则，但默认层要写齐子组件的必填 props（如 Icon 的 icon），
+* 返回完整的 props 类型，展开到子组件上不必再断言：
+*   <Icon {...mergePartProps<IconProps>({ icon: X, sx: styles.icon }, propsIcon)} />
+*/
+function mergePartProps(defaults, user, managed) {
+	return mergeProps(defaults, user, managed);
+}
+/**
+* 原生元素部件的合并：mergeProps 的规则，再把 sx 换成 class 与 style（elementProps），结果直接展开到元素上：
+*   <svg {...mergeAttrs<'svg'>({ sx: styles.icon }, rest, { 'aria-hidden': true })} />
+*/
+function mergeAttrs(defaults, user, managed) {
+	return elementProps(mergeProps(defaults, user, managed));
+}
+/**
+* 原生元素部件：把 sx 换成样式引擎生成的 class 与 style，再与已有的 class、style 合并。
+* 去掉 children：它是内容不是元素属性（组件的 ...rest 里带着它，转交给子组件时要用）。
+*/
+function elementProps(props) {
+	const { sx, children: _children, ...rest } = props;
+	if (sx == null) return rest;
+	const compiled = compileSx(sx);
+	const element = rest;
+	if (compiled.ref && element.ref != null) {
+		const own = element.ref;
+		const bound = compiled.ref;
+		element.ref = (target) => {
+			setRef(own, target);
+			bound(target);
+		};
+	} else if (compiled.ref) element.ref = compiled.ref;
+	if (rest.class == null && rest.style == null) {
+		if (compiled.class != null) element.class = compiled.class;
+		if (compiled.style != null) element.style = compiled.style;
+		return rest;
+	}
+	element.class = present3(rest.class, compiled.class) ?? [];
+	element.style = present3(compiled.style, rest.style) ?? [];
+	return rest;
+}
+/**
+* 编译好的样式是不变的常量：单个样式（不是数组）按对象缓存 css.attrs 的结果，
+* 根元素、图标这类每次渲染都是同一个样式的部件不必重复合并
+*/
+var compiledCache = /* @__PURE__ */ new WeakMap();
+function compileSx(sx) {
+	if (Array.isArray(sx) || typeof sx !== "object" || sx === null) return css.attrs(sx);
+	let compiled = compiledCache.get(sx);
+	if (!compiled) compiledCache.set(sx, compiled = css.attrs(sx));
+	return compiled;
+}
+/** onClick、onUpdate:_value：on 后面跟大写字母 */
+function isHandlerKey(key) {
+	const third = key.charCodeAt(2);
+	return key.charCodeAt(0) === 111 && key.charCodeAt(1) === 110 && third >= 65 && third <= 90;
+}
+function hasKeys(layer) {
+	if (!layer) return false;
+	for (const _ in layer) return true;
+	return false;
+}
+/**
+* 使用方的回调先执行，它调用了 event.preventDefault() 就跳过组件自己的回调。
+* 只有一方提供回调时返回 undefined，保留展开合并的结果即可。
+*/
+function mergeHandlers(user, internal) {
+	const own = present(internal);
+	if (own.length + (user ? 1 : 0) < 2) return void 0;
+	return (...args) => {
+		user?.(...args);
+		const event = args[0];
+		if (event instanceof Event && event.defaultPrevented) return;
+		own.forEach((handler) => handler(...args));
+	};
+}
+function setRef(ref, element) {
+	if (typeof ref === "function") ref(element);
+	else ref.value = element;
+}
+var present = (values) => values.filter((value) => value != null);
+/** 按层排列、要合并成数组的属性 */
+var LISTED_KEYS = [
+	"sx",
+	"class",
+	"style"
+];
+/** 最多三个值里不为空的那些，按原顺序成数组；都为空时返回 undefined。渲染路径上用，不建中间数组 */
+function present3(a, b, c) {
+	if (a == null) {
+		if (b == null) return c == null ? void 0 : [c];
+		return c == null ? [b] : [b, c];
+	}
+	if (b == null) return c == null ? [a] : [a, c];
+	return c == null ? [a, b] : [
+		a,
+		b,
+		c
+	];
+}
+/**
+* 默认的 aria-labelledby（Field 的标签、弹层的触发器）：使用方写的 aria-labelledby 优先；使用方写了 aria-label 时
+* 不加默认的（aria-labelledby 会盖过 aria-label，使用方写的名称就白写了）
+*/
+function defaultLabelledBy(attrs, fallback) {
+	return attrs["aria-labelledby"] ?? (attrs["aria-label"] == null ? fallback : void 0);
+}
+/**
+* 内容（插槽、标题、说明、错误这类 VNodeChild）有没有东西：null、undefined、空字符串与布尔都算没有。
+* 使用方常写 `error={cond && '…'}`、`aside={wide && <Panel />}`，条件不成立时是 false，不该渲染出空的外层
+*/
+function hasContent(node) {
+	return node != null && typeof node !== "boolean" && node !== "";
+}
+/**
+* 把 css.attrs 的结果写到命令式创建的元素上（波纹、量取主题的探针）：class 与行内样式，
+* 自定义属性（动态样式的变量）名字原样、用 setProperty
+*/
+function applyStyleAttrs(element, { class: className, style }) {
+	element.className = className ?? "";
+	for (const [name, value] of Object.entries(style ?? {})) {
+		const property = name.startsWith("--") ? name : name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+		element.style.setProperty(property, String(value));
+	}
+}
+//#endregion
+export { applyStyleAttrs, dataAttrs, defaultLabelledBy, elementProps, hasContent, mergeAttrs, mergePartProps, mergeProps };
+
+//# sourceMappingURL=props.js.map

package/dist/utils/props.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.js","names":[],"sources":["../../src/utils/props.ts"],"sourcesContent":["/**\n * 部件 props 的类型与合并规则（COMPONENTS.md §2）。\n *\n * 组件给部件的属性分两层：可被使用方覆盖的默认属性（defaults），以及组件状态决定、\n * 不允许覆盖的受管属性（managed，如 role、aria-expanded）。合并规则：\n *   - sx：默认在前、使用方其次、受管最后，后者覆盖前者\n *   - class、style：依次排列成数组，交给 Vue 统一处理（它们也可能是数组或对象）\n *   - 事件 onXxx：使用方先执行，调用了 event.preventDefault() 就跳过组件自己的处理\n *   - ref：各方都拿到元素\n *   - 其他属性：受管 > 使用方 > 默认\n */\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport type { IntrinsicProps, JSX } from '@zerodep-dev/vue-tsx-pro-tsx/jsx-runtime';\n// 登记主题 tokens（样式里的 '_md' 靠它）：每个组件都经过这里合并属性，渲染之前一定登记过\nimport '../config/theme/tokens';\nimport type { StyleAttrs, SxStyles } from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport type { Ref, VNodeChild } from 'vue';\n\n/**\n * 原生元素部件的 props：该元素的属性加上 sx；去掉组件管理的属性与 children（内容走组件自己的 prop）。\n * 形如 `propsInput?: PartProps<'input', 'value' | 'aria-invalid'>`。\n */\nexport type PartProps<\n  Tag extends keyof JSX.IntrinsicElements,\n  Managed extends string = never,\n> = Omit<IntrinsicProps<Tag>, Managed | 'children'> & { sx?: SxStyles };\n\n/**\n * 展开收起类组件（Collapsible、Popover）交给触发器的属性：展开到任意可聚焦元素上，\n * 形如 `trigger={(props) => <Button {...props}>更多</Button>}`。弹层另外加上 id、ref、aria-haspopup。\n */\nexport interface TriggerProps {\n  /** 切换展开与收起 */\n  onClick: (event: MouseEvent) => void;\n  /** 当前是否展开，读屏据此播报“已展开 / 已折叠” */\n  'aria-expanded': boolean;\n  /** 被控制的内容区的 id */\n  'aria-controls': string;\n  /** 不可用：组件设了 disabled 时为 true，展开到按钮上就是原生的 disabled */\n  disabled?: boolean;\n}\n\n/**\n * data-* 属性写进对象字面量（部件属性、mergeAttrs 的各层）：元素的属性类型不收 data-* 键，\n * 用它包一层再展开。JSX 上直接写 data-* 不需要它。\n *\n *   mergeAttrs<'td'>(defaults, user, { role: 'gridcell', ...dataAttrs({ 'data-in-range': inRange || undefined }) })\n */\nexport const dataAttrs = (attrs: Record<`data-${string}`, string | number | boolean | undefined>) =>\n  attrs;\n\ntype Props = Record<string, unknown>;\ntype Handler = (...args: unknown[]) => unknown;\ntype RefSetter = ((element: unknown) => void) | Ref<unknown>;\n\n/**\n * 一层属性：Target 是标签名（'svg'）时为该元素的属性加 sx，是 props 类型（IconProps）时就是它。\n * 标签名的联合（'h1' | 'h2'，一个工厂生成的几个组件共用实现时）取这些标签共有的属性，所以这里不按联合分配\n */\ntype PropsLayer<Target> = Partial<\n  [Target] extends [keyof JSX.IntrinsicElements] ? PartProps<Target> : Target\n>;\n\n/**\n * 合并部件的三层属性：组件默认、使用方传入、组件受管，规则见文件开头。\n * 用类型参数写明属性落到哪里，三层的对象字面量才有补全、悬停说明与类型检查：\n *   mergeProps<IconProps>({ sx: … }, propsIcon)；原生元素用 mergeAttrs<'svg'>(默认, rest, 受管)\n *\n * 渲染里每个部件每次都要合并，按最常见的情况走捷径：只有默认层时原样返回；\n * 只有两层以上都给了同名事件时才包一层回调。\n */\nexport function mergeProps<Target = Props>(\n  defaults: PropsLayer<Target>,\n  user?: PropsLayer<Target>,\n  managed?: PropsLayer<Target>,\n): PropsLayer<Target> {\n  const base = defaults as Props;\n  const own = hasKeys(user) ? (user as Props) : undefined;\n  const fixed = hasKeys(managed) ? (managed as Props) : undefined;\n  if (!own && !fixed) return defaults;\n  const merged: Props = { ...base, ...own, ...fixed };\n\n  for (const key of LISTED_KEYS) {\n    const values = present3(base[key], own?.[key], fixed?.[key]);\n    if (values) merged[key] = values;\n  }\n\n  const refs = present3(base.ref, own?.ref, fixed?.ref) as RefSetter[] | undefined;\n  if (refs && refs.length > 1) {\n    merged.ref = (element: unknown) => refs.forEach((ref) => setRef(ref, element));\n  }\n\n  // 同名事件：使用方的与组件的（默认层、受管层）合并；只有组件两层都有时也要合并\n  if (own) {\n    for (const key in own) {\n      if (!isHandlerKey(key)) continue;\n      if (base[key] == null && fixed?.[key] == null) {\n        // 受管层写了 onXxx: undefined（这时没有自己的处理）也不盖掉使用方的事件\n        merged[key] = own[key];\n        continue;\n      }\n      // 使用方传了 undefined（onClick={cond ? fn : undefined}）时也保留组件自己的\n      merged[key] =\n        mergeHandlers(own[key] as Handler | undefined, [base[key], fixed?.[key]]) ??\n        fixed?.[key] ??\n        base[key];\n    }\n  }\n  if (fixed) {\n    for (const key in fixed) {\n      if (!isHandlerKey(key) || base[key] == null || (own && key in own)) continue;\n      const handler = mergeHandlers(undefined, [base[key], fixed[key]]);\n      if (handler) merged[key] = handler;\n    }\n  }\n  return merged as PropsLayer<Target>;\n}\n\n/**\n * 子组件部件的合并：mergeProps 的规则，但默认层要写齐子组件的必填 props（如 Icon 的 icon），\n * 返回完整的 props 类型，展开到子组件上不必再断言：\n *   <Icon {...mergePartProps<IconProps>({ icon: X, sx: styles.icon }, propsIcon)} />\n */\nexport function mergePartProps<P extends object>(\n  defaults: P,\n  user?: Partial<P>,\n  managed?: Partial<P>,\n): P {\n  // P 是组件 props 类型，不是标签名：按对象合并，结果的类型就是 P\n  return mergeProps(\n    defaults as Props,\n    user as Props | undefined,\n    managed as Props | undefined,\n  ) as P;\n}\n\n/**\n * 原生元素部件的合并：mergeProps 的规则，再把 sx 换成 class 与 style（elementProps），结果直接展开到元素上：\n *   <svg {...mergeAttrs<'svg'>({ sx: styles.icon }, rest, { 'aria-hidden': true })} />\n */\nexport function mergeAttrs<Tag extends keyof JSX.IntrinsicElements>(\n  defaults: PropsLayer<Tag>,\n  user?: PropsLayer<Tag>,\n  managed?: PropsLayer<Tag>,\n): Omit<PropsLayer<Tag>, 'sx' | 'children'> {\n  return elementProps(mergeProps<Tag>(defaults, user, managed));\n}\n\n/**\n * 原生元素部件：把 sx 换成样式引擎生成的 class 与 style，再与已有的 class、style 合并。\n * 去掉 children：它是内容不是元素属性（组件的 ...rest 里带着它，转交给子组件时要用）。\n */\nexport function elementProps<P extends object>(props: P): Omit<P, 'sx' | 'children'> {\n  // 解构出的 rest 是新对象：之后直接往上写，不再复制一次（每个元素每次渲染都要走这里）\n  const { sx, children: _children, ...rest } = props as P & Props;\n  if (sx == null) return rest as Omit<P, 'sx' | 'children'>;\n  const compiled = compileSx(sx as SxStyles);\n  const element = rest as Props;\n  // 响应式绑定的 ref（元素挂上后改变量）与使用方的 ref 都要拿到元素\n  if (compiled.ref && element.ref != null) {\n    const own = element.ref as RefSetter;\n    const bound = compiled.ref;\n    element.ref = (target: unknown) => {\n      setRef(own, target);\n      bound(target);\n    };\n  } else if (compiled.ref) element.ref = compiled.ref;\n  if (rest.class == null && rest.style == null) {\n    if (compiled.class != null) element.class = compiled.class;\n    if (compiled.style != null) element.style = compiled.style;\n    return rest as Omit<P, 'sx' | 'children'>;\n  }\n  element.class = present3(rest.class, compiled.class) ?? [];\n  element.style = present3(compiled.style, rest.style) ?? [];\n  return rest as Omit<P, 'sx' | 'children'>;\n}\n\n/**\n * 编译好的样式是不变的常量：单个样式（不是数组）按对象缓存 css.attrs 的结果，\n * 根元素、图标这类每次渲染都是同一个样式的部件不必重复合并\n */\nconst compiledCache = new WeakMap<object, ReturnType<typeof css.attrs>>();\nfunction compileSx(sx: SxStyles) {\n  if (Array.isArray(sx) || typeof sx !== 'object' || sx === null) return css.attrs(sx);\n  let compiled = compiledCache.get(sx);\n  if (!compiled) compiledCache.set(sx, (compiled = css.attrs(sx)));\n  return compiled;\n}\n\n/** onClick、onUpdate:_value：on 后面跟大写字母 */\nfunction isHandlerKey(key: string) {\n  const third = key.charCodeAt(2);\n  return key.charCodeAt(0) === 111 && key.charCodeAt(1) === 110 && third >= 65 && third <= 90;\n}\n\nfunction hasKeys(layer: object | undefined): boolean {\n  if (!layer) return false;\n  for (const _ in layer) return true;\n  return false;\n}\n\n/**\n * 使用方的回调先执行，它调用了 event.preventDefault() 就跳过组件自己的回调。\n * 只有一方提供回调时返回 undefined，保留展开合并的结果即可。\n */\nfunction mergeHandlers(user: Handler | undefined, internal: unknown[]): Handler | undefined {\n  const own = present(internal) as Handler[];\n  if (own.length + (user ? 1 : 0) < 2) return undefined;\n  return (...args) => {\n    user?.(...args);\n    const event = args[0];\n    if (event instanceof Event && event.defaultPrevented) return;\n    own.forEach((handler) => handler(...args));\n  };\n}\n\nfunction setRef(ref: RefSetter, element: unknown) {\n  if (typeof ref === 'function') ref(element);\n  else ref.value = element;\n}\n\nconst present = <T>(values: readonly (T | null | undefined)[]) =>\n  values.filter((value): value is T => value != null);\n\n/** 按层排列、要合并成数组的属性 */\nconst LISTED_KEYS = ['sx', 'class', 'style'] as const;\n\n/** 最多三个值里不为空的那些，按原顺序成数组；都为空时返回 undefined。渲染路径上用，不建中间数组 */\nfunction present3(a: unknown, b: unknown, c?: unknown): unknown[] | undefined {\n  if (a == null) {\n    if (b == null) return c == null ? undefined : [c];\n    return c == null ? [b] : [b, c];\n  }\n  if (b == null) return c == null ? [a] : [a, c];\n  return c == null ? [a, b] : [a, b, c];\n}\n\n/**\n * 默认的 aria-labelledby（Field 的标签、弹层的触发器）：使用方写的 aria-labelledby 优先；使用方写了 aria-label 时\n * 不加默认的（aria-labelledby 会盖过 aria-label，使用方写的名称就白写了）\n */\nexport function defaultLabelledBy(\n  attrs: { 'aria-label'?: string; 'aria-labelledby'?: string },\n  fallback: string | undefined,\n): string | undefined {\n  return attrs['aria-labelledby'] ?? (attrs['aria-label'] == null ? fallback : undefined);\n}\n\n/**\n * 内容（插槽、标题、说明、错误这类 VNodeChild）有没有东西：null、undefined、空字符串与布尔都算没有。\n * 使用方常写 `error={cond && '…'}`、`aside={wide && <Panel />}`，条件不成立时是 false，不该渲染出空的外层\n */\nexport function hasContent(node: VNodeChild): boolean {\n  return node != null && typeof node !== 'boolean' && node !== '';\n}\n\n/**\n * 把 css.attrs 的结果写到命令式创建的元素上（波纹、量取主题的探针）：class 与行内样式，\n * 自定义属性（动态样式的变量）名字原样、用 setProperty\n */\nexport function applyStyleAttrs(element: HTMLElement, { class: className, style }: StyleAttrs) {\n  element.className = className ?? '';\n  for (const [name, value] of Object.entries(style ?? {})) {\n    const property = name.startsWith('--')\n      ? name\n      : name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);\n    element.style.setProperty(property, String(value));\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAgDA,IAAa,aAAa,UACxB;;;;;;;;;AAsBF,SAAgB,WACd,UACA,MACA,SACoB;CACpB,MAAM,OAAO;CACb,MAAM,MAAM,QAAQ,IAAI,IAAK,OAAiB,KAAA;CAC9C,MAAM,QAAQ,QAAQ,OAAO,IAAK,UAAoB,KAAA;CACtD,IAAI,CAAC,OAAO,CAAC,OAAO,OAAO;CAC3B,MAAM,SAAgB;EAAE,GAAG;EAAM,GAAG;EAAK,GAAG;CAAM;CAElD,KAAK,MAAM,OAAO,aAAa;EAC7B,MAAM,SAAS,SAAS,KAAK,MAAM,MAAM,MAAM,QAAQ,IAAI;EAC3D,IAAI,QAAQ,OAAO,OAAO;CAC5B;CAEA,MAAM,OAAO,SAAS,KAAK,KAAK,KAAK,KAAK,OAAO,GAAG;CACpD,IAAI,QAAQ,KAAK,SAAS,GACxB,OAAO,OAAO,YAAqB,KAAK,SAAS,QAAQ,OAAO,KAAK,OAAO,CAAC;CAI/E,IAAI,KACF,KAAK,MAAM,OAAO,KAAK;EACrB,IAAI,CAAC,aAAa,GAAG,GAAG;EACxB,IAAI,KAAK,QAAQ,QAAQ,QAAQ,QAAQ,MAAM;GAE7C,OAAO,OAAO,IAAI;GAClB;EACF;EAEA,OAAO,OACL,cAAc,IAAI,MAA6B,CAAC,KAAK,MAAM,QAAQ,IAAI,CAAC,KACxE,QAAQ,QACR,KAAK;CACT;CAEF,IAAI,OACF,KAAK,MAAM,OAAO,OAAO;EACvB,IAAI,CAAC,aAAa,GAAG,KAAK,KAAK,QAAQ,QAAS,OAAO,OAAO,KAAM;EACpE,MAAM,UAAU,cAAc,KAAA,GAAW,CAAC,KAAK,MAAM,MAAM,IAAI,CAAC;EAChE,IAAI,SAAS,OAAO,OAAO;CAC7B;CAEF,OAAO;AACT;;;;;;AAOA,SAAgB,eACd,UACA,MACA,SACG;CAEH,OAAO,WACL,UACA,MACA,OACF;AACF;;;;;AAMA,SAAgB,WACd,UACA,MACA,SAC0C;CAC1C,OAAO,aAAa,WAAgB,UAAU,MAAM,OAAO,CAAC;AAC9D;;;;;AAMA,SAAgB,aAA+B,OAAsC;CAEnF,MAAM,EAAE,IAAI,UAAU,WAAW,GAAG,SAAS;CAC7C,IAAI,MAAM,MAAM,OAAO;CACvB,MAAM,WAAW,UAAU,EAAc;CACzC,MAAM,UAAU;CAEhB,IAAI,SAAS,OAAO,QAAQ,OAAO,MAAM;EACvC,MAAM,MAAM,QAAQ;EACpB,MAAM,QAAQ,SAAS;EACvB,QAAQ,OAAO,WAAoB;GACjC,OAAO,KAAK,MAAM;GAClB,MAAM,MAAM;EACd;CACF,OAAO,IAAI,SAAS,KAAK,QAAQ,MAAM,SAAS;CAChD,IAAI,KAAK,SAAS,QAAQ,KAAK,SAAS,MAAM;EAC5C,IAAI,SAAS,SAAS,MAAM,QAAQ,QAAQ,SAAS;EACrD,IAAI,SAAS,SAAS,MAAM,QAAQ,QAAQ,SAAS;EACrD,OAAO;CACT;CACA,QAAQ,QAAQ,SAAS,KAAK,OAAO,SAAS,KAAK,KAAK,CAAC;CACzD,QAAQ,QAAQ,SAAS,SAAS,OAAO,KAAK,KAAK,KAAK,CAAC;CACzD,OAAO;AACT;;;;;AAMA,IAAM,gCAAgB,IAAI,QAA8C;AACxE,SAAS,UAAU,IAAc;CAC/B,IAAI,MAAM,QAAQ,EAAE,KAAK,OAAO,OAAO,YAAY,OAAO,MAAM,OAAO,IAAI,MAAM,EAAE;CACnF,IAAI,WAAW,cAAc,IAAI,EAAE;CACnC,IAAI,CAAC,UAAU,cAAc,IAAI,IAAK,WAAW,IAAI,MAAM,EAAE,CAAE;CAC/D,OAAO;AACT;;AAGA,SAAS,aAAa,KAAa;CACjC,MAAM,QAAQ,IAAI,WAAW,CAAC;CAC9B,OAAO,IAAI,WAAW,CAAC,MAAM,OAAO,IAAI,WAAW,CAAC,MAAM,OAAO,SAAS,MAAM,SAAS;AAC3F;AAEA,SAAS,QAAQ,OAAoC;CACnD,IAAI,CAAC,OAAO,OAAO;CACnB,KAAK,MAAM,KAAK,OAAO,OAAO;CAC9B,OAAO;AACT;;;;;AAMA,SAAS,cAAc,MAA2B,UAA0C;CAC1F,MAAM,MAAM,QAAQ,QAAQ;CAC5B,IAAI,IAAI,UAAU,OAAO,IAAI,KAAK,GAAG,OAAO,KAAA;CAC5C,QAAQ,GAAG,SAAS;EAClB,OAAO,GAAG,IAAI;EACd,MAAM,QAAQ,KAAK;EACnB,IAAI,iBAAiB,SAAS,MAAM,kBAAkB;EACtD,IAAI,SAAS,YAAY,QAAQ,GAAG,IAAI,CAAC;CAC3C;AACF;AAEA,SAAS,OAAO,KAAgB,SAAkB;CAChD,IAAI,OAAO,QAAQ,YAAY,IAAI,OAAO;MACrC,IAAI,QAAQ;AACnB;AAEA,IAAM,WAAc,WAClB,OAAO,QAAQ,UAAsB,SAAS,IAAI;;AAGpD,IAAM,cAAc;CAAC;CAAM;CAAS;AAAO;;AAG3C,SAAS,SAAS,GAAY,GAAY,GAAoC;CAC5E,IAAI,KAAK,MAAM;EACb,IAAI,KAAK,MAAM,OAAO,KAAK,OAAO,KAAA,IAAY,CAAC,CAAC;EAChD,OAAO,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;CAChC;CACA,IAAI,KAAK,MAAM,OAAO,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;CAC7C,OAAO,KAAK,OAAO,CAAC,GAAG,CAAC,IAAI;EAAC;EAAG;EAAG;CAAC;AACtC;;;;;AAMA,SAAgB,kBACd,OACA,UACoB;CACpB,OAAO,MAAM,uBAAuB,MAAM,iBAAiB,OAAO,WAAW,KAAA;AAC/E;;;;;AAMA,SAAgB,WAAW,MAA2B;CACpD,OAAO,QAAQ,QAAQ,OAAO,SAAS,aAAa,SAAS;AAC/D;;;;;AAMA,SAAgB,gBAAgB,SAAsB,EAAE,OAAO,WAAW,SAAqB;CAC7F,QAAQ,YAAY,aAAa;CACjC,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,SAAS,CAAC,CAAC,GAAG;EACvD,MAAM,WAAW,KAAK,WAAW,IAAI,IACjC,OACA,KAAK,QAAQ,WAAW,MAAM,IAAI,EAAE,YAAY,GAAG;EACvD,QAAQ,MAAM,YAAY,UAAU,OAAO,KAAK,CAAC;CACnD;AACF"}

package/dist/utils/request/error-message.d.ts

@@ -0,0 +1,17 @@
+import type { Lang } from '../../config/lang/lang';
+/** 错误上的业务错误码；认不出时为 undefined */
+export declare function errorCodeOf(error: unknown): string | undefined;
+/**
+ * 给人看的错误文案：码在 lang.errorCodes 里有文案时用它（params 填进去）；没有时用错误自己的 message（后端给的兜底、
+ * 应用的上传函数抛的说明），再没有用 lang.requestFailed
+ */
+export declare function errorMessage(error: unknown, lang: Lang): string;
+/**
+ * 只按码取的文案；错误没有码、码没有文案时为 undefined。组件有自己的笼统提示时用它
+ * （远程选项：`errorCodeText(error, lang) ?? lang.listLoadFailed`），不把底层的英文说明露给用户
+ */
+export declare function errorCodeText(error: unknown, lang: Lang): string | undefined;
+/** 一个码的文案（也用于 errors 明细里按字段的码）；语言包里没有时为 undefined */
+export declare function codeText(code: string, params: Readonly<Record<string, unknown>> | undefined, lang: Lang): string | undefined;
+/** 当前语言下的 errorMessage（在 setup 里调用）；返回的函数随 Provider 切换语言 */
+export declare function useErrorMessage(): (error: unknown) => string;