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

package/compositions/common/__tests__/useDebounceFn.test.ts

@@ -0,0 +1,62 @@
+/**
+ * @description useDebounceFn 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import useDebounceFn from '../useDebounceFn';
+
+beforeEach(() => { vi.useFakeTimers(); });
+afterEach(() => { vi.useRealTimers(); });
+
+describe('useDebounceFn', () => {
+  it('返回防抖后的函数', () => {
+    const fn = vi.fn();
+    const debounced = useDebounceFn(fn, 100);
+
+    debounced();
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('默认延迟 200ms', () => {
+    const fn = vi.fn();
+    const debounced = useDebounceFn(fn);
+
+    debounced();
+    vi.advanceTimersByTime(199);
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(1);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('支持 maxWait 选项', () => {
+    const fn = vi.fn();
+    const debounced = useDebounceFn(fn, 100, { maxWait: 150 });
+
+    debounced();
+    vi.advanceTimersByTime(80);
+    debounced();
+    vi.advanceTimersByTime(80);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('多次调用只执行最后一次', () => {
+    const fn = vi.fn();
+    const debounced = useDebounceFn(fn, 50);
+
+    debounced('a');
+    debounced('b');
+    debounced('c');
+
+    vi.advanceTimersByTime(50);
+    expect(fn).toHaveBeenCalledOnce();
+    expect(fn).toHaveBeenCalledWith('c');
+  });
+});

package/compositions/common/__tests__/useEventListener.test.ts

@@ -0,0 +1,71 @@
+/**
+ * @description useEventListener 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import useEventListener from '../useEventListener';
+
+describe('useEventListener', () => {
+  it('add 注册事件，remove 移除事件', () => {
+    const handler = vi.fn();
+    const target = {
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    };
+
+    const { add, remove } = useEventListener({
+      target,
+      event: 'click',
+      handler,
+    });
+
+    add();
+    expect(target.addEventListener).toHaveBeenCalledWith('click', handler);
+
+    remove();
+    expect(target.removeEventListener).toHaveBeenCalledWith('click', handler);
+  });
+
+  it('onMounted 调用 add，onBeforeUnmount 调用 remove', () => {
+    const handler = vi.fn();
+    const target = {
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    };
+
+    const { onMounted, onBeforeUnmount } = useEventListener({
+      target,
+      event: 'scroll',
+      handler,
+    });
+
+    onMounted();
+    expect(target.addEventListener).toHaveBeenCalledOnce();
+
+    onBeforeUnmount();
+    expect(target.removeEventListener).toHaveBeenCalledOnce();
+  });
+
+  it('target 为函数时延迟求值', () => {
+    const handler = vi.fn();
+    const realTarget = {
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    };
+    const targetFn = vi.fn(() => realTarget);
+
+    const { add } = useEventListener({
+      target: targetFn,
+      event: 'click',
+      handler,
+    });
+
+    add();
+    expect(targetFn).toHaveBeenCalled();
+    expect(realTarget.addEventListener).toHaveBeenCalledWith('click', handler);
+  });
+});

package/compositions/common/__tests__/usePopover.test.ts

@@ -0,0 +1,38 @@
+/**
+ * @description usePopover（common）测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import usePopover from '../usePopover';
+
+describe('usePopover', () => {
+  it('默认 placement 为 bottom-start', () => {
+    const { popoverOptions } = usePopover();
+    expect(popoverOptions.placement).toBe('bottom-start');
+  });
+
+  it('自定义 placement', () => {
+    const { popoverOptions } = usePopover({ placement: 'top-end' });
+    expect(popoverOptions.placement).toBe('top-end');
+  });
+
+  it('默认 middleware 包含 offset、flip、shift', () => {
+    const { popoverOptions } = usePopover();
+    expect(popoverOptions.popper?.middleware).toHaveLength(3);
+  });
+
+  it('自定义 offset', () => {
+    const { popoverOptions } = usePopover(undefined, { offset: 10 });
+    expect(popoverOptions.popper?.middleware).toHaveLength(3);
+  });
+
+  it('扩展 middleware', () => {
+    const customMiddleware = { name: 'custom', fn: () => ({}) };
+    const { popoverOptions } = usePopover(undefined, { extends: [customMiddleware as any] });
+    expect(popoverOptions.popper?.middleware).toHaveLength(4);
+  });
+});

package/compositions/common/__tests__/useTeleport.test.ts

@@ -0,0 +1,25 @@
+/**
+ * @description useTeleport / initTeleportOptions 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import { initTeleportOptions } from '../useTeleport';
+
+describe('initTeleportOptions', () => {
+  it('true 默认 teleport 到 body', () => {
+    expect(initTeleportOptions(true)).toEqual({ to: 'body' });
+  });
+
+  it('undefined 默认 teleport 到 body', () => {
+    expect(initTeleportOptions(undefined)).toEqual({ to: 'body' });
+  });
+
+  it('自定义配置直接返回', () => {
+    const custom = { to: '#app', disabled: false };
+    expect(initTeleportOptions(custom as any)).toBe(custom);
+  });
+});

package/compositions/common/testAnchor.ts

@@ -0,0 +1,211 @@
+/**
+ * @description Test anchor system: provide/inject keys, types, and kDefineComponent wrapper
+ * @author kine-design
+ * @date 2026/4/28
+ * @version v1.0.0
+ *
+ * Renders business-semantic `data-k` attributes on DOM elements when testAnchor is enabled,
+ * allowing E2E tests to target components by stable identifiers.
+ */
+import {
+  cloneVNode,
+  defineComponent,
+  inject,
+  type ComponentPropsOptions,
+  type EmitsOptions,
+  type InjectionKey,
+  type Ref,
+  type SetupContext,
+  type VNode,
+} from 'vue';
+
+// ---------------------------------------------------------------------------
+// Injection keys
+// ---------------------------------------------------------------------------
+
+/** Global switch provided by KConfigProvider to enable data-k rendering */
+export const K_TEST_ANCHOR_KEY: InjectionKey<Ref<boolean>> = Symbol('k-test-anchor');
+
+/** Field identity provided by KFormItem so child inputs inherit field name */
+export const K_FIELD_KEY: InjectionKey<Ref<string | undefined>> = Symbol('k-field');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface KAnchorConfig {
+  /** Semantic type: 'field' | 'action' | 'table' | 'col' | 'dialog' | 'drawer' | 'tab' */
+  type: string;
+  /** Which prop to derive the identity from (e.g., 'prop' for KFormItem, 'title' for KDialog) */
+  prop?: string;
+  /** Derive identity from default slot text content (for KButton) */
+  slotText?: boolean;
+}
+
+interface KDefineComponentOptions {
+  name: string;
+  props?: ComponentPropsOptions;
+  emits?: EmitsOptions;
+  kAnchor?: KAnchorConfig;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract text content from a VNode tree (for slotText mode).
+ * Walks children recursively, concatenating string segments.
+ */
+function extractSlotText(nodes: VNode[] | undefined): string {
+  if (!nodes) return '';
+  let text = '';
+  for (const node of nodes) {
+    if (typeof node.children === 'string') {
+      text += node.children;
+    } else if (Array.isArray(node.children)) {
+      text += extractSlotText(node.children as VNode[]);
+    }
+  }
+  return text.trim();
+}
+
+/**
+ * Resolve the data-k value for a component instance.
+ * Returns undefined when testAnchor is off or no identity can be derived.
+ */
+function resolveDataK(
+  config: KAnchorConfig,
+  props: Record<string, unknown>,
+  attrs: Record<string, unknown>,
+  fieldFromParent: string | undefined,
+  slotNodes?: VNode[],
+): string | undefined {
+  // Developer override via k-{type} attr (e.g., k-action="approve")
+  const overrideKey = `k-${config.type}`;
+  const override = attrs[overrideKey];
+  if (typeof override === 'string' && override) {
+    return `${config.type}:${override}`;
+  }
+
+  // Derive from prop
+  if (config.prop) {
+    const val = props[config.prop];
+    if (typeof val === 'string' && val) {
+      return `${config.type}:${val}`;
+    }
+  }
+
+  // Derive from slot text (e.g., KButton default slot)
+  if (config.slotText && slotNodes) {
+    const text = extractSlotText(slotNodes);
+    if (text) {
+      return `${config.type}:${text}`;
+    }
+  }
+
+  // Fallback: check props.text (for KButton text prop)
+  if (config.slotText && typeof props.text === 'string' && props.text) {
+    return `${config.type}:${props.text}`;
+  }
+
+  // Inherit from parent KFormItem for input-type components
+  if (config.type === 'field' && !config.prop && fieldFromParent) {
+    return `${config.type}:${fieldFromParent}`;
+  }
+
+  return undefined;
+}
+
+/**
+ * Inject data-k attribute into a VNode.
+ * Uses cloneVNode to avoid mutating the original.
+ */
+function injectDataK(vnode: VNode, dataK: string): VNode {
+  return cloneVNode(vnode, { 'data-k': dataK });
+}
+
+// ---------------------------------------------------------------------------
+// kDefineComponent
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrapper around Vue's defineComponent that automatically injects `data-k`
+ * test anchor attributes when testAnchor is enabled via KConfigProvider.
+ *
+ * Usage:
+ * ```tsx
+ * export default kDefineComponent((_props, ctx) => {
+ *   return () => <div class="k-form-item">...</div>;
+ * }, {
+ *   name: 'KFormItem',
+ *   props: FormCore.formItemProps,
+ *   kAnchor: { type: 'field', prop: 'prop' },
+ * });
+ * ```
+ */
+export function kDefineComponent<P extends Record<string, unknown>>(
+  setup: (props: P, ctx: SetupContext) => () => VNode | VNode[] | null | undefined,
+  options: KDefineComponentOptions,
+) {
+  const { kAnchor, ...defineOptions } = options;
+
+  return defineComponent((rawProps: P, ctx: SetupContext) => {
+    // Call the original setup to get the render function
+    const render = setup(rawProps, ctx);
+
+    // If no kAnchor config, skip entirely
+    if (!kAnchor) {
+      return render;
+    }
+
+    // Read the global testAnchor switch
+    const testAnchor = inject(K_TEST_ANCHOR_KEY, undefined);
+
+    // For field-type components without own prop, inject parent field identity
+    const parentField = (kAnchor.type === 'field' && !kAnchor.prop)
+      ? inject(K_FIELD_KEY, undefined)
+      : undefined;
+
+    return () => {
+      const vnode = render();
+
+      // When testAnchor is off (default), render as-is
+      if (!testAnchor?.value) {
+        return vnode;
+      }
+
+      // Resolve the data-k value
+      const props = rawProps as Record<string, unknown>;
+      const slotNodes = kAnchor.slotText ? (ctx.slots.default?.() ?? undefined) : undefined;
+      const dataK = resolveDataK(
+        kAnchor,
+        props,
+        ctx.attrs,
+        parentField?.value,
+        slotNodes,
+      );
+
+      if (!dataK) {
+        return vnode;
+      }
+
+      // Inject into root vnode
+      if (vnode === null || vnode === undefined) {
+        return vnode;
+      }
+
+      // Handle array of vnodes (Fragment) — inject into first element
+      if (Array.isArray(vnode)) {
+        if (vnode.length === 0) return vnode;
+        const first = vnode[0];
+        if (first && typeof first === 'object') {
+          return [injectDataK(first, dataK), ...vnode.slice(1)];
+        }
+        return vnode;
+      }
+
+      return injectDataK(vnode, dataK);
+    };
+  }, defineOptions as Parameters<typeof defineComponent>[1]);
+}

package/compositions/common/useEventListener.ts

@@ -9,7 +9,7 @@
 
 
 export type EventListenerOptions = {
-  target: any,
+  target: EventTarget | (() => EventTarget),
   event: string,
   handler: EventListenerOrEventListenerObject,
 };
@@ -35,14 +35,14 @@ export default function useEventListener(options: EventListenerOptions) {
     add();
   };
 
-  const onBeforeDestroy = () => {
+  const onBeforeUnmount = () => {
     remove();
   };
 
   return {
     add, remove,
     onMounted,
-    onBeforeDestroy,
+    onBeforeUnmount,
   };
 
 }

package/compositions/common/useResizeObserver.ts

@@ -9,7 +9,7 @@
  * Learn from vueuse useResizeObserver
  */
 
-import { Ref, watch } from 'vue';
+import { onBeforeUnmount, Ref, watch } from 'vue';
 
 export function useResizeObserver(
   target: Ref<HTMLElement | null>,
@@ -27,7 +27,7 @@ export function useResizeObserver(
   };
 
   // vueuse used watch
-  watch(target, () => {
+  const stopWatch = watch(target, () => {
     if (target.value) {
       cleanup();
       observer = new ResizeObserver(callback);
@@ -35,6 +35,10 @@ export function useResizeObserver(
     }
   });
 
+  onBeforeUnmount(() => {
+    cleanup();
+    stopWatch();
+  });
 
   return {
     cleanup,

package/compositions/input/__tests__/useBooleanInput.test.ts

@@ -0,0 +1,73 @@
+/**
+ * @description initChecked / getNewModelValue 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it } from 'vitest';
+import { initChecked, getNewModelValue } from '../useBooleanInput';
+
+describe('initChecked', () => {
+  it('checked 为 true 时直接返回 true', () => {
+    expect(initChecked({ checked: true, modelValue: undefined, value: undefined })).toBe(true);
+  });
+
+  it('modelValue 为 boolean 时返回该值', () => {
+    expect(initChecked({ checked: undefined, modelValue: true, value: undefined })).toBe(true);
+    expect(initChecked({ checked: undefined, modelValue: false, value: undefined })).toBe(false);
+  });
+
+  it('modelValue 和 value 相等时返回 true', () => {
+    expect(initChecked({ checked: undefined, modelValue: 'a', value: 'a' })).toBe(true);
+  });
+
+  it('modelValue 和 value 不等时返回 false', () => {
+    expect(initChecked({ checked: undefined, modelValue: 'a', value: 'b' })).toBe(false);
+  });
+
+  it('modelValue 为数组时，检查 value 是否在数组中', () => {
+    expect(initChecked({ checked: undefined, modelValue: ['a', 'b'], value: 'a' })).toBe(true);
+    expect(initChecked({ checked: undefined, modelValue: ['a', 'b'], value: 'c' })).toBe(false);
+  });
+
+  it('所有值为空时返回 false', () => {
+    expect(initChecked({ checked: undefined, modelValue: undefined, value: undefined })).toBe(false);
+    expect(initChecked({ checked: null, modelValue: null, value: null })).toBe(false);
+  });
+});
+
+describe('getNewModelValue', () => {
+  // 有 value 且 modelValue 为数组
+  it('checked=true 且 modelValue 为数组时添加 value', () => {
+    expect(getNewModelValue({ value: 'c', modelValue: ['a', 'b'] }, true)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('checked=false 且 modelValue 为数组时移除 value', () => {
+    expect(getNewModelValue({ value: 'b', modelValue: ['a', 'b'] }, false)).toEqual(['a']);
+  });
+
+  it('不重复添加已存在的 value', () => {
+    expect(getNewModelValue({ value: 'a', modelValue: ['a', 'b'] }, true)).toEqual(['a', 'b']);
+  });
+
+  it('移除不存在的 value 不报错', () => {
+    expect(getNewModelValue({ value: 'c', modelValue: ['a', 'b'] }, false)).toEqual(['a', 'b']);
+  });
+
+  // 有 value 且 modelValue 非数组
+  it('checked=true 返回 value', () => {
+    expect(getNewModelValue({ value: 'a', modelValue: undefined }, true)).toBe('a');
+  });
+
+  it('checked=false 返回 undefined', () => {
+    expect(getNewModelValue({ value: 'a', modelValue: undefined }, false)).toBeUndefined();
+  });
+
+  // 无 value
+  it('无 value 时直接返回 checked 布尔值', () => {
+    expect(getNewModelValue({ value: undefined, modelValue: undefined }, true)).toBe(true);
+    expect(getNewModelValue({ value: undefined, modelValue: undefined }, false)).toBe(false);
+  });
+});

package/compositions/modal/__tests__/useModal.test.ts

@@ -0,0 +1,92 @@
+/**
+ * @description useModal 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { useModal } from '../useModal';
+
+describe('useModal', () => {
+  it('初始 visible 默认为 false', () => {
+    const emit = vi.fn();
+    const { visible } = useModal({}, emit);
+    expect(visible.value).toBe(false);
+  });
+
+  it('初始 visible 跟随 props', () => {
+    const emit = vi.fn();
+    const { visible } = useModal({ visible: true }, emit);
+    expect(visible.value).toBe(true);
+  });
+
+  it('open 设置 visible 为 true 并触发 emit', () => {
+    const emit = vi.fn();
+    const { visible, open } = useModal({}, emit);
+
+    open();
+    expect(visible.value).toBe(true);
+    expect(emit).toHaveBeenCalledWith('update:visible', true);
+  });
+
+  it('close 设置 visible 为 false 并触发 emit', () => {
+    const emit = vi.fn();
+    const { visible, close } = useModal({ visible: true }, emit);
+
+    close();
+    expect(visible.value).toBe(false);
+    expect(emit).toHaveBeenCalledWith('update:visible', false);
+  });
+
+  it('toggle 切换 visible 状态', () => {
+    const emit = vi.fn();
+    const { visible, toggle } = useModal({}, emit);
+
+    toggle(); // false → true
+    expect(visible.value).toBe(true);
+
+    toggle(); // true → false
+    expect(visible.value).toBe(false);
+  });
+
+  it('onMaskClick 默认关闭', () => {
+    const emit = vi.fn();
+    const { visible, open, onMaskClick } = useModal({}, emit);
+
+    open();
+    onMaskClick();
+    expect(visible.value).toBe(false);
+  });
+
+  it('onMaskClick 当 mask.clickClose=false 时不关闭', () => {
+    const emit = vi.fn();
+    const { visible, open, onMaskClick } = useModal({ mask: { clickClose: false } }, emit);
+
+    open();
+    onMaskClick();
+    expect(visible.value).toBe(true);
+  });
+
+  it('showMask 默认返回 true', () => {
+    const emit = vi.fn();
+    const { showMask } = useModal({}, emit);
+    expect(showMask()).toBe(true);
+  });
+
+  it('showMask 当 mask.show=false 时返回 false', () => {
+    const emit = vi.fn();
+    const { showMask } = useModal({ mask: { show: false } }, emit);
+    expect(showMask()).toBe(false);
+  });
+
+  it('onContentClick 阻止冒泡', () => {
+    const emit = vi.fn();
+    const { onContentClick } = useModal({}, emit);
+    const event = { stopPropagation: vi.fn() } as unknown as MouseEvent;
+
+    onContentClick(event);
+    expect(event.stopPropagation).toHaveBeenCalled();
+  });
+});

package/compositions/modal/useModal.ts

@@ -9,6 +9,7 @@
  * 处理 visible 状态、遮罩层点击关闭、emit 同步
  */
 import { ref, watch } from 'vue';
+import { type HookContext } from '../../components/types/hook';
 import { ModelMask } from '../../types/common/model';
 
 export interface UseModalProps {
@@ -16,8 +17,7 @@ export interface UseModalProps {
   mask?: ModelMask;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function useModal(props: UseModalProps, emit: (...args: any[]) => void) {
+export function useModal(props: UseModalProps, emit: HookContext['emit']) {
   const visible = ref(props.visible ?? false);
 
   watch(() => props.visible, (val) => {

package/compositions/popper/useClickAway.ts

@@ -11,14 +11,14 @@ import useEventListener from '../common/useEventListener';
 
 const event = 'pointerdown';
 export default function useClickAway(options: {
-  target: any,
-  handler: (event: any) => void
+  target: EventTarget | (() => EventTarget | null | undefined),
+  handler: (event: PointerEvent) => void
 }) {
   if (typeof window === 'undefined' || !window) {
     return;
   }
 
-  const listener = (event: any) => {
+  const listener = (event: Event) => {
     const el = typeof options.target === 'function' ? options.target() : options.target;
     if (!el) {
       return;
@@ -28,7 +28,7 @@ export default function useClickAway(options: {
       return;
     }
 
-    options.handler(event);
+    options.handler(event as PointerEvent);
   };
 
   return useEventListener({