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

package/components/base/transfer/useTransfer.ts

@@ -0,0 +1,208 @@
+/**
+ * @description Transfer 组件核心 composable
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 核心逻辑：
+ * - 左右数据分割：data 按 modelValue（右侧 key 列表）分为左侧/右侧两列表
+ * - 勾选状态：leftChecked / rightChecked 分别维护左右侧勾选集合
+ * - 过滤：filterable 模式下各自按搜索词过滤
+ * - 穿梭操作：将勾选项从一侧移到另一侧，emit change 事件
+ */
+import { computed, ref, toRef } from 'vue';
+import { TransferItem, TransferProps } from './props';
+import { type HookContext } from '../../types/hook';
+
+export function useTransfer(props: TransferProps, ctx: HookContext) {
+  const dataRef = toRef(() => props.data ?? []);
+  const modelValueRef = toRef(() => props.modelValue ?? []);
+
+  // --- 搜索关键词 ---
+  const leftSearch = ref('');
+  const rightSearch = ref('');
+
+  // --- 勾选状态（key 集合） ---
+  const leftChecked = ref<Set<string | number>>(new Set());
+  const rightChecked = ref<Set<string | number>>(new Set());
+
+  // --- 左右数据分割 ---
+
+  /** 右侧数据：key 在 modelValue 中的项 */
+  const rightData = computed<TransferItem[]>(() => {
+    const rightKeys = new Set(modelValueRef.value);
+    return dataRef.value.filter(item => rightKeys.has(item.key));
+  });
+
+  /** 左侧数据：key 不在 modelValue 中的项 */
+  const leftData = computed<TransferItem[]>(() => {
+    const rightKeys = new Set(modelValueRef.value);
+    return dataRef.value.filter(item => !rightKeys.has(item.key));
+  });
+
+  /** 过滤后的左侧列表 */
+  const filteredLeftData = computed<TransferItem[]>(() => {
+    if (!props.filterable || !leftSearch.value) return leftData.value;
+    const q = leftSearch.value.toLowerCase();
+    return leftData.value.filter(item => item.label.toLowerCase().includes(q));
+  });
+
+  /** 过滤后的右侧列表 */
+  const filteredRightData = computed<TransferItem[]>(() => {
+    if (!props.filterable || !rightSearch.value) return rightData.value;
+    const q = rightSearch.value.toLowerCase();
+    return rightData.value.filter(item => item.label.toLowerCase().includes(q));
+  });
+
+  // --- 全选状态 ---
+
+  /** 左侧是否全选（仅计算过滤后的可勾选项） */
+  const isLeftAllChecked = computed(() => {
+    const checkable = filteredLeftData.value.filter(item => !item.disabled);
+    return checkable.length > 0 && checkable.every(item => leftChecked.value.has(item.key));
+  });
+
+  /** 左侧是否半选 */
+  const isLeftIndeterminate = computed(() => {
+    const checkable = filteredLeftData.value.filter(item => !item.disabled);
+    const checkedCount = checkable.filter(item => leftChecked.value.has(item.key)).length;
+    return checkedCount > 0 && checkedCount < checkable.length;
+  });
+
+  /** 右侧是否全选 */
+  const isRightAllChecked = computed(() => {
+    const checkable = filteredRightData.value.filter(item => !item.disabled);
+    return checkable.length > 0 && checkable.every(item => rightChecked.value.has(item.key));
+  });
+
+  /** 右侧是否半选 */
+  const isRightIndeterminate = computed(() => {
+    const checkable = filteredRightData.value.filter(item => !item.disabled);
+    const checkedCount = checkable.filter(item => rightChecked.value.has(item.key)).length;
+    return checkedCount > 0 && checkedCount < checkable.length;
+  });
+
+  // --- 事件处理 ---
+
+  /** 切换左侧某项的勾选 */
+  const toggleLeftCheck = (key: string | number, disabled: boolean) => {
+    if (disabled) return;
+    const newSet = new Set(leftChecked.value);
+    if (newSet.has(key)) {
+      newSet.delete(key);
+    } else {
+      newSet.add(key);
+    }
+    leftChecked.value = newSet;
+  };
+
+  /** 切换右侧某项的勾选 */
+  const toggleRightCheck = (key: string | number, disabled: boolean) => {
+    if (disabled) return;
+    const newSet = new Set(rightChecked.value);
+    if (newSet.has(key)) {
+      newSet.delete(key);
+    } else {
+      newSet.add(key);
+    }
+    rightChecked.value = newSet;
+  };
+
+  /** 左侧全选 / 取消全选 */
+  const toggleLeftAll = () => {
+    const checkable = filteredLeftData.value.filter(item => !item.disabled);
+    if (isLeftAllChecked.value) {
+      // 取消勾选过滤后的项
+      const newSet = new Set(leftChecked.value);
+      checkable.forEach(item => newSet.delete(item.key));
+      leftChecked.value = newSet;
+    } else {
+      // 全选过滤后的项
+      const newSet = new Set(leftChecked.value);
+      checkable.forEach(item => newSet.add(item.key));
+      leftChecked.value = newSet;
+    }
+  };
+
+  /** 右侧全选 / 取消全选 */
+  const toggleRightAll = () => {
+    const checkable = filteredRightData.value.filter(item => !item.disabled);
+    if (isRightAllChecked.value) {
+      const newSet = new Set(rightChecked.value);
+      checkable.forEach(item => newSet.delete(item.key));
+      rightChecked.value = newSet;
+    } else {
+      const newSet = new Set(rightChecked.value);
+      checkable.forEach(item => newSet.add(item.key));
+      rightChecked.value = newSet;
+    }
+  };
+
+  /** 将左侧勾选项移到右侧（→ 方向） */
+  const moveToRight = () => {
+    if (!leftChecked.value.size) return;
+
+    // 要移动的 key 列表
+    const movedKeys = [...leftChecked.value];
+    // 新的右侧 key 列表 = 原右侧 + 移过来的
+    const newModelValue = [...modelValueRef.value, ...movedKeys];
+
+    ctx.emit('update:modelValue', newModelValue);
+    ctx.emit('change', newModelValue, 'right', movedKeys);
+
+    // 清空左侧勾选
+    leftChecked.value = new Set();
+  };
+
+  /** 将右侧勾选项移到左侧（← 方向） */
+  const moveToLeft = () => {
+    if (!rightChecked.value.size) return;
+
+    const movedKeys = [...rightChecked.value];
+    const movedSet = new Set(movedKeys);
+    // 新的右侧 key 列表 = 原右侧中去掉移走的
+    const newModelValue = modelValueRef.value.filter(key => !movedSet.has(key));
+
+    ctx.emit('update:modelValue', newModelValue);
+    ctx.emit('change', newModelValue, 'left', movedKeys);
+
+    // 清空右侧勾选
+    rightChecked.value = new Set();
+  };
+
+  /** 左侧是否有勾选项（控制按钮是否可用） */
+  const hasLeftChecked = computed(() => leftChecked.value.size > 0);
+
+  /** 右侧是否有勾选项 */
+  const hasRightChecked = computed(() => rightChecked.value.size > 0);
+
+  return {
+    // 搜索
+    leftSearch,
+    rightSearch,
+    // 数据
+    leftData,
+    rightData,
+    filteredLeftData,
+    filteredRightData,
+    // 勾选状态
+    leftChecked,
+    rightChecked,
+    hasLeftChecked,
+    hasRightChecked,
+    // 全选
+    isLeftAllChecked,
+    isLeftIndeterminate,
+    isRightAllChecked,
+    isRightIndeterminate,
+    // 事件
+    toggleLeftCheck,
+    toggleRightCheck,
+    toggleLeftAll,
+    toggleRightAll,
+    moveToRight,
+    moveToLeft,
+  };
+}

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

