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

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

@@ -0,0 +1,40 @@
+/**
+ * @description loading api type
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.1.0
+ *
+ * @name k-loading
+ * @docDescription Loading component with Phosphor sci-fi theme.
+ *                 Kine Design 加载组件。
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { KineSize } from '../../types/props';
+
+export declare type LoadingProps = {
+  /**
+   * @description 是否显示 loading
+   * @type boolean
+   * @default false
+   */
+  modelValue?: boolean;
+  /**
+   * @description 尺寸
+   * @type 'large' | 'medium' | 'small'
+   * @default 'medium'
+   */
+  size?: KineSize;
+  /**
+   * @description 是否显示遮罩层（覆盖父元素）
+   * @type boolean
+   * @default false
+   */
+  mask?: boolean;
+  /**
+   * @description 加载提示文字
+   * @type string
+   */
+  text?: string;
+};

package/components/base/popover/api.ts

@@ -0,0 +1,28 @@
+/**
+ * @description popover 运行时 props
+ * @author 阿怪
+ * @date 2026/2/25 00:00
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { PopoverProps } from './props';
+import { MCOPO, MPropType } from '../../types/props';
+import { Placement } from '../../../compositions/popper/usePopper.ts';
+
+export const props: MCOPO<PopoverProps> = {
+  placement: {
+    type: String as MPropType<Placement>,
+    default: 'bottom',
+  },
+  mountRender: { type: Boolean, default: false },
+  disableClickAway: { type: Boolean, default: false },
+  hover: { type: Boolean, default: false },
+  show: { type: Boolean, default: null },
+  content: { type: String, default: '' },
+  popper: {
+    type: Object, default: () => ({}),
+  },
+  teleport: { type: [Object, Boolean], default: undefined },
+  title: { type: String, default: undefined },
+};

package/components/base/popover/index.ts

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

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

@@ -0,0 +1,73 @@
+/**
+ * @description popover 类型定义
+ * @author 阿怪
+ * @date 2026/2/25 00:00
+ * @version v1.0.0
+ *
+ * @name m-popover
+ * @docDescription Popover component.
+ *                 弹出框组件。
+ * @docUrl https://shuimo.design/popover
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { Placement, PopperConfig } from '../../../compositions/popper/usePopper.ts';
+import { MTeleportProps } from '../../../types/common/common';
+
+
+export type PopoverProps = {
+  /**
+   * @description 弹出框位置
+   * @type Placement
+   * @default bottom
+   */
+  placement?: Placement,
+  /**
+   * @description 挂载时是否渲染弹出内容
+   * @type boolean
+   * @default false
+   */
+  mountRender?: boolean,
+  /**
+   * @description 禁用点击外部自动关闭
+   * @type boolean
+   * @default false
+   */
+  disableClickAway?: boolean,
+  /**
+   * @description 简单文本内容可通过 prop 传入
+   * @type any
+   * @default ''
+   */
+  content?: any,
+  /**
+   * @description 是否通过 hover 触发
+   * @type boolean
+   * @default false
+   */
+  hover?: boolean,
+  /**
+   * @description 是否显示
+   * @type boolean
+   * @default false
+   */
+  show?: boolean,
+  /**
+   * @description floating-ui 配置项，参考 https://floating-ui.com/
+   * @type PopperConfig
+   * @default {}
+   */
+  popper?: PopperConfig,
+  /**
+   * @description 传送门配置
+   * @type MTeleportProps | boolean
+   * @default undefined
+   */
+  teleport?: MTeleportProps | undefined | boolean,
+  /**
+   * @description 气泡标题，传入时在内容上方渲染标题行
+   * @type string
+   * @default undefined
+   */
+  title?: string,
+};

package/components/base/popover/usePopover.ts

