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

package/components/template/virtualList/useVirtualList.ts

@@ -0,0 +1,237 @@
+/**
+ * @description 虚拟列表核心 hook（sentinel 方案）
+ * @author 阿怪
+ * @date 2026/2/25 14:00
+ * @version v3.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 基于 sentinel 哨兵元素 + scrollTop 绝对定位
+ * 不依赖状态机连续性，快速滚动也能正确定位
+ */
+import { computed, nextTick, onMounted, ref, watch, toRef, onBeforeUnmount } from 'vue';
+import { VirtualListProps } from './props';
+import { createHeightCache } from '../../../compositions/virtualList/useHeightCache';
+import { useSentinelObserver } from '../../../compositions/virtualList/useSentinelObserver';
+
+export interface UseVirtualListOptions<T> {
+  props: VirtualListProps<T>;
+  /** 触底事件 */
+  onReachBottom?: () => void;
+}
+
+export function useVirtualList<T>(options: UseVirtualListOptions<T>) {
+  const { props, onReachBottom } = options;
+
+  const containerRef = ref<HTMLElement | null>(null);
+  const wrapperRef = ref<HTMLElement | null>(null);
+  const topSentinelRef = ref<HTMLElement | null>(null);
+  const bottomSentinelRef = ref<HTMLElement | null>(null);
+
+  const listRef = toRef(() => props.list ?? []);
+  const estimatedHeight = props.estimatedHeight ?? 40;
+  const overScan = props.overScan ?? 1;
+
+  // 高度缓存
+  const heightCache = createHeightCache(listRef.value.length, estimatedHeight);
+
+  // 当前渲染范围
+  const renderFrom = ref(0);
+  const renderEnd = ref(0);
+
+  // spacer 总高度
+  const totalHeight = ref(0);
+  // wrapper 偏移
+  const offsetY = ref(0);
+
+  /** 根据 scrollTop 计算渲染范围 */
+  const calcRange = () => {
+    const container = containerRef.value;
+    if (!container) return;
+
+    const list = listRef.value;
+    const total = list.length;
+    if (total === 0) {
+      renderFrom.value = 0;
+      renderEnd.value = 0;
+      totalHeight.value = 0;
+      offsetY.value = 0;
+      return;
+    }
+
+    const scrollTop = container.scrollTop;
+    const containerHeight = container.clientHeight;
+
+    // 用 scrollTop 直接定位起始索引
+    const startIndex = heightCache.findIndex(scrollTop);
+    // 计算可见数量
+    let visibleEnd = startIndex;
+    let accHeight = 0;
+    while (visibleEnd < total && accHeight < containerHeight) {
+      accHeight += heightCache.getHeight(visibleEnd);
+      visibleEnd++;
+    }
+
+    const visibleCount = visibleEnd - startIndex;
+    const overScanCount = Math.max(1, Math.floor(visibleCount * overScan));
+
+    // 加上 overScan 缓冲区
+    const from = Math.max(0, startIndex - overScanCount);
+    const end = Math.min(total, visibleEnd + overScanCount);
+
+    renderFrom.value = from;
+    renderEnd.value = end;
+    totalHeight.value = heightCache.getTotalHeight();
+    offsetY.value = heightCache.getOffset(from);
+  };
+
+  /** 当前要渲染的数据切片 */
+  const displayList = computed(() => {
+    const list = listRef.value;
+    return list.slice(renderFrom.value, renderEnd.value)
+      .map((d, i) => ({ data: d as T, index: i + renderFrom.value }));
+  });
+
+  /**
+   * 测量已渲染项的实际高度并更新缓存
+   * 同时进行 scrollTop 补偿：当上方元素的真实高度和预估不同时，
+   * 修正 scrollTop 使视觉位置不跳动
+   */
+  const measureItems = () => {
+    const wrapper = wrapperRef.value;
+    const container = containerRef.value;
+    if (!wrapper || !container) return;
+
+    const scrollTop = container.scrollTop;
+    // 记录当前视口第一个可见项的旧偏移
+    const firstVisibleIndex = heightCache.findIndex(scrollTop);
+    const oldOffset = heightCache.getOffset(firstVisibleIndex);
+
+    const children = wrapper.children;
+    let hasChange = false;
+    // 跳过 top sentinel（第一个子元素）
+    for (let i = 1; i < children.length - 1; i++) {
+      const child = children[i];
+      const index = renderFrom.value + (i - 1); // -1 因为跳过 top sentinel
+      const height = child.getBoundingClientRect().height;
+      if (height > 0) {
+        const oldHeight = heightCache.getHeight(index);
+        if (Math.abs(oldHeight - height) > 0.5) {
+          heightCache.update(index, height);
+          hasChange = true;
+        }
+      }
+    }
+
+    if (hasChange) {
+      // 计算补偿量：上方高度变化导致的偏移差
+      const newOffset = heightCache.getOffset(firstVisibleIndex);
+      const delta = newOffset - oldOffset;
+      if (Math.abs(delta) > 0.5) {
+        container.scrollTop = scrollTop + delta;
+      }
+    }
+
+    // 更新总高度
+    totalHeight.value = heightCache.getTotalHeight();
+  };
+
+  const update = () => {
+    measureItems();
+    calcRange();
+    // 范围变化后，下一帧再测量一次（新渲染的元素）
+    nextTick(() => {
+      measureItems();
+    });
+  };
+
+  // sentinel observer
+  const { reobserve } = useSentinelObserver({
+    containerRef,
+    topSentinelRef,
+    bottomSentinelRef,
+    onUpdate: update,
+    onReachBottom,
+  });
+
+  // scroll 事件驱动：用 rAF 节流，保证滚动过程中持续更新渲染范围
+  let rafId: number | null = null;
+  let scrollHandler: (() => void) | undefined;
+  let scrollendHandler: (() => void) | undefined;
+
+  const setupScrollListener = () => {
+    const container = containerRef.value;
+    if (!container) return;
+
+    // 连续滚动时用 rAF 节流更新
+    scrollHandler = () => {
+      if (rafId !== null) return;
+      rafId = requestAnimationFrame(() => {
+        rafId = null;
+        calcRange();
+      });
+    };
+    container.addEventListener('scroll', scrollHandler, { passive: true });
+
+    // scrollend 做最终修正（测量 + 补偿）
+    scrollendHandler = () => {
+      measureItems();
+      calcRange();
+    };
+    container.addEventListener('scrollend', scrollendHandler);
+  };
+
+  const cleanupScrollListener = () => {
+    const container = containerRef.value;
+    if (container) {
+      if (scrollHandler) container.removeEventListener('scroll', scrollHandler);
+      if (scrollendHandler) container.removeEventListener('scrollend', scrollendHandler);
+    }
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+  };
+
+  // 初始化
+  onMounted(() => {
+    const list = listRef.value;
+    heightCache.reset(list.length);
+
+    // 初始渲染
+    calcRange();
+
+    nextTick(() => {
+      measureItems();
+      calcRange();
+      reobserve();
+      setupScrollListener();
+    });
+  });
+
+  // 响应 list 变化
+  watch(listRef, (newList) => {
+    heightCache.reset(newList.length);
+    if (containerRef.value) {
+      containerRef.value.scrollTop = 0;
+    }
+    calcRange();
+    nextTick(() => {
+      measureItems();
+      calcRange();
+      reobserve();
+    });
+  });
+
+  onBeforeUnmount(cleanupScrollListener);
+
+  return {
+    displayList,
+    containerRef,
+    wrapperRef,
+    topSentinelRef,
+    bottomSentinelRef,
+    totalHeight,
+    offsetY,
+  };
+}

