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

package/components/template/menu/props.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @description menu props 类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+/**
+ * 菜单数据项
+ */
+export interface MenuData {
+  key: string | number;
+  label?: string;
+  value?: string | number;
+  children?: MenuData[];
+  disabled?: boolean;
+  [k: string]: unknown;
+}
+
+/**
+ * 菜单内部节点数据（带状态）
+ */
+export interface MenuNodeData extends MenuData {
+  /** 是否展开 */
+  expand?: boolean;
+  /** 是否激活 */
+  isActive?: boolean;
+  /** 是否选中（checkbox 模式） */
+  checked?: boolean;
+  /** 半选状态 */
+  indeterminate?: boolean;
+  /** 子节点 */
+  children?: MenuNodeData[];
+  /** 父节点引用 */
+  parent?: MenuNodeData | null;
+  /** 是否根节点 */
+  isRoot?: boolean;
+}
+
+/**
+ * 菜单字段映射配置
+ */
+export interface MenuConfig {
+  key: string;
+  label: string;
+  children: string;
+}
+
+export declare type MenuProps = {
+  /**
+   * @description 菜单数据
+   * @type MenuData[]
+   * @default []
+   */
+  data?: MenuData[];
+  /**
+   * @description 字段映射配置
+   * @type MenuConfig
+   * @default { key: 'key', label: 'label', children: 'children' }
+   */
+  config?: MenuConfig;
+  /**
+   * @description 是否使用 checkbox
+   * @type boolean
+   * @default false
+   */
+  checkbox?: boolean;
+  /**
+   * @description 默认展开所有节点
+   * @type boolean
+   * @default false
+   */
+  defaultExpandAll?: boolean;
+  /**
+   * @description 选中的 key 列表
+   * @type Array<string|number>
+   * @default []
+   */
+  checkedKeys?: Array<string | number>;
+  /**
+   * @description 菜单排列方向
+   * @type 'vertical' | 'horizontal'
+   * @default 'vertical'
+   */
+  mode?: 'vertical' | 'horizontal';
+  /**
+   * @description 当前激活的菜单项 key（v-model:active）
+   * @type string | number
+   */
+  active?: string | number;
+};

package/components/template/menu/useMenu.ts

