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

package/components/base/datePicker/useDatePicker.ts

@@ -0,0 +1,392 @@
+/**
+ * @description datePicker 核心 composable
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 从 lib/useDatePicker 移植，去掉 usePopover / useBorder 依赖。
+ * 纯日历数据管理，不含任何 popover 逻辑。
+ */
+import dayjs from 'dayjs';
+import { computed, ref, Ref } from 'vue';
+import { DatePickerProps, CalendarType, DateRefType, CalendarItem } from './props';
+
+/** 时间部分的内部状态 */
+export type TimeRefType = {
+  hours: number;
+  minutes: number;
+  seconds: number;
+};
+
+/** 基础星期头（汉字显示） */
+export const BASE_WEEK_NAME: Array<{ day: string; isCurrentMonth: boolean }> = [
+  { day: '日', isCurrentMonth: true },
+  { day: '壹', isCurrentMonth: true },
+  { day: '贰', isCurrentMonth: true },
+  { day: '叁', isCurrentMonth: true },
+  { day: '肆', isCurrentMonth: true },
+  { day: '伍', isCurrentMonth: true },
+  { day: '陆', isCurrentMonth: true },
+];
+
+/** 月份名称 */
+export const BASE_MONTH_NAME = [
+  '1月', '2月', '3月', '4月', '5月', '6月',
+  '7月', '8月', '9月', '10月', '11月', '12月',
+];
+
+/**
+ * 将 string | Date 转换为 dayjs 对象。
+ * headless 组件需要用此函数更新 currentRef。
+ */
+export const toDayjs = (value: string | Date | undefined) => {
+  return dayjs(value);
+};
+
+/** 简单的空值判断，内联避免从 lib 导入 */
+const isEmpty = (value: unknown): boolean => {
+  return value === '' || value === null || value === undefined;
+};
+
+/**
+ * 生成 0..max-1（step 步进）的数字数组，用于时间列渲染。
+ * @param max 最大值（不含），如 24、60
+ * @param step 步长
+ */
+export const generateTimeColumn = (max: number, step: number): number[] => {
+  const result: number[] = [];
+  for (let i = 0; i < max; i += step) {
+    result.push(i);
+  }
+  return result;
+};
+
+export function useDatePicker(props: DatePickerProps) {
+  const today = dayjs();
+
+  /** 当前日历视图所在年月日 */
+  const dateRef = ref<DateRefType>({
+    year: today.year(),
+    month: today.month() + 1,
+    day: today.date(),
+  });
+
+  /** trigger 显示的格式化文本 */
+  const displayValue = ref('');
+
+  /** trigger span 的 class 列表（含 placeholder 状态） */
+  const spanClass = ref<Array<string | undefined>>([]);
+
+  /** 当前选中的日期（dayjs 对象），用于日历格高亮） */
+  const currentRef = ref(toDayjs(props.modelValue));
+
+  /** 日历面板显示模式：date / month / year（datetime 类型初始显示 date 模式） */
+  const calendarTypeRef = ref<CalendarType>(
+    props.type === 'datetime' ? 'date' : (props.type ?? 'date'),
+  );
+
+  /** 年份选择模式下展示的 12 个年份 */
+  const yearsRef = ref<number[]>([]);
+
+  /** 是否处于 placeholder 状态 */
+  let needPlaceholder = false;
+
+  /** 根据 type 和 format prop 计算实际使用的日期格式 */
+  const format = computed(() => {
+    if (props.format) return props.format;
+    switch (props.type) {
+      case 'month': return 'YYYY-MM';
+      case 'datetime': return 'YYYY-MM-DD HH:mm:ss';
+      case 'date':
+      default: return 'YYYY-MM-DD';
+    }
+  });
+
+  /** datetime 模式下的时间状态（时/分/秒） */
+  const timeRef = ref<TimeRefType>({ hours: 0, minutes: 0, seconds: 0 });
+
+  /**
+   * 根据传入值更新内部状态（dateRef、displayValue、spanClass）。
+   * 空值时显示 placeholder，有效日期时解析并同步。
+   */
+  const updateDateRef = (value: string | Date | undefined) => {
+    if (isEmpty(value)) {
+      displayValue.value = props.placeholder ?? '请选择日期...';
+      needPlaceholder = true;
+    } else {
+      needPlaceholder = false;
+      const dayjsValue = dayjs(value as string | Date);
+      if (dayjsValue.isValid()) {
+        displayValue.value = dayjsValue.format(format.value).toString();
+        dateRef.value = {
+          year: dayjsValue.year(),
+          month: dayjsValue.month() + 1,
+          day: dayjsValue.date(),
+        };
+        // datetime 模式下同步时间部分
+        if (props.type === 'datetime') {
+          timeRef.value = {
+            hours: dayjsValue.hour(),
+            minutes: dayjsValue.minute(),
+            seconds: dayjsValue.second(),
+          };
+        }
+      }
+      // 无效日期时保持原状，不做处理
+    }
+    spanClass.value = [
+      'm-date-picker-span',
+      needPlaceholder ? 'm-date-picker-placeholder' : undefined,
+    ];
+  };
+
+  // 初始化
+  updateDateRef(props.modelValue);
+
+  /**
+   * 生成 6×7 日历网格数据。
+   * 返回按 7 天分组的二维数组，每格包含日期信息。
+   */
+  const getCalendar = (MDateRefValue: Ref<DateRefType>): CalendarItem[][] => {
+    const dr = MDateRefValue.value;
+
+    // 当月第一天的 dayjs
+    const monthDayjs = dayjs().set('year', dr.year).set('month', dr.month - 1);
+    const dateDayjs = monthDayjs.set('date', dr.day);
+    const firstDayWeek = dateDayjs.startOf('month');
+    const firstDayWeekDay = firstDayWeek.day();
+
+    // 上个月信息
+    const prevDaysYear = dr.month === 1 ? dr.year - 1 : dr.year;
+    const lastMonthDayjs = dateDayjs.subtract(1, 'month');
+    const lastMonth = lastMonthDayjs.month() + 1;
+
+    // 填充上月日期（到当月第一天前的周日）
+    const prevDays: CalendarItem[] = Array.from({ length: firstDayWeekDay }, (_, i) => {
+      const day = firstDayWeek.subtract(firstDayWeekDay - i, 'day').date();
+      return { day, isCurrentMonth: false, month: lastMonth, year: prevDaysYear };
+    });
+
+    // 判断某日是否是当前选中日
+    const isCurrent = (dayNum: number): boolean => {
+      if (dr.year !== currentRef.value.year()) return false;
+      if (dr.month !== currentRef.value.month() + 1) return false;
+      return dayNum === currentRef.value.date();
+    };
+
+    // 当月所有日期
+    const currentDays: CalendarItem[] = Array.from({ length: monthDayjs.daysInMonth() }, (_, i) => ({
+      day: i + 1,
+      isCurrentMonth: true,
+      isCurrent: isCurrent(i + 1),
+      month: dr.month,
+      year: dr.year,
+    }));
+
+    // 下个月信息：填充到当月最后一天所在周的周六
+    const nextDaysYear = dr.month === 12 ? dr.year + 1 : dr.year;
+    const lastDayOfMonth = dayjs(`${dr.year}-${dr.month}`).daysInMonth();
+    const lastDayWeekDay = dayjs(`${dr.year}-${dr.month}-${lastDayOfMonth}`).day();
+    const nextDays: CalendarItem[] = Array.from({ length: 6 - lastDayWeekDay }, (_, i) => ({
+      day: i + 1,
+      isCurrentMonth: false,
+      month: dr.month === 12 ? 1 : dr.month + 1,
+      year: nextDaysYear,
+    }));
+
+    // 总格数不足 42（6 行）时补齐
+    if (prevDays.length + currentDays.length + nextDays.length < 42) {
+      if (firstDayWeekDay === 0) {
+        // 当月第一天是周日，需在前面多补一行上月日期
+        const lastMonthDays = lastMonthDayjs.daysInMonth();
+        prevDays.unshift(...Array.from({ length: 7 }, (_, i) => ({
+          day: lastMonthDays - 6 + i,
+          isCurrentMonth: false,
+          month: lastMonth,
+          year: prevDaysYear,
+        })));
+      } else {
+        // 末尾补充下月日期，补足一行
+        const nextMonth = dateDayjs.add(1, 'month');
+        const nextMonthFirstDayWeek = nextMonth.set('date', 1).day();
+        const baseDay = nextMonthFirstDayWeek === 0 ? 0 : (6 - nextMonthFirstDayWeek);
+        nextDays.push(...Array.from({ length: 7 }, (_, i) => ({
+          day: i + baseDay + 1,
+          isCurrentMonth: false,
+          month: dr.month === 12 ? 1 : dr.month + 1,
+          year: nextDaysYear,
+        })));
+      }
+    }
+
+    // 按 7 天一组切分为二维数组
+    const allDays = [...prevDays, ...currentDays, ...nextDays];
+    const result: CalendarItem[][] = [];
+    for (let i = 0; i < allDays.length; i += 7) {
+      result.push(allDays.slice(i, i + 7) as CalendarItem[]);
+    }
+    return result;
+  };
+
+  /** 切换到上一个月 */
+  const toPrevMonth = () => {
+    if (!dateRef.value) return;
+    dateRef.value.month -= 1;
+    if (dateRef.value.month === 0) {
+      dateRef.value.month = 12;
+      dateRef.value.year -= 1;
+    }
+  };
+
+  /** 切换到下一个月 */
+  const toNextMonth = () => {
+    if (!dateRef.value) return;
+    dateRef.value.month += 1;
+    if (dateRef.value.month === 13) {
+      dateRef.value.month = 1;
+      dateRef.value.year += 1;
+    }
+  };
+
+  /** 切换到下一年 */
+  const toNextYear = () => {
+    if (!dateRef.value) return;
+    dateRef.value.year += 1;
+    // 年份选择模式下，若当前年不在范围内则重新生成年份列表
+    if (calendarTypeRef.value === 'year') {
+      if (!yearsRef.value.includes(dateRef.value.year)) {
+        const startYear = dateRef.value.year;
+        yearsRef.value = Array.from({ length: 12 }, (_, i) => startYear + i);
+      }
+    }
+  };
+
+  /** 切换到上一年 */
+  const toPrevYear = () => {
+    if (!dateRef.value) return;
+    dateRef.value.year -= 1;
+    if (calendarTypeRef.value === 'year') {
+      if (!yearsRef.value.includes(dateRef.value.year)) {
+        const startYear = dateRef.value.year - 11;
+        yearsRef.value = Array.from({ length: 12 }, (_, i) => startYear + i);
+      }
+    }
+  };
+
+  /**
+   * 根据日历格数据生成格式化后的日期字符串值。
+   * datetime 模式下会同时拼接当前时间状态。
+   */
+  const getValue = (item: CalendarItem): string => {
+    let d = dayjs()
+      .set('year', item.year)
+      .set('month', (item.month as number) - 1)
+      .set('date', Number(item.day));
+    // datetime 模式下附加时间部分
+    if (props.type === 'datetime') {
+      d = d
+        .set('hour', timeRef.value.hours)
+        .set('minute', timeRef.value.minutes)
+        .set('second', timeRef.value.seconds);
+    }
+    return d.format(format.value);
+  };
+
+  /**
+   * 生成 datetime 模式的完整值（使用当前 dateRef + timeRef）。
+   * 在用户点击「确定」时调用。
+   */
+  const getDateTimeValue = (): string => {
+    return dayjs()
+      .set('year', dateRef.value.year)
+      .set('month', dateRef.value.month - 1)
+      .set('date', dateRef.value.day)
+      .set('hour', timeRef.value.hours)
+      .set('minute', timeRef.value.minutes)
+      .set('second', timeRef.value.seconds)
+      .format(format.value);
+  };
+
+  /** datetime 模式：选择小时 */
+  const selectHour = (hour: number) => {
+    timeRef.value = { ...timeRef.value, hours: hour };
+  };
+
+  /** datetime 模式：选择分钟 */
+  const selectMinute = (minute: number) => {
+    timeRef.value = { ...timeRef.value, minutes: minute };
+  };
+
+  /** datetime 模式：选择秒 */
+  const selectSecond = (second: number) => {
+    timeRef.value = { ...timeRef.value, seconds: second };
+  };
+
+  /**
+   * 点击头部年份文字 → 切换到年份选择模式，生成以 year 为中心的 12 个年份列表。
+   */
+  const clickCurrentYear = (year: number) => {
+    calendarTypeRef.value = 'year';
+    const startYear = year - 6;
+    const endYear = year + 5;
+    yearsRef.value = Array.from({ length: endYear - startYear + 1 }, (_, i) => startYear + i);
+  };
+
+  /**
+   * 点击年份列表中某一年 → 更新 dateRef.year 并根据 type 切换模式。
+   */
+  const clickYearItem = (year: number) => {
+    if (!dateRef.value) return;
+    dateRef.value.year = year;
+    if (props.type === 'date' || props.type === 'datetime') calendarTypeRef.value = 'date';
+    else if (props.type === 'month') calendarTypeRef.value = 'month';
+  };
+
+  /**
+   * 点击头部月份文字 → 切换到月份选择模式。
+   */
+  const clickCurrentMonth = (_month: number) => {
+    calendarTypeRef.value = 'month';
+  };
+
+  /**
+   * 点击月份列表中某一月 → 更新 dateRef.month，若 type="date" 则切换回日期模式。
+   */
+  const clickMonthItem = (month: number) => {
+    dateRef.value.month = month;
+    if (props.type === 'date' || props.type === 'datetime') calendarTypeRef.value = 'date';
+  };
+
+  return {
+    // 状态
+    dateRef,
+    displayValue,
+    spanClass,
+    currentRef,
+    calendarTypeRef,
+    yearsRef,
+    // datetime 时间状态
+    timeRef,
+    // 方法
+    updateDateRef,
+    getCalendar,
+    toPrevMonth,
+    toNextMonth,
+    toPrevYear,
+    toNextYear,
+    getValue,
+    getDateTimeValue,
+    clickCurrentYear,
+    clickYearItem,
+    clickCurrentMonth,
+    clickMonthItem,
+    // datetime 时间选择方法
+    selectHour,
+    selectMinute,
+    selectSecond,
+    // 工具
+    toDayjs,
+  };
+}

