@kine-design/core 0.0.1-beta.5 → 0.0.1-beta.6

package/compositions/common/__tests__/useDebounceFn.test.ts

@@ -0,0 +1,62 @@
+/**
+ * @description useDebounceFn 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import useDebounceFn from '../useDebounceFn';
+
+beforeEach(() => { vi.useFakeTimers(); });
+afterEach(() => { vi.useRealTimers(); });
+
+describe('useDebounceFn', () => {
+  it('返回防抖后的函数', () => {
+    const fn = vi.fn();
+    const debounced = useDebounceFn(fn, 100);
+
+    debounced();
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('默认延迟 200ms', () => {
+    const fn = vi.fn();
+    const debounced = useDebounceFn(fn);
+
+    debounced();
+    vi.advanceTimersByTime(199);
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(1);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('支持 maxWait 选项', () => {
+    const fn = vi.fn();
+    const debounced = useDebounceFn(fn, 100, { maxWait: 150 });
+
+    debounced();
+    vi.advanceTimersByTime(80);
+    debounced();
+    vi.advanceTimersByTime(80);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('多次调用只执行最后一次', () => {
+    const fn = vi.fn();
+    const debounced = useDebounceFn(fn, 50);
+
+    debounced('a');
+    debounced('b');
+    debounced('c');
+
+    vi.advanceTimersByTime(50);
+    expect(fn).toHaveBeenCalledOnce();
+    expect(fn).toHaveBeenCalledWith('c');
+  });
+});

package/compositions/common/__tests__/useEventListener.test.ts

@@ -0,0 +1,71 @@
+/**
+ * @description useEventListener 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import useEventListener from '../useEventListener';
+
+describe('useEventListener', () => {
+  it('add 注册事件，remove 移除事件', () => {
+    const handler = vi.fn();
+    const target = {
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    };
+
+    const { add, remove } = useEventListener({
+      target,
+      event: 'click',
+      handler,
+    });
+
+    add();
+    expect(target.addEventListener).toHaveBeenCalledWith('click', handler);
+
+    remove();
+    expect(target.removeEventListener).toHaveBeenCalledWith('click', handler);
+  });
+
+  it('onMounted 调用 add，onBeforeUnmount 调用 remove', () => {
+    const handler = vi.fn();
+    const target = {
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    };
+
+    const { onMounted, onBeforeUnmount } = useEventListener({
+      target,
+      event: 'scroll',
+      handler,
+    });
+
+    onMounted();
+    expect(target.addEventListener).toHaveBeenCalledOnce();
+
+    onBeforeUnmount();
+    expect(target.removeEventListener).toHaveBeenCalledOnce();
+  });
+
+  it('target 为函数时延迟求值', () => {
+    const handler = vi.fn();
+    const realTarget = {
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    };
+    const targetFn = vi.fn(() => realTarget);
+
+    const { add } = useEventListener({
+      target: targetFn,
+      event: 'click',
+      handler,
+    });
+
+    add();
+    expect(targetFn).toHaveBeenCalled();
+    expect(realTarget.addEventListener).toHaveBeenCalledWith('click', handler);
+  });
+});

package/compositions/common/__tests__/usePopover.test.ts

@@ -0,0 +1,38 @@
+/**
+ * @description usePopover（common）测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import usePopover from '../usePopover';
+
+describe('usePopover', () => {
+  it('默认 placement 为 bottom-start', () => {
+    const { popoverOptions } = usePopover();
+    expect(popoverOptions.placement).toBe('bottom-start');
+  });
+
+  it('自定义 placement', () => {
+    const { popoverOptions } = usePopover({ placement: 'top-end' });
+    expect(popoverOptions.placement).toBe('top-end');
+  });
+
+  it('默认 middleware 包含 offset、flip、shift', () => {
+    const { popoverOptions } = usePopover();
+    expect(popoverOptions.popper?.middleware).toHaveLength(3);
+  });
+
+  it('自定义 offset', () => {
+    const { popoverOptions } = usePopover(undefined, { offset: 10 });
+    expect(popoverOptions.popper?.middleware).toHaveLength(3);
+  });
+
+  it('扩展 middleware', () => {
+    const customMiddleware = { name: 'custom', fn: () => ({}) };
+    const { popoverOptions } = usePopover(undefined, { extends: [customMiddleware as any] });
+    expect(popoverOptions.popper?.middleware).toHaveLength(4);
+  });
+});

package/compositions/common/__tests__/useTeleport.test.ts

@@ -0,0 +1,25 @@
+/**
+ * @description useTeleport / initTeleportOptions 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import { initTeleportOptions } from '../useTeleport';
+
+describe('initTeleportOptions', () => {
+  it('true 默认 teleport 到 body', () => {
+    expect(initTeleportOptions(true)).toEqual({ to: 'body' });
+  });
+
+  it('undefined 默认 teleport 到 body', () => {
+    expect(initTeleportOptions(undefined)).toEqual({ to: 'body' });
+  });
+
+  it('自定义配置直接返回', () => {
+    const custom = { to: '#app', disabled: false };
+    expect(initTeleportOptions(custom as any)).toBe(custom);
+  });
+});

package/compositions/common/useEventListener.ts

@@ -9,7 +9,7 @@
 
 
 export type EventListenerOptions = {
-  target: any,
+  target: EventTarget | (() => EventTarget),
   event: string,
   handler: EventListenerOrEventListenerObject,
 };
@@ -35,14 +35,14 @@ export default function useEventListener(options: EventListenerOptions) {
     add();
   };
 
-  const onBeforeDestroy = () => {
+  const onBeforeUnmount = () => {
     remove();
   };
 
   return {
     add, remove,
     onMounted,
-    onBeforeDestroy,
+    onBeforeUnmount,
   };
 
 }

package/compositions/common/useResizeObserver.ts

@@ -9,7 +9,7 @@
  * Learn from vueuse useResizeObserver
  */
 
