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

package/components/base/timePicker/useTimePicker.ts

@@ -0,0 +1,161 @@
+/**
+ * @description timePicker 核心 composable
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 纯时间数据管理，不含任何 popover 逻辑。
+ */
+import dayjs from 'dayjs';
+import { computed, ref } from 'vue';
+import { TimePickerProps, TimeRefType } from './props';
+
+/** 简单的空值判断 */
+const isEmpty = (value: unknown): boolean => {
+  return value === '' || value === null || value === undefined;
+};
+
+/**
+ * 生成一列可选数字数组。
+ * @param max 最大值（不含），如 24、60
+ * @param step 步长
+ */
+export const generateColumn = (max: number, step: number): number[] => {
+  const result: number[] = [];
+  for (let i = 0; i < max; i += step) {
+    result.push(i);
+  }
+  return result;
+};
+
+export function useTimePicker(props: TimePickerProps) {
+  const resolvedProps = props as Required<TimePickerProps>;
+
+  /** 内部时间状态 */
+  const timeRef = ref<TimeRefType>({
+    hours: 0,
+    minutes: 0,
+    seconds: 0,
+  });
+
+  /** trigger 显示的格式化文本 */
+  const displayValue = ref('');
+
+  /** trigger span 的 class 列表（含 placeholder 状态） */
+  const spanClass = ref<Array<string | undefined>>([]);
+
+  /** 是否处于 placeholder 状态 */
+  let needPlaceholder = false;
+
+  /** 根据 showSeconds 和 format prop 计算实际使用的时间格式 */
+  const format = computed(() => {
+    if (resolvedProps.format) return resolvedProps.format;
+    return resolvedProps.showSeconds ? 'HH:mm:ss' : 'HH:mm';
+  });
+
+  /** 生成时列数据 */
+  const hoursColumn = computed(() => generateColumn(24, resolvedProps.hourStep));
+  /** 生成分列数据 */
+  const minutesColumn = computed(() => generateColumn(60, resolvedProps.minuteStep));
+  /** 生成秒列数据 */
+  const secondsColumn = computed(() => generateColumn(60, resolvedProps.secondStep));
+
+  /**
+   * 根据传入值更新内部状态。
+   * 支持 "HH:mm:ss"、"HH:mm" 格式字符串。
+   */
+  const updateTimeRef = (value: string | undefined) => {
+    if (isEmpty(value)) {
+      displayValue.value = resolvedProps.placeholder ?? '请选择时间...';
+      needPlaceholder = true;
+    } else {
+      needPlaceholder = false;
+      // 用 dayjs 解析任意时间格式
+      const parsed = dayjs(`2000-01-01 ${value}`);
+      if (parsed.isValid()) {
+        timeRef.value = {
+          hours: parsed.hour(),
+          minutes: parsed.minute(),
+          seconds: parsed.second(),
+        };
+        displayValue.value = parsed.format(format.value);
+      } else {
+        // 兜底：尝试手动解析 HH:mm[:ss]
+        const parts = (value as string).split(':').map(Number);
+        if (parts.length >= 2 && !isNaN(parts[0]) && !isNaN(parts[1])) {
+          timeRef.value = {
+            hours: parts[0],
+            minutes: parts[1],
+            seconds: parts[2] ?? 0,
+          };
+          displayValue.value = formatTime(timeRef.value);
+        }
+      }
+    }
+    spanClass.value = [
+      'm-time-picker-span',
+      needPlaceholder ? 'm-time-picker-placeholder' : undefined,
+    ];
+  };
+
+  /** 将 TimeRefType 格式化为字符串 */
+  const formatTime = (time: TimeRefType): string => {
+    const d = dayjs()
+      .set('hour', time.hours)
+      .set('minute', time.minutes)
+      .set('second', time.seconds);
+    return d.format(format.value);
+  };
+
+  /** 选择小时 */
+  const selectHour = (hour: number) => {
+    timeRef.value = { ...timeRef.value, hours: hour };
+    needPlaceholder = false;
+    displayValue.value = formatTime(timeRef.value);
+    spanClass.value = ['m-time-picker-span'];
+  };
+
+  /** 选择分钟 */
+  const selectMinute = (minute: number) => {
+    timeRef.value = { ...timeRef.value, minutes: minute };
+    needPlaceholder = false;
+    displayValue.value = formatTime(timeRef.value);
+    spanClass.value = ['m-time-picker-span'];
+  };
+
+  /** 选择秒 */
+  const selectSecond = (second: number) => {
+    timeRef.value = { ...timeRef.value, seconds: second };
+    needPlaceholder = false;
+    displayValue.value = formatTime(timeRef.value);
+    spanClass.value = ['m-time-picker-span'];
+  };
+
+  /** 获取当前格式化后的时间值（用于 emit） */
+  const getValue = (): string => {
+    return formatTime(timeRef.value);
+  };
+
+  // 初始化
+  updateTimeRef(resolvedProps.modelValue);
+
+  return {
+    // 状态
+    timeRef,
+    displayValue,
+    spanClass,
+    // 列数据
+    hoursColumn,
+    minutesColumn,
+    secondsColumn,
+    // 方法
+    updateTimeRef,
+    selectHour,
+    selectMinute,
+    selectSecond,
+    getValue,
+    formatTime,
+  };
+}