package/components/base/divider/api.ts

@@ -0,0 +1,15 @@
+/**
+ * @description divider api
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { DividerProps } from './props';
+
+export const props: MCOPO<DividerProps> = {
+  vertical: { type: Boolean, default: false },
+  align: { type: String as unknown as MPropType<NonNullable<DividerProps['align']>>, default: 'center' },
+};

package/components/base/divider/divider.css

@@ -0,0 +1,11 @@
+.m-divider {
+  width: 100%;
+  height: 5px;
+  background: var(--m-line-crossrange) repeat-x;
+
+  &.m-divider-vertical {
+    height: 100%;
+    background: var(--m-line-vertical) repeat-y;
+    width: 6px;
+  }
+}

package/components/base/divider/index.ts

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

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

@@ -0,0 +1,30 @@
+/**
+ * @description divider api type
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.1.0
+ *
+ * @name m-divider
+ * @docDescription Divider component with shuimo-ui style.
+ *                 水墨组件的分割线组件。
+ * @docUrl https://shuimo.design/divider
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type DividerProps = {
+  /**
+   * @description divider is vertical or not
+   *              是否为垂直分割线
+   * @type boolean
+   * @default false
+   */
+  vertical?: boolean;
+  /**
+   * @description text alignment when slot content exists (horizontal only)
+   *              内容文字对齐方式，仅水平分割线有效
+   * @type 'left' | 'center' | 'right'
+   * @default 'center'
+   */
+  align?: 'left' | 'center' | 'right';
+};

