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

package/components/message/notification/__tests__/useNotification.test.ts

@@ -0,0 +1,129 @@
+/**
+ * @description useNotificationQueue 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { useNotificationQueue } from '../useNotification';
+
+beforeEach(() => { vi.useFakeTimers(); });
+afterEach(() => { vi.useRealTimers(); });
+
+describe('useNotificationQueue', () => {
+  it('初始通知列表为空', () => {
+    const { notifications } = useNotificationQueue();
+    expect(notifications.value).toHaveLength(0);
+  });
+
+  it('add 添加通知并返回 id', () => {
+    const { notifications, add } = useNotificationQueue();
+
+    const id = add({ title: '测试通知' });
+    expect(typeof id).toBe('number');
+    expect(notifications.value).toHaveLength(1);
+    expect(notifications.value[0].title).toBe('测试通知');
+  });
+
+  it('add 使用默认值', () => {
+    const { notifications, add } = useNotificationQueue();
+
+    add({ title: 'test' });
+    const item = notifications.value[0];
+
+    expect(item.message).toBe('');
+    expect(item.type).toBe('info');
+    expect(item.duration).toBe(4500);
+    expect(item.position).toBe('top-right');
+    expect(item.closable).toBe(true);
+  });
+
+  it('add 自定义所有字段', () => {
+    const { notifications, add } = useNotificationQueue();
+
+    add({
+      title: '错误',
+      message: '操作失败',
+      type: 'error',
+      duration: 3000,
+      position: 'bottom-left',
+      closable: false,
+    });
+
+    const item = notifications.value[0];
+    expect(item.type).toBe('error');
+    expect(item.message).toBe('操作失败');
+    expect(item.duration).toBe(3000);
+    expect(item.position).toBe('bottom-left');
+    expect(item.closable).toBe(false);
+  });
+
+  it('remove 按 id 移除通知', () => {
+    const { notifications, add, remove } = useNotificationQueue();
+
+    const id1 = add({ title: '通知1' });
+    const id2 = add({ title: '通知2' });
+
+    remove(id1);
+    expect(notifications.value).toHaveLength(1);
+    expect(notifications.value[0].id).toBe(id2);
+  });
+
+  it('remove 不存在的 id 不报错', () => {
+    const { notifications, add, remove } = useNotificationQueue();
+
+    add({ title: '通知' });
+    remove(999);
+    expect(notifications.value).toHaveLength(1);
+  });
+
+  it('duration > 0 时自动移除', () => {
+    const { notifications, add } = useNotificationQueue();
+
+    add({ title: '自动关闭', duration: 1000 });
+    expect(notifications.value).toHaveLength(1);
+
+    vi.advanceTimersByTime(1000);
+    expect(notifications.value).toHaveLength(0);
+  });
+
+  it('duration = 0 时不自动移除', () => {
+    const { notifications, add } = useNotificationQueue();
+
+    add({ title: '手动关闭', duration: 0 });
+
+    vi.advanceTimersByTime(10000);
+    expect(notifications.value).toHaveLength(1);
+  });
+
+  it('多条通知独立管理', () => {
+    const { notifications, add } = useNotificationQueue();
+
+    add({ title: '快速消失', duration: 1000 });
+    add({ title: '慢速消失', duration: 5000 });
+    add({ title: '不消失', duration: 0 });
+
+    expect(notifications.value).toHaveLength(3);
+
+    vi.advanceTimersByTime(1000);
+    expect(notifications.value).toHaveLength(2);
+
+    vi.advanceTimersByTime(4000);
+    expect(notifications.value).toHaveLength(1);
+    expect(notifications.value[0].title).toBe('不消失');
+  });
+
+  it('id 自增不重复', () => {
+    const { add } = useNotificationQueue();
+
+    const id1 = add({ title: '1' });
+    const id2 = add({ title: '2' });
+    const id3 = add({ title: '3' });
+
+    expect(id1).not.toBe(id2);
+    expect(id2).not.toBe(id3);
+    expect(id3 - id1).toBe(2);
+  });
+});

package/components/message/popover/usePopover.ts

@@ -162,7 +162,7 @@ export function usePopover(
     }
   };
 
-  const onBeforeDestroyEvents: Function[] = [];
+  const onBeforeUnmountEvents: Function[] = [];
 
   onMounted(() => {
     if (!popoverRef.value || !contentRef.value) {
@@ -188,8 +188,8 @@ export function usePopover(
 
   onBeforeUnmount(() => {
     if (clickAwayInstance) {
-      const { onBeforeDestroy } = clickAwayInstance;
-      onBeforeDestroy();
+      const { onBeforeUnmount } = clickAwayInstance;
+      onBeforeUnmount();
     }
     instance?.destroy();
   });
@@ -228,7 +228,7 @@ export function usePopover(
     popperInstance,
     style, arrowStyle,
     lifecycle: {
-      onBeforeDestroyEvents,
+      onBeforeUnmountEvents,
     },
   };
 }

package/components/other/darkMode/useDarkMode.ts

@@ -12,6 +12,7 @@
  *   - autoMode 时监听系统媒体查询变化，并在卸载时清理监听器
  */
 import { ref, watch, onMounted, onUnmounted } from 'vue';
