@beppla/tapas-ui 1.4.33 → 1.4.35

package/components/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/components/WordCloud/README.md

@@ -30,15 +30,86 @@
 
 ## 安装依赖
 
+### 必需依赖
+
+```bash
+npm install react react-native
+```
+
+### WordCloud 可选依赖
+
+根据你的使用场景安装对应的依赖：
+
+#### 传统词云（Web 端）
+
 ```bash
 # Web 端需要
-npm install react-wordcloud d3-hierarchy
+npm install react-wordcloud d3-cloud
+```
+
+#### 气泡词云（Web 端）
+
+```bash
+# Web 端气泡模式需要
+npm install d3-hierarchy
+```
+
+#### React Native 端
+
+```bash
+# RN 端需要（两种模式都需要）
+npm install react-native-svg
+```
+
+### 完整安装（推荐）
+
+如果你想使用所有功能，建议一次性安装：
+
+```bash
+# Web 端完整依赖
+npm install react-wordcloud d3-cloud d3-hierarchy
 
-# React Native 端需要
+# React Native 端依赖
 npm install react-native-svg
 ```
 
-## 基本用法
+### ⚠️ 依赖说明
+
+- 这些依赖被标记为 `optional`，不会自动安装
+- 如果缺少依赖，组件会优雅降级并显示提示信息
+- **警告处理**：如果你看到 `Module not found: Can't resolve 'd3-hierarchy'` 警告，这是正常的。你可以：
+  - **方案 1（推荐）**：安装 `d3-hierarchy` 以使用气泡词云功能
+  - **方案 2**：如果只使用传统词云，可以忽略这个警告（不影响使用）
+  - **方案 3**：在 webpack 配置中添加 `IgnorePlugin` 忽略警告（见下方）
+
+### 忽略警告（Webpack）
+
+如果你不需要气泡词云功能，可以在 webpack 配置中忽略警告：
+
+```js
+// webpack.config.js
+module.exports = {
+  plugins: [
+    new webpack.IgnorePlugin({
+      resourceRegExp: /^d3-hierarchy$/,
+      contextRegExp: /@beppla\/tapas-ui/,
+    }),
+  ],
+};
+```
+
+或者使用 `externals`：
+
+```js
+// webpack.config.js
+module.exports = {
+  externals: {
+    'd3-hierarchy': 'd3-hierarchy',
+  },
+};
+```
+
+---
 
 ### 传统词云
 

package/components/WordCloud/WordCloud.tsx

@@ -14,7 +14,7 @@ import { View, StyleSheet, Platform, Text as RNText } from 'react-native';
 
 // 动态导入依赖
 let Svg: any, Text: any, G: any, Circle: any;
