@xq-labs/data-ui-v2 0.2.0 → 0.3.0

package/docs/examples/local-development.md

@@ -0,0 +1,191 @@
+# 本地临时联调说明
+
+> 这份文档不是 API 文档。
+> 它只面向当前组件库维护者，用于把当前仓库的最新发布产物，临时安装到其他本地项目里做联调验证。
+
+## 1. 适用场景
+
+适合以下情况：
+
+- 刚改完组件能力，想马上到业务项目里验证
+- 只做当天的临时联调，不做长期本地依赖维护
+- 希望联调方式尽量贴近真实发布包结构
+
+不适合以下情况：
+
+- 需要连续多天频繁联调
+- 需要同时给多个本地项目持续推送更新
+- 需要基于源码目录直接调试发布链路之外的问题
+
+## 2. 联调原则
+
+当前仓库正式发布包根目录是 `.release/`，不是仓库根目录。
+
+所以本地临时联调时：
+
+- 推荐安装 `.release/`
+- 不推荐直接安装仓库根目录
+- 不推荐优先使用 `npm link`
+- 当前文档也不使用 `yalc`
+
+这样做的原因是：
+
+- `.release/` 更接近真实发包结果
+- 能直接验证 `package.json`、入口文件、样式和文档是否正确
+- 联调结果和正式发布后的安装结果更一致
+
+## 3. 当前仓库先做什么
+
+先在当前仓库执行构建：
+
+```bash
+npm run build
+```
+
+如需顺手检查发包内容，可以再执行：
+
+```bash
+npm run pack:check
+```
+
+构建完成后，确认 `.release/` 下至少存在：
+
+- `package.json`
+- `lib/`
+- `es/`
+- `theme-chalk/`
+
+## 4. 其他本地项目如何临时安装
+
+进入业务项目后执行：
+
+```bash
+npm install ../data-ui-v2/.release --no-save
+```
+
+说明：
+
+- `--no-save` 表示这次安装只用于临时联调
+- 这样可以尽量避免把本地路径依赖长期写进项目配置
+- 路径请按你的本地实际目录调整
+
+如果业务项目还没有安装图表运行依赖，需要补齐：
+
+```bash
+npm install echarts
+```
+
+如果这次要验证 3D 饼图，再额外安装：
+
+```bash
+npm install echarts-gl
+```
+
+## 5. 联调时如何使用
+
+业务项目里按正常方式引用即可，例如：
+
+```js
+import DataUI from '@xq-labs/data-ui-v2'
+```
+
+或按需引入：
+
+```js
+import { BarLineChart, PieChart } from '@xq-labs/data-ui-v2'
+```
+
+如果业务项目没有自动带上样式，可补充：
+
+```js
+import '@xq-labs/data-ui-v2/theme-chalk/index.css'
+```
+
+## 6. 组件库改完后，如何刷新联调结果
+
+如果你在当前仓库又改了代码，需要按下面顺序刷新：
+
+1. 回到组件库仓库重新构建
+2. 回到业务项目重新安装 `.release/`
+3. 重新启动业务项目，或至少重启开发服务
+
+命令示例：
+
+```bash
+# 组件库仓库
+npm run build
+
+# 业务项目仓库
+npm install ../data-ui-v2/.release --no-save
+```
+
+如果发现业务项目里还是旧内容，可以再执行一次卸载后重装：
+
+```bash
+npm uninstall @xq-labs/data-ui-v2
+npm install ../data-ui-v2/.release --no-save
+```
+
+## 7. 联调结束后如何恢复
+
+联调完成后，建议把业务项目恢复成正式依赖来源。
+
+如果原来就是 npm 正式版本，直接重新安装：
+
+```bash
+npm install @xq-labs/data-ui-v2
+```
+
+恢复后建议顺手检查：
+
+- `package.json`
+- `package-lock.json`
+
+确认没有残留本地临时依赖路径。
+
+## 8. 常见问题
+
+### 8.1 为什么不直接安装仓库根目录
+
+因为当前仓库真正用于发布的内容统一归档在 `.release/`。
+
+直接安装根目录时，联调结果不一定等于真实发布结果，容易把源码工作区和发布产物结构混在一起。
+
+### 8.2 为什么我改了组件代码，业务项目没更新
+
+因为业务项目安装的是某一次构建后的产物，不会自动跟随源码变化。
+
+每次改完后，都需要重新执行：
+
+```bash
+npm run build
+npm install ../data-ui-v2/.release --no-save
+```
+
+### 8.3 为什么这里不推荐 `npm link` 或 `yalc`
+
+这份文档针对的是“一天内的临时联调”。
+
+在这个场景下，直接安装 `.release/`：
+
+- 步骤最少
+- 最接近真实发包结果
+- 清理也最简单
+
+## 9. 最短操作路径
+
+如果只是想快速验证一次，直接按下面执行：
+
+```bash
+# 组件库仓库
+npm run build
+
+# 业务项目仓库
+npm install ../data-ui-v2/.release --no-save
+```
+
+联调结束后：
+
+```bash
+npm install @xq-labs/data-ui-v2
+```