+import { type HookContext } from '../../types/hook';
 import { DarkModeProps } from './props';
 
 /** 将暗色状态同步到 html[dark] attribute */
@@ -42,8 +43,7 @@ function writeStorage(storageKey: string, isDark: boolean) {
 
 export function useDarkMode(
   props: DarkModeProps,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ctx: { emit: (event: string, ...args: any[]) => void },
+  ctx: Pick<HookContext, 'emit'>,
 ) {
   const isDark = ref(props.modelValue ?? false);
 

package/components/template/menu/__tests__/useMenu.test.ts

@@ -0,0 +1,157 @@
+/**
+ * @description useMenu 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { useMenu } from '../useMenu';
+
+const SAMPLE_DATA = [
+  {
+    key: 'home', label: '首页',
+  },
+  {
+    key: 'system', label: '系统管理', children: [
+      { key: 'user', label: '用户管理' },
+      { key: 'role', label: '角色管理' },
+    ],
+  },
+  {
+    key: 'about', label: '关于',
+  },
+];
+
+describe('useMenu', () => {
+  it('initNodes 构建节点树', () => {
+    const { nodesRef, nodeMap } = useMenu({ data: SAMPLE_DATA });
+
+    expect(nodesRef.value).toHaveLength(3);
+    expect(nodeMap.size).toBe(5); // 3 + 2 children
+  });
+
+  it('根节点 isRoot=true，子节点有 parent', () => {
+    const { nodeMap } = useMenu({ data: SAMPLE_DATA });
+
+    expect(nodeMap.get('home')!.isRoot).toBe(true);
+    expect(nodeMap.get('user')!.isRoot).toBe(false);
+    expect(nodeMap.get('user')!.parent).toBe(nodeMap.get('system'));
+  });
+
+  it('defaultExpandAll 展开所有节点', () => {
+    const { nodeMap } = useMenu({ data: SAMPLE_DATA, defaultExpandAll: true });
+    expect(nodeMap.get('system')!.expand).toBe(true);
+  });
+
+  it('默认不展开', () => {
+    const { nodeMap } = useMenu({ data: SAMPLE_DATA });
+    expect(nodeMap.get('system')!.expand).toBe(false);
+  });
+
+  it('toggleExpand 切换展开', () => {
+    const { nodeMap, toggleExpand } = useMenu({ data: SAMPLE_DATA });
+    const node = nodeMap.get('system')!;
+
+    expect(node.expand).toBe(false);
+    toggleExpand(node);
+    expect(node.expand).toBe(true);
+    toggleExpand(node);
+    expect(node.expand).toBe(false);
+  });
+
+  it('setActive 激活节点并取消其他激活', () => {
+    const emit = vi.fn();
+    const { nodeMap, setActive } = useMenu({ data: SAMPLE_DATA }, emit);
+
+    setActive(nodeMap.get('home')!);
+    expect(nodeMap.get('home')!.isActive).toBe(true);
+    expect(emit).toHaveBeenCalledWith('update:active', 'home');
+
+    setActive(nodeMap.get('about')!);
+    expect(nodeMap.get('home')!.isActive).toBe(false);
+    expect(nodeMap.get('about')!.isActive).toBe(true);
+  });
+
+  it('受控 active 初始化', () => {
+    const { nodeMap } = useMenu({ data: SAMPLE_DATA, active: 'about' });
+    expect(nodeMap.get('about')!.isActive).toBe(true);
+    expect(nodeMap.get('home')!.isActive).toBe(false);
+  });
+
+  it('toggleChecked 切换选中', () => {
+    const { nodeMap, toggleChecked } = useMenu({ data: SAMPLE_DATA });
+    const node = nodeMap.get('user')!;
+
+    toggleChecked(node, true);
+    expect(node.checked).toBe(true);
+    expect(node.indeterminate).toBe(false);
+
+    toggleChecked(node, false);
+    expect(node.checked).toBe(false);
+  });
+
+  it('getCheckedKeys 获取选中 key', () => {
+    const { nodeMap, toggleChecked, getCheckedKeys } = useMenu({ data: SAMPLE_DATA });
+
+    toggleChecked(nodeMap.get('user')!, true);
+    toggleChecked(nodeMap.get('about')!, true);
+
+    const keys = getCheckedKeys();
+    expect(keys).toContain('user');
+    expect(keys).toContain('about');
+    expect(keys).toHaveLength(2);
+  });
+
+  it('半选节点不计入 getCheckedKeys', () => {
+    const { nodeMap, getCheckedKeys } = useMenu({ data: SAMPLE_DATA });
+    const node = nodeMap.get('system')!;
+    node.indeterminate = true;
+    node.checked = false;
+
+    expect(getCheckedKeys()).not.toContain('system');
+  });
+
+  it('getNodesByKeys 批量获取节点', () => {
+    const { getNodesByKeys } = useMenu({ data: SAMPLE_DATA });
+    const nodes = getNodesByKeys(['home', 'user']);
+    expect(nodes).toHaveLength(2);
+  });
+
+  it('getNodesByKeys 过滤不存在的 key', () => {
+    const { getNodesByKeys } = useMenu({ data: SAMPLE_DATA });
+    const nodes = getNodesByKeys(['home', 'nonexistent']);
+    expect(nodes).toHaveLength(1);
+  });
+
+  it('checkedKeys 初始化选中', () => {
+    const { nodeMap } = useMenu({ data: SAMPLE_DATA, checkedKeys: ['user', 'about'] });
+    expect(nodeMap.get('user')!.checked).toBe(true);
+    expect(nodeMap.get('about')!.checked).toBe(true);
+    expect(nodeMap.get('home')!.checked).toBe(false);
+  });
+
+  it('initNodes 重新初始化', () => {
+    const { initNodes, nodesRef, nodeMap } = useMenu({ data: SAMPLE_DATA });
+
+    initNodes([{ key: 'new', label: '新节点' }]);
+    expect(nodesRef.value).toHaveLength(1);
+    expect(nodeMap.size).toBe(1);
+    expect(nodeMap.get('new')!.label).toBe('新节点');
+  });
+
+  it('自定义 config 字段映射', () => {
+    const data = [
+      { id: 'a', name: '菜单A', items: [{ id: 'b', name: '子菜单B' }] },
+    ];
+    const { nodeMap } = useMenu({
+      data: data as any,
+      config: { key: 'id', label: 'name', children: 'items' },
+    });
+
+    expect(nodeMap.size).toBe(2);
+    expect(nodeMap.get('a')).toBeDefined();
+    expect(nodeMap.get('b')).toBeDefined();
+  });
+});

package/components/template/pagination/__tests__/usePagination.test.ts

@@ -0,0 +1,138 @@
+/**
+ * @description usePagination 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import { ref } from 'vue';
+import { usePagination, type Pager } from '../usePagination';
+
+/** 提取页码列表中的值 */
+const values = (list: Pager[]) => list.map(p => p.value);
+/** 提取页码列表中当前页标记 */
+const currentFlags = (list: Pager[]) => list.filter(p => p.isCurrent).map(p => p.value);
+
+describe('usePagination', () => {
+  describe('getPageBtnLength', () => {
+    it('计算总页数', () => {
+      const current = ref(1);
+      const { getPageBtnLength } = usePagination({ total: 100, pageSize: 10 }, current);
+      expect(getPageBtnLength()).toBe(10);
+    });
+
+    it('向上取整', () => {
+      const current = ref(1);
+      const { getPageBtnLength } = usePagination({ total: 101, pageSize: 10 }, current);
+      expect(getPageBtnLength()).toBe(11);
+    });
+
+    it('默认 total=0, pageSize=10', () => {
+      const current = ref(1);
+      const { getPageBtnLength } = usePagination({}, current);
+      expect(getPageBtnLength()).toBe(0);
+    });
+  });
+
+  describe('getPageNumList', () => {
+    it('只有一页时返回 [1]', () => {
+      const current = ref(1);
+      const { getPageNumList } = usePagination({ total: 5, pageSize: 10 }, current);
+      const list = getPageNumList();
+      expect(values(list)).toEqual([1]);
+    });
+
+    it('总页数 <= maxPageBtn 时不折叠', () => {
+      const current = ref(1);
+      const { getPageNumList } = usePagination({
+        total: 80, pageSize: 10, maxPageBtn: 10,
+      }, current);
+      const list = getPageNumList();
+      expect(values(list)).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+    });
+
+    it('当前页靠左时右侧折叠', () => {
+      const current = ref(1);
+      const { getPageNumList } = usePagination({
+        total: 200, pageSize: 10, foldedMaxPageBtn: 5, maxPageBtn: 10,
+      }, current);
+      const list = getPageNumList();
+
+      // 应包含折叠符 "..."
+      expect(list.some(p => p.type === 'folded')).toBe(true);
+      // 最后一个应是尾页 20
+      expect(list[list.length - 1].value).toBe(20);
+      // isCurrent 标记正确
+      expect(currentFlags(list)).toEqual([1]);
+    });
+
+    it('当前页靠右时左侧折叠', () => {
+      const current = ref(20);
+      const { getPageNumList } = usePagination({
+        total: 200, pageSize: 10, foldedMaxPageBtn: 5, maxPageBtn: 10,
+      }, current);
+      const list = getPageNumList();
+
+      expect(list[0].value).toBe(1); // 首页
+      expect(list[1].type).toBe('folded'); // 左折叠
+      expect(currentFlags(list)).toEqual([20]);
+    });
+
+    it('当前页居中时两侧折叠', () => {
+      const current = ref(10);
+      const { getPageNumList } = usePagination({
+        total: 200, pageSize: 10, foldedMaxPageBtn: 5, maxPageBtn: 10,
+      }, current);
+      const list = getPageNumList();
+
+      expect(list[0].value).toBe(1); // 首页
+      expect(list[list.length - 1].value).toBe(20); // 尾页
+      // 两个折叠符
+      const foldedCount = list.filter(p => p.type === 'folded').length;
+      expect(foldedCount).toBe(2);
+      expect(currentFlags(list)).toEqual([10]);
+    });
+
+    it('showEdgePageNum=false 不显示首尾页', () => {
+      const current = ref(10);
+      const { getPageNumList } = usePagination({
+        total: 200, pageSize: 10, foldedMaxPageBtn: 5, maxPageBtn: 10, showEdgePageNum: false,
+      }, current);
+      const list = getPageNumList();
+
+      // 不应以 1 开头
+      expect(list[0].value).not.toBe(1);
+      expect(list[list.length - 1].value).not.toBe(20);
+    });
+
+    it('折叠符的 jump 值正确', () => {
+      const current = ref(10);
+      const { getPageNumList } = usePagination({
+        total: 200, pageSize: 10, foldedMaxPageBtn: 5, maxPageBtn: 10,
+      }, current);
+      const list = getPageNumList();
+
+      const foldedPagers = list.filter(p => p.type === 'folded');
+      // 每个折叠符都应有 jump 值
+      foldedPagers.forEach(p => {
+        expect(p.jump).toBeGreaterThan(0);
+      });
+    });
+
+    it('isCurrent 标记正确跟随 currentValue', () => {
+      const current = ref(5);
+      const { getPageNumList } = usePagination({
+        total: 80, pageSize: 10,
+      }, current);
+      const list = getPageNumList();
+
+      expect(currentFlags(list)).toEqual([5]);
+
+      current.value = 3;
+      const list2 = getPageNumList();
+      expect(currentFlags(list2)).toEqual([3]);
+    });
+  });
+});

package/components/template/table/__tests__/useTable.test.ts

@@ -0,0 +1,139 @@
+/**
+ * @description useTable 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { useTable } from '../useTable';
+
+describe('useTable', () => {
+  const createRenders = () => ({
+    empty: 'EMPTY',
+    tbodyTr: (opt: any) => `TD:${opt.param}:${opt.data}`,
+    theadTh: (opt: any) => `TH:${opt.param}:${opt.label}`,
+    thead: (ths: string[]) => `THEAD:[${ths.join(',')}]`,
+    tbody: (trs: string[]) => `TBODY:[${trs.join(',')}]`,
+    tbodyTrs: (tds: string[], i: number) => `TR${i}:[${tds.join(',')}]`,
+    initSlot: () => undefined,
+  });
+
+  it('initTable 正确构建表头和表体', () => {
+    const { initTable } = useTable();
+    const columns = [
+      { props: { param: 'name', label: '姓名' } },
+      { props: { param: 'age', label: '年龄' } },
+    ];
+    const data = [
+      { name: '张三', age: 25 },
+      { name: '李四', age: 30 },
+    ];
+
+    const result = initTable(createRenders(), columns, data);
+
+    expect(result.thead).toBe('THEAD:[TH:name:姓名,TH:age:年龄]');
+    expect(result.tbody).toContain('TD:name:张三');
+    expect(result.tbody).toContain('TD:age:30');
+  });
+
+  it('数据为空时渲染 empty', () => {
+    const { initTable } = useTable();
+    const columns = [{ props: { param: 'name', label: '姓名' } }];
+
+    const result = initTable(createRenders(), columns, []);
+    expect(result.tbody).toBe('EMPTY');
+  });
+
+  it('列没有 props 时被过滤', () => {
+    const { initTable } = useTable();
+    const errorSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const columns = [
+      { props: { param: 'name', label: '姓名' } },
+      {}, // 无 props
+    ];
+    const data = [{ name: '张三' }];
+
+    const result = initTable(createRenders(), columns, data);
+    expect(result.thead).toBe('THEAD:[TH:name:姓名]');
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+
+  it('列宽 number 转换为 px', () => {
+    const { initTable } = useTable();
+    const renders = {
+      ...createRenders(),
+      theadTh: (opt: any) => `TH:${opt.style?.width}`,
+    };
+    const columns = [{ props: { param: 'name', label: '姓名', width: 200 } }];
+
+    const result = initTable(renders, columns, [{ name: 'test' }]);
+    expect(result.thead).toContain('200px');
+  });
+
+  it('列宽 string 直接使用', () => {
+    const { initTable } = useTable();
+    const renders = {
+      ...createRenders(),
+      theadTh: (opt: any) => `TH:${opt.style?.width}`,
+    };
+    const columns = [{ props: { param: 'name', label: '姓名', width: '50%' } }];
+
+    const result = initTable(renders, columns, [{ name: 'test' }]);
+    expect(result.thead).toContain('50%');
+  });
+
+  it('data 中缺少字段时返回空字符串', () => {
+    const { initTable } = useTable();
+    const columns = [{ props: { param: 'missing', label: '缺失' } }];
+    const data = [{ name: 'test' }];
+
+    const result = initTable(createRenders(), columns, data);
+    expect(result.tbody).toContain('TD:missing:');
+  });
+
+  it('initSlot 返回 slot 时传递给 tbodyTr', () => {
+    const { initTable } = useTable();
+    const bodySlot = () => 'custom';
+    const renders = {
+      ...createRenders(),
+      initSlot: () => ({ body: bodySlot, head: undefined }),
+      tbodyTr: (opt: any) => `TD:${opt.slot ? 'has-slot' : 'no-slot'}`,
+    };
+    const columns = [{ props: { param: 'name', label: '姓名' } }];
+    const data = [{ name: 'test' }];
+
+    const result = initTable(renders, columns, data);
+    expect(result.tbody).toContain('has-slot');
+  });
+
+  it('slotInfo 包含行数据和索引', () => {
+    const { initTable } = useTable();
+    let capturedSlotInfo: any;
+    const renders = {
+      ...createRenders(),
+      tbodyTr: (opt: any) => {
+        capturedSlotInfo = opt.slotInfo;
+        return 'TD';
+      },
+    };
+    const columns = [{ props: { param: 'name', label: '姓名' } }];
+    const data = [{ name: '张三' }];
+
+    initTable(renders, columns, data);
+    expect(capturedSlotInfo).toEqual({ data: { name: '张三' }, index: 0 });
+  });
+
+  it('error 输出带前缀的警告', () => {
+    const { error } = useTable();
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    error('test error');
+    expect(spy).toHaveBeenCalledWith('[水墨UI表格组件] test error');
+
+    spy.mockRestore();
+  });
+});

package/components/template/table/useTable.ts

@@ -49,10 +49,8 @@ export function useTable() {
 
     /** 从 data[i] 中安全取值 */
     const getData = (i: number, param: string) => {
-      if (data[i] && data[i][param]) {
-        return data[i][param];
-      }
-      return '';
+      if (data[i] == null) return '';
+      return data[i][param] ?? '';
     };
 
     /** 向每行的 td 列表中追加一列 */

package/components/types/hook.d.ts

@@ -10,4 +10,15 @@ 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;
+};
+