@hsu-react/ui 1.0.0 → 2.0.0

package/src/hooks/useIsDark.ts

@@ -0,0 +1,64 @@
+import { useEffect, useState } from "react";
+
+/**
+ * Attributes that mark the document as dark. These are the same selectors the generated
+ * `tokens.scss` keys off, so the CSS-variable layer and the antd theme always agree on which
+ * palette is active — `data-theme` is what consuming apps toggle, the `prefers-color*` pair is
+ * what the dumi docs site sets.
+ */
+const DARK_ATTRS = [
+  "data-theme",
+  "data-prefers-color",
+  "data-prefers-color-scheme",
+] as const;
+
+const read = (): boolean => {
+  if (typeof document === "undefined") return false;
+
+  const root = document.documentElement;
+  for (const attr of DARK_ATTRS) {
+    const value = root.getAttribute(attr);
+    if (value === "dark") return true;
+    if (value === "light") return false;
+  }
+
+  return (
+    typeof window !== "undefined" &&
+    window.matchMedia?.("(prefers-color-scheme: dark)").matches
+  );
+};
+
+/**
+ * Whether the document is currently in dark mode.
+ *
+ * The CSS variables switch on their own — they are plain CSS. antd's theme cannot: its tokens are
+ * computed in JS, so the algorithm has to be swapped on re-render. This hook is that bridge, and
+ * `ConfigProvider` uses it to pick `darkAlgorithm`.
+ */
+const useIsDark = (): boolean => {
+  const [isDark, setIsDark] = useState(read);
+
+  useEffect(() => {
+    const update = () => setIsDark(read());
+    update();
+
+    const observer = new MutationObserver(update);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: [...DARK_ATTRS],
+    });
+
+    // Only relevant while no explicit attribute is set, but harmless otherwise.
+    const media = window.matchMedia?.("(prefers-color-scheme: dark)");
+    media?.addEventListener?.("change", update);
+
+    return () => {
+      observer.disconnect();
+      media?.removeEventListener?.("change", update);
+    };
+  }, []);
+
+  return isDark;
+};
+
+export default useIsDark;

package/src/hooks/usePointerType.ts

@@ -0,0 +1,59 @@
+import { useEffect, useState } from "react";
+
+export interface PointerType {
+  /** 主要输入设备是粗指针（手指、触控笔） */
+  isCoarse: boolean;
+  /** 设备具备真正的悬停能力（鼠标、触控板） */
+  canHover: boolean;
+  /** 粗指针且不能悬停 —— 通常意义上的「触屏设备」 */
+  isTouch: boolean;
+}
+
+const QUERY_COARSE = "(pointer: coarse)";
+const QUERY_HOVER = "(hover: hover)";
+
+const read = (): PointerType => {
+  if (typeof window === "undefined" || !window.matchMedia) {
+    return { isCoarse: false, canHover: true, isTouch: false };
+  }
+
+  const isCoarse = window.matchMedia(QUERY_COARSE).matches;
+  const canHover = window.matchMedia(QUERY_HOVER).matches;
+
+  return { isCoarse, canHover, isTouch: isCoarse && !canHover };
+};
+
+/**
+ * 当前设备的指针能力。
+ *
+ * 刻意**不**做 UA 嗅探：二合一设备可以在触摸与鼠标之间来回切换，媒体查询会跟着变，UA 不会。
+ *
+ * 另外说明一个常见误解：不需要为了移动端把 `onClick` 换成 `onTouchStart`。触摸事件序列本来
+ * 就会合成 click，`onClick` 在触屏上一直是能用的；换成 touch 反而会丢掉键盘可访问性、在滚动
+ * 时误触发、并与合成的 click 重复触发。移动端真正要处理的是别的东西 —— 300ms 点击延迟
+ * （用 `touch-action: manipulation`）、点完粘住不消的 `:hover`（用 `_responsive.scss` 的
+ * `hover` mixin 包起来）、以及过小的点按目标。这个 hook 用于最后一类：需要按指针类型
+ * **改变结构或尺寸**的场合。
+ */
+const usePointerType = (): PointerType => {
+  const [state, setState] = useState<PointerType>(read);
+
+  useEffect(() => {
+    const update = () => setState(read());
+    update();
+
+    const coarse = window.matchMedia(QUERY_COARSE);
+    const hover = window.matchMedia(QUERY_HOVER);
+    coarse.addEventListener?.("change", update);
+    hover.addEventListener?.("change", update);
+
+    return () => {
+      coarse.removeEventListener?.("change", update);
+      hover.removeEventListener?.("change", update);
+    };
+  }, []);
+
+  return state;
+};
+
+export default usePointerType;

