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

package/components/base/autoComplete/useAutoComplete.ts

@@ -0,0 +1,149 @@
+/**
+ * @description autoComplete 核心 composable
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 与 Select 的核心差异：
+ * 1. freetype 模式：输入框文字直接就是 modelValue，不强制匹配选项
+ * 2. 搜索由外部 fetchSuggestions 驱动，结果动态替换
+ * 3. debounce：输入停止后延迟触发搜索，避免频繁请求
+ * 4. loading 状态：搜索进行中显示加载指示
+ */
+import { ref, toRef, onBeforeUnmount } from 'vue';
+import { AutoCompleteProps, AutoCompleteOption } from './props';
+
+export function useAutoComplete(props: AutoCompleteProps, ctx: any) {
+  const modelValueRef = toRef(() => props.modelValue ?? '');
+
+  // --- 状态 ---
+  /** 输入框当前文本，与 modelValue 保持同步 */
+  const inputValue = ref(modelValueRef.value);
+  /** 下拉是否展开 */
+  const isOpen = ref(false);
+  /** 搜索进行中 */
+  const loading = ref(false);
+  /** 当前建议列表 */
+  const suggestions = ref<AutoCompleteOption[]>([]);
+
+  // --- debounce timer ---
+  let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const clearDebounce = () => {
+    if (debounceTimer !== undefined) {
+      clearTimeout(debounceTimer);
+      debounceTimer = undefined;
+    }
+  };
+
+  // --- 搜索逻辑 ---
+
+  /**
+   * 执行一次搜索，更新 suggestions 并打开下拉
+   * 仅在 fetchSuggestions 存在时才执行
+   */
+  const doSearch = async (query: string) => {
+    if (!props.fetchSuggestions) return;
+
+    loading.value = true;
+    try {
+      const result = await props.fetchSuggestions(query);
+      suggestions.value = result ?? [];
+      // 有结果（包括空数组）时才打开，方便外部展示"无结果"状态
+      isOpen.value = true;
+    } catch {
+      suggestions.value = [];
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  /**
+   * debounce 包装的搜索：输入后等待 debounce ms 再执行
+   */
+  const debouncedSearch = (query: string) => {
+    clearDebounce();
+    const delay = props.debounce ?? 300;
+    debounceTimer = setTimeout(() => {
+      doSearch(query);
+      ctx.emit('search', query);
+    }, delay);
+  };
+
+  // --- 事件处理 ---
+
+  /** 输入事件：更新 modelValue + 触发 debounce 搜索 */
+  const onInput = (e: Event) => {
+    const value = (e.target as HTMLInputElement).value;
+    inputValue.value = value;
+    ctx.emit('update:modelValue', value);
+    debouncedSearch(value);
+  };
+
+  /** 聚焦事件 */
+  const onFocus = (e: FocusEvent) => {
+    if (props.disabled) return;
+    ctx.emit('focus', e);
+
+    if (props.triggerOnFocus) {
+      // 聚焦时立即搜索当前值（不走 debounce）
+      doSearch(inputValue.value);
+      ctx.emit('search', inputValue.value);
+    }
+  };
+
+  /** 失焦事件：延迟关闭，预留给点击选项的时间 */
+  const onBlur = (e: FocusEvent) => {
+    if (props.disabled) return;
+    // 延迟关闭，避免与选项的 mousedown 事件竞争
+    setTimeout(() => {
+      isOpen.value = false;
+    }, 150);
+    ctx.emit('blur', e);
+  };
+
+  /** 选中某条建议 */
+  const onSelect = (item: AutoCompleteOption) => {
+    inputValue.value = item.value;
+    ctx.emit('update:modelValue', item.value);
+    ctx.emit('select', item);
+    isOpen.value = false;
+    clearDebounce();
+  };
+
+  /** 清空输入 */
+  const onClear = () => {
+    inputValue.value = '';
+    suggestions.value = [];
+    isOpen.value = false;
+    clearDebounce();
+    ctx.emit('update:modelValue', '');
+  };
+
+  /** 关闭下拉 */
+  const close = () => {
+    isOpen.value = false;
+  };
+
+  // 组件卸载时清理 debounce timer
+  onBeforeUnmount(() => {
+    clearDebounce();
+  });
+
+  return {
+    // 状态
+    inputValue,
+    isOpen,
+    loading,
+    suggestions,
+    // 事件
+    onInput,
+    onFocus,
+    onBlur,
+    onSelect,
+    onClear,
+    close,
+  };
+}

package/components/base/avatar/api.ts

@@ -0,0 +1,17 @@
+/**
+ * @description avatar api
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { AvatarProps } from './props';
+
+export const props: MCOPO<AvatarProps> = {
+  shape: { type: String as MPropType<'circle' | 'square'>, default: 'circle' },
+  size: { type: String as MPropType<'large' | 'medium' | 'small'>, default: 'medium' },
+  src: { type: String, default: '' },
+  alt: { type: String, default: '' },
+};

package/components/base/avatar/avatar.css

@@ -0,0 +1,61 @@
+:root {
+  --m-avatar-large: 50px;
+  --m-avatar-default: 40px;
+  --m-avatar-small: 24px;
+}
+
+.m-avatar {
+  --m-avatar-size: var(--m-avatar-default);
+  --m-avatar-w: var(--m-avatar-size);
+  --m-image-size: var(--m-avatar-size);
+
+  display: inline-grid;
+  grid-template-areas: 'avatar';
+
+  &.m-avatar-large {
+    --m-avatar-size: var(--m-avatar-large);
+  }
+
+  &.m-avatar-small {
+    --m-avatar-size: var(--m-avatar-small);
+  }
+
+  width: var(--m-avatar-w);
+  height: var(--m-avatar-size);
+
+  & .m-avatar-mask {
+    grid-area: avatar;
+    width: var(--m-avatar-w);
+    height: var(--m-avatar-size);
+  }
+
+  --m-image-m-t: 0;
+  --m-image-m-l: 0;
+
+  & > img {
+    grid-area: avatar;
+    width: var(--m-image-size);
+    height: var(--m-image-size);
+    margin: var(--m-image-m-t) 0 0 var(--m-image-m-l);
+  }
+}
+
+
+.m-avatar-circle {
+  --m-avatar-w: calc(var(--m-avatar-size) / 43 * 54);
+  --m-image-size: calc(var(--m-avatar-size) / 54 * 45);
+  --m-image-m-t: calc(var(--m-avatar-w) / 54 * 3);
+  --m-image-m-l: calc(var(--m-avatar-w) / 54 * 9);
+
+  & > img {
+    margin: var(--m-image-m-t) 0 0 var(--m-image-m-l);
+    border-radius: 50%;
+  }
+}
+
+.m-avatar-square {
+  --m-image-size: calc(var(--m-avatar-size) / 49 * 45);
+  --m-image-m-t: calc(var(--m-avatar-w) / 52 * 2);
+  --m-image-m-l: calc(var(--m-avatar-w) / 52 * 2);
+}
+

package/components/base/avatar/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @description
+ * @author 阿怪
+ * @date 2024/10/9 00:35
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { props } from './api';
+
+export const AvatarCore = {
+  props,
+};
+
+export type { AvatarProps } from './props';

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

@@ -0,0 +1,37 @@
+/**
+ * @description avatar component props definition.
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type AvatarProps = {
+  /**
+   * @description avatar shape
+   *              头像的形状
+   * @type string
+   * @default circle
+   */
+  shape?: 'circle' | 'square';
+  /**
+   * @description avatar size
+   *             头像的大小
+   * @type string
+   * @default medium
+   */
+  size?: 'large' | 'medium' | 'small';
+  /**
+   * @description image url
+   *             头像图片地址
+   * @type string
+   */
+  src?: string;
+  /**
+   * @description image alt text
+   *             图片替代文字
+   * @type string
+   */
+  alt?: string;
+};

package/components/base/backTop/api.ts

@@ -0,0 +1,17 @@
+/**
+ * @description backTop api
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO } from '../../types/props';
+import { BackTopProps } from './props';
+
+export const props: MCOPO<BackTopProps> = {
+  target: { type: String, default: '' },
+  visibilityHeight: { type: Number, default: 200 },
+  right: { type: Number, default: 40 },
+  bottom: { type: Number, default: 40 },
+};

package/components/base/backTop/index.ts

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

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

@@ -0,0 +1,38 @@
+/**
+ * @description backTop props type
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * @name k-back-top
+ * @docDescription BackTop（回到顶部）组件。
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type BackTopProps = {
+  /**
+   * @description 触发滚动的目标元素 CSS 选择器，默认监听 window
+   * @type string
+   * @default ''
+   */
+  target?: string,
+  /**
+   * @description 滚动距离超过此值时显示按钮
+   * @type number
+   * @default 200
+   */
+  visibilityHeight?: number,
+  /**
+   * @description 按钮距离页面右侧的距离（px）
+   * @type number
+   * @default 40
+   */
+  right?: number,
+  /**
+   * @description 按钮距离页面底部的距离（px）
+   * @type number
+   * @default 40
+   */
+  bottom?: number,
+};

