@hsu-react/ui 0.0.25 → 2.0.0

package/src/layout/NavTabBar/index.tsx

@@ -0,0 +1,236 @@
+import { Tabs as AntdTabs, Tooltip } from "antd";
+import React, { ReactNode, useCallback, useMemo, useState } from "react";
+import { useNavigate } from "react-router";
+import type { DragEndEvent, DragStartEvent } from "@dnd-kit/core";
+import {
+  closestCenter,
+  DndContext,
+  PointerSensor,
+  useSensor,
+} from "@dnd-kit/core";
+import {
+  restrictToHorizontalAxis,
+  restrictToParentElement,
+} from "@dnd-kit/modifiers";
+import {
+  arrayMove,
+  horizontalListSortingStrategy,
+  SortableContext,
+} from "@dnd-kit/sortable";
+
+import { RouteType } from "../types";
+import styles from "./index.module.scss";
+import { useAliveController } from "react-activation";
+import useReload from "../_hooks/useReload";
+import { formatNavTabBar } from "./_utils/formatNavTabBar";
+import { useTabPath } from "./_hooks/useTabPath";
+import { useTabContextMenu } from "./_hooks/useTabContextMenu";
+import { useDropTabKey } from "./_hooks/useDropTabKey";
+import { useTabTitle } from "./_hooks/useTabTitle";
+import TabLabel from "./_components/TabLabel";
+import DraggableTabNode from "./_components/SortableTab";
+import TabDragOverlay from "./_components/TabDragOverlay";
+import { isLegacyHasSelectorBrowser } from "../../utils/cssSupports";
+import Button from "../../components/Button";
+import Icon from "../../components/Icon";
+
+export interface TabType {
+  label: ReactNode;
+  key: string;
+  element?: React.ReactNode;
+  children?: TabType[];
+  path?: string;
+  name?: ReactNode;
+  affix?: boolean;
+  icon?: ReactNode;
+}
+
+export interface NavTabBarProps {
+  router: RouteType[];
+  affixRouter?: string[];
+  basePath?: string;
+  /** 页签栏最前面的「刷新当前页」按钮 */
+  showReload?: boolean;
+}
+
+const NavTabBar: React.FC<NavTabBarProps> = (props) => {
+  const {
+    router,
+    affixRouter = [],
+    basePath = "/",
+    showReload = true,
+  } = props;
+  const navigate = useNavigate();
+  const { drop, refresh } = useAliveController();
+  const onReload = useReload();
+  const legacyHasSelector = isLegacyHasSelectorBrowser();
+
+  const items = useMemo(() => {
+    return formatNavTabBar(router);
+  }, [router]);
+
+  const { tabKey, openKeys, setOpenkeys } = useTabPath({
+    items,
+    affixRouter,
+  });
+
+  const { open, setOpen } = useTabContextMenu();
+
+  useDropTabKey(setOpenkeys);
+  useTabTitle(setOpenkeys);
+
+  // ID of the tab currently being dragged
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  // Configure the drag sensor with a 10px activation distance to avoid accidental drags
+  const sensor = useSensor(PointerSensor, {
+    activationConstraint: { distance: 10 },
+  });
+
+  // Handle the drag start event
+  const onDragStart = (event: DragStartEvent) => {
+    setActiveId(String(event.active.id));
+  };
+
+  // Handle the drag end event
+  const onDragEnd = ({ active, over }: DragEndEvent) => {
+    if (active.id !== over?.id) {
+      setOpenkeys((prev) => {
+        const activeIndex = prev.findIndex((i) => i.key === active.id);
+        const overIndex = prev.findIndex((i) => i.key === over?.id);
+        return arrayMove(prev, activeIndex, overIndex);
+      });
+    }
+    setActiveId(null);
+  };
+
+  // Handle the drag cancel event
+  const onDragCancel = () => {
+    setActiveId(null);
+  };
+
+  /**
+   * 刷新当前页。走的是和右键菜单「重新加载」完全相同的两步：`onReload` 通知页面自己重挂，
+   * `refresh` 让 react-activation 丢掉这份缓存。少调其中任何一个，都会出现「看上去刷新了、
+   * 实际还是那棵旧组件树」。
+   *
+   * key 要去掉 query —— 缓存是按路径存的，带上 `?a=1` 会找不到对应的那份。
+   */
+  const reloadCurrent = useCallback(() => {
+    const key = tabKey?.split("?")[0];
+    if (!key) return;
+    onReload(key);
+    refresh(key);
+  }, [tabKey, onReload, refresh]);
+
+  return (
+    <AntdTabs
+      className={styles.NavTabBar}
+      items={openKeys?.map((item, idx) => {
+        const closable = !(affixRouter.includes(item.key) || item.affix);
+
+        return {
+          label: (
+            <TabLabel
+              item={item}
+              index={idx}
+              openKeys={openKeys}
+              basePath={basePath}
+              affixRouter={affixRouter}
+              open={open}
+              onReload={onReload}
+              refresh={refresh}
+              drop={drop}
+              setOpenkeys={setOpenkeys}
+              setOpen={setOpen}
+              navigate={navigate}
+              className={
+                legacyHasSelector && closable
+                  ? styles.legacyClosableTabLabel
+                  : undefined
+              }
+            />
+          ),
+          key: item.key,
+          closeIcon: closable ? undefined : false,
+        };
+      })}
+      activeKey={tabKey}
+      tabBarExtraContent={
+        showReload
+          ? {
+              left: (
+                // 不用 Button 的 title —— 本库的 Button 把 title 当作 children 的兜底
+                // （children ?? title），传了会把文案画到按钮里，而不是变成悬浮提示
+                <Tooltip title="刷新当前页">
+                  <Button
+                    className={styles.reload}
+                    type="text"
+                    size="small"
+                    aria-label="刷新当前页"
+                    icon={<Icon icon="ep:refresh" />}
+                    onClick={reloadCurrent}
+                  />
+                </Tooltip>
+              ),
+            }
+          : undefined
+      }
+      hideAdd
+      type="editable-card"
+      onEdit={(key, action) => {
+        if (action === "remove") {
+          drop((key as string)?.split("?")[0] || "");
+          // Find the index of the tab being closed
+          const currentIndex = openKeys.findIndex((item) => item.key === key);
+          const newOpenKeys = openKeys.filter((item) => item.key !== key);
+          setOpenkeys(newOpenKeys);
+          setOpen("");
+          if (key === tabKey) {
+            // If the active tab is closed, select the previous tab; fall back to the first one
+            const targetIndex = currentIndex > 0 ? currentIndex - 1 : 0;
+            navigate(newOpenKeys[targetIndex]?.key || basePath);
+          }
+        }
+      }}
+      size="small"
+      renderTabBar={(tabBarProps, DefaultTabBar) => (
+        <DndContext
+          sensors={[sensor]}
+          onDragStart={onDragStart}
+          onDragEnd={onDragEnd}
+          onDragCancel={onDragCancel}
+          collisionDetection={closestCenter}
+          modifiers={[restrictToHorizontalAxis, restrictToParentElement]}
+        >
+          <SortableContext
+            items={openKeys.map((i) => i.key)}
+            strategy={horizontalListSortingStrategy}
+          >
+            <DefaultTabBar {...tabBarProps}>
+              {(node) => (
+                <DraggableTabNode {...node.props} key={node.key}>
+                  {node}
+                </DraggableTabNode>
+              )}
+            </DefaultTabBar>
+          </SortableContext>
+          <TabDragOverlay
+            activeId={activeId}
+            openKeys={openKeys}
+            basePath={basePath}
+            affixRouter={affixRouter}
+            open={open}
+            onReload={onReload}
+            refresh={refresh}
+            drop={drop}
+            setOpenkeys={setOpenkeys}
+            setOpen={setOpen}
+            navigate={navigate}
+          />
+        </DndContext>
+      )}
+    />
+  );
+};
+export default NavTabBar;

