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

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 = '';
+      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,20 @@
+/**
+ * @description tooltip 运行时 props
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.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',
+  },
+  disabled: { type: Boolean, default: false },
+  maxWidth: { type: String, default: undefined },
+};

package/components/base/tooltip/index.ts

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

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

@@ -0,0 +1,40 @@
+/**
+ * @description tooltip 类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * @name m-tooltip
+ * @docDescription Tooltip component.
+ *                 文字提示组件。
+ * @docUrl https://shuimo.design/tooltip
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type TooltipProps = {
+  /**
+   * @description 提示内容，简单文本可直接通过 prop 传入
+   * @type string
+   * @default ''
+   */
+  content?: string;
+  /**
+   * @description 弹出位置
+   * @type 'top' | 'bottom' | 'left' | 'right'
+   * @default 'top'
+   */
+  placement?: 'top' | 'bottom' | 'left' | 'right';
+  /**
+   * @description 是否禁用
+   * @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,89 @@
+/**
+ * @description tooltip composable，管理 hover 显示/隐藏及定位
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { ref, nextTick } from 'vue';
+import { TooltipProps } from './props';
+
+export type TooltipStyle = {
+  position: string;
+  left: string;
+  top: string;
+  zIndex: string;
+};
+
+/**
+ * 根据 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;
+  }
+
+  return {
+    position: 'fixed',
+    left: `${left}px`,
+    top: `${top}px`,
+    zIndex: '9999',
+  };
+}
+
+export function useTooltip(props: Required<TooltipProps>) {
+  const visible = ref(false);
+  const tooltipStyle = ref<TooltipStyle | Record<string, never>>({});
+
+  const triggerRef = ref<HTMLElement | null>(null);
+  const tooltipRef = ref<HTMLElement | null>(null);
+
+  const show = async () => {
+    if (props.disabled) return;
+    visible.value = true;
+    // 等待 tooltip DOM 渲染后再计算位置
+    await nextTick();
+    if (!triggerRef.value || !tooltipRef.value) return;
+    const rect = triggerRef.value.getBoundingClientRect();
+    tooltipStyle.value = calcPosition(rect, tooltipRef.value, props.placement);
+  };
+
+  const hide = () => {
+    visible.value = false;
+    tooltipStyle.value = {};
+  };
+
+  return {
+    visible,
+    tooltipStyle,
+    triggerRef,
+    tooltipRef,
+    show,
+    hide,
+  };
+}

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: undefined },
+  filterable: { type: Boolean, default: false },
+  filterPlaceholder: { type: String, default: undefined },
+};

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