@@ -0,0 +1,155 @@
+/**
+ * @description menu 核心 composable，内建简化版树数据管理
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { shallowRef, triggerRef, ShallowRef } from 'vue';
+import { MenuData, MenuNodeData, MenuConfig, MenuProps } from './props';
+
+const DEFAULT_CONFIG: MenuConfig = { key: 'key', label: 'label', children: 'children' };
+
+/**
+ * 递归构建节点树，附加状态属性
+ */
+function buildNodes(
+  data: MenuData[],
+  config: MenuConfig,
+  nodeMap: Map<string | number, MenuNodeData>,
+  defaultExpandAll: boolean = false,
+  parent: MenuNodeData | null,
+): MenuNodeData[] {
+  return data.map(item => {
+    const key = item[config.key] as string | number;
+    const childrenKey = config.children;
+    const node: MenuNodeData = {
+      ...item,
+      expand: defaultExpandAll,
+      isActive: false,
+      checked: false,
+      indeterminate: false,
+      parent,
+      isRoot: !parent,
+    };
+    nodeMap.set(key, node);
+
+    const rawChildren = item[childrenKey];
+    if (Array.isArray(rawChildren) && rawChildren.length > 0) {
+      node.children = buildNodes(
+        rawChildren as MenuData[],
+        config,
+        nodeMap,
+        defaultExpandAll,
+        node,
+      );
+    }
+
+    return node;
+  });
+}
+
+export function useMenu(props: MenuProps, emit?: (event: string, ...args: unknown[]) => void) {
+  const config: MenuConfig = { ...DEFAULT_CONFIG, ...props.config };
+  const nodeMap = new Map<string | number, MenuNodeData>();
+  const nodesRef: ShallowRef<MenuNodeData[]> = shallowRef([]);
+
+  /**
+   * 将原始 MenuData[] 转换为带状态的 MenuNodeData[]
+   * 供初始化或 data prop 变更时调用
+   */
+  const initNodes = (data: MenuData[] = []) => {
+    nodeMap.clear();
+    nodesRef.value = buildNodes(data, config, nodeMap, props.defaultExpandAll ?? false, null);
+
+    // 处理外部传入的 checkedKeys
+    if (props.checkedKeys?.length) {
+      props.checkedKeys.forEach(key => {
+        const node = nodeMap.get(key);
+        if (node) {
+          node.checked = true;
+        }
+      });
+    }
+
+    triggerRef(nodesRef);
+  };
+
+  // 首次初始化
+  initNodes(props.data ?? []);
+
+  // 受控模式：根据外部 active prop 初始化激活状态
+  if (props.active !== undefined) {
+    const activeNode = nodeMap.get(props.active);
+    if (activeNode) {
+      activeNode.isActive = true;
+    }
+  }
+
+  /**
+   * 切换节点展开/收起状态
+   */
+  const toggleExpand = (node: MenuNodeData) => {
+    node.expand = !node.expand;
+    triggerRef(nodesRef);
+  };
+
+  /**
+   * 设置节点为激活状态，同时取消其他节点的激活，并触发 update:active
+   */
+  const setActive = (node: MenuNodeData) => {
+    nodeMap.forEach(n => {
+      n.isActive = false;
+    });
+    node.isActive = true;
+    triggerRef(nodesRef);
+    if (emit) {
+      const key = node[config.key] as string | number;
+      emit('update:active', key);
+    }
+  };
+
+  /**
+   * 切换 checkbox 选中状态
+   */
+  const toggleChecked = (node: MenuNodeData, checked: boolean) => {
+    node.checked = checked;
+    node.indeterminate = false;
+    triggerRef(nodesRef);
+  };
+
+  /**
+   * 获取当前所有选中节点的 key 列表
+   */
+  const getCheckedKeys = (): (string | number)[] => {
+    const keys: (string | number)[] = [];
+    nodeMap.forEach((node, key) => {
+      if (node.checked && !node.indeterminate) {
+        keys.push(key);
+      }
+    });
+    return keys;
+  };
+
+  /**
+   * 根据 key 列表批量获取节点
+   */
+  const getNodesByKeys = (keys: (string | number)[]): MenuNodeData[] => {
+    return keys
+      .map(key => nodeMap.get(key))
+      .filter((n): n is MenuNodeData => n !== undefined);
+  };
+
+  return {
+    nodesRef,
+    nodeMap,
+    initNodes,
+    toggleExpand,
+    setActive,
+    toggleChecked,
+    getCheckedKeys,
+    getNodesByKeys,
+    config,
+  };
+}

package/components/template/pagination/api.ts

@@ -0,0 +1,22 @@
+/**
+ * @description pagination 运行时 props
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO } from '../../types/props';
+import { PaginationProps } from './props';
+
+export const props: MCOPO<PaginationProps> = {
+  total: { type: Number, default: 0 },
+  modelValue: { type: Number, default: undefined },
+  defaultCurrent: { type: Number, default: 1 },
+  pageSize: { type: Number, default: 10 },
+  pageSizes: { type: Array, default: () => [10, 20, 30, 40, 50, 100] },
+  layout: { type: String, default: 'prev, pager, next, total' },
+  foldedMaxPageBtn: { type: Number, default: 5 },
+  maxPageBtn: { type: Number, default: 10 },
+  showEdgePageNum: { type: Boolean, default: true },
+};

package/components/template/pagination/index.ts

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

package/components/template/pagination/props.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @description pagination props 类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type PaginationProps = {
+  /**
+   * @description 分页总条数
+   * @type number
+   * @default 0
+   */
+  total?: number;
+  /**
+   * @description 当前页（受控）
+   * @type number
+   * @default undefined
+   */
+  modelValue?: number;
+  /**
+   * @description 默认当前页（非受控初始值）
+   * @type number
+   * @default 1
+   */
+  defaultCurrent?: number;
+  /**
+   * @description 每页数量
+   * @type number
+   * @default 10
+   */
+  pageSize?: number;
+  /**
+   * @description 可选每页数量列表
+   * @type number[]
+   * @default [10, 20, 30, 40, 50, 100]
+   */
+  pageSizes?: number[];
+  /**
+   * @description 组件布局，逗号分隔，可选值：prev, pager, next, total
+   * @type string
+   * @default 'prev, pager, next, total'
+   */
+  layout?: string;
+  /**
+   * @description 折叠时最多显示的页码按钮数（必须为奇数，偶数自动 +1）
+   * @type number | null
+   * @default 5
+   */
+  foldedMaxPageBtn?: number | null;
+  /**
+   * @description 不折叠时最大显示页数，超过后启用折叠逻辑
+   * @type number | null
+   * @default 10
+   */
+  maxPageBtn?: number | null;
+  /**
+   * @description 是否显示首尾边缘页码
+   * @type boolean
+   * @default true
+   */
+  showEdgePageNum?: boolean;
+};