package/components/base/backTop/useBackTop.ts

@@ -0,0 +1,62 @@
+/**
+ * @description backTop hook
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { ref, onMounted, onUnmounted } from 'vue';
+import { BackTopProps } from './props';
+
+export function useBackTop(props: Required<BackTopProps>) {
+  const visible = ref(false);
+
+  /** 获取滚动目标元素，无匹配则使用 window */
+  const getScrollTarget = (): HTMLElement | Window => {
+    if (props.target) {
+      const el = document.querySelector<HTMLElement>(props.target);
+      if (el) { return el; }
+    }
+    return window;
+  };
+
+  /** 读取当前滚动高度 */
+  const getScrollTop = (): number => {
+    const target = getScrollTarget();
+    if (target === window) {
+      return window.scrollY;
+    }
+    return (target as HTMLElement).scrollTop;
+  };
+
+  const onScroll = () => {
+    visible.value = getScrollTop() >= props.visibilityHeight;
+  };
+
+  const scrollToTop = () => {
+    const target = getScrollTarget();
+    if (target === window) {
+      window.scrollTo({ top: 0, behavior: 'smooth' });
+    } else {
+      (target as HTMLElement).scrollTo({ top: 0, behavior: 'smooth' });
+    }
+  };
+
+  onMounted(() => {
+    const target = getScrollTarget();
+    target.addEventListener('scroll', onScroll, { passive: true });
+    // 初始检测
+    onScroll();
+  });
+
+  onUnmounted(() => {
+    const target = getScrollTarget();
+    target.removeEventListener('scroll', onScroll);
+  });
+
+  return {
+    visible,
+    scrollToTop,
+  };
+}