@@ -0,0 +1,223 @@
+/**
+ * @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']);
+  });
+
+  it('getTreeData 不存在的 key 返回 undefined 元素', () => {
+    // cacheMap.get(key) 对不存在的 key 返回 undefined，
+    // getNodesByKeys 不做过滤，数组中会包含 undefined
+    const tree = new Tree({ data: SAMPLE_DATA });
+    const nodes = tree.getTreeData(['nonexistent']);
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]).toBeUndefined();
+  });
+});

package/components/base/tree/api.ts

@@ -0,0 +1,47 @@
+/**
+ * @description tree 运行时 props 定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { TreeNodeData, TreeNodeProps, TreeProps } from './props';
+import { DEFAULT_CONFIG } from './tree';
+
+/** 默认树配置（对外导出供使用方引用） */
+export const DEFAULT_TREE_CONFIG = DEFAULT_CONFIG;
+
+/** MTree 组件的 props 定义 */
+export const props: MCOPO<TreeProps> = {
+  data: { type: [Object, Array], default: () => [] },
+  config: { type: Object, default: () => DEFAULT_CONFIG },
+  checkbox: { type: Boolean, default: false },
+  defaultExpandAll: { type: Boolean, default: false },
+  checkedKeys: { type: Array, default: () => [] },
+  checkStrictly: { type: Boolean, default: true },
+};
+
+/** MTreeNode 子组件的 props 定义 */
+export const treeNodeProps: MCOPO<TreeNodeProps> = {
+  data: { type: Array, default: () => [] },
+  config: { type: Object, default: () => DEFAULT_CONFIG },
+  checkbox: { type: Boolean, default: false },
+  getNodesByKeys: {
+    type: Function as MPropType<(keys: TreeNodeData['key'][]) => TreeNodeData[]>,
+    required: true,
+  },
+  handleCheck: {
+    type: Function as MPropType<(node: TreeNodeData, check: boolean) => void>,
+    required: true,
+  },
+  handleExpand: {
+    type: Function as MPropType<(node: TreeNodeData, e: MouseEvent) => void>,
+    required: true,
+  },
+  handleItemClick: {
+    type: Function as MPropType<(node: TreeNodeData, e: MouseEvent) => void>,
+    required: true,
+  },
+};