package/src/index.ts

@@ -13,20 +13,52 @@ export {
 export type { RequestImpl, RequestConfig, ResType, ListRes, FileRes } from "./request";
 
 // hooks & utils
-export { usePermissions, PermissionsContent, useLabelWidth } from "./hooks";
+export {
+  usePermissions,
+  PermissionsContent,
+  useLabelWidth,
+  useIsDark,
+  useBreakpoint,
+  usePointerType,
+} from "./hooks";
+export type { BreakpointName, BreakpointState, PointerType } from "./hooks";
 export { getUUID, supportsHasSelector, isLegacyHasSelectorBrowser } from "./utils";
 
-// Design tokens (TS constants for JS-side consumers such as antd themeConfig; CSS-variable version lives in es/styles/tokens.scss)
-export { lightTokens, darkTokens, defaultPrimaryColor } from "./styles/tokens";
+// Design tokens. src/styles/tokens.json is the single source of truth: this module is its JS side
+// (including toAntdTheme, which ConfigProvider feeds to antd), and es/styles/tokens.scss is the
+// generated --vita-* CSS-variable side.
+export {
+  lightTokens,
+  darkTokens,
+  defaultPrimaryColor,
+  radius,
+  fontTokens,
+  controlTokens,
+  modalWidth,
+  breakpoints,
+  toAntdTheme,
+} from "./styles/tokens";
 export type { HsuThemeTokens } from "./styles/tokens";
 
+// 主题化的命令式反馈 API。与 antd 的 message / notification 同名同签名，区别是输出落在
+// ConfigProvider 内，会跟随注入的主题；把 `from "antd"` 换成 `from "@hsu-react/ui"` 即可。
+export { message, notification } from "./feedback";
+
+// 布局组件**刻意不从这里导出**。
+//
+// 它们依赖 react-router / react-intl，而这两个是可选 peerDependency。一旦在根入口静态
+// re-export，`import { Button } from "@hsu-react/ui"` 也会让打包器去解析 react-router ——
+// 没装的项目直接构建失败，"可选" 就名存实亡了。
+//
+// 改为子路径引入：
+//   import Layout from "@hsu-react/ui/es/layout";
+//   import type { RouteType } from "@hsu-react/ui/es/layout";
+
 // Components
 export { default as Button } from "./components/Button";
 export * from "./components/Button";
 export { default as ChainGraph } from "./components/ChainGraph";
 export * from "./components/ChainGraph";
-export { default as ChakraRoot } from "./components/ChakraRoot";
-export * from "./components/ChakraRoot";
 export { default as Chart } from "./components/Chart";
 export * from "./components/Chart";
 export { default as Chat } from "./components/Chat";

package/src/layout/Breadcrumb/_components/BreadcrumbItemIcon/index.tsx

@@ -0,0 +1,26 @@
+import React, { ReactNode } from "react";
+import { Space } from "antd";
+import Icon from "../../../../components/Icon";
+
+interface BreadcrumbItemIconProps {
+  icon?: ReactNode;
+  title?: ReactNode;
+}
+
+/**
+ * Breadcrumb item icon and title component
+ */
+const BreadcrumbItemIcon: React.FC<BreadcrumbItemIconProps> = ({
+  icon,
+  title,
+}) => {
+  return (
+    <Space size={5}>
+      {typeof icon === "string" ? <Icon icon={icon} /> : icon}
+      {title}
+    </Space>
+  );
+};
+
+export default BreadcrumbItemIcon;
+

package/src/layout/Breadcrumb/_components/BreadcrumbMenuItem/index.tsx

@@ -0,0 +1,32 @@
+import React from "react";
+import { Space } from "antd";
+import Icon from "../../../../components/Icon";
+import { BreadcrumbType } from "../..";
+
+interface BreadcrumbMenuItemProps {
+  item: BreadcrumbType;
+  navigate: (path: string) => void;
+}
+
+/**
+ * Breadcrumb menu item component
+ */
+const BreadcrumbMenuItem: React.FC<BreadcrumbMenuItemProps> = ({
+  item,
+  navigate,
+}) => {
+  const handleClick = () => {
+    if ((!item.children || item.route?.index) && item.path) {
+      navigate(item.path);
+    }
+  };
+
+  return (
+    <Space size={5} onClick={handleClick}>
+      {typeof item.icon === "string" ? <Icon icon={item.icon} /> : item.icon}
+      {item.title}
+    </Space>
+  );
+};
+
+export default BreadcrumbMenuItem;

package/src/layout/Breadcrumb/_hooks/useBreadcrumbPath.ts

@@ -0,0 +1,111 @@
+import { useEffect, useState, useContext, useMemo } from "react";
+import { useLocation } from "react-router";
+import { BreadcrumbType } from "..";
+import { checkBreadcrumbPathMatch } from "../_utils/pathMatch";
+import { NavTabBarTitleContent } from "../../_hooks/useSetTabTitle";
+
+/**
+ * Hook that handles breadcrumb path matching
+ */
+export const useBreadcrumbPath = (_routes: BreadcrumbType[]) => {
+  const location = useLocation();
+  const { tabTitles } = useContext(NavTabBarTitleContent);
+  const [breadcrumb, setBreadcrumb] = useState<BreadcrumbType[]>([]);
+
+  const pathname = useMemo(
+    () => decodeURI(location.pathname),
+    [location.pathname]
+  );
+
+  useEffect(() => {
+    const _setBreadcrumb = (
+      routes: BreadcrumbType[],
+      parents?: BreadcrumbType[]
+    ) => {
+      const checkPath = (item: BreadcrumbType) => {
+        if (item.path) {
+          const isMatch = checkBreadcrumbPathMatch(
+            pathname,
+            item.path,
+            item.parent?.path
+          );
+
+          if (isMatch) {
+            // If tabTitles has a title for the current path, apply the custom title
+            const finalItem =
+              tabTitles && tabTitles[pathname] !== undefined
+                ? { ...item, title: tabTitles[pathname] }
+                : item;
+
+            if (parents) {
+              return [...parents, finalItem];
+            } else {
+              return [finalItem];
+            }
+          }
+        }
+
+        return [];
+      };
+
+      routes?.forEach((item) => {
+        if (item.children) {
+          if (item.route?.index) {
+            const _breadcrumb = checkPath(item);
+            if (_breadcrumb.length > 0) {
+              setBreadcrumb(_breadcrumb);
+            } else {
+              const _newParents = parents ? [...parents, item] : [item];
+              _setBreadcrumb(item.children, _newParents);
+            }
+          } else {
+            const _newParents = parents ? [...parents, item] : [item];
+            _setBreadcrumb(item.children, _newParents);
+          }
+        } else {
+          const _breadcrumb = checkPath(item);
+          if (_breadcrumb.length > 0) {
+            setBreadcrumb(_breadcrumb);
+          }
+        }
+      });
+    };
+
+    setBreadcrumb([]);
+    _setBreadcrumb(_routes);
+  }, [_routes, pathname, tabTitles]);
+
+  // When tabTitles changes, update the title of the last breadcrumb item
+  useEffect(() => {
+    if (!pathname) return;
+
+    setBreadcrumb((prev) => {
+      if (prev.length === 0) return prev;
+
+      const newBreadcrumb = [...prev];
+      const lastItem = newBreadcrumb[newBreadcrumb.length - 1];
+
+      // Check whether the current path matches the last breadcrumb item
+      const isPathMatch =
+        lastItem.path === pathname ||
+        (lastItem.path &&
+          checkBreadcrumbPathMatch(
+            pathname,
+            lastItem.path,
+            lastItem.parent?.path
+          ));
+
+      if (isPathMatch && tabTitles && tabTitles[pathname] !== undefined) {
+        // If tabTitles has a title for the current path, update it
+        newBreadcrumb[newBreadcrumb.length - 1] = {
+          ...lastItem,
+          title: tabTitles[pathname],
+        };
+      }
+
+      return newBreadcrumb;
+    });
+  }, [tabTitles, pathname]);
+
+  return breadcrumb;
+};

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

@@ -0,0 +1,30 @@
+import React from "react";
+import { BreadcrumbType } from "..";
+import { ItemType as MenuItemType } from "antd/es/menu/interface";
+import BreadcrumbMenuItem from "../_components/BreadcrumbMenuItem";
+import { cloneDeep } from "lodash";
+
+/**
+ * Format the breadcrumb submenu
+ * @param children Child breadcrumb items
+ * @param navigate Navigation function
+ * @returns Array of menu items
+ */
+export const formatBreadcrumbMenu = (
+  children: BreadcrumbType[],
+  navigate: (path: string) => void
+): Omit<MenuItemType, "null">[] => {
+  return children?.map((item) => {
+    const children = item.children?.filter((i) => !i.path?.includes(":"));
+    const childrenBreadcrumb = formatBreadcrumbMenu(
+      cloneDeep(children || []),
+      navigate
+    );
+
+    return {
+      key: decodeURI(item.path ?? ""),
+      label: React.createElement(BreadcrumbMenuItem, { item, navigate }),
+      children: childrenBreadcrumb.length > 0 ? childrenBreadcrumb : undefined,
+    };
+  });
+};

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

@@ -0,0 +1,71 @@
+import { cloneDeep } from "lodash";
+import { RouteType } from "../../types";
+import { BreadcrumbType } from "..";
+
+/**
+ * Format routes into breadcrumb items
+ * @param router Route configuration
+ * @param parent Parent route
+ * @returns Array of breadcrumb items
+ */
+export const formatRoutes = (
+  router: RouteType[],
+  parent?: RouteType
+): BreadcrumbType[] => {
+  const newRoutes: BreadcrumbType[] = [];
+
+  router?.forEach((route) => {
+    let children: BreadcrumbType[] | undefined = undefined;
+    if (route.children) {
+      children = formatRoutes(route.children, cloneDeep(route) as RouteType);
+    }
+
+    const { meta } = route;
+
+    if (meta?.menu || !meta?.noTabsView) {
+      let path = "";
+
+      if (route.path) {
+        path = decodeURI(route.path);
+      }
+
+      if (route.index) {
+        newRoutes.push({
+          path: parent?.path,
+          title: meta?.name,
+          children: (children?.length || 0) > 0 ? children : undefined,
+          icon: meta?.icon,
+          parent: parent,
+          route: route,
+          index: true,
+        });
+      } else {
+        const indexChild = children?.find((child) => child?.index);
+        const newChildren = children?.filter((child) => !child?.index);
+
+        if (indexChild) {
+          newRoutes.push({
+            ...indexChild,
+            index: false,
+            parent: parent,
+            children: (newChildren?.length || 0) > 0 ? newChildren : undefined,
+          });
+        } else {
+          newRoutes.push({
+            path,
+            title: meta?.name,
+            children: (children?.length || 0) > 0 ? children : undefined,
+            icon: meta?.icon,
+            parent: parent,
+          });
+        }
+      }
+    } else {
+      if (children) {
+        newRoutes.push(...children);
+      }
+    }
+  });
+
+  return newRoutes;
+};

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;
+}
+
+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;