@kine-design/core 0.0.1-beta.1 → 0.0.1-beta.11

package/compositions/input/useBooleanInput.ts

@@ -0,0 +1,52 @@
+/**
+ * @description boolean input like checkbox/radio... hooks
+ * @author 阿怪
+ * @date 2023/4/23 15:22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { isBoolean, notEmpty } from '../../tools';
+
+export const initChecked = (props: {
+  checked: boolean | null | undefined,
+  modelValue: any,
+  value: any
+}) => {
+  if (props.checked) {
+    return props.checked;
+  }
+
+  if (notEmpty(props.modelValue)) {
+    if (notEmpty(props.value)) {
+      if (Array.isArray(props.modelValue)) {
+        return props.modelValue.includes(props.value);
+      }
+      return props.value === props.modelValue;
+    }
+
+    if (isBoolean(props.modelValue)) {
+      return props.modelValue;
+    }
+  }
+
+  return false;
+};
+
+
+export const getNewModelValue = (props: { value: any, modelValue?: any }, checked: boolean) => {
+  if (props.value) {
+    if (Array.isArray(props.modelValue)) {
+      const arr = [...props.modelValue];
+      if (checked) {
+        if (!arr.includes(props.value)) arr.push(props.value);
+      } else {
+        const idx = arr.indexOf(props.value);
+        if (idx !== -1) arr.splice(idx, 1);
+      }
+      return arr;
+    }
+    return checked ? props.value : undefined;
+  }
+  return checked;
+};

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

@@ -0,0 +1,110 @@
+/**
+ * @description useModal 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { nextTick, reactive } from 'vue';
+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();
+  });
+
+  it('外部 props.visible 变化时 watcher 同步内部 visible', async () => {
+    const emit = vi.fn();
+    const props = reactive({ visible: false });
+    const { visible } = useModal(props, emit);
+
+    expect(visible.value).toBe(false);
+
+    // 外部修改 props.visible → watcher 同步 visible.value
+    props.visible = true;
+    await nextTick();
+    expect(visible.value).toBe(true);
+
+    props.visible = false;
+    await nextTick();
+    expect(visible.value).toBe(false);
+  });
+});

package/compositions/modal/useModal.ts

@@ -0,0 +1,72 @@
+/**
+ * @description 模态框公共 composable（dialog / drawer / confirm 共用）
+ * @author 阿怪
+ * @date 2026/2/25 16:00
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 处理 visible 状态、遮罩层点击关闭、emit 同步
+ */
+import { ref, watch } from 'vue';
+import { type HookContext } from '../../components/types/hook';
+import { ModelMask } from '../../types/common/model';
+
+export interface UseModalProps {
+  visible?: boolean;
+  mask?: ModelMask;
+}
+
+export function useModal(props: UseModalProps, emit: HookContext['emit']) {
+  const visible = ref(props.visible ?? false);
+
+  watch(() => props.visible, (val) => {
+    visible.value = val ?? false;
+  });
+
+  /** 打开 */
+  const open = () => {
+    visible.value = true;
+    emit('update:visible', true);
+  };
+
+  /** 关闭 */
+  const close = () => {
+    visible.value = false;
+    emit('update:visible', false);
+  };
+
+  /** 切换 */
+  const toggle = () => {
+    if (visible.value) { close(); } else { open(); }
+  };
+
+  /** 遮罩层点击 */
+  const onMaskClick = () => {
+    const mask = props.mask;
+    const clickClose = mask?.clickClose ?? true;
+    if (clickClose) {
+      close();
+    }
+  };
+
+  /** 是否显示遮罩 */
+  const showMask = () => {
+    return props.mask?.show ?? true;
+  };
+
+  /** 阻止内容区域点击冒泡到遮罩 */
+  const onContentClick = (e: MouseEvent) => {
+    e.stopPropagation();
+  };
+
+  return {
+    visible,
+    open,
+    close,
+    toggle,
+    onMaskClick,
+    showMask,
+    onContentClick,
+  };
+}

package/compositions/popper/useClickAway.ts