package/components/types/hook.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @description
+ * @author 阿怪
+ * @date 2024/12/16 10:15
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { SlotsType } from '@vue/runtime-core';
+
+export type UseHookResult<Props, S extends SlotsType, Return> = Return;
+
+/**
+ * Core hook 所需的最小 context 类型。
+ * 使用 `(...args: any[]) => void` 而非 `(event: string, ...) => void`，
+ * 以兼容 Vue defineComponent typed emits 产生的窄化 emit 签名。
+ */
+export type HookContext = {
+  emit: (...args: any[]) => void;
+  slots: Readonly<Record<string, ((...args: any[]) => any) | undefined>>;
+  expose?: (exposed?: Record<string, any>) => void;
+};
+
+

package/components/types/props.d.ts

@@ -0,0 +1,57 @@
+/* eslint-disable */
+/**
+ * @description M Component Object Props Options
+ * @author 阿怪
+ * @date 2022/12/13 00:01
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ * M means Shuimo
+ */
+export declare type MPropOptions<T = any, D = T> = {
+  type?: MPropType<T> | true | null,
+  required: true,
+  default?: D | DefaultFactory<D> | null | undefined | object,
+  enum?: T[],
+}
+
+export declare type MPropOptionsWithDefault<T = any, D = T> = {
+  type?: MPropType<T> | true | null,
+  required?: false,
+  default: D | DefaultFactory<D> | null | undefined | object,
+  enum?: T[],
+}
+
+/**
+ * @description MComponentObjectPropsOptions
+ */
+export type MCOPO<P, OK = Required<Pick<P, OptionalKeys<P>>>> = {
+  [K in keyof OK]: MPropOptionsWithDefault<OK[K]>
+} & {
+  [K in keyof Pick<P, RequiredKeys<P>>]-?: MPropOptions<P[K]>
+}
+
+
+type DefaultFactory<T> = (props: Data) => T;
+
+type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T];
+
+type OptionalKeys<T> = Exclude<keyof T, RequiredKeys<T>>;
+
+type MPropConstructor<T = any> =
+  | { new(...args: any[]): T & {} }
+  | { (): T }
+  | MPropMethod<T>
+
+type MPropMethod<T, TConstructor = any> = [T] extends [
+      ((...args: any) => any) | undefined
+  ] // if is function with args, allowing non-required functions
+  ? { new(): TConstructor; (): T; readonly prototype: TConstructor } // Create Function like constructor
+  : never
+
+export type MPropType<T> = MPropConstructor<T> | MPropConstructor<T>[];
+
+/**
+ * @description unified component size variants
+ */
+export type KineSize = 'large' | 'medium' | 'small';