package/src/layout/Theme/ThemeStore.ts

@@ -0,0 +1,70 @@
+import { readStorage, writeStorage, STORAGE_KEY } from "../_utils/storage";
+import { makeAutoObservable } from "mobx";
+
+export type Layout = "left" | "top" | "mixed";
+
+export type Theme = "light" | "dark";
+
+export type HeaderTheme = "light" | "dark" | "theme";
+
+// Three appearance modes (light / dark / follow system)
+export type Appearance = "light" | "dark" | "system";
+
+class ThemeStore {
+  // Appearance mode selected by the user
+  get appearance() {
+    return this._appearance;
+  }
+  private _appearance: Appearance = "system";
+
+  // Whether the system is currently dark (takes effect when appearance=system)
+  private _systemDark = false;
+
+  // Resolved actual dark-mode state
+  get isDark(): boolean {
+    if (this._appearance === "system") return this._systemDark;
+    return this._appearance === "dark";
+  }
+
+  // Fixed left layout; switching is no longer offered
+  get layout(): Layout {
+    return "left";
+  }
+
+  // Nav light/dark follows the appearance
+  get headerTheme(): HeaderTheme {
+    return this.isDark ? "dark" : "light";
+  }
+
+  // Content theme follows the appearance
+  get theme(): Theme {
+    return this.isDark ? "dark" : "light";
+  }
+
+  constructor() {
+    makeAutoObservable(this);
+
+    const cached = readStorage(STORAGE_KEY.APPEARANCE) as Appearance | undefined;
+    if (cached === "light" || cached === "dark" || cached === "system") {
+      this._appearance = cached;
+    }
+
+    // Listen for system color-scheme changes, following in real time when appearance=system
+    if (typeof window !== "undefined" && window.matchMedia) {
+      const mq = window.matchMedia("(prefers-color-scheme: dark)");
+      this._systemDark = mq.matches;
+      mq.addEventListener("change", (e) => this._setSystemDark(e.matches));
+    }
+  }
+
+  private _setSystemDark = (v: boolean) => {
+    this._systemDark = v;
+  };
+
+  public setAppearance = (appearance: Appearance) => {
+    this._appearance = appearance;
+    writeStorage(STORAGE_KEY.APPEARANCE, appearance);
+  };
+}
+
+export default new ThemeStore();