@@ -0,0 +1,41 @@
+/**
+ * @description click away hook
+ * @author 阿怪
+ * @date 2023/5/12 01:02
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import useEventListener from '../common/useEventListener';
+
+
+const event = 'pointerdown';
+export default function useClickAway(options: {
+  target: EventTarget | (() => EventTarget | null | undefined),
+  handler: (event: PointerEvent) => void
+}) {
+  if (typeof window === 'undefined' || !window) {
+    return;
+  }
+
+  const listener = (event: Event) => {
+    const el = typeof options.target === 'function' ? options.target() : options.target;
+    if (!el) {
+      return;
+    }
+
+    if (el === event.target || event.composedPath().includes(el)) {
+      return;
+    }
+
+    options.handler(event as PointerEvent);
+  };
+
+  return useEventListener({
+    target: window,
+    event,
+    handler: listener,
+  });
+
+
+}

package/compositions/popper/usePopper.ts

@@ -0,0 +1,63 @@
+/**
+ * @description popper hook
+ * @author 阿怪
+ * @date 2023/1/29 10:21
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { arrow, autoUpdate, computePosition, ComputePositionConfig } from '@floating-ui/dom';
+
+export type Placement =
+  | 'top' | 'top-start' | 'top-end'
+  | 'right' | 'right-start' | 'right-end'
+  | 'bottom' | 'bottom-start' | 'bottom-end'
+  | 'left' | 'left-start' | 'left-end';
+export type PopperConfig = Partial<ComputePositionConfig>;
+
+type DomStyle = { left: string; top: string; display: string; position: string };
+export type PositionStyle = { style: DomStyle; arrowStyle: DomStyle, placement: Placement };
+
+export const usePopper = (
+  triggerNode: HTMLElement,
+  popperNode: HTMLElement,
+  update: (data: PositionStyle) => void,
+  arrowNode?: HTMLElement,
+  config?: PopperConfig,
+) => {
+
+  const getPositionStyle = async () => {
+    if (arrowNode && config?.middleware) {
+      config.middleware.push(arrow({ element: arrowNode }));
+    }
+
+
+    const { x, y, placement, middlewareData } = await computePosition(triggerNode, popperNode, config);
+    const res: PositionStyle = {
+      style: {
+        left: `${x}px`,
+        top: `${y}px`,
+        display: 'block',
+        position: 'absolute',
+      },
+      arrowStyle: {
+        left: `${middlewareData.arrow?.x ?? 0}px`,
+        top: `${middlewareData.arrow?.y ?? 0}px`,
+        display: 'block',
+        position: 'absolute',
+      },
+      placement,
+    };
+    update(res);
+
+    return res;
+  };
+
+  const clear = autoUpdate(triggerNode, popperNode, getPositionStyle);
+
+
+  return {
+    getPositionStyle,
+    clear,
+  };
+};

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/utils/filters.ts

@@ -0,0 +1,135 @@
+/**
+ * @description event filter(防抖、节流)
+ * @author youus
+ * @date 2022/8/20 00:17
+ * @version v1.0.0
+ *
+ * Hello, humor
+ */
+
+
+export type FunctionArgs<Args extends any[] = any[], Return = void> = (...args: Args) => Return;
+
+export interface FunctionWrapperOptions<Args extends any[] = any[], This = any> {
+  fn: FunctionArgs<Args, This>,
+  args: Args,
+  thisArg: This
+}
+
+export type EventFilter<Args extends any[] = any[], This = any> = (
+  invoke: () => void,
+  options: FunctionWrapperOptions<Args, This>,
+) => void;
+
+export interface DebounceFilterOptions {
+  /**
+   * The maximum time allowed to be delayed before it's invoked.
+   * In milliseconds.
+   */
+  maxWait?: number;
+}
+
+/**
+ * @internal
+ */
+export function createFilterWrapper<T extends FunctionArgs>(filter: EventFilter, fn: T) {
+  function wrapper(this: any, ...args: any[]) {
+    filter(() => fn.apply(this, args), { fn, thisArg: this, args });
+  }
+
+  return wrapper as any as T;
+}
+
+/**
+ * Create an EventFilter that debounce the events
+ *
+ * @param ms
+ * @param options
+ */
+export function debounceFilter(ms: number, options: DebounceFilterOptions = {}) {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let maxTimer: ReturnType<typeof setTimeout> | undefined | null;
+
+  const filter: EventFilter = invoke => {
+    const duration = ms;
+    const maxDuration = options.maxWait;
+
+    if (timer) clearTimeout(timer);
+
+    if (duration <= 0 || (maxDuration !== undefined && maxDuration <= 0)) {
+      if (maxTimer) {
+        clearTimeout(maxTimer);
+        maxTimer = null;
+      }
+      return invoke();
+    }
+
+    // Create the maxTimer. Clears the regular timer on invoke
+    if (maxDuration && !maxTimer) {
+      maxTimer = setTimeout(() => {
+        if (timer) clearTimeout(timer);
+        maxTimer = null;
+        invoke();
+      }, maxDuration);
+    }
+
+    // Create the regular timer. Clears the max timer on invoke
+    timer = setTimeout(() => {
+      if (maxTimer) clearTimeout(maxTimer);
+      maxTimer = null;
+      invoke();
+    }, duration);
+  };
+
+  return filter;
+}
+
+/**
+ * Create an EventFilter that throttle the events
+ *
+ * @param ms
+ * @param [trailing=true]
+ * @param [leading=true]
+ */
+export function throttleFilter(ms: number, trailing = true, leading = true) {
+  let lastExec = 0;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let isLeading = true;
+
+  const clear = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  const filter: EventFilter = invoke => {
+    const duration = ms;
+    const elapsed = Date.now() - lastExec;
+
+    clear();
+
+    if (duration <= 0) {
+      lastExec = Date.now();
+      return invoke();
+    }
+
+    if (elapsed > duration && (leading || !isLeading)) {
+      lastExec = Date.now();
+      invoke();
+    } else if (trailing) {
+      timer = setTimeout(() => {
+        lastExec = Date.now();
+        isLeading = true;
+        clear();
+        invoke();
+      }, duration);
+    }
+
+    if (!leading && !timer) timer = setTimeout(() => (isLeading = true), duration);
+
+    isLeading = false;
+  };
+
+  return filter;
+}

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
+  });
+});