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

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';
+import { usePopover } from './usePopover';
+
+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,234 @@
+/**
+ * @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 { onBeforeUnmount, 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() {
+    this.popperInstance?.clear?.();
+    this.visible = false;
+    this.onShow = undefined;
+    this.onHide = undefined;
+  }
+}
+
+// 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 onBeforeUnmountEvents: 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?
+      },
+    });
+  });
+
+  onBeforeUnmount(() => {
+    if (clickAwayInstance) {
+      const { onBeforeUnmount } = clickAwayInstance;
+      onBeforeUnmount();
+    }
+    instance?.destroy();
+  });
+
+
+  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: {
+      onBeforeUnmountEvents,
+    },
+  };
+}

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';

package/components/other/darkMode/props.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @description dark mode api type
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.1.0
+ *
+ * @name m-dark-mode
+ * @docDescription Headless dark mode component.
+ *                 无样式暗色模式组件，用于切换日夜间模式。
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type DarkModeProps = {
+  /**
+   * @description 开关绑定值（true = 暗色）
+   * @type boolean
+   * @default false
+   */
+  modelValue?: boolean;
+  /**
+   * @description 自动初始化模式，跟随系统媒体查询
+   * @type boolean
+   * @default false
+   */
+  autoMode?: boolean;
+  /**
+   * @description 初始化事件，返回 true 则执行自动初始化
+   * @type function
+   */
+  initHandler?: () => boolean;
+  /**
+   * @description localStorage 持久化 key，传入则启用持久化
+   * @type string
+   */
+  storageKey?: string;
+};

package/components/other/darkMode/useDarkMode.ts

@@ -0,0 +1,129 @@
+/**
+ * @description dark mode composable
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.1.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 核心约定：
+ *   - 暗色模式通过 html[dark] attribute 标记（与 lib 层保持一致）
+ *   - 传入 storageKey 时启用 localStorage 持久化
+ *   - autoMode 时监听系统媒体查询变化，并在卸载时清理监听器
+ */
+import { ref, watch, onMounted, onUnmounted } from 'vue';
+import { type HookContext } from '../../types/hook';
+import { DarkModeProps } from './props';
+
+/** 将暗色状态同步到 html[dark] attribute */
+function applyDarkAttr(isDark: boolean) {
+  if (typeof document === 'undefined') return;
+  const html = document.querySelector('html');
+  if (!html) return;
+  if (isDark) {
+    html.setAttribute('dark', '');
+  } else {
+    html.removeAttribute('dark');
+  }
+}
+
+/** 从 localStorage 读取持久化的暗色模式偏好，未找到返回 null */
+function readStorage(storageKey: string): boolean | null {
+  if (typeof window === 'undefined') return null;
+  const stored = localStorage.getItem(storageKey);
+  if (stored === null) return null;
+  return stored === 'true';
+}
+
+/** 将暗色模式偏好写入 localStorage */
+function writeStorage(storageKey: string, isDark: boolean) {
+  if (typeof window === 'undefined') return;
+  localStorage.setItem(storageKey, isDark.toString());
+}
+
+export function useDarkMode(
+  props: DarkModeProps,
+  ctx: Pick<HookContext, 'emit'>,
+) {
+  const isDark = ref(props.modelValue ?? false);
+
+  /** 切换暗色模式，同步 DOM 并触发事件 */
+  const toggle = () => {
+    isDark.value = !isDark.value;
+    ctx.emit('update:modelValue', isDark.value);
+    ctx.emit('change', isDark.value);
+  };
+
+  // 监听外部 modelValue 变化，同步到内部状态
+  watch(
+    () => props.modelValue,
+    (val) => {
+      if (val !== undefined && val !== isDark.value) {
+        isDark.value = val;
+      }
+    },
+  );
+
+  // 内部状态变化时同步 DOM 及 localStorage
+  watch(isDark, (val) => {
+    applyDarkAttr(val);
+    if (props.storageKey) {
+      writeStorage(props.storageKey, val);
+    }
+  });
+
+  // 系统媒体查询变化回调
+  let mediaQuery: MediaQueryList | null = null;
+  const onSystemChange = (event: MediaQueryListEvent) => {
+    isDark.value = event.matches;
+    ctx.emit('update:modelValue', isDark.value);
+    ctx.emit('change', isDark.value);
+  };
+
+  onMounted(() => {
+    // 1. 若有 initHandler，优先交由外部决定是否自动初始化
+    if (props.initHandler) {
+      const shouldAutoInit = props.initHandler();
+      if (!shouldAutoInit) {
+        // initHandler 已处理好初始状态，只需同步 DOM
+        applyDarkAttr(isDark.value);
+        return;
+      }
+    } else if (props.storageKey) {
+      // 2. 无 initHandler 但有 storageKey，尝试从 localStorage 读取
+      const stored = readStorage(props.storageKey);
+      if (stored !== null) {
+        isDark.value = stored;
+        applyDarkAttr(isDark.value);
+        // 有存储值则不再跟随系统
+        return;
+      }
+    }
+
+    // 3. autoMode：跟随系统媒体查询
+    if (props.autoMode && typeof window !== 'undefined') {
+      mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+      isDark.value = mediaQuery.matches;
+      ctx.emit('update:modelValue', isDark.value);
+      ctx.emit('change', isDark.value);
+      mediaQuery.addEventListener('change', onSystemChange);
+    }
+
+    // 挂载时应用当前状态
+    applyDarkAttr(isDark.value);
+  });
+
+  onUnmounted(() => {
+    // 清理媒体查询监听器，防止内存泄漏
+    if (mediaQuery) {
+      mediaQuery.removeEventListener('change', onSystemChange);
+      mediaQuery = null;
+    }
+  });
+
+  return {
+    isDark,
+    toggle,
+    applyDarkAttr,
+  };
+}

package/components/template/border/api.ts

@@ -0,0 +1,18 @@
+/**
+ * @description border 运行时 props
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO } from '../../types/props';
+import { BorderProps } from './props';
+
+export const props: MCOPO<BorderProps> = {
+  top: { type: [Boolean, String], default: true },
+  right: { type: [Boolean, String], default: true },
+  bottom: { type: [Boolean, String], default: true },
+  left: { type: [Boolean, String], default: true },
+  insteadMain: { type: [Boolean, String], default: false },
+};

package/components/template/border/index.ts

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

package/components/template/border/props.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @description border props 类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type BorderProps = {
+  /**
+   * @description 顶部边框是否显示
+   * @default true
+   * @type boolean | string
+   */
+  top?: boolean | string;
+  /**
+   * @description 右侧边框是否显示
+   * @default true
+   * @type boolean | string
+   */
+  right?: boolean | string;
+  /**
+   * @description 底部边框是否显示
+   * @default true
+   * @type boolean | string
+   */
+  bottom?: boolean | string;
+  /**
+   * @description 左侧边框是否显示
+   * @default true
+   * @type boolean | string
+   */
+  left?: boolean | string;
+  /**
+   * @description 是否用 slot 替换主容器 div
+   * @default false
+   * @type boolean | string
+   */
+  insteadMain?: boolean | string;
+};

package/components/template/breadcrumb/api.ts

@@ -0,0 +1,15 @@
+/**
+ * @description breadcrumb 运行时 props
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO } from '../../types/props';
+import { BreadcrumbProps } from './props';
+
+export const props: MCOPO<BreadcrumbProps> = {
+  separator: { type: String, default: '/' },
+  items: { type: Array, default: () => [] },
+};