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

package/components/base/image/__tests__/useImage.test.ts

@@ -173,4 +173,65 @@ describe('useImage', () => {
     expect(previewScale.value).toBe(1);
     expect(previewRotate.value).toBe(0);
   });
+
+  // ── 混合媒体预览 ──
+
+  it('纯字符串列表 currentPreviewItem.type 为 image', () => {
+    const emit = createEmit();
+    const props = { ...defaultProps, src: 'a.png', previewSrcList: ['a.png', 'b.png'] };
+    const { currentPreviewItem, openPreview } = useImage(props, emit);
+
+    openPreview();
+    expect(currentPreviewItem.value).toEqual({ src: 'a.png', type: 'image' });
+  });
+
+  it('混合列表定位到 PreviewItem 对象', () => {
+    const emit = createEmit();
+    const props = {
+      ...defaultProps,
+      src: 'video.mp4',
+      previewSrcList: [
+        'a.png',
+        { src: 'video.mp4', type: 'video' as const },
+        'c.png',
+      ],
+    };
+    const { currentPreviewItem, currentPreviewIsVideo, previewIndex, openPreview } = useImage(props, emit);
+
+    openPreview();
+    expect(previewIndex.value).toBe(1);
+    expect(currentPreviewItem.value).toEqual({ src: 'video.mp4', type: 'video' });
+    expect(currentPreviewIsVideo.value).toBe(true);
+  });
+
+  it('切换时 currentPreviewIsVideo 跟随变化', () => {
+    const emit = createEmit();
+    const props = {
+      ...defaultProps,
+      src: 'a.png',
+      previewSrcList: [
+        'a.png',
+        { src: 'video.mp4', type: 'video' as const },
+      ],
+    };
+    const { currentPreviewIsVideo, openPreview, previewNext } = useImage(props, emit);
+
+    openPreview();
+    expect(currentPreviewIsVideo.value).toBe(false);
+
+    previewNext();
+    expect(currentPreviewIsVideo.value).toBe(true);
+  });
+
+  it('PreviewItem 不指定 type 时默认为 image', () => {
+    const emit = createEmit();
+    const props = {
+      ...defaultProps,
+      previewSrcList: [{ src: 'photo.jpg' }],
+    };
+    const { currentPreviewItem, openPreview } = useImage(props, emit);
+
+    openPreview();
+    expect(currentPreviewItem.value.type).toBe('image');
+  });
 });

package/components/base/image/api.ts

@@ -7,7 +7,7 @@
  * 江湖的业务千篇一律，复杂的代码好几百行。
  */
 import { MCOPO, MPropType } from '../../types/props';
