@hsu-react/ui 1.0.0 → 2.0.0

package/src/layout/Header/index.md

@@ -0,0 +1,105 @@
+---
+title: Header 顶栏
+order: 1
+---
+
+# Header 顶栏
+
+站点标题、面包屑、语言与外观切换、账号菜单。
+
+## 引入
+
+布局组件走**子路径**引入：
+
+```ts
+import Layout from "@hsu-react/ui/es/layout";
+import type { RouteType } from "@hsu-react/ui/es/layout";
+```
+
+## 与路由的关系
+
+`Menu`、`Breadcrumb`、`NavTabBar` 都是**路由驱动**的：它们从一份 `RouteType[]` 里读展示信息，并用 react-router 的 `useLocation` / `useNavigate` 决定当前位置与跳转。因此：
+
+- **`react-router` 与 `react-intl` 是可选 peerDependency** —— 只用 `Button`、`Table` 这些的项目完全不受影响，用到 `Layout.*` 的项目才需要装
+- 正因为可选，布局**不从包根导出**。如果 `import { Button } from "@hsu-react/ui"` 也会连带解析 react-router，没装的项目会直接构建失败，"可选" 就没意义了
+- 组件必须渲染在 `<BrowserRouter>` 之类的 Router 上下文里
+
+`RouteType` 就是 react-router 的 `RouteObject` 加了一个 `meta`，通常你现有的路由配置不用改：
+
+```ts | pure
+export interface MetaType {
+  // 布局组件会读的
+  name?: string;          // 菜单项、面包屑、页签上显示的文案
+  menu?: boolean;         // true 才进菜单；不写 = 可访问但不在菜单里（详情页这类）
+  icon?: ReactNode;
+  activeIcon?: ReactNode; // 选中态图标，不传则沿用 icon
+  disabled?: boolean;
+  affix?: boolean;        // 固定页签，不可关闭
+  noTabsView?: boolean;   // 不进页签栏
+  secondary?: boolean;    // 二级导航
+
+  // 布局组件不读，只是搭车放在同一份配置里，由消费方自己消费
+  title?: string;         // 页面标题，写 document.title 之类
+  noCache?: boolean;      // 不做页面缓存（消费方决定是否包 KeepAlive）
+  noLazy?: boolean;       // 不走懒加载
+  noAuth?: boolean;       // 无需登录（消费方的鉴权守卫用）
+  hasPermi?: string[];    // 权限码（消费方生成路由时过滤）
+}
+
+export type RouteType = { children?: RouteType[]; meta?: MetaType } & RouteObject;
+```
+
+## 典型装配
+
+```tsx | pure
+import { ConfigProvider } from "@hsu-react/ui";
+import Layout from "@hsu-react/ui/es/layout";
+
+<ConfigProvider permissions={perms} request={{ get, post, del, put }}>
+  <Layout.I18n defaultLocale="zh-CN">
+    <Layout.Theme>
+      <BrowserRouter>
+        <Layout.Header
+          router={router}
+          title="控制台"
+          smallTitle="台"
+          user={{ nickname }}
+          collapsed={collapsed}
+          onToggleCollapsed={() => setCollapsed((v) => !v)}
+          onChildItems={setChildItems}
+          menu={accountActions}
+        />
+        <Layout.Menu router={router} collapsed={collapsed} />
+        <Layout.NavTabBar router={router} />
+      </BrowserRouter>
+    </Layout.Theme>
+  </Layout.I18n>
+</ConfigProvider>;
+```
+
+顺序上，`ConfigProvider` 在最外层（它提供令牌与 antd 主题），`Layout.Theme` 在内层（它只管外观三态与侧栏配色，不重复做全局主题）。
+
+## 样式
+
+顶栏的样式是**跟着组件发的**，引入组件即可，不需要在应用里另外准备一份全局 CSS。
+
+它原本写在 starter 的全局 `App.scss` 里（`.header` / `.title` / `.menu` 这类裸类名），搬进库时收成了 CSS Module —— 一是库不该要求消费方自带样式表，二是那些类名太通用，留在全局迟早和应用自己的撞上。
+
+有三样**没有**跟进来，因为它们属于应用外壳而不是这个组件：页面整体的 `#App` / `.body` / `.content` 布局、侧栏 `.ant-layout-sider` 的背景与分隔线、右上角的版本号。
+
+深色导航的渐变两端色读 `--nav-dark-top` / `--nav-dark-bottom`，由 [`Layout.Theme`](/layouts/theme) 的 `navDarkColors` 写入；顶栏单独使用（不套 `Theme`）时走内置兜底值，不会变成透明底。
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| router | 路由配置，用于渲染面包屑与顶部菜单 | `RouteType[]` | - |
+| title | 站点标题 | `ReactNode` | - |
+| smallTitle | 侧栏收起时的短标题；不传回落到 `title` | `ReactNode` | - |
+| user | 当前用户，用于右上角展示 | `{ nickname?: string; avatar?: string }` | - |
+| collapsed | 侧栏是否收起 | `boolean` | - |
+| onToggleCollapsed | 点击收起按钮 | `() => void` | - |
+| onChildItems | mixed 布局下把顶部菜单的子项回传给左侧栏 | `(items: MenuType[]) => void` | - |
+| menu | 账号下拉里的动作项（改密、退出等） | `AccountAction[]` | - |
+
+> `user` 与 `title` 原本分别读应用的鉴权模块与全局 `Config`，移入库时改成了属性 —— 组件不该认识消费方的这两样东西。

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