package/docs/examples/pie-chart.md

@@ -29,7 +29,8 @@ Playground 中 `PieChart` 采用分组路由组织，按能力查阅：
     maxHeight,
     hideZeroValueSlices,
     labelOptions,
-    customOption
+    customOption,
+    stateConfig
   }"
 />
 ```
@@ -44,29 +45,66 @@ Playground 中 `PieChart` 采用分组路由组织，按能力查阅：
 - `hideZeroValueSlices`：3D 下是否隐藏 0 值扇区。
 - `labelOptions`：标签与引导线细节（格式、线长、颜色等）。
 - `customOption`：ECharts 细节覆盖（标题、提示、图例等）。
+- `stateConfig`：统一收拢空态文案、空态图和 loading 文案。
+
+推荐结构：
+
+```js
+const stateConfig = {
+  empty: {
+    text: '暂无占比数据',
+    image: 'https://example.com/pie-empty.png'
+  },
+  loading: {
+    text: '饼图加载中...'
+  }
+}
+```
 
 ## 2.1 3D 依赖说明
 
-3D 饼图需要安装 echarts-gl，依赖包名为 `echarts-gl`。
+如果业务页面要使用 3D `PieChart`，请先安装 `echarts-gl`，并引入 3D 桥接入口：
 
-只使用 2D 饼图、环图、玫瑰图时不需要安装 `echarts-gl`。
+```js
+import '@xq-labs/data-ui-v2/pie-chart/3d-runtime'
+```
 
-如果业务侧需要启用 3D 饼图，请额外安装：
+推荐直接写在**业务页面**顶部。
 
-```bash
-npm install echarts-gl
-```
+如果项目多个页面都会用到 3D `PieChart`，
+也可以在应用入口统一引入这个桥接入口。
+
+包内保留 `pie-chart/3d-runtime.js` 物理入口，
+用于兼容不识别 `package.json#exports` 的老 webpack / Vue CLI 链路。
+
+只使用 2D 饼图、环图、玫瑰图时，不需要引入 `echarts-gl`。
 
 ## 3. 如何自定义（推荐顺序）
 
 1. **优先公开 props**：先用 `variant`、`dimension`、`preset`、高度参数表达业务语义。
 2. **其次 `labelOptions`**：标签文案、引导线样式优先在这里完成。
-3. **最后 `customOption`**：仅用于补充 ECharts 展示细节。
+3. **状态文案统一交给 `stateConfig`**：空态图、空态文案、loading 文案不要分散到多个字段。
+4. **最后 `customOption`**：仅用于补充 ECharts 展示细节。
 
 不建议业务侧直接拼接或重写内部 `series`，避免覆盖组件内置能力与升级兼容性。
 
+默认 hover tooltip 已内置为白底阴影卡片，
+内容为“彩色圆点 + 名称:值”，例如 `● 已完成:140`。
+如需展示百分比或单位，请通过 `customOption.tooltip.formatter` 覆盖。
+
+## 3.1 3D 运行时失败的空态优先级
+
+当 `dimension="3d"` 且业务还没有先引入 3D 桥接入口时：
+
+1. `PieChart` 会优先显示组件内部错误文案。
+2. `stateConfig.empty.image` 仍然生效。
+3. `stateConfig.loading.text` 仍然生效。
+
+也就是说，业务可以继续自定义空态图，但不能覆盖这类
+“请先在业务页面中执行 `import '@xq-labs/data-ui-v2/pie-chart/3d-runtime'`”提示。
+
 ## 4. 可执行验收要点
 
 - 页面分组名称与路由一致：基础用法、2D 形态、3D 能力、标签与引导线、customOption 与自定义、实验室。
-- 文档示例包含 `hideZeroValueSlices` 与 `customOption`。
-- 文档明确实验室边界与推荐自定义顺序。
+- 文档示例包含 `hideZeroValueSlices`、`stateConfig` 与 `customOption`。
+- 文档明确实验室边界与推荐自定义顺序。

package/docs/examples/radar-chart.md