-import { ImageProps } from './props';
+import { ImageProps, PreviewSrcListItem } from './props';
 
 export const props: MCOPO<ImageProps> = {
   src: { type: String, required: true },
@@ -20,6 +20,6 @@ export const props: MCOPO<ImageProps> = {
   width: { type: [String, Number], default: undefined },
   height: { type: [String, Number], default: undefined },
   lazy: { type: Boolean, default: false },
-  previewSrcList: { type: Array as MPropType<string[]>, default: () => [] },
+  previewSrcList: { type: Array as MPropType<PreviewSrcListItem[]>, default: () => [] },
   zIndex: { type: Number, default: 2000 },
 };

package/components/base/image/index.ts

@@ -14,5 +14,5 @@ export const ImageCore = {
   useImage,
 };
 
-export type { ImageProps, ImageEvents } from './props';
-export type { ImageLoadStatus } from './useImage';
+export type { ImageProps, ImageEvents, PreviewItem, PreviewSrcListItem } from './props';
+export type { ImageLoadStatus, NormalizedPreviewItem } from './useImage';

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

@@ -6,11 +6,21 @@
  *
  * @name m-image
  * @docDescription Image component with lazy loading and preview support.
- *                 图片组件，支持懒加载和全屏预览。
+ *                 图片组件，支持懒加载和全屏预览。支持图片与视频混合预览。
  *
  * 江湖的业务千篇一律，复杂的代码好几百行。
  */
 
+/**
+ * @description 预览列表项，支持纯字符串（向后兼容，视为图片）或结构化对象
+ */
+export declare type PreviewItem = {
+  src: string,
+  type?: 'image' | 'video',
+};
+
+export declare type PreviewSrcListItem = string | PreviewItem;
+
 export declare type ImageProps = {
   /**
    * @description 图片地址
@@ -37,11 +47,12 @@ export declare type ImageProps = {
    */
   lazy?: boolean,
   /**
-   * @description 开启预览的图片列表，传入后点击可全屏预览
-   * @type string[]
+   * @description 开启预览的媒体列表，传入后点击可全屏预览。
+   *              支持纯字符串（向后兼容，视为图片）或 { src, type } 对象。
+   * @type (string | PreviewItem)[]
    * @default []
    */
-  previewSrcList?: string[],
+  previewSrcList?: PreviewSrcListItem[],
   /**
    * @description 图片宽度
    * @type string | number

package/components/base/image/useImage.ts

@@ -6,27 +6,44 @@
  *
  * 江湖的业务千篇一律，复杂的代码好几百行。
  */
-import { ref, watch, onMounted } from 'vue';
-import { ImageProps } from './props';
+import { ref, computed, watch, onMounted } from 'vue';
+import { ImageProps, PreviewSrcListItem } from './props';
 
 /** 图片加载状态 */
 export type ImageLoadStatus = 'loading' | 'loaded' | 'error';
 
+/** 正规化后的预览项 */
+export type NormalizedPreviewItem = { src: string; type: 'image' | 'video' };
+
+function normalizeItem(item: PreviewSrcListItem): NormalizedPreviewItem {
+  if (typeof item === 'string') {
+    return { src: item, type: 'image' };
+  }
+  return { src: item.src, type: item.type ?? 'image' };
+}
+
+function getSrc(item: PreviewSrcListItem): string {
+  return typeof item === 'string' ? item : item.src;
+}
+
 export function useImage(
   props: Required<ImageProps>,
   emit: (event: 'load' | 'error' | 'switch', payload: Event | number) => void,
 ) {
   const status = ref<ImageLoadStatus>('loading');
-  // 预览弹层是否可见
   const previewVisible = ref(false);
-  // 预览当前索引（在 previewSrcList 中的位置）
   const previewIndex = ref(0);
-  // 预览缩放比例
   const previewScale = ref(1);
-  // 预览旋转角度
   const previewRotate = ref(0);
 
-  /** 重置加载状态（src 变化时调用） */
+  const currentPreviewItem = computed<NormalizedPreviewItem>(() => {
+    const list = props.previewSrcList;
+    if (!list || list.length === 0) { return { src: '', type: 'image' }; }
+    return normalizeItem(list[previewIndex.value] ?? list[0]);
+  });
+
+  const currentPreviewIsVideo = computed(() => currentPreviewItem.value.type === 'video');
+
   const reset = () => {
     status.value = 'loading';
   };
@@ -41,10 +58,9 @@ export function useImage(
     emit('error', e);
   };
 
-  /** 打开全屏预览，定位到 src 在 previewSrcList 中的位置 */
   const openPreview = () => {
     if (!props.previewSrcList || props.previewSrcList.length === 0) { return; }
-    const idx = props.previewSrcList.indexOf(props.src);
+    const idx = props.previewSrcList.findIndex(item => getSrc(item) === props.src);
     previewIndex.value = idx >= 0 ? idx : 0;
     previewScale.value = 1;
     previewRotate.value = 0;
@@ -55,7 +71,6 @@ export function useImage(
     previewVisible.value = false;
   };
 
-  /** 预览切换到上一张 */
   const previewPrev = () => {
     const total = props.previewSrcList.length;
     if (total === 0) { return; }
@@ -65,7 +80,6 @@ export function useImage(
     emit('switch', previewIndex.value);
   };
 
-  /** 预览切换到下一张 */
   const previewNext = () => {
     const total = props.previewSrcList.length;
     if (total === 0) { return; }
@@ -75,27 +89,22 @@ export function useImage(
     emit('switch', previewIndex.value);
   };
 
-  /** 预览放大 */
   const zoomIn = () => {
     previewScale.value = Math.min(previewScale.value + 0.25, 5);
   };
 
-  /** 预览缩小 */
   const zoomOut = () => {
     previewScale.value = Math.max(previewScale.value - 0.25, 0.25);
   };
 
-  /** 顺时针旋转 90° */
   const rotate = () => {
     previewRotate.value = (previewRotate.value + 90) % 360;
   };
 
-  // src 变化时重置加载状态
   watch(() => props.src, reset);
 
   onMounted(() => {
     if (props.lazy) {
-      // 懒加载：交由 img 标签的 loading="lazy" 处理
       status.value = 'loading';
     }
   });
@@ -106,6 +115,8 @@ export function useImage(
     previewIndex,
     previewScale,
     previewRotate,
+    currentPreviewItem,
+    currentPreviewIsVideo,
     handleLoad,
     handleError,
     openPreview,

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