@@ -0,0 +1,193 @@
+/**
+ * @description popover composable
+ * @author 阿怪
+ * @date 2026/2/25 00:00
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { Placement, PopperConfig, PositionStyle, usePopper } from '../../../compositions/popper/usePopper.ts';
+import useClickAway from '../../../compositions/popper/useClickAway';
+import { PopoverProps } from './props';
+import { onBeforeUnmount, onMounted, ref, type Ref, shallowRef } from 'vue';
+import { type HookContext } from '../../types/hook';
+
+
+export type IPopper = ReturnType<typeof usePopper>;
+
+/**
+ * Popover 实例，管理定位、显示/隐藏状态
+ */
+export class PopoverImpl {
+
+  protected _active: HTMLElement;
+  protected _content: HTMLElement;
+  protected _arrow: HTMLElement | undefined;
+  popperInstance: IPopper;
+  style: Ref;
+  arrowStyle: Ref;
+  placement: Ref;
+  visible: boolean = false;
+  onShow?: Function;
+  onHide?: Function;
+
+  constructor(
+    val: { style: Ref, arrowStyle: Ref, placement: Ref, show: boolean },
+    active: HTMLElement,
+    content: HTMLElement,
+    arrow?: HTMLElement,
+    config?: PopperConfig,
+    lifecycle?: {
+      onShow?: Function,
+      onHide?: Function
+    },
+  ) {
+    if (!content) { throw new Error('MPopover: content is required'); }
+    if (!active) { throw new Error('MPopover: active is required'); }
+
+    this._active = active;
+    this._content = content;
+    this._arrow = arrow;
+    this.popperInstance = usePopper(this._active, this._content,
+      (positionStyle: PositionStyle) => this.update(positionStyle), this._arrow, config);
+    this.style = val.style;
+    this.arrowStyle = val.arrowStyle;
+    this.placement = val.placement;
+    this.visible = val.show;
+    this.onShow = lifecycle?.onShow;
+    this.onHide = lifecycle?.onHide;
+  }
+
+  get content() {
+    return this._content;
+  }
+
+  async show() {
+    this.style.value = { display: 'block', opacity: '0' };
+    this.arrowStyle.value = { display: 'block', opacity: '0' };
+    this.visible = true;
+    await this.popperInstance.getPositionStyle();
+    this.onShow?.();
+  }
+
+  update(positionStyle: PositionStyle) {
+    if (!this.visible) {
+      this.hide();
+      return;
+    }
+    this.style.value = positionStyle.style;
+    this.arrowStyle.value = positionStyle.arrowStyle;
+    this.placement.value = positionStyle.placement;
+  }
+
+  hide() {
+    this.style.value = undefined;
+    this.arrowStyle.value = undefined;
+    this.visible = false;
+    this.onHide?.();
+  }
+
+  async toggle() {
+    if (this.visible) {
+      this.hide();
+    } else {
+      await this.show();
+    }
+  }
+
+  destroy() {
+    this.popperInstance?.clear?.();
+    this.visible = false;
+    this.onShow = undefined;
+    this.onHide = undefined;
+  }
+}
+
+
+export function usePopover(props: Required<PopoverProps>, ctx: HookContext) {
+  const style = ref();
+  const arrowStyle = ref();
+  const placement = ref<Placement>(props.placement);
+  let instance: PopoverImpl | null = null;
+  let clickAwayInstance: ReturnType<typeof useClickAway>;
+
+  const popperInstance = shallowRef<PopoverImpl>();
+
+  const popoverRef = ref<HTMLElement>();
+  const contentRef = ref<HTMLElement>();
+  const arrowRef = ref<HTMLElement>();
+
+  const createPopover = (
+    active: HTMLElement,
+    content: HTMLElement,
+    arrow?: HTMLElement,
+    config?: PopperConfig,
+  ) => {
+    instance = new PopoverImpl(
+      { style, arrowStyle, placement, show: props.show },
+      active,
+      content,
+      arrow,
+      config,
+      {
+        onShow: () => {
+          clickAwayInstance?.add();
+          ctx.emit('update:show', true);
+        },
+        onHide: () => {
+          clickAwayInstance?.remove();
+          ctx.emit('update:show', false);
+        },
+      });
+    return instance;
+  };
+
+  const popoverEnter = () => {
+    if (props.hover) {
+      instance?.show();
+    }
+  };
+  const popoverLeave = () => {
+    if (props.hover) {
+      instance?.hide();
+    }
+  };
+
+  onMounted(() => {
+    if (!popoverRef.value || !contentRef.value) {
+      return;
+    }
+    popperInstance.value = createPopover(popoverRef.value, contentRef.value, arrowRef.value, {
+      ...props.popper,
+      placement: props.placement,
+    });
+
+    if (props.disableClickAway) {
+      return;
+    }
+
+    clickAwayInstance = useClickAway({
+      target: () => instance?.content?.parentElement,
+      handler: () => {
+        instance?.hide();
+      },
+    });
+  });
+
+  onBeforeUnmount(() => {
+    if (clickAwayInstance) {
+      const { onBeforeUnmount } = clickAwayInstance;
+      onBeforeUnmount();
+    }
+    instance?.destroy();
+  });
+
+  return {
+    popoverEnter,
+    popoverLeave,
+    popoverRef, contentRef, arrowRef,
+    popperInstance,
+    style, arrowStyle,
+    placement,
+  };
+}

