@hsu-react/ui 1.0.0 → 2.0.1

package/src/feedback/index.tsx

@@ -0,0 +1,141 @@
+import React, { useMemo } from "react";
+import {
+  Modal as AntdModal,
+  message as antdMessage,
+  notification as antdNotification,
+} from "antd";
+import type { HookAPI as ModalHookApi } from "antd/es/modal/useModal";
+import type { MessageInstance } from "antd/es/message/interface";
+import type { NotificationInstance } from "antd/es/notification/interface";
+
+/**
+ * 主题化的 message / notification / modal。
+ *
+ * 问题：antd 的 `message.success()`、`Modal.confirm()` 这类是命令式静态方法，调用时不在
+ * React 树里，读不到 `ConfigProvider` 注入的 `theme.token` —— 换过品牌色或切到暗色之后，
+ * 弹出来的东西还是 antd 的默认观感，与页面割裂。antd 官方的答案是改用 hook 版本
+ * （`Modal.useModal()` 等）并把返回的 contextHolder 渲染进树里，但那样每个调用点都得先拿
+ * 到实例，命令式的写法就没了。
+ *
+ * 这里的做法：`ConfigProvider` 内部挂一个 `FeedbackHolder`，它调用那三个 hook，把拿到的
+ * 实例存到模块级变量，并渲染各自的 contextHolder。下面导出的同名函数只是代理，转发给
+ * 被捕获的实例。于是调用写法不变，输出却在树内、能读到主题。
+ *
+ * 没挂 `ConfigProvider` 时回退到 antd 的静态方法：功能照常，只是不跟随主题，
+ * 并在开发环境提示一次。
+ */
+
+let modalInstance: ModalHookApi | null = null;
+let messageInstance: MessageInstance | null = null;
+let notificationInstance: NotificationInstance | null = null;
+
+let warned = false;
+const warnOnce = (name: string) => {
+  if (warned || process.env.NODE_ENV === "production") return;
+  warned = true;
+  console.warn(
+    `[@hsu-react/ui] ${name} 在 <ConfigProvider> 之外被调用，已回退到 antd 的静态方法。` +
+      `功能正常，但不会跟随 ConfigProvider 注入的主题（品牌色、暗色等）。` +
+      `把应用包在 <ConfigProvider> 里即可。`
+  );
+};
+
+/**
+ * 捕获三个 hook 实例并渲染它们的 contextHolder。由 `ConfigProvider` 内部渲染，
+ * 消费方不需要自己挂。
+ */
+export const FeedbackHolder: React.FC = () => {
+  const [modalApi, modalHolder] = AntdModal.useModal();
+  const [messageApi, messageHolder] = antdMessage.useMessage();
+  const [notificationApi, notificationHolder] =
+    antdNotification.useNotification();
+
+  // 同步赋值而不是放进 useEffect：子树里如果有组件在自己的 effect 里就弹提示，
+  // effect 的执行顺序是自下而上的，等到这里的 effect 跑完就已经晚了。
+  useMemo(() => {
+    modalInstance = modalApi;
+    messageInstance = messageApi;
+    notificationInstance = notificationApi;
+  }, [modalApi, messageApi, notificationApi]);
+
+  return (
+    <>
+      {modalHolder}
+      {messageHolder}
+      {notificationHolder}
+    </>
+  );
+};
+
+/** 仅供测试 / 卸载时清理 */
+export const resetFeedbackInstances = () => {
+  modalInstance = null;
+  messageInstance = null;
+  notificationInstance = null;
+};
+
+type MessageKey = keyof MessageInstance;
+type NotificationKey = keyof NotificationInstance;
+type ModalKey = keyof ModalHookApi;
+
+const proxyMessage = <K extends MessageKey>(key: K): MessageInstance[K] =>
+  ((...args: unknown[]) => {
+    const api = messageInstance;
+    if (!api) warnOnce("message");
+    return (
+      (api ?? antdMessage)[key] as unknown as (...a: unknown[]) => unknown
+    )(...args);
+  }) as MessageInstance[K];
+
+const proxyNotification = <K extends NotificationKey>(
+  key: K
+): NotificationInstance[K] =>
+  ((...args: unknown[]) => {
+    const api = notificationInstance;
+    if (!api) warnOnce("notification");
+    return (
+      (api ?? antdNotification)[key] as unknown as (...a: unknown[]) => unknown
+    )(...args);
+  }) as NotificationInstance[K];
+
+const proxyModal = <K extends ModalKey>(key: K): ModalHookApi[K] =>
+  ((...args: unknown[]) => {
+    const api = modalInstance;
+    if (!api) warnOnce("Modal");
+    return (
+      (api ?? AntdModal)[key] as unknown as (...a: unknown[]) => unknown
+    )(...args);
+  }) as ModalHookApi[K];
+
+/**
+ * 与 antd 的 `message` 同名同签名，区别是输出在 React 树内，会跟随主题。
+ * 直接把 `import { message } from "antd"` 换成从本库引入即可。
+ */
+export const message: MessageInstance = {
+  info: proxyMessage("info"),
+  success: proxyMessage("success"),
+  error: proxyMessage("error"),
+  warning: proxyMessage("warning"),
+  loading: proxyMessage("loading"),
+  open: proxyMessage("open"),
+  destroy: proxyMessage("destroy"),
+};
+
+/** 与 antd 的 `notification` 同名同签名，输出跟随主题 */
+export const notification: NotificationInstance = {
+  success: proxyNotification("success"),
+  error: proxyNotification("error"),
+  info: proxyNotification("info"),
+  warning: proxyNotification("warning"),
+  open: proxyNotification("open"),
+  destroy: proxyNotification("destroy"),
+};
+
+/** 与 antd 的 `Modal.confirm` 等同名同签名，输出跟随主题 */
+export const modalFuncs: ModalHookApi = {
+  info: proxyModal("info"),
+  success: proxyModal("success"),
+  error: proxyModal("error"),
+  warning: proxyModal("warning"),
+  confirm: proxyModal("confirm"),
+};

