@beppla/tapas-ui 1.5.10 → 1.5.11

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 内使用