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

package/components/base/tooltip/api.ts

@@ -1,8 +1,8 @@
 /**
- * @description tooltip 运行时 props
+ * @description tooltip runtime props
  * @author 阿怪
  * @date 2026/2/25
- * @version v1.0.0
+ * @version v2.0.0
  *
  * 江湖的业务千篇一律，复杂的代码好几百行。
  */
@@ -15,6 +15,7 @@ export const props: MCOPO<TooltipProps> = {
     type: String as MPropType<NonNullable<TooltipProps['placement']>>,
     default: 'top',
   },
+  delay: { type: Number, default: 300 },
   disabled: { type: Boolean, default: false },
   maxWidth: { type: String, default: undefined },
 };

package/components/base/tooltip/index.ts

@@ -1,8 +1,8 @@
 /**
- * @description tooltip core 导出
+ * @description tooltip core barrel export
  * @author 阿怪
  * @date 2026/2/25
- * @version v1.0.0
+ * @version v2.0.0
  *
  * 江湖的业务千篇一律，复杂的代码好几百行。
  */
@@ -15,3 +15,4 @@ export const TooltipCore = {
 };
 
 export type { TooltipProps } from './props';
+export type { TooltipPlacement, TooltipPositionData } from './useTooltip';

package/components/base/tooltip/props.d.ts

@@ -1,8 +1,8 @@
 /**
- * @description tooltip 类型定义
+ * @description tooltip type definitions
  * @author 阿怪
  * @date 2026/2/25
- * @version v1.0.0
+ * @version v2.0.0
  *
  * @name m-tooltip
  * @docDescription Tooltip component.
@@ -14,25 +14,31 @@
 
 export declare type TooltipProps = {
   /**
-   * @description 提示内容，简单文本可直接通过 prop 传入
+   * @description tooltip text content
    * @type string
    * @default ''
    */
   content?: string;
   /**
-   * @description 弹出位置
+   * @description preferred placement direction
    * @type 'top' | 'bottom' | 'left' | 'right'
    * @default 'top'
    */
   placement?: 'top' | 'bottom' | 'left' | 'right';
   /**
-   * @description 是否禁用
+   * @description show delay in milliseconds
+   * @type number
+   * @default 300
+   */
+  delay?: number;
+  /**
+   * @description whether the tooltip is disabled
    * @type boolean
    * @default false
    */
   disabled?: boolean;
   /**
-   * @description max width of tooltip content. 浮层最大宽度
+   * @description max width of tooltip content
    * @type string
    * @default undefined
    */

package/components/base/tooltip/useTooltip.ts

@@ -1,89 +1,208 @@
 /**
- * @description tooltip composable，管理 hover 显示/隐藏及定位
+ * @description tooltip composable — manages show/hide with delay, positioning via usePopper, singleton, scroll/interaction dismissal
  * @author 阿怪
  * @date 2026/2/25
- * @version v1.0.0
+ * @version v2.0.0
  *
  * 江湖的业务千篇一律，复杂的代码好几百行。
  */
-import { ref, nextTick } from 'vue';
+import { ref, onBeforeUnmount } from 'vue';
+import { flip, offset, shift } from '@floating-ui/dom';
+import { usePopper, type Placement, type PositionStyle } from '../../../compositions/popper/usePopper';
 import { TooltipProps } from './props';
 
-export type TooltipStyle = {
-  position: string;
-  left: string;
-  top: string;
-  zIndex: string;
-};
+const HIDE_DELAY = 100;
 
