@hsu-react/ui 0.0.25 → 2.0.0

package/src/layout/NavTabBar/_hooks/useTabPath.ts

@@ -0,0 +1,118 @@
+import { useCallback, useEffect, useState } from "react";
+import { useLocation } from "react-router";
+import { TabType } from "..";
+import { checkTabPathMatch } from "../_utils/pathMatch";
+import { array_is_includes } from "hsu-utils";
+
+interface UseTabPathOptions {
+  items: TabType[];
+  affixRouter: string[];
+}
+
+/**
+ * Hook that handles tab path matching and active state
+ */
+export const useTabPath = ({ items, affixRouter }: UseTabPathOptions) => {
+  const location = useLocation();
+  const [tabKey, setTabKey] = useState<string>("");
+  const [openKeys, setOpenkeys] = useState<TabType[]>([]);
+
+  /**
+   * Check affixed routes (affixRouter and affix) and add them to openKeys
+   */
+  const _checkAffix = useCallback(
+    (items: TabType[]) => {
+      items?.forEach((item) => {
+        if (item.children) {
+          _checkAffix(item.children);
+        } else {
+          // Check whether it is an affixed route
+          const isAffix = affixRouter.includes(item.key) || item.affix;
+          if (isAffix) {
+            setOpenkeys((prev) => {
+              const find = prev.find((i) => i.key === item.key);
+              if (find) {
+                return prev;
+              }
+              return [...prev, item];
+            });
+          }
+        }
+      });
+    },
+    [affixRouter]
+  );
+
+  const _checkPath = useCallback(
+    (items: TabType[], parents?: TabType[]) => {
+      const pathname = decodeURI(location.pathname);
+      const search = location.search;
+
+      items?.forEach((item) => {
+        if (item.children) {
+          const _parents = parents ? [...parents, item] : [item];
+          _checkPath(item.children, _parents);
+        } else {
+          const isMatch = checkTabPathMatch(pathname, item.key);
+
+          if (isMatch) {
+            const keyArr = item.key.split("/").filter(Boolean);
+            const hasParams =
+              keyArr.filter((i) => i.startsWith(":")).length > 0;
+            const pathArr = pathname.split("/").filter(Boolean);
+
+            if (
+              hasParams &&
+              array_is_includes(
+                keyArr.filter((i) => !i.startsWith(":")),
+                pathArr
+              )
+            ) {
+              // Handle param routes
+              setTabKey(`${pathname}${search}`);
+
+              setOpenkeys((prev) => {
+                const find = prev.find((i) => i.key.split("?")[0] === pathname);
+                if (find) {
+                  return prev.map((i) =>
+                    i.key.split("?")[0] === pathname
+                      ? { ...i, key: `${pathname}${search}` }
+                      : i
+                  );
+                }
+
+                return [...prev, { ...item, key: `${pathname}${search}` }];
+              });
+            } else {
+              // Handle plain routes
+              setTabKey(`${item.key}${search}`);
+
+              setOpenkeys((prev) => {
+                const find = prev.find((i) => i.key.split("?")[0] === item.key);
+                if (find) {
+                  return prev.map((i) =>
+                    i.key.split("?")[0] === item.key
+                      ? { ...i, key: `${item.key}${search}` }
+                      : i
+                  );
+                }
+
+                return [...prev, { ...item, key: `${item.key}${search}` }];
+              });
+            }
+          }
+        }
+      });
+    },
+    [location.pathname, location.search]
+  );
+
+  useEffect(() => {
+    // Handle affixed routes first to populate openKeys
+    _checkAffix(items);
+    // Then run path matching
+    _checkPath(items);
+  }, [_checkAffix, _checkPath, items]);
+
+  return { tabKey, setTabKey, openKeys, setOpenkeys };
+};

package/src/layout/NavTabBar/_hooks/useTabTitle.ts

