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

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

@@ -0,0 +1,53 @@
+/**
+ * @description composable for unified component locale with global injection
+ *   support — the i18n counterpart of `useComponentSize`. Components call
+ *   `useLocale()` to get the active message dictionary (a computed ref) and read
+ *   their user-facing strings from it instead of hardcoding text.
+ * @author kine-design
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { computed, inject, type ComputedRef, type InjectionKey, type Ref } from 'vue';
+import type { KineLocaleName, KineLocaleMessages } from '../../locale/types';
+import { DEFAULT_LOCALE, locales } from '../../locale';
+
+/** Accepted `locale` values: a built-in name, or a full custom dictionary. */
+export type KineLocaleConfig = KineLocaleName | KineLocaleMessages;
+
+export const KINE_LOCALE_KEY: InjectionKey<Ref<KineLocaleConfig | undefined>> = Symbol('kine-locale');
+
+function resolveMessages(config: KineLocaleConfig | undefined): KineLocaleMessages {
+  if (!config) return locales[DEFAULT_LOCALE];
+  if (typeof config === 'string') return locales[config] ?? locales[DEFAULT_LOCALE];
+  return config;
+}
+
+/**
+ * Resolve the active message dictionary from the nearest `KConfigProvider`.
+ * Falls back to the default (zh) pack when no provider is present.
+ */
+export function useLocale(): ComputedRef<KineLocaleMessages> {
+  const injected = inject(KINE_LOCALE_KEY, undefined);
+  return computed(() => resolveMessages(injected?.value));
+}
+
+// ── Global singleton ─────────────────────────────────────────────────────────
+// Components read locale through useLocale() (provide/inject, scoped + reactive).
+// But non-component code — the crud request/error feedback functions — has no
+// component context and cannot inject. Those read this module-level singleton
+// instead. KConfigProvider keeps it in sync inside its setup, so under a single
+// root provider the two are always consistent; with nested providers the global
+// reflects whichever was set last (an acceptable trade-off, since feedback text
+// is app-global by nature).
+let activeLocaleMessages: KineLocaleMessages = locales[DEFAULT_LOCALE];
+
+/** Set the global active dictionary. Called by KConfigProvider on locale change. */
+export function setActiveLocaleMessages(config: KineLocaleConfig | undefined): void {
+  activeLocaleMessages = resolveMessages(config);
+}
+
+/** Read the global active dictionary from non-component (pure-function) code. */
+export function getActiveLocaleMessages(): KineLocaleMessages {
+  return activeLocaleMessages;
+}

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

package/compositions/common/useResizeObserver.ts

@@ -0,0 +1,47 @@
+/**
+ * @description resizeObserver hook
+ * @author 阿怪
+ * @date 2023/6/24 16:08
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * Learn from vueuse useResizeObserver
+ */
+
+import { onBeforeUnmount, Ref, watch } from 'vue';
+
+export function useResizeObserver(
+  target: Ref<HTMLElement | null>,
+  callback: ResizeObserverCallback,
+  options: ResizeObserverOptions = {},
+) {
+
+  let observer: ResizeObserver | undefined;
+
+  const cleanup = () => {
+    if (observer) {
+      observer.disconnect();
+      observer = undefined;
+    }
+  };
+
+  // vueuse used watch
+  const stopWatch = watch(target, () => {
+    if (target.value) {
+      cleanup();
+      observer = new ResizeObserver(callback);
+      observer.observe(target.value, options);
+    }
+  });
+
+  onBeforeUnmount(() => {
+    cleanup();
+    stopWatch();
+  });
+
+  return {
+    cleanup,
+  };
+
+}

package/compositions/common/useTeleport.ts

@@ -0,0 +1,24 @@
+/**
+ * @description teleport hook
+ * @author 阿怪
+ * @date 2023/5/5 10:40
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { h, Teleport, TeleportProps, VNode } from 'vue';
+import { MTeleportProps } from '../../types/common/common';
+
+export default function useTeleport(options: {
+  teleportProps?: MTeleportProps | true,
+  slot: VNode | VNode[]
+}) {
+  return h(Teleport, initTeleportOptions(options.teleportProps as TeleportProps), options.slot);
+}
+
+export const initTeleportOptions = (options: TeleportProps | true | undefined) => {
+  if (options === true || options === undefined) {
+    return { to: 'body' };
+  }
+  return options;
+};

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