@melt-js/comps-vben 0.0.0-stage → 2026.11.8-2

package/src/menu-ui/hooks/use-menu.ts

@@ -0,0 +1,48 @@
+import type { SubMenuProvider } from '../types';
+
+import { computed, getCurrentInstance } from 'vue';
+
+import { findComponentUpward } from '../utils';
+
+function useMenu() {
+  const instance = getCurrentInstance();
+  if (!instance) {
+    throw new Error('instance is required');
+  }
+
+  /**
+   * @zh_CN 获取所有父级菜单链路
+   */
+  const parentPaths = computed(() => {
+    let parent = instance.parent;
+    const paths: string[] = [instance.props.path as string];
+    while (parent?.type.name !== 'MenuUI') {
+      if (parent?.props.path) {
+        paths.unshift(parent.props.path as string);
+      }
+      parent = parent?.parent ?? null;
+    }
+
+    return paths;
+  });
+
+  const parentMenu = computed(() => {
+    return findComponentUpward(instance, ['MenuUI', 'SubMenu']);
+  });
+
+  return {
+    parentMenu,
+    parentPaths,
+  };
+}
+
+function useMenuStyle(menu?: SubMenuProvider) {
+  const subMenuStyle = computed(() => {
+    return {
+      '--menu-level': menu ? (menu?.level ?? 0 + 1) : 0,
+    };
+  });
+  return subMenuStyle;
+}
+
+export { useMenu, useMenuStyle };

package/src/menu-ui/index.ts

@@ -0,0 +1,4 @@
+export { default as MenuBadge } from './components/menu-badge.vue';
+export * from './components/normal-menu';
+export { default as Menu } from './menu.vue';
+export type * from './types';

package/src/menu-ui/menu.vue

@@ -0,0 +1,32 @@
+<script setup lang="ts">
+import type { MenuRecordRaw } from '@melt-js/libs-vben/typings';
+
+import type { MenuProps } from './types';
+
+import { useForwardProps } from '@melt-js/libs-vben/composables';
+
+import { Menu } from './components';
+import SubMenu from './sub-menu.vue';
+
+interface Props extends MenuProps {
+  menus: MenuRecordRaw[];
+}
+
+defineOptions({
+  name: 'MenuView',
+});
+
+const props = withDefaults(defineProps<Props>(), {
+  collapse: false,
+});
+
+const forward = useForwardProps(props);
+</script>
+
+<template>
+  <Menu v-bind="forward">
+    <template v-for="menu in menus" :key="menu.path">
+      <SubMenu :menu="menu" />
+    </template>
+  </Menu>
+</template>

package/src/menu-ui/sub-menu.vue

@@ -0,0 +1,71 @@
+<script setup lang="ts">
+import type { MenuRecordRaw } from '@melt-js/libs-vben/typings';
+
+import { computed } from 'vue';
+
+import { MenuBadge, MenuItem, SubMenu as SubMenuComp } from './components';
+import SubMenu from './sub-menu.vue';
+
+interface Props {
+  /**
+   * 菜单项
+   */
+  menu: MenuRecordRaw;
+}
+
+defineOptions({
+  name: 'SubMenuUi',
+});
+
+const props = withDefaults(defineProps<Props>(), {});
+
+/**
+ * 判断是否有子节点，动态渲染 menu-item/sub-menu-item
+ */
+const hasChildren = computed(() => {
+  const { menu } = props;
+  return (
+    Reflect.has(menu, 'children') && !!menu.children && menu.children.length > 0
+  );
+});
+</script>
+
+<template>
+  <MenuItem
+    v-if="!hasChildren"
+    :key="menu.path"
+    :active-icon="menu.activeIcon"
+    :badge="menu.badge"
+    :badge-type="menu.badgeType"
+    :badge-variants="menu.badgeVariants"
+    :icon="menu.icon"
+    :path="menu.path"
+    :query="menu.query"
+  >
+    <template #title>
+      <span>{{ menu.name }}</span>
+    </template>
+  </MenuItem>
+  <SubMenuComp
+    v-else
+    :key="`${menu.path}_sub`"
+    :active-icon="menu.activeIcon"
+    :icon="menu.icon"
+    :path="menu.path"
+  >
+    <template #content>
+      <MenuBadge
+        :badge="menu.badge"
+        :badge-type="menu.badgeType"
+        :badge-variants="menu.badgeVariants"
+        class="right-6"
+      />
+    </template>
+    <template #title>
+      <span>{{ menu.name }}</span>
+    </template>
+    <template v-for="childItem in menu.children || []" :key="childItem.path">
+      <SubMenu :menu="childItem" />
+    </template>
+  </SubMenuComp>
+</template>

