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

package/components/template/table/useTable.ts

@@ -0,0 +1,138 @@
+/**
+ * @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] && data[i][param]) {
+        return data[i][param];
+      }
+      return '';
+    };
+
+    /** 向每行的 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,18 @@
+/**
+ * @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';
+export { useVirtualList } from './useVirtualList';

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

package/components/template/virtualList/useVirtualList.ts

@@ -0,0 +1,237 @@
+/**
+ * @description 虚拟列表核心 hook（sentinel 方案）
+ * @author 阿怪
+ * @date 2026/2/25 14:00
+ * @version v3.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 基于 sentinel 哨兵元素 + scrollTop 绝对定位
+ * 不依赖状态机连续性，快速滚动也能正确定位
+ */
+import { computed, nextTick, onMounted, ref, watch, toRef, onBeforeUnmount } from 'vue';
+import { VirtualListProps } from './props';
+import { createHeightCache } from '../../../compositions/virtualList/useHeightCache';
+import { useSentinelObserver } from '../../../compositions/virtualList/useSentinelObserver';
+
+export interface UseVirtualListOptions<T> {
+  props: VirtualListProps<T>;
+  /** 触底事件 */
+  onReachBottom?: () => void;
+}
+
+export function useVirtualList<T>(options: UseVirtualListOptions<T>) {
+  const { props, onReachBottom } = options;
+
+  const containerRef = ref<HTMLElement | null>(null);
+  const wrapperRef = ref<HTMLElement | null>(null);
+  const topSentinelRef = ref<HTMLElement | null>(null);
+  const bottomSentinelRef = ref<HTMLElement | null>(null);
+
+  const listRef = toRef(() => props.list ?? []);
+  const estimatedHeight = props.estimatedHeight ?? 40;
+  const overScan = props.overScan ?? 1;
+
+  // 高度缓存
+  const heightCache = createHeightCache(listRef.value.length, estimatedHeight);
+
+  // 当前渲染范围
+  const renderFrom = ref(0);
+  const renderEnd = ref(0);
+
+  // spacer 总高度
+  const totalHeight = ref(0);
+  // wrapper 偏移
+  const offsetY = ref(0);
+
+  /** 根据 scrollTop 计算渲染范围 */
+  const calcRange = () => {
+    const container = containerRef.value;
+    if (!container) return;
+
+    const list = listRef.value;
+    const total = list.length;
+    if (total === 0) {
+      renderFrom.value = 0;
+      renderEnd.value = 0;
+      totalHeight.value = 0;
+      offsetY.value = 0;
+      return;
+    }
+
+    const scrollTop = container.scrollTop;
+    const containerHeight = container.clientHeight;
+
+    // 用 scrollTop 直接定位起始索引
+    const startIndex = heightCache.findIndex(scrollTop);
+    // 计算可见数量
+    let visibleEnd = startIndex;
+    let accHeight = 0;
+    while (visibleEnd < total && accHeight < containerHeight) {
+      accHeight += heightCache.getHeight(visibleEnd);
+      visibleEnd++;
+    }
+
+    const visibleCount = visibleEnd - startIndex;
+    const overScanCount = Math.max(1, Math.floor(visibleCount * overScan));
+
+    // 加上 overScan 缓冲区
+    const from = Math.max(0, startIndex - overScanCount);
+    const end = Math.min(total, visibleEnd + overScanCount);
+
+    renderFrom.value = from;
+    renderEnd.value = end;
+    totalHeight.value = heightCache.getTotalHeight();
+    offsetY.value = heightCache.getOffset(from);
+  };
+
+  /** 当前要渲染的数据切片 */
+  const displayList = computed(() => {
+    const list = listRef.value;
+    return list.slice(renderFrom.value, renderEnd.value)
+      .map((d, i) => ({ data: d as T, index: i + renderFrom.value }));
+  });
+
+  /**
+   * 测量已渲染项的实际高度并更新缓存
+   * 同时进行 scrollTop 补偿：当上方元素的真实高度和预估不同时，
+   * 修正 scrollTop 使视觉位置不跳动
+   */
+  const measureItems = () => {
+    const wrapper = wrapperRef.value;
+    const container = containerRef.value;
+    if (!wrapper || !container) return;
+
+    const scrollTop = container.scrollTop;
+    // 记录当前视口第一个可见项的旧偏移
+    const firstVisibleIndex = heightCache.findIndex(scrollTop);
+    const oldOffset = heightCache.getOffset(firstVisibleIndex);
+
+    const children = wrapper.children;
+    let hasChange = false;
+    // 跳过 top sentinel（第一个子元素）
+    for (let i = 1; i < children.length - 1; i++) {
+      const child = children[i];
+      const index = renderFrom.value + (i - 1); // -1 因为跳过 top sentinel
+      const height = child.getBoundingClientRect().height;
+      if (height > 0) {
+        const oldHeight = heightCache.getHeight(index);
+        if (Math.abs(oldHeight - height) > 0.5) {
+          heightCache.update(index, height);
+          hasChange = true;
+        }
+      }
+    }
+
+    if (hasChange) {
+      // 计算补偿量：上方高度变化导致的偏移差
+      const newOffset = heightCache.getOffset(firstVisibleIndex);
+      const delta = newOffset - oldOffset;
+      if (Math.abs(delta) > 0.5) {
+        container.scrollTop = scrollTop + delta;
+      }
+    }
+
+    // 更新总高度
+    totalHeight.value = heightCache.getTotalHeight();
+  };
+
+  const update = () => {
+    measureItems();
+    calcRange();
+    // 范围变化后，下一帧再测量一次（新渲染的元素）
+    nextTick(() => {
+      measureItems();
+    });
+  };
+
+  // sentinel observer
+  const { reobserve } = useSentinelObserver({
+    containerRef,
+    topSentinelRef,
+    bottomSentinelRef,
+    onUpdate: update,
+    onReachBottom,
+  });
+
+  // scroll 事件驱动：用 rAF 节流，保证滚动过程中持续更新渲染范围
+  let rafId: number | null = null;
+  let scrollHandler: (() => void) | undefined;
+  let scrollendHandler: (() => void) | undefined;
+
+  const setupScrollListener = () => {
+    const container = containerRef.value;
+    if (!container) return;
+
+    // 连续滚动时用 rAF 节流更新
+    scrollHandler = () => {
+      if (rafId !== null) return;
+      rafId = requestAnimationFrame(() => {
+        rafId = null;
+        calcRange();
+      });
+    };
+    container.addEventListener('scroll', scrollHandler, { passive: true });
+
+    // scrollend 做最终修正（测量 + 补偿）
+    scrollendHandler = () => {
+      measureItems();
+      calcRange();
+    };
+    container.addEventListener('scrollend', scrollendHandler);
+  };
+
+  const cleanupScrollListener = () => {
+    const container = containerRef.value;
+    if (container) {
+      if (scrollHandler) container.removeEventListener('scroll', scrollHandler);
+      if (scrollendHandler) container.removeEventListener('scrollend', scrollendHandler);
+    }
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+  };
+
+  // 初始化
+  onMounted(() => {
+    const list = listRef.value;
+    heightCache.reset(list.length);
+
+    // 初始渲染
+    calcRange();
+
+    nextTick(() => {
+      measureItems();
+      calcRange();
+      reobserve();
+      setupScrollListener();
+    });
+  });
+
+  // 响应 list 变化
+  watch(listRef, (newList) => {
+    heightCache.reset(newList.length);
+    if (containerRef.value) {
+      containerRef.value.scrollTop = 0;
+    }
+    calcRange();
+    nextTick(() => {
+      measureItems();
+      calcRange();
+      reobserve();
+    });
+  });
+
+  onBeforeUnmount(cleanupScrollListener);
+
+  return {
+    displayList,
+    containerRef,
+    wrapperRef,
+    topSentinelRef,
+    bottomSentinelRef,
+    totalHeight,
+    offsetY,
+  };
+}