@@ -0,0 +1,215 @@
+// 顶栏样式。原本写在消费方的全局 App.scss 里（`.header` 这样的裸类名），组件搬进库之后
+// 一起收成 CSS Module —— 否则库里发出去的是一个没有任何样式的顶栏，还会和消费方自己的
+// `.header` / `.menu` / `.title` 撞名。
+//
+// 注意：CSS Module 里的类名都会被哈希，antd 的类名必须写在 :global() 里，否则规则不报错
+// 但永远匹配不到 antd 渲染出的 DOM。
+//
+// 没有搬进来的部分（属于应用，不属于这个组件）：`#App` 外壳、`.body` / `.content` 的布局、
+// 侧栏 `.ant-layout-sider` 的背景与分隔线、以及右上角的 `.app-version` 版本号。
+.header {
+  position: relative;
+  z-index: 11;
+
+  display: flex;
+  align-items: center;
+
+  width: 100%;
+  height: 50px;
+  line-height: 50px;
+  padding: 0px;
+  overflow: hidden;
+
+  // 用细边框而不是投影，跟随明暗切换
+  border-bottom: 1px solid var(--vita-border);
+  box-shadow: none;
+
+  .headerLeft {
+    display: flex;
+    align-items: center;
+
+    flex: 1;
+    min-width: 0px;
+
+    .title {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+
+      width: 230px;
+      min-width: 230px;
+      height: 100%;
+      padding: 0px 20px;
+
+      color: var(--vita-foreground);
+      font-size: 20px;
+      font-weight: bold;
+      white-space: nowrap;
+      word-break: keep-all;
+
+      overflow: hidden;
+
+      transition:
+        width 0.2s,
+        min-width 0.2s;
+
+      // 侧栏收起时标题一起收窄，宽度和收起后的侧栏对齐
+      &.titleCollapsed {
+        width: 80px;
+        min-width: 80px;
+        padding: 0px 10px;
+      }
+
+      // 顶部布局下标题不占固定宽度，按内容撑开
+      &.titleTop {
+        width: max-content;
+        min-width: max-content;
+      }
+    }
+
+    .collapsed {
+      width: max-content;
+      height: 100%;
+      padding: 0px 10px;
+
+      font-size: 16px;
+    }
+
+    .breadcrumb {
+      padding: 0px 10px;
+    }
+  }
+
+  .headerRight {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    column-gap: 12px;
+
+    min-width: max-content;
+    height: 100%;
+
+    font-size: 16px;
+
+    .user {
+      width: max-content;
+      min-width: max-content;
+      height: 36px;
+      padding: 0 12px;
+      margin-right: 8px;
+
+      white-space: nowrap;
+      word-break: keep-all;
+      color: var(--vita-foreground);
+
+      border-radius: 8px;
+      cursor: pointer;
+
+      transition:
+        background-color 0.3s,
+        color 0.3s;
+
+      &:hover {
+        background-color: var(--vita-hover);
+      }
+    }
+  }
+
+  // 深色 / 主题色导航的覆盖放在最后，并且每条都比上面的结构规则多一个类 ——
+  // 权重打平时后写的赢，靠顺序太脆，这里让它无论顺序都稳赢。
+  &.dark,
+  &.theme {
+    color: #fff;
+
+    border-bottom-color: rgb(255 255 255 / 10%);
+
+    .headerLeft .title,
+    .headerLeft .collapsed,
+    .headerLeft .breadcrumb {
+      color: #fff;
+    }
+
+    .headerRight .user {
+      color: #ffffffd9;
+
+      &:hover {
+        background-color: #ffffff26;
+        color: #ffffff;
+      }
+    }
+  }
+
+  // 只有深色导航铺中性黑渐变。两端颜色由 Layout.Theme 的 navDarkColors 给，但顶栏也允许
+  // 脱离 Theme 单独用，所以这里带上兜底值 —— 否则变量取不到，整条 gradient 会被判为无效，
+  // 深色导航直接变成透明底。
+  &.dark {
+    background: linear-gradient(
+      90deg,
+      var(--nav-dark-top, #1f1f1f) 0%,
+      var(--nav-dark-bottom, #141414) 100%
+    );
+  }
+}
+
+// 账号下拉。挂在 body 上，够不到 .header，所以是一条独立的顶层规则
+.userPopover {
+  // antd v6 里承载内边距的是 .ant-popover-container，v5 的 .ant-popover-inner 已经没有了 ——
+  // 照着 v5 写不会报错，只是这条规则永远不生效
+  :global(.ant-popover-container) {
+    padding: 8px;
+  }
+
+  :global(.ant-btn):hover {
+    color: var(--vita-primary) !important;
+    background-color: transparent !important;
+  }
+
+  .userMenuPanel {
+    min-width: 230px;
+
+    .settingRow {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      column-gap: 12px;
+
+      padding: 6px 8px;
+
+      .settingLabel {
+        color: var(--vita-muted-foreground);
+        font-size: 13px;
+        white-space: nowrap;
+      }
+    }
+
+    .settingDivider {
+      height: 1px;
+      margin: 6px 0;
+
+      background: var(--vita-border);
+    }
+
+    .menu {
+      display: flex;
+      flex-direction: column;
+
+      :global(.ant-btn) {
+        justify-content: flex-start;
+
+        width: 100%;
+
+        // 图标贴左、文字贴右：图标容器右侧留白撑满，把文字推到右端，和上面设置项
+        // 右侧的控件对齐。每一项都这样，不是只有「退出登录」
+        :global(.ant-btn-icon) {
+          margin-right: auto;
+        }
+
+        // 退出登录这类危险动作，用红色悬浮态区分
+        &.menuBtnDanger:hover {
+          background: color-mix(in srgb, var(--vita-error) 14%, transparent);
+          color: var(--vita-error);
+        }
+      }
+    }
+  }
+}

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;
+}
+
+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()`。