@hsu-react/ui 1.0.0 → 2.0.1

package/src/layout/Header/index.tsx

@@ -0,0 +1,198 @@
+import React from "react";
+
+// Only components hsu-ui does not provide fall back to antd; Button comes from hsu-ui
+import { Avatar, Layout, Popover, Segmented, Space } from "antd";
+import {
+  MenuFoldOutlined,
+  MenuUnfoldOutlined,
+  UserOutlined,
+} from "@ant-design/icons";
+import Button from "../../components/Button";
+import Icon from "../../components/Icon";
+import classNames from "classnames";
+
+import styles from "./index.module.scss";
+
+import { observer } from "mobx-react-lite";
+
+import Breadcrumb from "../Breadcrumb";
+import Menu, { MenuType } from "../Menu";
+import ThemeStore from "../Theme/ThemeStore";
+import I18nStore from "../I18n/I18nStore";
+// 用户信息由 App 传进来。这里原本是 `import { getUserInfo } from "@/utils/auth"` ——
+// 那是消费方自己的鉴权模块，组件不该认识它。改成 props 之后本组件只关心「显示什么名字」。
+
+/**
+ * 账号动作（改密 / 退出）由 App 传进来，本组件只认这个形状、不认来源。
+ *
+ * 别把 `PwdChange` 或 `LoginStore` 搬进来——看着它们该跟用户菜单待在一起，
+ * 但会同时踩两条：
+ *   1. `layout/` 反向 import `@/pages/…`（共享层依赖页面私有目录）；
+ *   2. `PwdChange` 用 `FormItem`，而 `FormItem` 静态引入全部字段渲染器
+ *      （wangeditor / codemirror / pdfjs / xlsx）。它现在由 App 以 `lazy()`
+ *      ＋「打开才挂载」持有，搬进来很容易顺手写成静态 import，那些库就又钉回首屏了。
+ */
+export interface AccountAction {
+  title: string;
+  icon: string;
+  onclick: () => void;
+  /** 危险动作（退出登录之类），悬浮态用红色区分 */
+  danger?: boolean;
+}
+
+export interface HeaderProps {
+  router: Parameters<typeof Breadcrumb>[0]["router"];
+  collapsed: boolean;
+  onToggleCollapsed: () => void;
+  /** mixed 布局下把顶部菜单的子项回传给左侧栏 */
+  onChildItems: (items: MenuType[]) => void;
+  menu: AccountAction[];
+  /** 当前用户，用于右上角展示。不传则不显示用户名 */
+  user?: { nickname?: string; avatar?: string };
+  /** 站点标题。原本读的是应用的全局 Config，组件不该认识那个 */
+  title?: React.ReactNode;
+  /** 侧栏收起时用的短标题；不传则回落到 title */
+  smallTitle?: React.ReactNode;
+}
+
+const Header: React.FC<HeaderProps> = observer((props) => {
+  const {
+    router,
+    collapsed,
+    onToggleCollapsed,
+    onChildItems,
+    menu,
+    user,
+    title,
+    smallTitle,
+  } = props;
+  const { layout, headerTheme, appearance, setAppearance } = ThemeStore;
+  const { locale, setLocale } = I18nStore;
+
+  // Appearance + language are grouped into the user dropdown; bilingual labels follow the current language
+  const isEn = locale === "en-US";
+  const appearanceOptions = [
+    { label: isEn ? "Light" : "浅色", value: "light" },
+    { label: isEn ? "Dark" : "深色", value: "dark" },
+    { label: isEn ? "System" : "跟随", value: "system" },
+  ];
+  const languageOptions = [
+    { label: "中文", value: "zh-CN" },
+    { label: "English", value: "en-US" },
+  ];
+
+  // Nav (header/sidebar) light/dark: light -> light, dark/theme-colored -> dark
+  const navTheme: "light" | "dark" = headerTheme === "light" ? "light" : "dark";
+
+  const nickname = user?.nickname;
+
+  return (
+    <Layout.Header className={classNames(styles.header, styles[headerTheme])}>
+      <div className={styles.headerLeft}>
+        {/* Title */}
+        {["left", "mixed"].includes(layout) ? (
+          <div
+            className={classNames(styles.title, {
+              [styles.titleCollapsed]: collapsed,
+            })}
+          >
+            {collapsed ? smallTitle ?? title : title}
+          </div>
+        ) : (
+          <div className={classNames(styles.title, styles.titleTop)}>
+            {title}
+          </div>
+        )}
+
+        {/* Collapse button */}
+        {["left", "mixed"].includes(layout) && (
+          <Button
+            className={styles.collapsed}
+            type="text"
+            icon={collapsed ? <MenuUnfoldOutlined /> : <MenuFoldOutlined />}
+            onClick={onToggleCollapsed}
+          />
+        )}
+
+        {/* Breadcrumb */}
+        {["left"].includes(layout) && (
+          <Breadcrumb router={router} className={styles.breadcrumb} />
+        )}
+
+        {/* Top menu */}
+        {["top", "mixed"].includes(layout) && (
+          <Menu
+            router={router}
+            mode="horizontal"
+            theme={navTheme}
+            onlyLvOneMenu={layout === "mixed"}
+            getCurrChildItems={onChildItems}
+          />
+        )}
+      </div>
+      <div className={styles.headerRight}>
+        {/* User info (appearance + language + account actions, all grouped in this dropdown) */}
+        <Popover
+          classNames={{ root: styles.userPopover }}
+          placement="bottomRight"
+          content={
+            <div className={styles.userMenuPanel}>
+              <div className={styles.settingRow}>
+                <span className={styles.settingLabel}>
+                  {isEn ? "Appearance" : "外观"}
+                </span>
+                <Segmented
+                  size="small"
+                  value={appearance}
+                  options={appearanceOptions}
+                  onChange={(v) => setAppearance(v as typeof appearance)}
+                />
+              </div>
+              <div className={styles.settingRow}>
+                <span className={styles.settingLabel}>
+                  {isEn ? "Language" : "语言"}
+                </span>
+                <Segmented
+                  size="small"
+                  value={locale}
+                  options={languageOptions}
+                  onChange={(v) => setLocale(v as string)}
+                />
+              </div>
+
+              <div className={styles.settingDivider} />
+
+              <div className={styles.menu}>
+                {menu?.map((item, index) => (
+                  <Button
+                    key={index}
+                    className={classNames({
+                      [styles.menuBtnDanger]: item.danger,
+                    })}
+                    icon={<Icon icon={item.icon} />}
+                    onClick={item.onclick}
+                    type="text"
+                  >
+                    {item.title}
+                  </Button>
+                ))}
+              </div>
+            </div>
+          }
+        >
+          <Space className={styles.user}>
+            <Avatar
+              style={{ backgroundColor: "#1677ff", verticalAlign: "middle" }}
+              icon={nickname ? undefined : <UserOutlined />}
+            >
+              {nickname?.[0]?.toUpperCase()}
+            </Avatar>
+            {nickname}
+          </Space>
+        </Popover>
+      </div>
+    </Layout.Header>
+  );
+});
+
+export default Header;

