@hsu-react/ui 1.0.0 → 2.0.0

package/src/layout/I18n/index.tsx

@@ -0,0 +1,44 @@
+import "dayjs/locale/zh-cn";
+
+import React, { ReactNode, useEffect } from "react";
+
+import { ConfigProvider } from "antd";
+import { IntlProvider } from "react-intl";
+import I18nStore from "./I18nStore";
+import { observer } from "mobx-react-lite";
+
+export interface InternationalizationProps {
+  children: ReactNode;
+  /**
+   * 默认语言。仅在本地没有缓存过语言时生效 —— 用户选过一次之后以缓存为准。
+   *
+   * 原实现是从应用的全局 `Config.locale` 兜底的，那是 build 期注入的 ambient 全局，
+   * 组件不该认识它，改由这里传入。
+   */
+  defaultLocale?: string;
+}
+
+const Internationalization: React.FC<InternationalizationProps> = observer(
+  ({ children, defaultLocale }) => {
+    const { messages, locale, antLocale } = I18nStore;
+
+    // 只在「从未选过语言」时应用默认值，不覆盖用户的选择
+    useEffect(() => {
+      if (defaultLocale) I18nStore.applyDefaultLocale(defaultLocale);
+    }, [defaultLocale]);
+
+    useEffect(() => {
+      const html = document.documentElement;
+      html.classList.remove("lang-en-US", "lang-zh-CN");
+      html.classList.add(`lang-${locale}`);
+    }, [locale]);
+
+    return (
+      <IntlProvider locale={locale} messages={messages}>
+        <ConfigProvider locale={antLocale}>{children}</ConfigProvider>
+      </IntlProvider>
+    );
+  }
+);
+
+export default Internationalization;

package/src/layout/I18n/locales/en-US.ts

@@ -0,0 +1,16 @@
+const en_US: Record<string, string> = {
+  "setting.title": "Settings",
+  "setting.navStyle": "Navigation Style",
+  "setting.nav.light": "Light",
+  "setting.nav.dark": "Dark",
+  "setting.nav.theme": "Primary",
+  "setting.primaryColor": "Primary Color",
+  "setting.layout": "Layout",
+  "setting.layout.left": "Side",
+  "setting.layout.top": "Top",
+  "setting.layout.mixed": "Mixed",
+  "setting.language": "Language",
+  "setting.reset": "Reset",
+};
+
+export default en_US;

package/src/layout/I18n/locales/zh-CN.ts

@@ -0,0 +1,16 @@
+const zh_CN: Record<string, string> = {
+  "setting.title": "界面设置",
+  "setting.navStyle": "导航风格",
+  "setting.nav.light": "亮色",
+  "setting.nav.dark": "暗色",
+  "setting.nav.theme": "主题色",
+  "setting.primaryColor": "主题色",
+  "setting.layout": "导航布局",
+  "setting.layout.left": "左侧",
+  "setting.layout.top": "顶部",
+  "setting.layout.mixed": "混合",
+  "setting.language": "语言",
+  "setting.reset": "恢复默认",
+};
+
+export default zh_CN;

package/src/layout/Menu/_components/SecondaryHeader/index.module.scss