package/components/types/hook.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @description
+ * @author 阿怪
+ * @date 2024/12/16 10:15
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { SlotsType } from '@vue/runtime-core';
+
+export type UseHookResult<Props, S extends SlotsType, Return> = Return;
+
+

package/components/types/props.d.ts

@@ -0,0 +1,52 @@
+/* eslint-disable */
+/**
+ * @description M Component Object Props Options
+ * @author 阿怪
+ * @date 2022/12/13 00:01
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ * M means Shuimo
+ */
+export declare type MPropOptions<T = any, D = T> = {
+  type?: MPropType<T> | true | null,
+  required: true,
+  default?: D | DefaultFactory<D> | null | undefined | object,
+  enum?: T[],
+}
+
+export declare type MPropOptionsWithDefault<T = any, D = T> = {
+  type?: MPropType<T> | true | null,
+  required?: false,
+  default: D | DefaultFactory<D> | null | undefined | object,
+  enum?: T[],
+}
+
+/**
+ * @description MComponentObjectPropsOptions
+ */
+export type MCOPO<P, OK = Required<Pick<P, OptionalKeys<P>>>> = {
+  [K in keyof OK]: MPropOptionsWithDefault<OK[K]>
+} & {
+  [K in keyof Pick<P, RequiredKeys<P>>]-?: MPropOptions<P[K]>
+}
+
+
+type DefaultFactory<T> = (props: Data) => T;
+
+type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T];
+
+type OptionalKeys<T> = Exclude<keyof T, RequiredKeys<T>>;
+
+type MPropConstructor<T = any> =
+  | { new(...args: any[]): T & {} }
+  | { (): T }
+  | MPropMethod<T>
+
+type MPropMethod<T, TConstructor = any> = [T] extends [
+      ((...args: any) => any) | undefined
+  ] // if is function with args, allowing non-required functions
+  ? { new(): TConstructor; (): T; readonly prototype: TConstructor } // Create Function like constructor
+  : never
+
+export type MPropType<T> = MPropConstructor<T> | MPropConstructor<T>[];