package/components/base/tree/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @description tree core 导出
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { props, treeNodeProps } from './api';
+import { useTree } from './useTree';
+
+export const TreeCore = {
+  props,
+  treeNodeProps,
+  useTree,
+};
+
+export type {
+  TreeProps,
+  TreeData,
+  TreeNodeData,
+  TreeConfig,
+  TreeStatusKey,
+  TreeNodeProps,
+} from './props';
+
+export { useTree, fixKey } from './useTree';
+export { default as Tree } from './tree';
+export { DEFAULT_TREE_CONFIG, props as treeProps, treeNodeProps } from './api';

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

@@ -0,0 +1,108 @@
+/**
+ * @description tree 组件类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * @name m-tree
+ * @docDescription Tree component with shuimo-ui style.
+ *                 水墨组件的树组件。
+ * @docUrl https://shuimo.design/tree
+ */
+
+export declare type TreeProps = {
+  /**
+   * @description 树数据
+   * @type TreeData | TreeData[]
+   * @default []
+   */
+  data?: TreeData | TreeData[];
+  /**
+   * @description 树配置项，用于字段映射
+   * @type TreeConfig
+   * @default { key:'key', label:'label', value:'value', children: 'children' }
+   */
+  config?: TreeConfig;
+  /**
+   * @description 是否使用 checkbox 模式
+   * @type boolean
+   * @default false
+   */
+  checkbox?: boolean;
+  /**
+   * @description 是否默认展开所有节点
+   * @type boolean
+   * @default false
+   */
+  defaultExpandAll?: boolean;
+  /**
+   * @description 选中的 key 列表（v-model:checkedKeys）
+   * @type Array<string|number>
+   * @default []
+   */
+  checkedKeys?: Array<string | number>;
+  /**
+   * @description 父子节点选中状态是否关联（true 表示关联）
+   * @type boolean
+   * @default true
+   */
+  checkStrictly?: boolean;
+};
+
+export interface TreeData {
+  key: string | number;
+  label?: string;
+  value?: string | number;
+  children?: TreeData[];
+  disabled?: boolean;
+  [k: string]: unknown;
+}
+
+export interface TreeNodeData extends TreeData {
+  /** checkbox 选中状态 */
+  checked?: boolean;
+  /** 半选状态（部分子节点选中） */
+  indeterminate?: boolean;
+  /** 点击选中状态 */
+  selected?: boolean;
+  /** 展开状态 */
+  expand?: boolean;
+  /** 收起状态 */
+  close?: boolean;
+  /** 子节点列表 */
+  children?: TreeNodeData[];
+  /** 父节点引用 */
+  parent?: TreeNodeData | null;
+  /** 是否为根节点 */
+  isRoot?: boolean;
+}
+
+export type TreeStatusKey = 'checked' | 'selected' | 'expand' | 'close';
+
+export interface TreeConfig {
+  key: string | number;
+  label: string;
+  value: string;
+  children: string;
+  expand?: string;
+}
+
+/**
+ * MTreeNode 子组件的 props 类型
+ */
+export declare type TreeNodeProps = {
+  /** 当前层节点数据列表 */
+  data?: TreeNodeData[];
+  /** 字段映射配置 */
+  config?: TreeConfig;
+  /** 是否使用 checkbox */
+  checkbox?: boolean;
+  /** 根据 key 批量获取节点 */
+  getNodesByKeys: (keys: (string | number)[]) => TreeNodeData[];
+  /** 切换展开/收起 */
+  handleExpand: (node: TreeNodeData, e: MouseEvent) => void;
+  /** 切换 checkbox 选中 */
+  handleCheck: (node: TreeNodeData, checked: boolean) => void;
+  /** 节点点击 */
+  handleItemClick: (node: TreeNodeData, e: MouseEvent) => void;
+};