package/src/hooks/index.ts

@@ -1,2 +1,7 @@
 export { default as usePermissions, PermissionsContent } from "./usePermissions";
 export { default as useLabelWidth } from "./useLabelWidth";
+export { default as useIsDark } from "./useIsDark";
+export { default as useBreakpoint } from "./useBreakpoint";
+export type { BreakpointName, BreakpointState } from "./useBreakpoint";
+export { default as usePointerType } from "./usePointerType";
+export type { PointerType } from "./usePointerType";

package/src/hooks/useBreakpoint.ts

@@ -0,0 +1,62 @@
+import { useEffect, useState } from "react";
+
+import { breakpoints } from "../styles/tokens";
+
+export type BreakpointName = keyof typeof breakpoints;
+
+export interface BreakpointState {
+  /** 当前命中的最大断点；视口比 sm 还窄时为 `xs` */
+  current: BreakpointName | "xs";
+  /** 视口 >= 对应断点 */
+  up: Record<BreakpointName, boolean>;
+  /** 视口 < 对应断点 */
+  down: Record<BreakpointName, boolean>;
+  /** `< md`，用于「这是不是手机」这类粗判断 */
+  isMobile: boolean;
+}
+
+const NAMES = Object.keys(breakpoints) as BreakpointName[];
+
+const read = (): BreakpointState => {
+  const width =
+    typeof window === "undefined" ? breakpoints.xl : window.innerWidth;
+
+  const up = {} as Record<BreakpointName, boolean>;
+  const down = {} as Record<BreakpointName, boolean>;
+  let current: BreakpointName | "xs" = "xs";
+
+  for (const name of NAMES) {
+    const hit = width >= breakpoints[name];
+    up[name] = hit;
+    down[name] = !hit;
+    if (hit) current = name;
+  }
+
+  return { current, up, down, isMobile: width < breakpoints.md };
+};
+
+/**
+ * 当前视口命中的断点。
+ *
+ * 断点值与 `styles/_responsive.scss` 的 mixin 同源（都由 tokens.json 生成），所以 JS 里的判断
+ * 不会和 CSS 里的媒体查询错开。
+ *
+ * 能用 CSS 解决的就别用它 —— 媒体查询不需要 JS 参与、没有首屏闪烁、也不会因 SSR 拿不到
+ * `window` 而先渲染错一帧。只有当**结构**要变（比如小屏把表格换成卡片列表、把工具栏收进抽屉）
+ * 时才需要它。
+ */
+const useBreakpoint = (): BreakpointState => {
+  const [state, setState] = useState<BreakpointState>(read);
+
+  useEffect(() => {
+    const update = () => setState(read());
+    update();
+
+    window.addEventListener("resize", update);
+    return () => window.removeEventListener("resize", update);
+  }, []);
+
+  return state;
+};
+
+export default useBreakpoint;

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