@hsu-react/ui 2.4.8 → 2.5.0

package/es/components/Chat/ChatHistory/_components/HistoryGroup/index.module.scss

@@ -8,7 +8,8 @@
 
     font-size: 14px;
     font-weight: bold;
-    color: var(--vita-subtle-foreground);
+    // 分组标题（「今天」「近 7 天」），与侧栏菜单的分组标题同一件事
+    color: var(--vita-muted-foreground);
 
     cursor: default;
   }

package/es/components/Chat/ChatList/_components/Assistant/AssistantItem/_components/QuoteList/index.module.scss

@@ -108,7 +108,8 @@
       transition: background-color 0.3s, color 0.3s;
 
       &:hover {
-        color: #fff;
+        // 同 TabBar：主色实底上的前景色走配对令牌
+        color: var(--vita-primary-foreground);
 
         background-color: var(--vita-primary);
       }

package/es/components/FormItem/FormInput/FormInputNumber/index.d.ts

@@ -2,7 +2,23 @@ import { ItemContainerProps } from "../../ItemContainer";
 import { InputNumberProps } from "../../../Input/Number";
 import React from "react";
 export interface FormInputNumberProps extends ItemContainerProps {
-    componentProps?: InputNumberProps;
+    /**
+     * `onChange` 的签名比基础组件宽：作为**表单字段**，默认交出的是
+     * `number | null`（见 Bridge 的注释）。写这个回调的人拿到的与表单拿到的
+     * 是同一个值。
+     */
+    componentProps?: Omit<InputNumberProps, "onChange"> & {
+        onChange?: (value: string | number | null) => void;
+    };
+    /**
+     * 交给表单的是字符串而不是数字。默认 `false`。
+     *
+     * 只有真的要处理**超出 IEEE754 安全范围的大数**（订单号、雪花 ID）时才打开
+     * —— 那种值转成 number 会丢精度，必须一路以字符串传递。
+     *
+     * 2.5.0 之前没有这个开关，行为固定等同于 `stringMode`（见下方 Bridge 注释）。
+     */
+    stringMode?: boolean;
 }
 declare const FormInputNumber: React.FC<FormInputNumberProps>;
 export default FormInputNumber;

package/es/components/FormItem/FormInput/FormInputNumber/index.js

@@ -1,6 +1,7 @@
 function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
-var _excluded = ["componentProps", "className", "disabled"],
-  _excluded2 = ["placeholder"];
+var _excluded = ["value", "onChange", "componentOnChange", "stringMode"],
+  _excluded2 = ["componentProps", "className", "disabled", "stringMode"],
+  _excluded3 = ["placeholder", "onChange"];
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
@@ -11,19 +12,77 @@ function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) r
 import ItemContainer from "../../ItemContainer";
 import Input from "../../../Input";
 import React from "react";
+
+// value / onChange 要重新声明：`InputNumberProps` 上那两个是**基础组件**的
+// 契约（字符串进、字符串出），而这里收的是**表单值**，可以是数字或 null
 import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 夹在 `Form.Item` 与 `Input.Number` 之间，**把字符串换成数字再交给表单**。