package/components/base/dropdown/api.ts

@@ -0,0 +1,33 @@
+/**
+ * @description dropdown 运行时 props
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { DropdownItemProps, DropdownProps } from './props';
+
+export const props: MCOPO<DropdownProps> = {
+  trigger: {
+    type: String as MPropType<'click' | 'hover'>,
+    default: 'click',
+  },
+  placement: {
+    type: String as MPropType<'bottom' | 'bottom-start' | 'bottom-end' | 'top' | 'top-start' | 'top-end'>,
+    default: 'bottom',
+  },
+  disabled: { type: Boolean, default: false },
+};
+
+export const itemProps: MCOPO<DropdownItemProps> = {
+  label: { type: String, default: '' },
+  disabled: { type: Boolean, default: false },
+  divided: { type: Boolean, default: false },
+  command: { type: [String, Number], default: undefined },
+  type: {
+    type: String as MPropType<'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info'>,
+    default: 'default',
+  },
+};

package/components/base/dropdown/index.ts

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

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

@@ -0,0 +1,60 @@
+/**
+ * @description dropdown api type
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type DropdownProps = {
+  /**
+   * @description 触发方式
+   * @type 'click' | 'hover'
+   * @default 'click'
+   */
+  trigger?: 'click' | 'hover';
+  /**
+   * @description 弹出位置
+   * @type string
+   * @default 'bottom'
+   */
+  placement?: 'bottom' | 'bottom-start' | 'bottom-end' | 'top' | 'top-start' | 'top-end';
+  /**
+   * @description 是否禁用
+   * @type boolean
+   * @default false
+   */
+  disabled?: boolean;
+};
+
+export declare type DropdownItemProps = {
+  /**
+   * @description 选项文本
+   * @type string
+   */
+  label?: string;
+  /**
+   * @description 是否禁用该选项
+   * @type boolean
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * @description 是否在此项上方显示分割线
+   * @type boolean
+   * @default false
+   */
+  divided?: boolean;
+  /**
+   * @description 点击触发的指令值
+   * @type string | number
+   */
+  command?: string | number;
+  /**
+   * @description 选项色彩类型
+   * @type 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info'
+   * @default 'default'
+   */
+  type?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
+};

