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

package/compositions/toast/useToast.ts

@@ -0,0 +1,176 @@
+/**
+ * @description toast 队列 composable — Promise-based 通知系统
+ * @author 阿怪
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { ref } from 'vue';
+
+/**
+ * Toast 类型
+ */
+export type ToastType = 'success' | 'error' | 'warning' | 'info' | 'loading';
+
+/**
+ * Toast 队列中每一条 toast 的内部结构
+ */
+export interface ToastItem {
+  id: number;
+  type: ToastType;
+  title: string;
+  message?: string;
+  duration: number;
+  createdAt: number;
+}
+
+/**
+ * 创建 toast 时的配置参数
+ */
+export interface ToastShowOptions {
+  type?: ToastType;
+  title: string;
+  message?: string;
+  duration?: number;
+}
+
+/**
+ * promise() 方法的三阶段配置
+ */
+export interface ToastPromiseOptions<T> {
+  loading: string | { title: string; message?: string };
+  success: string | { title: string; message?: string } | ((data: T) => string | { title: string; message?: string });
+  error: string | { title: string; message?: string } | ((err: unknown) => string | { title: string; message?: string });
+}
+
+/** 各类型默认自动关闭时间（毫秒） */
+const DEFAULT_DURATIONS: Record<ToastType, number> = {
+  success: 3000,
+  error: 5000,
+  warning: 4000,
+  info: 3000,
+  loading: 0, // loading never auto-dismiss
+};
+
+/** 最大可见 toast 数量 */
+const MAX_VISIBLE = 3;
+
+let nextId = 0;
+
+/**
+ * Toast 队列 composable
+ * 管理 toast 的增删、自动关闭定时器与 Promise 模式
+ */
+export function useToast() {
+  const toasts = ref<ToastItem[]>([]);
+  const timers = new Map<number, ReturnType<typeof setTimeout>>();
+
+  /**
+   * 展示一条 toast，返回 id
+   */
+  const show = (options: ToastShowOptions): number => {
+    const id = nextId++;
+    const type = options.type ?? 'info';
+    const duration = options.duration ?? DEFAULT_DURATIONS[type];
+
+    const item: ToastItem = {
+      id,
+      type,
+      title: options.title,
+      message: options.message,
+      duration,
+      createdAt: Date.now(),
+    };
+
+    toasts.value.push(item);
+
+    // enforce max visible — remove oldest (non-loading) if exceeding limit
+    while (toasts.value.length > MAX_VISIBLE) {
+      const oldest = toasts.value.find(t => t.type !== 'loading');
+      if (oldest) {
+        dismiss(oldest.id);
+      } else {
+        // all are loading, remove the very first
+        dismiss(toasts.value[0].id);
+      }
+    }
+
+    if (duration > 0) {
+      const timer = setTimeout(() => dismiss(id), duration);
+      timers.set(id, timer);
+    }
+
+    return id;
+  };
+
+  /**
+   * 按 id 移除一条 toast
+   */
+  const dismiss = (id: number): void => {
+    const idx = toasts.value.findIndex(t => t.id === id);
+    if (idx !== -1) {
+      toasts.value.splice(idx, 1);
+    }
+    const timer = timers.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      timers.delete(id);
+    }
+  };
+
+  /**
+   * 将 stage 配置标准化为 { title, message }
+   */
+  function normalizeStage(stage: string | { title: string; message?: string }): { title: string; message?: string } {
+    if (typeof stage === 'string') {
+      return { title: stage };
+    }
+    return stage;
+  }
+
+  /**
+   * Promise toast pattern:
+   *   - 立即展示 loading toast
+   *   - resolve → 替换为 success toast
+   *   - reject → 替换为 error toast
+   */
+  const promise = <T>(
+    p: Promise<T>,
+    options: ToastPromiseOptions<T>,
+  ): Promise<T> => {
+    const loadingStage = normalizeStage(options.loading);
+    const loadingId = show({
+      type: 'loading',
+      title: loadingStage.title,
+      message: loadingStage.message,
+    });
+
+    return p.then(
+      (data) => {
+        dismiss(loadingId);
+        const raw = typeof options.success === 'function' ? options.success(data) : options.success;
+        const successStage = normalizeStage(raw);
+        show({
+          type: 'success',
+          title: successStage.title,
+          message: successStage.message,
+        });
+        return data;
+      },
+      (err: unknown) => {
+        dismiss(loadingId);
+        const raw = typeof options.error === 'function' ? options.error(err) : options.error;
+        const errorStage = normalizeStage(raw);
+        show({
+          type: 'error',
+          title: errorStage.title,
+          message: errorStage.message,
+        });
+        throw err;
+      },
+    );
+  };
+
+  return { toasts, show, dismiss, promise };
+}

package/compositions/tooltip/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @description tooltip compositions barrel export
+ * @author 阿怪
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { useTooltip, type TooltipPlacement, type TooltipPositionData } from './useTooltip';