@@ -0,0 +1,65 @@
+.SecondaryHeader {
+  // 只管头部自身：整列的 flex 布局与 .ant-menu 的撑满交给 Menu 的 .secondaryWrap
+  flex: none;
+
+  .back {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin: 8px 10px 14px;
+    padding: 7px 10px;
+    cursor: pointer;
+    font-size: 13px;
+    font-weight: 600;
+    background: var(--wa-fill);
+    border: 1px solid var(--vita-border);
+    border-radius: 8px;
+
+    &:hover {
+      background: var(--wa-hover-bg);
+      border-color: var(--vita-primary);
+    }
+  }
+
+  .backText {
+    white-space: nowrap;
+  }
+
+  // 折叠态只剩箭头：图标居中
+  .backCollapsed {
+    justify-content: center;
+    padding-left: 0;
+    padding-right: 0;
+  }
+
+  .title {
+    padding: 2px 16px 10px;
+    font-weight: 600;
+    font-size: 14px;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  // 明暗两套文字色由 --cf-text 一并承担，不再各写一份字面量
+  .back,
+  .title {
+    color: var(--vita-foreground);
+  }
+
+  &.light {
+    border-inline-end: 1px solid var(--vita-border);
+  }
+}
+
+@media (max-width: 768px) {
+  .SecondaryHeader {
+    width: 64px !important;
+    min-width: 64px !important;
+
+    .backText,
+    .title {
+      display: none;
+    }
+  }
+}

package/src/layout/Menu/_components/SecondaryHeader/index.tsx

@@ -0,0 +1,61 @@
+import React, { ReactNode } from "react";
+
+import { ArrowLeftOutlined } from "@ant-design/icons";
+import { useNavigate } from "react-router-dom";
+import classNames from "classnames";
+
+import styles from "./index.module.scss";
+
+export interface SecondaryHeaderProps {
+  collapsed?: boolean;
+  theme?: "light" | "dark";
+  /** 返回入口文案，折叠时只剩箭头 */
+  backText?: string;
+  /** 自定义返回行为；不给就退回浏览器上一页 */
+  onBack?: () => void;
+  /** 当前实体名（详情页的标题），显示在返回入口下方 */
+  title?: string;
+  /** 返回入口与标题之间的额外内容，如详情内检索框 */
+  extra?: ReactNode;
+}
+
+/**
+ * 次级菜单的默认头部：返回入口 ＋ 标题，中间留一个 `extra` 插槽。
+ *
+ * `Menu` 在切到次级菜单时默认渲染它，调用方只需按需给 title/onBack/extra；
+ * 整块要换掉时再传 `secondaryHeader` 覆盖；业务侧的头部通常就是在这上面补一两件
+ * 自己的东西（检索框之类）。
+ */
+const SecondaryHeader: React.FC<SecondaryHeaderProps> = (props) => {
+  const {
+    collapsed = false,
+    theme = "dark",
+    backText = "返回",
+    onBack,
+    title,
+    extra,
+  } = props;
+  const navigate = useNavigate();
+
+  return (
+    <div className={classNames(styles.SecondaryHeader, styles[theme])}>
+      <div
+        className={classNames(styles.back, {
+          [styles.backCollapsed]: collapsed,
+        })}
+        onClick={() => (onBack ? onBack() : navigate(-1))}
+      >
+        <ArrowLeftOutlined />
+        {!collapsed && <span className={styles.backText}>{backText}</span>}
+      </div>
+      {!collapsed && extra}
+      {!collapsed && title && (
+        <div className={styles.title} title={title}>
+          {title}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default SecondaryHeader;

package/src/layout/Menu/_hooks/useMenuPath.ts

@@ -0,0 +1,81 @@
+import { useEffect, useState } from "react";
+import { useLocation } from "react-router";
+import { MenuType } from "..";
+import { checkPathMatch } from "../_utils/pathMatch";
+
+interface UseMenuPathOptions {
+  allItems: MenuType[];
+  collapsed: boolean;
+  mode?: string;
+}
+
+/**
+ * Hook that handles menu path matching and active state
+ */
+export const useMenuPath = ({
+  allItems,
+  collapsed,
+  mode = "inline",
+}: UseMenuPathOptions) => {
+  const location = useLocation();
+  const [menuKey, setMenuKey] = useState("");
+  const [openKeys, setOpenkeys] = useState<string[]>([]);
+
+  useEffect(() => {
+    // 菜单里实际存在的 key，用来判断高亮能不能落上去
+    const knownKeys = new Set<string>();
+    const collect = (items?: MenuType[]) =>
+      items?.forEach((i) => {
+        if (i.key) knownKeys.add(i.key);
+        collect(i.children);
+      });
+    collect(allItems);
+
+    const _checkPath = (items: MenuType[], parents?: MenuType[]) => {
+      const pathname = decodeURI(location.pathname);
+
+      items?.forEach((item) => {
+        if (item.children) {
+          const _parents = parents ? [...parents, item] : [item];
+          _checkPath(item.children, _parents);
+        } else {
+          const isMatch = checkPathMatch(pathname, item.key, item.parent?.path);
+
+          if (isMatch) {
+            // 判断「这一项本身是不是带参详情页」，只能看它**相对父级的那一段**：
+            // 整条 key 里含 ":" 是不够的，父路径带参时（子页的 key 都形如
+            // /admin/xxx/:id/detail）会把普通子页全判成详情页，高亮集体落到容器上。
+            const selfSeg = item.parent?.path
+              ? item.key.slice(item.parent.path.length)
+              : item.key;
+
+            if (selfSeg.includes(":")) {
+              // 详情页自己不在菜单里，高亮回落到它对应的列表页：去掉末尾参数段后
+              // **逐段上退**，直到退到一个菜单里真有的项。只退一段是不够的——
+              // /a/b/detail/:id 退一段是 /a/b/detail，菜单里没有这一项，还要再退一段。
+              let candidate = item.key.replace(/\/:[^/]+$/, "");
+              while (candidate && !knownKeys.has(candidate)) {
+                candidate = candidate.slice(0, candidate.lastIndexOf("/"));
+              }
+              setMenuKey(candidate || item.parent?.path || item.key);
+            } else {
+              setMenuKey(item.key);
+            }
+
+            // Set the expanded menu items
+            if (parents && !collapsed && mode !== "horizontal") {
+              const _openKeys = parents?.map((item) => item.key);
+              setOpenkeys([..._openKeys]);
+            }
+          }
+        }
+      });
+    };
+
+    setMenuKey("");
+    setOpenkeys([]);
+    _checkPath(allItems);
+  }, [allItems, location, collapsed, mode]);
+
+  return { menuKey, setMenuKey, openKeys, setOpenkeys };
+};

package/src/layout/Menu/_hooks/useOnlyLvOneMenu.ts

@@ -0,0 +1,44 @@
+import { useEffect } from "react";
+import { useLocation } from "react-router";
+import { MenuType } from "..";
+
+interface UseOnlyLvOneMenuOptions {
+  items: MenuType[];
+  onlyLvOneMenu: boolean;
+  getCurrChildItems?: (children: MenuType[]) => void;
+  setOpenkeys: (keys: string[]) => void;
+  setMenuKey: (key: string) => void;
+}
+
+/**
+ * Handle the top-level-only menu logic
+ */
+export const useOnlyLvOneMenu = ({
+  items,
+  onlyLvOneMenu,
+  getCurrChildItems,
+  setOpenkeys,
+  setMenuKey,
+}: UseOnlyLvOneMenuOptions) => {
+  const location = useLocation();
+
+  useEffect(() => {
+    if (onlyLvOneMenu) {
+      const item = items.find(
+        (i) => i.key === "/" + location.pathname.split("/").filter(Boolean)[0]
+      );
+      if (item) {
+        getCurrChildItems?.(item.children || []);
+        setOpenkeys([item.key]);
+        setMenuKey(item.key);
+      }
+    }
+  }, [
+    items,
+    getCurrChildItems,
+    location,
+    onlyLvOneMenu,
+    setOpenkeys,
+    setMenuKey,
+  ]);
+};

package/src/layout/Menu/_utils/formatMenu.ts

@@ -0,0 +1,57 @@
+import { cloneDeep } from "lodash";
+import { RouteType } from "../../types";
+import { MenuType } from "..";
+
+/**
+ * Format routes into menu items
+ * @param routes Route config
+ * @param all Whether to include all routes (including those not shown in the menu)
+ * @param parent Parent menu item
+ * @returns Menu item array
+ */
+export const formatMenu = (
+  routes: RouteType[],
+  all: boolean = false,
+  parent?: MenuType
+): MenuType[] => {
+  const newRoutes: MenuType[] = [];
+
+  routes?.forEach((route) => {
+    let children: MenuType[] | undefined = undefined;
+    if (route.children) {
+      children = formatMenu(route.children, all, cloneDeep(route) as MenuType);
+    }
+
+    const { meta } = route;
+
+    if ((!all ? meta?.menu : true) && route.path) {
+      newRoutes.push({
+        key: route.path,
+        title: meta?.name,
+        label: meta?.name,
+        icon: meta?.icon,
+        defaultIcon: meta?.icon,
+        activeIcon: meta?.activeIcon,
+        disabled: meta?.disabled,
+        children: (children?.length || 0) > 0 ? children : undefined,
+        parent: parent,
+      });
+    } else if ((!all ? meta?.menu : true) && route.index && parent?.path) {
+      newRoutes.push({
+        key: parent.path,
+        title: meta?.name,
+        label: meta?.name,
+        icon: meta?.icon,
+        defaultIcon: meta?.icon,
+        activeIcon: meta?.activeIcon,
+        disabled: meta?.disabled,
+      });
+    } else {
+      if (children) {
+        newRoutes.push(...children);
+      }
+    }
+  });
+
+  return newRoutes;
+};

package/src/layout/Menu/_utils/pathMatch.ts

@@ -0,0 +1,48 @@
+import { array_is_includes } from "hsu-utils";
+
+/**
+ * Check whether a path matches
+ * @param pathname Current path
+ * @param key Route key
+ * @param parentPath Parent path
+ * @returns Whether it matches
+ */
+export const checkPathMatch = (
+  pathname: string,
+  key: string,
+  parentPath?: string
+): boolean => {
+  const pathArr = pathname.split("/").filter(Boolean);
+  const keyArr = key.split("/").filter(Boolean);
+
+  if (keyArr.length === 0) {
+    return pathname === "/" && key === "/";
+  }
+
+  if (pathArr.length !== keyArr.length) {
+    return false;
+  }
+
+  // Handle the root path
+  if (pathname === "/" && key === "/") {
+    return true;
+  }
+
+  // Handle routes with params (e.g. /user/:id)
+  if (key.includes(":")) {
+    if (parentPath === "/") {
+      // If the parent path is the root path, check that there are no non-param segments
+      return !keyArr.filter((i: string) => !i.startsWith(":")).length;
+    } else {
+      // Filter out param segments and compare only the non-param parts
+      return array_is_includes(
+        keyArr.filter((i: string) => !i.startsWith(":")),
+        pathArr
+      );
+    }
+  } else {
+    // Plain path matching
+    return array_is_includes(keyArr, pathArr);
+  }
+};
+

package/src/layout/Menu/_utils/setActiveIcon.ts

@@ -0,0 +1,23 @@
+import { MenuType } from "..";
+
+/**
+ * Set the active icon for menu items
+ * @param items Menu item array
+ * @param menuKey Key of the currently active menu
+ */
+export const setActiveIcon = (items: MenuType[], menuKey: string): void => {
+  items?.forEach((item) => {
+    if (item.children) {
+      setActiveIcon(item.children, menuKey);
+    } else {
+      if (item.activeIcon && item.key === menuKey) {
+        item.icon = item.activeIcon;
+      } else {
+        item.icon = item.defaultIcon;
+      }
+    }
+
+    delete item.activeIcon;
+    delete item.defaultIcon;
+  });
+};

package/src/layout/Menu/index.md

@@ -0,0 +1,43 @@
+---
+title: Menu 菜单
+order: 2
+---
+
+# Menu 菜单
+
+从路由配置生成侧边 / 顶部菜单，自带选中态跟随、权限过滤与二级菜单。
+
+## 引入
+
+```ts
+import Layout from "@hsu-react/ui/es/layout";
+
+<Layout.Menu router={router} collapsed={collapsed} />;
+```
+
+## 说明
+
+菜单项由 `RouteType[]` 推导，规则：
+
+- **`meta.menu` 是显式开关**：只有 `meta.menu` 为真的路由才生成菜单项。不写等同于不进菜单 —— 路由本身照常可访问，详情页这类不需要额外标记
+- 文案取 `meta.name`，图标取 `meta.icon`；`meta.activeIcon` 是选中态图标，不传则沿用 `icon`（只对没有子项的菜单项生效）
+- `meta.disabled` 置灰不可点
+- 选中态按当前 `location.pathname` 匹配，深层路由会自动点亮其所属的菜单项
+
+`meta` 上还有 `hasPermi`、`noAuth` 这些字段，**本组件不读**，它们由消费方在生成路由时自行消费（例如按权限先裁剪一遍 `router` 再传进来）。
+
+`meta.secondary` 标记的路由进入**二级菜单**：主菜单只显示到一级，点进去之后左侧换成该模块的次级菜单，顶部可用 `secondaryHeader` 放返回入口、标题或检索框。
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| router | 路由配置 | `RouteType[]` | - |
+| collapsed | 是否收起（只显示图标） | `boolean` | `false` |
+| menuItems | 直接指定菜单项，跳过从 router 推导 | `MenuType[]` | - |
+| onlyLvOneMenu | 只渲染一级菜单（mixed 布局的顶部菜单用） | `boolean` | `false` |
+| getCurrChildItems | 回传当前一级菜单的子项，供外部渲染 | `(children: MenuType[]) => void` | - |
+| secondaryHeader | 次级菜单顶部的自定义区域 | `ReactNode` | - |
+| secondaryItemFilter | 次级菜单项的额外过滤，按 key（绝对路径）判断 | `(key: string) => boolean` | - |
+
+> 其余属性透传给 antd 的 [Menu](https://ant.design/components/menu-cn)。

package/src/layout/Menu/index.module.scss

@@ -0,0 +1,50 @@
+// 注意：CSS Module 里的类名都会被哈希，antd 的类名必须写在 :global() 中，否则
+// `.ant-menu-horizontal` 会变成 `.ant-menu-horizontal___xxxxx`，静悄悄地永不生效。
+.menu {
+  &::-webkit-scrollbar {
+    width: 0px;
+    height: 0px;
+  }
+
+  scrollbar-width: none;
+
+  // 顶部横向菜单：占满剩余宽度，背景交给外层的导航渐变
+  &:global(.ant-menu-horizontal) {
+    flex: 1;
+    min-width: 0px;
+
+    background-color: transparent;
+  }
+}
+
+// 弹出的子菜单挂在 body 上，够不到 .menu，所以由组件把这个类挂到 popup 上
+.popup {
+  &:global(.ant-menu-submenu-popup.ant-menu.ant-menu-dark) {
+    :global(.ant-menu-item),
+    :global(.ant-menu-submenu-title) {
+      color: var(--vita-foreground);
+
+      &:hover {
+        color: var(--vita-primary) !important;
+      }
+
+      &:global(.ant-menu-item-selected) {
+        background-color: color-mix(in srgb, var(--vita-primary) 8%, transparent);
+
+        color: var(--vita-primary) !important;
+      }
+    }
+  }
+}
+
+// 次级菜单：头部固定在上，菜单撑满剩余高度
+.secondaryWrap {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+
+  :global(.ant-menu) {
+    flex: 1;
+    border-inline-end: none !important;
+  }
+}