@@ -0,0 +1,28 @@
+import { useEffect, useContext } from "react";
+import { NavTabBarTitleContent } from "../../_hooks/useSetTabTitle";
+import { TabType } from "..";
+
+/**
+ * Hook that updates tab titles via tabTitles
+ */
+export const useTabTitle = (
+  setOpenkeys: React.Dispatch<React.SetStateAction<TabType[]>>
+) => {
+  const { tabTitles } = useContext(NavTabBarTitleContent);
+
+  useEffect(() => {
+    if (tabTitles && Object.keys(tabTitles).length > 0) {
+      setOpenkeys((prev) => {
+        return prev?.map((item) => {
+          if (tabTitles[item.key] !== undefined) {
+            return {
+              ...item,
+              label: tabTitles[item.key],
+            };
+          }
+          return item;
+        });
+      });
+    }
+  }, [tabTitles, setOpenkeys]);
+};

package/src/layout/NavTabBar/_utils/formatNavTabBar.ts

@@ -0,0 +1,50 @@
+import { cloneDeep } from "lodash";
+import { RouteType } from "../../types";
+import { TabType } from "..";
+
+/**
+ * Format routes into tab items
+ * @param routes Route configuration
+ * @param parent Parent tab item
+ * @returns Array of tab items
+ */
+export const formatNavTabBar = (
+  routes: RouteType[],
+  parent?: TabType
+): TabType[] => {
+  const newRoutes: TabType[] = [];
+
+  routes?.forEach((route) => {
+    let children: TabType[] | undefined = undefined;
+    if (route.children) {
+      children = formatNavTabBar(route.children, cloneDeep(route) as TabType);
+    }
+
+    const { meta } = route;
+
+    if (!meta?.noTabsView && route.path) {
+      newRoutes.push({
+        key: decodeURI(route.path),
+        label: meta?.name ?? "",
+        children: (children?.length || 0) > 0 ? children : undefined,
+        element: route.element,
+        affix: meta?.affix,
+        icon: meta?.icon,
+      });
+    } else if (!meta?.noTabsView && route.index && parent?.path) {
+      newRoutes.push({
+        key: decodeURI(parent.path),
+        label: meta?.name ?? "",
+        element: route.element,
+        affix: meta?.affix,
+        icon: meta?.icon,
+      });
+    } else {
+      if (children) {
+        newRoutes.push(...children);
+      }
+    }
+  });
+
+  return newRoutes;
+};

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

@@ -0,0 +1,37 @@
+import { array_is_includes } from "hsu-utils";
+
+/**
+ * Check whether a path matches (used by tabs)
+ * Note: matching of affixed routes (affixRouter and affix) is handled separately in _checkAffix of useTabPath
+ * @param pathname Current path
+ * @param key Route key
+ * @returns Whether it matches
+ */
+export const checkTabPathMatch = (pathname: string, key: string): boolean => {
+  // Handle the root path
+  if (pathname === "/" && key === "/") {
+    return true;
+  }
+
+  const pathArr = pathname.split("/").filter(Boolean);
+  const keyArr = key.split("/").filter(Boolean);
+
+  if (keyArr.length === 0) {
+    return false;
+  }
+
+  if (pathArr.length !== keyArr.length) {
+    return false;
+  }
+
+  // Handle routes containing params (e.g. /user/:id)
+  if (key.includes(":")) {
+    return array_is_includes(
+      keyArr.filter((i) => !i.startsWith(":")),
+      pathArr
+    );
+  } else {
+    // Plain path matching
+    return array_is_includes(keyArr, pathArr);
+  }
+};

package/src/layout/NavTabBar/_utils/tabActions.ts

