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

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

@@ -0,0 +1,98 @@
+/**
+ * @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(),
+      dispatchEvent: 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(),
+      dispatchEvent: 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(),
+      dispatchEvent: 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);
+  });
+
+  it('target 为 null 时 add 抛出异常（无防御性检查）', () => {
+    // useEventListener 不对 null/undefined target 做守卫，
+    // 调用 add() 时会对 null 调用 addEventListener，导致 TypeError
+    const handler = vi.fn();
+    const { add } = useEventListener({
+      target: null as unknown as EventTarget,
+      event: 'click',
+      handler,
+    });
+
+    expect(() => add()).toThrow();
+  });
+
+  it('target 为返回 undefined 的函数时 add 抛出异常', () => {
+    const handler = vi.fn();
+    const { add } = useEventListener({
+      target: (() => undefined) as unknown as () => EventTarget,
+      event: 'click',
+      handler,
+    });
+
+    expect(() => add()).toThrow();
+  });
+});

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

@@ -0,0 +1,43 @@
+/**
+ * @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 });
+    const middleware = popoverOptions.popper?.middleware;
+    expect(middleware).toHaveLength(3);
+    // middleware[0] 是 offset(10)，验证自定义 offset 值确实被应用
+    const offsetMiddleware = middleware![0] as { name: string; options: unknown };
+    expect(offsetMiddleware.name).toBe('offset');
+    expect(offsetMiddleware.options).toBe(10);
+  });
+
+  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,32 @@
+/**
+ * @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);
+  });
+
+  it('false 不命中 true/undefined 分支，原样返回', () => {
+    // initTeleportOptions 只对 true 和 undefined 返回 { to: 'body' }，
+    // false 走 else 分支直接返回原值
+    const result = initTeleportOptions(false as unknown as import('vue').TeleportProps);
+    expect(result).toBe(false);
+  });
+});

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

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/useComponentSize.ts

@@ -0,0 +1,17 @@
+/**
+ * @description composable for unified component size with global injection support
+ * @author 阿怪
+ * @date 2026/4/7
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { computed, inject, type InjectionKey, type Ref } from 'vue';
+import { KineSize } from '../../components/types/props';
+
+export const KINE_SIZE_KEY: InjectionKey<Ref<KineSize>> = Symbol('kine-size');
+
+export function useComponentSize(props: { size?: KineSize }): Ref<KineSize> {
+  const globalSize = inject(KINE_SIZE_KEY, undefined);
+  return computed(() => props.size ?? globalSize?.value ?? 'medium');
+}

package/compositions/common/useDebounceFn.ts

@@ -0,0 +1,27 @@
+/**
+ * @description 防抖hook
+ * @author youus
+ * @date 2022/8/19 23:47
+ * @version v1.0.0
+ *
+ * Hello, humor
+ */
+import type { DebounceFilterOptions, FunctionArgs } from '../utils/filters';
+import { createFilterWrapper, debounceFilter } from '../utils/filters';
+
+/**
+ * Debounce execution of a function.
+ *
+ * @see https://vueuse.org/useDebounceFn
+ * @param  fn          A function to be executed after delay milliseconds debounced.
+ * @param  ms          A zero-or-greater delay in milliseconds. For event callbacks, values around 100 or 250 (or even higher) are most useful.
+ * @param  opts        options
+ *
+ * @return A new, debounce, function.
+ */
+export default function useDebounceFn<T extends FunctionArgs>(fn: T, ms: number = 200, options: DebounceFilterOptions = {}): T {
+  return createFilterWrapper(
+    debounceFilter(ms, options),
+    fn,
+  );
+}

package/compositions/common/useDrag.ts