package/components/base/badge/api.ts

@@ -0,0 +1,22 @@
+/**
+ * @description badge api
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { BadgeProps } from './props';
+
+export const props: MCOPO<BadgeProps> = {
+  value: { type: [String, Number], default: undefined },
+  max: { type: Number, default: 99 },
+  dot: { type: Boolean, default: false },
+  hidden: { type: Boolean, default: false },
+  showZero: { type: Boolean, default: false },
+  type: {
+    type: String as MPropType<'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info'>,
+    default: 'danger',
+  },
+};

package/components/base/badge/index.ts

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

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

@@ -0,0 +1,50 @@
+/**
+ * @description badge api type
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.1.0
+ *
+ * @name m-badge
+ * @docDescription Badge component with shuimo-ui style.
+ *                 水墨组件的徽标组件。
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type BadgeProps = {
+  /**
+   * @description 显示的值，number 时支持 max 截断，string 时直接显示（如 "NEW"/"HOT"）
+   * @type number | string
+   */
+  value?: number | string;
+  /**
+   * @description 最大值，超出时显示 max+（仅 value 为 number 时生效）
+   * @type number
+   * @default 99
+   */
+  max?: number;
+  /**
+   * @description 是否显示小圆点（开启后忽略 value）
+   * @type boolean
+   * @default false
+   */
+  dot?: boolean;
+  /**
+   * @description 是否隐藏徽标
+   * @type boolean
+   * @default false
+   */
+  hidden?: boolean;
+  /**
+   * @description value 为 0 时是否显示徽标
+   * @type boolean
+   * @default false
+   */
+  showZero?: boolean;
+  /**
+   * @description 类型，控制徽标颜色
+   * @type 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info'
+   * @default 'danger'
+   */
+  type?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
+};

package/components/base/button/api.ts