package/src/layout/Theme/index.md

@@ -0,0 +1,48 @@
+---
+title: Theme 外观
+order: 5
+---
+
+# Theme 外观
+
+外观三态（浅色 / 深色 / 跟随系统）与导航区专属配色。
+
+## 引入
+
+```ts
+import Layout from "@hsu-react/ui/es/layout";
+
+<Layout.Theme>{children}</Layout.Theme>;
+```
+
+## 与 ConfigProvider 的分工
+
+这两个组件**不是二选一，也不重复**：
+
+- [`ConfigProvider`](/components/config-provider) 提供**全局主题** —— 色板、圆角、字号、控件高度、明暗算法、focus ring，全部从设计令牌产出
+- `Layout.Theme` 只做两件它独有的事：
+  1. 写 `html[data-theme]`。令牌的 CSS 变量与 `useIsDark` 都监听这个属性，但没有别的地方写它 —— 外观三态就落在这儿
+  2. 叠加导航区配色。菜单选中态的胶囊、深色侧栏的渐变，这些是布局特有的，通用令牌覆盖不到。选中态的颜色取**当前生效的主色**（antd `useToken` 读到的 `colorPrimary`），所以在 `ConfigProvider` 上换 `primaryColor`，菜单会跟着换
+
+所以顺序是 `ConfigProvider` 在外、`Layout.Theme` 在内（antd 的嵌套主题规则是内层胜）。
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| children | 子节点 | `ReactNode` | - |
+| navDarkColors | 深色导航渐变的两端色 | `{ top: string; bottom: string }` | `{ top: "#1f1f1f", bottom: "#141414" }` |
+
+## ThemeStore
+
+外观状态是一个 mobx store，应用侧可直接读写（`Layout.Header` 的外观切换器用的就是它）：
+
+```ts | pure
+import Layout from "@hsu-react/ui/es/layout";
+
+Layout.ThemeStore.appearance;              // "light" | "dark" | "system"
+Layout.ThemeStore.isDark;                  // 解析 system 之后的实际明暗
+Layout.ThemeStore.setAppearance("dark");   // 切换，并写入 localStorage
+```
+
+`appearance` 持久化在 `localStorage["hsu-ui:appearance"]`；选了 `system` 时会跟随 `prefers-color-scheme` 实时变化。

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

@@ -0,0 +1,6 @@
+.theme {
+  width: 100vw;
+  height: 100vh;
+
+  overflow: hidden;
+}

package/src/layout/Theme/index.tsx

