@hsu-react/ui 1.0.0 → 2.0.0

package/src/components/Tags/_components/EllipsisTag/index.tsx

@@ -39,7 +39,7 @@ const EllipsisTag: React.FC<EllipsisTagProps> = (props) => {
       }}
       color="#fff"
       styles={{
-        body: {
+        container: {
           padding: "6px",
           maxHeight: "300px",
           overflow: "auto",

package/src/components/TextEllipsis/index.tsx

@@ -1,6 +1,7 @@
 import { Tooltip, TooltipProps } from "antd";
 import { ReactNode, useEffect, useRef, useState } from "react";
 import cssStyles from "./index.module.scss";
+import { mergeSemantic } from "../../utils/semantic";
 
 // Default Tooltip width
 const DEFAULT_TOOLTIP_WIDTH = 200;
@@ -201,15 +202,16 @@ const TextEllipsis: React.FC<TextEllipsisProps> = ({
       placement="bottomLeft"
       {...restTooltipConfig}
       title={isOverflow && !disabled ? tooltipTitle : undefined}
-      styles={{
-        body: {
+      styles={mergeSemantic(styles, (outer) => ({
+        // v5 called this slot `body`; v6 renamed it to `container`
+        container: {
           width: tooltipWidth,
           overflow: "auto",
           maxHeight: "300px",
           whiteSpace: "pre-wrap",
         },
-        ...styles,
-      }}
+        ...outer,
+      }))}
     >
       {content}
     </Tooltip>

package/src/components/Tree/index.md

@@ -55,6 +55,15 @@ export default () => (
 );
 ```
 
+## 子组件
+
+```tsx | pure
+Tree.DirectoryTree  // antd 的目录树（文件夹图标 + 目录态选中）
+Tree.TreeNode       // antd 的 JSX 节点声明
+```
+
+`TreeNode` 供 JSX 写法，本库更推荐用 `treeData`。
+
 ## API
 
 在 [antd TreeProps](https://ant.design/components/tree-cn)（已 `Omit` 掉 `treeData`、`loadData`、`loadedKeys`、`titleRender`）基础上扩展：

package/src/components/Tree/index.module.scss

@@ -11,9 +11,9 @@
   height: 100%;
   min-height: 0px !important;
 
-  background: var(--cf-surface);
+  background: var(--vita-surface);
 
-  border-radius: 8px;
+  border-radius: var(--vita-radius);
 
   .title_search {
     display: flex;
@@ -35,7 +35,7 @@
     }
 
     .search {
-      height: 32px;
+      height: var(--vita-control-height);
 
       .searchIcon {
         font-size: 16px;
@@ -58,11 +58,11 @@
 
     :global(.ant-tree-treenode) {
       &:hover {
-        background: var(--cf-subtle);
+        background: var(--vita-muted);
       }
 
       &:has(> :global(.ant-tree-node-selected)) {
-        background-color: color-mix(in srgb, var(--primary-color) 12%, transparent);
+        background-color: color-mix(in srgb, var(--vita-primary) 12%, transparent);
 
         :global(.ant-tree-node-selected) {
           background-color: transparent;
@@ -131,7 +131,7 @@
   &.legacyHasSelectedNodeBackground {
     .treeContainer {
       :global(.ant-tree-treenode):global(.ant-tree-treenode-selected) {
-        background-color: color-mix(in srgb, var(--primary-color) 12%, transparent);
+        background-color: color-mix(in srgb, var(--vita-primary) 12%, transparent);
 
         :global(.ant-tree-node-selected) {
           background-color: transparent;

package/src/components/Tree/index.tsx

@@ -72,7 +72,14 @@ export interface TreeProps extends Omit<
   titleSearchBarClassName?: string;
 }
 
-const Tree: React.FC<TreeProps> = (props) => {
+interface TreeFC extends React.FC<TreeProps> {
+  /** antd 的目录树（带文件夹图标与目录态选中） */
+  DirectoryTree: typeof AntdTree.DirectoryTree;
+  /** antd 的 `Tree.TreeNode`，供 JSX 写法（本库更推荐用 `treeData`） */
+  TreeNode: typeof AntdTree.TreeNode;
+}
+
+const Tree = ((props: TreeProps) => {
   const {
     title,
     titleRender,
@@ -304,6 +311,9 @@ const Tree: React.FC<TreeProps> = (props) => {
       </div>
     </div>
   );
-};
+}) as TreeFC;
+
+Tree.DirectoryTree = AntdTree.DirectoryTree;
+Tree.TreeNode = AntdTree.TreeNode;
 
 export default Tree;

package/src/components/Upload/_components/UploadedItem/index.tsx

@@ -94,9 +94,9 @@ export const UploadedItem: React.FC<UploadedItemProps> = ({
     <div className={classNames(styles.fileItem, listProps?.item)}>
       <Tooltip
         title={name}
-        color="var(--cf-subtle)"
+        color="var(--vita-muted)"
         styles={{
-          body: { color: "var(--cf-text)", padding: "6px 16px" },
+          container: { color: "var(--vita-foreground)", padding: "6px 16px" },
         }}
       >
         <div className={classNames(styles.fileName, listProps?.itemName)}>

package/src/components/Upload/_components/UploadingItem/index.tsx

@@ -32,9 +32,9 @@ export const UploadingItem: React.FC<UploadingItemProps> = ({
       <div className={styles.uploading}>
         <Tooltip
           title={name}
-          color="var(--cf-subtle)"
+          color="var(--vita-muted)"
           styles={{
-            body: { color: "var(--cf-text)", padding: "6px 16px" },
+            container: { color: "var(--vita-foreground)", padding: "6px 16px" },
           }}
         >
           <div

package/src/components/Upload/_utils/normalUpload.ts

@@ -3,7 +3,7 @@ import { RcFile } from "antd/es/upload";
 import { deepCopy } from "hsu-utils";
 import { validateFile, createFormData, isSuccessResponse } from ".";
 import { UploadingList } from "..";
-import type { UploadRequestOption } from "rc-upload/lib/interface";
+import type { UploadRequestOption } from "../../../types/antd";
 
 interface NormalUploadOptions {
   file: RcFile;

package/src/components/Upload/_utils/validateFile.ts

@@ -8,6 +8,60 @@ interface ValidateFileOptions {
   en?: boolean;
 }
 
+/**
+ * 文件是否命中 accept —— 与 antd 保持一致的语义。
+ *
+ * 此前是把 accept 拼进正则：`new RegExp(`(${accept.replace(/,/g, "|")})$`)`，有两个问题：
+ * 字符没转义（`.png` 里的 `.` 是「任意字符」，实测放行了 `axpng`），且 HTML 允许的 MIME
+ * 形式里 `image/*` 的 `*` 会被当成量词（实测把 photo.png 判成了格式错误）。把外部字符串
+ * 拼进正则本身也是 ReDoS 入口。
+ *
+ * 这里照抄 @rc-component/upload 的 attr-accept 语义，而不是另写一套：这个函数是上传前的
+ * 预校验，antd 自己的 accept 过滤也在跑，两边规则一旦不一致，就会出现「antd 放行、我们拦下」
+ * 或反过来的割裂。逐条 some()，任一命中即通过，全不命中即拒绝 —— 不做额外兜底。
+ */
+const matchesAccept = (
+  file: { name: string; type?: string },
+  accept: string
+): boolean => {
+  const items = accept.split(",");
+  const fileName = file.name || "";
+  const mimeType = file.type || "";
+  const baseMimeType = mimeType.replace(/\/.*$/, "");
+
+  return items.some((item) => {
+    const validType = item.trim();
+    if (!validType) return false;
+
+    // `*` / `*​/*`：全部放行
+    if (/^\*(\/\*)?$/.test(validType)) return true;
+
+    // 扩展名。jpg 与 jpeg 互认，与 attr-accept 一致
+    if (validType.charAt(0) === ".") {
+      const lowerName = fileName.toLowerCase();
+      const lowerType = validType.toLowerCase();
+      const affixes =
+        lowerType === ".jpg" || lowerType === ".jpeg"
+          ? [".jpg", ".jpeg"]
+          : [lowerType];
+      return affixes.some((affix) => lowerName.endsWith(affix));
+    }
+
+    // `image/*` 这类通配
+    if (/\/\*$/.test(validType)) {
+      return baseMimeType === validType.replace(/\/.*$/, "");
+    }
+
+    // MIME 全等
+    if (mimeType === validType) return true;
+
+    // `png` 这种没有点也没有斜杠的写法是无效 accept，attr-accept 选择跳过而不是拦下
+    if (/^\w+$/.test(validType)) return true;
+
+    return false;
+  });
+};
+
 /**
  * Validate file format and size
  */
@@ -18,8 +72,7 @@ export function validateFile({
   en,
 }: ValidateFileOptions): { valid: boolean; error?: Error } {
   if (accept) {
-    const fileRegex = new RegExp(`(${accept.replace(/,/g, "|")})$`);
-    if (!fileRegex.test(file.name.toLowerCase())) {
+    if (!matchesAccept(file, accept)) {
       return {
         valid: false,
         error: new Error(

package/src/components/Upload/index.md

@@ -64,6 +64,15 @@ export default () => {
 };
 ```
 
+## 子组件
+
+```tsx | pure
+Upload.Dragger      // antd 的拖拽上传区
+Upload.LIST_IGNORE  // beforeUpload 返回它表示「跳过该文件且不进 fileList」
+```
+
+本库的 `Upload` 传 `drop` 属性即可切成拖拽形态；`Upload.Dragger` 是 antd 原生的那个，两者不要混用。
+
 ## API
 
 继承 antd [UploadProps](https://ant.design/components/upload-cn)（移除原 `action`、`data` 后重新定义），新增/重写属性如下：

package/src/components/Upload/index.tsx

@@ -3,7 +3,7 @@ import {
   UploadProps as AntdUploadProps,
   UploadFile,
 } from "antd";
-import type { UploadRequestOption } from "rc-upload/lib/interface";
+import type { UploadRequestOption } from "../../types/antd";
 import React, { useCallback } from "react";
 import { Canceler } from "axios";
 import { RcFile } from "antd/es/upload";
@@ -58,7 +58,14 @@ export interface UploadProps extends Omit<AntdUploadProps, "action" | "data"> {
   en?: boolean;
 }
 
-const Upload: React.FC<UploadProps> = (props) => {
+interface UploadFC extends React.FC<UploadProps> {
+  /** antd 的拖拽上传区 */
+  Dragger: typeof AntdUpload.Dragger;
+  /** `beforeUpload` 返回它表示「跳过这个文件且不进 fileList」 */
+  LIST_IGNORE: typeof AntdUpload.LIST_IGNORE;
+}
+
+const Upload = ((props: UploadProps) => {
   const {
     disabled = false,
     drop,
@@ -86,6 +93,11 @@ const Upload: React.FC<UploadProps> = (props) => {
     ...uploadConfig
   } = props;
 
+  // antd v6 widened `accept` to `string | { format: string; filter?: ... }`. This component's own
+  // extension check (validateFile) only understands the comma-separated string, so read the format
+  // out of the object form; antd still applies the full config to the native file input.
+  const acceptFormat = typeof accept === "string" ? accept : accept.format;
+
   const {
     fileList: _fileList,
     setFileList,
@@ -131,7 +143,7 @@ const Upload: React.FC<UploadProps> = (props) => {
         chunkNum,
         data,
         headers,
-        accept,
+        accept: acceptFormat,
         size,
         en,
         uploadingList,
@@ -148,7 +160,7 @@ const Upload: React.FC<UploadProps> = (props) => {
       chunkNum,
       data,
       headers,
-      accept,
+      acceptFormat,
       size,
       en,
       uploadingList,
@@ -180,7 +192,7 @@ const Upload: React.FC<UploadProps> = (props) => {
         action,
         data,
         headers,
-        accept,
+        accept: acceptFormat,
         size,
         en,
         uploadingList,
@@ -195,7 +207,7 @@ const Upload: React.FC<UploadProps> = (props) => {
       action,
       data,
       headers,
-      accept,
+      acceptFormat,
       size,
       en,
       uploadingList,
@@ -301,6 +313,9 @@ const Upload: React.FC<UploadProps> = (props) => {
       />
     </>
   );
-};
+}) as UploadFC;
+
+Upload.Dragger = AntdUpload.Dragger;
+Upload.LIST_IGNORE = AntdUpload.LIST_IGNORE;
 
 export default Upload;

package/src/config-provider/index.tsx

@@ -1,27 +1,70 @@
-import React, { useMemo } from "react";
+import React, { useEffect, useMemo } from "react";
+import {
+  ConfigProvider as AntdConfigProvider,
+  theme as antdTheme,
+  type ThemeConfig,
+} from "antd";
 
 import { PermissionsContent } from "../hooks/usePermissions";
+import useIsDark from "../hooks/useIsDark";
 import { configureRequest, RequestImpl } from "../request";
+import { toAntdComponents, toAntdTheme } from "../styles/tokens";
+import { FeedbackHolder } from "../feedback";
 
 export interface ConfigProviderProps {
   /** Current user's permission code list; when provided, usePermissions / hasPermi validate against it. If omitted, everything is allowed by default */
   permissions?: string[] | null;
   /** Inject the HTTP request implementation, used by smart components such as ImportForm */
   request?: Partial<RequestImpl>;
+  /**
+   * Brand colour. Sets both halves of the token layer at once: the `--vita-primary` CSS variable
+   * (via `--primary-color`, so pre-2.0 overrides keep working) and antd's `colorPrimary`.
+   *
+   * Setting the CSS variable by hand only moves this library's own styles — antd derives a
+   * 10-step palette from the JS token and cannot read a `var()`. Going through this prop is what
+   * keeps the two in step.
+   */
+  primaryColor?: string;
+  /**
+   * Force light/dark instead of following `html[data-theme]` / the OS preference.
+   * The CSS variables follow the same signals on their own.
+   */
+  dark?: boolean;
+  /**
+   * Extra antd theme config, merged on top of the generated one — escape hatch for a consumer
+   * that wants a token this library does not map.
+   */
+  theme?: ThemeConfig;
+  /**
+   * Set to `false` to stop managing antd's theme entirely, leaving it to the host app.
+   * Components this library wraps still follow the `--vita-*` variables; antd components it does
+   * not wrap will fall back to antd's stock look.
+   */
+  antdTheme?: boolean;
   children?: React.ReactNode;
 }
 
 /**
- * Hsu UI global configuration: injects permissions and the request implementation.
+ * Hsu UI global configuration: permissions, the request implementation, and the design tokens.
+ *
+ * On the theme: the `--vita-*` CSS variables cover everything this library styles itself, but not
+ * the antd components it merely re-exports or that a page uses directly. Feeding antd's
+ * `theme.token` from the very same tokens is what makes an unwrapped `<Steps />` land on the same
+ * palette, radii and type scale as a wrapped `<Table />` — without this library having to wrap all
+ * 75 antd components to keep the look consistent.
  *
  * @example
- * <ConfigProvider permissions={perms} request={{ get, post, del, put }}>
+ * <ConfigProvider permissions={perms} request={{ get, post, del, put }} primaryColor="#7c3aed">
  *   <App />
  * </ConfigProvider>
  */
 const ConfigProvider: React.FC<ConfigProviderProps> = ({
   permissions = null,
   request,
+  primaryColor,
+  dark,
+  theme,
+  antdTheme: manageAntdTheme = true,
   children,
 }) => {
   // Inject synchronously during render so child components get the request implementation on their very first interaction
@@ -31,11 +74,48 @@ const ConfigProvider: React.FC<ConfigProviderProps> = ({
 
   const permissionsValue = useMemo(() => ({ permissions }), [permissions]);
 
-  return (
+  const detectedDark = useIsDark();
+  const isDark = dark ?? detectedDark;
+
+  const themeConfig = useMemo<ThemeConfig>(
+    () => ({
+      algorithm: isDark ? antdTheme.darkAlgorithm : antdTheme.defaultAlgorithm,
+      ...theme,
+      token: { ...toAntdTheme({ dark: isDark, primaryColor }), ...theme?.token },
+      components: { ...toAntdComponents(), ...theme?.components },
+    }),
+    [isDark, primaryColor, theme]
+  );
+
+  // Written onto <html> rather than a wrapper element: this provider usually sits at the very top
+  // of the tree, and slipping an extra div in there would change the layout of whatever it wraps.
+  // `--primary-color` rather than `--vita-primary` because the generated tokens make the latter
+  // point at the former, so writing the legacy name keeps both spellings working for consumers.
+  useEffect(() => {
+    if (!primaryColor || typeof document === "undefined") return;
+
+    const root = document.documentElement;
+    const previous = root.style.getPropertyValue("--primary-color");
+    root.style.setProperty("--primary-color", primaryColor);
+
+    return () => {
+      if (previous) root.style.setProperty("--primary-color", previous);
+      else root.style.removeProperty("--primary-color");
+    };
+  }, [primaryColor]);
+
+  const tree = (
     <PermissionsContent.Provider value={permissionsValue}>
+      {/* 让 message / notification / Modal.confirm 这类命令式 API 的输出落在树内，
+          从而能读到下面注入的主题。见 ../feedback。 */}
+      <FeedbackHolder />
       {children}
     </PermissionsContent.Provider>
   );
+
+  if (!manageAntdTheme) return tree;
+
+  return <AntdConfigProvider theme={themeConfig}>{tree}</AntdConfigProvider>;
 };
 
 export default ConfigProvider;

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;