package/components/base/progress/api.ts

@@ -0,0 +1,20 @@
+/**
+ * @description progress api
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { ProgressProps, ProgressStatus, ProgressType } from './props';
+
+export const props: MCOPO<ProgressProps> = {
+  type: { type: String as unknown as MPropType<ProgressType>, default: 'line' },
+  value: { type: Number, default: 0 },
+  max: { type: Number, default: 100 },
+  showInfo: { type: Boolean, default: true },
+  status: { type: String as unknown as MPropType<ProgressStatus>, default: 'default' },
+  strokeWidth: { type: Number, default: 4 },
+  width: { type: Number, default: 80 },
+};

package/components/base/progress/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @description progress core
+ * @author 阿怪
+ * @date 2025/02/25 00:00
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { props } from './api';
+import { useProgress } from './useProgress';
+
+export const ProgressCore = {
+  props,
+  useProgress,
+};
+
+export type { ProgressProps, ProgressStatus } from './props';

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

@@ -0,0 +1,68 @@
+/**
+ * @description progress props type
+ * @author 阿怪
+ * @date 2026/2/27
+ * @version v1.1.0
+ *
+ * @name m-progress
+ * @docDescription Progress component.
+ *                 进度条组件。
+ * @docUrl https://shuimo.design/progress
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type ProgressStatus = 'default' | 'success' | 'warning' | 'danger';
+
+export declare type ProgressType = 'line' | 'circle';
+
+export declare type ProgressProps = {
+  /**
+   * @description progress type. 进度条类型：line 线性 | circle 环形
+   * @type ProgressType
+   * @default 'line'
+   */
+  type?: ProgressType,
+  /**
+   * @description progress value
+   *              进度条的值（0 ~ max）
+   * @type number
+   * @default 0
+   */
+  value?: number,
+  /**
+   * @description progress value max
+   *              进度条最大值
+   * @type number
+   * @default 100
+   */
+  max?: number,
+  /**
+   * @description display value
+   *              是否显示进度值
+   * @type boolean
+   * @default true
+   */
+  showInfo?: boolean,
+  /**
+   * @description status color variant
+   *              状态颜色变体：default | success | warning | danger
+   * @type ProgressStatus
+   * @default 'default'
+   */
+  status?: ProgressStatus,
+  /**
+   * @description stroke width in px
+   *              进度条粗细（px）
+   * @type number
+   * @default 4
+   */
+  strokeWidth?: number,
+  /**
+   * @description circle diameter in px (only for type='circle')
+   *              环形进度条直径（px），仅 type='circle' 时生效
+   * @type number
+   * @default 80
+   */
+  width?: number,
+};

package/components/base/progress/useProgress.ts

@@ -0,0 +1,28 @@
+/**
+ * @description progress hook
+ * @author 阿怪
+ * @date 2025/02/25 00:00
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { computed } from 'vue';
+import { ProgressProps } from './props';
+
+/**
+ * @description 清除多余小数位，保留两位小数
+ */
+const clearZero = (num: number) => {
+  const str = num.toString();
+  const index = str.indexOf('.');
+  if (index === -1) { return num; }
+  return str.slice(0, index + 3);
+};
+
+export function useProgress(props: Required<ProgressProps>) {
+  const percentage = computed(() => clearZero((props.value * 100 / props.max)));
+
+  return {
+    percentage,
+  };
+}