+ *
+ * 为什么需要它：`Input.Number` 内部以字符串保存（底层 `stringMode`，为的是不
+ * 丢大数精度），`onChange` 交出的也是字符串。这对一个**基础输入组件**是合理
+ * 的，但对一个叫 INPUTNUMBER 的**表单字段**不合理 —— 表单收上去的值会直接
+ * 进请求体，而后端字段多半是整数：
+ *
+ * ```
+ * 422  invalid type: string "2", expected i32
+ * ```
+ *
+ * 这个坑平时看不见：没动过的字段，值来自详情接口、本来就是数字，原样发回去
+ * 没事；**只有用户真的改了那一格**才会变成字符串。现象是「我明明只改了个
+ * 数字却保存失败」，而且报错在服务端，前端一行日志都没有。
+ *
+ * 转换只在**往上交**的方向做；`Input.Number` 内部仍然是字符串，所以正在敲的
+ * "1." / "1.50" 不会被改写（配套改动见 `Input/Number` 里的 sameNumber 判断）。
+ */
+var Bridge = function Bridge(props) {
+  var value = props.value,
+    onChange = props.onChange,
+    componentOnChange = props.componentOnChange,
+    stringMode = props.stringMode,
+    rest = _objectWithoutProperties(props, _excluded);
+  var emit = function emit(next) {
+    onChange === null || onChange === void 0 || onChange(next);
+    componentOnChange === null || componentOnChange === void 0 || componentOnChange(next);
+  };
+  return /*#__PURE__*/_jsx(Input.Number, _objectSpread(_objectSpread({}, rest), {}, {
+    value: value,
+    onChange: function onChange(text) {
+      if (stringMode) {
+        emit(text);
+        return;
+      }
+
+      // 空 → null 而不是 ""：语义是「没填」，不是「填了个空字符串」。
+      // 后端 `Option<i32>` 收得下 null，收不下 ""
+      if (text === "" || text === null || text === undefined) {
+        emit(null);
+        return;
+      }
+      var num = Number(text);
+      // 转不动就原样交出去（用户可能正敲到 "-" 或 "1e" 这种中间态）。
+      // 硬转成 NaN 会让表单里躺着一个既非数字也非空的值
+      emit(Number.isFinite(num) ? num : text);
+    }
+  }));
+};
 var FormInputNumber = function FormInputNumber(props) {
   var _inputConfig$disabled;
   var _props$componentProps = props.componentProps,
     componentProps = _props$componentProps === void 0 ? {} : _props$componentProps,
     itemClassName = props.className,
     disabled = props.disabled,
-    formItemProps = _objectWithoutProperties(props, _excluded);
+    stringMode = props.stringMode,
+    formItemProps = _objectWithoutProperties(props, _excluded2);
+  // onChange 必须摘出来，理由见 BridgeProps.componentOnChange
   var placeholder = componentProps.placeholder,
-    inputConfig = _objectWithoutProperties(componentProps, _excluded2);
+    componentOnChange = componentProps.onChange,
+    inputConfig = _objectWithoutProperties(componentProps, _excluded3);
   return /*#__PURE__*/_jsx(ItemContainer, _objectSpread(_objectSpread({}, formItemProps), {}, {
     className: "".concat(itemClassName !== null && itemClassName !== void 0 ? itemClassName : ""),
-    children: /*#__PURE__*/_jsx(Input.Number, _objectSpread(_objectSpread({}, inputConfig), {}, {
+    children: /*#__PURE__*/_jsx(Bridge, _objectSpread(_objectSpread({}, inputConfig), {}, {
+      componentOnChange: componentOnChange,
+      stringMode: stringMode,
       disabled: (_inputConfig$disabled = inputConfig.disabled) !== null && _inputConfig$disabled !== void 0 ? _inputConfig$disabled : disabled,
       placeholder: placeholder !== null && placeholder !== void 0 ? placeholder : "请输入"
     }))

package/es/components/Input/Number/index.d.ts

@@ -3,7 +3,11 @@ import React from "react";
 export interface InputNumberProps extends Omit<AntdInputNumberProps, "ref" | "onChange" | "value"> {
     getRef?: (ref: HTMLInputElement | null) => void;
     onChange?: (value: string) => void;
-    value?: string;
+    /**
+     * 受控值。本组件内部**始终以字符串保存**（底层开了 antd 的 `stringMode`，
+     * 为的是不丢大数精度），但外部传数字进来也接得住。
+     */
+    value?: string | number | null;
     allowClear?: boolean;
     wrapperClassName?: string;
 }

package/es/components/Input/Number/index.js

@@ -64,16 +64,33 @@ var InputNumber = function InputNumber(props) {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
       prevValueRef.current = value;
-      if (value !== undefined) {
+
+      // 数值相等就不要回写文本。
+      //
+      // 上游把值转成数字之后（`FormItem` 的 INPUTNUMBER 默认就会转），一个
+      // 回环会打回来：输入 "1." → onChange → 表单存 1 → value={1} 传回来。
+      // 若照单全收地写成 "1"，用户刚敲的小数点当场消失、光标还会跳到末尾，
+      // "1.50" 也会被改写成 "1.5"。
+      //
+      // 判据用**数值相等**而不是字符串相等：这几种写法（"1." / "1.50" / "+1"）
+      // 表示的是同一个数，此时以用户正在敲的那份文本为准。
+      var sameNumber = value !== undefined && value !== null && _value !== "" && Number(value) === Number(_value);
+      if (sameNumber) {
+        // 只同步「已提交值」，不动正在编辑的文本
+        setLastValue(_value);
+      } else if (value !== undefined && value !== null) {
         var newValue = typeof value === "number" ? "".concat(value) : value === null || value === void 0 ? void 0 : value.toString();
         setValue(newValue);
         setLastValue(newValue);
       } else {
-        // Clear only on initialization or when explicitly set to undefined externally
+        // Clear only on initialization or when explicitly set to undefined/null externally
         setValue("");
         setLastValue("");
       }
     }
+    // `_value` 是刻意不进依赖的：这个 effect 只该在**外部** value 变化时跑，
+    // 把它加进来会让每次键入都重跑一遍，等于绕过上面那个 prevValueRef 判断
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [value]);
   useEffect(function () {
     getRef === null || getRef === void 0 || getRef(ref.current);

package/es/components/Pagination/index.module.scss

@@ -95,7 +95,8 @@
           border-color: var(--vita-primary, #1890ff);
 
           > a {
-            color: #ffffff;
+            // 同 TabBar：主色实底上的前景色走配对令牌
+            color: var(--vita-primary-foreground);
           }
         }
 

package/es/components/Panel/ListPanel/_components/ColumnMgt/index.module.scss

@@ -10,7 +10,8 @@
       font-size: 12px;
       font-weight: normal;
 
-      color: var(--vita-subtle-foreground);
+      // 说明文字，不是占位符
+      color: var(--vita-muted-foreground);
     }
   }
 

package/es/components/SecondConf/index.module.scss

@@ -29,7 +29,9 @@
 
       .text {
         font-size: 16px;
-        color: var(--vita-subtle-foreground);
+        // 二次确认的正文，是这个弹窗里唯一要读的内容，不能用占位档。
+        // 与上面 .title 的层级差已经由 20px/bold 对 16px/normal 拉开了
+        color: var(--vita-muted-foreground);
       }
     }
   }

package/es/components/TabBar/index.module.scss

@@ -51,7 +51,10 @@
     &.active {
       background: var(--vita-primary);
 
-      color: #fff;
+      // 压在主色实底上的前景色走配对令牌，不要写死白：--vita-primary 是可配置的，
+      // 消费方把它换成近白的中性色时（shadcn 那种 primary/primary-foreground 配法），
+      // 写死的白就是白压白。默认值仍是 #ffffff，彩色品牌色的消费方不受影响
+      color: var(--vita-primary-foreground);
 
       z-index: 2;
     }

package/es/styles/antd-overload.scss

@@ -127,7 +127,14 @@ textarea,
     line-height: 1.4;
     text-transform: uppercase;
 
-    color: var(--vita-subtle-foreground);
+    // 注释写的就是 muted，值却落在 subtle —— 那一档是「占位 / 禁用文字」，
+    // 浅色下 #a1a1aa 压白只有 2.6:1。这是分组导航的标题，是要被读的内容，
+    // 而且 11px 粗体在 WCAG 里仍按正文算（大字号要 18.66px 粗体起），得够 4.5:1。
+    // muted(#71717a) 约 4.8:1，字号与字重维持不变。
+    //
+    // 同一类错在 tokens.ts 的 colorTextTertiary 上刚修过一次：可读的归 muted，
+    // 只有占位/禁用留在 subtle。这里是被本文件的单类选择器盖掉的第二处。
+    color: var(--vita-muted-foreground);
   }
 
   // Items within a group use more restrained left-aligned indentation (closer to CF)
@@ -193,3 +200,22 @@ textarea,
 .ant-modal-mask {
   pointer-events: auto !important;
 }
+
+// =============================================================
+// Alert 圆角：补 antd 没注入的那个变量
+//
+// antd 的 Alert 样式写的是 `border-radius: var(--ant-alert-border-radius)`，但在
+// CSS-var 模式下它**从不注入**这个变量 —— 实测该变量读出来是「未定义」，
+// 于是圆角回退成 0，四角是直的。
+//
+// 走组件令牌修不了：`Alert: { borderRadiusLG }` 注入的是 `--ant-border-radius-lg`
+// （Alert 一次都没引用），改成 `borderRadius` 也一样不生成该变量（两种都实测过）。
+// 对照组是 Table —— 它的 `--ant-table-border-radius` 同样未定义，但圆角正常 8px，
+// 因为 Table 的圆角来自本库自己的 scss，不依赖 antd 那条规则。
+//
+// 所以只能在样式层直接给。`.ant-alert-banner` 自带 `border-radius: 0`，
+// 且选择器更具体，通栏提示条不受影响。
+// =============================================================
+.ant-alert {
+  border-radius: var(--vita-radius);
+}

package/es/styles/tokens.js

@@ -114,7 +114,16 @@ export var toAntdTheme = function toAntdTheme(options) {
     colorInfo: primary,
     colorText: t.foreground,
     colorTextSecondary: t.mutedForeground,
-    colorTextTertiary: t.subtleForeground,
+    // antd 有四档文字色，本套令牌只有三档，压缩时分界线要放对：
+    // tertiary 在 antd 里是**描述性的可读文字**（面包屑、表单 extra、Descriptions 的
+    // 标签都吃它），quaternary 才是占位与禁用。原来两档都指向 subtleForeground，
+    // 于是面包屑拿到了占位级的对比度 —— 浅色下 #a1a1aa 压白只有 2.56:1，
+    // 14px 正文按 WCAG AA 要 4.5:1，连大字号的 3:1 都不到（消费方实测）。
+    //
+    // 压深 subtleForeground 治不了：要够 4.5:1 得到 #767676，那已经和
+    // mutedForeground(#71717a, 4.83:1) 几乎同色，第三档等于不存在。
+    // 所以按语义分流 —— 可读的归 muted，只有占位/禁用留在 subtle。
+    colorTextTertiary: t.mutedForeground,
     colorTextQuaternary: t.subtleForeground,
     colorBgContainer: t.surface,
     colorBgElevated: t.surface,

package/es/styles/tokens.json

@@ -27,7 +27,7 @@
     "hover": "#f4f4f5",
     "success": "#16a34a",
     "warning": "#f59e0b",
-    "error": "#ef4444",
+    "error": "#dc2626",
     "shadow1": "0 1px 2px 0 rgba(9, 9, 11, 0.05)",
     "shadow2": "0 4px 6px -1px rgba(9, 9, 11, 0.08), 0 2px 4px -2px rgba(9, 9, 11, 0.06)",
     "shadow3": "0 10px 15px -3px rgba(9, 9, 11, 0.1), 0 4px 6px -4px rgba(9, 9, 11, 0.08)"

package/es/styles/tokens.scss

@@ -33,7 +33,7 @@
   --vita-hover: #f4f4f5; // 行 / 项 hover 背景
   --vita-success: #16a34a;
   --vita-warning: #f59e0b;
-  --vita-error: #ef4444;
+  --vita-error: #dc2626;
   --vita-shadow-1: 0 1px 2px 0 rgba(9, 9, 11, 0.05); // 浮层阴影 - 弱
   --vita-shadow-2: 0 4px 6px -1px rgba(9, 9, 11, 0.08), 0 2px 4px -2px rgba(9, 9, 11, 0.06); // 浮层阴影 - 中
   --vita-shadow-3: 0 10px 15px -3px rgba(9, 9, 11, 0.1), 0 4px 6px -4px rgba(9, 9, 11, 0.08); // 浮层阴影 - 强

package/lib/components/Chat/ChatHistory/_components/HistoryGroup/index.module.scss

@@ -8,7 +8,8 @@
 
     font-size: 14px;
     font-weight: bold;
-    color: var(--vita-subtle-foreground);
+    // 分组标题（「今天」「近 7 天」），与侧栏菜单的分组标题同一件事
+    color: var(--vita-muted-foreground);
 
     cursor: default;
   }

package/lib/components/Chat/ChatList/_components/Assistant/AssistantItem/_components/QuoteList/index.module.scss

@@ -108,7 +108,8 @@
       transition: background-color 0.3s, color 0.3s;
 
       &:hover {
-        color: #fff;
+        // 同 TabBar：主色实底上的前景色走配对令牌
+        color: var(--vita-primary-foreground);
 
         background-color: var(--vita-primary);
       }

package/lib/components/FormItem/FormInput/FormInputNumber/index.d.ts

@@ -2,7 +2,23 @@ import { ItemContainerProps } from "../../ItemContainer";
 import { InputNumberProps } from "../../../Input/Number";
 import React from "react";
 export interface FormInputNumberProps extends ItemContainerProps {
-    componentProps?: InputNumberProps;
+    /**
+     * `onChange` 的签名比基础组件宽：作为**表单字段**，默认交出的是
+     * `number | null`（见 Bridge 的注释）。写这个回调的人拿到的与表单拿到的
+     * 是同一个值。
+     */
+    componentProps?: Omit<InputNumberProps, "onChange"> & {
+        onChange?: (value: string | number | null) => void;
+    };
+    /**
+     * 交给表单的是字符串而不是数字。默认 `false`。
+     *
+     * 只有真的要处理**超出 IEEE754 安全范围的大数**（订单号、雪花 ID）时才打开
+     * —— 那种值转成 number 会丢精度，必须一路以字符串传递。
+     *
+     * 2.5.0 之前没有这个开关，行为固定等同于 `stringMode`（见下方 Bridge 注释）。
+     */
+    stringMode?: boolean;
 }
 declare const FormInputNumber: React.FC<FormInputNumberProps>;
 export default FormInputNumber;

package/lib/components/FormItem/FormInput/FormInputNumber/index.js

@@ -9,22 +9,83 @@ var _Input = _interopRequireDefault(require("../../../Input"));
 var _react = _interopRequireDefault(require("react"));
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+// value / onChange 要重新声明：`InputNumberProps` 上那两个是**基础组件**的
+// 契约（字符串进、字符串出），而这里收的是**表单值**，可以是数字或 null
+
+/**
+ * 夹在 `Form.Item` 与 `Input.Number` 之间，**把字符串换成数字再交给表单**。
+ *
+ * 为什么需要它：`Input.Number` 内部以字符串保存（底层 `stringMode`，为的是不
+ * 丢大数精度），`onChange` 交出的也是字符串。这对一个**基础输入组件**是合理
+ * 的，但对一个叫 INPUTNUMBER 的**表单字段**不合理 —— 表单收上去的值会直接
+ * 进请求体，而后端字段多半是整数：
+ *
+ * ```
+ * 422  invalid type: string "2", expected i32
+ * ```
+ *
+ * 这个坑平时看不见：没动过的字段，值来自详情接口、本来就是数字，原样发回去
+ * 没事；**只有用户真的改了那一格**才会变成字符串。现象是「我明明只改了个
+ * 数字却保存失败」，而且报错在服务端，前端一行日志都没有。
+ *
+ * 转换只在**往上交**的方向做；`Input.Number` 内部仍然是字符串，所以正在敲的
+ * "1." / "1.50" 不会被改写（配套改动见 `Input/Number` 里的 sameNumber 判断）。
+ */
+const Bridge = props => {
+  const {
+    value,
+    onChange,
+    componentOnChange,
+    stringMode,
+    ...rest
+  } = props;
+  const emit = next => {
+    onChange?.(next);
+    componentOnChange?.(next);
+  };
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_Input.default.Number, {
+    ...rest,
+    value: value,
+    onChange: text => {
+      if (stringMode) {
+        emit(text);
+        return;
+      }
+
+      // 空 → null 而不是 ""：语义是「没填」，不是「填了个空字符串」。
+      // 后端 `Option<i32>` 收得下 null，收不下 ""
+      if (text === "" || text === null || text === undefined) {
+        emit(null);
+        return;
+      }
+      const num = Number(text);
+      // 转不动就原样交出去（用户可能正敲到 "-" 或 "1e" 这种中间态）。
+      // 硬转成 NaN 会让表单里躺着一个既非数字也非空的值
+      emit(Number.isFinite(num) ? num : text);
+    }
+  });
+};
 const FormInputNumber = props => {
   const {
     componentProps = {},
     className: itemClassName,
     disabled,
+    stringMode,
     ...formItemProps
   } = props;
+  // onChange 必须摘出来，理由见 BridgeProps.componentOnChange
   const {
     placeholder,
+    onChange: componentOnChange,
     ...inputConfig
   } = componentProps;
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_ItemContainer.default, {
     ...formItemProps,
     className: `${itemClassName ?? ""}`,
-    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_Input.default.Number, {
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(Bridge, {
       ...inputConfig,
+      componentOnChange: componentOnChange,
+      stringMode: stringMode,
       disabled: inputConfig.disabled ?? disabled,
       placeholder: placeholder ?? "请输入"
     })

package/lib/components/Input/Number/index.d.ts

@@ -3,7 +3,11 @@ import React from "react";
 export interface InputNumberProps extends Omit<AntdInputNumberProps, "ref" | "onChange" | "value"> {
     getRef?: (ref: HTMLInputElement | null) => void;
     onChange?: (value: string) => void;
-    value?: string;
+    /**
+     * 受控值。本组件内部**始终以字符串保存**（底层开了 antd 的 `stringMode`，
+     * 为的是不丢大数精度），但外部传数字进来也接得住。
+     */
+    value?: string | number | null;
     allowClear?: boolean;
     wrapperClassName?: string;
 }

package/lib/components/Input/Number/index.js

@@ -50,16 +50,33 @@ const InputNumber = props => {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
       prevValueRef.current = value;
-      if (value !== undefined) {
+
+      // 数值相等就不要回写文本。
+      //
+      // 上游把值转成数字之后（`FormItem` 的 INPUTNUMBER 默认就会转），一个
+      // 回环会打回来：输入 "1." → onChange → 表单存 1 → value={1} 传回来。
+      // 若照单全收地写成 "1"，用户刚敲的小数点当场消失、光标还会跳到末尾，
+      // "1.50" 也会被改写成 "1.5"。
+      //
+      // 判据用**数值相等**而不是字符串相等：这几种写法（"1." / "1.50" / "+1"）
+      // 表示的是同一个数，此时以用户正在敲的那份文本为准。
+      const sameNumber = value !== undefined && value !== null && _value !== "" && Number(value) === Number(_value);
+      if (sameNumber) {
+        // 只同步「已提交值」，不动正在编辑的文本
+        setLastValue(_value);
+      } else if (value !== undefined && value !== null) {
         const newValue = typeof value === "number" ? `${value}` : value?.toString();
         setValue(newValue);
         setLastValue(newValue);
       } else {
-        // Clear only on initialization or when explicitly set to undefined externally
+        // Clear only on initialization or when explicitly set to undefined/null externally
         setValue("");
         setLastValue("");
       }
     }
+    // `_value` 是刻意不进依赖的：这个 effect 只该在**外部** value 变化时跑，
+    // 把它加进来会让每次键入都重跑一遍，等于绕过上面那个 prevValueRef 判断
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [value]);
   (0, _react.useEffect)(() => {
     getRef?.(ref.current);

package/lib/components/Pagination/index.module.scss

@@ -95,7 +95,8 @@
           border-color: var(--vita-primary, #1890ff);
 
           > a {
-            color: #ffffff;
+            // 同 TabBar：主色实底上的前景色走配对令牌
+            color: var(--vita-primary-foreground);
           }
         }
 

package/lib/components/Panel/ListPanel/_components/ColumnMgt/index.module.scss

@@ -10,7 +10,8 @@
       font-size: 12px;
       font-weight: normal;
 
-      color: var(--vita-subtle-foreground);
+      // 说明文字，不是占位符
+      color: var(--vita-muted-foreground);
     }
   }
 

package/lib/components/SecondConf/index.module.scss

@@ -29,7 +29,9 @@
 
       .text {
         font-size: 16px;
-        color: var(--vita-subtle-foreground);
+        // 二次确认的正文，是这个弹窗里唯一要读的内容，不能用占位档。
+        // 与上面 .title 的层级差已经由 20px/bold 对 16px/normal 拉开了
+        color: var(--vita-muted-foreground);
       }
     }
   }

package/lib/components/TabBar/index.module.scss

@@ -51,7 +51,10 @@
     &.active {
       background: var(--vita-primary);
 
-      color: #fff;
+      // 压在主色实底上的前景色走配对令牌，不要写死白：--vita-primary 是可配置的，
+      // 消费方把它换成近白的中性色时（shadcn 那种 primary/primary-foreground 配法），
+      // 写死的白就是白压白。默认值仍是 #ffffff，彩色品牌色的消费方不受影响
+      color: var(--vita-primary-foreground);
 
       z-index: 2;
     }

package/lib/styles/antd-overload.scss

@@ -127,7 +127,14 @@ textarea,
     line-height: 1.4;
     text-transform: uppercase;
 
-    color: var(--vita-subtle-foreground);
+    // 注释写的就是 muted，值却落在 subtle —— 那一档是「占位 / 禁用文字」，
+    // 浅色下 #a1a1aa 压白只有 2.6:1。这是分组导航的标题，是要被读的内容，
+    // 而且 11px 粗体在 WCAG 里仍按正文算（大字号要 18.66px 粗体起），得够 4.5:1。
+    // muted(#71717a) 约 4.8:1，字号与字重维持不变。
+    //
+    // 同一类错在 tokens.ts 的 colorTextTertiary 上刚修过一次：可读的归 muted，
+    // 只有占位/禁用留在 subtle。这里是被本文件的单类选择器盖掉的第二处。
+    color: var(--vita-muted-foreground);
   }
 
   // Items within a group use more restrained left-aligned indentation (closer to CF)
@@ -193,3 +200,22 @@ textarea,
 .ant-modal-mask {
   pointer-events: auto !important;
 }
+
+// =============================================================
+// Alert 圆角：补 antd 没注入的那个变量
+//
+// antd 的 Alert 样式写的是 `border-radius: var(--ant-alert-border-radius)`，但在
+// CSS-var 模式下它**从不注入**这个变量 —— 实测该变量读出来是「未定义」，
+// 于是圆角回退成 0，四角是直的。
+//
+// 走组件令牌修不了：`Alert: { borderRadiusLG }` 注入的是 `--ant-border-radius-lg`
+// （Alert 一次都没引用），改成 `borderRadius` 也一样不生成该变量（两种都实测过）。
+// 对照组是 Table —— 它的 `--ant-table-border-radius` 同样未定义，但圆角正常 8px，
+// 因为 Table 的圆角来自本库自己的 scss，不依赖 antd 那条规则。
+//
+// 所以只能在样式层直接给。`.ant-alert-banner` 自带 `border-radius: 0`，
+// 且选择器更具体，通栏提示条不受影响。
+// =============================================================
+.ant-alert {
+  border-radius: var(--vita-radius);
+}

package/lib/styles/tokens.js

@@ -99,7 +99,16 @@ const toAntdTheme = options => {
     colorInfo: primary,
     colorText: t.foreground,
     colorTextSecondary: t.mutedForeground,
-    colorTextTertiary: t.subtleForeground,
+    // antd 有四档文字色，本套令牌只有三档，压缩时分界线要放对：
+    // tertiary 在 antd 里是**描述性的可读文字**（面包屑、表单 extra、Descriptions 的
+    // 标签都吃它），quaternary 才是占位与禁用。原来两档都指向 subtleForeground，
+    // 于是面包屑拿到了占位级的对比度 —— 浅色下 #a1a1aa 压白只有 2.56:1，
+    // 14px 正文按 WCAG AA 要 4.5:1，连大字号的 3:1 都不到（消费方实测）。
+    //
+    // 压深 subtleForeground 治不了：要够 4.5:1 得到 #767676，那已经和
+    // mutedForeground(#71717a, 4.83:1) 几乎同色，第三档等于不存在。
+    // 所以按语义分流 —— 可读的归 muted，只有占位/禁用留在 subtle。
+    colorTextTertiary: t.mutedForeground,
     colorTextQuaternary: t.subtleForeground,
     colorBgContainer: t.surface,
     colorBgElevated: t.surface,

package/lib/styles/tokens.json

@@ -27,7 +27,7 @@
     "hover": "#f4f4f5",
     "success": "#16a34a",
     "warning": "#f59e0b",
-    "error": "#ef4444",
+    "error": "#dc2626",
     "shadow1": "0 1px 2px 0 rgba(9, 9, 11, 0.05)",
     "shadow2": "0 4px 6px -1px rgba(9, 9, 11, 0.08), 0 2px 4px -2px rgba(9, 9, 11, 0.06)",
     "shadow3": "0 10px 15px -3px rgba(9, 9, 11, 0.1), 0 4px 6px -4px rgba(9, 9, 11, 0.08)"

package/lib/styles/tokens.scss

@@ -33,7 +33,7 @@
   --vita-hover: #f4f4f5; // 行 / 项 hover 背景
   --vita-success: #16a34a;
   --vita-warning: #f59e0b;
-  --vita-error: #ef4444;
+  --vita-error: #dc2626;
   --vita-shadow-1: 0 1px 2px 0 rgba(9, 9, 11, 0.05); // 浮层阴影 - 弱
   --vita-shadow-2: 0 4px 6px -1px rgba(9, 9, 11, 0.08), 0 2px 4px -2px rgba(9, 9, 11, 0.06); // 浮层阴影 - 中
   --vita-shadow-3: 0 10px 15px -3px rgba(9, 9, 11, 0.1), 0 4px 6px -4px rgba(9, 9, 11, 0.08); // 浮层阴影 - 强

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hsu-react/ui",
-  "version": "2.4.8",
+  "version": "2.5.0",
   "description": "一套基于 React + Ant Design 的中后台业务组件库",
   "license": "MIT",
   "type": "module",

package/src/components/Chat/ChatHistory/_components/HistoryGroup/index.module.scss

@@ -8,7 +8,8 @@
 
     font-size: 14px;
     font-weight: bold;
-    color: var(--vita-subtle-foreground);
+    // 分组标题（「今天」「近 7 天」），与侧栏菜单的分组标题同一件事
+    color: var(--vita-muted-foreground);
 
     cursor: default;
   }

package/src/components/Chat/ChatList/_components/Assistant/AssistantItem/_components/QuoteList/index.module.scss

@@ -108,7 +108,8 @@
       transition: background-color 0.3s, color 0.3s;
 
       &:hover {
-        color: #fff;
+        // 同 TabBar：主色实底上的前景色走配对令牌
+        color: var(--vita-primary-foreground);
 
         background-color: var(--vita-primary);
       }

package/src/components/FormItem/FormInput/FormInputNumber/index.tsx

@@ -5,22 +5,114 @@ import { InputNumberProps } from "../../../Input/Number";
 import React from "react";
 
 export interface FormInputNumberProps extends ItemContainerProps {
-  componentProps?: InputNumberProps;
+  /**
+   * `onChange` 的签名比基础组件宽：作为**表单字段**，默认交出的是
+   * `number | null`（见 Bridge 的注释）。写这个回调的人拿到的与表单拿到的
+   * 是同一个值。
+   */
+  componentProps?: Omit<InputNumberProps, "onChange"> & {
+    onChange?: (value: string | number | null) => void;
+  };
+  /**
+   * 交给表单的是字符串而不是数字。默认 `false`。
+   *
+   * 只有真的要处理**超出 IEEE754 安全范围的大数**（订单号、雪花 ID）时才打开
+   * —— 那种值转成 number 会丢精度，必须一路以字符串传递。
+   *
+   * 2.5.0 之前没有这个开关，行为固定等同于 `stringMode`（见下方 Bridge 注释）。
+   */
+  stringMode?: boolean;
 }
 
+// value / onChange 要重新声明：`InputNumberProps` 上那两个是**基础组件**的
+// 契约（字符串进、字符串出），而这里收的是**表单值**，可以是数字或 null
+type BridgeProps = Omit<InputNumberProps, "value" | "onChange"> & {
+  /** antd Form.Item 注入 */
+  value?: string | number | null;
+  /** antd Form.Item 注入 */
+  onChange?: (value: string | number | null) => void;
+  /**
+   * 使用方写在 `componentProps.onChange` 里的那个回调。
+   *
+   * 单独接出来、不跟着 `componentProps` 一起展开：展开的话它会盖掉
+   * Form.Item 注入的那个 onChange，字段值就再也传不到表单里了。
+   * 它拿到的与表单拿到的**是同一个值**（默认已转成数字）。
+   */
+  componentOnChange?: (value: string | number | null) => void;
+  stringMode?: boolean;
+};
+
+/**
+ * 夹在 `Form.Item` 与 `Input.Number` 之间，**把字符串换成数字再交给表单**。
+ *
+ * 为什么需要它：`Input.Number` 内部以字符串保存（底层 `stringMode`，为的是不
+ * 丢大数精度），`onChange` 交出的也是字符串。这对一个**基础输入组件**是合理
+ * 的，但对一个叫 INPUTNUMBER 的**表单字段**不合理 —— 表单收上去的值会直接
+ * 进请求体，而后端字段多半是整数：
+ *
+ * ```
+ * 422  invalid type: string "2", expected i32
+ * ```
+ *
+ * 这个坑平时看不见：没动过的字段，值来自详情接口、本来就是数字，原样发回去
+ * 没事；**只有用户真的改了那一格**才会变成字符串。现象是「我明明只改了个
+ * 数字却保存失败」，而且报错在服务端，前端一行日志都没有。
+ *
+ * 转换只在**往上交**的方向做；`Input.Number` 内部仍然是字符串，所以正在敲的
+ * "1." / "1.50" 不会被改写（配套改动见 `Input/Number` 里的 sameNumber 判断）。
+ */
+const Bridge: React.FC<BridgeProps> = (props) => {
+  const { value, onChange, componentOnChange, stringMode, ...rest } = props;
+
+  const emit = (next: string | number | null) => {
+    onChange?.(next);
+    componentOnChange?.(next);
+  };
+
+  return (
+    <Input.Number
+      {...rest}
+      value={value}
+      onChange={(text) => {
+        if (stringMode) {
+          emit(text);
+          return;
+        }
+
+        // 空 → null 而不是 ""：语义是「没填」，不是「填了个空字符串」。
+        // 后端 `Option<i32>` 收得下 null，收不下 ""
+        if (text === "" || text === null || text === undefined) {
+          emit(null);
+          return;
+        }
+
+        const num = Number(text);
+        // 转不动就原样交出去（用户可能正敲到 "-" 或 "1e" 这种中间态）。
+        // 硬转成 NaN 会让表单里躺着一个既非数字也非空的值
+        emit(Number.isFinite(num) ? num : text);
+      }}
+    />
+  );
+};
+
 const FormInputNumber: React.FC<FormInputNumberProps> = (props) => {
   const {
     componentProps = {},
     className: itemClassName,
     disabled,
+    stringMode,
     ...formItemProps
   } = props;
-  const { placeholder, ...inputConfig } = componentProps;
+  // onChange 必须摘出来，理由见 BridgeProps.componentOnChange
+  const { placeholder, onChange: componentOnChange, ...inputConfig } =
+    componentProps;
 
   return (
     <ItemContainer {...formItemProps} className={`${itemClassName ?? ""}`}>
-      <Input.Number
+      <Bridge
         {...inputConfig}
+        componentOnChange={componentOnChange}
+        stringMode={stringMode}
         disabled={inputConfig.disabled ?? disabled}
         placeholder={placeholder ?? "请输入"}
       />

package/src/components/FormItem/index.md

@@ -93,6 +93,22 @@ export default () => (
 );
 ```
 
+> **`2.5.0` 起，`INPUTNUMBER` 交给表单的是 `number | null`**（此前是字符串）。
+>
+> 表单值往往原样进请求体，而后端字段多半是整数，交字符串上去会被强类型服务端
+> 拒掉（Rust/serde 会回 `invalid type: string "2", expected i32`）。这个问题
+> 平时看不见：**没动过的字段**值来自详情接口、本来就是数字，只有用户真的改了
+> 那一格才会变成字符串 —— 现象是「我只改了个数字却保存失败」。
+>
+> - 空值交出的是 `null`（「没填」），不是 `""`。
+> - 敲到一半的中间态（`-`、`1e`）原样交出，不会变成 `NaN`。
+> - 正在输入的文本不会被回写打断，`1.` / `1.50` 都保得住。
+> - 确实需要字符串（大数不丢精度）时，加 `stringMode`：
+>
+> ```tsx
+> <FormItem type="INPUTNUMBER" name="orderNo" label="订单号" stringMode />
+> ```
+
 ## 范围输入
 
 ```tsx

package/src/components/Input/Number/index.tsx

@@ -17,7 +17,11 @@ export interface InputNumberProps extends Omit<
 > {
   getRef?: (ref: HTMLInputElement | null) => void;
   onChange?: (value: string) => void;
-  value?: string;
+  /**
+   * 受控值。本组件内部**始终以字符串保存**（底层开了 antd 的 `stringMode`，
+   * 为的是不丢大数精度），但外部传数字进来也接得住。
+   */
+  value?: string | number | null;
   allowClear?: boolean;
   wrapperClassName?: string;
 }
@@ -76,17 +80,38 @@ const InputNumber: React.FC<InputNumberProps> = (props) => {
     if (prevValueRef.current !== value) {
       prevValueRef.current = value;
 
-      if (value !== undefined) {
+      // 数值相等就不要回写文本。
+      //
+      // 上游把值转成数字之后（`FormItem` 的 INPUTNUMBER 默认就会转），一个
+      // 回环会打回来：输入 "1." → onChange → 表单存 1 → value={1} 传回来。
+      // 若照单全收地写成 "1"，用户刚敲的小数点当场消失、光标还会跳到末尾，
+      // "1.50" 也会被改写成 "1.5"。
+      //
+      // 判据用**数值相等**而不是字符串相等：这几种写法（"1." / "1.50" / "+1"）
+      // 表示的是同一个数，此时以用户正在敲的那份文本为准。
+      const sameNumber =
+        value !== undefined &&
+        value !== null &&
+        _value !== "" &&
+        Number(value) === Number(_value);
+
+      if (sameNumber) {
+        // 只同步「已提交值」，不动正在编辑的文本
+        setLastValue(_value);
+      } else if (value !== undefined && value !== null) {
         const newValue =
           typeof value === "number" ? `${value}` : value?.toString();
         setValue(newValue);
         setLastValue(newValue);
       } else {
-        // Clear only on initialization or when explicitly set to undefined externally
+        // Clear only on initialization or when explicitly set to undefined/null externally
         setValue("");
         setLastValue("");
       }
     }
+    // `_value` 是刻意不进依赖的：这个 effect 只该在**外部** value 变化时跑，
+    // 把它加进来会让每次键入都重跑一遍，等于绕过上面那个 prevValueRef 判断
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [value]);
 
   useEffect(() => {

package/src/components/Input/index.md

@@ -36,7 +36,15 @@ export default () => {
 
 ## 数字输入框
 
-数字输入框，`onChange` 返回字符串，内置 `allowClear`、`controls={false}` 与 `stringMode`。
+数字输入框，`onChange` 返回**字符串**，内置 `allowClear`、`controls={false}` 与 `stringMode`。
+
+返回字符串是刻意的：`stringMode` 让超出 IEEE754 安全范围的大数（订单号、雪花 ID）
+不丢精度，而转成 `number` 就丢了。
+
+> **注意**：作为**表单字段**用时（`FormItem type="INPUTNUMBER"`）行为不同 ——
+> 自 `2.5.0` 起它交给表单的是 `number | null`。表单值通常会直接进请求体，
+> 而后端字段多半是整数，交字符串上去会被强类型服务端拒掉。
+> 详见 [FormItem 的 INPUTNUMBER](/components/form-item)。
 
 ```tsx
 import React from "react";

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

@@ -95,7 +95,8 @@
           border-color: var(--vita-primary, #1890ff);
 
           > a {
-            color: #ffffff;
+            // 同 TabBar：主色实底上的前景色走配对令牌
+            color: var(--vita-primary-foreground);
           }
         }
 

package/src/components/Panel/ListPanel/_components/ColumnMgt/index.module.scss

@@ -10,7 +10,8 @@
       font-size: 12px;
       font-weight: normal;
 
-      color: var(--vita-subtle-foreground);
+      // 说明文字，不是占位符
+      color: var(--vita-muted-foreground);
     }
   }
 

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

@@ -29,7 +29,9 @@
 
       .text {
         font-size: 16px;
-        color: var(--vita-subtle-foreground);
+        // 二次确认的正文，是这个弹窗里唯一要读的内容，不能用占位档。
+        // 与上面 .title 的层级差已经由 20px/bold 对 16px/normal 拉开了
+        color: var(--vita-muted-foreground);
       }
     }
   }

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

@@ -51,7 +51,10 @@
     &.active {
       background: var(--vita-primary);
 
-      color: #fff;
+      // 压在主色实底上的前景色走配对令牌，不要写死白：--vita-primary 是可配置的，
+      // 消费方把它换成近白的中性色时（shadcn 那种 primary/primary-foreground 配法），
+      // 写死的白就是白压白。默认值仍是 #ffffff，彩色品牌色的消费方不受影响
+      color: var(--vita-primary-foreground);
 
       z-index: 2;
     }

package/src/styles/antd-overload.scss

@@ -127,7 +127,14 @@ textarea,
     line-height: 1.4;
     text-transform: uppercase;
 
-    color: var(--vita-subtle-foreground);
+    // 注释写的就是 muted，值却落在 subtle —— 那一档是「占位 / 禁用文字」，
+    // 浅色下 #a1a1aa 压白只有 2.6:1。这是分组导航的标题，是要被读的内容，
+    // 而且 11px 粗体在 WCAG 里仍按正文算（大字号要 18.66px 粗体起），得够 4.5:1。
+    // muted(#71717a) 约 4.8:1，字号与字重维持不变。
+    //
+    // 同一类错在 tokens.ts 的 colorTextTertiary 上刚修过一次：可读的归 muted，
+    // 只有占位/禁用留在 subtle。这里是被本文件的单类选择器盖掉的第二处。
+    color: var(--vita-muted-foreground);
   }
 
   // Items within a group use more restrained left-aligned indentation (closer to CF)
@@ -193,3 +200,22 @@ textarea,
 .ant-modal-mask {
   pointer-events: auto !important;
 }
+
+// =============================================================
+// Alert 圆角：补 antd 没注入的那个变量
+//
+// antd 的 Alert 样式写的是 `border-radius: var(--ant-alert-border-radius)`，但在
+// CSS-var 模式下它**从不注入**这个变量 —— 实测该变量读出来是「未定义」，
+// 于是圆角回退成 0，四角是直的。
+//
+// 走组件令牌修不了：`Alert: { borderRadiusLG }` 注入的是 `--ant-border-radius-lg`
+// （Alert 一次都没引用），改成 `borderRadius` 也一样不生成该变量（两种都实测过）。
+// 对照组是 Table —— 它的 `--ant-table-border-radius` 同样未定义，但圆角正常 8px，
+// 因为 Table 的圆角来自本库自己的 scss，不依赖 antd 那条规则。
+//
+// 所以只能在样式层直接给。`.ant-alert-banner` 自带 `border-radius: 0`，
+// 且选择器更具体，通栏提示条不受影响。
+// =============================================================
+.ant-alert {
+  border-radius: var(--vita-radius);
+}

package/src/styles/tokens.json

@@ -27,7 +27,7 @@
     "hover": "#f4f4f5",
     "success": "#16a34a",
     "warning": "#f59e0b",
-    "error": "#ef4444",
+    "error": "#dc2626",
     "shadow1": "0 1px 2px 0 rgba(9, 9, 11, 0.05)",
     "shadow2": "0 4px 6px -1px rgba(9, 9, 11, 0.08), 0 2px 4px -2px rgba(9, 9, 11, 0.06)",
     "shadow3": "0 10px 15px -3px rgba(9, 9, 11, 0.1), 0 4px 6px -4px rgba(9, 9, 11, 0.08)"

package/src/styles/tokens.scss

@@ -33,7 +33,7 @@
   --vita-hover: #f4f4f5; // 行 / 项 hover 背景
   --vita-success: #16a34a;
   --vita-warning: #f59e0b;
-  --vita-error: #ef4444;
+  --vita-error: #dc2626;
   --vita-shadow-1: 0 1px 2px 0 rgba(9, 9, 11, 0.05); // 浮层阴影 - 弱
   --vita-shadow-2: 0 4px 6px -1px rgba(9, 9, 11, 0.08), 0 2px 4px -2px rgba(9, 9, 11, 0.06); // 浮层阴影 - 中
   --vita-shadow-3: 0 10px 15px -3px rgba(9, 9, 11, 0.1), 0 4px 6px -4px rgba(9, 9, 11, 0.08); // 浮层阴影 - 强

package/src/styles/tokens.ts

@@ -145,7 +145,16 @@ export const toAntdTheme = (options?: {
 
     colorText: t.foreground,
     colorTextSecondary: t.mutedForeground,
-    colorTextTertiary: t.subtleForeground,
+    // antd 有四档文字色，本套令牌只有三档，压缩时分界线要放对：
+    // tertiary 在 antd 里是**描述性的可读文字**（面包屑、表单 extra、Descriptions 的
+    // 标签都吃它），quaternary 才是占位与禁用。原来两档都指向 subtleForeground，
+    // 于是面包屑拿到了占位级的对比度 —— 浅色下 #a1a1aa 压白只有 2.56:1，
+    // 14px 正文按 WCAG AA 要 4.5:1，连大字号的 3:1 都不到（消费方实测）。
+    //
+    // 压深 subtleForeground 治不了：要够 4.5:1 得到 #767676，那已经和
+    // mutedForeground(#71717a, 4.83:1) 几乎同色，第三档等于不存在。
+    // 所以按语义分流 —— 可读的归 muted，只有占位/禁用留在 subtle。
+    colorTextTertiary: t.mutedForeground,
     colorTextQuaternary: t.subtleForeground,
 
     colorBgContainer: t.surface,