@@ -0,0 +1,65 @@
+/**
+ * @description drag hook
+ * @author 阿怪
+ * @date 2023/5/23 16:42
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import * as _interactjsModule from 'interactjs';
+// interactjs 是 UMD 格式，Vite ESM 不提供 default export，需兼容处理
+const interactjs = (_interactjsModule as any).default ?? _interactjsModule;
+import { Ref, ref } from 'vue';
+
+// 方向类型，内联定义避免引用 lib 的 MessageDirectionType
+export type DragDirectionType = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | string;
+export type InteractEvent = any;
+export type DragPosition = { x: number, y: number };
+export type DragOption = { startAxis: 'x' | 'y', lockAxis: 'x' | 'y' };
+
+
+export default function useDrag(config: {
+  direction: DragDirectionType,
+  value?: {
+    domRef?: Ref<HTMLElement | null>
+  },
+  event?: {
+    getOption?: () => DragOption,
+    movePositionHandler?: (event: InteractEvent, position: DragPosition) => DragPosition,
+    onDragLeave?: (event: InteractEvent) => void
+  }
+}) {
+  const domRef = config.value?.domRef ?? ref();
+
+  const init = (basePosition?: { x?: number, y?: number }) => {
+    if (!domRef.value) {
+      return;
+    }
+    const position: DragPosition = { x: basePosition?.x ?? 0, y: basePosition?.y ?? 0 };
+    return interactjs(domRef.value)
+      .styleCursor(false)
+      .draggable({
+        ...config.event?.getOption?.(),
+        listeners: {
+          end: (event: InteractEvent) => {
+            config.event?.onDragLeave?.(event);
+          },
+          move: (event: InteractEvent) => {
+            const { x, y } = config.event?.movePositionHandler?.(event, position) ?? {
+              x: position.x + event.dx, y: position.y + event.dy,
+            };
+            position.x = x;
+            position.y = y;
+            event.target.style.transform = `translate(${position.x}px, ${position.y}px)`;
+          },
+        },
+      });
+  };
+
+
+  return {
+    domRef,
+    init,
+  };
+
+}

package/compositions/common/useElementSize.ts

@@ -0,0 +1,37 @@
+/**
+ * @description element size hook
+ * @author 阿怪
+ * @date 2023/6/24 16:17
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * Learn from vueuse useElementSize
+ */
+import { Ref, ref } from 'vue';
+import { useResizeObserver } from './useResizeObserver';
+
+
+export function useElementSize(
+  target: Ref<HTMLElement | null>,
+  // initialSize = { w: 0, h: 0 },
+  // options: ResizeObserverOptions = {},
+) {
+
+  const w = ref(0);
+  const h = ref(0);
+
+  useResizeObserver(target, () => {
+    const ele = target.value;
+    if (window && ele) {
+      const styles = window.getComputedStyle(ele);
+      w.value = Number.parseFloat(styles.width);
+      h.value = Number.parseFloat(styles.height);
+    }
+  });
+
+
+  return {
+    w, h,
+  };
+}

package/compositions/common/useEventListener.ts

@@ -0,0 +1,48 @@
+/**
+ * @description event listener hook
+ * @author 阿怪
+ * @date 2023/5/12 00:57
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+
+export type EventListenerOptions = {
+  target: EventTarget | (() => EventTarget),
+  event: string,
+  handler: EventListenerOrEventListenerObject,
+};
+
+export default function useEventListener(options: EventListenerOptions) {
+
+  const getTarget = () => {
+    if (typeof options.target === 'function') {
+      return options.target();
+    }
+    return options.target;
+  };
+
+  const add = () => {
+    getTarget().addEventListener(options.event, options.handler);
+  };
+
+  const remove = () => {
+    getTarget().removeEventListener(options.event, options.handler);
+  };
+
+  const onMounted = () => {
+    add();
+  };
+
+  const onBeforeUnmount = () => {
+    remove();
+  };
+
+  return {
+    add, remove,
+    onMounted,
+    onBeforeUnmount,
+  };
+
+}

package/compositions/common/usePopover.ts

@@ -0,0 +1,45 @@
+/**
+ * @description popover hook, for component like select, datepicker, etc.
+ * @author 阿怪
+ * @date 2023/5/19 00:12
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { PopoverProps } from '../../components/message/popover/props';
+import { arrow, flip, offset, type OffsetOptions, shift } from '@floating-ui/dom';
+
+export {
+  flip,
+  offset,
+  shift,
+  arrow,
+};
+
+export default function usePopover(
+  props?: Partial<PopoverProps>,
+  middleware?: {
+    offset?: OffsetOptions
+    extends?: any[]
+  },
+) {
+
+  const offsetOptions = middleware?.offset ?? { crossAxis: 3 };
+
+
+  const popoverOptions: PopoverProps = {
+    placement: props?.placement ?? 'bottom-start',
+    popper: {
+      middleware: [
+        offset(offsetOptions),
+        flip(),
+        shift(),
+        ...middleware?.extends ?? [],
+      ],
+    },
+  };
+
+  return {
+    popoverOptions,
+  };
+}