@@ -0,0 +1,97 @@
+# RadarChart 示例说明（对齐 Playground Demo 库）
+
+## 1. 路由与分组
+
+Playground 中 `RadarChart` 按分组路由组织：
+
+- 基础用法：`/radar-chart/basic`
+- customOption 与自定义：`/radar-chart/custom`
+- 实验室：`/radar-chart/lab`
+
+> 实验室边界：仅用于调试/验证，不作为推荐业务写法。
+
+## 2. 外部配置怎么传
+
+业务侧通过公开 props（推荐 `v-bind`）传入：
+
+```vue
+<RadarChart
+  v-bind="{
+    data,
+    indicators,
+    nameKey,
+    variant,
+    preset,
+    colors,
+    customOption,
+    stateConfig
+  }"
+/>
+```
+
+关键字段：
+
+- `data`：雷达图业务数据数组，每一项代表一个系列。
+- `indicators`：雷达指标配置，`key` 用于映射 `data` 中的字段。
+- `nameKey`：系列名称字段，默认 `name`。
+- `variant`：`area` / `line`。
+- `preset`：`compare` / `score`。
+- `colors`：组件级系列色板，按数据顺序分配。
+- `customOption`：ECharts 展示细节覆盖。
+- `stateConfig`：统一收拢空态文案、空态图和 loading 文案。
+
+推荐结构：
+
+```js
+const indicators = [
+  { key: 'quality', name: '质量', max: 100 },
+  { key: 'efficiency', name: '效率', max: 100 },
+  { key: 'cost', name: '成本控制', max: 100 },
+  { key: 'risk', name: '风险控制', max: 100 }
+]
+
+const data = [
+  {
+    name: '本月',
+    quality: 86,
+    efficiency: 78,
+    cost: 92,
+    risk: 70
+  }
+]
+
+const colors = ['#6B98F8', '#FF8A5B']
+```
+
+## 3. 颜色配置
+
+颜色优先级：
+
+```text
+data[i].color → colors[index] → DEFAULT_COLORS[index]
+```
+
+推荐做法：
+
+- 页面统一色板用 `colors`。
+- 单个系列需要强调时，用 `data[i].color`。
+- 常规业务不要直接拼 ECharts `series.data.itemStyle`。
+- 完全定制时再使用 `customOption.series`。
+
+## 4. 如何自定义（推荐顺序）
+
+1. **优先 `indicators` 表达指标语义**：先确定指标字段、名称、最大值与最小值。
+2. **用 `data` 表达业务系列**：每一项代表一个对象，例如本月、上月、目标值。
+3. **用 `colors` 控制系列色板**：保持页面整体视觉一致。
+4. **用 `variant` 选择视觉形态**：`area` 更适合画像展示，`line` 更适合减少遮挡。
+5. **`stateConfig` 收拢状态文案**：空态图、空态文案、loading 文案统一从这里传。
+6. **`customOption` 补充细节**：用于 title、tooltip、radar、series 等展示项。
+
+不建议业务直接维护 ECharts 原生 `value` 数组，容易和指标顺序错位。
+
+## 5. 可执行验收要点
+
+- 页面分组名称与路由一致：基础用法、customOption 与自定义、实验室。
+- 文档示例包含 `indicators`、`colors`、`customOption` 与 `stateConfig`。
+- 文档明确 `data[i].color → colors[index] → DEFAULT_COLORS[index]` 的颜色优先级。
+- 文档明确实验室边界与推荐自定义顺序。

package/es/bar-line-chart/index.js

@@ -1,11 +1,11 @@
 import '../../theme-chalk/index.css';
-import { B as BarLineChart } from '../index-6128787e.js';
-import { w as withInstall } from '../with-install-befebea5.js';
+import { B as BarLineChart } from '../index-d01ce220.js';
+import { w as withInstall } from '../with-install-e405b463.js';
 import 'echarts/core';
 import 'echarts/charts';
 import 'echarts/components';
 import 'echarts/renderers';
-import '../colors-ca059479.js';
+import '../colors-ec0ad9ce.js';
 
 var BarLineChartComponent = withInstall(BarLineChart);
 var install = BarLineChartComponent.install;

package/es/base-chart/index.js

@@ -1,5 +1,5 @@
 import '../../theme-chalk/index.css';
-import { w as withInstall, B as BaseChart } from '../with-install-befebea5.js';
+import { w as withInstall, B as BaseChart } from '../with-install-e405b463.js';
 import 'echarts/core';
 
 var BaseChartComponent = withInstall(BaseChart);

package/es/{colors-ca059479.js → colors-ec0ad9ce.js}

@@ -62,6 +62,15 @@ function _toPropertyKey(t) {
   var i = _toPrimitive(t, "string");
   return "symbol" == typeof i ? i : i + "";
 }
+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);
+}
 function _unsupportedIterableToArray(r, a) {
   if (r) {
     if ("string" == typeof r) return _arrayLikeToArray(r, a);
@@ -112,4 +121,4 @@ function mergeChartOption(baseOption, presetOption, customOption) {
 
 var DEFAULT_COLORS = ['#8979ff', '#ff928a', '#3cc3df', '#ffae4c', '#5c7cfa', '#5dd39e', '#8064d8', '#26b7d8', '#238ff2', '#f6c93d', '#59c5b5', '#5a7cc4', '#f2953f', '#82c65b', '#cf7a78', '#63c5d2', '#cfb291', '#2fa0bf', '#50a579', '#7869bd'];
 
-export { DEFAULT_COLORS as D, _objectSpread2 as _, _toConsumableArray as a, isEmptyData as i, mergeChartOption as m };
+export { DEFAULT_COLORS as D, _objectSpread2 as _, _toConsumableArray as a, _typeof as b, isEmptyData as i, mergeChartOption as m };