-/**
- * 根据 trigger 元素的 getBoundingClientRect 和 placement 计算 tooltip 的 fixed 定位样式
- */
-function calcPosition(
-  rect: DOMRect,
-  tooltipEl: HTMLElement,
-  placement: NonNullable<TooltipProps['placement']>,
-): TooltipStyle {
-  const gap = 8;
-  const tooltipRect = tooltipEl.getBoundingClientRect();
-  let left = 0;
-  let top = 0;
-
-  switch (placement) {
-    case 'top':
-      left = rect.left + rect.width / 2 - tooltipRect.width / 2;
-      top = rect.top - tooltipRect.height - gap;
-      break;
-    case 'bottom':
-      left = rect.left + rect.width / 2 - tooltipRect.width / 2;
-      top = rect.bottom + gap;
-      break;
-    case 'left':
-      left = rect.left - tooltipRect.width - gap;
-      top = rect.top + rect.height / 2 - tooltipRect.height / 2;
-      break;
-    case 'right':
-      left = rect.right + gap;
-      top = rect.top + rect.height / 2 - tooltipRect.height / 2;
-      break;
-  }
+/** Singleton: only one tooltip visible at a time */
+let activeHide: (() => void) | null = null;
 
-  return {
-    position: 'fixed',
-    left: `${left}px`,
-    top: `${top}px`,
-    zIndex: '9999',
-  };
-}
+export type TooltipPlacement = Placement;
+
+export type TooltipPositionData = {
+  style: Record<string, string>;
+  arrowStyle: Record<string, string>;
+  placement: Placement;
+};
 
 export function useTooltip(props: Required<TooltipProps>) {
   const visible = ref(false);
-  const tooltipStyle = ref<TooltipStyle | Record<string, never>>({});
+  const positionData = ref<TooltipPositionData | null>(null);
 
   const triggerRef = ref<HTMLElement | null>(null);
   const tooltipRef = ref<HTMLElement | null>(null);
+  const arrowRef = ref<HTMLElement | null>(null);
+
+  let showTimer: ReturnType<typeof setTimeout> | null = null;
+  let hideTimer: ReturnType<typeof setTimeout> | null = null;
+  let popperCleanup: (() => void) | null = null;
+
+  const tooltipId = `k-tooltip-${Math.random().toString(36).slice(2, 10)}`;
+
+  /** Clean up popper auto-update subscription */
+  const destroyPopper = () => {
+    if (popperCleanup) {
+      popperCleanup();
+      popperCleanup = null;
+    }
+  };
 
-  const show = async () => {
+  /** Immediately hide — no delay */
+  const hideImmediate = () => {
+    clearTimers();
+    visible.value = false;
+    positionData.value = null;
+    destroyPopper();
+    if (activeHide === hideImmediate) {
+      activeHide = null;
+    }
+    removeInteractionListeners();
+    removeScrollListeners();
+  };
+
+  /** Show tooltip after delay */
+  const show = () => {
     if (props.disabled) return;
+
+    // Dismiss any existing tooltip (singleton)
+    if (activeHide && activeHide !== hideImmediate) {
+      activeHide();
+    }
+
+    if (hideTimer) {
+      clearTimeout(hideTimer);
+      hideTimer = null;
+    }
+
+    if (visible.value) return;
+
+    const delay = props.delay ?? 300;
+    showTimer = setTimeout(() => {
+      showTimer = null;
+      if (props.disabled) return;
+      doShow();
+    }, delay);
+  };
+
+  /** Actually display the tooltip and set up popper */
+  const doShow = () => {
     visible.value = true;
-    // 等待 tooltip DOM 渲染后再计算位置
-    await nextTick();
+    activeHide = hideImmediate;
+    addInteractionListeners();
+    addScrollListeners();
+  };
+
+  /** Initialize popper positioning — called after tooltip DOM is mounted */
+  const initPopper = () => {
     if (!triggerRef.value || !tooltipRef.value) return;
-    const rect = triggerRef.value.getBoundingClientRect();
-    tooltipStyle.value = calcPosition(rect, tooltipRef.value, props.placement);
+
+    destroyPopper();
+
+    const { clear } = usePopper(
+      triggerRef.value,
+      tooltipRef.value,
+      (data: PositionStyle) => {
+        positionData.value = {
+          style: { ...data.style },
+          arrowStyle: { ...data.arrowStyle },
+          placement: data.placement,
+        };
+      },
+      arrowRef.value ?? undefined,
+      {
+        placement: props.placement as Placement,
+        middleware: [
+          offset(8),
+          flip(),
+          shift({ padding: 8 }),
+        ],
+      },
+    );
+
+    popperCleanup = clear;
   };
 
+  /** Hide tooltip with a short delay (allows cursor to move between trigger and tooltip) */
   const hide = () => {
-    visible.value = false;
-    tooltipStyle.value = {};
+    if (showTimer) {
+      clearTimeout(showTimer);
+      showTimer = null;
+    }
+
+    if (!visible.value) return;
+
+    hideTimer = setTimeout(() => {
+      hideTimer = null;
+      hideImmediate();
+    }, HIDE_DELAY);
+  };
+
+  const clearTimers = () => {
+    if (showTimer) {
+      clearTimeout(showTimer);
+      showTimer = null;
+    }
+    if (hideTimer) {
+      clearTimeout(hideTimer);
+      hideTimer = null;
+    }
   };
 
+  /* ── Interaction listeners: dismiss on click / keydown ── */
+  const onInteraction = () => {
+    hideImmediate();
+  };
+
+  const addInteractionListeners = () => {
+    document.addEventListener('mousedown', onInteraction, true);
+    document.addEventListener('keydown', onInteraction, true);
+  };
+
+  const removeInteractionListeners = () => {
+    document.removeEventListener('mousedown', onInteraction, true);
+    document.removeEventListener('keydown', onInteraction, true);
+  };
+
+  /* ── Scroll listeners: dismiss when trigger scrolls out of view ── */
+  const onScroll = () => {
+    if (!triggerRef.value) {
+      hideImmediate();
+      return;
+    }
+    const rect = triggerRef.value.getBoundingClientRect();
+    const inView =
+      rect.bottom > 0 &&
+      rect.top < window.innerHeight &&
+      rect.right > 0 &&
+      rect.left < window.innerWidth;
+    if (!inView) {
+      hideImmediate();
+    }
+  };
+
+  const addScrollListeners = () => {
+    window.addEventListener('scroll', onScroll, true);
+    window.addEventListener('resize', onScroll, true);
+  };
+
+  const removeScrollListeners = () => {
+    window.removeEventListener('scroll', onScroll, true);
+    window.removeEventListener('resize', onScroll, true);
+  };
+
+  onBeforeUnmount(() => {
+    hideImmediate();
+  });
+
   return {
     visible,
-    tooltipStyle,
+    positionData,
     triggerRef,
     tooltipRef,
+    arrowRef,
+    tooltipId,
     show,
     hide,
+    hideImmediate,
+    initPopper,
   };
 }

package/compositions/commandPalette/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @description commandPalette composition barrel export
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { useCommandPalette } from './useCommandPalette';
+export type { UseCommandPaletteReturn } from './useCommandPalette';
+export type { Command } from './types';

package/compositions/commandPalette/types.ts

@@ -0,0 +1,29 @@
+/**
+ * @description CommandPalette command type definitions
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import type { VNode } from 'vue';
+
+/**
+ * A single command registered in the palette.
+ */
+export interface Command {
+  /** Unique identifier */
+  id: string;
+  /** Display label (also used for search) */
+  label: string;
+  /** Optional icon render function */
+  icon?: () => VNode;
+  /** Additional search terms beyond the label */
+  keywords?: string[];
+  /** Grouping category (e.g. "Navigation", "Actions") */
+  group?: string;
+  /** Shortcut hint text displayed on the right side of the item */
+  shortcut?: string;
+  /** Callback executed when the command is selected */
+  action: () => void;
+}

package/compositions/commandPalette/useCommandPalette.ts

@@ -0,0 +1,135 @@
+/**
+ * @description CommandPalette composable — global search + command execution
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * Manages open/close state, command registration, query filtering, and execution.
+ * Does NOT participate in overlayStack — fixed z-index 9500.
+ */
+import { ref, computed, type Ref, type ComputedRef } from 'vue';
+import type { Command } from './types';
+
+export interface UseCommandPaletteReturn {
+  /** Whether the palette is open */
+  isOpen: Ref<boolean>;
+  /** Current search query */
+  query: Ref<string>;
+  /** Index of the currently highlighted item */
+  activeIndex: Ref<number>;
+  /** All registered commands */
+  commands: Ref<Command[]>;
+  /** Filtered commands based on query */
+  filtered: ComputedRef<Command[]>;
+  /** Open the palette */
+  open: () => void;
+  /** Close the palette */
+  close: () => void;
+  /** Toggle open/close */
+  toggle: () => void;
+  /** Register a command */
+  registerCommand: (cmd: Command) => void;
+  /** Unregister a command by id */
+  unregisterCommand: (id: string) => void;
+  /** Execute the command at a given index in the filtered list, then close */
+  execute: (index: number) => void;
+}
+
+/**
+ * CommandPalette composable
+ *
+ * Provides reactive state for opening, searching, and executing commands.
+ */
+export function useCommandPalette(): UseCommandPaletteReturn {
+  const isOpen = ref(false);
+  const query = ref('');
+  const activeIndex = ref(0);
+  const commands = ref<Command[]>([]);
+
+  /** element that had focus before the palette opened */
+  let previousActiveElement: Element | null = null;
+
+  const open = () => {
+    previousActiveElement = document.activeElement;
+    isOpen.value = true;
+    query.value = '';
+    activeIndex.value = 0;
+  };
+
+  const close = () => {
+    isOpen.value = false;
+    query.value = '';
+    activeIndex.value = 0;
+    // restore focus to the previously focused element
+    if (previousActiveElement && previousActiveElement instanceof HTMLElement) {
+      previousActiveElement.focus();
+    }
+    previousActiveElement = null;
+  };
+
+  const toggle = () => {
+    if (isOpen.value) {
+      close();
+    } else {
+      open();
+    }
+  };
+
+  const registerCommand = (cmd: Command) => {
+    // prevent duplicates
+    const exists = commands.value.some(c => c.id === cmd.id);
+    if (!exists) {
+      commands.value.push(cmd);
+    }
+  };
+
+  const unregisterCommand = (id: string) => {
+    const idx = commands.value.findIndex(c => c.id === id);
+    if (idx !== -1) {
+      commands.value.splice(idx, 1);
+    }
+  };
+
+  /**
+   * Simple case-insensitive substring match on label + keywords.
+   */
+  const filtered = computed<Command[]>(() => {
+    const q = query.value.trim().toLowerCase();
+    if (!q) {
+      return commands.value;
+    }
+    return commands.value.filter(cmd => {
+      if (cmd.label.toLowerCase().includes(q)) {
+        return true;
+      }
+      if (cmd.keywords) {
+        return cmd.keywords.some(kw => kw.toLowerCase().includes(q));
+      }
+      return false;
+    });
+  });
+
+  const execute = (index: number) => {
+    const cmd = filtered.value[index];
+    if (cmd) {
+      close();
+      cmd.action();
+    }
+  };
+
+  return {
+    isOpen,
+    query,
+    activeIndex,
+    commands,
+    filtered,
+    open,
+    close,
+    toggle,
+    registerCommand,
+    unregisterCommand,
+    execute,
+  };
+}

package/compositions/contextMenu/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @description context menu composables barrel export
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { useContextMenu } from './useContextMenu';
+export type { MenuItem } from './types';

package/compositions/contextMenu/types.ts

@@ -0,0 +1,21 @@
+/**
+ * @description context menu types
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import type { VNode } from 'vue';
+
+export interface MenuItem {
+  key: string;
+  label: string;
+  icon?: () => VNode;
+  action: () => void;
+  visible?: boolean;
+  disabled?: boolean;
+  danger?: boolean;
+  children?: MenuItem[];
+  separator?: boolean;
+}

package/compositions/contextMenu/useContextMenu.ts

@@ -0,0 +1,101 @@
+/**
+ * @description context menu composable — manages open/close state, positioning, and keyboard navigation
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { ref, computed } from 'vue';
+import type { MenuItem } from './types';
+
+export function useContextMenu() {
+  const isOpen = ref(false);
+  const position = ref({ x: 0, y: 0 });
+  const items = ref<MenuItem[]>([]);
+  const activeIndex = ref(-1);
+
+  const visibleItems = computed(() =>
+    items.value.filter(item => item.visible !== false),
+  );
+
+  const open = (event: MouseEvent, menuItems: MenuItem[]) => {
+    event.preventDefault();
+    event.stopPropagation();
+
+    items.value = menuItems;
+    activeIndex.value = -1;
+
+    // Calculate position with viewport edge flipping
+    const x = event.clientX;
+    const y = event.clientY;
+
+    position.value = { x, y };
+    isOpen.value = true;
+  };
+
+  const close = () => {
+    isOpen.value = false;
+    activeIndex.value = -1;
+  };
+
+  const moveUp = () => {
+    const visible = visibleItems.value;
+    if (visible.length === 0) return;
+
+    let next = activeIndex.value - 1;
+    // Skip separators
+    while (next >= 0 && visible[next]?.separator) {
+      next--;
+    }
+    if (next < 0) {
+      // Wrap to last non-separator item
+      next = visible.length - 1;
+      while (next >= 0 && visible[next]?.separator) {
+        next--;
+      }
+    }
+    activeIndex.value = next;
+  };
+
+  const moveDown = () => {
+    const visible = visibleItems.value;
+    if (visible.length === 0) return;
+
+    let next = activeIndex.value + 1;
+    // Skip separators
+    while (next < visible.length && visible[next]?.separator) {
+      next++;
+    }
+    if (next >= visible.length) {
+      // Wrap to first non-separator item
+      next = 0;
+      while (next < visible.length && visible[next]?.separator) {
+        next++;
+      }
+    }
+    activeIndex.value = next;
+  };
+
+  const executeCurrent = () => {
+    const visible = visibleItems.value;
+    const item = visible[activeIndex.value];
+    if (item && !item.disabled && !item.separator) {
+      item.action();
+      close();
+    }
+  };
+
+  return {
+    isOpen,
+    position,
+    items,
+    activeIndex,
+    visibleItems,
+    open,
+    close,
+    moveUp,
+    moveDown,
+    executeCurrent,
+  };
+}

package/compositions/editor/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @description Editor composition barrel export
+ * @author kine-design
+ * @date 2026/5/22
+ * @version v1.0.0
+ *
+ * Headless editor composable — provides logic, no rendering.
+ */
+export { useEditor } from './useEditor';
+export type {
+  UseEditorOptions,
+  EditorConfig,
+  EditorToolbarConfig,
+  EditorExtensionConfig,
+  EditorToolbarActions,
+  EditorActiveState,
+  UseEditorReturn,
+} from './types';