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

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,19 @@
+/**
+ * @description dialog runtime props 定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO } 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 },
+};

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,55 @@
+/**
+ * @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;
+};

package/components/message/drawer/api.ts

@@ -0,0 +1,32 @@
+/**
+ * @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 },
+};

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

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

@@ -0,0 +1,73 @@
+/**
+ * @description drawer api type
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.1.0
+ *
+ * @name m-drawer
+ * @docDescription Headless drawer component.
+ *                 无样式抽屉组件。
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import type { ModelMask } from '../../../types/common/model.d.ts';
+import type { MTeleportProps } from '../../../types/common/common.d.ts';
+
+export declare type DrawerProps = {
+  /**
+   * @description drawer visible value
+   *              抽屉是否显示
+   * @type boolean
+   * @default false
+   */
+  visible?: boolean,
+  /**
+   * @description drawer mask option
+   *              抽屉背景配置
+   * @type ModelMask
+   * @default { show: true, clickClose: true }
+   */
+  mask?: ModelMask,
+  /**
+   * @description drawer class
+   *              抽屉扩展类名
+   * @type string[]
+   * @default []
+   */
+  drawerClass?: string[],
+  /**
+   * @description drawer direction
+   *              抽屉出现方向
+   * @type 'top' | 'right' | 'bottom' | 'left'
+   * @default 'right'
+   */
+  direction?: 'top' | 'right' | 'bottom' | 'left',
+  /**
+   * @description drawer teleport
+   *              抽屉传送配置
+   * @type MTeleportProps
+   * @default { to: 'body' }
+   */
+  teleport?: MTeleportProps,
+  /**
+   * @description drawer title
+   *              抽屉标题，传入时渲染标题栏
+   * @type string
+   * @default undefined
+   */
+  title?: string,
+  /**
+   * @description drawer width
+   *              抽屉宽度，适用于 left / right 方向
+   * @type string
+   * @default undefined
+   */
+  width?: string,
+  /**
+   * @description drawer height
+   *              抽屉高度，适用于 top / bottom 方向
+   * @type string
+   * @default undefined
+   */
+  height?: string,
+};

package/components/message/message/api.ts

@@ -0,0 +1,27 @@
+/**
+ * @description message runtime props 定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { MessageProps, MessageListProps, MessageType, MessageDirectionType } from './props';
+
+/**
+ * 单条消息组件的运行时 props
+ */
+export const messageProps: MCOPO<MessageProps> = {
+  content: { type: String, required: true },
+  type: { type: String as MPropType<MessageType>, default: 'info' },
+  duration: { type: Number, default: 3000 },
+  direction: { type: String as MPropType<MessageDirectionType>, default: 'top-right' },
+};
+
+/**
+ * 消息列表容器的运行时 props
+ */
+export const messageListProps: MCOPO<MessageListProps> = {
+  direction: { type: String as MPropType<MessageDirectionType>, default: 'top-right' },
+};

package/components/message/message/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @description message core 导出
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { messageProps, messageListProps } from './api';
+import { useMessageQueue } from './useMessage';
+
+export const MessageCore = {
+  messageProps,
+  messageListProps,
+  useMessageQueue,
+};
+
+export { useMessageQueue } from './useMessage';
+export type { MessageProps, MessageListProps, MessageType, MessageDirectionType } from './props';
+export type { MessageItem } from './useMessage';

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

@@ -0,0 +1,54 @@
+/**
+ * @description message 组件 props 类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+/**
+ * 消息类型枚举
+ */
+export type MessageType = 'success' | 'warning' | 'info' | 'error';
+
+/**
+ * 消息出现方位枚举
+ */
+export type MessageDirectionType = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center';
+
+/**
+ * 单条消息 props
+ */
+export declare type MessageProps = {
+  /**
+   * @description 消息类型
+   * @default 'info'
+   */
+  type?: MessageType;
+  /**
+   * @description 显示时长（毫秒），0 表示不自动关闭
+   * @default 3000
+   */
+  duration?: number;
+  /**
+   * @description 消息内容
+   */
+  content: string;
+  /**
+   * @description 消息出现的方位
+   * @default 'top-right'
+   */
+  direction?: MessageDirectionType;
+};
+
+/**
+ * 消息列表容器 props
+ */
+export declare type MessageListProps = {
+  /**
+   * @description 消息列表出现的方位
+   * @default 'top-right'
+   */
+  direction?: MessageDirectionType;
+};

package/components/message/message/useMessage.ts

@@ -0,0 +1,61 @@
+/**
+ * @description message 队列 composable
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { ref } from 'vue';
+import { MessageType } from './props';
+
+/**
+ * 消息队列中每一条消息的内部结构
+ */
+export interface MessageItem {
+  id: number;
+  type: MessageType;
+  content: string;
+  duration: number;
+}
+
+/**
+ * 消息队列 composable
+ * 管理消息的增删与自动关闭定时器
+ */
+export function useMessageQueue() {
+  const messages = ref<MessageItem[]>([]);
+  let nextId = 0;
+
+  /**
+   * 添加一条消息，duration > 0 时自动移除
+   */
+  const add = (props: { type?: MessageType; content: string; duration?: number }): number => {
+    const id = nextId++;
+    const item: MessageItem = {
+      id,
+      type: props.type ?? 'info',
+      content: props.content,
+      duration: props.duration ?? 3000,
+    };
+    messages.value.push(item);
+
+    if (item.duration > 0) {
+      setTimeout(() => remove(id), item.duration);
+    }
+
+    return id;
+  };
+
+  /**
+   * 按 id 移除一条消息
+   */
+  const remove = (id: number): void => {
+    const idx = messages.value.findIndex(m => m.id === id);
+    if (idx !== -1) {
+      messages.value.splice(idx, 1);
+    }
+  };
+
+  return { messages, add, remove };
+}

package/components/message/notification/api.ts

@@ -0,0 +1,23 @@
+/**
+ * @description notification runtime props 定义
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { NotificationProps, NotificationType, NotificationPosition } from './props';
+
+/**
+ * 单条通知运行时 props
+ */
+export const notificationProps: MCOPO<NotificationProps> = {
+  title: { type: String, required: true },
+  message: { type: String, default: '' },
+  type: { type: String as MPropType<NotificationType>, default: 'info' },
+  duration: { type: Number, default: 4500 },
+  position: { type: String as MPropType<NotificationPosition>, default: 'top-right' },
+  closable: { type: Boolean, default: true },
+  offset: { type: Number, default: 16 },
+};

package/components/message/notification/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @description notification core 导出
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { notificationProps } from './api';
+import { useNotificationQueue } from './useNotification';
+
+export const NotificationCore = {
+  notificationProps,
+  useNotificationQueue,
+};
+
+export { useNotificationQueue } from './useNotification';
+export type { NotificationProps, NotificationEvents, NotificationType, NotificationPosition } from './props';
+export type { NotificationItem, NotificationAddOptions } from './useNotification';