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

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

package/components/base/tree/useTree.ts

@@ -0,0 +1,114 @@
+/**
+ * @description Tree 组件 composable，封装树的初始化与交互逻辑
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { shallowRef } from 'vue';
+import Tree from './tree';
+import { TreeData, TreeNodeData, TreeProps } from './props';
+
+/** fixKey 内部递归实现：为无 key 的节点生成唯一 key */
+const _fixKey = (data: TreeData[], key: string | number = 'key', prefixKey: string | number): TreeData[] => {
+  let keyStart = 0;
+  return data.map(d => {
+    if (!d[key]) {
+      d[key] = `${prefixKey}${keyStart++}`;
+    }
+    if (d.children) {
+      d.children = _fixKey(d.children as TreeData[], key, d[key] as string | number) as TreeData[];
+    }
+    return d;
+  });
+};
+
+/**
+ * 为没有 key 的节点递归生成唯一标识
+ * @param data 树数据（数组或单节点）
+ * @param key  key 字段名，默认 'key'
+ * @param prefixKey 前缀 key，用于构造子节点唯一 id
+ */
+export const fixKey = (
+  data: TreeData | TreeData[],
+  key: string | number,
+  prefixKey: string | number = '',
+): TreeData | TreeData[] => {
+  return Array.isArray(data)
+    ? _fixKey(data, key ?? 'key', prefixKey)
+    : _fixKey([data], key ?? 'key', prefixKey)[0];
+};
+
+export interface UseTreeOptions {
+  props: TreeProps;
+  event: {
+    /** 触发 shallowRef 更新，通知 Vue 重新渲染 */
+    triggerTree: () => void;
+  };
+}
+
+/**
+ * useTree — Tree 组件逻辑 composable
+ *
+ * 返回：
+ * - treeRef：Tree 实例的 shallowRef
+ * - initTreeRef：重新初始化 Tree（数据变化时调用）
+ * - handleToggleExpand：切换节点展开/收起
+ * - handleToggleChecked：切换节点 checkbox 选中状态
+ * - getNodesByKeys：根据 key 批量获取节点
+ */
+export const useTree = (options: UseTreeOptions) => {
+  const { props, event } = options;
+  const treeRef = shallowRef<Tree>();
+
+  /**
+   * 初始化 Tree 实例
+   * 使用 structuredClone 深拷贝数据，避免直接修改外部数据源
+   */
+  const initTreeRef = (data: TreeData | TreeData[] | undefined = props.data) => {
+    // 统一转为数组
+    const rawArr = Array.isArray(data) ? data : (data ? [data] : []);
+    // 深拷贝避免污染原始数据（不使用 structuredClone，因为 Vue 响应式代理无法被 clone）
+    const cloned = JSON.parse(JSON.stringify(rawArr)) as TreeData[];
+    // 为无 key 节点补充 key
+    const keyField = props.config?.key ?? 'key';
+    const fixed = fixKey(cloned, keyField) as TreeData[];
+
+    treeRef.value = new Tree({
+      data: fixed,
+      config: props.config,
+      defaultExpandAll: props.defaultExpandAll,
+      checkStrictly: props.checkStrictly,
+    });
+  };
+
+  // 组件挂载时立即初始化
+  initTreeRef();
+
+  /** 切换节点展开/收起，并触发 Vue 响应式更新 */
+  const handleToggleExpand = (node: TreeNodeData, e: MouseEvent) => {
+    e.stopPropagation();
+    treeRef.value?.toggleExpand(node);
+    event.triggerTree();
+  };
+
+  /** 切换节点 checkbox 选中状态，并触发 Vue 响应式更新 */
+  const handleToggleChecked = (node: TreeNodeData, checked: boolean) => {
+    treeRef.value?.setNodeCheckbox(node, checked);
+    event.triggerTree();
+  };
+
+  /** 根据 key 数组获取节点列表（透传给 MTreeNode 使用） */
+  const getNodesByKeys = (keys: TreeNodeData['key'][]): TreeNodeData[] => {
+    return treeRef.value!.getTreeData(keys);
+  };
+
+  return {
+    treeRef,
+    getNodesByKeys,
+    handleToggleExpand,
+    handleToggleChecked,
+    initTreeRef,
+  };
+};

package/components/message/confirm/api.ts

