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

package/components/base/tag/props.d.ts

@@ -12,6 +12,8 @@
  * 江湖的业务千篇一律，复杂的代码好几百行。
  */
 
+import { KineSize } from '../../types/props';
+
 export declare type TagProps = {
   /**
    * @description tag type
@@ -28,7 +30,7 @@ export declare type TagProps = {
    * @default medium
    * @enum large|medium|small
    */
-  size?: 'large' | 'medium' | 'small';
+  size?: KineSize;
   /**
    * @description 是否显示关闭按钮
    * @type boolean

package/components/base/timePicker/__tests__/useTimePicker.test.ts

@@ -0,0 +1,118 @@
+/**
+ * @description useTimePicker 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import { useTimePicker, generateColumn } from '../useTimePicker';
+
+describe('generateColumn', () => {
+  it('生成 24 小时列', () => {
+    expect(generateColumn(24, 1)).toHaveLength(24);
+  });
+
+  it('生成 60 分钟列，步进 5', () => {
+    expect(generateColumn(60, 5)).toEqual([0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55]);
+  });
+});
+
+describe('useTimePicker', () => {
+  const defaultProps = {
+    modelValue: undefined as string | undefined,
+    showSeconds: true,
+    format: '',
+    placeholder: '请选择时间...',
+    hourStep: 1,
+    minuteStep: 1,
+    secondStep: 1,
+  };
+
+  it('初始化空值显示 placeholder', () => {
+    const tp = useTimePicker({ ...defaultProps });
+    expect(tp.displayValue.value).toBe('请选择时间...');
+    expect(tp.spanClass.value).toContain('m-time-picker-placeholder');
+  });
+
+  it('初始化有效时间正确解析', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '14:30:00' });
+    expect(tp.timeRef.value.hours).toBe(14);
+    expect(tp.timeRef.value.minutes).toBe(30);
+    expect(tp.timeRef.value.seconds).toBe(0);
+    expect(tp.displayValue.value).toBe('14:30:00');
+  });
+
+  it('解析 HH:mm 格式', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '08:15' });
+    expect(tp.timeRef.value.hours).toBe(8);
+    expect(tp.timeRef.value.minutes).toBe(15);
+  });
+
+  it('updateTimeRef 更新状态', () => {
+    const tp = useTimePicker({ ...defaultProps });
+    tp.updateTimeRef('22:45:30');
+
+    expect(tp.timeRef.value.hours).toBe(22);
+    expect(tp.timeRef.value.minutes).toBe(45);
+    expect(tp.timeRef.value.seconds).toBe(30);
+  });
+
+  it('updateTimeRef 空值恢复 placeholder', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '10:00:00' });
+    tp.updateTimeRef('');
+    expect(tp.displayValue.value).toBe('请选择时间...');
+  });
+
+  it('selectHour 更新小时并刷新显示', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '10:00:00' });
+    tp.selectHour(15);
+
+    expect(tp.timeRef.value.hours).toBe(15);
+    expect(tp.displayValue.value).toContain('15');
+    expect(tp.spanClass.value).not.toContain('m-time-picker-placeholder');
+  });
+
+  it('selectMinute 更新分钟', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '10:00:00' });
+    tp.selectMinute(30);
+    expect(tp.timeRef.value.minutes).toBe(30);
+  });
+
+  it('selectSecond 更新秒', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '10:00:00' });
+    tp.selectSecond(45);
+    expect(tp.timeRef.value.seconds).toBe(45);
+  });
+
+  it('getValue 返回格式化时间', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '10:30:45' });
+    expect(tp.getValue()).toBe('10:30:45');
+  });
+
+  it('showSeconds=false 时格式为 HH:mm', () => {
+    const tp = useTimePicker({ ...defaultProps, showSeconds: false, modelValue: '10:30:45' });
+    expect(tp.getValue()).toBe('10:30');
+  });
+
+  it('自定义 format', () => {
+    const tp = useTimePicker({ ...defaultProps, format: 'HH-mm-ss', modelValue: '10:30:45' });
+    expect(tp.displayValue.value).toBe('10-30-45');
+  });
+
+  it('hoursColumn 按 hourStep 生成', () => {
+    const tp = useTimePicker({ ...defaultProps, hourStep: 2 });
+    expect(tp.hoursColumn.value).toEqual([0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22]);
+  });
+
+  it('minutesColumn 按 minuteStep 生成', () => {
+    const tp = useTimePicker({ ...defaultProps, minuteStep: 15 });
+    expect(tp.minutesColumn.value).toEqual([0, 15, 30, 45]);
+  });
+
+  it('secondsColumn 按 secondStep 生成', () => {
+    const tp = useTimePicker({ ...defaultProps, secondStep: 30 });
+    expect(tp.secondsColumn.value).toEqual([0, 30]);
+  });
+});

package/components/base/timePicker/api.ts

@@ -6,7 +6,7 @@
  *
  * 江湖的业务千篇一律，复杂的代码好几百行。
  */
-import { MCOPO } from '../../types/props';
+import { MCOPO, MPropType } from '../../types/props';
 import { TimePickerProps } from './props';
 
 export const props: MCOPO<TimePickerProps> = {
@@ -18,4 +18,7 @@ export const props: MCOPO<TimePickerProps> = {
   hourStep: { type: Number, default: 1 },
   minuteStep: { type: Number, default: 1 },
   secondStep: { type: Number, default: 1 },
+  readonly: { type: Boolean, default: false },
+  clearable: { type: Boolean, default: false },
+  size: { type: String as unknown as MPropType<NonNullable<TimePickerProps['size']>>, default: undefined },
 };

package/components/base/timePicker/props.d.ts

@@ -7,6 +7,8 @@
  * 江湖的业务千篇一律，复杂的代码好几百行。
  */
 
+import { KineSize } from '../../types/props';
+
 export declare type TimePickerProps = {
   /**
    * @description 时间值（字符串，如 "14:30:00"）
@@ -56,6 +58,24 @@ export declare type TimePickerProps = {
    * @default 1
    */
   secondStep?: number;
+  /**
+   * @description 是否只读
+   * @type boolean
+   * @default false
+   */
+  readonly?: boolean;
+  /**
+   * @description whether to show clear button. 是否可清空
+   * @type boolean
+   * @default false
+   */
+  clearable?: boolean;
+  /**
+   * @description 尺寸
+   * @type KineSize
+   * @default undefined
+   */
+  size?: KineSize;
 };
 
 /** 时间内部引用 */

package/components/base/tooltip/api.ts

@@ -16,4 +16,5 @@ export const props: MCOPO<TooltipProps> = {
     default: 'top',
   },
   disabled: { type: Boolean, default: false },
+  maxWidth: { type: String, default: undefined },
 };

package/components/base/tooltip/props.d.ts

@@ -31,4 +31,10 @@ export declare type TooltipProps = {
    * @default false
    */
   disabled?: boolean;
+  /**
+   * @description max width of tooltip content. 浮层最大宽度
+   * @type string
+   * @default undefined
+   */
+  maxWidth?: string;
 };

package/components/base/transfer/useTransfer.ts

@@ -14,8 +14,9 @@
  */
 import { computed, ref, toRef } from 'vue';
 import { TransferItem, TransferProps } from './props';
+import { type HookContext } from '../../types/hook';
 
-export function useTransfer(props: TransferProps, ctx: any) {
+export function useTransfer(props: TransferProps, ctx: HookContext) {
   const dataRef = toRef(() => props.data ?? []);
   const modelValueRef = toRef(() => props.modelValue ?? []);
 

package/components/base/tree/__tests__/tree.test.ts

@@ -0,0 +1,214 @@
+/**
+ * @description Tree 类核心测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import Tree, { mergeConfig, DEFAULT_CONFIG } from '../tree';
+import { fixKey } from '../useTree';
+
+const SAMPLE_DATA = [
+  {
+    key: '1', label: '节点 1', children: [
+      { key: '1-1', label: '子节点 1-1' },
+      { key: '1-2', label: '子节点 1-2', children: [
+        { key: '1-2-1', label: '孙节点 1-2-1' },
+      ] },
+    ],
+  },
+  { key: '2', label: '节点 2' },
+  { key: '3', label: '节点 3', disabled: true },
+];
+
+describe('mergeConfig', () => {
+  it('返回默认配置', () => {
+    expect(mergeConfig(DEFAULT_CONFIG)).toBe(DEFAULT_CONFIG);
+  });
+
+  it('自定义字段合并', () => {
+    const result = mergeConfig({ key: 'id', label: 'name' });
+    expect(result.key).toBe('id');
+    expect(result.label).toBe('name');
+    expect(result.children).toBe('children');
+  });
+});
+
+describe('fixKey', () => {
+  it('为无 key 的节点生成 key', () => {
+    const data = [{ label: 'A' }, { label: 'B' }] as any[];
+    const result = fixKey(data, 'key') as any[];
+    expect(result[0].key).toBe('0');
+    expect(result[1].key).toBe('1');
+  });
+
+  it('已有 key 的节点保持不变', () => {
+    const data = [{ key: 'existing', label: 'A' }];
+    const result = fixKey(data, 'key') as any[];
+    expect(result[0].key).toBe('existing');
+  });
+
+  it('递归处理子节点', () => {
+    const data = [{ key: 'root', children: [{ label: 'child' }] }] as any[];
+    const result = fixKey(data, 'key') as any[];
+    expect(result[0].children[0].key).toBe('root0');
+  });
+
+  it('单节点也能处理', () => {
+    const data = { label: 'single' } as any;
+    const result = fixKey(data, 'key') as any;
+    expect(result.key).toBe('0');
+  });
+});
+
+describe('Tree', () => {
+  it('构建树并获取根节点', () => {
+    const tree = new Tree({ data: SAMPLE_DATA });
+    const roots = tree.getTreeData();
+    expect(roots).toHaveLength(3);
+    expect(roots[0].isRoot).toBe(true);
+  });
+
+  it('getTreeData 通过 keys 获取节点', () => {
+    const tree = new Tree({ data: SAMPLE_DATA });
+    const nodes = tree.getTreeData(['1-1', '2']);
+    expect(nodes).toHaveLength(2);
+  });
+
+  it('getChildrenKeys 返回直接子节点 key', () => {
+    const tree = new Tree({ data: SAMPLE_DATA });
+    const root = tree.getTreeData(['1'])[0];
+    const keys = tree.getChildrenKeys(root);
+    expect(keys).toEqual(['1-1', '1-2']);
+  });
+
+  it('toggleExpand 切换展开状态', () => {
+    const tree = new Tree({ data: SAMPLE_DATA });
+    const node = tree.getTreeData(['1'])[0];
+
+    expect(node.expand).toBe(false);
+    tree.toggleExpand(node);
+    expect(node.expand).toBe(true);
+    tree.toggleExpand(node);
+    expect(node.expand).toBe(false);
+  });
+
+  it('toggleExpand 指定值', () => {
+    const tree = new Tree({ data: SAMPLE_DATA });
+    const node = tree.getTreeData(['1'])[0];
+
+    tree.toggleExpand(node, true);
+    expect(node.expand).toBe(true);
+    tree.toggleExpand(node, true);
+    expect(node.expand).toBe(true);
+  });
+
+  it('defaultExpandAll 展开所有节点', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, defaultExpandAll: true });
+    const root = tree.getTreeData(['1'])[0];
+    expect(root.expand).toBe(true);
+  });
+
+  it('setNodeCheckbox 选中节点', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, checkStrictly: true });
+    const root = tree.getTreeData(['1'])[0];
+
+    tree.setNodeCheckbox(root, true);
+    expect(root.checked).toBe(true);
+    expect(root.indeterminate).toBe(false);
+
+    // 子节点也被选中（checkStrictly=true 级联）
+    const child = tree.getTreeData(['1-1'])[0];
+    expect(child.checked).toBe(true);
+  });
+
+  it('setNodeCheckbox checkStrictly=true 向上级联', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, checkStrictly: true });
+    const child = tree.getTreeData(['1-1'])[0];
+
+    tree.setNodeCheckbox(child, true);
+
+    // 父节点应该是半选（只有一个子节点选中）
+    const root = tree.getTreeData(['1'])[0];
+    expect(root.indeterminate).toBe(true);
+    expect(root.checked).toBe(false);
+  });
+
+  it('setNodeCheckbox 全部子节点选中时父节点全选', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, checkStrictly: true });
+
+    tree.setNodeCheckbox(tree.getTreeData(['1-1'])[0], true);
+    tree.setNodeCheckbox(tree.getTreeData(['1-2'])[0], true);
+
+    const root = tree.getTreeData(['1'])[0];
+    expect(root.checked).toBe(true);
+    expect(root.indeterminate).toBe(false);
+  });
+
+  it('setNodeCheckbox checkStrictly=false 不级联', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, checkStrictly: false });
+    const root = tree.getTreeData(['1'])[0];
+
+    tree.setNodeCheckbox(root, true);
+    // 子节点不受影响
+    const child = tree.getTreeData(['1-1'])[0];
+    expect(child.checked).toBe(false);
+  });
+
+  it('disabled 节点不受级联影响', () => {
+    const data = [
+      {
+        key: 'p', children: [
+          { key: 'c1' },
+          { key: 'c2', disabled: true },
+        ],
+      },
+    ];
+    const tree = new Tree({ data, checkStrictly: true });
+    const parent = tree.getTreeData(['p'])[0];
+
+    tree.setNodeCheckbox(parent, true);
+    // c1 被选中，c2 因 disabled 不受影响
+    expect(tree.getTreeData(['c1'])[0].checked).toBe(true);
+    expect(tree.getTreeData(['c2'])[0].checked).toBe(false);
+  });
+
+  it('setCheckedByKeys 批量选中', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, checkStrictly: true });
+    tree.setCheckedByKeys(['1-1', '2']);
+
+    expect(tree.getTreeData(['1-1'])[0].checked).toBe(true);
+    expect(tree.getTreeData(['2'])[0].checked).toBe(true);
+  });
+
+  it('getKeys 获取选中和展开的 key', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, checkStrictly: true, defaultExpandAll: true });
+    tree.setNodeCheckbox(tree.getTreeData(['2'])[0], true);
+
+    const { checkedKeys, expandKeys } = tree.getKeys();
+    expect(checkedKeys).toContain('2');
+    expect(expandKeys.length).toBeGreaterThan(0);
+  });
+
+  it('单节点数据也能正常构建', () => {
+    const tree = new Tree({ data: { key: 'single', label: '单节点' } });
+    const roots = tree.getTreeData();
+    expect(roots).toHaveLength(1);
+    expect(roots[0].isRoot).toBe(true);
+  });
+
+  it('自定义 config 字段映射', () => {
+    const data = [{ id: 'a', name: '节点 A', items: [{ id: 'b', name: '子节点 B' }] }] as any[];
+    const tree = new Tree({
+      data,
+      config: { key: 'id', label: 'name', value: 'value', children: 'items' },
+    });
+    const roots = tree.getTreeData();
+    expect(roots).toHaveLength(1);
+
+    const childKeys = tree.getChildrenKeys(roots[0]);
+    expect(childKeys).toEqual(['b']);
+  });
+});

package/components/message/dialog/api.ts

@@ -6,7 +6,7 @@
  *
  * 江湖的业务千篇一律，复杂的代码好几百行。
  */
-import { MCOPO } from '../../types/props';
+import { MCOPO, MPropType } from '../../types/props';
 import { DialogProps } from './props';
 
 export const props: MCOPO<DialogProps> = {
@@ -16,4 +16,5 @@ export const props: MCOPO<DialogProps> = {
   teleport: { type: Object, default: () => ({ to: 'body' }) },
   title: { type: String, default: undefined },
   width: { type: String, default: undefined },
+  beforeClose: { type: Function as unknown as MPropType<NonNullable<DialogProps['beforeClose']>>, default: undefined },
 };

package/components/message/dialog/props.d.ts

@@ -52,4 +52,11 @@ export declare type DialogProps = {
    * @default undefined
    */
   width?: string;
+  /**
+   * @description callback before close, return false or Promise.reject to prevent close
+   *              关闭前的回调，返回 false 或 reject 的 Promise 可阻止关闭
+   * @type () => boolean | Promise<boolean>
+   * @default undefined
+   */
+  beforeClose?: () => boolean | Promise<boolean>;
 };

package/components/message/drawer/api.ts

@@ -29,4 +29,5 @@ export const props: MCOPO<DrawerProps> = {
   title: { type: String, default: undefined },
   width: { type: String, default: undefined },
   height: { type: String, default: undefined },
+  beforeClose: { type: Function as unknown as MPropType<NonNullable<DrawerProps['beforeClose']>>, default: undefined },
 };

package/components/message/drawer/props.d.ts

@@ -70,4 +70,11 @@ export declare type DrawerProps = {
    * @default undefined
    */
   height?: string,
+  /**
+   * @description callback before close, return false or Promise.reject to prevent close
+   *              关闭前的回调，返回 false 或 reject 的 Promise 可阻止关闭
+   * @type () => boolean | Promise<boolean>
+   * @default undefined
+   */
+  beforeClose?: () => boolean | Promise<boolean>,
 };

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