@beppla/tapas-ui 1.5.9 → 1.5.11

package/package/module/ComboChart/README.md

@@ -0,0 +1,124 @@
+# ComboChart
+
+组合图表组件，支持在同一图表中混合展示柱状图和折线图。**仅支持 Web 平台**，基于 recharts 的 ComposedChart 实现。Native 端会显示提示信息，建议分别使用 BarChart 和 LineChart。
+
+## 功能特性
+
+- ✅ 柱状图和折线图混合展示
+- ✅ 支持多个柱状图系列和折线图系列
+- ✅ 支持双 Y 轴（left / right），展示不同量级数据
+- ✅ 图例支持 top / bottom / left / right 四个位置
+- ✅ 网格线显示控制
+- ✅ X 轴标签旋转角度和显示间隔控制
+- ✅ Y 轴格式化函数
+- ✅ 折线图样式配置（线宽、数据点大小、隐藏数据点）
+- ✅ 响应式容器（ResponsiveContainer）
+- ✅ Tooltip 悬停提示
+- ✅ 空数据友好提示
+- ✅ **仅支持 Web 平台**（使用 recharts 库）
+
+## 安装使用
+
+```tsx
+import { ComboChart } from '@beppla/tapas-ui/components/ComboChart';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| categories | `string[]` | (必填) | X 轴分类标签数组 |
+| series | `ComboChartDataSeries[]` | (必填) | 数据系列数组 |
+| width | `number` | - | 图表宽度 |
+| height | `number` | `350` | 图表高度 |
+| showGrid | `boolean` | `true` | 是否显示网格线 |
+| showLabels | `boolean` | `true` | 是否显示 X 轴标签 |
+| showLegend | `boolean` | `true` | 是否显示图例 |
+| legendPosition | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | 图例位置 |
+| xAxisAngle | `number` | `-45` | X 轴标签旋转角度（负数逆时针） |
+| xAxisInterval | `number \| 'preserveStartEnd' \| 'preserveStart' \| 'preserveEnd'` | `0` | X 轴标签显示间隔 |
+| yAxisFormat | `(value: number) => string` | `(value) => value.toString()` | Y 轴格式化函数 |
+| style | `any` | - | 容器样式 |
+| testID | `string` | - | 测试标识 |
+
+### ComboChartDataSeries
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| name | `string` | 系列名称（必填），显示在图例中 |
+| data | `number[]` | 数据数组（必填），长度应与 categories 一致 |
+| type | `'bar' \| 'line'` | 图表类型（必填） |
+| color | `string` | 系列颜色 |
+| yAxisId | `'left' \| 'right'` | 绑定的 Y 轴，默认 left |
+| strokeWidth | `number` | 折线宽度（默认 2，仅 line 类型） |
+| dotRadius | `number` | 数据点半径（默认 4，仅 line 类型） |
+| activeDotRadius | `number` | 活动数据点半径（默认 6，仅 line 类型） |
+| hideDot | `boolean` | 隐藏数据点（仅 line 类型） |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<ComboChart
+  categories={['Store A', 'Store B', 'Store C', 'Store D', 'Store E']}
+  series={[
+    { name: 'Revenue', data: [58000, 73000, 68000, 48000, 80000], type: 'bar', color: '#FFB800' },
+    { name: 'Cost', data: [25000, 35000, 45000, 30000, 40000], type: 'line', color: '#E91E63' },
+  ]}
+  height={350}
+/>
+```
+
+### 多系列组合
+
+```tsx
+<ComboChart
+  categories={['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun']}
+  series={[
+    { name: 'Revenue', data: [50000, 60000, 70000, 55000, 65000, 75000], type: 'bar', color: '#FF6B00' },
+    { name: 'Cost', data: [30000, 35000, 40000, 32000, 38000, 42000], type: 'bar', color: '#0066CC' },
+    { name: 'Profit', data: [20000, 25000, 30000, 23000, 27000, 33000], type: 'line', color: '#00B894' },
+    { name: 'Target', data: [22000, 24000, 28000, 25000, 29000, 35000], type: 'line', color: '#6C5CE7' },
+  ]}
+  height={400}
+/>
+```
+
+### 双 Y 轴
+
+```tsx
+<ComboChart
+  categories={['Q1', 'Q2', 'Q3', 'Q4']}
+  series={[
+    { name: 'Revenue', data: [150000, 180000, 210000, 240000], type: 'bar', color: '#FF6B00', yAxisId: 'left' },
+    { name: 'Growth (%)', data: [15, 20, 17, 14], type: 'line', color: '#0066CC', yAxisId: 'right' },
+  ]}
+  height={350}
+/>
+```
+
+### 长标签旋转 + Y 轴格式化
+
+```tsx
+<ComboChart
+  categories={['Store name A', 'Store name B', 'Store name C']}
+  series={[
+    { name: 'Revenue', data: [850000, 680000, 730000], type: 'bar', color: '#FFB800' },
+    { name: 'Cost', data: [15000, 12000, 18000], type: 'line', color: '#D63031', strokeWidth: 2, dotRadius: 4 },
+  ]}
+  xAxisAngle={-90}
+  yAxisFormat={(v) => v >= 1000 ? `${(v / 1000).toFixed(0)}k` : v.toString()}
+  height={500}
+/>
+```
+
+## 注意事项
+
+- **仅支持 Web 平台**，Native 端显示提示信息，建议在移动端分别使用 BarChart 和 LineChart
+- 依赖 `recharts` 库，需确保项目已安装
+- 设置 `yAxisId: 'right'` 的系列会自动启用右侧 Y 轴
+- 默认 X 轴标签旋转 -45 度以避免长标签重叠，`xAxisAngle` 为 0 时不旋转
+- 底部 margin 会根据 `xAxisAngle` 自动调整以避免标签被截断
+- 折线图样式属性（strokeWidth、dotRadius 等）使用 `??` 运算符设默认值，传 `0` 有效
+- 所有 series 的 data 数组长度应与 categories 数组长度一致

