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

package/components/template/table/__tests__/useTable.test.ts

@@ -0,0 +1,138 @@
+/**
+ * @description useTable 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { useTable } from '../useTable';
+
+describe('useTable', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+  const createRenders = () => ({
+    empty: 'EMPTY',
+    tbodyTr: (opt: any) => `TD:${opt.param}:${opt.data}`,
+    theadTh: (opt: any) => `TH:${opt.param}:${opt.label}`,
+    thead: (ths: string[]) => `THEAD:[${ths.join(',')}]`,
+    tbody: (trs: string[]) => `TBODY:[${trs.join(',')}]`,
+    tbodyTrs: (tds: string[], i: number) => `TR${i}:[${tds.join(',')}]`,
+    initSlot: () => undefined,
+  });
+
+  it('initTable 正确构建表头和表体', () => {
+    const { initTable } = useTable();
+    const columns = [
+      { props: { param: 'name', label: '姓名' } },
+      { props: { param: 'age', label: '年龄' } },
+    ];
+    const data = [
+      { name: '张三', age: 25 },
+      { name: '李四', age: 30 },
+    ];
+
+    const result = initTable(createRenders(), columns, data);
+
+    expect(result.thead).toBe('THEAD:[TH:name:姓名,TH:age:年龄]');
+    expect(result.tbody).toContain('TD:name:张三');
+    expect(result.tbody).toContain('TD:age:30');
+  });
+
+  it('数据为空时渲染 empty', () => {
+    const { initTable } = useTable();
+    const columns = [{ props: { param: 'name', label: '姓名' } }];
+
+    const result = initTable(createRenders(), columns, []);
+    expect(result.tbody).toBe('EMPTY');
+  });
+
+  it('列没有 props 时被过滤', () => {
+    const { initTable } = useTable();
+    const errorSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const columns = [
+      { props: { param: 'name', label: '姓名' } },
+      {}, // 无 props
+    ];
+    const data = [{ name: '张三' }];
+
+    const result = initTable(createRenders(), columns, data);
+    expect(result.thead).toBe('THEAD:[TH:name:姓名]');
+    expect(errorSpy).toHaveBeenCalled();
+  });
+
+  it('列宽 number 转换为 px', () => {
+    const { initTable } = useTable();
+    const renders = {
+      ...createRenders(),
+      theadTh: (opt: any) => `TH:${opt.style?.width}`,
+    };
+    const columns = [{ props: { param: 'name', label: '姓名', width: 200 } }];
+
+    const result = initTable(renders, columns, [{ name: 'test' }]);
+    expect(result.thead).toContain('200px');
+  });
+
+  it('列宽 string 直接使用', () => {
+    const { initTable } = useTable();
+    const renders = {
+      ...createRenders(),
+      theadTh: (opt: any) => `TH:${opt.style?.width}`,
+    };
+    const columns = [{ props: { param: 'name', label: '姓名', width: '50%' } }];
+
+    const result = initTable(renders, columns, [{ name: 'test' }]);
+    expect(result.thead).toContain('50%');
+  });
+
+  it('data 中缺少字段时返回空字符串', () => {
+    const { initTable } = useTable();
+    const columns = [{ props: { param: 'missing', label: '缺失' } }];
+    const data = [{ name: 'test' }];
+
+    const result = initTable(createRenders(), columns, data);
+    expect(result.tbody).toContain('TD:missing:');
+  });
+
+  it('initSlot 返回 slot 时传递给 tbodyTr', () => {
+    const { initTable } = useTable();
+    const bodySlot = () => 'custom';
+    const renders = {
+      ...createRenders(),
+      initSlot: () => ({ body: bodySlot, head: undefined }),
+      tbodyTr: (opt: any) => `TD:${opt.slot ? 'has-slot' : 'no-slot'}`,
+    };
+    const columns = [{ props: { param: 'name', label: '姓名' } }];
+    const data = [{ name: 'test' }];
+
+    const result = initTable(renders, columns, data);
+    expect(result.tbody).toContain('has-slot');
+  });
+
+  it('slotInfo 包含行数据和索引', () => {
+    const { initTable } = useTable();
+    let capturedSlotInfo: any;
+    const renders = {
+      ...createRenders(),
+      tbodyTr: (opt: any) => {
+        capturedSlotInfo = opt.slotInfo;
+        return 'TD';
+      },
+    };
+    const columns = [{ props: { param: 'name', label: '姓名' } }];
+    const data = [{ name: '张三' }];
+
+    initTable(renders, columns, data);
+    expect(capturedSlotInfo).toEqual({ data: { name: '张三' }, index: 0 });
+  });
+
+  it('error 输出带前缀的警告', () => {
+    const { error } = useTable();
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    error('test error');
+    expect(spy).toHaveBeenCalledWith('[水墨UI表格组件] test error');
+  });
+});

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

package/components/template/table/useTable.ts

@@ -0,0 +1,136 @@
+/**
+ * @description core table hook
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+
+export function useTable() {
+
+  // 使用 console.warn 替代 Printer 依赖
+  const error = (msg: string) => console.warn(`[水墨UI表格组件] ${msg}`);
+
+  type SlotRender = any | undefined;
+  type StyleType = { width?: string } | undefined;
+
+  const initTable = <T>(renders: {
+    /** 数据为空时渲染的内容 */
+    empty: T,
+    /** 渲染单个 td 单元格 */
+    tbodyTr: (option: {
+      data: any | string,
+      param: string,
+      slot?: SlotRender,
+      style?: StyleType,
+      slotInfo?: { data: any, index: number }
+    }) => T,
+    /** 渲染单个 th 表头单元格 */
+    theadTh: (option: {
+      param?: string,
+      label?: string,
+      slot?: SlotRender,
+      style?: StyleType
+    }) => T,
+    /** 渲染整个 thead */
+    thead: (ths: T[]) => T,
+    /** 渲染整个 tbody */
+    tbody: (trs: T[]) => T,
+    /** 渲染单行 tr */
+    tbodyTrs: (tds: T[], i: number) => T,
+    /** 从 tableColumn VNode 中提取 body/head 插槽 */
+    initSlot: (tableColumn: any) => { body: SlotRender, head: SlotRender } | undefined,
+  }, columns: Array<any>, data: any[]) => {
+    // 每行对应的 td 列表，按行索引分组
+    const tbodyTrList: T[][] = [];
+    data.forEach(() => { tbodyTrList.push([]); });
+
+    /** 从 data[i] 中安全取值 */
+    const getData = (i: number, param: string) => {
+      if (data[i] == null) return '';
+      return data[i][param] ?? '';
+    };
+
+    /** 向每行的 td 列表中追加一列 */
+    const pushTd = (param: string | undefined, bodySlot: SlotRender, style: StyleType) => {
+      if (!param && !bodySlot) {
+        error('param is undefined, column without param or slot will be ignored!');
+        return;
+      }
+      tbodyTrList.forEach((t, i) => {
+        t.push(renders.tbodyTr({
+          data: param ? getData(i, param) : '',
+          style,
+          param: param ?? '',
+          slot: bodySlot,
+          slotInfo: {
+            data: data[i],
+            index: i,
+          },
+        }));
+      });
+    };
+
+    /** 将列宽 prop 转换为 style 对象 */
+    const getStyle = (options?: { width?: string | number }): StyleType => {
+      if (!options || !options.width) {
+        return {};
+      }
+      const numberWidth = Number(options.width);
+      if (!isNaN(numberWidth)) {
+        return { width: numberWidth + 'px' };
+      }
+      return { width: options.width as string };
+    };
+
+    /**
+     * 初始化表头，同时将每列对应的 td 推入 tbodyTrList
+     */
+    const initTHead = () => {
+      const ths = (columns ?? []).filter(column => {
+        if (!column.props) {
+          error('column.props is undefined, column without param will be ignored!');
+          return false;
+        }
+        return true;
+      }).map(column => {
+        const slots = renders.initSlot(column);
+        let bodySlot: SlotRender | undefined;
+        let headSlot: SlotRender | undefined;
+        const style = getStyle(column.props);
+        if (slots) {
+          bodySlot = slots.body;
+          headSlot = slots.head;
+        }
+        pushTd(column.props.param, bodySlot, style);
+
+        return renders.theadTh({
+          label: column.props.label,
+          param: column.props.param,
+          slot: headSlot,
+          style,
+        });
+      });
+      return renders.thead(ths);
+    };
+
+    const thead = initTHead();
+    const tbody = tbodyTrList.length > 0
+      ? renders.tbody(tbodyTrList.map((tds, i) => renders.tbodyTrs(tds, i)))
+      : renders.empty;
+
+    return {
+      thead,
+      tbody,
+    };
+  };
+
+
+  return {
+    initTable,
+    error,
+  };
+
+}