package/src/menu-ui/types.ts

@@ -0,0 +1,154 @@
+import type { Component, Ref } from 'vue';
+
+import type {
+  MenuRecordBadgeRaw,
+  Recordable,
+  ThemeModeType,
+} from '@melt-js/libs-vben/typings';
+
+interface MenuProps {
+  /**
+   * @zh_CN 是否开启手风琴模式
+   * @default true
+   */
+  accordion?: boolean;
+  /**
+   * @zh_CN 菜单是否折叠
+   * @default false
+   */
+  collapse?: boolean;
+
+  /**
+   * @zh_CN 菜单折叠时是否显示菜单名称
+   * @default false
+   */
+  collapseShowTitle?: boolean;
+
+  /**
+   * @zh_CN 默认激活的菜单
+   */
+  defaultActive?: string;
+
+  /**
+   * @zh_CN 默认展开的菜单
+   */
+  defaultOpeneds?: string[];
+
+  /**
+   * @zh_CN 菜单模式
+   * @default vertical
+   */
+  mode?: 'horizontal' | 'vertical';
+
+  /**
+   * @zh_CN 是否圆润风格
+   * @default true
+   */
+  rounded?: boolean;
+
+  /**
+   * @zh_CN 是否自动滚动到激活的菜单项
+   * @default false
+   */
+  scrollToActive?: boolean;
+
+  /**
+   * @zh_CN 菜单主题
+   * @default dark
+   */
+  theme?: ThemeModeType;
+}
+
+interface SubMenuProps extends MenuRecordBadgeRaw {
+  /**
+   * @zh_CN 激活图标
+   */
+  activeIcon?: string;
+  /**
+   * @zh_CN 是否禁用
+   */
+  disabled?: boolean;
+  /**
+   * @zh_CN 图标
+   */
+  icon?: Component | string;
+  /**
+   * @zh_CN submenu 名称
+   */
+  path: string;
+}
+
+interface MenuItemProps extends MenuRecordBadgeRaw {
+  /**
+   * @zh_CN 图标
+   */
+  activeIcon?: string;
+  /**
+   * @zh_CN 是否禁用
+   */
+  disabled?: boolean;
+  /**
+   * @zh_CN 图标
+   */
+  icon?: Component | string;
+  /**
+   * @zh_CN menuitem 名称
+   */
+  path: string;
+  /**
+   * @zh_CN 菜单所携带的参数
+   */
+  query?: Recordable<any>;
+}
+
+interface MenuItemRegistered {
+  active: boolean;
+  parentPaths: string[];
+  path: string;
+  query?: Recordable<any>;
+}
+
+interface MenuItemClicked {
+  parentPaths: string[];
+  path: string;
+}
+
+interface MenuProvider {
+  activePath?: string;
+  addMenuItem: (item: MenuItemRegistered) => void;
+
+  addSubMenu: (item: MenuItemRegistered) => void;
+  closeMenu: (path: string, parentLinks: string[]) => void;
+  handleMenuItemClick: (item: MenuItemClicked) => void;
+  handleSubMenuClick: (subMenu: MenuItemRegistered) => void;
+  isMenuPopup: boolean;
+  items: Record<string, MenuItemRegistered>;
+
+  openedMenus: string[];
+  openMenu: (path: string, parentLinks: string[]) => void;
+  props: MenuProps;
+  removeMenuItem: (item: MenuItemRegistered) => void;
+
+  removeSubMenu: (item: MenuItemRegistered) => void;
+
+  subMenus: Record<string, MenuItemRegistered>;
+  theme: string;
+}
+
+interface SubMenuProvider {
+  addSubMenu: (item: MenuItemRegistered) => void;
+  handleMouseleave?: (deepDispatch: boolean) => void;
+  level: number;
+  mouseInChild: Ref<boolean>;
+  removeSubMenu: (item: MenuItemRegistered) => void;
+}
+
+export type {
+  MenuItemClicked,
+  MenuItemProps,
+  MenuItemRegistered,
+  MenuProps,
+  MenuProvider,
+  SubMenuProps,
+  SubMenuProvider,
+};