package/package/module/DEPENDENCY_WARNINGS.md

@@ -0,0 +1,242 @@
+# 依赖警告处理指南
+
+## 常见警告及解决方案
+
+### 1. `Module not found: Can't resolve 'd3-hierarchy'`
+
+**原因：** WordCloud 的气泡模式需要 `d3-hierarchy`，但该依赖被标记为可选，不会自动安装。
+
+**解决方案：**
+
+#### 方案 1：安装依赖（推荐）
+
+如果你需要使用气泡词云功能：
+
+```bash
+npm install d3-hierarchy
+# 或
+yarn add d3-hierarchy
+```
+
+#### 方案 2：忽略警告
+
+如果你只使用传统词云，可以忽略此警告，或在 webpack 配置中屏蔽：
+
+```js
+// webpack.config.js
+module.exports = {
+  plugins: [
+    new webpack.IgnorePlugin({
+      resourceRegExp: /^d3-hierarchy$/,
+      contextRegExp: /@beppla\/tapas-ui/,
+    }),
+  ],
+};
+```
+
+#### 方案 3：条件导入
+
+在代码中使用时动态检测：
+
+```tsx
+import { WordCloud } from '@beppla/tapas-ui';
+
+// 只使用传统模式，不会触发 d3-hierarchy 加载
+<WordCloud
+  variant="traditional"  // 默认值
+  words={data}
+/>
+
+// 如果使用气泡模式，确保已安装 d3-hierarchy
+<WordCloud
+  variant="bubble"  // 需要 d3-hierarchy
+  words={data}
+/>
+```
+
+---
+
+### 2. `Module not found: NestedPieChart` 路径错误
+
+**错误示例：**
+
+```tsx
+// ❌ 错误：不要使用相对路径访问 node_modules 内部文件
+const m = require("../../../../../node_modules/@beppla/tapas-ui/commonjs/PieChart/NestedPieChart");
+```
+
+**原因：** 使用了错误的导入路径。
+
+**正确导入方式：**
+
+```tsx
+// ✅ 正确：从包的根路径导入
+import { NestedPieChart } from '@beppla/tapas-ui';
+
+// ✅ 或者从子路径导入（如果需要）
+import { NestedPieChart } from '@beppla/tapas-ui/PieChart';
+```
+
+**如果需要动态导入：**
+
+```tsx
+// ✅ 正确的动态导入
+let NestedPieChart;
+try {
+  if (Platform.OS === 'web') {
+    // 从包的正确导出路径导入
+    const module = await import('@beppla/tapas-ui');
+    NestedPieChart = module.NestedPieChart;
+  }
+} catch (error) {
+  console.warn('NestedPieChart not available');
+}
+```
+
+---
+
+## 完整依赖列表
+
+### WordCloud 组件
+
+| 依赖 | 用途 | 平台 | 是否必需 |
+|------|------|------|----------|
+| `react-wordcloud` | 传统词云 | Web | 可选 |
+| `d3-cloud` | 传统词云 | Web | 可选 |
+| `d3-hierarchy` | 气泡词云 | Web | 可选 |
+| `react-native-svg` | 所有模式 | RN | 可选 |
+
+### PieChart / NestedPieChart 组件
+
+| 依赖 | 用途 | 平台 | 是否必需 |
+|------|------|------|----------|
+| `recharts` | 图表渲染 | Web | 可选 |
+| `react-native-svg` | 图表渲染 | RN | 可选 |
+| `react-native-svg-charts` | 图表渲染 | RN | 可选 |
+
+### LineChart / BarChart / ComboChart 组件
+
+| 依赖 | 用途 | 平台 | 是否必需 |
+|------|------|------|----------|
+| `recharts` | 图表渲染 | Web | 可选 |
+| `react-native-svg-charts` | 图表渲染 | RN | 可选 |
+
+---
+
+## 按需安装策略
+
+### 策略 1：最小安装
+
+只使用基础组件（不包含图表）：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+```
+
+### 策略 2：Web 图表
+
+使用 Web 端图表组件：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+npm install recharts d3-hierarchy react-wordcloud
+```
+
+### 策略 3：RN 图表
+
+使用 React Native 图表组件：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+npm install react-native-svg react-native-svg-charts
+```
+
+### 策略 4：全平台图表（推荐）
+
+同时支持 Web 和 RN：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+
+# Web 依赖
+npm install recharts d3-hierarchy react-wordcloud d3-cloud
+
+# RN 依赖
+npm install react-native-svg react-native-svg-charts
+```
+
+---
+
+## 生产环境优化
+
+### Tree Shaking
+
+确保你的打包工具支持 tree-shaking，未使用的组件不会被打包：
+
+```js
+// 只导入需要的组件
+import { WordCloud, NestedPieChart } from '@beppla/tapas-ui';
+
+// ✅ 只有 WordCloud 和 NestedPieChart 会被打包
+// ✅ 未使用的组件（如 BarChart）不会被打包
+```
+
+### 按需加载
+
+对于大型应用，可以使用动态导入：
+
+```tsx
+// 懒加载气泡词云
+const BubbleCloudPage = lazy(() => 
+  import('./pages/BubbleCloud').then(module => ({
+    default: module.BubbleCloudPage
+  }))
+);
+```
+
+---
+
+## 常见问题
+
+### Q: 为什么不将这些依赖设为必需依赖？
+
+**A:** 这些依赖较大（如 `recharts` ~500KB），并且不是所有用户都需要所有功能。将它们设为可选依赖可以：
+- 减小默认包体积
+- 让用户按需安装
+- 支持更灵活的使用场景
+
+### Q: 警告会影响应用运行吗？
+
+**A:** 不会。这些警告只是提示缺少可选依赖，不影响：
+- 已安装依赖的功能正常使用
+- 应用的其他部分
+- 构建和部署流程
+
+### Q: 如何确认依赖是否正确安装？
+
+**A:** 运行以下命令：
+
+```bash
+# 检查 d3-hierarchy
+npm list d3-hierarchy
+
+# 检查 recharts
+npm list recharts
+
+# 检查所有 @beppla/tapas-ui 依赖
+npm list --depth=0 | grep -E "d3|recharts|svg"
+```
+
+---
+
+## 获取帮助
+
+如果遇到其他依赖问题：
+
+1. 查看 [完整文档](https://github.com/your-repo/tapas-ui)
+2. 搜索 [GitHub Issues](https://github.com/your-repo/tapas-ui/issues)
+3. 提交新的 Issue 并附上：
+   - 错误信息
+   - 你的 package.json
+   - 使用的平台（Web / RN）
+   - 组件代码示例

package/package/module/DashboardCard/README.md

@@ -0,0 +1,120 @@
+# DashboardCard
+
+仪表板卡片组件，支持 Header / Content / Footer 三段式布局，适用于数据概览、功能模块入口等场景。
+
+## 功能特性
+
+- ✅ 三段式布局：Header（图标+标题+描述标签+操作区）、Content、Footer
+- ✅ 鼠标悬停阴影效果（Web 端 Hoverable 实现）
+- ✅ 支持禁用状态，自动调整所有文本和图标颜色
+- ✅ Header 支持自定义操作区域（React 节点），带独立点击事件
+- ✅ Header 支持多个描述标签数组
+- ✅ Footer 支持标题+描述+图标按钮
+- ✅ 整卡可点击，支持 onCardPress 回调
+- ✅ 标题单行截断，防止溢出
+- ✅ 高度自定义样式：cardContainerStyle / cardStyle / contentStyle / headerStyle / titleStyle
+
+## 安装使用
+
+```tsx
+import DashboardCard from '@beppla/tapas-ui/components/DashboardCard/DashboardCard';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| header | `{ icon?: string; title?: string; description?: string[]; action?: ReactNode; onPressAction?: (value: any) => void; actionStyle?: StyleProp<ViewStyle> }` | - | 头部配置 |
+| content | `string` | - | 内容区域文本 |
+| footer | `{ title?: string; description?: string; onPress?: () => void; icon?: string }` | - | 底部配置 |
+| onCardPress | `() => void` | - | 卡片点击回调 |
+| disabled | `boolean` | - | 是否禁用 |
+| testID | `string` | - | 测试标识 |
+| cardContainerStyle | `StyleProp<ViewStyle>` | - | 卡片外层容器样式（Hoverable 层） |
+| cardStyle | `StyleProp<ViewStyle>` | - | 卡片主体样式 |
+| contentStyle | `StyleProp<ViewStyle>` | - | 内容区域样式 |
+| headerStyle | `StyleProp<ViewStyle>` | - | 头部区域样式 |
+| titleStyle | `StyleProp<ViewStyle>` | - | 标题区域样式 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<DashboardCard
+  header={{
+    icon: 'restaurant_menu',
+    title: '订单管理',
+    description: ['今日订单', '待处理'],
+  }}
+  content="查看订单详情"
+  footer={{
+    title: '总计',
+    description: '128 单',
+    icon: 'back',
+    onPress: () => console.log('Footer pressed'),
+  }}
+  onCardPress={() => console.log('Card pressed')}
+/>
+```
+
+### 带操作按钮
+
+```tsx
+<DashboardCard
+  header={{
+    icon: 'dashboard',
+    title: '数据概览',
+    action: <Text>...</Text>,
+    onPressAction: (value) => console.log('Action:', value),
+  }}
+  footer={{
+    title: '更新时间',
+    description: '5 分钟前',
+  }}
+/>
+```
+
+### 禁用状态
+
+```tsx
+<DashboardCard
+  disabled
+  header={{
+    icon: 'lock',
+    title: '功能暂不可用',
+  }}
+  contentStyle={{ padding: 16 }}
+  cardStyle={{ width: 400 }}
+/>
+```
+
+### 自定义宽度和内容
+
+```tsx
+<DashboardCard
+  cardStyle={{ width: 400 }}
+  contentStyle={{ padding: 16 }}
+  header={{
+    icon: 'restaurant_menu',
+    title: '自定义宽度卡片',
+    description: ['标签1', '标签2'],
+  }}
+  content="自定义内容区域"
+  footer={{
+    title: '底部标题',
+    description: '底部描述',
+    icon: 'back',
+    onPress: () => console.log('Navigate'),
+  }}
+/>
+```
+
+## 注意事项
+
+- 禁用状态下 `onCardPress` 和 `footer.onPress` 均不会触发
+- `header.description` 为字符串数组，每项显示为独立标签，空值会被过滤
+- `footer.icon` 设置后才会渲染底部图标按钮（带旋转 180 度样式）
+- `content` 属性为 string 时自动渲染为 Text，也支持传入 ReactNode
+- 悬停效果在禁用状态下不会显示
+- 组件使用 `@rneui/themed` 主题系统，需在 ThemeProvider 内使用