@kine-design/core 0.0.1-beta.5 → 0.0.1-beta.7

package/components/base/inputNumber/useInputNumber.ts

@@ -2,28 +2,66 @@
  * @description inputNumber composable
  * @author 阿怪
  * @date 2026/2/25 00:00
- * @version v1.1.0
+ * @version v1.2.0
  *
  * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * v1.2.0 changelog:
+ * - emit 类型保真：string 入 string 出，number 入 number 出；空值一律 emit null
+ * - 内部 currentValue 保留中间态（'-' / '0.' / ''），仅在 emit 时归一
  */
 import { ref, watch } from 'vue';
 import { InputNumberProps } from './props';
 import { HTMLElementEvent } from '../../types/template';
+import { type HookContext } from '../../types/hook';
 
 export type InputNumber = string | number | null;
 
-export function useInputNumber(props: Required<InputNumberProps>, ctx: any) {
+/** 用户输入中间态：不构成可 emit 的数字，emit null */
+const MID_STATES = new Set(['', '-', '.', '-.']);
+
+/**
+ * 把任意内部值归一为 number | null。
+ * 规则：
+ * - null/undefined/中间态 → null
+ * - 末尾小数点去掉（'1.' → '1'）
+ * - 非法 NaN → null
+ * - 其他 → Number(v)
+ */
+const normalize = (v: string | number | null | undefined): number | null => {
+  if (v === null || v === undefined) return null;
+  const s = String(v);
+  if (MID_STATES.has(s)) return null;
+  const cleaned = s.endsWith('.') ? s.slice(0, -1) : s;
+  const n = Number(cleaned);
+  return Number.isNaN(n) ? null : n;
+};
+
+export function useInputNumber(props: Required<InputNumberProps>, ctx: HookContext) {
   const currentValue = ref<string | number>(props.modelValue ?? '');
 
+  /**
+   * 按外部 modelValue 的当前 typeof 决定出参类型，保真 v-model 声明。
+   * - null/undefined → null
+   * - 外部当前是 string → emit String(n)
+   * - 否则 → emit n（默认 number）
+   */
+  const toEmitValue = (n: number | null): number | string | null => {
+    if (n === null) return null;
+    return typeof props.modelValue === 'string' ? String(n) : n;
+  };
+
   const updateInput = (oldVal: InputNumber) => {
-    ctx.emit('update:modelValue', currentValue.value);
-    ctx.emit('change', currentValue.value, oldVal);
+    const out = toEmitValue(normalize(currentValue.value));
+    ctx.emit('update:modelValue', out);
+    ctx.emit('change', out, oldVal);
   };
 
   const setCurrentValue = (newVal: string | number, e?: HTMLElementEvent<HTMLInputElement>) => {
     const oldVal = currentValue.value;
     const { min, max, precision } = props;
-    if (oldVal === newVal) {
+    // 字符串归一比较：'1' 和 1 视为同值，避免跨类型重复 emit；'-' vs '-' 也命中
+    if (String(oldVal) === String(newVal)) {
       return;
     } else if (+newVal >= +max) {
       // 超过最大值，截断到 max
@@ -75,18 +113,22 @@ export function useInputNumber(props: Required<InputNumberProps>, ctx: any) {
   };
 
   const handleInputBlur = () => {
+    const oldVal = currentValue.value;
     // blur 时清理末尾的负号
     if (currentValue.value === '-') {
       currentValue.value = '';
     } else if (currentValue.value === '-0') {
       currentValue.value = 0;
+    } else {
+      const str = String(currentValue.value);
+      // 清理末尾小数点
+      if (str.indexOf('.') === str.length - 1 && str.length > 0) {
+        currentValue.value = str.replace(/\.$/g, '');
+      }
     }
-    const oldVal = currentValue.value;
-    const str = String(currentValue.value);
-    // 清理末尾小数点
-    currentValue.value = str.indexOf('.') === str.length - 1
-      ? str.replace(/\.$/g, '')
-      : currentValue.value;
+    // blur 后内部归一到数字（避免 '1' 和 1 并存）
+    const n = normalize(currentValue.value);
+    currentValue.value = n === null ? '' : n;
     updateInput(oldVal);
   };
 

package/components/base/popover/usePopover.ts

@@ -10,6 +10,7 @@ import { Placement, PopperConfig, PositionStyle, usePopper } from '../../../comp
 import useClickAway from '../../../compositions/popper/useClickAway';
 import { PopoverProps } from './props';
 import { onBeforeUnmount, onMounted, ref, type Ref, shallowRef } from 'vue';
+import { type HookContext } from '../../types/hook';
 
 
 export type IPopper = ReturnType<typeof usePopper>;
@@ -103,7 +104,7 @@ export class PopoverImpl {
 }
 
 
-export function usePopover(props: Required<PopoverProps>, ctx: any) {
+export function usePopover(props: Required<PopoverProps>, ctx: HookContext) {
   const style = ref();
   const arrowStyle = ref();
   const placement = ref<Placement>(props.placement);
@@ -175,8 +176,8 @@ export function usePopover(props: Required<PopoverProps>, ctx: any) {
 
   onBeforeUnmount(() => {
     if (clickAwayInstance) {
-      const { onBeforeDestroy } = clickAwayInstance;
-      onBeforeDestroy();
+      const { onBeforeUnmount } = clickAwayInstance;
+      onBeforeUnmount();
     }
     instance?.destroy();
   });

package/components/base/rate/useRate.ts

@@ -7,9 +7,10 @@
  * 江湖的业务千篇一律，复杂的代码好几百行。
  */
 import { ref } from 'vue';
+import { type HookContext } from '../../types/hook';
 import { RateProps } from './props';
 
-export function useRate(props: Required<RateProps>, emit: (...args: any[]) => void) {
+export function useRate(props: Required<RateProps>, emit: HookContext['emit']) {
   // 悬停预览值，null 表示未悬停
   const hoverValue = ref<number | null>(null);
 

package/components/base/select/useSelect.ts

@@ -14,6 +14,7 @@
 import { computed, ref, watch, toRef, onBeforeUnmount } from 'vue';
 import { SelectProps } from './props';
 import { useSelectTools } from './useSelectTools';
+import { type HookContext } from '../../types/hook';
 
 export interface SelectOptionItem {
   /** 原始值 */
@@ -24,7 +25,7 @@ export interface SelectOptionItem {
   isSelected: boolean;
 }
 
-export function useSelect(props: SelectProps, ctx: any) {
+export function useSelect(props: SelectProps, ctx: HookContext) {
   const tools = useSelectTools(props);
   const optionsRef = toRef(() => props.options ?? []);
   const modelValueRef = toRef(() => props.modelValue);

package/components/base/slider/useSlider.ts

@@ -10,8 +10,9 @@ import { onMounted, ref } from 'vue';
 import { SliderProps } from './props';
 import { useElementSize } from '../../../compositions/common/useElementSize.ts';
 import useDrag, { DragOption, DragPosition, InteractEvent } from '../../../compositions/common/useDrag.ts';
+import { type HookContext } from '../../types/hook';
 
-export function useSlider(props: Required<SliderProps>, ctx: any) {
+export function useSlider(props: Required<SliderProps>, ctx: HookContext) {
   const sliderRef = ref<HTMLElement | null>(null);
   const sliderSize = useElementSize(sliderRef);
 

package/components/base/steps/__tests__/useSteps.test.ts

@@ -0,0 +1,46 @@
+/**
+ * @description resolveStepStatus 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import { resolveStepStatus, type StepsContext } from '../useSteps';
+
+const createCtx = (active: number): StepsContext => ({
+  active,
+  finishStatus: 'finish',
+  processStatus: 'process',
+  total: 4,
+  direction: 'horizontal',
+});
+
+describe('resolveStepStatus', () => {
+  it('显式状态优先', () => {
+    expect(resolveStepStatus(0, 'error', createCtx(2))).toBe('error');
+  });
+
+  it('index < active 返回 finishStatus', () => {
+    expect(resolveStepStatus(0, undefined, createCtx(2))).toBe('finish');
+    expect(resolveStepStatus(1, undefined, createCtx(2))).toBe('finish');
+  });
+
+  it('index === active 返回 processStatus', () => {
+    expect(resolveStepStatus(2, undefined, createCtx(2))).toBe('process');
+  });
+
+  it('index > active 返回 wait', () => {
+    expect(resolveStepStatus(3, undefined, createCtx(2))).toBe('wait');
+  });
+
+  it('active=0 时第一步为 process', () => {
+    expect(resolveStepStatus(0, undefined, createCtx(0))).toBe('process');
+  });
+
+  it('自定义 finishStatus=success', () => {
+    const ctx = { ...createCtx(2), finishStatus: 'success' as const };
+    expect(resolveStepStatus(0, undefined, ctx)).toBe('success');
+  });
+});

package/components/base/switch/useSwitch.tsx

@@ -9,6 +9,7 @@
 import { SwitchProps } from './props';
 import { computed, ref } from 'vue';
 import { isEmpty } from '../../../tools';
+import { type HookContext } from '../../types/hook';
 
 export const switchIsBoolean = (value: SwitchProps['modelValue']) => {
   return typeof value === 'boolean';
@@ -21,7 +22,7 @@ export const getIsActive = (value: SwitchProps['modelValue'], activeValue: Switc
 
 export function useSwitch<
   Props extends Record<string, any>,
->(props: Props, ctx: any) {
+>(props: Props, ctx: HookContext) {
   const activeValue = ref(props.activeValue);
   const inactiveValue = ref(props.inactiveValue);
   const { slots, emit } = ctx;

package/components/base/tabs/useTabs.ts

@@ -8,10 +8,11 @@
  */
 import { computed } from 'vue';
 import { TabsProps } from './props';
+import { type HookContext } from '../../types/hook';
 
 export function useTabs<
   Props extends Record<string, unknown>,
->(props: Props, ctx: any) {
+>(props: Props, ctx: HookContext) {
   const { emit } = ctx;
 
   /** 当前激活的标签名 */

package/components/base/timePicker/__tests__/useTimePicker.test.ts

@@ -0,0 +1,118 @@
+/**
+ * @description useTimePicker 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import { useTimePicker, generateColumn } from '../useTimePicker';
+
+describe('generateColumn', () => {
+  it('生成 24 小时列', () => {
+    expect(generateColumn(24, 1)).toHaveLength(24);
+  });
+
+  it('生成 60 分钟列，步进 5', () => {
+    expect(generateColumn(60, 5)).toEqual([0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55]);
+  });
+});
+
+describe('useTimePicker', () => {
+  const defaultProps = {
+    modelValue: undefined as string | undefined,
+    showSeconds: true,
+    format: '',
+    placeholder: '请选择时间...',
+    hourStep: 1,
+    minuteStep: 1,
+    secondStep: 1,
+  };
+
+  it('初始化空值显示 placeholder', () => {
+    const tp = useTimePicker({ ...defaultProps });
+    expect(tp.displayValue.value).toBe('请选择时间...');
+    expect(tp.spanClass.value).toContain('m-time-picker-placeholder');
+  });
+
+  it('初始化有效时间正确解析', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '14:30:00' });
+    expect(tp.timeRef.value.hours).toBe(14);
+    expect(tp.timeRef.value.minutes).toBe(30);
+    expect(tp.timeRef.value.seconds).toBe(0);
+    expect(tp.displayValue.value).toBe('14:30:00');
+  });
+
+  it('解析 HH:mm 格式', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '08:15' });
+    expect(tp.timeRef.value.hours).toBe(8);
+    expect(tp.timeRef.value.minutes).toBe(15);
+  });
+
+  it('updateTimeRef 更新状态', () => {
+    const tp = useTimePicker({ ...defaultProps });
+    tp.updateTimeRef('22:45:30');
+
+    expect(tp.timeRef.value.hours).toBe(22);
+    expect(tp.timeRef.value.minutes).toBe(45);
+    expect(tp.timeRef.value.seconds).toBe(30);
+  });
+
+  it('updateTimeRef 空值恢复 placeholder', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '10:00:00' });
+    tp.updateTimeRef('');
+    expect(tp.displayValue.value).toBe('请选择时间...');
+  });
+
+  it('selectHour 更新小时并刷新显示', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '10:00:00' });
+    tp.selectHour(15);
+
+    expect(tp.timeRef.value.hours).toBe(15);
+    expect(tp.displayValue.value).toContain('15');
+    expect(tp.spanClass.value).not.toContain('m-time-picker-placeholder');
+  });
+
+  it('selectMinute 更新分钟', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '10:00:00' });
+    tp.selectMinute(30);
+    expect(tp.timeRef.value.minutes).toBe(30);
+  });
+
+  it('selectSecond 更新秒', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '10:00:00' });
+    tp.selectSecond(45);
+    expect(tp.timeRef.value.seconds).toBe(45);
+  });
+
+  it('getValue 返回格式化时间', () => {
+    const tp = useTimePicker({ ...defaultProps, modelValue: '10:30:45' });
+    expect(tp.getValue()).toBe('10:30:45');
+  });
+
+  it('showSeconds=false 时格式为 HH:mm', () => {
+    const tp = useTimePicker({ ...defaultProps, showSeconds: false, modelValue: '10:30:45' });
+    expect(tp.getValue()).toBe('10:30');
+  });
+
+  it('自定义 format', () => {
+    const tp = useTimePicker({ ...defaultProps, format: 'HH-mm-ss', modelValue: '10:30:45' });
+    expect(tp.displayValue.value).toBe('10-30-45');
+  });
+
+  it('hoursColumn 按 hourStep 生成', () => {
+    const tp = useTimePicker({ ...defaultProps, hourStep: 2 });
+    expect(tp.hoursColumn.value).toEqual([0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22]);
+  });
+
+  it('minutesColumn 按 minuteStep 生成', () => {
+    const tp = useTimePicker({ ...defaultProps, minuteStep: 15 });
+    expect(tp.minutesColumn.value).toEqual([0, 15, 30, 45]);
+  });
+
+  it('secondsColumn 按 secondStep 生成', () => {
+    const tp = useTimePicker({ ...defaultProps, secondStep: 30 });
+    expect(tp.secondsColumn.value).toEqual([0, 30]);
+  });
+});

package/components/base/transfer/useTransfer.ts

@@ -14,8 +14,9 @@
  */
 import { computed, ref, toRef } from 'vue';
 import { TransferItem, TransferProps } from './props';
+import { type HookContext } from '../../types/hook';
 
-export function useTransfer(props: TransferProps, ctx: any) {
+export function useTransfer(props: TransferProps, ctx: HookContext) {
   const dataRef = toRef(() => props.data ?? []);
   const modelValueRef = toRef(() => props.modelValue ?? []);
 

package/components/base/tree/__tests__/tree.test.ts

@@ -0,0 +1,214 @@
+/**
+ * @description Tree 类核心测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import Tree, { mergeConfig, DEFAULT_CONFIG } from '../tree';
+import { fixKey } from '../useTree';
+
+const SAMPLE_DATA = [
+  {
+    key: '1', label: '节点 1', children: [
+      { key: '1-1', label: '子节点 1-1' },
+      { key: '1-2', label: '子节点 1-2', children: [
+        { key: '1-2-1', label: '孙节点 1-2-1' },
+      ] },
+    ],
+  },
+  { key: '2', label: '节点 2' },
+  { key: '3', label: '节点 3', disabled: true },
+];
+
+describe('mergeConfig', () => {
+  it('返回默认配置', () => {
+    expect(mergeConfig(DEFAULT_CONFIG)).toBe(DEFAULT_CONFIG);
+  });
+
+  it('自定义字段合并', () => {
+    const result = mergeConfig({ key: 'id', label: 'name' });
+    expect(result.key).toBe('id');
+    expect(result.label).toBe('name');
+    expect(result.children).toBe('children');
+  });
+});
+
+describe('fixKey', () => {
+  it('为无 key 的节点生成 key', () => {
+    const data = [{ label: 'A' }, { label: 'B' }] as any[];
+    const result = fixKey(data, 'key') as any[];
+    expect(result[0].key).toBe('0');
+    expect(result[1].key).toBe('1');
+  });
+
+  it('已有 key 的节点保持不变', () => {
+    const data = [{ key: 'existing', label: 'A' }];
+    const result = fixKey(data, 'key') as any[];
+    expect(result[0].key).toBe('existing');
+  });
+
+  it('递归处理子节点', () => {
+    const data = [{ key: 'root', children: [{ label: 'child' }] }] as any[];
+    const result = fixKey(data, 'key') as any[];
+    expect(result[0].children[0].key).toBe('root0');
+  });
+
+  it('单节点也能处理', () => {
+    const data = { label: 'single' } as any;
+    const result = fixKey(data, 'key') as any;
+    expect(result.key).toBe('0');
+  });
+});
+
+describe('Tree', () => {
+  it('构建树并获取根节点', () => {
+    const tree = new Tree({ data: SAMPLE_DATA });
+    const roots = tree.getTreeData();
+    expect(roots).toHaveLength(3);
+    expect(roots[0].isRoot).toBe(true);
+  });
+
+  it('getTreeData 通过 keys 获取节点', () => {
+    const tree = new Tree({ data: SAMPLE_DATA });
+    const nodes = tree.getTreeData(['1-1', '2']);
+    expect(nodes).toHaveLength(2);
+  });
+
+  it('getChildrenKeys 返回直接子节点 key', () => {
+    const tree = new Tree({ data: SAMPLE_DATA });
+    const root = tree.getTreeData(['1'])[0];
+    const keys = tree.getChildrenKeys(root);
+    expect(keys).toEqual(['1-1', '1-2']);
+  });
+
+  it('toggleExpand 切换展开状态', () => {
+    const tree = new Tree({ data: SAMPLE_DATA });
+    const node = tree.getTreeData(['1'])[0];
+
+    expect(node.expand).toBe(false);
+    tree.toggleExpand(node);
+    expect(node.expand).toBe(true);
+    tree.toggleExpand(node);
+    expect(node.expand).toBe(false);
+  });
+
+  it('toggleExpand 指定值', () => {
+    const tree = new Tree({ data: SAMPLE_DATA });
+    const node = tree.getTreeData(['1'])[0];
+
+    tree.toggleExpand(node, true);
+    expect(node.expand).toBe(true);
+    tree.toggleExpand(node, true);
+    expect(node.expand).toBe(true);
+  });
+
+  it('defaultExpandAll 展开所有节点', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, defaultExpandAll: true });
+    const root = tree.getTreeData(['1'])[0];
+    expect(root.expand).toBe(true);
+  });
+
+  it('setNodeCheckbox 选中节点', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, checkStrictly: true });
+    const root = tree.getTreeData(['1'])[0];
+
+    tree.setNodeCheckbox(root, true);
+    expect(root.checked).toBe(true);
+    expect(root.indeterminate).toBe(false);
+
+    // 子节点也被选中（checkStrictly=true 级联）
+    const child = tree.getTreeData(['1-1'])[0];
+    expect(child.checked).toBe(true);
+  });
+
+  it('setNodeCheckbox checkStrictly=true 向上级联', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, checkStrictly: true });
+    const child = tree.getTreeData(['1-1'])[0];
+
+    tree.setNodeCheckbox(child, true);
+
+    // 父节点应该是半选（只有一个子节点选中）
+    const root = tree.getTreeData(['1'])[0];
+    expect(root.indeterminate).toBe(true);
+    expect(root.checked).toBe(false);
+  });
+
+  it('setNodeCheckbox 全部子节点选中时父节点全选', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, checkStrictly: true });
+
+    tree.setNodeCheckbox(tree.getTreeData(['1-1'])[0], true);
+    tree.setNodeCheckbox(tree.getTreeData(['1-2'])[0], true);
+
+    const root = tree.getTreeData(['1'])[0];
+    expect(root.checked).toBe(true);
+    expect(root.indeterminate).toBe(false);
+  });
+
+  it('setNodeCheckbox checkStrictly=false 不级联', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, checkStrictly: false });
+    const root = tree.getTreeData(['1'])[0];
+
+    tree.setNodeCheckbox(root, true);
+    // 子节点不受影响
+    const child = tree.getTreeData(['1-1'])[0];
+    expect(child.checked).toBe(false);
+  });
+
+  it('disabled 节点不受级联影响', () => {
+    const data = [
+      {
+        key: 'p', children: [
+          { key: 'c1' },
+          { key: 'c2', disabled: true },
+        ],
+      },
+    ];
+    const tree = new Tree({ data, checkStrictly: true });
+    const parent = tree.getTreeData(['p'])[0];
+
+    tree.setNodeCheckbox(parent, true);
+    // c1 被选中，c2 因 disabled 不受影响
+    expect(tree.getTreeData(['c1'])[0].checked).toBe(true);
+    expect(tree.getTreeData(['c2'])[0].checked).toBe(false);
+  });
+
+  it('setCheckedByKeys 批量选中', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, checkStrictly: true });
+    tree.setCheckedByKeys(['1-1', '2']);
+
+    expect(tree.getTreeData(['1-1'])[0].checked).toBe(true);
+    expect(tree.getTreeData(['2'])[0].checked).toBe(true);
+  });
+
+  it('getKeys 获取选中和展开的 key', () => {
+    const tree = new Tree({ data: SAMPLE_DATA, checkStrictly: true, defaultExpandAll: true });
+    tree.setNodeCheckbox(tree.getTreeData(['2'])[0], true);
+
+    const { checkedKeys, expandKeys } = tree.getKeys();
+    expect(checkedKeys).toContain('2');
+    expect(expandKeys.length).toBeGreaterThan(0);
+  });
+
+  it('单节点数据也能正常构建', () => {
+    const tree = new Tree({ data: { key: 'single', label: '单节点' } });
+    const roots = tree.getTreeData();
+    expect(roots).toHaveLength(1);
+    expect(roots[0].isRoot).toBe(true);
+  });
+
+  it('自定义 config 字段映射', () => {
+    const data = [{ id: 'a', name: '节点 A', items: [{ id: 'b', name: '子节点 B' }] }] as any[];
+    const tree = new Tree({
+      data,
+      config: { key: 'id', label: 'name', value: 'value', children: 'items' },
+    });
+    const roots = tree.getTreeData();
+    expect(roots).toHaveLength(1);
+
+    const childKeys = tree.getChildrenKeys(roots[0]);
+    expect(childKeys).toEqual(['b']);
+  });
+});