@veltra/compositions 1.0.8 → 1.0.9

package/dist/index.d.ts

@@ -4,11 +4,11 @@ import { useDrag } from "./use-drag/index.js";
 import { useFallbackProps, useFormFallbackProps } from "./use-fallback-props/index.js";
 import { useFocus } from "./use-focus/index.js";
 import { useFormComponent } from "./use-form-component/index.js";
-import { Updater, useUpdateLock } from "./use-lock/index.js";
+import { UserAction, UserActionResult, useUserAction } from "./use-user-action/index.js";
 import { useModel } from "./use-model/index.js";
 import { usePop } from "./use-pop/index.js";
 import { RefElement, ResizeObserverReturn, useObserverCallback, useResizeObserver } from "./use-resize-observer/index.js";
 import { useReactiveSize } from "./use-reactive-size/index.js";
 import { useTransition } from "./use-transition/index.js";
-import { VirtualReturned, useVirtual } from "./use-virtual/index.js";
-export { RefElement, ResizeObserverReturn, Updater, VirtualReturned, setDocumentSize, useComponentProps, useConfig, useDrag, useFallbackProps, useFocus, useFormComponent, useFormFallbackProps, useModel, useObserverCallback, usePop, useReactiveSize, useResizeObserver, useTransition, useUpdateLock, useVirtual };
+import { EstimateSize, GetItemKey, UseVirtualizerOptions, UseVirtualizerReturned, VirtualAlign, VirtualItem, VirtualMeasurement, VirtualRange, VirtualScrollOptions, VirtualSnapshot, Virtualizer, VirtualizerOptions, useVirtualizer } from "./use-virtualizer/index.js";
+export { EstimateSize, GetItemKey, RefElement, ResizeObserverReturn, UseVirtualizerOptions, UseVirtualizerReturned, UserAction, UserActionResult, VirtualAlign, VirtualItem, VirtualMeasurement, VirtualRange, VirtualScrollOptions, VirtualSnapshot, Virtualizer, VirtualizerOptions, setDocumentSize, useComponentProps, useConfig, useDrag, useFallbackProps, useFocus, useFormComponent, useFormFallbackProps, useModel, useObserverCallback, usePop, useReactiveSize, useResizeObserver, useTransition, useUserAction, useVirtualizer };

package/dist/index.js

@@ -4,11 +4,11 @@ import { useDrag } from "./use-drag/index.js";
 import { useFallbackProps, useFormFallbackProps } from "./use-fallback-props/index.js";
 import { useFocus } from "./use-focus/index.js";
 import { useFormComponent } from "./use-form-component/index.js";
-import { useUpdateLock } from "./use-lock/index.js";
+import { useUserAction } from "./use-user-action/index.js";
 import { useModel } from "./use-model/index.js";
 import { usePop } from "./use-pop/index.js";
 import { useObserverCallback, useResizeObserver } from "./use-resize-observer/index.js";
 import { useReactiveSize } from "./use-reactive-size/index.js";
 import { useTransition } from "./use-transition/index.js";
-import { useVirtual } from "./use-virtual/index.js";
-export { setDocumentSize, useComponentProps, useConfig, useDrag, useFallbackProps, useFocus, useFormComponent, useFormFallbackProps, useModel, useObserverCallback, usePop, useReactiveSize, useResizeObserver, useTransition, useUpdateLock, useVirtual };
+import { useVirtualizer } from "./use-virtualizer/index.js";
+export { setDocumentSize, useComponentProps, useConfig, useDrag, useFallbackProps, useFocus, useFormComponent, useFormFallbackProps, useModel, useObserverCallback, usePop, useReactiveSize, useResizeObserver, useTransition, useUserAction, useVirtualizer };

package/dist/use-user-action/index.d.ts

@@ -0,0 +1,32 @@
+//#region src/use-user-action/index.d.ts
+type UserAction = <T extends (...args: any[]) => void | Promise<void>>(fn: T) => (...args: Parameters<T>) => Promise<void>;
+interface UserActionResult {
+  isUserActive: () => boolean;
+  userAction: UserAction;
+}
+/**
+ * 创建用户活动
+ * @description
+ * 解决"组件内部 emit 更新 → 外部 props 回传 → 监听 props 的副作用再次触发
+ * 内部状态变更"的循环更新问题。典型搭配：
+ *
+ * ```ts
+ * const { userAction, isUserActive } = useUserAction()
+ *
+ * // 将函数标记为一个用户动作
+ * const handleSelect = userAction((date: Dater) => {
+ *   currentDate.value = date
+ *   emit('update:modelValue', date.format(fmt))
+ * })
+ *
+ * // modelValue 回显：用户活动期间跳过
+ * watch(() => props.modelValue, (v) => {
+ *   if (isUserActive()) return
+ *   currentDate.value = v ? date(v) : undefined
+ * })
+ * ```
+ */
+declare function useUserAction(): UserActionResult;
+//#endregion
+export { UserAction, UserActionResult, useUserAction };
+//# sourceMappingURL=index.d.ts.map

package/dist/use-user-action/index.js

@@ -0,0 +1,50 @@
+import { nextTick } from "vue";
+//#region src/use-user-action/index.ts
+/**
+* 创建用户活动
+* @description
+* 解决"组件内部 emit 更新 → 外部 props 回传 → 监听 props 的副作用再次触发
+* 内部状态变更"的循环更新问题。典型搭配：
+*
+* ```ts
+* const { userAction, isUserActive } = useUserAction()
+*
+* // 将函数标记为一个用户动作
+* const handleSelect = userAction((date: Dater) => {
+*   currentDate.value = date
+*   emit('update:modelValue', date.format(fmt))
+* })
+*
+* // modelValue 回显：用户活动期间跳过
+* watch(() => props.modelValue, (v) => {
+*   if (isUserActive()) return
+*   currentDate.value = v ? date(v) : undefined
+* })
+* ```
+*/
+function useUserAction() {
+	let actionCount = 0;
+	const isUserActive = () => {
+		return actionCount > 0;
+	};
+	const userAction = (fn) => {
+		return async (...args) => {
+			actionCount++;
+			try {
+				await fn(...args);
+			} catch (error) {
+				console.error(error);
+			}
+			await nextTick();
+			actionCount--;
+		};
+	};
+	return {
+		isUserActive,
+		userAction
+	};
+}
+//#endregion
+export { useUserAction };
+
+//# sourceMappingURL=index.js.map