@@ -0,0 +1,105 @@
+import React, { useEffect, useMemo } from "react";
+import { ConfigProvider as AntdConfigProvider, theme as antdTheme } from "antd";
+import { observer } from "mobx-react-lite";
+import classNames from "classnames";
+
+import styles from "./index.module.scss";
+import ThemeStore from "./ThemeStore";
+import { lightTokens, darkTokens, withAlpha } from "../../styles/tokens";
+
+export interface ThemeProps {
+  children?: React.ReactNode;
+  /** 深色导航渐变的两端色，不传用内置值 */
+  navDarkColors?: { top: string; bottom: string };
+}
+
+/**
+ * 外观控制器 + 布局专属配色。
+ *
+ * 这里刻意**不**做全局主题 —— 色板、圆角、字号、控件高度、明暗算法、focus ring 都由本库的
+ * `ConfigProvider` 从设计令牌统一产出。这个组件只负责两件它独有的事：
+ *
+ * 1. **写 `html[data-theme]`**。令牌的 CSS 变量与 `useIsDark` 都监听这个属性，但**没有人写它** ——
+ *    这是外观三态（light / dark / 跟随系统）落地的地方，也是这个组件存在的主要理由。
+ * 2. **侧栏与导航的配色**。菜单选中态的胶囊、深色导航的渐变，这些是布局特有的，
+ *    通用令牌覆盖不到，用一层就近的 antd ConfigProvider 叠加（antd 的嵌套规则：内层胜）。
+ *
+ * 移植时去掉的（本库已有，留着会重复甚至打架）：
+ * - 自己包一层 antd ConfigProvider 做全局主题、切 darkAlgorithm  -> ConfigProvider
+ * - hexToRgba                                                   -> styles/tokens 的 withAlpha
+ * - 自存一份主题色（原来固定是青色）                                -> antd useToken 里当前生效的 colorPrimary
+ * - matchMedia 监听系统深色                                       -> useIsDark
+ * - borderRadius / colorBorder / Table / Card / Button / Input 等成套 token 覆盖 -> toAntdTheme
+ * - 在包裹元素上内联重定义 --cf-*：那会盖掉 tokens.scss 生成的值，属于主动帮倒忙
+ */
+const Theme: React.FC<ThemeProps> = observer((props) => {
+  const { children, navDarkColors } = props;
+  const { isDark } = ThemeStore;
+
+  const t = isDark ? darkTokens : lightTokens;
+
+  // 主色取**当前生效**的那个，而不是自己再存一份 —— 消费方在 ConfigProvider 上换了
+  // primaryColor，导航的选中态要跟着换，否则菜单会是一个和全站无关的颜色。
+  const { token } = antdTheme.useToken();
+  const primaryColor = token.colorPrimary;
+
+  // 写 data-theme：CSS 变量与 useIsDark 都看它。
+  useEffect(() => {
+    document.documentElement.dataset.theme = isDark ? "dark" : "light";
+  }, [isDark]);
+
+  const themeConfig = useMemo(
+    () => ({
+      components: {
+        Layout: {
+          headerBg: t.surface,
+          siderBg: t.surface,
+        },
+        Menu: {
+          // 背景透明，好让导航的渐变透出来；选中态是一颗圆角胶囊
+          darkItemBg: "transparent",
+          darkSubMenuItemBg: "transparent",
+          darkPopupBg: t.surface,
+          darkItemColor: "rgba(255, 255, 255, 0.82)",
+          darkItemHoverColor: "#ffffff",
+          darkItemHoverBg: "rgba(255, 255, 255, 0.14)",
+          darkItemSelectedBg: withAlpha(primaryColor, 0.16),
+          darkItemSelectedColor: primaryColor,
+          itemSelectedBg: withAlpha(primaryColor, 0.12),
+          itemSelectedColor: primaryColor,
+          itemActiveBg: withAlpha(primaryColor, 0.12),
+          itemHoverBg: isDark
+            ? "rgba(255, 255, 255, 0.06)"
+            : "rgba(0, 0, 0, 0.04)",
+          itemColor: t.foreground,
+          itemBorderRadius: 6,
+          itemMarginInline: 8,
+          itemMarginBlock: 2,
+          itemHeight: 38,
+          horizontalItemHoverBg: "#0000000a",
+        },
+      },
+    }),
+    [isDark, primaryColor, t]
+  );
+
+  return (
+    <AntdConfigProvider theme={themeConfig}>
+      <div
+        className={classNames(styles.theme, isDark ? "dark" : "light")}
+        style={
+          {
+            "--nav-dark-top": navDarkColors?.top ?? "#1f1f1f",
+            "--nav-dark-bottom": navDarkColors?.bottom ?? "#141414",
+          } as React.CSSProperties
+        }
+      >
+        {children}
+      </div>
+    </AntdConfigProvider>
+  );
+});
+
+Theme.displayName = "Theme";
+
+export default Theme;

package/src/layout/_hooks/useDropTab.ts

