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

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 { 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,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ctx: { emit: (event: string, ...args: any[]) => void },
+) {
+  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: () => [] },
+};

package/components/template/breadcrumb/index.ts

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

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

@@ -0,0 +1,45 @@
+/**
+ * @description breadcrumb props 类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+/**
+ * 面包屑单项数据结构
+ */
+export declare type BreadcrumbItemOption = {
+  /**
+   * @description 显示文本
+   * @type string
+   */
+  label: string;
+  /**
+   * @description 跳转链接，有值时渲染为 <a> 标签
+   * @type string
+   */
+  href?: string;
+  /**
+   * @description 是否禁用
+   * @default false
+   * @type boolean
+   */
+  disabled?: boolean;
+};
+
+export declare type BreadcrumbProps = {
+  /**
+   * @description 分隔符
+   * @default '/'
+   * @type string
+   */
+  separator?: string;
+  /**
+   * @description 面包屑数据项列表
+   * @default []
+   * @type BreadcrumbItemOption[]
+   */
+  items?: BreadcrumbItemOption[];
+};

package/components/template/descriptions/api.ts

@@ -0,0 +1,23 @@
+/**
+ * @description descriptions api
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { DescriptionsProps, DescriptionsItemProps } from './props';
+
+export const descriptionsProps: MCOPO<DescriptionsProps> = {
+  title: { type: String, default: '' },
+  column: { type: Number, default: 3 },
+  direction: { type: String as MPropType<'horizontal' | 'vertical'>, default: 'horizontal' },
+  border: { type: Boolean, default: false },
+  size: { type: String as MPropType<'small' | 'medium' | 'large'>, default: 'medium' },
+};
+
+export const descriptionsItemProps: MCOPO<DescriptionsItemProps> = {
+  label: { type: String, required: true },
+  span: { type: Number, default: 1 },
+};

package/components/template/descriptions/index.ts

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

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

@@ -0,0 +1,54 @@
+/**
+ * @description descriptions api type
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type DescriptionsProps = {
+  /**
+   * @description 标题文本
+   * @type string
+   */
+  title?: string,
+  /**
+   * @description 每行列数
+   * @type number
+   * @default 3
+   */
+  column?: number,
+  /**
+   * @description 标签与值的布局方向
+   * @type 'horizontal' | 'vertical'
+   * @default 'horizontal'
+   */
+  direction?: 'horizontal' | 'vertical',
+  /**
+   * @description 是否显示边框
+   * @type boolean
+   * @default false
+   */
+  border?: boolean,
+  /**
+   * @description 尺寸，影响内边距
+   * @type 'small' | 'medium' | 'large'
+   * @default 'medium'
+   */
+  size?: 'small' | 'medium' | 'large',
+};
+
+export declare type DescriptionsItemProps = {
+  /**
+   * @description 标签文本
+   * @type string
+   */
+  label: string,
+  /**
+   * @description 列跨度
+   * @type number
+   * @default 1
+   */
+  span?: number,
+};

package/components/template/form/api.ts

@@ -0,0 +1,23 @@
+/**
+ * @description form 运行时 props
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO } from '../../types/props';
+import { FormProps, FormItemProps } from './props';
+
+export const formProps: MCOPO<FormProps> = {
+  inline: { type: Boolean, default: false },
+  submit: { type: Boolean, default: false },
+  model: { type: Object, default: undefined },
+  labelWidth: { type: String, default: undefined },
+};
+
+export const formItemProps: MCOPO<FormItemProps> = {
+  label: { type: String, default: '' },
+  prop: { type: String, default: '' },
+  required: { type: Boolean, default: false },
+};

package/components/template/form/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @description form core 导出
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { formProps, formItemProps } from './api';
+
+/**
+ * FormCore 使用包装对象导出，避免 formProps / formItemProps 两个 props 名称与其他组件冲突。
+ * headless / lib 均通过解构 FormCore 取用。
+ */
+export const FormCore = {
+  props: formProps,
+  formItemProps,
+};
+
+export type { FormProps, FormItemProps } from './props';

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