@@ -0,0 +1,131 @@
+import { TabType } from "..";
+
+/**
+ * Close the tab at the given index (keeping pinned tabs)
+ */
+export const closeTab = (
+  openKeys: TabType[],
+  index: number,
+  drop: (key: string) => void,
+  affixRouter: string[] = []
+): TabType[] => {
+  const targetItem = openKeys[index];
+  // Do not close if it is a pinned tab
+  if (affixRouter.includes(targetItem.key) || targetItem.affix) {
+    return openKeys;
+  }
+
+  const newOpenKeys = [...openKeys];
+  const removed = newOpenKeys.splice(index, 1);
+  removed?.forEach((item) => {
+    drop(item.key?.split("?")[0] || "");
+  });
+  return newOpenKeys;
+};
+
+/**
+ * Close tabs to the left (keeping pinned tabs)
+ */
+export const closeLeftTabs = (
+  openKeys: TabType[],
+  index: number,
+  drop: (key: string) => void,
+  affixRouter: string[] = []
+): TabType[] => {
+  // Split off the tabs on the left
+  const leftTabs = openKeys.slice(0, index);
+  const rightTabs = openKeys.slice(index);
+
+  // Filter out the non-pinned tabs on the left and close them
+  const removedTabs = leftTabs.filter(
+    (item) => !affixRouter.includes(item.key) && !item.affix
+  );
+  removedTabs.forEach((item) => {
+    drop(item.key?.split("?")[0] || "");
+  });
+
+  // Keep the pinned tabs on the left and all tabs on the right
+  const keptLeftTabs = leftTabs.filter(
+    (item) => affixRouter.includes(item.key) || item.affix
+  );
+  return [...keptLeftTabs, ...rightTabs];
+};
+
+/**
+ * Close tabs to the right (keeping pinned tabs)
+ */
+export const closeRightTabs = (
+  openKeys: TabType[],
+  index: number,
+  drop: (key: string) => void,
+  affixRouter: string[] = []
+): TabType[] => {
+  // Split into left and right tabs
+  const leftTabs = openKeys.slice(0, index + 1);
+  const rightTabs = openKeys.slice(index + 1);
+
+  // Filter out the non-pinned tabs on the right and close them
+  const removedTabs = rightTabs.filter(
+    (item) => !affixRouter.includes(item.key) && !item.affix
+  );
+  removedTabs.forEach((item) => {
+    drop(item.key?.split("?")[0] || "");
+  });
+
+  // Keep all tabs on the left and the pinned tabs on the right
+  const keptRightTabs = rightTabs.filter(
+    (item) => affixRouter.includes(item.key) || item.affix
+  );
+  return [...leftTabs, ...keptRightTabs];
+};
+
+/**
+ * Close other tabs (keeping pinned tabs)
+ */
+export const closeOtherTabs = (
+  openKeys: TabType[],
+  currentItem: TabType,
+  drop: (key: string) => void,
+  affixRouter: string[] = []
+): TabType[] => {
+  // Filter out the other non-pinned tabs and close them
+  const removedTabs = openKeys.filter(
+    (item) =>
+      item.key !== currentItem.key &&
+      !affixRouter.includes(item.key) &&
+      !item.affix
+  );
+  removedTabs.forEach((item) => {
+    drop(item.key?.split("?")[0] || "");
+  });
+
+  // Keep the current tab and all pinned tabs
+  return openKeys.filter(
+    (item) =>
+      item.key === currentItem.key ||
+      affixRouter.includes(item.key) ||
+      item.affix
+  );
+};
+
+/**
+ * Close all tabs (keeping pinned tabs)
+ */
+export const closeAllTabs = (
+  openKeys: TabType[],
+  drop: (key: string) => void,
+  affixRouter: string[] = []
+): TabType[] => {
+  // Filter out the non-pinned tabs and close them
+  const removedTabs = openKeys.filter(
+    (item) => !affixRouter.includes(item.key) && !item.affix
+  );
+  removedTabs.forEach((item) => {
+    drop(item.key?.split("?")[0] || "");
+  });
+
+  // Return the pinned tabs
+  return openKeys.filter(
+    (item) => affixRouter.includes(item.key) || item.affix
+  );
+};

package/src/layout/NavTabBar/index.md