package/components/types/template.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @description
+ * @author 阿怪
+ * @date 2022/12/12 14:52
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { RenderFunction, SetupContext } from 'vue';
+import { MCOPO } from './props';
+
+type WithArray<T> = T | T[]; // todo fix this
+
+export type HTMLElementEvent<T extends HTMLElement> = Event & {
+  target: T;
+};
+
+type MVNodeRenderParams = {
+  if?: boolean,
+  show?: boolean,
+};
+
+interface ElementEventListener {
+  (event: HTMLElementEvent<any>): void;
+}
+
+export type MNodeProps = Record<string, WithArray<string | number | boolean> | ElementEventListener | Record<string, any>>;
+
+export declare type MNodeSlot = MVNodeRenderParams & {
+  props?: MNodeProps,
+};
+
+export declare type MNodeTemplate = {
+  type: string,
+  props?: MNodeProps,
+  children?: Record<string, MNodeTemplate>,
+  slots?: Map<string, MNodeSlot>,
+  innerText?: string[],
+  initProps?: (templateProps: MCOPO<any>, props: MNodeProps, filter?: string[]) => void,
+} & MVNodeRenderParams;
+
+
+export declare type MVNode = {
+  name: string,
+  template?: MNodeTemplate,
+  dom?: HTMLElement,
+  props?: MNodeTemplate['props'],
+  children?: Record<string, MVNode>,
+  slots?: MNodeTemplate['slots']
+};
+
+export declare type CustomElementParams = {
+  name: string,
+  style?: string,
+  template?: MNodeTemplate,
+  props?: MCOPO<any>
+};
+
+export declare type WCSetup<T = any> = (slot?: HTMLSlotElement) => (props: Readonly<T>, ctx: SetupContext) => RenderFunction;

package/compositions/commandPalette/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @description commandPalette composition barrel export
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { useCommandPalette } from './useCommandPalette';
+export type { UseCommandPaletteReturn } from './useCommandPalette';
+export type { Command } from './types';

package/compositions/commandPalette/types.ts