-import { Ref, watch } from 'vue';
+import { onBeforeUnmount, Ref, watch } from 'vue';
 
 export function useResizeObserver(
   target: Ref<HTMLElement | null>,
@@ -27,7 +27,7 @@ export function useResizeObserver(
   };
 
   // vueuse used watch
-  watch(target, () => {
+  const stopWatch = watch(target, () => {
     if (target.value) {
       cleanup();
       observer = new ResizeObserver(callback);
@@ -35,6 +35,10 @@ export function useResizeObserver(
     }
   });
 
+  onBeforeUnmount(() => {
+    cleanup();
+    stopWatch();
+  });
 
   return {
     cleanup,

package/compositions/input/__tests__/useBooleanInput.test.ts

@@ -0,0 +1,73 @@
+/**
+ * @description initChecked / getNewModelValue 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import { initChecked, getNewModelValue } from '../useBooleanInput';
+
+describe('initChecked', () => {
+  it('checked 为 true 时直接返回 true', () => {
+    expect(initChecked({ checked: true, modelValue: undefined, value: undefined })).toBe(true);
+  });
+
+  it('modelValue 为 boolean 时返回该值', () => {
+    expect(initChecked({ checked: undefined, modelValue: true, value: undefined })).toBe(true);
+    expect(initChecked({ checked: undefined, modelValue: false, value: undefined })).toBe(false);
+  });
+
+  it('modelValue 和 value 相等时返回 true', () => {
+    expect(initChecked({ checked: undefined, modelValue: 'a', value: 'a' })).toBe(true);
+  });
+
+  it('modelValue 和 value 不等时返回 false', () => {
+    expect(initChecked({ checked: undefined, modelValue: 'a', value: 'b' })).toBe(false);
+  });
+
+  it('modelValue 为数组时，检查 value 是否在数组中', () => {
+    expect(initChecked({ checked: undefined, modelValue: ['a', 'b'], value: 'a' })).toBe(true);
+    expect(initChecked({ checked: undefined, modelValue: ['a', 'b'], value: 'c' })).toBe(false);
+  });
+
+  it('所有值为空时返回 false', () => {
+    expect(initChecked({ checked: undefined, modelValue: undefined, value: undefined })).toBe(false);
+    expect(initChecked({ checked: null, modelValue: null, value: null })).toBe(false);
+  });
+});
+
+describe('getNewModelValue', () => {
+  // 有 value 且 modelValue 为数组
+  it('checked=true 且 modelValue 为数组时添加 value', () => {
+    expect(getNewModelValue({ value: 'c', modelValue: ['a', 'b'] }, true)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('checked=false 且 modelValue 为数组时移除 value', () => {
+    expect(getNewModelValue({ value: 'b', modelValue: ['a', 'b'] }, false)).toEqual(['a']);
+  });
+
+  it('不重复添加已存在的 value', () => {
+    expect(getNewModelValue({ value: 'a', modelValue: ['a', 'b'] }, true)).toEqual(['a', 'b']);
+  });
+
+  it('移除不存在的 value 不报错', () => {
+    expect(getNewModelValue({ value: 'c', modelValue: ['a', 'b'] }, false)).toEqual(['a', 'b']);
+  });
+
+  // 有 value 且 modelValue 非数组
+  it('checked=true 返回 value', () => {
+    expect(getNewModelValue({ value: 'a', modelValue: undefined }, true)).toBe('a');
+  });
+
+  it('checked=false 返回 undefined', () => {
+    expect(getNewModelValue({ value: 'a', modelValue: undefined }, false)).toBeUndefined();
+  });
+
+  // 无 value
+  it('无 value 时直接返回 checked 布尔值', () => {
+    expect(getNewModelValue({ value: undefined, modelValue: undefined }, true)).toBe(true);
+    expect(getNewModelValue({ value: undefined, modelValue: undefined }, false)).toBe(false);
+  });
+});

package/compositions/modal/__tests__/useModal.test.ts

@@ -0,0 +1,92 @@
+/**
+ * @description useModal 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { useModal } from '../useModal';
+
+describe('useModal', () => {
+  it('初始 visible 默认为 false', () => {
+    const emit = vi.fn();
+    const { visible } = useModal({}, emit);
+    expect(visible.value).toBe(false);
+  });
+
+  it('初始 visible 跟随 props', () => {
+    const emit = vi.fn();
+    const { visible } = useModal({ visible: true }, emit);
+    expect(visible.value).toBe(true);
+  });
+
+  it('open 设置 visible 为 true 并触发 emit', () => {
+    const emit = vi.fn();
+    const { visible, open } = useModal({}, emit);
+
+    open();
+    expect(visible.value).toBe(true);
+    expect(emit).toHaveBeenCalledWith('update:visible', true);
+  });
+
+  it('close 设置 visible 为 false 并触发 emit', () => {
+    const emit = vi.fn();
+    const { visible, close } = useModal({ visible: true }, emit);
+
+    close();
+    expect(visible.value).toBe(false);
+    expect(emit).toHaveBeenCalledWith('update:visible', false);
+  });
+
+  it('toggle 切换 visible 状态', () => {
+    const emit = vi.fn();
+    const { visible, toggle } = useModal({}, emit);
+
+    toggle(); // false → true
+    expect(visible.value).toBe(true);
+
+    toggle(); // true → false
+    expect(visible.value).toBe(false);
+  });
+
+  it('onMaskClick 默认关闭', () => {
+    const emit = vi.fn();
+    const { visible, open, onMaskClick } = useModal({}, emit);
+
+    open();
+    onMaskClick();
+    expect(visible.value).toBe(false);
+  });
+
+  it('onMaskClick 当 mask.clickClose=false 时不关闭', () => {
+    const emit = vi.fn();
+    const { visible, open, onMaskClick } = useModal({ mask: { clickClose: false } }, emit);
+
+    open();
+    onMaskClick();
+    expect(visible.value).toBe(true);
+  });
+
+  it('showMask 默认返回 true', () => {
+    const emit = vi.fn();
+    const { showMask } = useModal({}, emit);
+    expect(showMask()).toBe(true);
+  });
+
+  it('showMask 当 mask.show=false 时返回 false', () => {
+    const emit = vi.fn();
+    const { showMask } = useModal({ mask: { show: false } }, emit);
+    expect(showMask()).toBe(false);
+  });
+
+  it('onContentClick 阻止冒泡', () => {
+    const emit = vi.fn();
+    const { onContentClick } = useModal({}, emit);
+    const event = { stopPropagation: vi.fn() } as unknown as MouseEvent;
+
+    onContentClick(event);
+    expect(event.stopPropagation).toHaveBeenCalled();
+  });
+});

package/compositions/modal/useModal.ts

@@ -9,6 +9,7 @@
  * 处理 visible 状态、遮罩层点击关闭、emit 同步
  */
 import { ref, watch } from 'vue';
+import { type HookContext } from '../../components/types/hook';
 import { ModelMask } from '../../types/common/model';
 
 export interface UseModalProps {
@@ -16,8 +17,7 @@ export interface UseModalProps {
   mask?: ModelMask;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function useModal(props: UseModalProps, emit: (...args: any[]) => void) {
+export function useModal(props: UseModalProps, emit: HookContext['emit']) {
   const visible = ref(props.visible ?? false);
 
   watch(() => props.visible, (val) => {

package/compositions/popper/useClickAway.ts

@@ -11,14 +11,14 @@ import useEventListener from '../common/useEventListener';
 
 const event = 'pointerdown';
 export default function useClickAway(options: {
-  target: any,
-  handler: (event: any) => void
+  target: EventTarget | (() => EventTarget | null | undefined),
+  handler: (event: PointerEvent) => void
 }) {
   if (typeof window === 'undefined' || !window) {
     return;
   }
 
-  const listener = (event: any) => {
+  const listener = (event: Event) => {
     const el = typeof options.target === 'function' ? options.target() : options.target;
     if (!el) {
       return;
@@ -28,7 +28,7 @@ export default function useClickAway(options: {
       return;
     }
 
-    options.handler(event);
+    options.handler(event as PointerEvent);
   };
 
   return useEventListener({

package/compositions/utils/__tests__/filters.test.ts

@@ -0,0 +1,136 @@
+/**
+ * @description debounceFilter / throttleFilter / createFilterWrapper 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { createFilterWrapper, debounceFilter, throttleFilter } from '../filters';
+
+beforeEach(() => { vi.useFakeTimers(); });
+afterEach(() => { vi.useRealTimers(); });
+
+describe('debounceFilter', () => {
+  it('延迟执行函数', () => {
+    const fn = vi.fn();
+    const debounced = createFilterWrapper(debounceFilter(100), fn);
+
+    debounced();
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('多次调用只执行最后一次', () => {
+    const fn = vi.fn();
+    const debounced = createFilterWrapper(debounceFilter(100), fn);
+
+    debounced();
+    debounced();
+    debounced();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('ms <= 0 时立即执行', () => {
+    const fn = vi.fn();
+    const debounced = createFilterWrapper(debounceFilter(0), fn);
+
+    debounced();
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('maxWait 限制最大等待时间', () => {
+    const fn = vi.fn();
+    const debounced = createFilterWrapper(debounceFilter(100, { maxWait: 150 }), fn);
+
+    debounced();
+    vi.advanceTimersByTime(80);
+    debounced(); // 重置 debounce timer
+    vi.advanceTimersByTime(80); // 总共 160ms，超过 maxWait
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('maxWait <= 0 时立即执行', () => {
+    const fn = vi.fn();
+    const debounced = createFilterWrapper(debounceFilter(100, { maxWait: 0 }), fn);
+
+    debounced();
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('保留参数传递', () => {
+    const fn = vi.fn();
+    const debounced = createFilterWrapper(debounceFilter(50), fn);
+
+    debounced('a', 'b');
+    vi.advanceTimersByTime(50);
+    expect(fn).toHaveBeenCalledWith('a', 'b');
+  });
+});
+
+describe('throttleFilter', () => {
+  it('首次立即执行（leading=true 默认）', () => {
+    const fn = vi.fn();
+    const throttled = createFilterWrapper(throttleFilter(100), fn);
+
+    throttled();
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('间隔内不重复执行', () => {
+    const fn = vi.fn();
+    const throttled = createFilterWrapper(throttleFilter(100), fn);
+
+    throttled();
+    throttled();
+    throttled();
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('trailing=true 时间隔结束后执行尾部调用', () => {
+    const fn = vi.fn();
+    const throttled = createFilterWrapper(throttleFilter(100, true, true), fn);
+
+    throttled(); // leading 执行
+    throttled(); // 排队 trailing
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('trailing=false 不执行尾部调用', () => {
+    const fn = vi.fn();
+    const throttled = createFilterWrapper(throttleFilter(100, false, true), fn);
+
+    throttled(); // leading 执行
+    throttled(); // 不排队
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('leading=false 首次不执行', () => {
+    const fn = vi.fn();
+    const throttled = createFilterWrapper(throttleFilter(100, true, false), fn);
+
+    throttled();
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('ms <= 0 时立即执行', () => {
+    const fn = vi.fn();
+    const throttled = createFilterWrapper(throttleFilter(0), fn);
+
+    throttled();
+    throttled();
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+});

package/compositions/virtualList/__tests__/useHeightCache.test.ts

@@ -0,0 +1,97 @@
+/**
+ * @description createHeightCache 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import { createHeightCache } from '../useHeightCache';
+
+describe('createHeightCache', () => {
+  it('初始化后 getHeight 返回预估高度', () => {
+    const cache = createHeightCache(10, 40);
+    expect(cache.getHeight(0)).toBe(40);
+    expect(cache.getHeight(5)).toBe(40);
+    expect(cache.getHeight(9)).toBe(40);
+  });
+
+  it('update 后 getHeight 返回实际高度', () => {
+    const cache = createHeightCache(10, 40);
+    cache.update(3, 60);
+    expect(cache.getHeight(3)).toBe(60);
+    // 其他未更新的仍为预估值
+    expect(cache.getHeight(4)).toBe(40);
+  });
+
+  it('update 越界不报错', () => {
+    const cache = createHeightCache(5, 40);
+    cache.update(-1, 50); // 越界
+    cache.update(10, 50); // 越界
+    expect(cache.getHeight(0)).toBe(40); // 不受影响
+  });
+
+  it('getOffset 返回累计高度', () => {
+    const cache = createHeightCache(5, 40);
+    // 全部预估：0*40=0, 1*40=40, ...
+    expect(cache.getOffset(0)).toBe(0);
+    expect(cache.getOffset(1)).toBe(40);
+    expect(cache.getOffset(3)).toBe(120);
+
+    // 更新某项后
+    cache.update(1, 60);
+    expect(cache.getOffset(2)).toBe(40 + 60); // 100
+    expect(cache.getOffset(3)).toBe(40 + 60 + 40); // 140
+  });
+
+  it('getTotalHeight 返回所有项高度之和', () => {
+    const cache = createHeightCache(5, 40);
+    expect(cache.getTotalHeight()).toBe(200);
+
+    cache.update(0, 50);
+    expect(cache.getTotalHeight()).toBe(210);
+  });
+
+  it('findIndex 二分查找定位正确', () => {
+    const cache = createHeightCache(100, 40);
+
+    // scrollTop=0 → index 0
+    expect(cache.findIndex(0)).toBe(0);
+
+    // scrollTop=40 → index 1
+    expect(cache.findIndex(40)).toBe(1);
+
+    // scrollTop=39 → 仍在 index 0 区间内
+    expect(cache.findIndex(39)).toBe(0);
+
+    // scrollTop=80 → index 2
+    expect(cache.findIndex(80)).toBe(2);
+
+    // scrollTop 超过总高度 → 最后一项
+    expect(cache.findIndex(99999)).toBe(99);
+  });
+
+  it('findIndex 在实际高度不等时也能正确定位', () => {
+    const cache = createHeightCache(5, 40);
+    cache.update(0, 100); // [100, 40, 40, 40, 40]
+
+    // scrollTop=50 → 还在 index 0（0-100）
+    expect(cache.findIndex(50)).toBe(0);
+
+    // scrollTop=100 → index 1（100-140）
+    expect(cache.findIndex(100)).toBe(1);
+
+    // scrollTop=140 → index 2（140-180）
+    expect(cache.findIndex(140)).toBe(2);
+  });
+
+  it('reset 重置缓存', () => {
+    const cache = createHeightCache(5, 40);
+    cache.update(0, 100);
+
+    cache.reset(3);
+    expect(cache.getHeight(0)).toBe(40); // 重置为预估值
+    expect(cache.getTotalHeight()).toBe(120); // 3 * 40
+  });
+});