x-next 1.6.0 → 1.8.0

package/AI_USAGE.md

@@ -1,11 +1,11 @@
 <!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage-recipes.md and script/ai-usage/manifest.js. -->
 # x-next AI 使用手册
 
-适用版本：**x-next@1.6.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
+适用版本：**x-next@1.8.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
 
-来源指纹（精选示例、映射、版本与公开类型声明）：`8b4e92e3477781a27ff136cbc59a1f8508ba69d45a4f5539daeee1de7a5d9570`。
+来源指纹（精选示例、映射、版本与公开类型声明）：`3e81e69933489d5ab6307ac5eaa38e89cb26004916f02f2556f74d18b1ed1766`。
 
-先按业务需要选择组件，不要求全部迁移。本手册限定在用户确认的 22 个组件及必要的同族子组件，未覆盖的导出不表示已完成业务验收。
+先按业务需要选择组件，不要求全部迁移。本手册限定在用户确认的 26 个组件及必要的同族子组件，未覆盖的导出不表示已完成业务验收。
 
 读取入口：`node_modules/x-next/AI_USAGE.md`；可用 `require.resolve('x-next/AI_USAGE.md')` 定位。这个文件名不会自动让所有 AI 工具加载，消费项目应在自己的指令中明确引用。
 
@@ -35,7 +35,11 @@
 | Steps | `Steps` | `<x-steps>` | `v-model:current` | [组件文档](https://x-next.ztes.com/components/steps) |
 | Tabs | `Tabs` | `<x-tabs>` | `v-model:active-key` | [组件文档](https://x-next.ztes.com/components/tabs) |
 | Empty | `Empty` | `<x-empty>` | 无 | [组件文档](https://x-next.ztes.com/components/empty) |
-这是一份给业务开发者和 AI Coding 使用的中文代码手册。以下 22 个入口是本手册选定的常用组件与服务；公开导出还有其他能力，不能据此推断所有导出都具有相同成熟度，也不要求每个项目全部使用。
+| Upload | `Upload` | `<x-upload>` | `v-model:file-list` | [组件文档](https://x-next.ztes.com/components/upload) |
+| BarChart | `BarChart` | `<x-bar-chart>` | 无 | [组件文档](https://x-next.ztes.com/components/bar-chart) |
+| LineChart | `LineChart` | `<x-line-chart>` | 无 | [组件文档](https://x-next.ztes.com/components/line-chart) |
+| PieChart | `PieChart` | `<x-pie-chart>` | 无 | [组件文档](https://x-next.ztes.com/components/pie-chart) |
+这是一份给业务开发者和 AI Coding 使用的中文代码手册。以下 26 个入口是本手册选定的常用组件与服务；公开导出还有其他能力，不能据此推断所有导出都具有相同成熟度，也不要求每个项目全部使用。
 
 每节提供一个可复制到 `App.vue` 的独立 Vue SFC，显式从 `x-next` 根入口导入，并包含全量 CSS。实际项目可将重复的 CSS 导入统一移到应用入口。本文是代码配方，不新增 live demo；每节链接的既有组件文档提供可交互示例和完整 API。
 
@@ -645,3 +649,177 @@ function refresh() { refreshed.value = true; }
   </Empty>
 </template>
 ```
+
+## Upload
+
+[组件文档与 live demo](https://x-next.ztes.com/components/upload)。`action` 是上传地址，也可用 `customRequest` 接管请求；两者都没提供时组件不会发起上传。`name` 是 FormData 字段名，默认 `'file'`；`method` 默认 `'post'`，`withCredentials` 默认 `false`。
+
+**接入已有上传方法的推荐写法**：`customRequest` 返回 Promise 时组件自动接管状态，resolve 即成功（结果写入 `file.response`，可用 `responseUrlKey` 提取 url，字符串支持 `data.url` 嵌套路径）、reject 即失败并出现重试入口，无需手动调用 `onSuccess` / `onError`。axios、flyio、fetch 或任何返回 Promise 的方法都适用。返回值是 fetch `Response` 时组件读取响应体；非 2xx 按失败处理，`error.status` 为状态码。需要进度与取消时，把 option 的 `signal`（取消 / 移除 / 卸载时触发）与 `onProgress`（0 ~ 1）透传给底层请求。返回 `{ abort }` 并手动回调的旧写法仍然支持。
+
+列表默认非受控，用 `defaultFileList` 给初值；需要外部驱动时用 `v-model:file-list`，列表项以 `uid` 为稳定标识。`listType` 取 `'text' | 'picture' | 'picture-card'`。`limit` 为数量上限，超出会触发 `exceed`，超出部分不进入列表；`beforeUpload` 返回 `false` 拦截、返回新 `File` 替换，支持 Promise。
+
+`change({ file, fileList })` 覆盖加入、进度、成功、失败和移除；`success` / `error` / `remove` / `progress` 是更细粒度的补充。`autoUpload=false` 时文件先以 `init` 入列，再用组件 `submit()` 上传、`abort()` 取消、`retry()` 重试。图片卡场景可加 `image-preview` 用内置 `ImagePreview` 看图。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Upload, type UploadFile } from 'x-next';
+import 'x-next/dist/style.css';
+const fileList = ref<UploadFile[]>([]);
+const status = ref('尚未选择文件');
+// 项目里已封装好的上传方法：返回 Promise 即可，组件自动显示成功与失败
+function uploadAttachment(params: { file: File; orderId: string }) {
+  const form = new FormData();
+  form.append('file', params.file);
+  form.append('orderId', params.orderId);
+  return fetch('/api/upload', { method: 'POST', body: form }).then((response) => {
+    if (!response.ok) throw new Error(`上传失败：${response.status}`);
+    return response.json() as Promise<{ data: { url: string } }>;
+  });
+}
+function changed(info: { file: UploadFile; fileList: UploadFile[] }) {
+  status.value = `${info.file.name}：${info.file.status ?? 'unknown'}`;
+}
+function beforeUpload(file: File) {
+  // 超过 2MB 直接拦截，文件不会进入列表
+  return file.size <= 2 * 1024 * 1024;
+}
+</script>
+<template>
+  <Upload
+    v-model:file-list="fileList"
+    :custom-request="({ file }) => uploadAttachment({ file, orderId: 'SO-20261003' })"
+    response-url-key="data.url"
+    name="file"
+    multiple
+    list-type="picture"
+    accept="image/*"
+    :limit="5"
+    :before-upload="beforeUpload"
+    @change="changed"
+  />
+  <p role="status">{{ status }}</p>
+</template>
+```
+
+## BarChart
+
+[组件文档与 live demo](https://x-next.ztes.com/components/bar-chart)。按天 / 小时聚合的柱状趋势图：`categories` 是类目轴标签，`series` 是数据系列（`{ name, data, color }`），两者按下标对应。单系列就是普通柱状图；多系列默认并排，加 `stack` 变成堆叠并显示合计。轻量迷你走势用 TrendChart，需要坐标轴与读数用本组件。
+
+数值轴自动取 1/2/5 步长的整洁刻度（所以刻度行数可能少于 `grid.horizontalLinesNumber`）；传 `max` 可锁定上界。`loading` 显示加载遮罩；数据全为 0 时显示空态，可用 `empty` 插槽替换。`null` / 负数按 0 处理且不画柱体。
+
+`tooltip` 默认开启，`legend` 开启后点击图例可隐藏系列并触发 `legendChange`；点击柱体触发 `barClick`，命中具体柱体时带 `seriesIndex` / `value`，未命中时为 `null`。`valueFormatter` 统一控制提示、图例与数值轴的数字格式。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BarChart } from 'x-next';
+import 'x-next/dist/style.css';
+const categories = ref(['09-28', '09-29', '09-30', '10-01', '10-02']);
+const series = ref([
+  { name: '浏览量', data: [86, 142, 98, 210, 176] },
+  { name: '访客数', data: [52, 88, 61, 120, 96] },
+]);
+const picked = ref('尚未选择');
+// 原生属性（含 aria-*）用对象 v-bind 传递，组件 props 与事件仍直接绑定
+const chartAttrs = { 'aria-label': '每日浏览量与访客数' };
+function onBarClick(data: { label: string; total: number; value: number | null }) {
+  picked.value = `${data.label}：合计 ${data.total}`;
+}
+</script>
+<template>
+  <BarChart
+    v-bind="chartAttrs"
+    :categories="categories"
+    :series="series"
+    :height="240"
+    legend
+    @bar-click="onBarClick"
+  />
+  <p role="status">{{ picked }}</p>
+</template>
+```
+
+## LineChart
+
+[组件文档与 live demo](https://x-next.ztes.com/components/line-chart)。随时间看趋势就用它：`categories` 是时间轴标签，`series` 是数据系列（`{ name, data, color }`），按下标对应。多系列默认叠放，加 `area` 填充、再加 `stack` 变堆叠面积。按类目比大小用 BarChart，看占比用 PieChart，卡片角落的迷你走势用 TrendChart——完整选择指引见[图表总览](https://x-next.ztes.com/components/charts)。
+
+**缺测要显式表达**：把没有数据的点写成 `null`，默认会在该处**断开**折线（不会画成跌到 0）；确需连线时传 `:connect-nulls="true"`。数值轴对纯正数数据保持 0 基线，出现负值才向下扩展；`min` / `max` 可锁定区间。`smooth` 默认开启，`show-points` 默认 `'auto'`（点数少时常显）。
+
+`tooltip` 默认开启，`legend` 开启后点击图例可隐藏系列并触发 `legendChange`（数值轴会按剩余可见系列重算）；点击触发 `lineClick`，命中数据点时带 `seriesIndex` / `value`。`valueFormatter` 同时作用于提示与图例，`labels.yFormatter` 只作用于数值轴。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { LineChart } from 'x-next';
+import 'x-next/dist/style.css';
+const categories = ref(['09-28', '09-29', '09-30', '10-01', '10-02']);
+// 10-01 当天缺测：null 会让折线在该处断开
+const series = ref([
+  { name: '请求量', data: [820, 932, null, 934, 1290] },
+  { name: '错误数', data: [12, 18, null, 9, 22] },
+]);
+const picked = ref('尚未选择');
+function onLineClick(data: { label: string; value: number | null }) {
+  picked.value = `${data.label}：${data.value ?? '缺测'}`;
+}
+</script>
+<template>
+  <LineChart
+    :categories="categories"
+    :series="series"
+    :height="280"
+    area
+    legend
+    @line-click="onLineClick"
+  />
+  <p role="status">{{ picked }}</p>
+</template>
+```
+
+## PieChart
+
+[组件文档与 live demo](https://x-next.ztes.com/components/pie-chart)。表达占比：`data` 是 `{ name, value }[]`，值按**可见**分片求和换算角度。`innerRadius="62%"` 渲染成环形并在中心显示合计（推荐形态，信息密度更高）；数字形式的 `innerRadius` 按 px。负值、0 与非有限数会被跳过，不计入总量。
+
+**类别要收敛**：饼图超过 7 个分片就难以阅读，先按值排序、把尾部合并成「其他」再传入（本配方给出写法）。需要精确比较大小改用 BarChart，需要看随时间的变化改用 LineChart。
+
+`legend` 开启后图例项展示数值与占比，点击可隐藏分片——剩余分片重新分配角度、中心合计同步更新，并触发 `legendChange`；点击分片触发 `itemClick`。`center` / `tooltip` / `label` / `legend` 插槽可分别自定义。
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { PieChart } from 'x-next';
+import 'x-next/dist/style.css';
+const raw = ref([
+  { name: 'search', value: 820 },
+  { name: 'read_file', value: 610 },
+  { name: 'write_file', value: 430 },
+  { name: 'run_shell', value: 320 },
+  { name: 'browse', value: 210 },
+  { name: 'exec_python', value: 180 },
+  { name: 'grep', value: 140 },
+]);
+const LIMIT = 5;
+// 饼图不宜超过 7 个分片：取前 N 项，尾部合并为「其他」
+const data = computed(() => {
+  const sorted = [...raw.value].sort((a, b) => b.value - a.value);
+  const top = sorted.slice(0, LIMIT);
+  const rest = sorted.slice(LIMIT).reduce((sum, item) => sum + item.value, 0);
+  return rest > 0 ? [...top, { name: '其他', value: rest }] : top;
+});
+const picked = ref('尚未选择');
+function onItemClick(item: { name: string; value: number; percent: number; formatPercent: (p: number) => string }) {
+  picked.value = `${item.name}：${item.value}（${item.formatPercent(item.percent)}）`;
+}
+</script>
+<template>
+  <PieChart
+    :data="data"
+    inner-radius="62%"
+    :height="280"
+    legend
+    @item-click="onItemClick"
+  />
+  <p role="status">{{ picked }}</p>
+</template>
+```

package/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.8.0] - 2026-10-05
+
+### 新增
+
+- **图表族：BarChart 柱状趋势图 / LineChart 折线图 / PieChart 饼图**，与既有 TrendChart、Heatmap 组成完整的基础图表集，文档站新增「图表」分类与[图表总览](https://x-next.ztes.com/components/charts)（含「怎么选」指引）。
+  - **BarChart**：单系列柱状、多系列并排 / 堆叠；数值轴按 1/2/5 取整洁刻度，`max` 可锁定上界；`legend` 点击隐藏系列并重算轴；`bar` / `tooltip` / `legend` / `empty` 插槽。
+  - **LineChart**：多系列、面积、堆叠面积、平滑曲线；`null` 缺测**默认断线**（不画成跌到 0），`connectNulls` 可跨过；纯正数保持 0 基线，出现负值才扩展负向刻度；`min` / `max` 锁域；`point` 插槽自定义数据点。
+  - **PieChart**：饼图 / 环形一体（`innerRadius` 支持 px 与百分比）；环形中心默认显示合计，`center` 插槽可自定义；`legend` 展示「数值·占比」并可点击隐藏分片，剩余分片重新分配角度；小于 4% 的分片不画外围标签。
+  - 三个图表共享一套交互约定：整块画布一个悬浮提示节点、键盘方向键读数（Home / End 跳首尾、Esc 关闭）、`aria-live` 播报、`ariaLabel` 图像名称、容器尺寸自适应。
+- **图表族共享核心**：`_utils/chart`（padding 解析、数值轴刻度与双侧域、折线 / 面积 / 扇形路径、数值与文本估宽）、`_components/chart`（ChartAxis / ChartTooltip / ChartLegend 与 `--x-chart-*` token）、`useChartSize` hook。四个图表共用同一套轴、提示、图例实现与配色。
+- **Heatmap 键盘可达性与实例级 id**：网格可聚焦（`role="grid"` + 方向键按天 / 按周移动 + Home / End + Esc），读数通过 `aria-live` 播报；格子 id 加实例前缀，同页多块热力图不再重复；交互模式下不再用 `role="img"` 遮蔽整个子树。
+- 新增语言包：`chart`（合计 / 系列名 / 图例无障碍名称 / 饼图总计）、`heatmap.gridLabel`。
+
+### 修复
+
+- **BEM `is()` mixin 类名错位（影响已发布功能）**：`@include is(state)` 编译出的选择器是 `.-state`，与运行时类名 `x-<block>-is-<state>` 永远不匹配，状态样式自加入起即静默失效。Heatmap 的悬浮提示（1.6.0 已发布）因此完全不可见。修复后 mixin 输出完整类名，并补齐 `bar-chart` / `line-chart` / `pie-chart` / `heatmap` 的激活与隐藏态。
+- **Heatmap 提示浮层定位偏移与溢出**：浮层改为渲染在网格内（网格为定位基准），不再少算左侧星期标签的宽度；气泡横向收敛到网格范围，首列与末列不再溢出网格。
+- **TrendChart 边缘内容被裁**：裁剪路径向外扩一个数据点半径，首点 / 末点 / 极值点不再被切掉一半；提示气泡横向收敛到绘图区，首末点的读数完整可见。
+- **TrendChart 标签补偿压垮绘图区**：`padding` 与自动标签补偿叠加后会把绘图区压到 0（曲线静默退化成直线），现限制补偿上限并在绘图区小于 8×8 时给出开发期提示。
+- **TrendChart 提示气泡宽度低估**：`text.length * 7` 的估算对纯中文文案低估约 40% 导致文字溢出，改用按字形估宽（CJK 1em / 其余 0.6em）。
+- **BarChart 画布测量含图例**：改用画布节点测量尺寸，图例高度不再计入绘图区。
+- **`is()` 相关状态样式**：`x-bar-chart-is-active`、`x-line-chart-is-active`、`x-pie-chart-is-active/dimmed`、`x-heatmap-is-visible/out-of-range` 全部生效。
+- 修复 `labels.yFormatter` / `labels.color`（BarChart）与 `PieSegment` 类型泄漏导致的构建失败。
+
+### 变更
+
+- **TrendChart 的 `grid` 与 `labels` 标记废弃**：这两个 prop 在 1.7.0 发布过，但从定位上不属于迷你图——带网格和坐标文字的图是「读数的图」，应该用 LineChart。1.8.0 起**不再渲染任何内容**，props 声明保留并在开发期给出废弃警告，既有代码升级不会编译或运行报错；下个主版本（2.0.0）彻底移除。
+- **TrendChart 视觉减重**：描边 2 → **1.5px**、数据点半径 3 → **2px**、激活竖线 2 → **1px**、默认 `padding` `'5'` → `'3'`（3 是激活点半径可容纳的最小值，曲线峰值距顶由 5px 收到 3px）。
+- BarChart 与 LineChart 的轴 / 提示 / 图例样式移入共享层（`x-chart--*`），组件样式只保留几何部分。
+- `TrendChart` 的曲线平滑与面积路径改用共享实现，与 LineChart 曲率一致。
+
+### 文档与测试
+
+- 新增 `charts.md`（图表总览与选择指引）、`line-chart.md`（8 个 live demo）、`pie-chart.md`（7 个 live demo）；侧栏与组件总览新增「图表」分类，TrendChart、Heatmap 迁入。
+- `trend-chart.md` 重写尺寸指引（推荐 40~60px）、新增「卡片场景」示例与「什么时候需要标签」判断表；`heatmap.md` 补键盘导航与无障碍结构说明。
+- 新增测试：共享图表 helper 16 项、LineChart 33 项、PieChart 26 项、BarChart 49 项、TrendChart 47 项、Heatmap 48 项；全量 2266 项通过。
+- AI 使用手册扩到 26 个组件（新增 BarChart / LineChart / PieChart 配方）；`check:bundle-size` 的 `base.css` 上限由 25,200 调整为 26,200（共享图表层 22 个 token 与公共样式的一次成本，由 4 个图表组件摊薄）。
+
+## [1.7.0] - 2026-10-04
+
+### 新增
+
+- **Upload 上传组件**：支持点击选择、拖拽（含文件夹递归读取并保留相对路径）、粘贴上传；文本 / 图片 / 图片卡三种列表形态；`limit` 数量限制与 `exceed`、`beforeUpload` 拦截或替换文件、`beforeRemove` 移除前钩子；`autoUpload=false` 手动上传配合 `submit()` / `abort()` / `retry()`；逐项取消回到待上传态（不同于 Arco 归属 error 的处理）；`updateFile(uid, file)` 原地替换文件；`tip` 提示、操作按钮开关、内置 `ImagePreview` 图片预览；`aria-live` 上传状态播报与操作按钮无障碍名称。
+- **接入已有上传方法（`customRequest` 返回 Promise）**：业务只需 `:custom-request="({ file }) => uploadApi({ file, orderId })"`，组件自动接管状态——resolve 即成功、reject 即失败并出现重试入口，结果写入 `file.response`；axios、flyio、fetch 或任何返回 Promise 的方法均可直接接入，无需手动调用 `onSuccess` / `onError`。返回 `{ abort }` 加手动回调的写法继续兼容。
+- **`UploadRequestOption.signal`**：每次尝试独立的 `AbortSignal`，取消上传、移除文件或组件卸载时触发，可直接透传给 fetch / axios 真正中止网络请求。
+- **fetch `Response` 自动归一化**：`customRequest` 直接返回 `fetch(...)` 时，JSON / text 响应体解析后写入 `file.response`，非 2xx 按失败处理并在 `error.status` 提供状态码；axios / flyio 已解析的响应对象原样透传。
+- **`responseUrlKey` 嵌套路径**：字符串支持 `data.url` 形式的路径提取；函数形态增加第二个参数 `response`。
+- 新增 Upload 中英文语言包（`trigger` / `drag` / `fileUploaded` 等 18 项）；ImagePreview 语言包补 `openLabel` / `loadError` / `loading`。
+- 新增 `_self/upload-icons` 图标（上传云、文件、图片、刷新、下载、删除）。
+
+### 修复
+
+- **Image 加载失败态**：默认错误占位由大红底改为中性色底 + 次级文字，错误占位补齐圆角，不再刺眼。
+- **ImagePreview 工具条**：亮色白底改为深色半透明 + 模糊背景，hover 反馈统一为透明底浅色图标，窄屏工具条可折行不再溢出。
+- **Image 换图与 SSR**：`src` 由 `watchEffect` 直写 DOM 改为声明式绑定带 key 的 `img`，SSR 正确输出地址；源变更重置加载状态，旧图片节点的 load / error 事件不再覆盖新图；`description` 按文档回退给 `alt`。
+- **Image / Preview 键盘可达性**：缩略图可聚焦并用 Enter 打开预览；预览弹层补齐 Tab 圈定与关闭后焦点恢复；快捷键只在顶层预览生效。
+- **ImagePreview 加载失败**：失败时提供可访问的错误占位而非只撤下 spinner；`actionsLayout=[]` 时自定义 actions 独立渲染，不再被一并隐藏。
+- **ImagePreview 动态配置与边界**：`keyboard` / `popupContainer` 动态变更时迁移监听并清理计时器；`defaultScale` / `zoomRate` 非法值与满屏零尺寸兜底，不再产生无效 transform。
+- **ImagePreviewAction**：`attrs` 不再覆盖内部 class、`disabled` 与 aria 属性，自定义样式与禁用语义同时生效。
+- **Image 拖拽 hook**：`use-image-drag` 在节点更换时解绑旧监听，移除 / 换图不再残留移动状态。
+- **ImagePreviewGroup 无障碍**：弹层读屏标签传入真实序号与总数，不再恒为「第 1 张，共 1 张」。
+- **多层预览滚动锁**：预览使用 `useOverflow` 引用计数与容器迁移，关闭上层预览不再提前解锁页面滚动。
+- **Image 外置 footer 高度**：根节点高度由内容撑开，多行说明不再溢出或与下方内容重叠。
+- **ImagePreview SSR**：仅客户端清理 wheel 的 RAF，`docs:build` 不再输出 `cancelAnimationFrame` 报错。
+- **Image 原生事件声明**：`load` / `error` 显式声明并转发，消费者 `strictTemplates` 编译通过。
+
+### 文档与测试
+
+- 新增 `upload.md`（15 个 live demo，覆盖接入已有方法、响应提取、进度与取消、多选限制、拖拽、图片卡、手动上传、校验重试、插槽、禁用粘贴、文件夹、替换文件、Form 联动）与 `volar` 注册；组件索引、侧栏同步。
+- `image.md` 重写扩充：12 个场景全部含 live demo 与完整 SFC，补换图、错误恢复、仅自定义工具条、局部容器、键盘组切换等。
+- Upload 单测 81 项（含 Promise resolve / reject、取消后晚到结果不覆盖、signal 中止、fetch Response 归一化、手动回调优先等 13 项新增回归）；Image 新增 21 项行为断言；全量测试 2136 项。
+- AI 使用手册新增 Upload（23 个公共组件），`ai-usage-recipes.md` 示例改为「接入已有上传方法」并重新生成 `AI_USAGE.md`。
+- `check:bundle-size` 的 Input 预算由 38,000 调整为 39,500：Input 消费者结构性携带整个共享语言包（zh-CN + en-US 合计 11,635 bytes，约占 30%），按组件拆分的方案继续在 `项目审查/2026-10-03-main-共享语言包与Input体积门禁.md` 跟踪。
+
 ## [1.6.0] - 2026-10-02
 
 ### 新增

package/dist/_hooks/use-chart-size.d.ts

@@ -0,0 +1,25 @@
+import { Ref } from 'vue';
+export interface ChartCanvasSize {
+    width: number;
+    height: number;
+}
+/**
+ * 图表画布尺寸观测（ResizeObserver + window resize 兜底）。
+ *
+ * 观测对象必须是**画布**而不是组件根节点：根节点通常还挂着图例等内容，
+ * 用根节点高度计算绘图区会把图例高度算进去，底部轴标签会与图例重叠。
+ *
+ * width / height 传 getter：数字按 px 直接采用，其余取元素实测尺寸，
+ * 与组件 props 的 `number | string` 语义一致。
+ */
+export declare const useChartSize: ({ elementRef, width, height, }: {
+    elementRef: Ref<HTMLElement | null | undefined>;
+    width: () => number | string;
+    height: () => number | string;
+}) => {
+    size: {
+        width: number;
+        height: number;
+    };
+    setSize: () => void;
+};

package/dist/_utils/chart/index.d.ts

@@ -0,0 +1,6 @@
+export type { ChartPadding } from './padding';
+export { getPadding, validatePadding } from './padding';
+export type { NiceScale, NiceDomain } from './scale';
+export { getNiceScale, getScale, getNiceDomain, getDomain, formatNumber, formatTickValue, defaultValueFormatter, formatPercent, estimateTextWidth, pickLabelIndices, } from './scale';
+export type { ChartPoint, ArcSegmentParams } from './path';
+export { roundedTopRectPath, genLinePath, genAreaPath, polarPoint, describeArcSegment, } from './path';

package/dist/_utils/chart/padding.d.ts

@@ -0,0 +1,15 @@
+export interface ChartPadding {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * 解析 CSS 简写风格的 1-4 个非负值（如 '8 12'），语义与 CSS padding 一致。
+ *
+ * 图表族（BarChart / LineChart / TrendChart）共用这一份实现，
+ * 避免每个组件各写一份导致边界行为漂移。
+ */
+export declare const getPadding: (padding: string | number) => ChartPadding;
+/** 接受单个非负数字，或 1-4 个以空格分隔的非负数字字符串 */
+export declare const validatePadding: (padding: string | number) => boolean;

package/dist/_utils/chart/path.d.ts

@@ -0,0 +1,34 @@
+export interface ChartPoint {
+    x: number;
+    y: number;
+}
+/** 仅顶部圆角的矩形路径；radius 会被收敛到合法范围 */
+export declare const roundedTopRectPath: (x: number, y: number, width: number, height: number, radius: number) => string;
+/**
+ * 折线路径。
+ *
+ * 平滑模式用「相邻两点水平中点」作为控制点：每个数据点的切线是水平的，
+ * 曲线在每个区间内单调、不会过冲（Catmull-Rom 会在尖峰处冲出去），
+ * 观感接近 Arco / AntDV 的曲线图。
+ */
+export declare const genLinePath: (points: ChartPoint[], smooth?: boolean) => string;
+/** 面积路径：折线两端垂落到基线后闭合 */
+export declare const genAreaPath: (points: ChartPoint[], baseline: number, smooth?: boolean) => string;
+/** 极坐标转直角坐标；SVG 的 y 轴向下，正角度即顺时针 */
+export declare const polarPoint: (cx: number, cy: number, radius: number, angleDeg: number) => ChartPoint;
+export interface ArcSegmentParams {
+    cx: number;
+    cy: number;
+    outerRadius: number;
+    /** 0 表示实心扇形，> 0 表示环形分段 */
+    innerRadius: number;
+    startAngle: number;
+    endAngle: number;
+}
+/**
+ * 扇形 / 环形分段路径。
+ *
+ * 全圆（360°）会让起止点重合、SVG 无法画出弧线，这里把扫过角度收敛到
+ * 359.99°；内半径夹到外半径以内，避免出现反向路径。
+ */
+export declare const describeArcSegment: (params: ArcSegmentParams) => string;

package/dist/_utils/chart/scale.d.ts

@@ -0,0 +1,55 @@
+export interface NiceScale {
+    /** 数据域上界（对齐到「好看」的刻度步长） */
+    max: number;
+    /** 自 0 起均匀分布的刻度值，长度 = 网格线数量 */
+    ticks: number[];
+}
+/** 双侧数值域，折线图出现负值时使用 */
+export interface NiceDomain {
+    min: number;
+    max: number;
+    /** 自 min 起按步长均匀分布的刻度值 */
+    ticks: number[];
+}
+/**
+ * 计算「好看」的数值轴（0 基线）：步长只取 1 / 2 / 5 乘以 10 的幂。
+ *
+ * 上行数上取整到步长的整数倍，因此实际刻度数量会**小于等于**请求值
+ * （例如数据上限 10、请求 4 条时刻度为 0/5/10）。刻度值保持整洁
+ * 优先于数量精确，避免出现 3.33 这类刻度和浮点噪声。
+ */
+export declare const getNiceScale: (dataMax: number, lineCount?: number) => NiceScale;
+/**
+ * 计算数值轴；传入 lockedMax（max prop）时按锁定值为上界，
+ * 不再做「好看」对齐，保证业务指定的刻度精确生效。
+ */
+export declare const getScale: (dataMax: number, lineCount?: number, lockedMax?: number) => NiceScale;
+/**
+ * 计算「好看」的双侧数值域。
+ *
+ * 单侧数据保持 0 基线（与柱状图一致，避免非零基线夸大波动）；
+ * 数据出现负值时才把下界扩展到负向刻度，正负对称地覆盖 0 线。
+ */
+export declare const getNiceDomain: (dataMin: number, dataMax: number, lineCount?: number) => NiceDomain;
+/**
+ * 计算双侧数值域；min / max 传入后按锁定值均分，保证业务指定的刻度精确生效。
+ */
+export declare const getDomain: (dataMin: number, dataMax: number, lineCount?: number, lockedMin?: number, lockedMax?: number) => NiceDomain;
+/** 千分位格式化，最多保留指定小数位并去掉末尾 0 */
+export declare const formatNumber: (value: number, maximumFractionDigits?: number) => string;
+/** 刻度文本：先消掉浮点尾差再走千分位格式化 */
+export declare const formatTickValue: (value: number) => string;
+/**
+ * 图表默认数值格式化：千分位 + 最多 4 位小数。
+ * 覆盖整数计数（13,000,067）与小额金额（¥0.49）两类常见场景。
+ */
+export declare const defaultValueFormatter: (value: number) => string;
+/** 百分比文案：`12.3%`；total 为 0 时返回 `0%` 而不是 NaN */
+export declare const formatPercent: (value: number, total: number, digits?: number) => string;
+/** 文本近似渲染宽度：CJK 按 1em，其余按 0.6em */
+export declare const estimateTextWidth: (text: string, fontSize: number) => number;
+/**
+ * 类目标签抽稀：按柱间距与标签宽度算出步长，保证相邻标签间留有 gap。
+ * 末位标签总是保留（趋势图需要看到最新时间点），与倒数第二个太近时挤掉前一个。
+ */
+export declare const pickLabelIndices: (count: number, band: number, maxLabelWidth: number, gap?: number) => number[];

package/dist/components/_components/chart/ChartAxis.d.ts

@@ -0,0 +1,85 @@
+import { PropType } from 'vue';
+import { ChartAxisPlot, ChartAxisTick, ChartAxisXLabel } from './interface';
+/**
+ * 直角坐标系的网格与轴标签。
+ *
+ * BarChart 与 LineChart 的轴布局完全一致（横向网格 + 左侧数值标签 +
+ * 底部类目标签），抽到这里避免两处各写一份、改一处漏一处。
+ * 迷你图 TrendChart 有独立的边界/标签体系，不使用本组件。
+ */
+declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    plot: {
+        type: PropType<ChartAxisPlot>;
+        required: true;
+    };
+    ticks: {
+        type: PropType<ChartAxisTick[]>;
+        default: () => never[];
+    };
+    xLabels: {
+        type: PropType<ChartAxisXLabel[]>;
+        default: () => never[];
+    };
+    fontSize: {
+        type: NumberConstructor;
+        default: number;
+    };
+    color: {
+        type: StringConstructor;
+        default: string;
+    };
+    showX: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    showY: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    showHorizontalLines: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, () => VNode, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    plot: {
+        type: PropType<ChartAxisPlot>;
+        required: true;
+    };
+    ticks: {
+        type: PropType<ChartAxisTick[]>;
+        default: () => never[];
+    };
+    xLabels: {
+        type: PropType<ChartAxisXLabel[]>;
+        default: () => never[];
+    };
+    fontSize: {
+        type: NumberConstructor;
+        default: number;
+    };
+    color: {
+        type: StringConstructor;
+        default: string;
+    };
+    showX: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    showY: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    showHorizontalLines: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{}>, {
+    color: string;
+    fontSize: number;
+    ticks: ChartAxisTick[];
+    xLabels: ChartAxisXLabel[];
+    showX: boolean;
+    showY: boolean;
+    showHorizontalLines: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/components/_components/chart/ChartLegend.d.ts

@@ -0,0 +1,26 @@
+import { PropType } from 'vue';
+import { ChartLegendItem } from './interface';
+/**
+ * 图例。
+ *
+ * 项可点击切换显隐（柱状 / 折线按系列，饼图按分片）；
+ * `default` 插槽可整体替换渲染，插槽参数为当前图例项。
+ */
+declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    items: {
+        type: PropType<ChartLegendItem[]>;
+        default: () => never[];
+    };
+}>, () => any, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    toggle: (index: number) => boolean;
+}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    items: {
+        type: PropType<ChartLegendItem[]>;
+        default: () => never[];
+    };
+}>> & Readonly<{
+    onToggle?: ((index: number) => any) | undefined;
+}>, {
+    items: ChartLegendItem[];
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/components/_components/chart/ChartTooltip.d.ts

@@ -0,0 +1,76 @@
+import { PropType } from 'vue';
+import { ChartTooltipEntry } from './interface';
+/**
+ * 悬浮提示宿主。
+ *
+ * 三张图表（柱状 / 折线 / 饼图）只共享一个提示节点，位置由各图自行换算；
+ * 默认内容为「标题 + 逐行数值 + 合计」，`default` 插槽可整体替换。
+ */
+declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    visible: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    title: {
+        type: StringConstructor;
+    };
+    entries: {
+        type: PropType<ChartTooltipEntry[]>;
+        default: () => never[];
+    };
+    /** 合计行；entries 只有一个时可传 null 隐藏 */
+    total: {
+        type: PropType<{
+            label: string;
+            value: string;
+        } | null>;
+        default: null;
+    };
+    /** 位置样式，由各图换算（锚点或指针坐标） */
+    position: {
+        type: PropType<Record<string, string | number>>;
+        default: () => {};
+    };
+    /** 需要测量提示宽度做贴边收敛时，通过该回调取到 DOM 节点 */
+    onElement: {
+        type: PropType<(el: HTMLDivElement | null) => void>;
+    };
+}>, () => any, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    visible: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    title: {
+        type: StringConstructor;
+    };
+    entries: {
+        type: PropType<ChartTooltipEntry[]>;
+        default: () => never[];
+    };
+    /** 合计行；entries 只有一个时可传 null 隐藏 */
+    total: {
+        type: PropType<{
+            label: string;
+            value: string;
+        } | null>;
+        default: null;
+    };
+    /** 位置样式，由各图换算（锚点或指针坐标） */
+    position: {
+        type: PropType<Record<string, string | number>>;
+        default: () => {};
+    };
+    /** 需要测量提示宽度做贴边收敛时，通过该回调取到 DOM 节点 */
+    onElement: {
+        type: PropType<(el: HTMLDivElement | null) => void>;
+    };
+}>> & Readonly<{}>, {
+    entries: ChartTooltipEntry[];
+    visible: boolean;
+    total: {
+        label: string;
+        value: string;
+    } | null;
+    position: Record<string, string | number>;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/components/_components/chart/colors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 图表族共享的分类色板。
+ *
+ * 颜色引用 `--x-chart-color-series-N` 语义 token（定义在
+ * _components/chart/style/var.scss），亮 / 暗主题与 ConfigProvider 换主色时
+ * 自动联动。写全量 token 字符串而不是拼接下标，样式 token 门禁才能静态看到引用，
+ * 避免色板被误判为「已定义但未使用」。
+ */
+export declare const ChartSeriesColors: string[];
+export declare const getSeriesColor: (index: number) => string;