@beppla/tapas-ui 1.4.33 → 1.4.35

package/package/commonjs/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/commonjs/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/package/commonjs/WordCloud/WordCloud.js

@@ -21,7 +21,7 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
 
 // 动态导入依赖
 let Svg, Text, G, Circle;
-let D3WordCloud, d3Hierarchy, d3Pack;
+let D3WordCloud;
 if (_reactNative.Platform.OS === 'web') {
   // Web 端使用 react-wordcloud 和 d3-hierarchy
   try {
@@ -30,13 +30,6 @@ if (_reactNative.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 {
@@ -240,17 +233,86 @@ const WordCloud = ({
     const viewWidth = width || 600;
     const viewHeight = height;
 
-    // Web 端使用 D3 pack 布局
-    if (_reactNative.Platform.OS === 'web' && d3Hierarchy && d3Pack) {
-      const packLayout = d3Pack().size([viewWidth, viewHeight]).padding(bubblePadding);
-      const root = d3Hierarchy({
-        children: bubbleData
-      }).sum(d => d.radius * d.radius);
-      const nodes = packLayout(root).leaves();
+    // Web 端使用类似传统词云的中心散开布局
+    if (_reactNative.Platform.OS === 'web') {
+      // 使用自定义算法：从中心向外螺旋式布局（类似传统词云）
+      const centerX = viewWidth / 2;
+      const centerY = viewHeight / 2;
+      const layoutBubbles = () => {
+        const positioned = [];
+
+        // 按 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;
+                  }
+                }
+              }
+            }
+          }
+          positioned.push({
+            data,
+            x: placed ? x : centerX,
+            y: placed ? y : centerY,
+            r: data.radius
+          });
+        });
+        return positioned;
+      };
+      const positionedBubbles = layoutBubbles();
       return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
-        style: [styles.container, {
+        style: [{
           height,
-          width: viewWidth
+          width: viewWidth,
+          backgroundColor: 'transparent'
         }, style],
         testID: testID,
         children: /*#__PURE__*/(0, _jsxRuntime.jsx)("svg", {
@@ -259,34 +321,34 @@ const WordCloud = ({
           style: {
             backgroundColor: 'transparent'
           },
-          children: nodes.map((node, index) => {
-            const data = node.data;
+          children: positionedBubbles.map((bubble, index) => {
+            const adjustedFontSize = Math.max(10, Math.min(24, bubble.r * 0.35));
             return /*#__PURE__*/(0, _jsxRuntime.jsxs)("g", {
-              onClick: () => onBubbleClick?.(data),
+              onClick: () => onBubbleClick?.(bubble.data),
               children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("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'
                 }
               }), /*#__PURE__*/(0, _jsxRuntime.jsx)("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
                 },
-                children: data.displayText
+                children: bubble.data.displayText
               })]
             }, index);
           })
@@ -294,54 +356,75 @@ const WordCloud = ({
       });
     }
 
-    // RN 端使用简化的圆形打包算法
-    if (_reactNative.Platform.OS !== 'web' && Svg && Circle && Text) {
-      // 简化的圆形打包布局算法
+    // RN 端使用相同的中心散开布局
+    if (Svg && Circle && Text) {
+      // 从中心向外螺旋式布局（与 Web 端一致）
+      const centerX = viewWidth / 2;
+      const centerY = viewHeight / 2;
       const layoutBubbles = () => {
         const positioned = [];
-        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 = 0;
-          let y = 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,
+            x: placed ? x : centerX,
+            y: placed ? y : centerY,
             r: data.radius
           });
         });