package/components/template/pagination/usePagination.ts

@@ -0,0 +1,186 @@
+/**
+ * @description pagination 核心逻辑（分页按钮列表计算）
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { Ref } from 'vue';
+import { PaginationProps } from './props';
+
+
+/**
+ * 由于靠近按钮时需要优雅的交互，按钮需要对称渲染，因此折叠区域数量必须为奇数
+ */
+const oddNum = (num: number) => {
+  return num % 2 === 0 ? num + 1 : num;
+};
+
+/**
+ * 页码按钮描述类型
+ * - type 为 'number' 时表示普通页码按钮
+ * - type 为 'folded' 时表示折叠省略号，jump 为点击后跳转的目标页
+ */
+export type Pager = {
+  value: number;
+  type: 'number';
+  isCurrent: boolean;
+  jump?: number;
+} | {
+  value: string;
+  type: 'folded';
+  isCurrent: false;
+  jump: number;
+};
+
+/**
+ * 分页核心 hook
+ * @param props 分页组件 props（需包含 total / pageSize / foldedMaxPageBtn / maxPageBtn / showEdgePageNum）
+ * @param currentValue 当前页的响应式引用，由调用方维护
+ */
+export function usePagination(props: PaginationProps, currentValue: Ref<number>) {
+  /**
+   * 计算总页数
+   */
+  const getPageBtnLength = () => {
+    const total = props.total ?? 0;
+    const pageSize = props.pageSize ?? 10;
+    return Math.ceil(total / pageSize);
+  };
+
+  /**
+   * 构造普通页码 Pager 对象
+   */
+  const toPager = (value: number | string, config?: Partial<Omit<Pager, 'value'>>): Pager => {
+    return {
+      value,
+      type: config?.type ?? 'number',
+      isCurrent: currentValue.value === value,
+      jump: config?.jump ?? (value as number),
+    } as Pager;
+  };
+
+  /**
+   * 构造折叠省略号 Pager 对象
+   */
+  const toFoldedPager = (jump: number): Pager => {
+    return toPager('...', { type: 'folded', jump });
+  };
+
+  /**
+   * 生成从 start 开始、长度为 length 的连续页码列表
+   */
+  const getPageNumListRange = (start: number, length: number): Pager[] => {
+    return Array.from({ length }, (_, i) => toPager(i + start));
+  };
+
+  /**
+   * 生成完整的页码按钮列表，包含折叠逻辑
+   *
+   * 折叠规则：
+   * - 总页数 ≤ 1 页时：直接返回 [1]
+   * - 总页数 ≤ maxPageBtn 或 foldedMaxPageBtn ≥ 总页数-1 时：不折叠，显示全部
+   * - 当前页靠近左边缘：左侧全显 + 右侧折叠
+   * - 当前页靠近右边缘：左侧折叠 + 右侧全显
+   * - 当前页居中：两侧折叠
+   */
+  const getPageNumList = (): Pager[] => {
+    const pageBtnLength = getPageBtnLength();
+    const total = props.total ?? 0;
+    const pageSize = props.pageSize ?? 10;
+    const foldedMaxPageBtn = props.foldedMaxPageBtn ?? 5;
+    const maxPageBtn = props.maxPageBtn ?? 10;
+    const showEdgePageNum = props.showEdgePageNum ?? true;
+
+    // 只有一页时无需完整分页列表
+    if (total <= pageSize) {
+      return [toPager(1)];
+    }
+
+    // 总页数未超过 maxPageBtn，或 foldedMaxPageBtn 已足够覆盖大部分页数时不折叠
+    // eslint-disable-next-line @stylistic/no-mixed-operators
+    if (!maxPageBtn || pageBtnLength <= maxPageBtn || foldedMaxPageBtn && foldedMaxPageBtn >= pageBtnLength - 1) {
+      return getPageNumListRange(1, pageBtnLength);
+    }
+
+    // 折叠区域页码数必须为奇数，保证两侧对称
+    const foldedMaxPageBtnOdd = Math.max(oddNum(foldedMaxPageBtn ?? 5), 1);
+
+    const edgeConfig = {
+      // showEdgePageNum 时首尾各占 1 个槽位
+      length: showEdgePageNum ? 1 : 0,
+      // 右侧起始位置的偏移修正
+      rightStartSub: showEdgePageNum ? 0 : 1,
+    };
+
+    // 折叠区去掉首尾边缘页码后，剩余的中间页码数
+    const btnNumWithoutEdge = foldedMaxPageBtnOdd - (showEdgePageNum ? 2 : 0);
+    // 当前页两侧各显示的页码数
+    const pageEdge = (btnNumWithoutEdge - 1) / 2;
+
+    // 当前页 ≤ leftEdgeNum 时认为靠左，右侧折叠
+    const leftEdgeNum = pageEdge + 2;
+    // 当前页 ≥ rightEdgeNum 时认为靠右，左侧折叠
+    const rightEdgeNum = pageBtnLength - pageEdge - 1;
+    // 靠右时右侧连续区域的起始页
+    const rightStart = pageBtnLength - foldedMaxPageBtnOdd + 2 - edgeConfig.rightStartSub;
+
+    // ---- 靠左：左侧全显 + 右侧折叠 ----
+    if (currentValue.value <= leftEdgeNum) {
+      const numLength = foldedMaxPageBtnOdd - edgeConfig.length;
+      const res: Pager[] = [
+        ...getPageNumListRange(1, numLength),
+        toFoldedPager(1 + numLength),
+      ];
+      if (showEdgePageNum) {
+        res.push(toPager(pageBtnLength));
+      }
+      return res;
+    }
+
+    // ---- 靠右：左侧折叠 + 右侧全显 ----
+    if (currentValue.value >= rightEdgeNum) {
+      const res: Pager[] = [];
+      if (showEdgePageNum) {
+        res.push(toPager(1));
+      }
+      res.push(toFoldedPager(rightStart - 1), ...getPageNumListRange(rightStart, foldedMaxPageBtnOdd - edgeConfig.length));
+      return res;
+    }
+
+    // ---- 居中：两侧折叠 ----
+    const leftStart = currentValue.value - pageEdge;
+    const rightEnd = currentValue.value + pageEdge;
+
+    // 左侧折叠符：距离边缘超过 2 格时用省略号，否则直接显示相邻页码
+    const leftFolded = Math.abs(leftStart - 1) > 2 || !showEdgePageNum
+      ? toFoldedPager(leftStart - 1)
+      : toPager(showEdgePageNum ? 2 : 1);
+
+    // 右侧折叠符：同理
+    const rightFolded = Math.abs(rightEnd - pageBtnLength) > 2 || !showEdgePageNum
+      ? toFoldedPager(rightEnd + 1)
+      : toPager(showEdgePageNum ? pageBtnLength - 1 : pageBtnLength);
+
+    const res: Pager[] = [];
+    if (showEdgePageNum) {
+      res.push(toPager(1));
+    }
+    res.push(
+      leftFolded,
+      ...getPageNumListRange(leftStart, foldedMaxPageBtnOdd - edgeConfig.length * 2),
+      rightFolded,
+    );
+    if (showEdgePageNum) {
+      res.push(toPager(pageBtnLength));
+    }
+
+    return res;
+  };
+
+  return {
+    getPageNumList,
+    getPageBtnLength,
+  };
+}

package/components/template/table/api.ts

@@ -0,0 +1,18 @@
+/**
+ * @description table api
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO } from '../../types/props';
+import { TableProps } from './props';
+
+
+export const props: MCOPO<TableProps> = {
+  data: { type: Array, default: () => [] },
+  height: { type: String, default: null },
+  paramClass: { type: Boolean, default: false },
+  loading: { type: Boolean, default: false },
+};

package/components/template/table/index.ts

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

package/components/template/table/props.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @description table 组件类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type TableProps = {
+  /**
+   * @description table data
+   *              表格内容
+   * @type any[]
+   */
+  data?: Array<any>,
+  /**
+   * @description table height
+   *              表格高度
+   * @type string
+   */
+  height?: string | null,
+  /**
+   * @description auto add param class
+   *             自动添加key class
+   * @type boolean
+   * @default false
+   */
+  paramClass?: boolean,
+  /**
+   * @description 加载中状态，显示覆盖层
+   * @type boolean
+   * @default false
+   */
+  loading?: boolean
+};