package/src/layout/I18n/I18nStore.ts

@@ -0,0 +1,98 @@
+import { IntlFormatters, createIntl, createIntlCache } from "react-intl";
+
+import { Locale } from "antd/lib/locale";
+import enUS from "antd/locale/en_US";
+import en_US from "./locales/en-US";
+import { makeAutoObservable } from "mobx";
+import zhCN from "antd/locale/zh_CN";
+import zh_CN from "./locales/zh-CN";
+import { readStorage, writeStorage, STORAGE_KEY } from "../_utils/storage";
+
+type MessagesType = Record<string, string>;
+
+type FormatMessage = IntlFormatters["formatMessage"];
+
+export interface LocaleOption {
+  label: string;
+  value: string;
+}
+export const LocaleOptions: LocaleOption[] = [
+  { label: "中文简体", value: "zh-CN" },
+  { label: "English", value: "en-US" },
+];
+
+class I18n {
+  get locale() {
+    return this._locale;
+  }
+  private _locale: string = "zh-CN";
+
+  get messages() {
+    return this._messages;
+  }
+  private _messages: MessagesType = zh_CN;
+
+  get antLocale() {
+    return this._antLocale;
+  }
+  private _antLocale: Locale = zhCN;
+
+  // 显式标注返回类型。不标的话 TS 会把它推断成 react-intl 内部依赖里的类型，
+  // 生成的 d.ts 就会带上 `react-intl/node_modules/intl-messageformat` 这种路径 ——
+  // 在消费方那边（依赖扁平化后位置不同）解析不到。发包才会暴露的问题。
+  get formatMessage(): FormatMessage {
+    return this._formatMessage;
+  }
+  private _formatMessage!: FormatMessage;
+
+  constructor() {
+    makeAutoObservable(this);
+    // 原本兜底读的是应用的全局 Config.locale。那是消费方 build 期注入的 ambient 全局，
+    // 组件不该认识它 —— 默认语言改由 <Layout.I18n defaultLocale> 传入。
+    this.setLocale(readStorage(STORAGE_KEY.LANG) || "zh-CN");
+  }
+
+  /**
+   * 应用默认语言：只在本地从未缓存过语言时生效，不覆盖用户已经做过的选择。
+   * 由 `<Layout.I18n defaultLocale>` 调用。
+   */
+  public applyDefaultLocale = (locale: string) => {
+    if (!readStorage(STORAGE_KEY.LANG)) this.setLocale(locale);
+  };
+
+  public setLocale = (locale: string = "zh-CN") => {
+    this._locale = locale;
+
+    writeStorage(STORAGE_KEY.LANG, locale);
+
+    switch (locale) {
+      case "en-US":
+        this._antLocale = enUS;
+        this._messages = en_US;
+        break;
+      default:
+        this._antLocale = zhCN;
+        this._messages = zh_CN;
+        break;
+    }
+
+    this._setFormatMessage();
+  };
+
+  private _setFormatMessage = () => {
+    const cache = createIntlCache();
+
+    const intl = createIntl(
+      {
+        locale: this._locale,
+        messages: this._messages,
+      },
+      cache
+    );
+
+    this._formatMessage = intl.formatMessage;
+  };
+}
+
+const I18nStore = new I18n();
+export default I18nStore;