@@ -0,0 +1,23 @@
+import { createContext, useContext, useCallback } from "react";
+
+export const NavTabBarContent = createContext<{
+  dropKey?: string;
+  setDropKey?: (key: string) => void;
+}>({});
+
+export default function useDropTab() {
+  const { setDropKey } = useContext(NavTabBarContent);
+
+  const drop = useCallback(
+    (key: string) => {
+      setDropKey?.(key);
+
+      setTimeout(() => {
+        setDropKey?.("");
+      }, 0);
+    },
+    [setDropKey]
+  );
+
+  return drop;
+}

package/src/layout/_hooks/useReload.ts

@@ -0,0 +1,19 @@
+import { createContext, useCallback, useContext } from "react";
+
+export const ReloadContent = createContext<{
+  id?: string;
+  setId?: (id: string) => void;
+}>({});
+
+export default function useReload() {
+  const { setId: setReLoadId } = useContext(ReloadContent);
+
+  const onReload = useCallback(
+    (id: string) => {
+      setReLoadId?.(id);
+    },
+    [setReLoadId]
+  );
+
+  return onReload;
+}

package/src/layout/_hooks/useSetTabTitle.ts

@@ -0,0 +1,19 @@
+import { createContext, useContext, useCallback } from "react";
+
+export const NavTabBarTitleContent = createContext<{
+  tabTitles?: Record<string, React.ReactNode>;
+  setTabTitle?: (key: string, title: React.ReactNode) => void;
+}>({});
+
+export default function useSetTabTitle() {
+  const { setTabTitle: _setTabTitle } = useContext(NavTabBarTitleContent);
+
+  const setTabTitle = useCallback(
+    (key: string, title: React.ReactNode) => {
+      _setTabTitle?.(key, title);
+    },
+    [_setTabTitle]
+  );
+
+  return setTabTitle;
+}

package/src/layout/_utils/storage.ts

@@ -0,0 +1,34 @@
+/**
+ * 布局层用到的一点点本地持久化：外观模式与语言，各是一个字符串。
+ *
+ * 消费方原本用的是一个 web-storage-cache 封装 + 一张全局 CACHE_KEY 表。那张表属于应用，
+ * 不该跟着组件进库；而这里的需求只有「读一个字符串 / 写一个字符串」，直接用 localStorage
+ * 就够了，也不必为此多一个运行时依赖。
+ *
+ * key 统一加 `hsu-ui:` 前缀，避免和消费方自己的存储撞名。
+ */
+const PREFIX = "hsu-ui:";
+
+export const readStorage = (key: string): string | undefined => {
+  if (typeof window === "undefined") return undefined;
+  try {
+    return window.localStorage.getItem(PREFIX + key) ?? undefined;
+  } catch {
+    // 隐私模式 / 禁用存储时 localStorage 会抛异常，静默降级为「没有缓存」
+    return undefined;
+  }
+};
+
+export const writeStorage = (key: string, value: string): void => {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(PREFIX + key, value);
+  } catch {
+    // 同上：写不进去不该让界面崩掉
+  }
+};
+
+export const STORAGE_KEY = {
+  APPEARANCE: "appearance",
+  LANG: "lang",
+} as const;

package/src/layout/index.ts