package/src/menu-ui/utils/index.ts

@@ -0,0 +1,52 @@
+import type {
+  ComponentInternalInstance,
+  VNode,
+  VNodeChild,
+  VNodeNormalizedChildren,
+} from 'vue';
+
+import { isVNode } from 'vue';
+
+type VNodeChildAtom = Exclude<VNodeChild, Array<any>>;
+type RawSlots = Exclude<VNodeNormalizedChildren, Array<any> | null | string>;
+
+type FlattenVNodes = Array<RawSlots | VNodeChildAtom>;
+
+/**
+ * @zh_CN Find the parent component upward
+ * @param instance
+ * @param parentNames
+ */
+function findComponentUpward(
+  instance: ComponentInternalInstance,
+  parentNames: string[],
+) {
+  let parent = instance.parent;
+  while (parent && !parentNames.includes(parent?.type?.name ?? '')) {
+    parent = parent.parent;
+  }
+  return parent;
+}
+
+const flattedChildren = (
+  children: FlattenVNodes | VNode | VNodeNormalizedChildren,
+): FlattenVNodes => {
+  const vNodes = Array.isArray(children) ? children : [children];
+  const result: FlattenVNodes = [];
+
+  vNodes.forEach((child) => {
+    if (Array.isArray(child)) {
+      result.push(...flattedChildren(child));
+    } else if (isVNode(child) && Array.isArray(child.children)) {
+      result.push(...flattedChildren(child.children));
+    } else {
+      result.push(child);
+      if (isVNode(child) && child.component?.subTree) {
+        result.push(...flattedChildren(child.component.subTree));
+      }
+    }
+  });
+  return result;
+};
+
+export { findComponentUpward, flattedChildren };

package/src/plugins/echarts/README.md

@@ -0,0 +1,41 @@
+# ECharts Plugin
+
+ECharts 图表插件，预置常用组件和图表类型。
+
+## 导出
+
+| 导出         | 类型 | 说明         |
+| ------------ | ---- | ------------ |
+| `default`    | 对象 | echarts 实例 |
+| `EchartsUI`  | 组件 | 图表容器组件 |
+| `ECOption`   | 类型 | 图表配置类型 |
+| `useEcharts` | 函数 | 组合式函数   |
+
+## 使用
+
+```ts
+import { EchartsUI, useEcharts, ECOption } from '@vben/plugins/echarts';
+```
+
+## 类型
+
+```ts
+import type { ECOption } from '@vben/plugins/echarts';
+```
+
+## 预置组件
+
+- TitleComponent
+- TooltipComponent
+- GridComponent
+- LegendComponent
+- ToolboxComponent
+- DatasetComponent
+- TransformComponent
+
+## 预置图表
+
+- BarChart
+- LineChart
+- PieChart
+- RadarChart

package/src/plugins/echarts/echarts-ui.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+interface Props {
+  height?: string;
+  width?: string;
+}
+
+withDefaults(defineProps<Props>(), {
+  height: '300px',
+  width: '100%',
+});
+</script>
+
+<template>
+  <div v-bind="$attrs" :style="{ height, width }"></div>
+</template>

package/src/plugins/echarts/echarts.ts