package/components/base/dropdown/useDropdown.ts

@@ -0,0 +1,124 @@
+/**
+ * @description dropdown composable
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { computed, onBeforeUnmount, onMounted, ref } from 'vue';
+import { DropdownItemProps, DropdownProps } from './props';
+import useClickAway from '../../../compositions/popper/useClickAway';
+import { type HookContext } from '../../types/hook';
+
+export function useDropdown(props: Required<DropdownProps>, ctx: HookContext) {
+  const { emit } = ctx;
+
+  // 下拉菜单是否展开
+  const visible = ref(false);
+
+  // 触发器 DOM 引用，用于 clickAway 检测
+  const triggerRef = ref<HTMLElement>();
+  const menuRef = ref<HTMLElement>();
+
+  /** 打开下拉菜单 */
+  const open = () => {
+    if (props.disabled) { return; }
+    visible.value = true;
+  };
+
+  /** 关闭下拉菜单 */
+  const close = () => {
+    visible.value = false;
+  };
+
+  /** 切换下拉菜单展开/收起 */
+  const toggle = () => {
+    if (visible.value) {
+      close();
+    } else {
+      open();
+    }
+  };
+
+  // 点击外部自动关闭
+  let clickAwayInstance: ReturnType<typeof useClickAway>;
+
+  onMounted(() => {
+    clickAwayInstance = useClickAway({
+      // 以 trigger 容器为边界，点击 trigger 或 menu 内部不触发关闭
+      target: () => triggerRef.value?.parentElement,
+      handler: () => {
+        close();
+      },
+    });
+    clickAwayInstance?.add();
+  });
+
+  onBeforeUnmount(() => {
+    clickAwayInstance?.remove();
+  });
+
+  // ---- 触发器事件处理 ----
+
+  /** click 触发模式下点击处理 */
+  const handleTriggerClick = () => {
+    if (props.trigger !== 'click') { return; }
+    toggle();
+  };
+
+  /** hover 触发模式下鼠标进入处理 */
+  const handleMouseenter = () => {
+    if (props.trigger !== 'hover') { return; }
+    open();
+  };
+
+  /** hover 触发模式下鼠标离开处理 */
+  const handleMouseleave = () => {
+    if (props.trigger !== 'hover') { return; }
+    close();
+  };
+
+  // ---- 选项点击处理 ----
+
+  /**
+   * 选项被点击时：触发 command 事件并关闭菜单
+   */
+  const handleItemClick = (item: DropdownItemProps) => {
+    if (item.disabled) { return; }
+    emit('command', item.command);
+    close();
+  };
+
+  // ---- class 计算 ----
+
+  const dropdownClass = computed(() => [
+    'm-dropdown',
+    { 'm-dropdown-open': visible.value },
+    { 'm-dropdown-disabled': props.disabled },
+  ]);
+
+  const menuClass = computed(() => ['m-dropdown-menu']);
+
+  const getItemClass = (item: DropdownItemProps) => [
+    'm-dropdown-item',
+    { 'm-dropdown-item-disabled': item.disabled },
+    { 'm-dropdown-item-divided': item.divided },
+  ];
+
+  return {
+    visible,
+    triggerRef,
+    menuRef,
+    open,
+    close,
+    toggle,
+    handleTriggerClick,
+    handleMouseenter,
+    handleMouseleave,
+    handleItemClick,
+    dropdownClass,
+    menuClass,
+    getItemClass,
+  };
+}