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

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/__tests__/useMenu.test.ts

@@ -0,0 +1,157 @@
+/**
+ * @description useMenu 测试
+ * @author 阿怪
+ * @date 2026/3/23
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { useMenu } from '../useMenu';
+
+const SAMPLE_DATA = [
+  {
+    key: 'home', label: '首页',
+  },
+  {
+    key: 'system', label: '系统管理', children: [
+      { key: 'user', label: '用户管理' },
+      { key: 'role', label: '角色管理' },
+    ],
+  },
+  {
+    key: 'about', label: '关于',
+  },
+];
+
+describe('useMenu', () => {
+  it('initNodes 构建节点树', () => {
+    const { nodesRef, nodeMap } = useMenu({ data: SAMPLE_DATA });
+
+    expect(nodesRef.value).toHaveLength(3);
+    expect(nodeMap.size).toBe(5); // 3 + 2 children
+  });
+
+  it('根节点 isRoot=true，子节点有 parent', () => {
+    const { nodeMap } = useMenu({ data: SAMPLE_DATA });
+
+    expect(nodeMap.get('home')!.isRoot).toBe(true);
+    expect(nodeMap.get('user')!.isRoot).toBe(false);
+    expect(nodeMap.get('user')!.parent).toBe(nodeMap.get('system'));
+  });
+
+  it('defaultExpandAll 展开所有节点', () => {
+    const { nodeMap } = useMenu({ data: SAMPLE_DATA, defaultExpandAll: true });
+    expect(nodeMap.get('system')!.expand).toBe(true);
+  });
+
+  it('默认不展开', () => {
+    const { nodeMap } = useMenu({ data: SAMPLE_DATA });
+    expect(nodeMap.get('system')!.expand).toBe(false);
+  });
+
+  it('toggleExpand 切换展开', () => {
+    const { nodeMap, toggleExpand } = useMenu({ data: SAMPLE_DATA });
+    const node = nodeMap.get('system')!;
+
+    expect(node.expand).toBe(false);
+    toggleExpand(node);
+    expect(node.expand).toBe(true);
+    toggleExpand(node);
+    expect(node.expand).toBe(false);
+  });
+
+  it('setActive 激活节点并取消其他激活', () => {
+    const emit = vi.fn();
+    const { nodeMap, setActive } = useMenu({ data: SAMPLE_DATA }, emit);
+
+    setActive(nodeMap.get('home')!);
+    expect(nodeMap.get('home')!.isActive).toBe(true);
+    expect(emit).toHaveBeenCalledWith('update:active', 'home');
+
+    setActive(nodeMap.get('about')!);
+    expect(nodeMap.get('home')!.isActive).toBe(false);
+    expect(nodeMap.get('about')!.isActive).toBe(true);
+  });
+
+  it('受控 active 初始化', () => {
+    const { nodeMap } = useMenu({ data: SAMPLE_DATA, active: 'about' });
+    expect(nodeMap.get('about')!.isActive).toBe(true);
+    expect(nodeMap.get('home')!.isActive).toBe(false);
+  });
+
+  it('toggleChecked 切换选中', () => {
+    const { nodeMap, toggleChecked } = useMenu({ data: SAMPLE_DATA });
+    const node = nodeMap.get('user')!;
+
+    toggleChecked(node, true);
+    expect(node.checked).toBe(true);
+    expect(node.indeterminate).toBe(false);
+
+    toggleChecked(node, false);
+    expect(node.checked).toBe(false);
+  });
+
+  it('getCheckedKeys 获取选中 key', () => {
+    const { nodeMap, toggleChecked, getCheckedKeys } = useMenu({ data: SAMPLE_DATA });
+
+    toggleChecked(nodeMap.get('user')!, true);
+    toggleChecked(nodeMap.get('about')!, true);
+
+    const keys = getCheckedKeys();
+    expect(keys).toContain('user');
+    expect(keys).toContain('about');
+    expect(keys).toHaveLength(2);
+  });
+
+  it('半选节点不计入 getCheckedKeys', () => {
+    const { nodeMap, getCheckedKeys } = useMenu({ data: SAMPLE_DATA });
+    const node = nodeMap.get('system')!;
+    node.indeterminate = true;
+    node.checked = false;
+
+    expect(getCheckedKeys()).not.toContain('system');
+  });
+
+  it('getNodesByKeys 批量获取节点', () => {
+    const { getNodesByKeys } = useMenu({ data: SAMPLE_DATA });
+    const nodes = getNodesByKeys(['home', 'user']);
+    expect(nodes).toHaveLength(2);
+  });
+
+  it('getNodesByKeys 过滤不存在的 key', () => {
+    const { getNodesByKeys } = useMenu({ data: SAMPLE_DATA });
+    const nodes = getNodesByKeys(['home', 'nonexistent']);
+    expect(nodes).toHaveLength(1);
+  });
+
+  it('checkedKeys 初始化选中', () => {
+    const { nodeMap } = useMenu({ data: SAMPLE_DATA, checkedKeys: ['user', 'about'] });
+    expect(nodeMap.get('user')!.checked).toBe(true);
+    expect(nodeMap.get('about')!.checked).toBe(true);
+    expect(nodeMap.get('home')!.checked).toBe(false);
+  });
+
+  it('initNodes 重新初始化', () => {
+    const { initNodes, nodesRef, nodeMap } = useMenu({ data: SAMPLE_DATA });
+
+    initNodes([{ key: 'new', label: '新节点' }]);
+    expect(nodesRef.value).toHaveLength(1);
+    expect(nodeMap.size).toBe(1);
+    expect(nodeMap.get('new')!.label).toBe('新节点');
+  });
+
+  it('自定义 config 字段映射', () => {
+    const data = [
+      { id: 'a', name: '菜单A', items: [{ id: 'b', name: '子菜单B' }] },
+    ];
+    const { nodeMap } = useMenu({
+      data: data as any,
+      config: { key: 'id', label: 'name', children: 'items' },
+    });
+
+    expect(nodeMap.size).toBe(2);
+    expect(nodeMap.get('a')).toBeDefined();
+    expect(nodeMap.get('b')).toBeDefined();
+  });
+});

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,18 @@
+/**
+ * @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 type { MenuProps, MenuData, MenuNodeData, MenuConfig } from './props';

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

@@ -0,0 +1,93 @@
+/**
+ * @description menu props 类型定义
+ * @author 阿怪
+ * @date 2026/2/25
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+/**
+ * 菜单数据项
+ */
+export interface MenuData {
+  key: string | number;
+  label?: string;
+  value?: string | number;
+  children?: MenuData[];
+  disabled?: boolean;
+  [k: string]: unknown;
+}
+
+/**
+ * 菜单内部节点数据（带状态）
+ */
+export interface MenuNodeData extends MenuData {
+  /** 是否展开 */
+  expand?: boolean;
+  /** 是否激活 */
+  isActive?: boolean;
+  /** 是否选中（checkbox 模式） */
+  checked?: boolean;
+  /** 半选状态 */
+  indeterminate?: boolean;
+  /** 子节点 */
+  children?: MenuNodeData[];
+  /** 父节点引用 */
+  parent?: MenuNodeData | null;
+  /** 是否根节点 */
+  isRoot?: boolean;
+}
+
+/**
+ * 菜单字段映射配置
+ */
+export interface MenuConfig {
+  key: string;
+  label: string;
+  children: string;
+}
+
+export declare type MenuProps = {
+  /**
+   * @description 菜单数据
+   * @type MenuData[]
+   * @default []
+   */
+  data?: MenuData[];
+  /**
+   * @description 字段映射配置
+   * @type MenuConfig
+   * @default { key: 'key', label: 'label', children: 'children' }
+   */
+  config?: MenuConfig;
+  /**
+   * @description 是否使用 checkbox
+   * @type boolean
+   * @default false
+   */
+  checkbox?: boolean;
+  /**
+   * @description 默认展开所有节点
+   * @type boolean
+   * @default false
+   */
+  defaultExpandAll?: boolean;
+  /**
+   * @description 选中的 key 列表
+   * @type Array<string|number>
+   * @default []
+   */
+  checkedKeys?: Array<string | number>;
+  /**
+   * @description 菜单排列方向
+   * @type 'vertical' | 'horizontal'
+   * @default 'vertical'
+   */
+  mode?: 'vertical' | 'horizontal';
+  /**
+   * @description 当前激活的菜单项 key（v-model:active）
+   * @type string | number
+   */
+  active?: string | number;
+};