package/compositions/tooltip/useTooltip.ts

@@ -0,0 +1,10 @@
+/**
+ * @description tooltip composable re-export from component layer
+ * @author 阿怪
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { useTooltip } from '../../components/base/tooltip/useTooltip';
+export type { TooltipPlacement, TooltipPositionData } from '../../components/base/tooltip/useTooltip';

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

package/compositions/virtualList/enums.ts

@@ -0,0 +1,52 @@
+/**
+ * @description 虚拟列表 action 枚举
+ * @author 阿怪
+ * @date 2026/2/25 13:30
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+/** 元素可见性变化的动作类型 */
+export enum ACTION {
+  /** 从顶部进入可视区域（开始露出） */
+  ENTER_TOP_START,
+  /** 从顶部完全进入可视区域 */
+  ENTER_TOP_END,
+  /** 从底部进入可视区域（开始露出） */
+  ENTER_BOTTOM_START,
+  /** 从底部完全进入可视区域 */
+  ENTER_BOTTOM_END,
+  /** 从顶部开始离开可视区域 */
+  LEAVE_TOP_START,
+  /** 从顶部完全离开可视区域 */
+  LEAVE_TOP_END,
+  /** 从底部开始离开可视区域 */
+  LEAVE_BOTTOM_START,
+  /** 从底部完全离开可视区域 */
+  LEAVE_BOTTOM_END,
+  /** 未知状态 */
+  UNKNOWN,
+}
+
+/** 元素相对于容器的位置类型 */
+export enum POSITION_TYPE {
+  /** 完全在可视区域上方 */
+  TOP,
+  /** 部分在可视区域上方（上半部分露出） */
+  TOP_VISIBLE,
+  /** 完全在可视区域内 */
+  VISIBLE,
+  /** 部分在可视区域下方（下半部分露出） */
+  BOTTOM_VISIBLE,
+  /** 完全在可视区域下方 */
+  BOTTOM,
+}
+
+/** 元素信息记录 */
+export type EntryInfo = {
+  ratio: number;
+  position: POSITION_TYPE;
+  realIndex: number;
+  translateY: number;
+};

package/compositions/virtualList/useContainerObserver.ts

@@ -0,0 +1,89 @@
+/**
+ * @description 容器 IntersectionObserver 管理
+ * @author 阿怪
+ * @date 2026/2/25 13:30
+ * @version v2.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 管理 IntersectionObserver 的创建、observe/unobserve，配合 ResizeObserver 处理容器尺寸变化
+ */
+import { onBeforeUnmount, Ref } from 'vue';
+import { useResizeObserver } from '../common/useResizeObserver';
+
+export default function useContainerObserver(options: {
+  containerRef: Ref<HTMLElement | null>;
+  threshold?: number | number[];
+  getTarget: () => ArrayLike<Element>;
+  callback: (entries: IntersectionObserverEntry[], observer: IntersectionObserver) => void;
+}) {
+  let ob: IntersectionObserver | undefined;
+  const observeList: Element[] = [];
+
+  // 队列：在 observer 创建前缓存操作
+  const eventQueue: Array<{ target: ArrayLike<Element> | Element; type: 'observe' | 'unobserve' }> = [];
+
+  const processTarget = (target: ArrayLike<Element> | Element, type: 'observe' | 'unobserve') => {
+    if (!ob) {
+      eventQueue.push({ target, type });
+      return;
+    }
+    if ('length' in target) {
+      for (let i = 0; i < target.length; i++) {
+        if (target[i]) {
+          ob[type](target[i]);
+        }
+      }
+    } else {
+      ob[type](target);
+    }
+  };
+
+  const clearQueue = () => {
+    while (eventQueue.length) {
+      const { target, type } = eventQueue.shift()!;
+      processTarget(target, type);
+    }
+  };
+
+  const reObserve = (target: ArrayLike<Element>) => {
+    // 先 unobserve 所有已观察的
+    processTarget(observeList, 'unobserve');
+    observeList.length = 0;
+    // 再 observe 新的
+    for (let i = 0; i < target.length; i++) {
+      observeList.push(target[i]);
+    }
+    processTarget(target, 'observe');
+  };
+
+  const initOb = () => {
+    if (ob) {
+      ob.disconnect();
+    }
+    ob = new IntersectionObserver(options.callback, {
+      root: options.containerRef.value,
+      threshold: options.threshold ?? [0, 1],
+    });
+    clearQueue();
+  };
+
+  useResizeObserver(options.containerRef, () => {
+    if (options.containerRef.value) {
+      if (!ob) {
+        initOb();
+      }
+      const target = options.getTarget();
+      reObserve(target);
+    }
+  });
+
+  onBeforeUnmount(() => {
+    if (ob) {
+      ob.disconnect();
+      ob = undefined;
+    }
+  });
+
+  return { reObserve };
+}