@@ -0,0 +1,40 @@
+import { BarChart, LineChart, PieChart, RadarChart } from 'echarts/charts';
+import {
+  DatasetComponent,
+  GraphicComponent,
+  GridComponent,
+  LegendComponent,
+  TitleComponent,
+  ToolboxComponent,
+  TooltipComponent,
+  TransformComponent,
+} from 'echarts/components';
+import * as echarts from 'echarts/core';
+import {
+  LabelLayout,
+  LegacyGridContainLabel,
+  UniversalTransition,
+} from 'echarts/features';
+import { CanvasRenderer } from 'echarts/renderers';
+
+echarts.use([
+  TitleComponent,
+  PieChart,
+  RadarChart,
+  TooltipComponent,
+  GridComponent,
+  DatasetComponent,
+  TransformComponent,
+  BarChart,
+  LineChart,
+  LabelLayout,
+  LegacyGridContainLabel,
+  UniversalTransition,
+  CanvasRenderer,
+  LegendComponent,
+  ToolboxComponent,
+  GraphicComponent,
+]);
+export type { ECOption } from './types';
+
+export default echarts;

package/src/plugins/echarts/index.ts

@@ -0,0 +1,4 @@
+export * from './echarts';
+export { default as EchartsUI } from './echarts-ui.vue';
+export * from './types';
+export * from './use-echarts';

package/src/plugins/echarts/types.ts

@@ -0,0 +1,28 @@
+import type {
+  BarSeriesOption,
+  LineSeriesOption,
+  PieSeriesOption,
+  RadarSeriesOption,
+} from 'echarts/charts';
+import type {
+  DatasetComponentOption,
+  GridComponentOption,
+  LegendComponentOption,
+  TitleComponentOption,
+  ToolboxComponentOption,
+  TooltipComponentOption,
+} from 'echarts/components';
+import type { ComposeOption } from 'echarts/core';
+
+export type ECOption = ComposeOption<
+  | BarSeriesOption
+  | DatasetComponentOption
+  | GridComponentOption
+  | LegendComponentOption
+  | LineSeriesOption
+  | PieSeriesOption
+  | RadarSeriesOption
+  | TitleComponentOption
+  | ToolboxComponentOption
+  | TooltipComponentOption
+>;

package/src/plugins/echarts/use-echarts.ts

