@hsu-react/ui 1.0.0 → 2.0.1

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

@@ -0,0 +1,52 @@
+import { array_is_includes } from "hsu-utils";
+
+/**
+ * Check whether a path matches (used by the breadcrumb)
+ * @param pathname Current path
+ * @param itemPath Route path
+ * @param parentPath Parent path
+ * @returns Whether it matches
+ */
+export const checkBreadcrumbPathMatch = (
+  pathname: string,
+  itemPath: string,
+  parentPath?: string
+): boolean => {
+  if (!itemPath) {
+    return pathname === "/" && itemPath === "/";
+  }
+
+  const pathArr = pathname.split("/").filter(Boolean);
+  const keyArr = itemPath.split("/").filter(Boolean);
+
+  if (keyArr.length === 0) {
+    return false;
+  }
+
+  if (pathArr.length !== keyArr.length) {
+    return false;
+  }
+
+  // Handle the root path
+  if (pathname === "/" && itemPath === "/") {
+    return true;
+  }
+
+  // Handle routes containing params (e.g. /user/:id)
+  if (itemPath.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/Breadcrumb/index.md

@@ -0,0 +1,37 @@
+---
+title: Breadcrumb 面包屑
+order: 3
+---
+
+# Breadcrumb 面包屑
+
+从路由配置推导当前位置的层级路径，父级带下拉菜单可直接跳转到同级页面。
+
+## 引入
+
+布局组件走**子路径**引入（原因见 [与路由的关系](/layouts/header#与路由的关系)）：
+
+```ts
+import Layout from "@hsu-react/ui/es/layout";
+
+<Layout.Breadcrumb router={router} />;
+```
+
+## 说明
+
+`router` 传的就是应用的路由配置（`RouteType[]`）。组件会：
+
+- 按当前 `location.pathname` 逐级匹配出路径链
+- 用每级的 `meta.name` 作为文案、`meta.icon` 作为图标
+- 父级若有多个子路由，渲染成下拉菜单，点击直接跳转
+
+面包屑比菜单**宽松**：只要 `meta.menu` 为真、**或者** `meta.noTabsView` 不为真，该层就会出现在路径链里。所以「不进菜单但能访问」的详情页照样有面包屑，只有显式标了 `noTabsView` 且没开 `menu` 的路由才会被跳过（它的子级会顶上来）。
+
+带路径参数的子路由（`path` 里含 `:`）不会进下拉菜单 —— 没有具体参数值，跳过去也没有意义。
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| router | 路由配置 | `RouteType[]` | - |
+| className | 自定义类名 | `string` | - |

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

@@ -0,0 +1,15 @@
+.Breadcrumb {
+  cursor: default;
+
+  // On narrow screens, keep long paths on one line so they do not squeeze the top bar; hide the overflow
+  overflow: hidden;
+
+  :global(ol) {
+    flex-wrap: nowrap;
+    white-space: nowrap;
+  }
+
+  * {
+    color: inherit !important;
+  }
+}

package/src/layout/Breadcrumb/index.tsx

@@ -0,0 +1,103 @@
+import { Breadcrumb as AntBreadcrumb } from "antd";
+import React, { ReactNode, useMemo, useCallback } from "react";
+import { useNavigate } from "react-router";
+
+import { ItemType } from "antd/es/breadcrumb/Breadcrumb";
+import { RouteType } from "../types";
+import styles from "./index.module.scss";
+import { cloneDeep } from "lodash";
+import classNames from "classnames";
+import { formatRoutes } from "./_utils/formatRoutes";
+import { formatBreadcrumbMenu } from "./_utils/formatMenu";
+import { useBreadcrumbPath } from "./_hooks/useBreadcrumbPath";
+import BreadcrumbItemIcon from "./_components/BreadcrumbItemIcon";
+
+// Omit 掉 children：antd v6 把 BreadcrumbItemType.children 收窄成了
+// `Omit<BreadcrumbItemType, "children">[]`，而这里的 children 要能递归携带 parent / route
+// 这些自有字段，直接 extends 会判为不兼容。渲染时再转回 antd 认识的形状。
+export interface BreadcrumbType extends Omit<ItemType, "children"> {
+  children?: BreadcrumbType[];
+  icon?: ReactNode;
+  parent?: RouteType;
+  route?: RouteType;
+  index?: boolean;
+}
+
+export interface BreadcrumbProps {
+  router: RouteType[];
+  className?: string;
+}
+
+/**
+ * Breadcrumb component
+ */
+const Breadcrumb: React.FC<BreadcrumbProps> = (props) => {
+  const { router, className } = props;
+  const navigate = useNavigate();
+
+  const _routes = useMemo(() => {
+    return formatRoutes(router);
+  }, [router]);
+
+  const breadcrumb = useBreadcrumbPath(_routes);
+
+  /**
+   * Handle the breadcrumb item click event
+   */
+  const handleItemClick = useCallback(
+    (path: string) => {
+      navigate(path);
+    },
+    [navigate]
+  );
+
+  /**
+   * Format breadcrumb items
+   */
+  const formattedItems = useMemo(() => {
+    return cloneDeep(breadcrumb)?.map((item, index) => {
+      const isLastItem = index === breadcrumb.length - 1;
+      const children = item.children?.filter((i) => !i.path?.includes(":"));
+      const hasChildren = children && children.length > 0;
+
+      // If there are child menus, set the menu items
+      if (hasChildren) {
+        item.onClick = (e) => e.preventDefault();
+        item.menu = {
+          items: formatBreadcrumbMenu(cloneDeep(children), navigate),
+        };
+      }
+
+      // The last item does not show a path
+      if (isLastItem) {
+        item.path = undefined;
+      }
+
+      // If there is an icon, wrap the title
+      if (item.icon) {
+        item.title = <BreadcrumbItemIcon icon={item.icon} title={item.title} />;
+      }
+
+      // If there is a path and no child menu, set the click handler
+      if (item.path && !hasChildren) {
+        item.onClick = (e) => {
+          e.preventDefault();
+          handleItemClick(item.path as string);
+        };
+      }
+
+      return { ...item };
+    });
+  }, [breadcrumb, navigate, handleItemClick]);
+
+  return (
+    <AntBreadcrumb
+      className={classNames(styles.Breadcrumb, className)}
+      // BreadcrumbType 比 antd 的 ItemType 多带了 parent / route / children 这些自有字段，
+      // 供上面的格式化与点击逻辑使用；渲染时 antd 只读它认识的那几个，多出来的会被忽略。
+      items={formattedItems as ItemType[]}
+    />
+  );
+};
+
+export default Breadcrumb;

package/src/layout/Header/index.md

@@ -0,0 +1,120 @@
+---
+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` 在内层（它只管外观三态与侧栏配色，不重复做全局主题）。
+
+## 类型
+
+组件用到的公开类型都从 `@hsu-react/ui/es/layout` 出，不要深路径引到各组件目录里去：
+
+```ts | pure
+import type {
+  RouteType, MetaType,          // 路由与其附加信息
+  AccountAction, HeaderProps,   // 顶栏
+  MenuType, MenuProps,          // 菜单
+  TabType, NavTabBarProps,      // 页签栏
+  BreadcrumbType, BreadcrumbProps,
+  InternationalizationProps, ThemeProps,
+} from "@hsu-react/ui/es/layout";
+```
+
+## 样式
+
+顶栏的样式是**跟着组件发的**，引入组件即可，不需要在应用里另外准备一份全局 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);
+        }
+      }
+    }
+  }
+}