@hsu-react/ui 0.0.1 → 0.0.3

package/src/components/Chart/index.md

@@ -8,10 +8,360 @@ title: Chart 图表
 
 # Chart 图表
 
-> `Chart` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 echarts 封装的图表集合，以 `Chart.Line`、`Chart.Bar`、`Chart.Pie` 等子组件形式提供常用图表，自动处理实例创建、容器自适应与销毁。
 
 ## 引入
 
 ```ts
 import { Chart } from "@hsu-react/ui";
 ```
+
+## 子组件一览
+
+`Chart` 提供以下子组件：
+
+| 子组件 | 说明 |
+| --- | --- |
+| Chart.Line | 折线图 |
+| Chart.Bar | 柱状图 |
+| Chart.Pie | 饼图（另含 `Chart.Pie.Three` 3D 饼图） |
+| Chart.Polar | 极坐标图 |
+| Chart.Gauge | 仪表盘 |
+| Chart.Sankey | 桑基图 |
+| Chart.Tree | 树图 |
+| Chart.Bubble | 气泡图 |
+| Chart.Heatmap | 热力图 |
+| Chart.Radar | 雷达图 |
+| Chart.Group | 组合图表（可在 `Line`/`Bar`/`Pie` 间切换） |
+| Chart.Common | 通用图表，直接透传 echarts 的 `EChartsOption` |
+
+> 以下示例均放在固定高度的容器中（echarts 需要有尺寸的容器才能渲染）。
+
+## 折线图
+
+以 `Chart.Line` 为例，传入 `xAxisData` 与 `seriesData` 即可渲染折线图：
+
+```tsx
+import React from "react";
+import { Chart } from "@hsu-react/ui";
+
+export default () => (
+  <Chart.Line
+    style={{ height: 300 }}
+    legendData={["销量"]}
+    xAxisData={["周一", "周二", "周三", "周四", "周五", "周六", "周日"]}
+    seriesData={[120, 200, 150, 80, 70, 110, 130]}
+  />
+);
+```
+
+## 柱状图
+
+柱状图，与 `Chart.Line` 用法一致，传入 `xAxisData` 与 `seriesData`。
+
+```tsx
+import React from "react";
+import { Chart } from "@hsu-react/ui";
+
+export default () => (
+  <div style={{ height: 280 }}>
+    <Chart.Bar
+      legendData={["销量"]}
+      xAxisData={["一月", "二月", "三月", "四月", "五月", "六月"]}
+      seriesData={[120, 200, 150, 80, 70, 110]}
+    />
+  </div>
+);
+```
+
+## 饼图
+
+饼图，`seriesData` 为 `{ name, value }` 对象数组。
+
+```tsx
+import React from "react";
+import { Chart } from "@hsu-react/ui";
+
+export default () => (
+  <div style={{ height: 280 }}>
+    <Chart.Pie
+      chartTitle="访问来源"
+      seriesData={[
+        { name: "直接访问", value: 335 },
+        { name: "搜索引擎", value: 234 },
+        { name: "邮件营销", value: 154 },
+        { name: "联盟广告", value: 135 },
+      ]}
+    />
+  </div>
+);
+```
+
+## 雷达图
+
+雷达图，`indicators` 定义各维度（`{ name, max }`），`data` 为对应数值数组。
+
+```tsx
+import React from "react";
+import { Chart } from "@hsu-react/ui";
+
+export default () => (
+  <div style={{ height: 280 }}>
+    <Chart.Radar
+      name="能力评估"
+      indicators={[
+        { name: "研发", max: 100 },
+        { name: "测试", max: 100 },
+        { name: "运维", max: 100 },
+        { name: "设计", max: 100 },
+        { name: "产品", max: 100 },
+      ]}
+      data={[80, 70, 65, 90, 75]}
+    />
+  </div>
+);
+```
+
+## 仪表盘
+
+仪表盘，`seriesData` 为 `{ value, name }` 数组（默认量程 0~100）。
+
+```tsx
+import React from "react";
+import { Chart } from "@hsu-react/ui";
+
+export default () => (
+  <div style={{ height: 280 }}>
+    <Chart.Gauge seriesData={[{ value: 72, name: "完成率" }]} />
+  </div>
+);
+```
+
+## 桑基图
+
+桑基图，`seriesData` 为节点 `{ name }` 数组，`seriesLinks` 为连线 `{ source, target }` 数组。
+
+```tsx
+import React from "react";
+import { Chart } from "@hsu-react/ui";
+
+export default () => (
+  <div style={{ height: 280 }}>
+    <Chart.Sankey
+      seriesData={[
+        { name: "访问" },
+        { name: "注册" },
+        { name: "下单" },
+        { name: "复购" },
+      ]}
+      seriesLinks={[
+        { source: "访问", target: "注册" },
+        { source: "注册", target: "下单" },
+        { source: "下单", target: "复购" },
+      ]}
+    />
+  </div>
+);
+```
+
+## 热力图
+
+热力图，`data` 为 `[xIndex, yIndex, value]` 数组，配合 `xAxisData`、`yAxisData` 类目。
+
+```tsx
+import React from "react";
+import { Chart } from "@hsu-react/ui";
+
+export default () => (
+  <div style={{ height: 280 }}>
+    <Chart.Heatmap
+      xAxisData={["周一", "周二", "周三"]}
+      yAxisData={["上午", "下午", "晚上"]}
+      data={[
+        [0, 0, 5],
+        [0, 1, 7],
+        [0, 2, 3],
+        [1, 0, 8],
+        [1, 1, 2],
+        [1, 2, 6],
+        [2, 0, 4],
+        [2, 1, 9],
+        [2, 2, 1],
+      ]}
+    />
+  </div>
+);
+```
+
+## 气泡图
+
+气泡图，`data` 为 `{ name, value }` 数组，气泡大小随 `value` 自适应。
+
+```tsx
+import React from "react";
+import { Chart } from "@hsu-react/ui";
+
+export default () => (
+  <div style={{ height: 280 }}>
+    <Chart.Bubble
+      data={[
+        { name: "前端", value: 120 },
+        { name: "后端", value: 90 },
+        { name: "测试", value: 60 },
+        { name: "运维", value: 40 },
+        { name: "设计", value: 30 },
+      ]}
+    />
+  </div>
+);
+```
+
+## 树图
+
+树图，`seriesData` 为带 `children` 的层级节点数组（节点需含 `value` 字段）。
+
+```tsx
+import React from "react";
+import { Chart } from "@hsu-react/ui";
+
+export default () => (
+  <div style={{ height: 280 }}>
+    <Chart.Tree
+      seriesData={[
+        {
+          name: "根节点",
+          value: 1,
+          children: [
+            {
+              name: "分支 A",
+              value: 1,
+              children: [
+                { name: "叶子 1", value: 1 },
+                { name: "叶子 2", value: 1 },
+              ],
+            },
+            { name: "分支 B", value: 1 },
+          ],
+        },
+      ]}
+    />
+  </div>
+);
+```
+
+## 极坐标图
+
+极坐标进度环，`seriesData` 为单个 `{ name, value }` 对象（`angleAxis.max` 默认 100）。
+
+```tsx
+import React from "react";
+import { Chart } from "@hsu-react/ui";
+
+export default () => (
+  <div style={{ height: 280 }}>
+    <Chart.Polar
+      title1="75%"
+      title2="完成度"
+      title1Style={{ color: "#333" }}
+      title2Style={{ color: "#999" }}
+      color={["#1675FB", "#5AB5F6"]}
+      seriesData={{ name: "完成度", value: 75 }}
+    />
+  </div>
+);
+```
+
+## 通用图表
+
+通用图表，直接透传 echarts 原生 `EChartsOption`，适合上述封装未覆盖的场景。
+
+```tsx
+import React from "react";
+import { Chart } from "@hsu-react/ui";
+
+export default () => (
+  <div style={{ height: 280 }}>
+    <Chart.Common
+      tooltip={{ trigger: "axis" }}
+      xAxis={{ type: "category", data: ["A", "B", "C", "D", "E"] }}
+      yAxis={{ type: "value" }}
+      series={[{ type: "line", smooth: true, data: [10, 22, 18, 30, 25] }]}
+    />
+  </div>
+);
+```
+
+## 组合图表
+
+组合图表，通过 `chartGroup` 传入若干 `{ type, options }`，可按 `pageSize` 分页展示并在 `Line`/`Bar`/`Pie` 间组合。其内部依赖布局样式，建议在业务页面中使用：
+
+```tsx | pure
+import { Chart } from "@hsu-react/ui";
+
+export default () => (
+  <Chart.Group
+    style={{ height: 320 }}
+    pageSize={2}
+    chartGroup={[
+      {
+        type: "Bar",
+        options: {
+          chartTitle: "销量",
+          xAxisData: ["一月", "二月", "三月"],
+          seriesData: [120, 200, 150],
+        },
+      },
+      {
+        type: "Pie",
+        options: {
+          chartTitle: "占比",
+          seriesData: [
+            { name: "直接访问", value: 335 },
+            { name: "搜索引擎", value: 234 },
+          ],
+        },
+      },
+    ]}
+  />
+);
+```
+
+## API
+
+### Chart.Line / Chart.Bar
+
+在 echarts `EChartsOption` 基础上扩展（`Chart.Bar` 同此表）：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| xAxisData | X 轴类目数据 | `string[]` | - |
+| seriesData | 系列数据，可为数字数组或带 `name`/`series` 的对象数组 | `SeriesDataType` | - |
+| legendData | 图例数据 | `string[]` | - |
+| chartTitle | 图表标题 | `string` | - |
+| scrollConfig | 滚动/缩放配置 | `ChartScrollConfig` | - |
+| insideDataZoom | 内置型数据缩放配置 | `DataZoomComponentOption` | - |
+| sliderDataZoom | 滑动条型数据缩放配置 | `DataZoomComponentOption` | - |
+| enableLegendAutoScroll | 是否启用图例自动滚动 | `boolean` | `false` |
+| legendVisibleCount | 图例每页可见数量 | `number` | `8` |
+| legendScrollInterval | 图例滚动间隔（ms） | `number` | `1500` |
+| onClick | 图元点击回调 | `(event: ECElementEvent) => void` | - |
+| className | 容器类名 | `string` | - |
+| style | 容器样式 | `ChartCSSProperties` | - |
+
+> `Chart.Line` 额外支持 `yAxisNameOffsets?: number[]`；其余 echarts 原生配置项（`grid`、`xAxis`、`yAxis`、`tooltip`、`series` 等）均可直接透传。
+
+### Chart.Pie
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| seriesData | 系列数据 | `SeriesDataType` | - |
+| chartTitle | 图表中心标题 | `string` | - |
+| extendSeries | 追加的额外系列 | `Series[]` | `[]` |
+| isSemiCircle | 是否为半圆 | `boolean` | `false` |
+| position | 半圆贴边位置 | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` |
+| spanAngle | 显示角度 | `number` | `180` |
+| center | 中心位置 | `[string, string]` | - |
+| radius | 半径配置 | `[string, string]` | - |
+| enableLegendAutoScroll | 是否启用图例自动滚动 | `boolean` | `false` |
+| onClick | 图元点击回调 | `(event: ECElementEvent) => void` | - |
+| onChart | 图表实例就绪回调 | `(chart: EChartsType) => void` | - |

package/src/components/Chat/ChatInput/_components/SendButton/index.module.less

@@ -10,7 +10,7 @@
   border: none;
   border-radius: 4px;
 
-  .ant-btn-icon {
+  :global(.ant-btn-icon) {
     display: flex;
     align-items: center;
     justify-content: center;

package/src/components/Chat/ChatInput/_components/UploadButton/index.module.less

@@ -4,7 +4,7 @@
 
   border-radius: 4px;
 
-  .ant-btn-icon {
+  :global(.ant-btn-icon) {
     display: flex;
     align-items: center;
     justify-content: center;

package/src/components/Chat/ChatInput/index.module.less

@@ -57,7 +57,7 @@
           opacity: 0.8;
           width: 140px;
           height: 100%;
-          .ant-select-selector {
+          :global(.ant-select-selector) {
             border: none;
             margin: 1px 0 0;
           }
@@ -92,7 +92,7 @@
 
   border-radius: 4px;
 
-  .ant-btn-icon {
+  :global(.ant-btn-icon) {
     display: flex;
     align-items: center;
     justify-content: center;

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

@@ -20,7 +20,7 @@
   }
 
   .answerBubble {
-    .ant-bubble-dot {
+    :global(.ant-bubble-dot) {
       column-gap: var(--ant-margin-xxs);
     }
 

package/src/components/Chat/index.md

@@ -8,10 +8,149 @@ title: Chat 对话
 
 # Chat 对话
 
-> `Chat` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 `@ant-design/x` 封装的 AI 对话组件集合，以 `Chat.List`（消息列表）、`Chat.Input`（输入框）、`Chat.History`（历史会话）三个子组件构成完整对话界面。
 
 ## 引入
 
 ```ts
 import { Chat } from "@hsu-react/ui";
 ```
+
+## 对话
+
+```tsx
+import React, { useState } from "react";
+import { Chat } from "@hsu-react/ui";
+
+export default () => {
+  const [list, setList] = useState([
+    {
+      query: { query: "你好，请介绍一下你自己" },
+      answers: [
+        { answer: "你好！我是 AI 助手，有什么可以帮你的吗？", messageId: "1" },
+      ],
+    },
+  ]);
+
+  const handleSend = (value) => {
+    setList((prev) => [
+      ...prev,
+      {
+        query: { query: value },
+        answers: [{ answer: `已收到：${value}`, messageId: String(Date.now()) }],
+      },
+    ]);
+  };
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", height: 420 }}>
+      <div style={{ flex: 1, overflow: "auto" }}>
+        <Chat.List list={list} />
+      </div>
+      <Chat.Input onSend={handleSend} uploadEnabled={false} />
+    </div>
+  );
+};
+```
+
+## 历史会话
+
+历史会话列表，`historyList` 为按分组（如日期）组织的会话数据，支持新建、点击切换、重命名与删除会话。
+
+```tsx
+import React, { useState } from "react";
+import { Chat } from "@hsu-react/ui";
+
+export default () => {
+  const [currentChatId, setCurrentChatId] = useState("1");
+
+  const historyList = {
+    今天: [
+      { id: "1", name: "如何学习 React", conversationId: "c1" },
+      { id: "2", name: "TypeScript 入门", conversationId: "c2" },
+    ],
+    昨天: [{ id: "3", name: "前端性能优化", conversationId: "c3" }],
+  };
+
+  return (
+    <div
+      style={{
+        height: 360,
+        width: 260,
+        border: "1px solid #f0f0f0",
+        borderRadius: 8,
+        overflow: "hidden",
+      }}
+    >
+      <Chat.History
+        historyList={historyList}
+        currentChatId={currentChatId}
+        width="260px"
+        onNewChat={() => setCurrentChatId("")}
+        onChatItemClick={(item) => setCurrentChatId(item.id)}
+        updateTitle={(chatId, title) => console.log("重命名", chatId, title)}
+        deleteHistory={(item) => console.log("删除", item)}
+      />
+    </div>
+  );
+};
+```
+
+## Chat.List
+
+消息列表，渲染用户提问与 AI 回答。
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| list | 消息列表数据 | `ChatMessage[]` | `[]` |
+| assistanting | AI 是否正在回答中 | `boolean` | - |
+| onAgain | 重新生成回调 | `(query: string) => void` | - |
+| onLikeChange | 点赞/点踩变化回调 | `(messageId: string, like: boolean \| null, content: string) => void` | - |
+| hideTool | 是否隐藏消息工具栏 | `boolean` | - |
+| defaultAnswer | 默认（空态）回答内容 | `string` | - |
+| userName / assistantName | 用户/助手名称 | `string` | - |
+| userAvatar / assistantAvatar | 用户/助手头像 | `ReactNode` | - |
+| userRenderContent | 自定义用户消息内容 | `(originContent: ReactNode, item: QueryMessage) => ReactNode` | - |
+| userRenderQuery | 自定义用户提问文本 | `(query: string \| undefined, item: QueryMessage) => string \| undefined` | - |
+| noAnswerTip | 无回答时的提示文案 | `string` | - |
+| className | 容器类名 | `string` | - |
+
+> 另有 `defaultAnswerClassName`、`userClassName`、`assistantClassName`、`userHeaderClassName`、`assistantHeaderClassName` 等多个样式类名属性。
+
+## Chat.Input
+
+对话输入框，支持文件上传、模型切换、功能（agent）开关。
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| onSend | 发送回调 | `(value: string) => void` | - |
+| assistanting | AI 是否回答中（显示停止按钮） | `boolean` | - |
+| onStop | 停止回答回调 | `() => void` | - |
+| fileList | 文件列表 | `UploadFile[]` | `[]` |
+| onFileListChange | 文件列表变化回调 | `(fileList: UploadFile[]) => void` | - |
+| uploadEnabled | 是否启用上传 | `boolean` | `true` |
+| uploadConfig | 上传配置 | `UploadConfig` | - |
+| modelConfig | 模型切换配置 | `{ modelList: ModelConfig[]; modelType: string; setModelType: (value: string) => void }` | - |
+| agents | 功能开关配置 | `AgentToggleConfig[]` | `[]` |
+| agentsState | 功能开关状态（受控） | `AgentConfig[]` | - |
+| onAgentsChange | 功能开关变化回调 | `(agents: AgentConfig[]) => void` | - |
+| placeholder | 占位提示文字 | `string` | `'询问问题'` |
+| sendIcon / stopIcon | 发送/停止图标 | `string` | - |
+| buttonGroup | 额外按钮组 | `ButtonProps[]` | - |
+| wrapperClassName | 容器类名 | `string` | - |
+
+## Chat.History
+
+历史会话列表，支持新建、重命名、删除会话。
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| historyList | 分组历史会话数据 | `Record<string, ChatHistoryData[]>` | - |
+| currentChatId | 当前选中的会话 id | `string` | - |
+| onNewChat | 新建会话回调 | `() => void` | - |
+| onChatItemClick | 会话点击回调 | `(item: ChatHistoryData) => void` | - |
+| updateTitle | 重命名回调 | `(chatId: string, title: string) => void` | - |
+| deleteHistory | 删除会话回调 | `(item?: ChatHistoryData) => void` | - |
+| onScrollEnd | 滚动到底部回调（加载更多） | `() => void` | - |
+| width | 容器宽度 | `string` | - |
+| tools | 顶部自定义工具区 | `ReactNode` | - |

package/src/components/Checkbox/CheckboxGroup/index.module.less

@@ -10,7 +10,7 @@
     height: 100%;
 
     // 当 hasAll 为 true 时，Group 作为子元素
-    > .ant-checkbox-group {
+    > :global(.ant-checkbox-group) {
       display: flex;
       flex-direction: column;
       row-gap: 8px;
@@ -28,9 +28,9 @@
   }
 
   &.outline {
-    .ant-checkbox-wrapper {
-      .ant-checkbox {
-        .ant-checkbox-inner {
+    :global(.ant-checkbox-wrapper) {
+      :global(.ant-checkbox) {
+        :global(.ant-checkbox-inner) {
           border-color: rgba(204, 204, 204, 1) !important;
 
           background: transparent !important;
@@ -41,16 +41,16 @@
           }
         }
 
-        &.ant-checkbox-checked {
-          .ant-checkbox-inner {
+        &:global(.ant-checkbox-checked) {
+          :global(.ant-checkbox-inner) {
             background: rgba(255, 255, 255, 1) !important;
           }
         }
       }
 
-      &.ant-checkbox-wrapper-disabled {
-        .ant-checkbox {
-          .ant-checkbox-inner {
+      &:global(.ant-checkbox-wrapper-disabled) {
+        :global(.ant-checkbox) {
+          :global(.ant-checkbox-inner) {
             background: rgba(0, 0, 0, 0.04) !important;
 
             &::after {
@@ -58,8 +58,8 @@
             }
           }
 
-          &.ant-checkbox-checked {
-            .ant-checkbox-inner {
+          &:global(.ant-checkbox-checked) {
+            :global(.ant-checkbox-inner) {
               background: rgba(0, 0, 0, 0.04) !important;
             }
           }
@@ -68,7 +68,7 @@
     }
   }
 
-  .ant-checkbox-wrapper {
+  :global(.ant-checkbox-wrapper) {
     align-items: center;
 
     font-family: inherit;
@@ -76,7 +76,7 @@
     font-weight: inherit;
     color: inherit;
 
-    .ant-checkbox {
+    :global(.ant-checkbox) {
       width: 16px;
       min-width: 16px;
       height: 16px;
@@ -84,12 +84,12 @@
 
       border-radius: 2px;
 
-      input[type="checkbox"].ant-checkbox-input {
+      input[type="checkbox"]:global(.ant-checkbox-input) {
         width: 100%;
         height: 100%;
       }
 
-      .ant-checkbox-inner {
+      :global(.ant-checkbox-inner) {
         width: 100%;
         height: 100%;
 
@@ -106,7 +106,7 @@
       }
 
       &-indeterminate {
-        .ant-checkbox-inner {
+        :global(.ant-checkbox-inner) {
           &::after {
             left: 50%;
             top: 50%;