@@ -0,0 +1,213 @@
+import type { EChartsOption } from 'echarts';
+
+import type { ComponentPublicInstance, Ref } from 'vue';
+
+import type { Nullable } from '@melt-js/libs-vben/types';
+
+import {
+  computed,
+  nextTick,
+  onActivated,
+  onBeforeUnmount,
+  onDeactivated,
+  onMounted,
+  ref,
+  unref,
+  watch,
+} from 'vue';
+
+import { usePreferences } from '@melt-js/libs-vben/preferences';
+
+import {
+  tryOnUnmounted,
+  useDebounceFn,
+  useResizeObserver,
+  useTimeoutFn,
+  useWindowSize,
+} from '@vueuse/core';
+
+import echarts from './echarts';
+
+type EchartsUIType = ComponentPublicInstance | undefined;
+
+type EchartsThemeType = 'dark' | 'light' | null;
+
+function useEcharts(chartRef: Ref<EchartsUIType>) {
+  let chartInstance: echarts.ECharts | null = null;
+  let cacheOptions: EChartsOption = {};
+  // echarts是否处于激活状态
+  const isActiveRef = ref(false);
+
+  const { isDark } = usePreferences();
+  const { height, width } = useWindowSize();
+  const resizeHandler: () => void = useDebounceFn(resize, 200);
+
+  const getChartEl = (): HTMLElement | null => {
+    const refValue = chartRef?.value as unknown;
+    if (!refValue) return null;
+    if (refValue instanceof HTMLElement) {
+      return refValue;
+    }
+    const maybeComponent = refValue as { $el?: HTMLElement };
+    return maybeComponent.$el ?? null;
+  };
+
+  onMounted(() => (isActiveRef.value = true));
+  onActivated(() => (isActiveRef.value = true));
+  onDeactivated(() => (isActiveRef.value = false));
+  onBeforeUnmount(() => (isActiveRef.value = false));
+
+  const isElHidden = (el: HTMLElement | null): boolean => {
+    if (!el) return true;
+    return el.offsetHeight === 0 || el.offsetWidth === 0;
+  };
+
+  const getOptions = computed((): EChartsOption => {
+    if (!isDark.value) {
+      return {};
+    }
+
+    return {
+      backgroundColor: 'transparent',
+    };
+  });
+
+  const initCharts = (t?: EchartsThemeType) => {
+    const el = chartRef?.value?.$el;
+    if (!el) {
+      return undefined;
+    }
+    // 求值顺序与上游一致：t || isDark.value 先于三元（即 t='light' 时
+    // 仍会落到 'dark'，为上游既有行为，本工具链 PR 不改动）。
+    chartInstance = echarts.init(el, t || isDark.value ? 'dark' : null);
+
+    return chartInstance;
+  };
+
+  const renderEcharts = (
+    options: EChartsOption,
+    clear = true,
+  ): Promise<Nullable<echarts.ECharts>> => {
+    if (!unref(isActiveRef)) {
+      return Promise.resolve(null);
+    }
+    cacheOptions = options;
+    const currentOptions = {
+      ...options,
+      ...getOptions.value,
+    };
+    return new Promise((resolve) => {
+      if (getChartEl()?.offsetHeight === 0) {
+        useTimeoutFn(async () => {
+          resolve(await renderEcharts(currentOptions));
+        }, 30);
+        return;
+      }
+      void nextTick(() => {
+        const el = getChartEl();
+        if (isElHidden(el)) {
+          useTimeoutFn(async () => {
+            resolve(await renderEcharts(currentOptions));
+          }, 30);
+          return;
+        }
+        useTimeoutFn(() => {
+          if (!chartInstance || chartInstance?.getDom() !== el) {
+            chartInstance?.dispose();
+            const instance = initCharts();
+            // 等待窗口内组件卸载（ref 已空）时拿不到实例：按 Nullable
+            // 语义 resolve(null)，不能裸 return——那会让返回的 Promise
+            // 永久 pending，挂起下游 await renderEcharts/updateData 的
+            // 调用方。
+            if (!instance) {
+              resolve(null);
+              return;
+            }
+            chartInstance = instance;
+          }
+          clear && chartInstance?.clear();
+          chartInstance?.setOption(currentOptions);
+          resolve(chartInstance);
+        }, 30);
+      });
+    });
+  };
+
+  const updateData = (
+    option: EChartsOption,
+    notMerge = false, // false = 合并（保留动画），true = 完全替换
+    lazyUpdate = false, // true 时不立即重绘，适合短时间内多次调用
+  ): Promise<echarts.ECharts | null> => {
+    return new Promise((resolve) => {
+      void nextTick(() => {
+        if (!chartInstance) {
+          // 还没初始化 → 当作首次渲染
+          // renderEcharts 的不变式是只 resolve 不 reject；catch 为防御性
+          // 兜底——不变式被打破时降级为 null，而非产生 unhandled rejection
+          void renderEcharts(option)
+            .then(resolve)
+            .catch(() => resolve(null));
+          return;
+        }
+
+        // 合并你原有的全局配置（比如 backgroundColor）
+        const finalOption = {
+          ...option,
+          ...getOptions.value,
+        };
+
+        chartInstance.setOption(finalOption, {
+          notMerge,
+          lazyUpdate,
+          // silent: true,     // 如果追求极致性能可开启（关闭所有事件）
+        });
+
+        resolve(chartInstance);
+      });
+    });
+  };
+
+  function resize() {
+    const el = getChartEl();
+    if (isElHidden(el)) {
+      return;
+    }
+    chartInstance?.resize({
+      animation: {
+        duration: 300,
+        easing: 'quadraticIn',
+      },
+    });
+  }
+
+  watch([width, height], () => {
+    resizeHandler?.();
+  });
+
+  useResizeObserver(getChartEl, resizeHandler);
+
+  watch([isDark, isActiveRef], () => {
+    if (chartInstance && unref(isActiveRef)) {
+      chartInstance.dispose();
+      initCharts();
+      void renderEcharts(cacheOptions);
+      resize();
+    }
+  });
+
+  tryOnUnmounted(() => {
+    // 销毁实例，释放资源
+    chartInstance?.dispose();
+  });
+  return {
+    isActive: isActiveRef,
+    renderEcharts,
+    resize,
+    updateData,
+    getChartInstance: () => chartInstance,
+  };
+}
+
+export { useEcharts };
+
+export type { EchartsUIType };