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

package/components/message/notification/props.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @description notification 组件 props 类型定义
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+/**
+ * 通知类型
+ */
+export type NotificationType = 'success' | 'warning' | 'error' | 'info';
+
+/**
+ * 通知显示位置
+ */
+export type NotificationPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+
+/**
+ * 单条通知 props
+ */
+export declare type NotificationProps = {
+  /**
+   * @description 通知标题
+   */
+  title: string;
+  /**
+   * @description 通知正文内容
+   */
+  message?: string;
+  /**
+   * @description 通知类型
+   * @default 'info'
+   */
+  type?: NotificationType;
+  /**
+   * @description 显示时长（毫秒），0 表示不自动关闭
+   * @default 4500
+   */
+  duration?: number;
+  /**
+   * @description 通知显示位置
+   * @default 'top-right'
+   */
+  position?: NotificationPosition;
+  /**
+   * @description 是否显示关闭按钮
+   * @default true
+   */
+  closable?: boolean;
+  /**
+   * @description 与屏幕边缘的偏移量（像素）
+   * @default 16
+   */
+  offset?: number;
+};
+
+/**
+ * 通知事件类型
+ */
+export declare type NotificationEvents = {
+  onClose?: () => void;
+};

package/components/message/notification/useNotification.ts

@@ -0,0 +1,79 @@
+/**
+ * @description notification 队列 composable
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { ref } from 'vue';
+import { NotificationType, NotificationPosition } from './props';
+
+/**
+ * 通知队列中每一条通知的内部结构
+ */
+export interface NotificationItem {
+  id: number;
+  title: string;
+  message: string;
+  type: NotificationType;
+  duration: number;
+  position: NotificationPosition;
+  closable: boolean;
+}
+
+/**
+ * 创建通知时的配置参数
+ */
+export interface NotificationAddOptions {
+  title: string;
+  message?: string;
+  type?: NotificationType;
+  duration?: number;
+  position?: NotificationPosition;
+  closable?: boolean;
+}
+
+/**
+ * 通知队列 composable
+ * 管理通知的增删与自动关闭定时器
+ */
+export function useNotificationQueue() {
+  const notifications = ref<NotificationItem[]>([]);
+  let nextId = 0;
+
+  /**
+   * 添加一条通知，duration > 0 时自动移除
+   */
+  const add = (options: NotificationAddOptions): number => {
+    const id = nextId++;
+    const item: NotificationItem = {
+      id,
+      title: options.title,
+      message: options.message ?? '',
+      type: options.type ?? 'info',
+      duration: options.duration ?? 4500,
+      position: options.position ?? 'top-right',
+      closable: options.closable ?? true,
+    };
+    notifications.value.push(item);
+
+    if (item.duration > 0) {
+      setTimeout(() => remove(id), item.duration);
+    }
+
+    return id;
+  };
+
+  /**
+   * 按 id 移除一条通知
+   */
+  const remove = (id: number): void => {
+    const idx = notifications.value.findIndex(n => n.id === id);
+    if (idx !== -1) {
+      notifications.value.splice(idx, 1);
+    }
+  };
+
+  return { notifications, add, remove };
+}

package/components/message/popover/MPopover.tsx

@@ -0,0 +1,94 @@
+/**
+ * @description MPopover
+ * @author youus
+ * @date 2022/4/3 18:07
+ * @version v2.0.0-process
+ *
+ * Hello, humor
+ * v2.0.0-process 阿怪 准备重构，搭建模版
+ */
+import { defineComponent, ref, watch } from 'vue';
+import { props } from './api.ts';
+import useTeleport from '../../../compositions/common/useTeleport.ts';
+import { usePopover } from './usePopover.ts';
+import './popover.css';
+import { PopoverProps } from './props';
+
+
+export default defineComponent((_props: PopoverProps, { slots, emit, expose }) => {
+  const props = _props as Required<PopoverProps>;
+
+  if (!slots.content) {
+    console.error('MPopover: content is required');
+    return () => (<></>);
+  }
+
+  if (!slots.default) {
+    console.error('MPopover: trigger is required');
+    return () => (<></>);
+  }
+
+
+  const placementRef = ref(props.placement);
+  const {
+    getContent,
+    popoverEnter,
+    popoverLeave,
+    popoverRef, contentRef, arrowRef,
+    popperInstance,
+    style, arrowStyle,
+  } = usePopover(
+    { props, value: { placement: placementRef } },
+    {
+      onShow: () => {
+        emit('update:show', true);
+      },
+      onHide: () => {
+        emit('update:show', false);
+      },
+    },
+  );
+
+  const show = async () => {
+    await popperInstance.value?.show();
+  };
+  const hide = () => {
+    popperInstance.value?.hide();
+  };
+
+  expose({ show, hide });
+
+  watch(() => props.show, () => {
+    if (props.show) {show();} else {hide();}
+  });
+
+  const handleClick = async () => {
+    if (props.hover) {return;}
+    await popperInstance.value?.toggle();
+  };
+
+
+  return () => {
+    return <div class="m-popover" data-popper-placement={placementRef.value}
+                onMouseleave={popoverLeave}>
+      <div class="m-popover-default-wrapper"
+           ref={popoverRef}
+           onMouseenter={popoverEnter}
+           onClick={handleClick}>
+        {slots.default?.()}
+      </div>
+      <div class="m-popover-content" ref={contentRef} style={style.value}>
+        {getContent(props, () => slots.content?.(), useTeleport)}
+        {
+          // todo when content not render arrow should not render
+          slots.arrow ?
+            <div class="m-popover-arrow" ref={arrowRef} style={arrowStyle.value}>{slots.arrow()}</div> : null
+        }
+      </div>
+    </div>;
+  };
+}, {
+  name: 'MPopover',
+  props,
+  emits: ['open:popper', 'close:popper', 'update:show'],
+});