@@ -0,0 +1,21 @@
+/**
+ * @description confirm runtime props 定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO } from '../../types/props';
+import { ConfirmProps } from './props';
+
+export const props: MCOPO<ConfirmProps> = {
+  visible: { type: Boolean, default: false },
+  mask: { type: Object, default: () => ({ show: true, clickClose: false }) },
+  teleport: { type: Object, default: () => ({ to: 'body' }) },
+  content: { type: String, default: '' },
+  confirmText: { type: String, default: '确定' },
+  cancelText: { type: String, default: '取消' },
+  title: { type: String, default: undefined },
+  loading: { type: Boolean, default: false },
+};

package/components/message/confirm/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @description confirm core 导出
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { props } from './api';
+
+export const ConfirmCore = {
+  props,
+};
+
+export type { ConfirmProps } from './props';

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

@@ -0,0 +1,69 @@
+/**
+ * @description confirm props 类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import type { ModelMask } from '../../../types/common/model.d.ts';
+import type { MTeleportProps } from '../../../types/common/common.d.ts';
+
+export declare type ConfirmProps = {
+  /**
+   * @description confirm mask option
+   *              确认框背景配置
+   * @type ModelMask
+   * @default { show: true, clickClose: false }
+   */
+  mask?: ModelMask;
+  /**
+   * @description confirm teleport
+   *              确认框传送目标
+   * @type MTeleportProps
+   * @default { to: 'body' }
+   */
+  teleport?: MTeleportProps;
+  /**
+   * @description confirm content
+   *              确认框内容
+   * @type string
+   * @default ''
+   */
+  content?: string;
+  /**
+   * @description confirm button text
+   *              确认按钮文字
+   * @type string
+   * @default '确定'
+   */
+  confirmText?: string;
+  /**
+   * @description cancel button text
+   *              取消按钮文字
+   * @type string
+   * @default '取消'
+   */
+  cancelText?: string;
+  /**
+   * @description confirm dialog visible
+   *              确认框是否显示（由 composable 内部管理）
+   * @type boolean
+   * @default false
+   */
+  visible?: boolean;
+  /**
+   * @description confirm title
+   *              确认框标题，传入时渲染标题栏
+   * @type string
+   * @default undefined
+   */
+  title?: string;
+  /**
+   * @description confirm button loading state
+   *              确认按钮 loading 状态，loading 时禁用按钮并显示 spinner
+   * @type boolean
+   * @default false
+   */
+  loading?: boolean;
+};

package/components/message/dialog/api.ts

@@ -0,0 +1,20 @@
+/**
+ * @description dialog runtime props 定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { DialogProps } from './props';
+
+export const props: MCOPO<DialogProps> = {
+  visible: { type: Boolean, default: false },
+  mask: { type: Object, default: () => ({ show: true, clickClose: true }) },
+  closeBtn: { type: Boolean, default: true },
+  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/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @description dialog core 导出
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { props } from './api';
+
+export const DialogCore = {
+  props,
+};
+
+export type { DialogProps } from './props';

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

@@ -0,0 +1,62 @@
+/**
+ * @description dialog props 类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import type { MTeleportProps } from '../../../types/common/common.d.ts';
+import type { ModelMask } from '../../../types/common/model.d.ts';
+
+export declare type DialogProps = {
+  /**
+   * @description dialog visible value
+   *              弹窗是否显示
+   * @type boolean
+   * @default false
+   */
+  visible?: boolean;
+  /**
+   * @description dialog mask option
+   *              弹窗遮罩配置
+   * @type ModelMask
+   * @default { show: true, clickClose: true }
+   */
+  mask?: ModelMask;
+  /**
+   * @description close button visible
+   *              是否显示关闭按钮
+   * @type boolean
+   * @default true
+   */
+  closeBtn?: boolean;
+  /**
+   * @description dialog teleport
+   *              弹窗传送目标
+   * @type MTeleportProps
+   * @default { to: 'body' }
+   */
+  teleport?: MTeleportProps;
+  /**
+   * @description dialog title
+   *              弹窗标题，传入时渲染标题栏
+   * @type string
+   * @default undefined
+   */
+  title?: string;
+  /**
+   * @description dialog width
+   *              弹窗宽度，支持 px / % 等合法 CSS 宽度值
+   * @type string
+   * @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

@@ -0,0 +1,33 @@
+/**
+ * @description drawer api
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { DrawerProps } from './props';
+import type { ModelMask } from '../../../types/common/model.d.ts';
+import type { MTeleportProps } from '../../../types/common/common.d.ts';
+
+export const props: MCOPO<DrawerProps> = {
+  visible: { type: Boolean, default: false },
+  mask: {
+    type: Object as MPropType<ModelMask>,
+    default: () => ({ show: true, clickClose: true }),
+  },
+  drawerClass: { type: Array, default: () => [] },
+  direction: {
+    type: String as MPropType<'top' | 'right' | 'bottom' | 'left'>,
+    default: 'right',
+  },
+  teleport: {
+    type: Object as MPropType<MTeleportProps>,
+    default: () => ({ to: 'body' }),
+  },
+  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/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @description drawer core 导出
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { props } from './api';
+
+export const DrawerCore = {
+  props,
+};
+
+export type { DrawerProps } from './props';