package/components/base/timeline/api.ts

@@ -0,0 +1,24 @@
+/**
+ * @description timeline api
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { TimelineProps, TimelineItemProps } from './props';
+
+export const timelineProps: MCOPO<TimelineProps> = {
+  reverse: { type: Boolean, default: false },
+};
+
+export const timelineItemProps: MCOPO<TimelineItemProps> = {
+  timestamp: { type: String, default: '' },
+  hideTimestamp: { type: Boolean, default: false },
+  placement: { type: String as MPropType<'top' | 'bottom'>, default: 'bottom' },
+  type: { type: String as MPropType<'primary' | 'success' | 'warning' | 'danger' | 'info'>, default: 'primary' },
+  size: { type: String as MPropType<'normal' | 'large'>, default: 'normal' },
+  icon: { type: String, default: '' },
+  hollow: { type: Boolean, default: false },
+};

package/components/base/timeline/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @description timeline core 导出
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { timelineProps, timelineItemProps } from './api';
+
+export const TimelineCore = {
+  timelineProps,
+  timelineItemProps,
+};
+
+export type { TimelineProps, TimelineItemProps } from './props';

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

@@ -0,0 +1,60 @@
+/**
+ * @description timeline api type
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type TimelineProps = {
+  /**
+   * @description 是否倒序排列
+   * @type boolean
+   * @default false
+   */
+  reverse?: boolean,
+};
+
+export declare type TimelineItemProps = {
+  /**
+   * @description 时间戳文本
+   * @type string
+   */
+  timestamp?: string,
+  /**
+   * @description 是否隐藏时间戳
+   * @type boolean
+   * @default false
+   */
+  hideTimestamp?: boolean,
+  /**
+   * @description 时间戳相对内容的位置
+   * @type 'top' | 'bottom'
+   * @default 'bottom'
+   */
+  placement?: 'top' | 'bottom',
+  /**
+   * @description 节点类型，影响圆点颜色
+   * @type 'primary' | 'success' | 'warning' | 'danger' | 'info'
+   * @default 'primary'
+   */
+  type?: 'primary' | 'success' | 'warning' | 'danger' | 'info',
+  /**
+   * @description 节点尺寸
+   * @type 'normal' | 'large'
+   * @default 'normal'
+   */
+  size?: 'normal' | 'large',
+  /**
+   * @description 自定义图标（图标名或内容，由消费层解释）
+   * @type string
+   */
+  icon?: string,
+  /**
+   * @description 是否为空心圆点
+   * @type boolean
+   * @default false
+   */
+  hollow?: boolean,
+};

package/components/base/tooltip/api.ts

