@xihan-ui/vue 1.0.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# @xihan-ui/vue
+
+## 1.0.0-alpha.0
+
+### Major Changes
+
+- bc65cb7: 首个公开版本：框架无关的 UI 基座。
+
+  自研薄 FSM 内核 + headless（anatomy / machine / connect）+ 设计令牌与主题运行时 + 样式层，
+  102 个组件在 Vue 与 Web Components 两套适配器上共用同一份内核，跨适配器一致性套件与
+  真实 Chromium 里的无障碍扫描、浮层定位契约全绿。
+
+  浮层定位、虚拟滚动、Web Components 响应式基类、代码着色、流式 Markdown 均为自研，
+  运行时不带第三方依赖。
+
+- 84b1aa3: 新增 Icon 原语，`@xihan-ui/icons` 整包重写为首方图标集。
+
+  旧的 `@xihan-ui/icons` 是 27 个第三方图标集的聚合（约四万个图标），已整体移除并在
+  npm 上弃用。新包只收自研图标，第一批 29 个覆盖组件库自用的全部语义，24×24 单色
+  描边、`stroke-width` 2。
+
+  用法：
+
+  - `@xihan-ui/kernel` 导出 `IconRecord` / `IconNode` / `IconTag` 三个类型
+  - `@xihan-ui/headless` 导出 `connectIcon` / `iconAnatomy` / `iconMeta` / `iconKeyboard`
+  - `@xihan-ui/vue` 导出 `XhIcon`，`@xihan-ui/web-components` 注册 `<xh-icon>`
+  - `@xihan-ui/styles` 新增 `icon.css`，`data-size` 与 `data-weight` 各三档
+
+  图标记录是结构化节点数组而不是 SVG 字符串，渲染端逐节点建元素，运行期不经 HTML
+  解析器。图标数据传的是记录本身而不是名字：按名字查表要把全表静态引进来，摇树会
+  整个失效。
+
+  WC 侧要在 `<svg data-xh-part="root">` 里留一个空的 `<g data-xh-part="glyph"></g>`
+  作为授权点，元素只在它内部铺图元；不留这个空壳就一个节点都不动，手写内联 SVG 与
+  `<use>` 引用两种写法因此都还能用。`icon` 是对象，只能走 property 传，属性里写不出来。
+
+  可及名字两态互斥：`label` 给了非空白文本就输出 `role="img"` 与 `aria-label`，否则
+  输出 `aria-hidden="true"`。只有图标的按钮请把名字写在按钮上而不是图标上，两处都写
+  读屏会念两遍。
+
+- e788896: Select 支持多选，选中值由单值改为集合，公开 API 破坏性变更。
+
+  多选打开方式是 `multiple`：点中条目即在集合里增删该项，列表不收起；单选行为不变，只是选中值
+  的容器形状统一成了数组（单选恒为长度 ≤ 1）。
+
+  迁移点：
+
+  - `SelectValueChangeDetails.value` 由 `string | null` 变 `string[]`。原先判空写 `details.value === null`
+    的，改判 `details.value.length === 0`；取单选值写 `details.value[0]`。
+  - `SelectApi` 的 `value` 与 `valueText` 由单值变数组，两者逐项对应；`setValue` 签名变
+    `(next: string | string[]) => void`，裸串按单选简写处理；新增 `multiple`。
+    想拿「显示成什么字」不必自己拼，用 `displayText`：有选中取选中项文本（多选按半角逗号加空格连起来），
+    否则取 `placeholder`。
+  - Vue 默认插槽暴露的 `value` 与 `setValue` 随之变化；`update:value` 的载荷由单值变数组，
+    因此 `v-model:value` 绑定的变量类型要一并改。`value` / `default-value` 两个 prop 仍接受裸串与 `null`。
+  - WC `value-change` 事件的 `detail` 由 `{ value: string | null }` 变 `{ value: string[] }`；
+    新增 `multiple` 属性。`value` 属性只递得进单值，多选集合请写 property。
+    表单影子 `hidden-select` 不再写 `value`，选中态一律由 `option` 的 `selected` 表达（多选时开原生
+    `multiple`）—— 靠读 `hidden-select.value` 反查选中项的代码要改成读 `selectedOptions`。
+
+### Minor Changes
+
+- c5c5f7f: 两个适配器接上视觉层，各自走独立子入口 `@xihan-ui/vue/backgrounds` 与 `@xihan-ui/web-components/backgrounds`。
+
+  `@xihan-ui/backgrounds` 声明为**可选 peer**：主入口一行都不引它，不用视觉效果的应用不会因为装了适配器
+  而多出一个 WebGL 引擎。
+
+  Vue 侧三种用法，从轻到重：`v-background` 指令、`XhBackground` 组件、`useBackground` 组合式函数。
+  指令用在组件上时 Vue 会把它落到该组件的单一根元素上，所以给现成组件加背景不必改动组件本身。
+
+  WC 侧是 `<xh-background>`：元素自身就是画布容器，内容照常写在里面，效果铺在内容底下，
+  画布 `pointer-events: none` 不挡交互。参数走 `.params` property，点云走 `.setCloud()`。
+
+### Patch Changes
+
+- Updated dependencies [bc65cb7]
+- Updated dependencies [84b1aa3]
+- Updated dependencies [e788896]
+- Updated dependencies [46b82b0]
+  - @xihan-ui/kernel@1.0.0-alpha.0
+  - @xihan-ui/machine@1.0.0-alpha.0
+  - @xihan-ui/behavior@1.0.0-alpha.0
+  - @xihan-ui/headless@1.0.0-alpha.0
+  - @xihan-ui/position@1.0.0-alpha.0
+  - @xihan-ui/code-highlight@1.0.0-alpha.0
+  - @xihan-ui/backgrounds@1.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-Present XiHanFun and contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# @xihan-ui/vue
+
+Vue 3 适配器：102 个组件的 Vue 形态，外加对应的 composables。行为全部来自 `@xihan-ui/headless`，这一层只负责把它接到 Vue 的响应式与渲染上。
+
+**谁会装它**：在 Vue 里用这套组件的人装它。样式另装 `@xihan-ui/styles`，或者自己写。
+
+## 用法
+
+```ts
+import { XhButton, XhDialog } from '@xihan-ui/vue'
+import '@xihan-ui/styles'
+```
+
+## 装
+
+```bash
+pnpm add @xihan-ui/vue
+```
+
+完整文档见 [https://ui.docs.xihanfun.com](https://ui.docs.xihanfun.com)。这个包属于 `adapters/` 组，组的含义见仓库里的 `ui/packages/README.md`。
+
+许可：MIT

package/dist/backgrounds.d.ts

@@ -0,0 +1,158 @@
+import { Directive, PropType, ShallowRef } from "vue";
+import { BackgroundEffect, BackgroundQuality, BackgroundSurface, MorphOptions, ParamValue, PointCloud } from "@xihan-ui/backgrounds";
+//#region src/backgrounds.d.ts
+interface UseBackgroundOptions {
+  effect: BackgroundEffect | string;
+  params?: Record<string, ParamValue>;
+  quality?: BackgroundQuality;
+  /** 自动绑定指针事件，默认 true。 */
+  pointer?: boolean;
+  /** 创建后立即播放，默认 true。 */
+  autoplay?: boolean;
+  /** 系统开启减弱动态效果时冻结时间轴，默认 true。 */
+  respectReducedMotion?: boolean;
+  /** 滚出视口时暂停绘制，默认 true。 */
+  pauseOffscreen?: boolean;
+}
+interface UseBackgroundReturn {
+  readonly surface: ShallowRef<BackgroundSurface | null>;
+  /**
+   * 挂载点。直接当模板 ref 用：`<div :ref="visual.attach">`，
+   * 渲染器会在元素进出 DOM 时把元素或 null 交进来。
+   */
+  attach: (element: Element | null) => void;
+  setEffect: (effect: BackgroundEffect | string) => void;
+  setParams: (patch: Record<string, ParamValue>) => void;
+  setCloud: (cloud: PointCloud, options?: MorphOptions) => void;
+  play: () => void;
+  pause: () => void;
+  destroy: () => void;
+}
+/**
+ * 建一张受 Vue 生命周期管理的视觉画面。
+ *
+ * 用**函数式 ref** 而不是监听一个模板 ref：元素由渲染器直接交到手上，
+ * 不经过响应式与调度队列，因此不受 flush 时序影响，元素换了也一定收得到。
+ * 组件卸载时自动销毁；在 setup 之外调用则需自己调 destroy。
+ */
+declare function useBackground(options: UseBackgroundOptions): UseBackgroundReturn;
+/**
+ * `<XhBackground>` —— 独立视觉组件。默认插槽的内容浮在效果之上；
+ * 画布铺满根元素且 pointer-events: none，不会挡住插槽里的交互。
+ */
+declare const XhBackground: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  effect: {
+    type: PropType<BackgroundEffect | string>;
+    required: true;
+  };
+  params: {
+    type: PropType<Record<string, ParamValue>>;
+    default: undefined;
+  };
+  quality: {
+    type: PropType<BackgroundQuality>;
+    default: undefined;
+  };
+  /** 数据驱动点云。效果的粒子通道是 cloud 模式时才有意义。 */
+  cloud: {
+    type: PropType<PointCloud | null>;
+    default: null;
+  };
+  /** 换点云时的形变时长（秒）。 */
+  morphDuration: {
+    type: NumberConstructor;
+    default: undefined;
+  };
+  pointer: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  autoplay: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  respectReducedMotion: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  pauseOffscreen: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  /** 渲染成什么标签。 */
+  as: {
+    type: StringConstructor;
+    default: string;
+  };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  effect: {
+    type: PropType<BackgroundEffect | string>;
+    required: true;
+  };
+  params: {
+    type: PropType<Record<string, ParamValue>>;
+    default: undefined;
+  };
+  quality: {
+    type: PropType<BackgroundQuality>;
+    default: undefined;
+  };
+  /** 数据驱动点云。效果的粒子通道是 cloud 模式时才有意义。 */
+  cloud: {
+    type: PropType<PointCloud | null>;
+    default: null;
+  };
+  /** 换点云时的形变时长（秒）。 */
+  morphDuration: {
+    type: NumberConstructor;
+    default: undefined;
+  };
+  pointer: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  autoplay: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  respectReducedMotion: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  pauseOffscreen: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  /** 渲染成什么标签。 */
+  as: {
+    type: StringConstructor;
+    default: string;
+  };
+}>> & Readonly<{}>, {
+  params: Record<string, ParamValue>;
+  quality: BackgroundQuality;
+  cloud: PointCloud | null;
+  morphDuration: number;
+  pointer: boolean;
+  autoplay: boolean;
+  respectReducedMotion: boolean;
+  pauseOffscreen: boolean;
+  as: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+type BackgroundDirectiveValue = BackgroundEffect | string | UseBackgroundOptions;
+/**
+ * `v-background` —— 给任意元素铺一层视觉背景。
+ *
+ * 用在组件上时，Vue 会把指令落到该组件的单一根元素上，所以给现成组件加背景不需要改组件：
+ *
+ * ```vue
+ * <XhButton v-background="fluidEffect">提交</XhButton>
+ * <div v-background="{ effect: 'aurora', params: { speed: 1.6 } }" />
+ * ```
+ */
+declare const vBackground: Directive<HTMLElement, BackgroundDirectiveValue>;
+//#endregion
+export { BackgroundDirectiveValue, UseBackgroundOptions, UseBackgroundReturn, XhBackground, useBackground, vBackground };
+//# sourceMappingURL=backgrounds.d.ts.map

package/dist/backgrounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backgrounds.d.ts","names":[],"sources":["../src/backgrounds.ts"],"mappings":";;;UA4BiB;EACf,QAAQ;EACR,SAAS,eAAe;EACxB,UAAU;;EAEV;;EAEA;;EAEA;;EAEA;;UAGe;WACN,SAAS,WAAW;;;;;EAK7B,SAAS,SAAS;EAClB,YAAY,QAAQ;EACpB,YAAY,OAAO,eAAe;EAClC,WAAW,OAAO,YAAY,UAAU;EACxC;EACA;EACA;;;;;;;;;iBAUc,cAAc,SAAS,uBAAuB;;;;;cAwCjD,4BAAY,8BAAA;;IAGe,MAAA,SAAS;;;;IACnB,MAAA,SAAS,eAAe;;;;IACvB,MAAA,SAAS;;;;;IAEX,MAAA,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAJE,MAAA,SAAS;;;;IACnB,MAAA,SAAS,eAAe;;;;IACvB,MAAA,SAAS;;;;;IAEX,MAAA,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCAoFpC;KAEU,2BAA2B,4BAA4B;;;;;;;;;;;cAoBtD,aAAa,UAAU,aAAa"}

package/dist/backgrounds.js

@@ -0,0 +1,193 @@
+import { defineComponent, getCurrentScope, h, onScopeDispose, shallowRef } from "vue";
+import { createBackgroundSurface } from "@xihan-ui/backgrounds";
+//#region src/backgrounds.ts
+/**
+* 建一张受 Vue 生命周期管理的视觉画面。
+*
+* 用**函数式 ref** 而不是监听一个模板 ref：元素由渲染器直接交到手上，
+* 不经过响应式与调度队列，因此不受 flush 时序影响，元素换了也一定收得到。
+* 组件卸载时自动销毁；在 setup 之外调用则需自己调 destroy。
+*/
+function useBackground(options) {
+	const surface = shallowRef(null);
+	let attached = null;
+	function attach(element) {
+		const el = element instanceof HTMLElement ? element : null;
+		if (el === attached) return;
+		attached = el;
+		surface.value?.destroy();
+		surface.value = el === null ? null : createBackgroundSurface(el, options);
+	}
+	function destroy() {
+		attached = null;
+		surface.value?.destroy();
+		surface.value = null;
+	}
+	if (getCurrentScope()) onScopeDispose(destroy);
+	return {
+		surface,
+		attach,
+		setEffect: (effect) => surface.value?.setEffect(effect),
+		setParams: (patch) => surface.value?.setParams(patch),
+		setCloud: (cloud, morph) => surface.value?.setCloud(cloud, morph),
+		play: () => surface.value?.play(),
+		pause: () => surface.value?.pause(),
+		destroy
+	};
+}
+/**
+* `<XhBackground>` —— 独立视觉组件。默认插槽的内容浮在效果之上；
+* 画布铺满根元素且 pointer-events: none，不会挡住插槽里的交互。
+*/
+const XhBackground = defineComponent({
+	name: "XhBackground",
+	props: {
+		effect: {
+			type: [Object, String],
+			required: true
+		},
+		params: {
+			type: Object,
+			default: void 0
+		},
+		quality: {
+			type: String,
+			default: void 0
+		},
+		/** 数据驱动点云。效果的粒子通道是 cloud 模式时才有意义。 */
+		cloud: {
+			type: Object,
+			default: null
+		},
+		/** 换点云时的形变时长（秒）。 */
+		morphDuration: {
+			type: Number,
+			default: void 0
+		},
+		pointer: {
+			type: Boolean,
+			default: true
+		},
+		autoplay: {
+			type: Boolean,
+			default: true
+		},
+		respectReducedMotion: {
+			type: Boolean,
+			default: true
+		},
+		pauseOffscreen: {
+			type: Boolean,
+			default: true
+		},
+		/** 渲染成什么标签。 */
+		as: {
+			type: String,
+			default: "div"
+		}
+	},
+	setup(props, { slots, expose }) {
+		const api = useBackground({
+			effect: props.effect,
+			params: props.params,
+			quality: props.quality,
+			pointer: props.pointer,
+			autoplay: props.autoplay,
+			respectReducedMotion: props.respectReducedMotion,
+			pauseOffscreen: props.pauseOffscreen
+		});
+		let appliedEffect;
+		let appliedQuality;
+		let appliedCloud = null;
+		let appliedAutoplay = props.autoplay;
+		/**
+		* 把当前 props 推到画面上。在渲染函数里调用而不是挂 watcher：
+		* 渲染函数一定会随 props 变化重跑，且这里读到的参数值同时建立了依赖追踪，
+		* 调用方原地改参数对象里的某一项也收得到。
+		*/
+		function sync() {
+			const surface = api.surface.value;
+			if (surface === null) return;
+			if (props.effect !== appliedEffect) {
+				surface.setEffect(props.effect);
+				appliedEffect = props.effect;
+			}
+			if (props.quality !== void 0 && props.quality !== appliedQuality) {
+				surface.setQuality(props.quality);
+				appliedQuality = props.quality;
+			}
+			if (props.params !== void 0) surface.setParams(props.params);
+			if (props.cloud && props.cloud !== appliedCloud) {
+				surface.setCloud(props.cloud, { duration: appliedCloud === null ? 0 : props.morphDuration });
+				appliedCloud = props.cloud;
+			}
+			if (props.autoplay !== appliedAutoplay) {
+				if (props.autoplay) surface.play();
+				else surface.pause();
+				appliedAutoplay = props.autoplay;
+			}
+		}
+		const mount = (element) => {
+			const previous = api.surface.value;
+			api.attach(element instanceof HTMLElement ? element : null);
+			const current = api.surface.value;
+			if (current === previous || current === null) return;
+			appliedEffect = props.effect;
+			appliedQuality = props.quality;
+			appliedCloud = null;
+			appliedAutoplay = props.autoplay;
+			sync();
+		};
+		expose(api);
+		return () => {
+			sync();
+			return h(props.as, {
+				"ref": mount,
+				"data-scope": "background",
+				"data-part": "root"
+			}, slots.default?.());
+		};
+	}
+});
+function toOptions(value) {
+	if (typeof value === "string") return { effect: value };
+	return "effect" in value ? value : { effect: value };
+}
+const mounted = /* @__PURE__ */ new WeakMap();
+/**
+* `v-background` —— 给任意元素铺一层视觉背景。
+*
+* 用在组件上时，Vue 会把指令落到该组件的单一根元素上，所以给现成组件加背景不需要改组件：
+*
+* ```vue
+* <XhButton v-background="fluidEffect">提交</XhButton>
+* <div v-background="{ effect: 'aurora', params: { speed: 1.6 } }" />
+* ```
+*/
+const vBackground = {
+	mounted(el, binding) {
+		const options = toOptions(binding.value);
+		mounted.set(el, {
+			surface: createBackgroundSurface(el, options),
+			effect: options.effect
+		});
+	},
+	updated(el, binding) {
+		const entry = mounted.get(el);
+		if (entry === void 0) return;
+		const options = toOptions(binding.value);
+		if (options.effect !== entry.effect) {
+			entry.surface.setEffect(options.effect);
+			entry.effect = options.effect;
+		}
+		if (options.params !== void 0) entry.surface.setParams(options.params);
+	},
+	unmounted(el) {
+		mounted.get(el)?.surface.destroy();
+		mounted.delete(el);
+	}
+};
+//#endregion
+export { XhBackground, useBackground, vBackground };
+
+//# sourceMappingURL=backgrounds.js.map

package/dist/backgrounds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backgrounds.js","names":[],"sources":["../src/backgrounds.ts"],"sourcesContent":["// @xihan-ui/vue/backgrounds —— 视觉层的 Vue 适配。\n//\n// 与主入口分开：@xihan-ui/backgrounds 是可选 peer，不用视觉效果的应用不会因为装了本包\n// 而多出一个 WebGL 引擎。用之前先装 @xihan-ui/backgrounds。\n//\n// 三种用法，从轻到重：\n//   v-background   给任意元素或组件的根元素铺一层背景，一个字都不用改组件\n//   XhBackground   独立的视觉组件，插槽内容浮在效果之上\n//   useBackground  自己拿画面实例，接自定义调度或调参面板\n\nimport type {\n  BackgroundEffect,\n  BackgroundQuality,\n  BackgroundSurface,\n  MorphOptions,\n  ParamValue,\n  PointCloud,\n} from '@xihan-ui/backgrounds'\nimport type { Directive, PropType, ShallowRef, VNodeRef } from 'vue'\nimport { createBackgroundSurface } from '@xihan-ui/backgrounds'\nimport {\n  defineComponent,\n  getCurrentScope,\n  h,\n  onScopeDispose,\n  shallowRef,\n} from 'vue'\n\nexport interface UseBackgroundOptions {\n  effect: BackgroundEffect | string\n  params?: Record<string, ParamValue>\n  quality?: BackgroundQuality\n  /** 自动绑定指针事件，默认 true。 */\n  pointer?: boolean\n  /** 创建后立即播放，默认 true。 */\n  autoplay?: boolean\n  /** 系统开启减弱动态效果时冻结时间轴，默认 true。 */\n  respectReducedMotion?: boolean\n  /** 滚出视口时暂停绘制，默认 true。 */\n  pauseOffscreen?: boolean\n}\n\nexport interface UseBackgroundReturn {\n  readonly surface: ShallowRef<BackgroundSurface | null>\n  /**\n   * 挂载点。直接当模板 ref 用：`<div :ref=\"visual.attach\">`，\n   * 渲染器会在元素进出 DOM 时把元素或 null 交进来。\n   */\n  attach: (element: Element | null) => void\n  setEffect: (effect: BackgroundEffect | string) => void\n  setParams: (patch: Record<string, ParamValue>) => void\n  setCloud: (cloud: PointCloud, options?: MorphOptions) => void\n  play: () => void\n  pause: () => void\n  destroy: () => void\n}\n\n/**\n * 建一张受 Vue 生命周期管理的视觉画面。\n *\n * 用**函数式 ref** 而不是监听一个模板 ref：元素由渲染器直接交到手上，\n * 不经过响应式与调度队列，因此不受 flush 时序影响，元素换了也一定收得到。\n * 组件卸载时自动销毁；在 setup 之外调用则需自己调 destroy。\n */\nexport function useBackground(options: UseBackgroundOptions): UseBackgroundReturn {\n  const surface = shallowRef<BackgroundSurface | null>(null)\n  // 元素没换就不动画面：函数式 ref 每次 patch 都会被再调一遍，\n  // 不挡住的话每渲染一帧就销毁重建一次，画面永远停在创建时那份参数上\n  let attached: HTMLElement | null = null\n\n  function attach(element: Element | null): void {\n    const el = element instanceof HTMLElement ? element : null\n    if (el === attached)\n      return\n    attached = el\n    surface.value?.destroy()\n    surface.value = el === null ? null : createBackgroundSurface(el, options)\n  }\n\n  function destroy(): void {\n    attached = null\n    surface.value?.destroy()\n    surface.value = null\n  }\n\n  if (getCurrentScope())\n    onScopeDispose(destroy)\n\n  return {\n    surface,\n    attach,\n    setEffect: (effect): void => surface.value?.setEffect(effect),\n    setParams: (patch): void => surface.value?.setParams(patch),\n    setCloud: (cloud, morph): void => surface.value?.setCloud(cloud, morph),\n    play: (): void => surface.value?.play(),\n    pause: (): void => surface.value?.pause(),\n    destroy,\n  }\n}\n\n/**\n * `<XhBackground>` —— 独立视觉组件。默认插槽的内容浮在效果之上；\n * 画布铺满根元素且 pointer-events: none，不会挡住插槽里的交互。\n */\nexport const XhBackground = defineComponent({\n  name: 'XhBackground',\n  props: {\n    effect: { type: [Object, String] as PropType<BackgroundEffect | string>, required: true },\n    params: { type: Object as PropType<Record<string, ParamValue>>, default: undefined },\n    quality: { type: String as PropType<BackgroundQuality>, default: undefined },\n    /** 数据驱动点云。效果的粒子通道是 cloud 模式时才有意义。 */\n    cloud: { type: Object as PropType<PointCloud | null>, default: null },\n    /** 换点云时的形变时长（秒）。 */\n    morphDuration: { type: Number, default: undefined },\n    pointer: { type: Boolean, default: true },\n    autoplay: { type: Boolean, default: true },\n    respectReducedMotion: { type: Boolean, default: true },\n    pauseOffscreen: { type: Boolean, default: true },\n    /** 渲染成什么标签。 */\n    as: { type: String, default: 'div' },\n  },\n  setup(props, { slots, expose }) {\n    const api = useBackground({\n      effect: props.effect,\n      params: props.params,\n      quality: props.quality,\n      pointer: props.pointer,\n      autoplay: props.autoplay,\n      respectReducedMotion: props.respectReducedMotion,\n      pauseOffscreen: props.pauseOffscreen,\n    })\n\n    let appliedEffect: BackgroundEffect | string | undefined\n    let appliedQuality: BackgroundQuality | undefined\n    let appliedCloud: PointCloud | null = null\n    let appliedAutoplay = props.autoplay\n\n    /**\n     * 把当前 props 推到画面上。在渲染函数里调用而不是挂 watcher：\n     * 渲染函数一定会随 props 变化重跑，且这里读到的参数值同时建立了依赖追踪，\n     * 调用方原地改参数对象里的某一项也收得到。\n     */\n    function sync(): void {\n      const surface = api.surface.value\n      if (surface === null)\n        return\n      if (props.effect !== appliedEffect) {\n        surface.setEffect(props.effect)\n        appliedEffect = props.effect\n      }\n      if (props.quality !== undefined && props.quality !== appliedQuality) {\n        surface.setQuality(props.quality)\n        appliedQuality = props.quality\n      }\n      if (props.params !== undefined)\n        surface.setParams(props.params)\n      if (props.cloud && props.cloud !== appliedCloud) {\n        // 第一份点云直接就位，之后的换形态才走过渡\n        surface.setCloud(props.cloud, { duration: appliedCloud === null ? 0 : props.morphDuration })\n        appliedCloud = props.cloud\n      }\n      if (props.autoplay !== appliedAutoplay) {\n        if (props.autoplay)\n          surface.play()\n        else surface.pause()\n        appliedAutoplay = props.autoplay\n      }\n    }\n\n    // 签名照 VNodeRef 的函数式 ref 写：渲染器在元素进出 DOM 时把元素或 null 交进来。\n    // 同一个元素会被反复交进来，attach 对此幂等；只有真换了画面才重置记账。\n    const mount: VNodeRef = (element): void => {\n      const previous = api.surface.value\n      api.attach(element instanceof HTMLElement ? element : null)\n      const current = api.surface.value\n      if (current === previous || current === null)\n        return\n      appliedEffect = props.effect\n      appliedQuality = props.quality\n      appliedCloud = null\n      appliedAutoplay = props.autoplay\n      sync()\n    }\n\n    expose(api)\n\n    return () => {\n      sync()\n      return h(\n        props.as,\n        { 'ref': mount, 'data-scope': 'background', 'data-part': 'root' },\n        slots.default?.(),\n      )\n    }\n  },\n})\n\nexport type BackgroundDirectiveValue = BackgroundEffect | string | UseBackgroundOptions\n\nfunction toOptions(value: BackgroundDirectiveValue): UseBackgroundOptions {\n  if (typeof value === 'string')\n    return { effect: value }\n  return 'effect' in value ? value : { effect: value }\n}\n\nconst mounted = new WeakMap<HTMLElement, { surface: BackgroundSurface, effect: BackgroundEffect | string }>()\n\n/**\n * `v-background` —— 给任意元素铺一层视觉背景。\n *\n * 用在组件上时，Vue 会把指令落到该组件的单一根元素上，所以给现成组件加背景不需要改组件：\n *\n * ```vue\n * <XhButton v-background=\"fluidEffect\">提交</XhButton>\n * <div v-background=\"{ effect: 'aurora', params: { speed: 1.6 } }\" />\n * ```\n */\nexport const vBackground: Directive<HTMLElement, BackgroundDirectiveValue> = {\n  mounted(el, binding) {\n    const options = toOptions(binding.value)\n    mounted.set(el, { surface: createBackgroundSurface(el, options), effect: options.effect })\n  },\n  updated(el, binding) {\n    const entry = mounted.get(el)\n    if (entry === undefined)\n      return\n    const options = toOptions(binding.value)\n    if (options.effect !== entry.effect) {\n      entry.surface.setEffect(options.effect)\n      entry.effect = options.effect\n    }\n    if (options.params !== undefined)\n      entry.surface.setParams(options.params)\n  },\n  unmounted(el) {\n    mounted.get(el)?.surface.destroy()\n    mounted.delete(el)\n  },\n}\n"],"mappings":"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"}