package/components/message/popover/api.ts

@@ -0,0 +1,54 @@
+/**
+ * @description popover api
+ * @author 阿怪
+ * @date 2023/4/23 11:53
+ * @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',
+    // validator: (value: string) =>
+    //   [
+    //     'auto',
+    //     'auto-start',
+    //     'auto-end',
+    //     'top',
+    //     'top-start',
+    //     'top-end',
+    //     'bottom',
+    //     'bottom-start',
+    //     'bottom-end',
+    //     'right',
+    //     'right-start',
+    //     'right-end',
+    //     'left',
+    //     'left-start',
+    //     'left-end'
+    //   ].includes(value)
+  },
+  mountRender: { type: Boolean, default: false },
+  disableClickAway: { type: Boolean, default: false },
+  // offsetSkid: { type: String, default: '0' },
+  // offsetDistance: { type: String, default: '0' },
+  hover: { type: Boolean, default: false },
+  show: { type: Boolean, default: null },
+  // disabled: { type: Boolean, default: false },
+  // openDelay: { type: Number, default: 0 },
+  // closeDelay: { type: Number, default: 0 },
+  // interactive: { type: Boolean, default: true },
+  // locked: { type: Boolean, default: false },
+  content: { type: String, default: '' },
+  popper: {
+    type: Object, default: () => ({}),
+  },
+  teleport: { type: [Object, Boolean], default: undefined },
+  title: { type: String, default: undefined },
+};

package/components/message/popover/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @description
+ * @author 阿怪
+ * @date 2024/11/29 09:22
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { props } from './api.ts';
+import { usePopover } from './usePopover.ts';
+
+export const MessagePopoverCore = {
+  props,
+  usePopover,
+};
+
+export type { PopoverProps as MessagePopoverProps } from './props';

package/components/message/popover/popover.css

@@ -0,0 +1,21 @@
+.m-popover {
+  display: inline-block;
+}
+
+.m-popover-content {
+  position: absolute;
+  display: none;
+  z-index: 9;
+  width: max-content;
+  top: 0;
+  left: 0;
+}
+
+.m-popover-default-wrapper {
+  display: inline-block;
+}
+
+.m-popover-arrow {
+  position: absolute;
+  display: none;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * @description popover api type
+ * @author youus
+ * @date 2022/4/4 01:22
+ * @version v1.0.0
+ *
+ * @name m-popover
+ * @docDescription Popover component with shuimo-ui style.
+ *                 水墨组件的弹出框组件。
+ * @docUrl https://shuimo.design/popover
+ *
+ * Hello, humor
+ */
+import { Placement, PopperConfig } from '../../../compositions/popper/usePopper.ts';
+import { MTeleportProps } from '../../../types/common/common';
+
+
+export type PopoverProps = {
+  /**
+   * @description popover display placement
+   * @type Placement
+   * @default bottom
+   */
+  placement?: Placement,
+  /**
+   * @description Whether to render the popover content when the component is mounted
+   * @type boolean
+   * @default false
+   */
+  mountRender?: boolean,
+  /**
+   * @description Disables automatically closing the popover when the user clicks away from it
+   * @type boolean
+   * @default false
+   */
+  disableClickAway?: boolean,
+  /**
+   * @description If the content is just a simple string, it can be passed in as a prop
+   * @type any
+   * @default ''
+   */
+  content?: any,
+  /**
+   * @description Trigger the popper on hover
+   * @type boolean
+   * @default false
+   */
+  hover?: boolean,
+  /**
+   * @description display content value
+   *              是否显示参数
+   * @type boolean
+   * @default false
+   */
+  show?: boolean,
+  /**
+   * @description floating-ui options, look: https://floating-ui.com/
+   * @type PopperConfig
+   * @default {}
+   */
+  popper?: PopperConfig,
+  /**
+   * @description popover teleport
+   *              弹出框传送
+   * @type teleport props
+   * @default undefined
+   */
+  teleport?: MTeleportProps | undefined | boolean,
+  /**
+   * @description popover title
+   *              气泡标题，传入时在内容上方渲染标题行
+   * @type string
+   * @default undefined
+   */
+  title?: string,
+};

