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

package/components/base/card/api.ts

@@ -0,0 +1,17 @@
+/**
+ * @description card api
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { CardProps } from './props';
+
+export const props: MCOPO<CardProps> = {
+  title: { type: String, default: undefined },
+  shadow: { type: String as MPropType<'always' | 'hover' | 'never'>, default: 'never' },
+  bodyStyle: { type: Object, default: undefined },
+  bordered: { type: Boolean, default: true },
+};

package/components/base/card/index.ts

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

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

@@ -0,0 +1,37 @@
+/**
+ * @description card api type
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * @name m-card
+ * @docDescription Card component with shuimo-ui style.
+ *                 水墨组件的卡片组件。
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type CardProps = {
+  /**
+   * @description 卡片标题
+   * @type string
+   */
+  title?: string;
+  /**
+   * @description 阴影显示时机
+   * @type 'always' | 'hover' | 'never'
+   * @default 'never'
+   */
+  shadow?: 'always' | 'hover' | 'never';
+  /**
+   * @description 卡片内容区自定义样式
+   * @type Record<string, string>
+   */
+  bodyStyle?: Record<string, string>;
+  /**
+   * @description 是否显示边框
+   * @type boolean
+   * @default true
+   */
+  bordered?: boolean;
+};

package/components/base/carousel/api.ts

@@ -0,0 +1,28 @@
+/**
+ * @description carousel api
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { CarouselProps } from './props';
+
+export const props: MCOPO<CarouselProps> = {
+  autoplay: { type: Boolean, default: true },
+  interval: { type: Number, default: 3000 },
+  loop: { type: Boolean, default: true },
+  direction: {
+    type: String as MPropType<'horizontal' | 'vertical'>,
+    default: 'horizontal',
+    enum: ['horizontal', 'vertical'],
+  },
+  modelValue: { type: Number, default: undefined },
+  initialIndex: { type: Number, default: 0 },
+  showIndicators: { type: Boolean, default: true },
+  showArrows: {
+    type: [Boolean, String] as MPropType<boolean | 'hover'>,
+    default: 'hover',
+  },
+};

package/components/base/carousel/index.ts

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

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

@@ -0,0 +1,72 @@
+/**
+ * @description carousel props type
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * @name m-carousel
+ * @docDescription Carousel / slideshow component.
+ *                 轮播图组件。
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type CarouselProps = {
+  /**
+   * @description 是否自动播放
+   * @type boolean
+   * @default true
+   */
+  autoplay?: boolean,
+  /**
+   * @description 自动切换时间间隔（毫秒）
+   * @type number
+   * @default 3000
+   */
+  interval?: number,
+  /**
+   * @description 是否循环播放
+   * @type boolean
+   * @default true
+   */
+  loop?: boolean,
+  /**
+   * @description 轮播方向
+   * @type string
+   * @default horizontal
+   * @enum horizontal|vertical
+   */
+  direction?: 'horizontal' | 'vertical',
+  /**
+   * @description 当前激活的幻灯片索引（v-model）
+   * @type number
+   * @default 0
+   */
+  modelValue?: number,
+  /**
+   * @description 初始激活的幻灯片索引
+   * @type number
+   * @default 0
+   */
+  initialIndex?: number,
+  /**
+   * @description 是否显示指示器
+   * @type boolean
+   * @default true
+   */
+  showIndicators?: boolean,
+  /**
+   * @description 是否显示切换箭头，hover 表示鼠标悬浮时显示
+   * @type boolean | 'hover'
+   * @default 'hover'
+   */
+  showArrows?: boolean | 'hover',
+};
+
+export declare type CarouselEvents = {
+  /**
+   * @description 幻灯片切换时触发
+   * @param index 当前激活的索引
+   */
+  onChange?: (index: number) => void,
+};

package/components/base/carousel/useCarousel.ts