@@ -0,0 +1,60 @@
+/**
+ * @description form 组件类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+/**
+ * Form 组件 Props 类型
+ */
+export declare type FormProps = {
+  /**
+   * @description form 是否行内显示
+   * @type boolean
+   * @default false
+   */
+  inline?: boolean;
+  /**
+   * @description form 是否允许默认提交行为
+   * @type boolean
+   * @default false
+   */
+  submit?: boolean;
+  /**
+   * @description 表单数据对象
+   * @type Record<string, any>
+   */
+  model?: Record<string, unknown>;
+  /**
+   * @description 标签宽度，如 '80px'
+   * @type string
+   */
+  labelWidth?: string;
+};
+
+/**
+ * FormItem 组件 Props 类型
+ */
+export declare type FormItemProps = {
+  /**
+   * @description 表单项标题
+   * @type string
+   * @default ''
+   */
+  label?: string;
+  /**
+   * @description 表单内置 label 的原生 for/prop 属性
+   * @type string
+   * @default ''
+   */
+  prop?: string;
+  /**
+   * @description 是否必填，显示红色星号
+   * @type boolean
+   * @default false
+   */
+  required?: boolean;
+};

package/components/template/grid/api.ts

@@ -0,0 +1,20 @@
+/**
+ * @description grid 运行时 props
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { GridProps } from './props';
+
+export const props: MCOPO<GridProps> = {
+  h: { type: Number, default: undefined },
+  w: { type: Number, default: undefined },
+  gap: { type: [Number, String], default: 0 },
+  colGap: { type: [Number, String], default: undefined },
+  rowGap: { type: [Number, String], default: undefined },
+  direction: { type: String as MPropType<'column' | 'row'>, default: 'row' },
+  cols: { type: Number, default: undefined },
+};

package/components/template/grid/index.ts

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

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

@@ -0,0 +1,48 @@
+/**
+ * @description grid props 类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export declare type GridProps = {
+  /**
+   * @description 网格高度
+   * @type number
+   */
+  h?: number;
+  /**
+   * @description 网格宽度
+   * @type number
+   */
+  w?: number;
+  /**
+   * @description 通用间距，同时作用于行列
+   * @default 0
+   * @type number | string
+   */
+  gap?: number | string;
+  /**
+   * @description 列间距，优先级高于 gap
+   * @type number | string
+   */
+  colGap?: number | string;
+  /**
+   * @description 行间距，优先级高于 gap
+   * @type number | string
+   */
+  rowGap?: number | string;
+  /**
+   * @description 子元素排列方向
+   * @default 'row'
+   * @type 'column' | 'row'
+   */
+  direction?: 'column' | 'row';
+  /**
+   * @description 列数，设置后使用 CSS grid 布局，grid-template-columns: repeat(cols, 1fr)
+   * @type number
+   */
+  cols?: number;
+};

package/components/template/menu/api.ts

@@ -0,0 +1,26 @@
+/**
+ * @description menu 运行时 props
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { MCOPO, MPropType } from '../../types/props';
+import { MenuProps } from './props';
+
+export const DEFAULT_MENU_CONFIG = {
+  key: 'key',
+  label: 'label',
+  children: 'children',
+};
+
+export const props: MCOPO<MenuProps> = {
+  data: { type: Array, default: () => [] },
+  config: { type: Object, default: () => ({ ...DEFAULT_MENU_CONFIG }) },
+  checkbox: { type: Boolean, default: false },
+  defaultExpandAll: { type: Boolean, default: false },
+  checkedKeys: { type: Array, default: () => [] },
+  mode: { type: String as MPropType<'vertical' | 'horizontal'>, default: 'vertical' },
+  active: { type: [String, Number], default: undefined },
+};

package/components/template/menu/index.ts

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