@@ -0,0 +1,21 @@
+/**
+ * @description tooltip runtime props
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v2.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { TooltipProps } from './props';
+import { MCOPO, MPropType } from '../../types/props';
+
+export const props: MCOPO<TooltipProps> = {
+  content: { type: String, default: '' },
+  placement: {
+    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

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

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

@@ -0,0 +1,46 @@
+/**
+ * @description tooltip type definitions
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v2.0.0
+ *
+ * @name m-tooltip
+ * @docDescription Tooltip component.
+ *                 文字提示组件。
+ * @docUrl https://shuimo.design/tooltip
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type TooltipProps = {
+  /**
+   * @description tooltip text content
+   * @type string
+   * @default ''
+   */
+  content?: string;
+  /**
+   * @description preferred placement direction
+   * @type 'top' | 'bottom' | 'left' | 'right'
+   * @default 'top'
+   */
+  placement?: 'top' | 'bottom' | 'left' | 'right';
+  /**
+   * @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
+   * @type string
+   * @default undefined
+   */
+  maxWidth?: string;
+};

package/components/base/tooltip/useTooltip.ts

@@ -0,0 +1,208 @@
+/**
+ * @description tooltip composable — manages show/hide with delay, positioning via usePopper, singleton, scroll/interaction dismissal
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v2.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+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';
+
+const HIDE_DELAY = 100;
+
+/** Singleton: only one tooltip visible at a time */
+let activeHide: (() => void) | null = null;
+
+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 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;
+    }
+  };
+
+  /** 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;
+    activeHide = hideImmediate;
+    addInteractionListeners();
+    addScrollListeners();
+  };
+
+  /** Initialize popper positioning — called after tooltip DOM is mounted */
+  const initPopper = () => {
+    if (!triggerRef.value || !tooltipRef.value) return;
+
+    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 = () => {
+    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,
+    positionData,
+    triggerRef,
+    tooltipRef,
+    arrowRef,
+    tooltipId,
+    show,
+    hide,
+    hideImmediate,
+    initPopper,
+  };
+}

package/components/base/transfer/api.ts

@@ -0,0 +1,18 @@
+/**
+ * @description transfer api
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { TransferProps, TransferItem } from './props';
+
+export const props: MCOPO<TransferProps> = {
+  modelValue: { type: Array as MPropType<(string | number)[]>, default: () => [] },
+  data: { type: Array as MPropType<TransferItem[]>, default: () => [] },
+  titles: { type: Array as unknown as MPropType<[string, string]>, default: () => ['源列表', '目标列表'] },
+  filterable: { type: Boolean, default: false },
+  filterPlaceholder: { type: String, default: '请输入搜索内容' },
+};

package/components/base/transfer/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @description transfer core 导出
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { props } from './api';
+import { useTransfer } from './useTransfer';
+
+export const TransferCore = {
+  props,
+  useTransfer,
+};
+
+export type { TransferProps, TransferItem } from './props';

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

@@ -0,0 +1,63 @@
+/**
+ * @description transfer api type
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+/**
+ * 穿梭框的数据项
+ */
+export declare type TransferItem = {
+  /**
+   * @description 数据项唯一标识
+   * @type string | number
+   */
+  key: string | number;
+  /**
+   * @description 数据项显示文本
+   * @type string
+   */
+  label: string;
+  /**
+   * @description 是否禁用该项
+   * @type boolean
+   * @default false
+   */
+  disabled?: boolean;
+};
+
+export declare type TransferProps = {
+  /**
+   * @description 右侧已选中的数据 key 列表
+   * @type (string | number)[]
+   * @default []
+   */
+  modelValue?: (string | number)[];
+  /**
+   * @description 数据源
+   * @type TransferItem[]
+   * @default []
+   */
+  data?: TransferItem[];
+  /**
+   * @description 左右栏的标题
+   * @type [string, string]
+   * @default ['源列表', '目标列表']
+   */
+  titles?: [string, string];
+  /**
+   * @description 是否可搜索
+   * @type boolean
+   * @default false
+   */
+  filterable?: boolean;
+  /**
+   * @description 搜索框占位文本
+   * @type string
+   * @default '请输入搜索内容'
+   */
+  filterPlaceholder?: string;
+};