package/components/types/template.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @description
+ * @author 阿怪
+ * @date 2022/12/12 14:52
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { RenderFunction, SetupContext } from 'vue';
+import { MCOPO } from './props';
+
+type WithArray<T> = T | T[]; // todo fix this
+
+export type HTMLElementEvent<T extends HTMLElement> = Event & {
+  target: T;
+};
+
+type MVNodeRenderParams = {
+  if?: boolean,
+  show?: boolean,
+};
+
+interface ElementEventListener {
+  (event: HTMLElementEvent<any>): void;
+}
+
+export type MNodeProps = Record<string, WithArray<string | number | boolean> | ElementEventListener | Record<string, any>>;
+
+export declare type MNodeSlot = MVNodeRenderParams & {
+  props?: MNodeProps,
+};
+
+export declare type MNodeTemplate = {
+  type: string,
+  props?: MNodeProps,
+  children?: Record<string, MNodeTemplate>,
+  slots?: Map<string, MNodeSlot>,
+  innerText?: string[],
+  initProps?: (templateProps: MCOPO<any>, props: MNodeProps, filter?: string[]) => void,
+} & MVNodeRenderParams;
+
+
+export declare type MVNode = {
+  name: string,
+  template?: MNodeTemplate,
+  dom?: HTMLElement,
+  props?: MNodeTemplate['props'],
+  children?: Record<string, MVNode>,
+  slots?: MNodeTemplate['slots']
+};
+
+export declare type CustomElementParams = {
+  name: string,
+  style?: string,
+  template?: MNodeTemplate,
+  props?: MCOPO<any>
+};
+
+export declare type WCSetup<T = any> = (slot?: HTMLSlotElement) => (props: Readonly<T>, ctx: SetupContext) => RenderFunction;

package/compositions/common/defineCore.ts

@@ -0,0 +1,55 @@
+/* eslint-disable */
+/**
+ * @description A tool for normalizing grammatical structures
+ * @author 阿怪
+ * @date 2023/6/16 11:25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { Ref } from 'vue';
+
+type OptionsEmpty = undefined;
+
+
+type IsAllUndefined<T extends any[]> = T extends [infer H, ...infer R]
+  ? H extends undefined
+    ? IsAllUndefined<R>
+    : false
+  : true;
+
+interface OptionsNotEmpty<P, V, E> {
+  props: Required<P>;
+  value: { [K in keyof V]: Ref<V[K]>; };
+  event: E;
+}
+
+type CoreArguments = keyof OptionsNotEmpty<any, any, any>;
+type AnyArguments = {
+  [K in CoreArguments]?: any
+}
+
+type DefinedKeys<T extends AnyArguments> = { [K in keyof T]: T[K] extends undefined ? never : K }[keyof T];
+type UndefinedKeys<T extends AnyArguments> = Exclude<keyof CoreArguments, DefinedKeys<T>>;
+
+export type OptionsKeys<
+  A extends AnyArguments,
+  P, V, E,
+  DK extends string | number | symbol = DefinedKeys<A>,
+  UK extends string | number | symbol = UndefinedKeys<A>
+> = {
+  [K in DK & keyof OptionsNotEmpty<P, V, E>]: OptionsNotEmpty<P, V, E>[K];
+} & {
+  [K in UK & keyof OptionsNotEmpty<P, V, E>]-?: OptionsNotEmpty<P, V, E>[K];
+}
+
+export type Options<
+  K extends AnyArguments,
+  P = K['props'],
+  V = K['value'],
+  E = K['event'],
+> =
+  IsAllUndefined<[P, V, E]> extends true
+    ? OptionsEmpty
+    : OptionsKeys<K, P, V, E>;