package/src/layout/I18n/index.md

@@ -0,0 +1,45 @@
+---
+title: I18n 国际化
+order: 6
+---
+
+# I18n 国际化
+
+react-intl 的 `IntlProvider` 与 antd `locale` 的组合，内置中英两套。
+
+## 引入
+
+```ts
+import Layout from "@hsu-react/ui/es/layout";
+
+<Layout.I18n defaultLocale="zh-CN">{children}</Layout.I18n>;
+```
+
+## 说明
+
+组件做三件事：
+
+1. 提供 `IntlProvider`，业务里可以照常用 `useIntl()` / `<FormattedMessage />`
+2. 同步 antd 的 `locale`（日期选择器、分页、空态这些的内建文案）与 dayjs 的语言
+3. 在 `html` 上打 `lang-zh-CN` / `lang-en-US` 类名，供需要按语言微调排版的样式使用
+
+语言持久化在 `localStorage["hsu-ui:lang"]`。`defaultLocale` **只在从未选过语言时生效** —— 用户手动切过之后以缓存为准，不会被默认值覆盖回去。
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| children | 子节点 | `ReactNode` | - |
+| defaultLocale | 默认语言，仅在无缓存时生效 | `string` | `"zh-CN"` |
+
+## I18nStore
+
+```ts | pure
+import Layout from "@hsu-react/ui/es/layout";
+
+Layout.I18nStore.locale;                    // "zh-CN" | "en-US"
+Layout.I18nStore.setLocale("en-US");        // 切换语言，并写入 localStorage
+Layout.I18nStore.formatMessage({ id: "x" }); // 在 React 组件之外取文案
+```
+
+`formatMessage` 是为了在 store / 工具函数这类拿不到 hook 的地方取文案而暴露的；组件内部仍然优先用 `useIntl()`。

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,
+  ]);
+};