@@ -0,0 +1,66 @@
+/**
+ * 中后台布局组件。
+ *
+ * 这几个组件是路由驱动的：菜单、面包屑、页签都从一份 `RouteType[]` 里读展示信息，并用
+ * react-router 的 `useLocation` / `useNavigate` 决定当前位置与跳转。因此 **`react-router`
+ * 与 `react-intl` 是可选 peerDependency** —— 只用 Button、Table 这些的项目完全不受影响，
+ * 用到 `Layout.*` 的项目才需要装。
+ *
+ * 与本库其余部分的分工：主题、色板、圆角这些由 `ConfigProvider` 统一提供，`Layout.Theme`
+ * 只负责外观三态（light / dark / 跟随系统）与侧栏导航的专属配色。
+ */
+import Breadcrumb from "./Breadcrumb";
+import Header from "./Header";
+import I18n from "./I18n";
+import Menu from "./Menu";
+import NavTabBar from "./NavTabBar";
+import Theme from "./Theme";
+
+import I18nStore from "./I18n/I18nStore";
+import ThemeStore from "./Theme/ThemeStore";
+
+export type { RouteType, MetaType } from "./types";
+export type { ThemeProps } from "./Theme";
+
+export { default as useSetTabTitle, NavTabBarTitleContent } from "./_hooks/useSetTabTitle";
+export { default as useReload, ReloadContent } from "./_hooks/useReload";
+export { default as useDropTab, NavTabBarContent } from "./_hooks/useDropTab";
+
+/**
+ * 显式标注这个命名空间的类型，而不是让 TS 去推断。
+ *
+ * 推断会把两类东西泄进 d.ts：mobx store 的私有字段（TS4094），以及各组件的 Props 类型 ——
+ * 那些没有被导出，消费方那边无法解析（TS4023）。react-intl 的内部依赖同理（TS2742）。
+ * 这些都只在开了 declaration 的发包构建里才会暴露，本地跑 dev 看不出来。
+ */
+interface LayoutNamespace {
+  Header: typeof Header;
+  Menu: typeof Menu;
+  Breadcrumb: typeof Breadcrumb;
+  NavTabBar: typeof NavTabBar;
+  Theme: typeof Theme;
+  I18n: typeof I18n;
+  ThemeStore: typeof ThemeStore;
+  I18nStore: typeof I18nStore;
+}
+
+const Layout: LayoutNamespace = {
+  /** 顶栏：标题、面包屑、语言与外观切换、账号菜单 */
+  Header,
+  /** 侧边 / 顶部菜单 */
+  Menu,
+  /** 面包屑 */
+  Breadcrumb,
+  /** 多页签栏（可拖拽排序、右键菜单） */
+  NavTabBar,
+  /** 外观三态与布局配色 */
+  Theme,
+  /** react-intl provider + antd locale */
+  I18n,
+  /** 外观状态（mobx），供应用侧读写 appearance */
+  ThemeStore,
+  /** 语言状态（mobx），供应用侧读写 locale */
+  I18nStore,
+};
+
+export default Layout;

package/src/layout/types.ts

@@ -0,0 +1,58 @@
+import type { ReactNode } from "react";
+import type { RouteObject } from "react-router";
+
+/**
+ * 路由的附加信息。菜单、面包屑、页签这三个组件都从这里取展示所需的一切 ——
+ * 它们不认识业务，只认识这个形状。
+ *
+ * 字段分两类，下面用分组标出：**布局组件真正会读的**，以及**只是搭车放在这里、由消费方
+ * 自己消费的**。后者原样保留是因为它们本来就写在同一份路由配置里（鉴权守卫、KeepAlive
+ * 包装、懒加载装配各取所需），把它们从类型里删掉只会逼消费方再声明一次。
+ */
+export interface MetaType {
+  // —— 布局组件会读的 ——
+
+  /** 菜单项 / 面包屑 / 页签上显示的文案 */
+  name?: string;
+  /**
+   * 是否作为菜单项展示。注意是**显式开启**：只有为 `true` 的路由才会进 Menu，
+   * 不写等同于不进菜单（但路由本身照常可访问）。
+   */
+  menu?: boolean;
+  icon?: ReactNode;
+  /** 选中态图标；不传则沿用 `icon`。只对没有子项的菜单项生效 */
+  activeIcon?: ReactNode;
+  /** 菜单项置灰不可点 */
+  disabled?: boolean;
+  /** 固定页签，不可关闭，也不会被「关闭其他 / 关闭右侧」清掉 */
+  affix?: boolean;
+  /** 不进入页签栏 */
+  noTabsView?: boolean;
+  /** 二级导航：该路由的子级换到次级菜单里展示（配合 Menu 的 secondaryHeader） */
+  secondary?: boolean;
+
+  // —— 布局组件不读，留给消费方 ——
+
+  /** 页面标题，供消费方写 document.title 等用途 */
+  title?: string;
+  /** 不做页面缓存，供消费方决定是否用 react-activation 的 KeepAlive 包裹 */
+  noCache?: boolean;
+  /** 不走懒加载，供消费方装配路由时判断 */
+  noLazy?: boolean;
+  /** 无需登录即可访问，供消费方的鉴权守卫判断 */
+  noAuth?: boolean;
+  /** 权限码，供消费方在生成路由时用 usePermissions / ConfigProvider.permissions 过滤 */
+  hasPermi?: string[];
+}
+
+/**
+ * 路由配置。在 react-router 的 `RouteObject` 上加了 `meta`。
+ *
+ * 这个类型原本定义在消费方的 `@/router/router.config` 里，布局组件反过来 import 它 ——
+ * 那样组件就绑死在某个具体应用上了。收进库里之后，消费方改为让自己的路由配置符合这个
+ * 形状（`RouteObject` 本来就是 react-router 的标准类型，通常不用改任何东西）。
+ */
+export type RouteType = {
+  children?: RouteType[];
+  meta?: MetaType;
+} & RouteObject;