package/components/message/popover/usePopover.ts

@@ -0,0 +1,230 @@
+/**
+ * @description core usePopover hook
+ * @author 阿怪
+ * @date 2023/1/29 10:39
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { Placement, PopperConfig, PositionStyle, usePopper } from '../../../compositions/popper/usePopper.ts';
+import useClickAway from '../../../compositions/popper/useClickAway';
+import { Options } from '../../../compositions/common/defineCore';
+// import MPrinter from '../../other/printer/Printer';
+import { PopoverProps } from './props';
+import { onBeforeMount, onMounted, ref, type Ref, shallowRef } from 'vue';
+
+
+// const error = MPrinter('水墨Popover组件').error;
+export type IPopper = ReturnType<typeof usePopper>;
+
+
+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, /* default */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() {
+
+  }
+}
+
+// magic tool type, get array element type
+type ArrayElement<ArrayType> =
+  ArrayType extends readonly (infer ElementType)[] ? ElementType : never;
+
+export function usePopover(
+  options: Options<{ props: PopoverProps, value: { placement: Placement } }>,
+  lifecycle?: { /* event can't use optional... */
+    onShow?: Function,
+    onHide?: Function
+  }) {
+  const style = ref();
+  const arrowStyle = ref();
+  const placement = ref(options.value.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: options.props.show },
+      active,
+      content,
+      arrow,
+      config,
+      {
+        onShow: () => {
+          clickAwayInstance?.add();
+          lifecycle?.onShow?.();
+        },
+        onHide: () => {
+          clickAwayInstance?.remove();
+          lifecycle?.onHide?.();
+        },
+      });
+    return instance;
+  };
+
+  const props = options.props;
+  const popoverEnter = () => {
+    if (props.hover) {
+      instance?.show();
+    }
+  };
+  const popoverLeave = () => {
+    if (props.hover) {
+      instance?.hide();
+    }
+  };
+
+  const onBeforeDestroyEvents: Function[] = [];
+
+  onMounted(() => {
+    if (!popoverRef.value || !contentRef.value) {
+      return;
+    }
+    popperInstance.value = createPopover(popoverRef.value, contentRef.value, arrowRef.value, {
+      ...props.popper,
+      placement: props.placement,
+    });
+
+    if (options.props.disableClickAway) {
+      return;
+    }
+
+    clickAwayInstance = useClickAway({
+      target: () => instance?.content?.parentElement,
+      handler: () => {
+        instance?.hide();
+        // emits?
+      },
+    });
+  });
+
+  onBeforeMount(() => {
+    if (clickAwayInstance) {
+      const { onBeforeDestroy } = clickAwayInstance;
+      onBeforeDestroy();
+    }
+  });
+
+
+  const getContent = <T>(
+    props: PopoverProps,
+    getContentSlot: () => T,
+    useTeleport: (options: any) => ArrayElement<T> | T,
+    _instance = instance,
+  ) => {
+    const contentTeleportWrapper = () => {
+      if (props.teleport) {
+        return useTeleport({
+          teleportProps: props.teleport,
+          slot: getContentSlot(),
+        });
+      }
+      return getContentSlot();
+    };
+
+    if (props.mountRender) {
+      return contentTeleportWrapper();
+    }
+    if (!_instance || !_instance.visible) {
+      return null;
+    }
+    return contentTeleportWrapper();
+  };
+
+  return {
+    getContent,
+    popoverEnter,
+    popoverLeave,
+    popoverRef, contentRef, arrowRef,
+    popperInstance,
+    style, arrowStyle,
+    lifecycle: {
+      onBeforeDestroyEvents,
+    },
+  };
+}

package/components/other/darkMode/api.ts

@@ -0,0 +1,17 @@
+/**
+ * @description dark mode api
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { DarkModeProps } from './props';
+
+export const props: MCOPO<DarkModeProps> = {
+  modelValue: { type: Boolean, default: false },
+  autoMode: { type: Boolean, default: false },
+  initHandler: { type: Function as MPropType<() => boolean>, default: undefined },
+  storageKey: { type: String, default: undefined },
+};

package/components/other/darkMode/index.ts

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