-let D3WordCloud: any, d3Hierarchy: any, d3Pack: any;
+let D3WordCloud: any;
 
 if (Platform.OS === 'web') {
   // Web 端使用 react-wordcloud 和 d3-hierarchy
@@ -24,14 +24,6 @@ if (Platform.OS === 'web') {
   } catch (e) {
     // console.warn('react-wordcloud not available for Web', e);
   }
-  
-  try {
-    const d3 = require('d3-hierarchy');
-    d3Hierarchy = d3.hierarchy;
-    d3Pack = d3.pack;
-  } catch (e) {
-    // console.warn('d3-hierarchy not available for Web', e);
-  }
 } else {
   // RN 端使用 react-native-svg
   try {
@@ -277,48 +269,130 @@ export const WordCloud: React.FC<WordCloudProps> = ({
     const viewWidth = width || 600;
     const viewHeight = height;
 
-    // Web 端使用 D3 pack 布局
-    if (Platform.OS === 'web' && d3Hierarchy && d3Pack) {
-      const packLayout = d3Pack()
-        .size([viewWidth, viewHeight])
-        .padding(bubblePadding);
+    // Web 端使用类似传统词云的中心散开布局
+    if (Platform.OS === 'web') {
+      // 使用自定义算法：从中心向外螺旋式布局（类似传统词云）
+      const centerX = viewWidth / 2;
+      const centerY = viewHeight / 2;
+      
+      const layoutBubbles = () => {
+        const positioned: Array<{
+          data: any;
+          x: number;
+          y: number;
+          r: number;
+        }> = [];
+
+        // 按 value 排序，大的先放置
+        const sortedData = [...bubbleData].sort((a, b) => b.value - a.value);
+
+        sortedData.forEach((data, index) => {
+          let x = centerX;
+          let y = centerY;
+          let placed = false;
+
+          if (index === 0) {
+            // 第一个气泡放在正中心
+            placed = true;
+          } else {
+            // 从中心开始螺旋向外寻找位置
+            for (let attempt = 0; attempt < 500; attempt++) {
+              const angle = attempt * 0.5; // 螺旋角度
+              const distance = Math.sqrt(attempt) * (data.radius * 0.6 + bubblePadding);
+              x = centerX + distance * Math.cos(angle);
+              y = centerY + distance * Math.sin(angle);
+
+              // 检查边界
+              if (x - data.radius < 0 || x + data.radius > viewWidth ||
+                  y - data.radius < 0 || y + data.radius > viewHeight) {
+                continue;
+              }
+
+              // 检查是否与已有气泡重叠
+              const overlaps = positioned.some(p => {
+                const dx = x - p.x;
+                const dy = y - p.y;
+                const dist = Math.sqrt(dx * dx + dy * dy);
+                return dist < (data.radius + p.r + bubblePadding);
+              });
+
+              if (!overlaps) {
+                placed = true;
+                break;
+              }
+            }
+
+            // 如果还是找不到位置，在可用空间随机放置
+            if (!placed) {
+              for (let i = 0; i < 100; i++) {
+                const randomAngle = Math.random() * Math.PI * 2;
+                const randomDistance = Math.random() * Math.min(viewWidth, viewHeight) * 0.4;
+                x = centerX + randomDistance * Math.cos(randomAngle);
+                y = centerY + randomDistance * Math.sin(randomAngle);
+
+                if (x - data.radius >= 0 && x + data.radius <= viewWidth &&
+                    y - data.radius >= 0 && y + data.radius <= viewHeight) {
+                  const overlaps = positioned.some(p => {
+                    const dx = x - p.x;
+                    const dy = y - p.y;
+                    const dist = Math.sqrt(dx * dx + dy * dy);
+                    return dist < (data.radius + p.r + bubblePadding * 0.5);
+                  });
+                  
+                  if (!overlaps) {
+                    placed = true;
+                    break;
+                  }
+                }
+              }
+            }
+          }
 
-      const root = d3Hierarchy({ children: bubbleData })
-        .sum((d: any) => d.radius * d.radius);
+          positioned.push({ 
+            data, 
+            x: placed ? x : centerX, 
+            y: placed ? y : centerY, 
+            r: data.radius 
+          });
+        });
 
-      const nodes = packLayout(root).leaves();
+        return positioned;
+      };
+
+      const positionedBubbles = layoutBubbles();
 
       return (
-        <View style={[styles.container, { height, width: viewWidth }, style]} testID={testID}>
+        <View style={[{ height, width: viewWidth, backgroundColor: 'transparent' }, style]} testID={testID}>
           <svg width={viewWidth} height={viewHeight} style={{ backgroundColor: 'transparent' }}>
-            {nodes.map((node: any, index: number) => {
-              const data = node.data;
+            {positionedBubbles.map((bubble, index) => {
+              const adjustedFontSize = Math.max(10, Math.min(24, bubble.r * 0.35));
+              
               return (
-                <g key={index} onClick={() => onBubbleClick?.(data)}>
+                <g key={index} onClick={() => onBubbleClick?.(bubble.data)}>
                   <circle
-                    cx={node.x}
-                    cy={node.y}
-                    r={node.r}
-                    fill={data.bubbleColor}
+                    cx={bubble.x}
+                    cy={bubble.y}
+                    r={bubble.r}
+                    fill={bubble.data.bubbleColor}
                     stroke="none"
                     style={{ cursor: onBubbleClick ? 'pointer' : 'default' }}
                   />
                   <text
-                    x={node.x}
-                    y={node.y}
+                    x={bubble.x}
+                    y={bubble.y}
                     textAnchor="middle"
                     dominantBaseline="middle"
-                    fontSize={data.fontSize}
-                    fill={data.textColor}
+                    fontSize={adjustedFontSize}
+                    fill={bubble.data.textColor}
                     fontFamily={fontFamily}
                     fontWeight="400"
                     style={{
                       userSelect: 'none',
                       pointerEvents: 'none',
-                      maxWidth: node.r * 1.8,
+                      maxWidth: bubble.r * 1.8,
                     }}
                   >
-                    {data.displayText}
+                    {bubble.data.displayText}
                   </text>
                 </g>
               );
@@ -328,9 +402,12 @@ export const WordCloud: React.FC<WordCloudProps> = ({
       );
     }
 
-    // RN 端使用简化的圆形打包算法
-    if (Platform.OS !== 'web' && Svg && Circle && Text) {
-      // 简化的圆形打包布局算法
+    // RN 端使用相同的中心散开布局
+    if (Svg && Circle && Text) {
+      // 从中心向外螺旋式布局（与 Web 端一致）
+      const centerX = viewWidth / 2;
+      const centerY = viewHeight / 2;
+      
       const layoutBubbles = () => {
         const positioned: Array<{
           data: any;
@@ -339,50 +416,77 @@ export const WordCloud: React.FC<WordCloudProps> = ({
           r: number;
         }> = [];
 
-        const sortedData = [...bubbleData].sort((a, b) => b.radius - a.radius);
-        const centerX = viewWidth / 2;
-        const centerY = viewHeight / 2;
+        // 按 value 排序，大的先放置
+        const sortedData = [...bubbleData].sort((a, b) => b.value - a.value);
 
         sortedData.forEach((data, index) => {
-          let x: number = 0;
-          let y: number = 0;
-          let attempts = 0;
-          const maxAttempts = 100;
+          let x = centerX;
+          let y = centerY;
+          let placed = false;
 
           if (index === 0) {
-            // 第一个气泡放在中心
-            x = centerX;
-            y = centerY;
+            // 第一个气泡放在正中心
+            placed = true;
           } else {
-            // 后续气泡使用螺旋算法寻找位置
-            while (attempts < maxAttempts) {
-              const angle = attempts * 0.5;
-              const spiralRadius = Math.sqrt(attempts + 1) * (data.radius + bubblePadding);
-              x = centerX + spiralRadius * Math.cos(angle);
-              y = centerY + spiralRadius * Math.sin(angle);
+            // 从中心开始螺旋向外寻找位置
+            for (let attempt = 0; attempt < 500; attempt++) {
+              const angle = attempt * 0.5;
+              const distance = Math.sqrt(attempt) * (data.radius * 0.6 + bubblePadding);
+              x = centerX + distance * Math.cos(angle);
+              y = centerY + distance * Math.sin(angle);
+
+              // 检查边界
+              if (x - data.radius < 0 || x + data.radius > viewWidth ||
+                  y - data.radius < 0 || y + data.radius > viewHeight) {
+                continue;
+              }
 
               // 检查是否与已有气泡重叠
               const overlaps = positioned.some(p => {
                 const dx = x - p.x;
                 const dy = y - p.y;
-                const distance = Math.sqrt(dx * dx + dy * dy);
-                return distance < (data.radius + p.r + bubblePadding);
+                const dist = Math.sqrt(dx * dx + dy * dy);
+                return dist < (data.radius + p.r + bubblePadding);
               });
 
               if (!overlaps) {
+                placed = true;
                 break;
               }
-              attempts++;
             }
 
-            // 如果找不到合适位置，强制放置
-            if (attempts >= maxAttempts) {
-              x = centerX + (Math.random() * viewWidth * 0.3 - viewWidth * 0.15);
-              y = centerY + (Math.random() * viewHeight * 0.3 - viewHeight * 0.15);
+            // 兜底：随机放置在中心周围
+            if (!placed) {
+              for (let i = 0; i < 100; i++) {
+                const randomAngle = Math.random() * Math.PI * 2;
+                const randomDistance = Math.random() * Math.min(viewWidth, viewHeight) * 0.4;
+                x = centerX + randomDistance * Math.cos(randomAngle);
+                y = centerY + randomDistance * Math.sin(randomAngle);
+
+                if (x - data.radius >= 0 && x + data.radius <= viewWidth &&
+                    y - data.radius >= 0 && y + data.radius <= viewHeight) {
+                  const overlaps = positioned.some(p => {
+                    const dx = x - p.x;
+                    const dy = y - p.y;
+                    const dist = Math.sqrt(dx * dx + dy * dy);
+                    return dist < (data.radius + p.r + bubblePadding * 0.5);
+                  });
+                  
+                  if (!overlaps) {
+                    placed = true;
+                    break;
+                  }
+                }
+              }
             }
           }
 
-          positioned.push({ data, x: x || 0, y: y || 0, r: data.radius });
+          positioned.push({ 
+            data, 
+            x: placed ? x : centerX, 
+            y: placed ? y : centerY, 
+            r: data.radius 
+          });
         });
 
         return positioned;