@@ -0,0 +1,151 @@
+/**
+ * @description carousel hook
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { ref, computed, onMounted, onUnmounted, watch } from 'vue';
+import { CarouselProps } from './props';
+
+export function useCarousel(props: Required<CarouselProps>, emit: (event: string, ...args: any[]) => void, count: () => number) {
+  // 逻辑索引（0..N-1），用于指示器和 v-model
+  const activeIndex = ref(props.modelValue ?? props.initialIndex);
+  // track 位置索引（loop 时含克隆偏移）
+  const trackIndex = ref(0);
+  // 禁用过渡标记（用于无缝瞬间跳转）
+  const disableTransition = ref(false);
+  // 自动播放定时器
+  let timer: ReturnType<typeof setInterval> | null = null;
+
+  const hasClones = () => props.loop && count() > 1;
+
+  // 同步 trackIndex 到当前 activeIndex
+  const syncTrackIndex = () => {
+    trackIndex.value = hasClones() ? activeIndex.value + 1 : activeIndex.value;
+  };
+
+  // 初始化
+  syncTrackIndex();
+
+  // 外部 v-model 变化时同步
+  watch(() => props.modelValue, (val) => {
+    if (val != null && val !== activeIndex.value) {
+      activeIndex.value = val;
+      syncTrackIndex();
+    }
+  });
+
+  /**
+   * 切换到指定索引，支持循环
+   */
+  const setActive = (index: number) => {
+    const total = count();
+    if (total === 0) { return; }
+
+    if (props.loop && total > 1) {
+      if (index >= total) {
+        // forward past last => slide to clone of first (trackIndex = total + 1)
+        activeIndex.value = 0;
+        trackIndex.value = total + 1;
+        emit('update:modelValue', 0);
+        emit('change', 0);
+      } else if (index < 0) {
+        // backward past first => slide to clone of last (trackIndex = 0)
+        activeIndex.value = total - 1;
+        trackIndex.value = 0;
+        emit('update:modelValue', total - 1);
+        emit('change', total - 1);
+      } else {
+        activeIndex.value = index;
+        trackIndex.value = index + 1;
+        emit('update:modelValue', index);
+        emit('change', index);
+      }
+    } else {
+      const next = Math.max(0, Math.min(index, total - 1));
+      if (next !== activeIndex.value) {
+        activeIndex.value = next;
+        trackIndex.value = next;
+        emit('update:modelValue', next);
+        emit('change', next);
+      }
+    }
+  };
+
+  /**
+   * transitionend 回调：如果停在克隆位置，瞬间跳回真实位置
+   */
+  const onTrackTransitionEnd = () => {
+    const total = count();
+    if (!hasClones() || total === 0) { return; }
+
+    const ti = trackIndex.value;
+    if (ti === 0) {
+      // 在克隆的最后一张 => 跳到真实的最后一张
+      disableTransition.value = true;
+      trackIndex.value = total;
+      reEnableTransition();
+    } else if (ti === total + 1) {
+      // 在克隆的第一张 => 跳到真实的第一张
+      disableTransition.value = true;
+      trackIndex.value = 1;
+      reEnableTransition();
+    }
+  };
+
+  const reEnableTransition = () => {
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        disableTransition.value = false;
+      });
+    });
+  };
+
+  /** 切换到上一张 */
+  const prev = () => setActive(activeIndex.value - 1);
+  /** 切换到下一张 */
+  const next = () => setActive(activeIndex.value + 1);
+
+  /** 启动自动播放 */
+  const startAutoplay = () => {
+    if (!props.autoplay || props.interval <= 0) { return; }
+    timer = setInterval(next, props.interval);
+  };
+
+  /** 停止自动播放 */
+  const stopAutoplay = () => {
+    if (timer !== null) {
+      clearInterval(timer);
+      timer = null;
+    }
+  };
+
+  // 监听 autoplay 属性变化
+  watch(() => props.autoplay, (val) => {
+    if (val) { startAutoplay(); } else { stopAutoplay(); }
+  });
+
+  onMounted(startAutoplay);
+  onUnmounted(stopAutoplay);
+
+  const arrowsClass = computed(() => {
+    if (props.showArrows === 'hover') { return 'k-carousel-arrows-hover'; }
+    if (props.showArrows === false) { return 'k-carousel-arrows-hidden'; }
+    return 'k-carousel-arrows-always';
+  });
+
+  return {
+    activeIndex,
+    trackIndex,
+    disableTransition,
+    prev,
+    next,
+    setActive,
+    startAutoplay,
+    stopAutoplay,
+    arrowsClass,
+    onTrackTransitionEnd,
+  };
+}

package/components/base/cascader/api.ts

@@ -0,0 +1,23 @@
+/**
+ * @description cascader api
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { CascaderProps, CascaderOption } from './props';
+
+export const props: MCOPO<CascaderProps> = {
+  modelValue: { type: undefined, default: () => [] },
+  options: { type: Array as MPropType<CascaderOption[]>, default: () => [] },
+  placeholder: { type: String, default: '请选择' },
+  disabled: { type: Boolean, default: false },
+  clearable: { type: Boolean, default: false },
+  filterable: { type: Boolean, default: false },
+  separator: { type: String, default: '/' },
+  expandTrigger: { type: String as MPropType<'click' | 'hover'>, default: 'click' },
+  showAllLevels: { type: Boolean, default: true },
+  multiple: { type: Boolean, default: false },
+};

package/components/base/cascader/index.ts

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

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

@@ -0,0 +1,103 @@
+/**
+ * @description cascader api type
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+/**
+ * 级联选择器的选项数据结构
+ */
+export declare type CascaderOption = {
+  /**
+   * @description 选项值
+   * @type string | number
+   */
+  value: string | number;
+  /**
+   * @description 选项显示文本
+   * @type string
+   */
+  label: string;
+  /**
+   * @description 子选项列表
+   * @type CascaderOption[]
+   */
+  children?: CascaderOption[];
+  /**
+   * @description 是否禁用该选项
+   * @type boolean
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * @description 是否为叶子节点（无子节点）
+   * @type boolean
+   */
+  leaf?: boolean;
+};
+
+export declare type CascaderProps = {
+  /**
+   * @description 绑定值，单选时为数组路径，多选时为二维数组
+   * @type (string | number)[] | (string | number)[][]
+   * @default []
+   */
+  modelValue?: (string | number)[] | (string | number)[][];
+  /**
+   * @description 可选项数据源
+   * @type CascaderOption[]
+   * @default []
+   */
+  options?: CascaderOption[];
+  /**
+   * @description 占位文本
+   * @type string
+   * @default '请选择'
+   */
+  placeholder?: string;
+  /**
+   * @description 是否禁用
+   * @type boolean
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * @description 是否支持清空
+   * @type boolean
+   * @default false
+   */
+  clearable?: boolean;
+  /**
+   * @description 是否可搜索过滤
+   * @type boolean
+   * @default false
+   */
+  filterable?: boolean;
+  /**
+   * @description 选项分隔符
+   * @type string
+   * @default '/'
+   */
+  separator?: string;
+  /**
+   * @description 次级菜单的展开方式
+   * @type 'click' | 'hover'
+   * @default 'click'
+   */
+  expandTrigger?: 'click' | 'hover';
+  /**
+   * @description 是否在输入框中显示选中值的完整路径
+   * @type boolean
+   * @default true
+   */
+  showAllLevels?: boolean;
+  /**
+   * @description 是否多选
+   * @type boolean
+   * @default false
+   */
+  multiple?: boolean;
+};