package/components/template/tableColumn/api.ts

@@ -0,0 +1,17 @@
+/**
+ * @description table column api
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO } from '../../types/props';
+import { TableColumnProps } from './props';
+
+
+export const props: MCOPO<TableColumnProps> = {
+  width: { type: String, default: '' },
+  param: { type: String, default: '' },
+  label: { type: String, default: '' },
+};

package/components/template/tableColumn/index.ts

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

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

@@ -0,0 +1,32 @@
+/**
+ * @description tableColumn 组件类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type TableColumnProps = {
+  /**
+   * @description table column width
+   *              列宽
+   * @type string
+   * @default ''
+   */
+  width?: string;
+  /**
+   * @description table column param
+   *              列对应的参数字段名
+   * @type string
+   * @default ''
+   */
+  param?: string;
+  /**
+   * @description table column label
+   *              列标题
+   * @type string
+   * @default ''
+   */
+  label?: string;
+};

package/components/template/virtualList/api.ts

@@ -0,0 +1,16 @@
+/**
+ * @description 虚拟列表运行时 props
+ * @author 阿怪
+ * @date 2026/2/25 13:30
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO } from '../../types/props';
+import { VirtualListProps } from './props';
+
+export const props: MCOPO<VirtualListProps> = {
+  list: { type: Array, default: () => [] },
+  estimatedHeight: { type: Number, default: 40 },
+  overScan: { type: Number, default: 1 },
+};

package/components/template/virtualList/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @description 虚拟列表 core 导出
+ * @author 阿怪
+ * @date 2026/2/25 14:00
+ * @version v2.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { props } from './api';
+import { useVirtualList } from './useVirtualList';
+
+export const VirtualListCore = {
+  props,
+  useVirtualList,
+};
+
+export type { VirtualListProps } from './props';

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

@@ -0,0 +1,25 @@
+/**
+ * @description 虚拟列表 props 类型定义
+ * @author 阿怪
+ * @date 2026/2/25 13:30
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type VirtualListProps<T = any> = {
+  /**
+   * @description 列表数据
+   */
+  list?: Array<T>;
+  /**
+   * @description 预估行高，用于初始计算可见数量，避免依赖首次全量渲染
+   * @default 40
+   */
+  estimatedHeight?: number;
+  /**
+   * @description 过扫描系数，渲染可视区域外的额外行数倍数
+   * @default 1
+   */
+  overScan?: number;
+};