@@ -0,0 +1,29 @@
+/**
+ * @description CommandPalette command type definitions
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import type { VNode } from 'vue';
+
+/**
+ * A single command registered in the palette.
+ */
+export interface Command {
+  /** Unique identifier */
+  id: string;
+  /** Display label (also used for search) */
+  label: string;
+  /** Optional icon render function */
+  icon?: () => VNode;
+  /** Additional search terms beyond the label */
+  keywords?: string[];
+  /** Grouping category (e.g. "Navigation", "Actions") */
+  group?: string;
+  /** Shortcut hint text displayed on the right side of the item */
+  shortcut?: string;
+  /** Callback executed when the command is selected */
+  action: () => void;
+}

package/compositions/commandPalette/useCommandPalette.ts

@@ -0,0 +1,135 @@
+/**
+ * @description CommandPalette composable — global search + command execution
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * Manages open/close state, command registration, query filtering, and execution.
+ * Does NOT participate in overlayStack — fixed z-index 9500.
+ */
+import { ref, computed, type Ref, type ComputedRef } from 'vue';
+import type { Command } from './types';
+
+export interface UseCommandPaletteReturn {
+  /** Whether the palette is open */
+  isOpen: Ref<boolean>;
+  /** Current search query */
+  query: Ref<string>;
+  /** Index of the currently highlighted item */
+  activeIndex: Ref<number>;
+  /** All registered commands */
+  commands: Ref<Command[]>;
+  /** Filtered commands based on query */
+  filtered: ComputedRef<Command[]>;
+  /** Open the palette */
+  open: () => void;
+  /** Close the palette */
+  close: () => void;
+  /** Toggle open/close */
+  toggle: () => void;
+  /** Register a command */
+  registerCommand: (cmd: Command) => void;
+  /** Unregister a command by id */
+  unregisterCommand: (id: string) => void;
+  /** Execute the command at a given index in the filtered list, then close */
+  execute: (index: number) => void;
+}
+
+/**
+ * CommandPalette composable
+ *
+ * Provides reactive state for opening, searching, and executing commands.
+ */
+export function useCommandPalette(): UseCommandPaletteReturn {
+  const isOpen = ref(false);
+  const query = ref('');
+  const activeIndex = ref(0);
+  const commands = ref<Command[]>([]);
+
+  /** element that had focus before the palette opened */
+  let previousActiveElement: Element | null = null;
+
+  const open = () => {
+    previousActiveElement = document.activeElement;
+    isOpen.value = true;
+    query.value = '';
+    activeIndex.value = 0;
+  };
+
+  const close = () => {
+    isOpen.value = false;
+    query.value = '';
+    activeIndex.value = 0;
+    // restore focus to the previously focused element
+    if (previousActiveElement && previousActiveElement instanceof HTMLElement) {
+      previousActiveElement.focus();
+    }
+    previousActiveElement = null;
+  };
+
+  const toggle = () => {
+    if (isOpen.value) {
+      close();
+    } else {
+      open();
+    }
+  };
+
+  const registerCommand = (cmd: Command) => {
+    // prevent duplicates
+    const exists = commands.value.some(c => c.id === cmd.id);
+    if (!exists) {
+      commands.value.push(cmd);
+    }
+  };
+
+  const unregisterCommand = (id: string) => {
+    const idx = commands.value.findIndex(c => c.id === id);
+    if (idx !== -1) {
+      commands.value.splice(idx, 1);
+    }
+  };
+
+  /**
+   * Simple case-insensitive substring match on label + keywords.
+   */
+  const filtered = computed<Command[]>(() => {
+    const q = query.value.trim().toLowerCase();
+    if (!q) {
+      return commands.value;
+    }
+    return commands.value.filter(cmd => {
+      if (cmd.label.toLowerCase().includes(q)) {
+        return true;
+      }
+      if (cmd.keywords) {
+        return cmd.keywords.some(kw => kw.toLowerCase().includes(q));
+      }
+      return false;
+    });
+  });
+
+  const execute = (index: number) => {
+    const cmd = filtered.value[index];
+    if (cmd) {
+      close();
+      cmd.action();
+    }
+  };
+
+  return {
+    isOpen,
+    query,
+    activeIndex,
+    commands,
+    filtered,
+    open,
+    close,
+    toggle,
+    registerCommand,
+    unregisterCommand,
+    execute,
+  };
+}

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