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

package/components/base/transfer/useTransfer.ts

@@ -0,0 +1,207 @@
+/**
+ * @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';
+
+export function useTransfer(props: TransferProps, ctx: any) {
+  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/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;
+};

package/components/base/tree/tree.ts

@@ -0,0 +1,263 @@
+/**
+ * @description Tree 核心数据结构类，负责树节点的构建、缓存和状态管理
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { TreeConfig, TreeData, TreeNodeData, TreeStatusKey } from './props';
+
+/** 节点缓存 Map 类型 */
+export type TreeDataMap = Map<TreeNodeData['key'], TreeNodeData>;
+
+/** 默认字段映射配置 */
+export const DEFAULT_CONFIG: TreeConfig = {
+  key: 'key',
+  label: 'label',
+  value: 'value',
+  children: 'children',
+  expand: 'expand',
+};
+
+/** 合并用户配置与默认配置 */
+export const mergeConfig = (config: Partial<TreeConfig>): TreeConfig => {
+  if (config === DEFAULT_CONFIG) {
+    return DEFAULT_CONFIG;
+  }
+  return {
+    key: config.key ?? DEFAULT_CONFIG.key,
+    label: config.label ?? DEFAULT_CONFIG.label,
+    value: config.value ?? DEFAULT_CONFIG.value,
+    children: config.children ?? DEFAULT_CONFIG.children,
+    expand: config.expand ?? DEFAULT_CONFIG.expand,
+  };
+};
+
+export interface TreeNodeOptions {
+  data: TreeData | TreeData[];
+  config?: TreeConfig;
+  defaultExpandAll?: boolean;
+  checkStrictly?: boolean;
+}
+
+export interface TreeAttrs {
+  defaultExpandAll: boolean;
+  checkStrictly: boolean;
+}
+
+export default class Tree {
+  /** 源数据（已深拷贝） */
+  #source: TreeNodeData[];
+  /** 节点缓存 Map，key 为节点标识 */
+  #cacheMap: TreeDataMap;
+  /** 字段映射配置 */
+  #config: TreeConfig = DEFAULT_CONFIG;
+  /** 初始化配置（defaultExpandAll / checkStrictly） */
+  #initialConfig: TreeAttrs;
+
+  constructor(options: TreeNodeOptions) {
+    const {
+      data,
+      config = DEFAULT_CONFIG,
+      defaultExpandAll = false,
+      checkStrictly = true,
+    } = options;
+    this.#cacheMap = new Map<TreeNodeData['key'], TreeNodeData>();
+    this.#source = Array.isArray(data) ? data : [data];
+    this.#config = mergeConfig(config);
+    this.#initialConfig = { defaultExpandAll, checkStrictly };
+    this.#init();
+  }
+
+  /** 暴露配置，供组件层读取 */
+  get config() {
+    return this.#config;
+  }
+
+  /** 递归生成单个 TreeNodeData，并写入 cacheMap */
+  #genTreeNodeData(data: TreeData, parentKey?: TreeData['key']): TreeNodeData {
+    const { defaultExpandAll } = this.#initialConfig;
+    const { key: k, children: c, expand: e } = this.#config;
+
+    const node: TreeNodeData = {
+      ...data,
+      expand: defaultExpandAll || !!(data[e!] as boolean | undefined),
+      selected: false,
+      checked: false,
+      indeterminate: false,
+      parent: parentKey ? this.#cacheMap.get(parentKey) : undefined,
+      isRoot: !parentKey,
+    };
+
+    // 使用节点自身的 key 字段值作为 Map 键
+    this.#cacheMap.set(node[k] as TreeNodeData['key'], node);
+
+    // 递归处理子节点
+    const nodeChildren = node[c] as TreeNodeData[] | undefined;
+    if (nodeChildren && nodeChildren.length > 0) {
+      node[c] = this.#genCacheMap(nodeChildren, node[k] as TreeData['key']) as unknown;
+    }
+
+    return node;
+  }
+
+  /** 清空缓存 */
+  #clearCache() {
+    this.#cacheMap.clear();
+  }
+
+  /** 初始化：清空缓存后重新构建 */
+  #init() {
+    this.#clearCache();
+    this.#genCacheMap();
+  }
+
+  /** 递归批量构建节点并填充 cacheMap */
+  #genCacheMap(data: TreeNodeData[] = this.#source, parentKey?: TreeData['key']): TreeNodeData[] {
+    const len = data.length;
+    const treeNodeData: TreeNodeData[] = [];
+    for (let i = 0; i < len; i++) {
+      const treeNode = this.#genTreeNodeData(data[i], parentKey);
+      treeNodeData.push(treeNode);
+    }
+    return treeNodeData;
+  }
+
+  /** 获取所有缓存节点列表 */
+  #getCacheList(): TreeNodeData[] {
+    return Array.from(this.#cacheMap.values());
+  }
+
+  /**
+   * 向上递归更新父节点的选中/半选状态
+   * 规则：所有子节点选中 → 父节点选中；部分选中或有半选 → 父节点半选
+   */
+  #setParentChecked(parent: TreeNodeData) {
+    if (parent.disabled) {
+      return;
+    }
+    const { children: c } = this.#config;
+    const children: TreeNodeData[] = (parent[c] as TreeNodeData[]) ?? [];
+    const allChecked = children.every(child => child.checked);
+    const oneChecked = children.some(child => child.checked);
+    const onIndeterminate = children.some(child => child.indeterminate);
+
+    if (allChecked) {
+      parent.indeterminate = false;
+      parent.checked = true;
+    } else {
+      parent.indeterminate = oneChecked || onIndeterminate;
+      parent.checked = false;
+    }
+
+    // 继续向上传播
+    if (parent.parent) {
+      this.#setParentChecked(parent.parent);
+    }
+  }
+
+  /** 递归设置子节点的某个状态字段 */
+  #setChildrenStatus(statusKey: TreeStatusKey, nodes: TreeNodeData[], value: boolean) {
+    const { children: c } = this.#config;
+    nodes.forEach(node => {
+      if (node.disabled) {
+        return;
+      }
+      (node as Record<string, unknown>)[statusKey] = value;
+      const nodeChildren = node[c] as TreeNodeData[] | undefined;
+      if (nodeChildren) {
+        this.#setChildrenStatus(statusKey, nodeChildren, value);
+      }
+    });
+  }
+
+  // ==================== 公开方法 ====================
+
+  /** 获取某节点的直接子节点 key 列表 */
+  getChildrenKeys(node: TreeNodeData): TreeNodeData['key'][] {
+    const { children: c, key: k } = this.#config;
+    const children = node[c] as TreeNodeData[] | undefined;
+    if (children) {
+      return children.map((it) => it[k] as TreeNodeData['key']);
+    }
+    return [];
+  }
+
+  /** 根据 key 数组批量获取节点 */
+  getNodesByKeys(keys: TreeNodeData['key'][]): TreeNodeData[] {
+    return keys.map(key => this.#cacheMap.get(key)!);
+  }
+
+  /**
+   * 获取树形数据
+   * @param keys 若传入则返回对应 key 的节点列表，否则返回所有根节点
+   */
+  getTreeData(keys?: TreeNodeData['key'][]): TreeNodeData[] {
+    if (keys) {
+      return this.getNodesByKeys(keys);
+    }
+    return this.#getCacheList().filter(it => it.isRoot);
+  }
+
+  /** 获取当前所有选中 key 和展开 key */
+  getKeys(): { checkedKeys: TreeNodeData['key'][]; expandKeys: TreeNodeData['key'][] } {
+    const expandKeys: TreeNodeData['key'][] = [];
+    const checkedKeys: TreeNodeData['key'][] = [];
+    const iterator = this.#cacheMap[Symbol.iterator]();
+    let next = iterator.next();
+    while (!next.done) {
+      const [, node] = next.value;
+      const key = Reflect.get(node as Record<string, unknown>, this.#config.key as string) as TreeNodeData['key'];
+      // 排除半选状态
+      if (node.checked && !node.indeterminate) {
+        checkedKeys.push(key);
+      }
+      if (node.children && node.expand) {
+        expandKeys.push(key);
+      }
+      next = iterator.next();
+    }
+    return { checkedKeys, expandKeys };
+  }
+
+  /** 切换节点展开/收起状态 */
+  toggleExpand(node: TreeNodeData, value?: boolean) {
+    if (value !== undefined) {
+      node.expand = value;
+    } else {
+      node.expand = !node.expand;
+    }
+  }
+
+  /**
+   * 设置节点 checkbox 选中状态
+   * checkStrictly=true（默认）时级联更新子节点和父节点状态
+   */
+  setNodeCheckbox(node: TreeNodeData, checked: boolean) {
+    node.checked = checked;
+    node.indeterminate = false;
+    const { checkStrictly } = this.#initialConfig;
+    if (!checkStrictly) {
+      return;
+    }
+    // 向下级联：设置所有子孙节点
+    if (node.children) {
+      this.#setChildrenStatus('checked', node.children, checked);
+    }
+    // 向上级联：更新父节点的半选/全选状态
+    if (node.parent) {
+      this.#setParentChecked(node.parent);
+    }
+  }
+
+  /** 根据 key 数组批量设置节点为选中状态 */
+  setCheckedByKeys(keys: TreeNodeData['key'][]) {
+    const nodes = this.getNodesByKeys(keys);
+    nodes.forEach(node => {
+      if (node) {
+        this.setNodeCheckbox(node, true);
+      }
+    });
+  }
+}