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

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?: (...args: any[]) => 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/__tests__/usePagination.test.ts

@@ -0,0 +1,138 @@
+/**
+ * @description usePagination 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import { ref } from 'vue';
+import { usePagination, type Pager } from '../usePagination';
+
+/** 提取页码列表中的值 */
+const values = (list: Pager[]) => list.map(p => p.value);
+/** 提取页码列表中当前页标记 */
+const currentFlags = (list: Pager[]) => list.filter(p => p.isCurrent).map(p => p.value);
+
+describe('usePagination', () => {
+  describe('getPageBtnLength', () => {
+    it('计算总页数', () => {
+      const current = ref(1);
+      const { getPageBtnLength } = usePagination({ total: 100, pageSize: 10 }, current);
+      expect(getPageBtnLength()).toBe(10);
+    });
+
+    it('向上取整', () => {
+      const current = ref(1);
+      const { getPageBtnLength } = usePagination({ total: 101, pageSize: 10 }, current);
+      expect(getPageBtnLength()).toBe(11);
+    });
+
+    it('默认 total=0, pageSize=10', () => {
+      const current = ref(1);
+      const { getPageBtnLength } = usePagination({}, current);
+      expect(getPageBtnLength()).toBe(0);
+    });
+  });
+
+  describe('getPageNumList', () => {
+    it('只有一页时返回 [1]', () => {
+      const current = ref(1);
+      const { getPageNumList } = usePagination({ total: 5, pageSize: 10 }, current);
+      const list = getPageNumList();
+      expect(values(list)).toEqual([1]);
+    });
+
+    it('总页数 <= maxPageBtn 时不折叠', () => {
+      const current = ref(1);
+      const { getPageNumList } = usePagination({
+        total: 80, pageSize: 10, maxPageBtn: 10,
+      }, current);
+      const list = getPageNumList();
+      expect(values(list)).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+    });
+
+    it('当前页靠左时右侧折叠', () => {
+      const current = ref(1);
+      const { getPageNumList } = usePagination({
+        total: 200, pageSize: 10, foldedMaxPageBtn: 5, maxPageBtn: 10,
+      }, current);
+      const list = getPageNumList();
+
+      // 应包含折叠符 "..."
+      expect(list.some(p => p.type === 'folded')).toBe(true);
+      // 最后一个应是尾页 20
+      expect(list[list.length - 1].value).toBe(20);
+      // isCurrent 标记正确
+      expect(currentFlags(list)).toEqual([1]);
+    });
+
+    it('当前页靠右时左侧折叠', () => {
+      const current = ref(20);
+      const { getPageNumList } = usePagination({
+        total: 200, pageSize: 10, foldedMaxPageBtn: 5, maxPageBtn: 10,
+      }, current);
+      const list = getPageNumList();
+
+      expect(list[0].value).toBe(1); // 首页
+      expect(list[1].type).toBe('folded'); // 左折叠
+      expect(currentFlags(list)).toEqual([20]);
+    });
+
+    it('当前页居中时两侧折叠', () => {
+      const current = ref(10);
+      const { getPageNumList } = usePagination({
+        total: 200, pageSize: 10, foldedMaxPageBtn: 5, maxPageBtn: 10,
+      }, current);
+      const list = getPageNumList();
+
+      expect(list[0].value).toBe(1); // 首页
+      expect(list[list.length - 1].value).toBe(20); // 尾页
+      // 两个折叠符
+      const foldedCount = list.filter(p => p.type === 'folded').length;
+      expect(foldedCount).toBe(2);
+      expect(currentFlags(list)).toEqual([10]);
+    });
+
+    it('showEdgePageNum=false 不显示首尾页', () => {
+      const current = ref(10);
+      const { getPageNumList } = usePagination({
+        total: 200, pageSize: 10, foldedMaxPageBtn: 5, maxPageBtn: 10, showEdgePageNum: false,
+      }, current);
+      const list = getPageNumList();
+
+      // 不应以 1 开头
+      expect(list[0].value).not.toBe(1);
+      expect(list[list.length - 1].value).not.toBe(20);
+    });
+
+    it('折叠符的 jump 值正确', () => {
+      const current = ref(10);
+      const { getPageNumList } = usePagination({
+        total: 200, pageSize: 10, foldedMaxPageBtn: 5, maxPageBtn: 10,
+      }, current);
+      const list = getPageNumList();
+
+      const foldedPagers = list.filter(p => p.type === 'folded');
+      // 每个折叠符都应有 jump 值
+      foldedPagers.forEach(p => {
+        expect(p.jump).toBeGreaterThan(0);
+      });
+    });
+
+    it('isCurrent 标记正确跟随 currentValue', () => {
+      const current = ref(5);
+      const { getPageNumList } = usePagination({
+        total: 80, pageSize: 10,
+      }, current);
+      const list = getPageNumList();
+
+      expect(currentFlags(list)).toEqual([5]);
+
+      current.value = 3;
+      const list2 = getPageNumList();
+      expect(currentFlags(list2)).toEqual([3]);
+    });
+  });
+});

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,19 @@
+/**
+ * @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 } from './usePagination';
+export 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,
+  };
+}