package/components/base/radio/api.ts

@@ -0,0 +1,19 @@
+/**
+ * @description radio api
+ * @author 阿怪
+ * @date 2025/02/25 00:00
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO } from '../../types/props';
+import { RadioProps } from './props';
+
+export const props: MCOPO<RadioProps> = {
+  label: { type: [String, Number], default: '' },
+  name: { type: String, default: undefined },
+  checked: { type: Boolean, default: undefined },
+  value: { type: [String, Number], default: '' },
+  modelValue: { type: null, default: '' },
+  disabled: { type: Boolean, default: false },
+};

package/components/base/radio/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @description radio core
+ * @author 阿怪
+ * @date 2025/02/25 00:00
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { props } from './api';
+import { initChecked, getNewModelValue, createRadioId } from './useRadio';
+
+export const RadioCore = {
+  props,
+  initChecked,
+  getNewModelValue,
+  createRadioId,
+};
+
+export { initChecked, getNewModelValue, createRadioId } from './useRadio';

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

@@ -0,0 +1,59 @@
+/**
+ * @description radio props type
+ * @author 阿怪
+ * @date 2025/02/25 00:00
+ * @version v1.0.0
+ *
+ * @name m-radio
+ * @docDescription Radio component.
+ *                 单选组件。
+ * @docUrl https://shuimo.design/radio
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type RadioProps = {
+  /**
+   * @description radio label
+   *              单选框的标签值
+   * @type string | number
+   * @default ''
+   */
+  label?: string | number,
+  /**
+   * @description radio name
+   *              单选框的name值
+   * @type string | undefined
+   * @default undefined
+   */
+  name?: string,
+  /**
+   * @description radio checked
+   *              是否选中
+   * @default undefined
+   */
+  checked?: boolean | undefined | null,
+  /**
+   * @description radio value
+   *              单选框的值
+   * @default undefined
+   */
+  value?: string | number,
+  /**
+   * @description value
+   *              绑定值
+   * @type string | number | boolean
+   * @default ''
+   */
+  modelValue?: string | number | boolean,
+  /**
+   * @description radio disabled
+   *              是否禁用
+   * @default false
+   */
+  disabled?: boolean,
+};
+
+export declare type RadioEvents = {
+  onClick?: (e: MouseEvent, value?: string | number) => void
+};

package/components/base/radio/useRadio.ts

@@ -0,0 +1,11 @@
+/**
+ * @description radio hook
+ * @author 阿怪
+ * @date 2025/02/25 00:00
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export { initChecked, getNewModelValue } from '../../../compositions/input/useBooleanInput';
+export const createRadioId = () => `m-radio-${Math.random().toString(36).substring(2)}`;

package/components/base/rate/api.ts

@@ -0,0 +1,18 @@
+/**
+ * @description rate api
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO } from '../../types/props';
+import { RateProps } from './props';
+
+export const props: MCOPO<RateProps> = {
+  modelValue: { type: Number, default: 0 },
+  count: { type: Number, default: 5 },
+  allowHalf: { type: Boolean, default: false },
+  readonly: { type: Boolean, default: false },
+  disabled: { type: Boolean, default: false },
+};

package/components/base/rate/index.ts

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

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

@@ -0,0 +1,49 @@
+/**
+ * @description rate props type
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * @name k-rate
+ * @docDescription Rate（评分）组件。
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type RateProps = {
+  /**
+   * @description 当前评分值（v-model）
+   * @type number
+   * @default 0
+   */
+  modelValue?: number,
+  /**
+   * @description 星星总数
+   * @type number
+   * @default 5
+   */
+  count?: number,
+  /**
+   * @description 是否允许半星
+   * @type boolean
+   * @default false
+   */
+  allowHalf?: boolean,
+  /**
+   * @description 是否只读（仅展示，不可交互，不灰显）
+   * @type boolean
+   * @default false
+   */
+  readonly?: boolean,
+  /**
+   * @description 是否禁用
+   * @type boolean
+   * @default false
+   */
+  disabled?: boolean,
+};
+
+export declare type RateEmits = {
+  'onUpdate:modelValue'?: (value: number) => void,
+  onChange?: (value: number) => void,
+};