@@ -0,0 +1,76 @@
+---
+title: NavTabBar 页签栏
+order: 4
+---
+
+# NavTabBar 页签栏
+
+多页签导航：可拖拽排序、右键菜单（关闭其他 / 关闭右侧 / 刷新）、固定页签、页面缓存。
+
+## 引入
+
+```ts
+import Layout from "@hsu-react/ui/es/layout";
+
+<Layout.NavTabBar router={router} />;
+```
+
+## 用法
+
+页签栏最前面是「刷新当前页」按钮，右键页签可以关闭 / 批量关闭 / 重新加载，页签之间可以拖拽排序。
+
+```tsx | pure
+import React from "react";
+import { BrowserRouter } from "react-router-dom";
+import { AliveScope } from "react-activation";
+import Layout from "@hsu-react/ui/es/layout";
+
+const router = [
+  { path: "/home", meta: { name: "首页", menu: true, affix: true } },
+  { path: "/order", meta: { name: "订单管理", menu: true } },
+  { path: "/user", meta: { name: "用户列表", menu: true } },
+];
+
+export default () => (
+  <AliveScope>
+    <BrowserRouter>
+      <Layout.NavTabBar router={router} />
+    </BrowserRouter>
+  </AliveScope>
+);
+```
+
+> 「首页」标了 `meta.affix`，所以没有关闭按钮。
+>
+> 这里只给代码不给可运行示例：页签栏要接管地址栏，而文档站本身也跑在一个 react-router 里，
+> 嵌一层 Router 会直接报错（react-router 不允许嵌套），不嵌又会让示例真的把文档站导走。
+
+## 说明
+
+页签由访问过的路由累积而来，文案取 `meta.name`、图标取 `meta.icon`。两个开关直接影响这里：
+
+- `meta.noTabsView` —— 该路由不进页签栏（它的子路由会顶上来）
+- `meta.affix` —— 固定页签，不显示关闭按钮，也不会被「关闭其他 / 关闭右侧」清掉
+
+页签的关闭与刷新走 [react-activation](https://github.com/CJY0208/react-activation) 的 `useAliveController`，因此消费方需要把路由出口包在 `<AliveScope>` 里、页面组件包 `<KeepAlive>`，关闭 / 刷新才能真正丢弃并重建对应的组件树。要让某个页面不缓存，在消费方装配路由时按 `meta.noCache` 跳过 `KeepAlive` 即可 —— 这个字段本组件不读。
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| router | 路由配置 | `RouteType[]` | - |
+| affixRouter | 额外固定的路由路径（等价于给这些路由加 `meta.affix`） | `string[]` | `[]` |
+| basePath | 关掉最后一个页签后回退到的路径 | `string` | `"/"` |
+| showReload | 页签栏最前面的「刷新当前页」按钮 | `boolean` | `true` |
+
+## 配套 Hook
+
+页签的标题与生命周期需要页面内部参与时，用这三个 hook（都从 `@hsu-react/ui/es/layout` 具名导出）：
+
+| Hook | 用途 |
+| --- | --- |
+| `useSetTabTitle()` | 返回 `(key, title) => void`。详情页想把页签标题改成「订单 #123」这类动态文案时用它 |
+| `useReload()` | 返回 `(id) => void`。触发某个页面重新挂载，右键菜单的「刷新」走的就是它 |
+| `useDropTab()` | 返回 `(key) => void`。业务里主动关掉某个页签，例如表单提交成功后关闭自己并跳回列表 |
+
+三者都依赖 `NavTabBar` 挂载时提供的 context，因此只能在页签体系内部的页面里调用。

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

@@ -0,0 +1,179 @@
+// 注意：这是 CSS Module，文件里的每个类名都会被哈希。antd 的类名必须写在 :global() 里，
+// 否则 `.ant-tabs-nav` 会被编译成一串哈希，永远匹配不到 antd 渲染出的 DOM —— 规则不会报错，
+// 只是静悄悄地全部失效。本库其余组件的样式都遵循这个写法。
+.NavTabBar {
+  padding: 6px 8px 0px;
+
+  // Modern look: keep the white strip; the active tab is a light teal pill
+  background: var(--vita-surface);
+
+  border-bottom: 1px solid var(--vita-border);
+
+  // 把根类重复一次（编译成 `.x.x`），只为提一档权重。antd 的卡片样式是
+  // `:where(...).ant-tabs-card.ant-tabs-small.ant-tabs-top > .ant-tabs-nav .ant-tabs-tab`，
+  // `:where()` 不计权重，正好和这里的四个类打平 —— 打平时后注入的赢，而 antd 的
+  // CSS-in-JS 是运行时插进 <head> 的，永远在后面，圆角这类就会被它盖回卡片样式。
+  &.NavTabBar {
+    :global(.ant-tabs-nav) {
+      height: 36px;
+      margin-bottom: 0px;
+
+      &::before {
+        border-bottom: none;
+      }
+
+      // Card-style tabs do not need the bottom ink bar
+      :global(.ant-tabs-ink-bar) {
+        display: none;
+      }
+
+      :global(.ant-tabs-nav-list) {
+        :global(.ant-tabs-tab) {
+          position: relative;
+
+          padding: 0px;
+          margin: 0px;
+
+          border: none;
+          border-radius: 8px;
+          background: transparent;
+
+          transition: background 0.2s;
+
+          & + :global(.ant-tabs-tab) {
+            margin-left: 4px;
+          }
+
+          :global(.ant-tabs-tab-btn) {
+            color: var(--vita-muted-foreground);
+
+            > .tabLabel {
+              display: inline-flex;
+              align-items: center;
+              justify-content: center;
+              column-gap: 5px;
+
+              width: 100%;
+              height: 100%;
+              padding: 6px 16px;
+            }
+
+            > .tabLabel.legacyClosableTabLabel {
+              padding-right: 36px;
+            }
+          }
+
+          &:hover {
+            background: var(--vita-border-weak);
+          }
+
+          &:global(.ant-tabs-tab-active) {
+            background: var(--vita-muted);
+
+            :global(.ant-tabs-tab-btn) {
+              color: var(--vita-primary);
+              font-weight: 500;
+            }
+          }
+
+          :global(.ant-tabs-tab-remove) {
+            position: absolute;
+            right: 16px;
+            top: 50%;
+            transform: translateY(-50%);
+          }
+
+          &:has(:global(.ant-tabs-tab-remove)) {
+            :global(.ant-tabs-tab-btn) {
+              > .tabLabel {
+                padding-right: 36px;
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // extra 区域自身没有高度，撑满后才能和页签对齐；右边那条竖线把刷新按钮和页签分开
+    :global(.ant-tabs-extra-content) {
+      display: flex;
+      align-items: center;
+      align-self: stretch;
+
+      margin-right: 8px;
+      padding-right: 8px;
+
+      border-right: 1px solid var(--vita-border-weak);
+    }
+
+    // 「刷新当前页」按钮
+    .reload {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+
+      width: 28px;
+      height: 28px;
+      padding: 0px;
+
+      color: var(--vita-muted-foreground);
+
+      &:hover {
+        color: var(--vita-primary);
+      }
+    }
+
+    :global(.ant-tabs-nav-operations) {
+      > button {
+        cursor: pointer;
+      }
+    }
+  }
+}
+
+.popover {
+  // antd v6 里承载内边距的是 .ant-popover-container，v5 的 .ant-popover-inner 已经没有了 ——
+  // 照着 v5 写不会报错，只是这条规则永远不生效，右键菜单会白白多出一圈 12px 内边距
+  :global(.ant-popover-container) {
+    padding: 0px;
+  }
+
+  .part {
+    display: flex;
+    flex-direction: column;
+
+    padding: 6px 0px;
+
+    border-bottom: 1px solid var(--vita-border-weak);
+
+    :global(.ant-btn) {
+      justify-content: flex-start;
+
+      border-radius: 0px;
+    }
+  }
+}
+
+.dragOverlay {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+
+  cursor: pointer;
+  opacity: 0.9;
+
+  height: 34px;
+  padding: 6px 16px;
+
+  background: var(--vita-surface);
+  border-radius: 6px 6px 0 0;
+  border: 1px solid var(--vita-border);
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+
+  .tabLabel {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    column-gap: 5px;
+  }
+}