@@ -0,0 +1,28 @@
+/**
+ * @description button api
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { ButtonProps } from './props';
+
+export const props: MCOPO<ButtonProps> = {
+  text: { type: String, default: '' },
+  link: { type: Boolean, default: false },
+  disabled: { type: Boolean, default: false },
+  loading: { type: Boolean, default: false },
+  plain: { type: Boolean, default: false },
+  type: {
+    type: String as MPropType<'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info'>,
+    default: 'default',
+    enum: ['default', 'primary', 'success', 'warning', 'danger', 'info'],
+  },
+  size: {
+    type: String as MPropType<'large' | 'medium' | 'small'>,
+    default: 'medium',
+    enum: ['large', 'medium', 'small'],
+  },
+};

package/components/base/button/button.css

@@ -0,0 +1,34 @@
+:root {
+/*  --m-button-width: 180px;
+  --m-button-height: 80px;
+  --m-button-line-height: 24px;*/
+}
+
+.m-button {
+  padding: 0 15px;
+  outline: unset;
+  height: var(--m-button-height, 32px);
+  /*line-height: var(--m-button-line-height, 32px);*/
+  min-width: var(--m-button-width, 32px);
+  border: 5px double transparent;
+  border-radius: var(--kine-radius-xs);
+  color: white;
+  text-align: center;
+  cursor: var(--m-cursor-pointer);
+
+  &:disabled, &:disabled:hover {
+    color: var(--m-color-text-disabled);
+    cursor: var(--m-cursor-disabled);
+
+    & > slot {
+      pointer-events: none;
+    }
+  }
+}
+
+a.m-button {
+  text-decoration: unset;
+  height: 22px;
+  padding: unset;
+}
+

package/components/base/button/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @description
+ * @author 阿怪
+ * @date 2024/12/16 09:44
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { props } from './api';
+import { useButton } from './useButton';
+
+export const ButtonCore = {
+  props,
+  useButton,
+};
+
+export type { ButtonProps } from './props';

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

@@ -0,0 +1,64 @@
+/**
+ * @description button api type
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.1.0
+ *
+ * @name m-button
+ * @docDescription Button component with kine-design style.
+ *              kine-design 的按钮组件。
+ *
+ * 公司的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type ButtonProps = {
+  /**
+   * @description button inline text, will replace by slot
+   *              按钮文本，会被 slot 覆盖
+   * @type string
+   * @default ''
+   */
+  text?: string,
+  /**
+   * @description link style 链接样式
+   * @type boolean
+   * @default false
+   */
+  link?: boolean,
+  /**
+   * @description disable or not 是否禁用
+   * @type boolean
+   * @default false
+   */
+  disabled?: boolean,
+  /**
+   * @description loading state 加载状态（自动禁用点击并显示 spinner）
+   * @type boolean
+   * @default false
+   */
+  loading?: boolean,
+  /**
+   * @description plain style 文本按钮样式（无边框无背景）
+   * @type boolean
+   * @default false
+   */
+  plain?: boolean,
+  /**
+   * @description button type 按钮类型
+   * @type string
+   * @default default
+   * @enum default|primary|success|warning|danger|info
+   */
+  type?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info',
+  /**
+   * @description button size 按钮尺寸
+   * @type string
+   * @default medium
+   * @enum large|medium|small
+   */
+  size?: 'large' | 'medium' | 'small',
+};
+
+export declare type ButtonEvents = {
+  onClick?: (e: MouseEvent) => void
+};

package/components/base/button/useButton.ts

@@ -0,0 +1,37 @@
+/**
+ * @description button composable
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { SetupContext } from 'vue';
+import { ButtonProps } from './props';
+
+export function useButton(props: ButtonProps, { slots }: SetupContext) {
+  const domType = props.link ? 'a' : 'button';
+  const slot = slots.default?.() ?? props.text;
+
+  // loading 状态视为禁用（阻止交互）
+  const isDisabled = props.disabled || props.loading;
+
+  const domProps = {
+    class: [
+      'm-button',
+      { 'm-button-disabled': isDisabled },
+      { 'm-button-loading': props.loading },
+      { 'm-button-plain': props.plain },
+      `m-button-${props.type ?? 'default'}`,
+      `m-button-${props.size ?? 'medium'}`,
+    ],
+    disabled: isDisabled,
+  };
+
+  return {
+    domType,
+    slot,
+    domProps,
+    isDisabled,
+  };
+}