package/dist/use-user-action/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/use-user-action/index.ts"],"sourcesContent":["import { nextTick } from 'vue'\n\nexport type UserAction = <T extends (...args: any[]) => void | Promise<void>>(\n  fn: T\n) => (...args: Parameters<T>) => Promise<void>\n\nexport interface UserActionResult {\n  isUserActive: () => boolean\n  userAction: UserAction\n}\n\n/**\n * 创建用户活动\n * @description\n * 解决\"组件内部 emit 更新 → 外部 props 回传 → 监听 props 的副作用再次触发\n * 内部状态变更\"的循环更新问题。典型搭配：\n *\n * ```ts\n * const { userAction, isUserActive } = useUserAction()\n *\n * // 将函数标记为一个用户动作\n * const handleSelect = userAction((date: Dater) => {\n *   currentDate.value = date\n *   emit('update:modelValue', date.format(fmt))\n * })\n *\n * // modelValue 回显：用户活动期间跳过\n * watch(() => props.modelValue, (v) => {\n *   if (isUserActive()) return\n *   currentDate.value = v ? date(v) : undefined\n * })\n * ```\n */\nexport function useUserAction(): UserActionResult {\n  let actionCount = 0\n  const isUserActive = () => {\n    return actionCount > 0\n  }\n\n  const userAction: UserAction = (fn) => {\n    return async (...args) => {\n      actionCount++\n\n      try {\n        await fn(...args)\n      } catch (error) {\n        console.error(error)\n      }\n      await nextTick()\n\n      actionCount--\n    }\n  }\n\n  return { isUserActive, userAction }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,gBAAkC;CAChD,IAAI,cAAc;CAClB,MAAM,qBAAqB;AACzB,SAAO,cAAc;;CAGvB,MAAM,cAA0B,OAAO;AACrC,SAAO,OAAO,GAAG,SAAS;AACxB;AAEA,OAAI;AACF,UAAM,GAAG,GAAG,KAAK;YACV,OAAO;AACd,YAAQ,MAAM,MAAM;;AAEtB,SAAM,UAAU;AAEhB;;;AAIJ,QAAO;EAAE;EAAc;EAAY"}

package/dist/use-virtualizer/index.d.ts

@@ -0,0 +1,69 @@
+import { MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+import { EstimateSize, GetItemKey, VirtualAlign, VirtualItem, VirtualMeasurement, VirtualRange, VirtualScrollOptions, VirtualSnapshot, Virtualizer as Virtualizer$1, VirtualizerOptions } from "@cat-kit/fe";
+
+//#region src/use-virtualizer/index.d.ts
+type MaybeEl = HTMLElement | null | undefined;
+interface UseVirtualizerOptions extends Omit<VirtualizerOptions, 'count'> {
+  /** 响应式虚拟项总数；内部 `watch` 驱动 `virtualizer.setCount`。 */
+  count: Ref<number>;
+  /**
+   * 响应式滚动容器；变更时自动 `connect` / `disconnect`。
+   * `immediate: true`，初始为 `null` 时等价于 `disconnect()`。
+   */
+  scrollEl: MaybeRefOrGetter<MaybeEl>;
+  /**
+   * 可选：内容承接元素。hook 订阅到结构性更新时直接写入
+   * `style.height = totalSize + 'px'`（水平模式为 `width`），
+   * **不经过 Vue 响应式**——因此 `totalSize` 的变化不会触发模板重渲染。
+   * 当引用切换为 `null` 时，会清空此前写入的内联尺寸，恢复 CSS 默认。
+   */
+  contentEl?: MaybeRefOrGetter<MaybeEl>;
+  /** 可选：首项前占位元素。语义同 `contentEl`，写 `beforeSize`。 */
+  beforeEl?: MaybeRefOrGetter<MaybeEl>;
+  /** 可选：末项后占位元素。语义同 `contentEl`，写 `afterSize`。 */
+  afterEl?: MaybeRefOrGetter<MaybeEl>;
+}
+interface UseVirtualizerReturned {
+  /**
+   * 底层 `Virtualizer` 实例。
+   *
+   * 未做包装；消费者可直接调用 `scrollToIndex` / `scrollToOffset` /
+   * `reset` / `measureMany` / `setOptions` / `measureElement` 等方法。
+   */
+  virtualizer: Virtualizer$1;
+  /**
+   * 完整快照 shallowRef。任一结构性变化（items/range/isScrolling/各种 size）都会更新。
+   * 大多数消费者只需 `items` / `isScrolling`，此 ref 仅在需要 `range` / `totalSize` 等
+   * 其它字段时使用。
+   */
+  snapshot: ShallowRef<VirtualSnapshot>;
+  /**
+   * 仅在底层 `items` 引用变化时才更新的 shallowRef。
+   *
+   * 独立于 `snapshot`，用于模板 `v-for`；这样 `isScrolling` 等字段的切换不会
+   * 连带触发 `items.map(...)` 的重新求值。
+   */
+  items: ShallowRef<VirtualItem[]>;
+  /** 仅在布尔值变化时更新的 `isScrolling` 状态。 */
+  isScrolling: ShallowRef<boolean>;
+}
+/**
+ * Vue 适配层：把 `@cat-kit/fe` 的 `Virtualizer` 生命周期与响应式系统对接。
+ *
+ * 设计原则：
+ * 1. **尺寸写入走 DOM**：`contentEl` / `beforeEl` / `afterEl` 一旦传入，
+ *    hook 在 `subscribe` 回调中命令式写 `style.height`；消费者模板无需绑定
+ *    `totalSize` / `beforeSize` / `afterSize`，滚动时 Vue 不会因尺寸变化重渲染。
+ * 2. **`items` / `isScrolling` 独立拆分**：底层 subscribe 一次回调可能同时包含
+ *    items 变化与 isScrolling 切换；拆成两个 shallowRef 后，消费者 `v-for`
+ *    的 `computed(() => items.value.map(...))` 不会因 `isScrolling` 变化而重新执行。
+ * 3. **业务语义外置**：阈值判定 / key 组装 / `scrollToIndex` 对齐方式由消费者组装。
+ *
+ * 约束：
+ * - `initialOffset` / `initialViewport` 仅构造时生效，后续 `setOptions` 忽略（底层契约）。
+ * - 消费者若需运行时切换 `estimateSize` / `getItemKey` 等字段，调用 `virtualizer.setOptions(...)`。
+ */
+declare function useVirtualizer(options: UseVirtualizerOptions): UseVirtualizerReturned;
+//#endregion
+export { type EstimateSize, type GetItemKey, UseVirtualizerOptions, UseVirtualizerReturned, type VirtualAlign, type VirtualItem, type VirtualMeasurement, type VirtualRange, type VirtualScrollOptions, type VirtualSnapshot, type Virtualizer$1 as Virtualizer, type VirtualizerOptions, useVirtualizer };
+//# sourceMappingURL=index.d.ts.map

package/dist/use-virtualizer/index.js

@@ -0,0 +1,87 @@
+import { onScopeDispose, shallowRef, toValue, watch } from "vue";
+import { Virtualizer } from "@cat-kit/fe";
+//#region src/use-virtualizer/index.ts
+function writeSize(el, size, horizontal) {
+	if (!el) return;
+	if (horizontal) el.style.width = `${size}px`;
+	else el.style.height = `${size}px`;
+}
+function clearSize(el, horizontal) {
+	if (!el) return;
+	if (horizontal) el.style.width = "";
+	else el.style.height = "";
+}
+/**
+* Vue 适配层：把 `@cat-kit/fe` 的 `Virtualizer` 生命周期与响应式系统对接。
+*
+* 设计原则：
+* 1. **尺寸写入走 DOM**：`contentEl` / `beforeEl` / `afterEl` 一旦传入，
+*    hook 在 `subscribe` 回调中命令式写 `style.height`；消费者模板无需绑定
+*    `totalSize` / `beforeSize` / `afterSize`，滚动时 Vue 不会因尺寸变化重渲染。
+* 2. **`items` / `isScrolling` 独立拆分**：底层 subscribe 一次回调可能同时包含
+*    items 变化与 isScrolling 切换；拆成两个 shallowRef 后，消费者 `v-for`
+*    的 `computed(() => items.value.map(...))` 不会因 `isScrolling` 变化而重新执行。
+* 3. **业务语义外置**：阈值判定 / key 组装 / `scrollToIndex` 对齐方式由消费者组装。
+*
+* 约束：
+* - `initialOffset` / `initialViewport` 仅构造时生效，后续 `setOptions` 忽略（底层契约）。
+* - 消费者若需运行时切换 `estimateSize` / `getItemKey` 等字段，调用 `virtualizer.setOptions(...)`。
+*/
+function useVirtualizer(options) {
+	const { count, scrollEl, contentEl, beforeEl, afterEl, ...initOptions } = options;
+	const horizontal = initOptions.horizontal === true;
+	const virtualizer = new Virtualizer({
+		...initOptions,
+		count: count.value
+	});
+	const initialSnapshot = virtualizer.getSnapshot();
+	const snapshot = shallowRef(initialSnapshot);
+	const items = shallowRef(initialSnapshot.items);
+	const isScrolling = shallowRef(initialSnapshot.isScrolling);
+	function flushSizes(s) {
+		writeSize(toValue(contentEl) ?? null, s.totalSize, horizontal);
+		writeSize(toValue(beforeEl) ?? null, s.beforeSize, horizontal);
+		writeSize(toValue(afterEl) ?? null, s.afterSize, horizontal);
+	}
+	flushSizes(initialSnapshot);
+	const unsubscribe = virtualizer.subscribe((next) => {
+		snapshot.value = next;
+		if (next.items !== items.value) items.value = next.items;
+		if (next.isScrolling !== isScrolling.value) isScrolling.value = next.isScrolling;
+		flushSizes(next);
+	});
+	watch(count, (c) => {
+		virtualizer.setCount(c);
+	});
+	watch(() => toValue(scrollEl) ?? null, (el) => {
+		if (el) virtualizer.connect(el);
+		else virtualizer.disconnect();
+	}, { immediate: true });
+	function bindSizeSlot(source, pick) {
+		if (source === void 0) return;
+		watch(() => toValue(source) ?? null, (el, oldEl) => {
+			if (oldEl && oldEl !== el) clearSize(oldEl, horizontal);
+			if (el) writeSize(el, pick(snapshot.value), horizontal);
+		});
+	}
+	bindSizeSlot(contentEl, (s) => s.totalSize);
+	bindSizeSlot(beforeEl, (s) => s.beforeSize);
+	bindSizeSlot(afterEl, (s) => s.afterSize);
+	onScopeDispose(() => {
+		unsubscribe();
+		virtualizer.destroy();
+		clearSize(toValue(contentEl) ?? null, horizontal);
+		clearSize(toValue(beforeEl) ?? null, horizontal);
+		clearSize(toValue(afterEl) ?? null, horizontal);
+	});
+	return {
+		virtualizer,
+		snapshot,
+		items,
+		isScrolling
+	};
+}
+//#endregion
+export { useVirtualizer };
+
+//# sourceMappingURL=index.js.map

package/dist/use-virtualizer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/use-virtualizer/index.ts"],"sourcesContent":["import {\n  Virtualizer,\n  type EstimateSize,\n  type GetItemKey,\n  type VirtualAlign,\n  type VirtualItem,\n  type VirtualMeasurement,\n  type VirtualRange,\n  type VirtualScrollOptions,\n  type VirtualSnapshot,\n  type VirtualizerOptions\n} from '@cat-kit/fe'\nimport {\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  watch,\n  type MaybeRefOrGetter,\n  type Ref,\n  type ShallowRef\n} from 'vue'\n\nexport type {\n  EstimateSize,\n  GetItemKey,\n  VirtualAlign,\n  VirtualItem,\n  VirtualMeasurement,\n  VirtualRange,\n  VirtualScrollOptions,\n  VirtualSnapshot,\n  Virtualizer,\n  VirtualizerOptions\n}\n\ntype MaybeEl = HTMLElement | null | undefined\n\nexport interface UseVirtualizerOptions extends Omit<VirtualizerOptions, 'count'> {\n  /** 响应式虚拟项总数；内部 `watch` 驱动 `virtualizer.setCount`。 */\n  count: Ref<number>\n  /**\n   * 响应式滚动容器；变更时自动 `connect` / `disconnect`。\n   * `immediate: true`，初始为 `null` 时等价于 `disconnect()`。\n   */\n  scrollEl: MaybeRefOrGetter<MaybeEl>\n  /**\n   * 可选：内容承接元素。hook 订阅到结构性更新时直接写入\n   * `style.height = totalSize + 'px'`（水平模式为 `width`），\n   * **不经过 Vue 响应式**——因此 `totalSize` 的变化不会触发模板重渲染。\n   * 当引用切换为 `null` 时，会清空此前写入的内联尺寸，恢复 CSS 默认。\n   */\n  contentEl?: MaybeRefOrGetter<MaybeEl>\n  /** 可选：首项前占位元素。语义同 `contentEl`，写 `beforeSize`。 */\n  beforeEl?: MaybeRefOrGetter<MaybeEl>\n  /** 可选：末项后占位元素。语义同 `contentEl`，写 `afterSize`。 */\n  afterEl?: MaybeRefOrGetter<MaybeEl>\n}\n\nexport interface UseVirtualizerReturned {\n  /**\n   * 底层 `Virtualizer` 实例。\n   *\n   * 未做包装；消费者可直接调用 `scrollToIndex` / `scrollToOffset` /\n   * `reset` / `measureMany` / `setOptions` / `measureElement` 等方法。\n   */\n  virtualizer: Virtualizer\n  /**\n   * 完整快照 shallowRef。任一结构性变化（items/range/isScrolling/各种 size）都会更新。\n   * 大多数消费者只需 `items` / `isScrolling`，此 ref 仅在需要 `range` / `totalSize` 等\n   * 其它字段时使用。\n   */\n  snapshot: ShallowRef<VirtualSnapshot>\n  /**\n   * 仅在底层 `items` 引用变化时才更新的 shallowRef。\n   *\n   * 独立于 `snapshot`，用于模板 `v-for`；这样 `isScrolling` 等字段的切换不会\n   * 连带触发 `items.map(...)` 的重新求值。\n   */\n  items: ShallowRef<VirtualItem[]>\n  /** 仅在布尔值变化时更新的 `isScrolling` 状态。 */\n  isScrolling: ShallowRef<boolean>\n}\n\nfunction writeSize(el: MaybeEl, size: number, horizontal: boolean): void {\n  if (!el) return\n  if (horizontal) el.style.width = `${size}px`\n  else el.style.height = `${size}px`\n}\n\nfunction clearSize(el: MaybeEl, horizontal: boolean): void {\n  if (!el) return\n  if (horizontal) el.style.width = ''\n  else el.style.height = ''\n}\n\n/**\n * Vue 适配层：把 `@cat-kit/fe` 的 `Virtualizer` 生命周期与响应式系统对接。\n *\n * 设计原则：\n * 1. **尺寸写入走 DOM**：`contentEl` / `beforeEl` / `afterEl` 一旦传入，\n *    hook 在 `subscribe` 回调中命令式写 `style.height`；消费者模板无需绑定\n *    `totalSize` / `beforeSize` / `afterSize`，滚动时 Vue 不会因尺寸变化重渲染。\n * 2. **`items` / `isScrolling` 独立拆分**：底层 subscribe 一次回调可能同时包含\n *    items 变化与 isScrolling 切换；拆成两个 shallowRef 后，消费者 `v-for`\n *    的 `computed(() => items.value.map(...))` 不会因 `isScrolling` 变化而重新执行。\n * 3. **业务语义外置**：阈值判定 / key 组装 / `scrollToIndex` 对齐方式由消费者组装。\n *\n * 约束：\n * - `initialOffset` / `initialViewport` 仅构造时生效，后续 `setOptions` 忽略（底层契约）。\n * - 消费者若需运行时切换 `estimateSize` / `getItemKey` 等字段，调用 `virtualizer.setOptions(...)`。\n */\nexport function useVirtualizer(options: UseVirtualizerOptions): UseVirtualizerReturned {\n  const { count, scrollEl, contentEl, beforeEl, afterEl, ...initOptions } = options\n  const horizontal = initOptions.horizontal === true\n\n  const virtualizer = new Virtualizer({ ...initOptions, count: count.value })\n\n  const initialSnapshot = virtualizer.getSnapshot()\n  const snapshot = shallowRef<VirtualSnapshot>(initialSnapshot)\n  const items = shallowRef<VirtualItem[]>(initialSnapshot.items)\n  const isScrolling = shallowRef<boolean>(initialSnapshot.isScrolling)\n\n  function flushSizes(s: VirtualSnapshot): void {\n    writeSize(toValue(contentEl) ?? null, s.totalSize, horizontal)\n    writeSize(toValue(beforeEl) ?? null, s.beforeSize, horizontal)\n    writeSize(toValue(afterEl) ?? null, s.afterSize, horizontal)\n  }\n\n  // 初次同步，覆盖构造阶段 count > 0 场景（容器未 connect 时 totalSize 已有值）。\n  flushSizes(initialSnapshot)\n\n  const unsubscribe = virtualizer.subscribe((next) => {\n    snapshot.value = next\n    if (next.items !== items.value) items.value = next.items\n    if (next.isScrolling !== isScrolling.value) isScrolling.value = next.isScrolling\n    flushSizes(next)\n  })\n\n  watch(count, (c) => {\n    virtualizer.setCount(c)\n  })\n\n  watch(\n    () => toValue(scrollEl) ?? null,\n    (el) => {\n      if (el) virtualizer.connect(el)\n      else virtualizer.disconnect()\n    },\n    { immediate: true }\n  )\n\n  // 元素引用切换时：清旧元素的内联尺寸 + 立即给新元素写入当前快照值。\n  // 不向 hook 返回值暴露这些元素（消费者用 :ref 绑定自己的 ref 即可）。\n  function bindSizeSlot(\n    source: MaybeRefOrGetter<MaybeEl> | undefined,\n    pick: (s: VirtualSnapshot) => number\n  ): void {\n    if (source === undefined) return\n    watch(\n      () => toValue(source) ?? null,\n      (el, oldEl) => {\n        if (oldEl && oldEl !== el) clearSize(oldEl, horizontal)\n        if (el) writeSize(el, pick(snapshot.value), horizontal)\n      }\n    )\n  }\n\n  bindSizeSlot(contentEl, (s) => s.totalSize)\n  bindSizeSlot(beforeEl, (s) => s.beforeSize)\n  bindSizeSlot(afterEl, (s) => s.afterSize)\n\n  onScopeDispose(() => {\n    unsubscribe()\n    virtualizer.destroy()\n    clearSize(toValue(contentEl) ?? null, horizontal)\n    clearSize(toValue(beforeEl) ?? null, horizontal)\n    clearSize(toValue(afterEl) ?? null, horizontal)\n  })\n\n  return { virtualizer, snapshot, items, isScrolling }\n}\n"],"mappings":";;;AAmFA,SAAS,UAAU,IAAa,MAAc,YAA2B;AACvE,KAAI,CAAC,GAAI;AACT,KAAI,WAAY,IAAG,MAAM,QAAQ,GAAG,KAAK;KACpC,IAAG,MAAM,SAAS,GAAG,KAAK;;AAGjC,SAAS,UAAU,IAAa,YAA2B;AACzD,KAAI,CAAC,GAAI;AACT,KAAI,WAAY,IAAG,MAAM,QAAQ;KAC5B,IAAG,MAAM,SAAS;;;;;;;;;;;;;;;;;;AAmBzB,SAAgB,eAAe,SAAwD;CACrF,MAAM,EAAE,OAAO,UAAU,WAAW,UAAU,SAAS,GAAG,gBAAgB;CAC1E,MAAM,aAAa,YAAY,eAAe;CAE9C,MAAM,cAAc,IAAI,YAAY;EAAE,GAAG;EAAa,OAAO,MAAM;EAAO,CAAC;CAE3E,MAAM,kBAAkB,YAAY,aAAa;CACjD,MAAM,WAAW,WAA4B,gBAAgB;CAC7D,MAAM,QAAQ,WAA0B,gBAAgB,MAAM;CAC9D,MAAM,cAAc,WAAoB,gBAAgB,YAAY;CAEpE,SAAS,WAAW,GAA0B;AAC5C,YAAU,QAAQ,UAAU,IAAI,MAAM,EAAE,WAAW,WAAW;AAC9D,YAAU,QAAQ,SAAS,IAAI,MAAM,EAAE,YAAY,WAAW;AAC9D,YAAU,QAAQ,QAAQ,IAAI,MAAM,EAAE,WAAW,WAAW;;AAI9D,YAAW,gBAAgB;CAE3B,MAAM,cAAc,YAAY,WAAW,SAAS;AAClD,WAAS,QAAQ;AACjB,MAAI,KAAK,UAAU,MAAM,MAAO,OAAM,QAAQ,KAAK;AACnD,MAAI,KAAK,gBAAgB,YAAY,MAAO,aAAY,QAAQ,KAAK;AACrE,aAAW,KAAK;GAChB;AAEF,OAAM,QAAQ,MAAM;AAClB,cAAY,SAAS,EAAE;GACvB;AAEF,aACQ,QAAQ,SAAS,IAAI,OAC1B,OAAO;AACN,MAAI,GAAI,aAAY,QAAQ,GAAG;MAC1B,aAAY,YAAY;IAE/B,EAAE,WAAW,MAAM,CACpB;CAID,SAAS,aACP,QACA,MACM;AACN,MAAI,WAAW,KAAA,EAAW;AAC1B,cACQ,QAAQ,OAAO,IAAI,OACxB,IAAI,UAAU;AACb,OAAI,SAAS,UAAU,GAAI,WAAU,OAAO,WAAW;AACvD,OAAI,GAAI,WAAU,IAAI,KAAK,SAAS,MAAM,EAAE,WAAW;IAE1D;;AAGH,cAAa,YAAY,MAAM,EAAE,UAAU;AAC3C,cAAa,WAAW,MAAM,EAAE,WAAW;AAC3C,cAAa,UAAU,MAAM,EAAE,UAAU;AAEzC,sBAAqB;AACnB,eAAa;AACb,cAAY,SAAS;AACrB,YAAU,QAAQ,UAAU,IAAI,MAAM,WAAW;AACjD,YAAU,QAAQ,SAAS,IAAI,MAAM,WAAW;AAChD,YAAU,QAAQ,QAAQ,IAAI,MAAM,WAAW;GAC/C;AAEF,QAAO;EAAE;EAAa;EAAU;EAAO;EAAa"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veltra/compositions",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "files": [
     "dist",
     "src"
@@ -17,15 +17,12 @@
     "check-types": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@cat-kit/core": "^1.0.1",
+    "@cat-kit/core": "^1.1.1",
+    "@cat-kit/fe": "^1.1.1",
     "@floating-ui/dom": "^1.7.6",
-    "@tanstack/vue-virtual": "^3.13.23",
-    "@veltra/utils": "1.0.8"
-  },
-  "devDependencies": {
-    "tsdown": "^0.21.7"
+    "@veltra/utils": "1.0.9"
   },
   "peerDependencies": {
-    "vue": "^3.5.0"
+    "vue": "^3.5.33"
   }
 }

package/src/index.ts

@@ -10,7 +10,7 @@ export * from './use-focus'
 
 export * from './use-form-component'
 
-export * from './use-lock'
+export * from './use-user-action'
 
 export * from './use-model'
 
@@ -22,4 +22,4 @@ export * from './use-resize-observer'
 
 export * from './use-transition'
 
-export * from './use-virtual'
+export * from './use-virtualizer'

package/src/use-user-action/index.ts

@@ -0,0 +1,56 @@
+import { nextTick } from 'vue'
+
+export type UserAction = <T extends (...args: any[]) => void | Promise<void>>(
+  fn: T
+) => (...args: Parameters<T>) => Promise<void>
+
+export interface UserActionResult {
+  isUserActive: () => boolean
+  userAction: UserAction
+}
+
+/**
+ * 创建用户活动
+ * @description
+ * 解决"组件内部 emit 更新 → 外部 props 回传 → 监听 props 的副作用再次触发
+ * 内部状态变更"的循环更新问题。典型搭配：
+ *
+ * ```ts
+ * const { userAction, isUserActive } = useUserAction()
+ *
+ * // 将函数标记为一个用户动作
+ * const handleSelect = userAction((date: Dater) => {
+ *   currentDate.value = date
+ *   emit('update:modelValue', date.format(fmt))
+ * })
+ *
+ * // modelValue 回显：用户活动期间跳过
+ * watch(() => props.modelValue, (v) => {
+ *   if (isUserActive()) return
+ *   currentDate.value = v ? date(v) : undefined
+ * })
+ * ```
+ */
+export function useUserAction(): UserActionResult {
+  let actionCount = 0
+  const isUserActive = () => {
+    return actionCount > 0
+  }
+
+  const userAction: UserAction = (fn) => {
+    return async (...args) => {
+      actionCount++
+
+      try {
+        await fn(...args)
+      } catch (error) {
+        console.error(error)
+      }
+      await nextTick()
+
+      actionCount--
+    }
+  }
+
+  return { isUserActive, userAction }
+}

package/src/use-virtualizer/index.ts

@@ -0,0 +1,181 @@
+import {
+  Virtualizer,
+  type EstimateSize,
+  type GetItemKey,
+  type VirtualAlign,
+  type VirtualItem,
+  type VirtualMeasurement,
+  type VirtualRange,
+  type VirtualScrollOptions,
+  type VirtualSnapshot,
+  type VirtualizerOptions
+} from '@cat-kit/fe'
+import {
+  onScopeDispose,
+  shallowRef,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+  type Ref,
+  type ShallowRef
+} from 'vue'
+
+export type {
+  EstimateSize,
+  GetItemKey,
+  VirtualAlign,
+  VirtualItem,
+  VirtualMeasurement,
+  VirtualRange,
+  VirtualScrollOptions,
+  VirtualSnapshot,
+  Virtualizer,
+  VirtualizerOptions
+}
+
+type MaybeEl = HTMLElement | null | undefined
+
+export interface UseVirtualizerOptions extends Omit<VirtualizerOptions, 'count'> {
+  /** 响应式虚拟项总数；内部 `watch` 驱动 `virtualizer.setCount`。 */
+  count: Ref<number>
+  /**
+   * 响应式滚动容器；变更时自动 `connect` / `disconnect`。
+   * `immediate: true`，初始为 `null` 时等价于 `disconnect()`。
+   */
+  scrollEl: MaybeRefOrGetter<MaybeEl>
+  /**
+   * 可选：内容承接元素。hook 订阅到结构性更新时直接写入
+   * `style.height = totalSize + 'px'`（水平模式为 `width`），
+   * **不经过 Vue 响应式**——因此 `totalSize` 的变化不会触发模板重渲染。
+   * 当引用切换为 `null` 时，会清空此前写入的内联尺寸，恢复 CSS 默认。
+   */
+  contentEl?: MaybeRefOrGetter<MaybeEl>
+  /** 可选：首项前占位元素。语义同 `contentEl`，写 `beforeSize`。 */
+  beforeEl?: MaybeRefOrGetter<MaybeEl>
+  /** 可选：末项后占位元素。语义同 `contentEl`，写 `afterSize`。 */
+  afterEl?: MaybeRefOrGetter<MaybeEl>
+}
+
+export interface UseVirtualizerReturned {
+  /**
+   * 底层 `Virtualizer` 实例。
+   *
+   * 未做包装；消费者可直接调用 `scrollToIndex` / `scrollToOffset` /
+   * `reset` / `measureMany` / `setOptions` / `measureElement` 等方法。
+   */
+  virtualizer: Virtualizer
+  /**
+   * 完整快照 shallowRef。任一结构性变化（items/range/isScrolling/各种 size）都会更新。
+   * 大多数消费者只需 `items` / `isScrolling`，此 ref 仅在需要 `range` / `totalSize` 等
+   * 其它字段时使用。
+   */
+  snapshot: ShallowRef<VirtualSnapshot>
+  /**
+   * 仅在底层 `items` 引用变化时才更新的 shallowRef。
+   *
+   * 独立于 `snapshot`，用于模板 `v-for`；这样 `isScrolling` 等字段的切换不会
+   * 连带触发 `items.map(...)` 的重新求值。
+   */
+  items: ShallowRef<VirtualItem[]>
+  /** 仅在布尔值变化时更新的 `isScrolling` 状态。 */
+  isScrolling: ShallowRef<boolean>
+}
+
+function writeSize(el: MaybeEl, size: number, horizontal: boolean): void {
+  if (!el) return
+  if (horizontal) el.style.width = `${size}px`
+  else el.style.height = `${size}px`
+}
+
+function clearSize(el: MaybeEl, horizontal: boolean): void {
+  if (!el) return
+  if (horizontal) el.style.width = ''
+  else el.style.height = ''
+}
+
+/**
+ * Vue 适配层：把 `@cat-kit/fe` 的 `Virtualizer` 生命周期与响应式系统对接。
+ *
+ * 设计原则：
+ * 1. **尺寸写入走 DOM**：`contentEl` / `beforeEl` / `afterEl` 一旦传入，
+ *    hook 在 `subscribe` 回调中命令式写 `style.height`；消费者模板无需绑定
+ *    `totalSize` / `beforeSize` / `afterSize`，滚动时 Vue 不会因尺寸变化重渲染。
+ * 2. **`items` / `isScrolling` 独立拆分**：底层 subscribe 一次回调可能同时包含
+ *    items 变化与 isScrolling 切换；拆成两个 shallowRef 后，消费者 `v-for`
+ *    的 `computed(() => items.value.map(...))` 不会因 `isScrolling` 变化而重新执行。
+ * 3. **业务语义外置**：阈值判定 / key 组装 / `scrollToIndex` 对齐方式由消费者组装。
+ *
+ * 约束：
+ * - `initialOffset` / `initialViewport` 仅构造时生效，后续 `setOptions` 忽略（底层契约）。
+ * - 消费者若需运行时切换 `estimateSize` / `getItemKey` 等字段，调用 `virtualizer.setOptions(...)`。
+ */
+export function useVirtualizer(options: UseVirtualizerOptions): UseVirtualizerReturned {
+  const { count, scrollEl, contentEl, beforeEl, afterEl, ...initOptions } = options
+  const horizontal = initOptions.horizontal === true
+
+  const virtualizer = new Virtualizer({ ...initOptions, count: count.value })
+
+  const initialSnapshot = virtualizer.getSnapshot()
+  const snapshot = shallowRef<VirtualSnapshot>(initialSnapshot)
+  const items = shallowRef<VirtualItem[]>(initialSnapshot.items)
+  const isScrolling = shallowRef<boolean>(initialSnapshot.isScrolling)
+
+  function flushSizes(s: VirtualSnapshot): void {
+    writeSize(toValue(contentEl) ?? null, s.totalSize, horizontal)
+    writeSize(toValue(beforeEl) ?? null, s.beforeSize, horizontal)
+    writeSize(toValue(afterEl) ?? null, s.afterSize, horizontal)
+  }
+
+  // 初次同步，覆盖构造阶段 count > 0 场景（容器未 connect 时 totalSize 已有值）。
+  flushSizes(initialSnapshot)
+
+  const unsubscribe = virtualizer.subscribe((next) => {
+    snapshot.value = next
+    if (next.items !== items.value) items.value = next.items
+    if (next.isScrolling !== isScrolling.value) isScrolling.value = next.isScrolling
+    flushSizes(next)
+  })
+
+  watch(count, (c) => {
+    virtualizer.setCount(c)
+  })
+
+  watch(
+    () => toValue(scrollEl) ?? null,
+    (el) => {
+      if (el) virtualizer.connect(el)
+      else virtualizer.disconnect()
+    },
+    { immediate: true }
+  )
+
+  // 元素引用切换时：清旧元素的内联尺寸 + 立即给新元素写入当前快照值。
+  // 不向 hook 返回值暴露这些元素（消费者用 :ref 绑定自己的 ref 即可）。
+  function bindSizeSlot(
+    source: MaybeRefOrGetter<MaybeEl> | undefined,
+    pick: (s: VirtualSnapshot) => number
+  ): void {
+    if (source === undefined) return
+    watch(
+      () => toValue(source) ?? null,
+      (el, oldEl) => {
+        if (oldEl && oldEl !== el) clearSize(oldEl, horizontal)
+        if (el) writeSize(el, pick(snapshot.value), horizontal)
+      }
+    )
+  }
+
+  bindSizeSlot(contentEl, (s) => s.totalSize)
+  bindSizeSlot(beforeEl, (s) => s.beforeSize)
+  bindSizeSlot(afterEl, (s) => s.afterSize)
+
+  onScopeDispose(() => {
+    unsubscribe()
+    virtualizer.destroy()
+    clearSize(toValue(contentEl) ?? null, horizontal)
+    clearSize(toValue(beforeEl) ?? null, horizontal)
+    clearSize(toValue(afterEl) ?? null, horizontal)
+  })
+
+  return { virtualizer, snapshot, items, isScrolling }
+}

package/dist/use-lock/index.d.ts

@@ -1,28 +0,0 @@
-//#region src/use-lock/index.d.ts
-type Update = (fn: Function) => any;
-type Lock = (fn: Function) => Promise<void>;
-interface Updater {
-  /**
-   * 更新
-   * @description 在非锁定时执行传入的函数
-   */
-  update: Update;
-  /**
-   * 更新并锁定
-   * @description 执行传入的函数，并锁定更新操作，直到函数执行完成
-   */
-  updateAndLock: Lock;
-}
-/**
- * 数据更新锁
- * @description
- * 更新锁主要用于防止组件数据更新时，循环触发更新。
- *
- * @returns 该函数返回两个函数：
- * 1. update: 更新函数，在非锁定时执行传入的函数
- * 2. lock: 锁定函数，执行时会锁定更新操作，直到锁定操作结束
- */
-declare function useUpdateLock(): Updater;
-//#endregion
-export { Updater, useUpdateLock };
-//# sourceMappingURL=index.d.ts.map

package/dist/use-lock/index.js

@@ -1,36 +0,0 @@
-import { nextTick } from "vue";
-//#region src/use-lock/index.ts
-/**
-* 数据更新锁
-* @description
-* 更新锁主要用于防止组件数据更新时，循环触发更新。
-*
-* @returns 该函数返回两个函数：
-* 1. update: 更新函数，在非锁定时执行传入的函数
-* 2. lock: 锁定函数，执行时会锁定更新操作，直到锁定操作结束
-*/
-function useUpdateLock() {
-	let lockedCount = 0;
-	function update(fn) {
-		if (lockedCount > 0) return;
-		return fn();
-	}
-	async function updateAndLock(fn) {
-		lockedCount++;
-		try {
-			await fn();
-		} catch (error) {
-			console.error(error);
-		}
-		await nextTick();
-		lockedCount--;
-	}
-	return {
-		updateAndLock,
-		update
-	};
-}
-//#endregion
-export { useUpdateLock };
-
-//# sourceMappingURL=index.js.map

package/dist/use-lock/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/use-lock/index.ts"],"sourcesContent":["import { nextTick } from 'vue'\n\ntype Update = (fn: Function) => any\ntype Lock = (fn: Function) => Promise<void>\n\nexport interface Updater {\n  /**\n   * 更新\n   * @description 在非锁定时执行传入的函数\n   */\n  update: Update\n  /**\n   * 更新并锁定\n   * @description 执行传入的函数，并锁定更新操作，直到函数执行完成\n   */\n  updateAndLock: Lock\n}\n\n/**\n * 数据更新锁\n * @description\n * 更新锁主要用于防止组件数据更新时，循环触发更新。\n *\n * @returns 该函数返回两个函数：\n * 1. update: 更新函数，在非锁定时执行传入的函数\n * 2. lock: 锁定函数，执行时会锁定更新操作，直到锁定操作结束\n */\nexport function useUpdateLock(): Updater {\n  let lockedCount = 0\n\n  function update(fn: Function) {\n    if (lockedCount > 0) return\n    return fn()\n  }\n\n  async function updateAndLock(fn: Function) {\n    lockedCount++\n\n    try {\n      await fn()\n    } catch (error) {\n      console.error(error)\n    }\n    await nextTick()\n\n    lockedCount--\n  }\n\n  return { updateAndLock, update }\n}\n"],"mappings":";;;;;;;;;;;AA2BA,SAAgB,gBAAyB;CACvC,IAAI,cAAc;CAElB,SAAS,OAAO,IAAc;AAC5B,MAAI,cAAc,EAAG;AACrB,SAAO,IAAI;;CAGb,eAAe,cAAc,IAAc;AACzC;AAEA,MAAI;AACF,SAAM,IAAI;WACH,OAAO;AACd,WAAQ,MAAM,MAAM;;AAEtB,QAAM,UAAU;AAEhB;;AAGF,QAAO;EAAE;EAAe;EAAQ"}

package/dist/use-virtual/index.d.ts

@@ -1,30 +0,0 @@
-import { ComputedRef, Ref, ShallowRef } from "vue";
-import { VirtualItem } from "@tanstack/vue-virtual";
-
-//#region src/use-virtual/index.d.ts
-interface Options {
-  /** 指定启用虚拟列表的阈值 */
-  virtualThreshold?: number | Ref<number | undefined>;
-  /** 数量 */
-  count: Ref<number>;
-  /** 滚动容器 */
-  scrollEl: ShallowRef<HTMLElement | null>;
-  /** 估算高度(宽度) */
-  estimateSize?: (index: number) => number;
-  /** 列表项之间的间距 */
-  gap?: number;
-}
-type CustomVirtualItem = Omit<VirtualItem, 'key'> & {
-  key: number | string;
-};
-type VirtualReturned = {
-  /** 虚拟列表 */virtualList: ShallowRef<CustomVirtualItem[]>; /** 总高度 */
-  totalHeight: ShallowRef<number>; /** 测量元素高度 */
-  measureElement: (el: any) => void; /** 滚动到指定索引 */
-  scrollTo: (index: number) => void; /** 是否启用虚拟列表 */
-  virtualEnabled: ComputedRef<boolean>;
-};
-declare function useVirtual(options: Options): VirtualReturned;
-//#endregion
-export { VirtualReturned, useVirtual };
-//# sourceMappingURL=index.d.ts.map

package/dist/use-virtual/index.js

@@ -1,67 +0,0 @@
-import { computed, isRef, onScopeDispose, shallowRef, watch } from "vue";
-import { Virtualizer, elementScroll, observeElementOffset, observeElementRect } from "@tanstack/vue-virtual";
-//#region src/use-virtual/index.ts
-const defaultEstimateSize = () => 34;
-function useVirtual(options) {
-	const { count, scrollEl, estimateSize, virtualThreshold, gap } = options;
-	const enabled = computed(() => {
-		if (isRef(virtualThreshold)) return virtualThreshold.value ? count.value > virtualThreshold.value : true;
-		return virtualThreshold ? count.value > virtualThreshold : true;
-	});
-	const virtualList = shallowRef([]);
-	/** 总高度 */
-	const totalHeight = shallowRef(0);
-	function updateVirtualList() {
-		if (enabled.value) {
-			totalHeight.value = v.getTotalSize();
-			virtualList.value = v.getVirtualItems();
-		}
-	}
-	const virtualizerOptions = computed(() => {
-		return {
-			enabled: enabled.value,
-			count: count.value,
-			getScrollElement: () => scrollEl.value,
-			estimateSize: estimateSize ?? defaultEstimateSize,
-			overscan: 3,
-			gap,
-			observeElementRect,
-			observeElementOffset,
-			scrollToFn: elementScroll,
-			onChange: updateVirtualList
-		};
-	});
-	const v = new Virtualizer(virtualizerOptions.value);
-	updateVirtualList();
-	const cleanup = v._didMount();
-	watch(scrollEl, (el) => {
-		el && v._willUpdate();
-	}, { immediate: true });
-	watch(() => virtualizerOptions.value, (o) => {
-		v.setOptions(o);
-		v._willUpdate();
-		updateVirtualList();
-	});
-	onScopeDispose(() => {
-		cleanup();
-	});
-	function scrollTo(index) {
-		v.scrollToIndex(index, { align: "center" });
-	}
-	/** 测量元素高度 */
-	function measureElement(el) {
-		if (!el) return;
-		v.measureElement(el);
-	}
-	return {
-		virtualEnabled: enabled,
-		virtualList,
-		totalHeight,
-		measureElement,
-		scrollTo
-	};
-}
-//#endregion
-export { useVirtual };
-
-//# sourceMappingURL=index.js.map

package/dist/use-virtual/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/use-virtual/index.ts"],"sourcesContent":["import {\n  elementScroll,\n  observeElementOffset,\n  observeElementRect,\n  type VirtualItem,\n  Virtualizer\n} from '@tanstack/vue-virtual'\nimport {\n  computed,\n  isRef,\n  onScopeDispose,\n  shallowRef,\n  watch,\n  type ComputedRef,\n  type Ref,\n  type ShallowRef\n} from 'vue'\n\ninterface Options {\n  /** 指定启用虚拟列表的阈值 */\n  virtualThreshold?: number | Ref<number | undefined>\n  /** 数量 */\n  count: Ref<number>\n  /** 滚动容器 */\n  scrollEl: ShallowRef<HTMLElement | null>\n  /** 估算高度(宽度) */\n  estimateSize?: (index: number) => number\n  /** 列表项之间的间距 */\n  gap?: number\n}\n\ntype CustomVirtualItem = Omit<VirtualItem, 'key'> & { key: number | string }\n\nexport type VirtualReturned = {\n  /** 虚拟列表 */\n  virtualList: ShallowRef<CustomVirtualItem[]>\n  /** 总高度 */\n  totalHeight: ShallowRef<number>\n  /** 测量元素高度 */\n  measureElement: (el: any) => void\n  /** 滚动到指定索引 */\n  scrollTo: (index: number) => void\n  /** 是否启用虚拟列表 */\n  virtualEnabled: ComputedRef<boolean>\n}\n\nconst defaultEstimateSize = () => 34\n\nexport function useVirtual(options: Options): VirtualReturned {\n  const { count, scrollEl, estimateSize, virtualThreshold, gap } = options\n\n  const enabled = computed(() => {\n    if (isRef(virtualThreshold)) {\n      return virtualThreshold.value ? count.value > virtualThreshold.value : true\n    }\n\n    return virtualThreshold ? count.value > virtualThreshold : true\n  })\n\n  const virtualList = shallowRef<CustomVirtualItem[]>([])\n\n  /** 总高度 */\n  const totalHeight = shallowRef(0)\n\n  function updateVirtualList() {\n    if (enabled.value) {\n      totalHeight.value = v.getTotalSize()\n      virtualList.value = v.getVirtualItems() as CustomVirtualItem[]\n    }\n  }\n\n  const virtualizerOptions = computed(() => {\n    return {\n      enabled: enabled.value,\n      count: count.value,\n      getScrollElement: () => scrollEl.value,\n      estimateSize: estimateSize ?? defaultEstimateSize,\n      overscan: 3,\n      gap,\n      observeElementRect: observeElementRect,\n      observeElementOffset: observeElementOffset,\n      scrollToFn: elementScroll,\n      onChange: updateVirtualList\n    }\n  })\n\n  const v = new Virtualizer(virtualizerOptions.value)\n\n  updateVirtualList()\n\n  const cleanup = v._didMount()\n\n  watch(\n    scrollEl,\n    (el) => {\n      el && v._willUpdate()\n    },\n    { immediate: true }\n  )\n\n  watch(\n    () => virtualizerOptions.value,\n    (o) => {\n      v.setOptions(o)\n\n      v._willUpdate()\n\n      updateVirtualList()\n    }\n  )\n\n  onScopeDispose(() => {\n    cleanup()\n  })\n\n  function scrollTo(index: number) {\n    v.scrollToIndex(index, { align: 'center' })\n  }\n\n  /** 测量元素高度 */\n  function measureElement(el: Element) {\n    if (!el) return\n\n    v.measureElement(el)\n\n    return undefined\n  }\n\n  return { virtualEnabled: enabled, virtualList, totalHeight, measureElement, scrollTo }\n}\n"],"mappings":";;;AA8CA,MAAM,4BAA4B;AAElC,SAAgB,WAAW,SAAmC;CAC5D,MAAM,EAAE,OAAO,UAAU,cAAc,kBAAkB,QAAQ;CAEjE,MAAM,UAAU,eAAe;AAC7B,MAAI,MAAM,iBAAiB,CACzB,QAAO,iBAAiB,QAAQ,MAAM,QAAQ,iBAAiB,QAAQ;AAGzE,SAAO,mBAAmB,MAAM,QAAQ,mBAAmB;GAC3D;CAEF,MAAM,cAAc,WAAgC,EAAE,CAAC;;CAGvD,MAAM,cAAc,WAAW,EAAE;CAEjC,SAAS,oBAAoB;AAC3B,MAAI,QAAQ,OAAO;AACjB,eAAY,QAAQ,EAAE,cAAc;AACpC,eAAY,QAAQ,EAAE,iBAAiB;;;CAI3C,MAAM,qBAAqB,eAAe;AACxC,SAAO;GACL,SAAS,QAAQ;GACjB,OAAO,MAAM;GACb,wBAAwB,SAAS;GACjC,cAAc,gBAAgB;GAC9B,UAAU;GACV;GACoB;GACE;GACtB,YAAY;GACZ,UAAU;GACX;GACD;CAEF,MAAM,IAAI,IAAI,YAAY,mBAAmB,MAAM;AAEnD,oBAAmB;CAEnB,MAAM,UAAU,EAAE,WAAW;AAE7B,OACE,WACC,OAAO;AACN,QAAM,EAAE,aAAa;IAEvB,EAAE,WAAW,MAAM,CACpB;AAED,aACQ,mBAAmB,QACxB,MAAM;AACL,IAAE,WAAW,EAAE;AAEf,IAAE,aAAa;AAEf,qBAAmB;GAEtB;AAED,sBAAqB;AACnB,WAAS;GACT;CAEF,SAAS,SAAS,OAAe;AAC/B,IAAE,cAAc,OAAO,EAAE,OAAO,UAAU,CAAC;;;CAI7C,SAAS,eAAe,IAAa;AACnC,MAAI,CAAC,GAAI;AAET,IAAE,eAAe,GAAG;;AAKtB,QAAO;EAAE,gBAAgB;EAAS;EAAa;EAAa;EAAgB;EAAU"}

package/src/use-lock/index.ts

@@ -1,50 +0,0 @@
-import { nextTick } from 'vue'
-
-type Update = (fn: Function) => any
-type Lock = (fn: Function) => Promise<void>
-
-export interface Updater {
-  /**
-   * 更新
-   * @description 在非锁定时执行传入的函数
-   */
-  update: Update
-  /**
-   * 更新并锁定
-   * @description 执行传入的函数，并锁定更新操作，直到函数执行完成
-   */
-  updateAndLock: Lock
-}
-
-/**
- * 数据更新锁
- * @description
- * 更新锁主要用于防止组件数据更新时，循环触发更新。
- *
- * @returns 该函数返回两个函数：
- * 1. update: 更新函数，在非锁定时执行传入的函数
- * 2. lock: 锁定函数，执行时会锁定更新操作，直到锁定操作结束
- */
-export function useUpdateLock(): Updater {
-  let lockedCount = 0
-
-  function update(fn: Function) {
-    if (lockedCount > 0) return
-    return fn()
-  }
-
-  async function updateAndLock(fn: Function) {
-    lockedCount++
-
-    try {
-      await fn()
-    } catch (error) {
-      console.error(error)
-    }
-    await nextTick()
-
-    lockedCount--
-  }
-
-  return { updateAndLock, update }
-}

package/src/use-virtual/index.ts

@@ -1,130 +0,0 @@
-import {
-  elementScroll,
-  observeElementOffset,
-  observeElementRect,
-  type VirtualItem,
-  Virtualizer
-} from '@tanstack/vue-virtual'
-import {
-  computed,
-  isRef,
-  onScopeDispose,
-  shallowRef,
-  watch,
-  type ComputedRef,
-  type Ref,
-  type ShallowRef
-} from 'vue'
-
-interface Options {
-  /** 指定启用虚拟列表的阈值 */
-  virtualThreshold?: number | Ref<number | undefined>
-  /** 数量 */
-  count: Ref<number>
-  /** 滚动容器 */
-  scrollEl: ShallowRef<HTMLElement | null>
-  /** 估算高度(宽度) */
-  estimateSize?: (index: number) => number
-  /** 列表项之间的间距 */
-  gap?: number
-}
-
-type CustomVirtualItem = Omit<VirtualItem, 'key'> & { key: number | string }
-
-export type VirtualReturned = {
-  /** 虚拟列表 */
-  virtualList: ShallowRef<CustomVirtualItem[]>
-  /** 总高度 */
-  totalHeight: ShallowRef<number>
-  /** 测量元素高度 */
-  measureElement: (el: any) => void
-  /** 滚动到指定索引 */
-  scrollTo: (index: number) => void
-  /** 是否启用虚拟列表 */
-  virtualEnabled: ComputedRef<boolean>
-}
-
-const defaultEstimateSize = () => 34
-
-export function useVirtual(options: Options): VirtualReturned {
-  const { count, scrollEl, estimateSize, virtualThreshold, gap } = options
-
-  const enabled = computed(() => {
-    if (isRef(virtualThreshold)) {
-      return virtualThreshold.value ? count.value > virtualThreshold.value : true
-    }
-
-    return virtualThreshold ? count.value > virtualThreshold : true
-  })
-
-  const virtualList = shallowRef<CustomVirtualItem[]>([])
-
-  /** 总高度 */
-  const totalHeight = shallowRef(0)
-
-  function updateVirtualList() {
-    if (enabled.value) {
-      totalHeight.value = v.getTotalSize()
-      virtualList.value = v.getVirtualItems() as CustomVirtualItem[]
-    }
-  }
-
-  const virtualizerOptions = computed(() => {
-    return {
-      enabled: enabled.value,
-      count: count.value,
-      getScrollElement: () => scrollEl.value,
-      estimateSize: estimateSize ?? defaultEstimateSize,
-      overscan: 3,
-      gap,
-      observeElementRect: observeElementRect,
-      observeElementOffset: observeElementOffset,
-      scrollToFn: elementScroll,
-      onChange: updateVirtualList
-    }
-  })
-
-  const v = new Virtualizer(virtualizerOptions.value)
-
-  updateVirtualList()
-
-  const cleanup = v._didMount()
-
-  watch(
-    scrollEl,
-    (el) => {
-      el && v._willUpdate()
-    },
-    { immediate: true }
-  )
-
-  watch(
-    () => virtualizerOptions.value,
-    (o) => {
-      v.setOptions(o)
-
-      v._willUpdate()
-
-      updateVirtualList()
-    }
-  )
-
-  onScopeDispose(() => {
-    cleanup()
-  })
-
-  function scrollTo(index: number) {
-    v.scrollToIndex(index, { align: 'center' })
-  }
-
-  /** 测量元素高度 */
-  function measureElement(el: Element) {
-    if (!el) return
-
-    v.measureElement(el)
-
-    return undefined
-  }
-
-  return { virtualEnabled: enabled, virtualList, totalHeight, measureElement, scrollTo }
-}