@beppla/tapas-ui 1.4.32 → 1.4.33

package/components/WebViewBridge/index.tsx

@@ -0,0 +1,12 @@
+export { 
+  WebViewBridge, 
+  createWebViewInjectedScript,
+  handleNativeWebViewMessage,
+  type WebViewBridgeRef, 
+  type WebViewBridgeProps, 
+  type WebViewMessage,
+  type TapasSysMessage,
+  type LogLevel
+} from './WebViewBridge';
+export { useWebViewBridge, type UseWebViewBridgeOptions, type UseWebViewBridgeReturn } from './useWebViewBridge';
+

package/components/WebViewBridge/useWebViewBridge.ts

@@ -0,0 +1,145 @@
+/**
+ * useWebViewBridge - WebView 通信 Hook
+ * 
+ * 简化 WebViewBridge 的使用，提供便捷的消息发送和监听方法
+ */
+import { useCallback, useRef } from 'react';
+import { WebViewBridgeRef, WebViewMessage } from './WebViewBridge';
+
+export interface UseWebViewBridgeOptions {
+  /**
+   * 消息来源标识（用于标识 RN Web 模块）
+   * 这个值会作为消息的 from 字段发送给 tapas-sys
+   * 注意：如果使用 WebViewBridge 组件，from 应该在组件 props 中提供
+   */
+  from?: string;
+  
+  /**
+   * 消息监听回调
+   */
+  onMessage?: (message: WebViewMessage) => void;
+  
+  /**
+   * 特定消息类型的处理器映射
+   */
+  messageHandlers?: {
+    [messageType: string]: (message: WebViewMessage) => void;
+  };
+  
+  /**
+   * 是否启用 base64 加密（默认 true，符合 tapas-sys 解析格式）
+   */
+  enableBase64?: boolean;
+}
+
+export interface UseWebViewBridgeReturn {
+  /**
+   * WebViewBridge ref，需要传递给 WebViewBridge 组件
+   */
+  bridgeRef: React.RefObject<WebViewBridgeRef>;
+  
+  /**
+   * 发送消息
+   * @returns 是否发送成功
+   */
+  sendMessage: (type: string, payload?: unknown) => boolean;
+  
+  /**
+   * 获取运行环境
+   */
+  getEnvironment: () => 'webview' | 'iframe' | 'unknown';
+  
+  /**
+   * 注册消息处理器
+   */
+  registerHandler: (type: string, handler: (message: WebViewMessage) => void) => () => void;
+  
+  /**
+   * 消息处理函数，需要传递给 WebViewBridge 的 onMessage prop
+   */
+  handleMessage: (message: WebViewMessage) => void;
+  
+  /**
+   * 清理所有监听器和资源
+   */
+  cleanup: () => void;
+}
+
+/**
+ * WebView 通信 Hook
+ */
+export const useWebViewBridge = (
+  options: UseWebViewBridgeOptions = {}
+): UseWebViewBridgeReturn => {
+  const { onMessage, messageHandlers } = options;
+  const bridgeRef = useRef<WebViewBridgeRef>(null);
+  const handlersRef = useRef<Map<string, (message: WebViewMessage) => void>>(new Map());
+
+  // 发送消息
+  const sendMessage = useCallback((type: string, payload?: unknown): boolean => {
+    if (bridgeRef.current) {
+      return bridgeRef.current.sendMessage(type, payload);
+    }
+    // eslint-disable-next-line no-console
+    console.warn('useWebViewBridge: bridgeRef 未初始化，无法发送消息');
+    return false;
+  }, []);
+
+  // 获取运行环境
+  const getEnvironment = useCallback(() => {
+    if (bridgeRef.current) {
+      return bridgeRef.current.getEnvironment();
+    }
+    return 'unknown' as const;
+  }, []);
+
+  // 注册消息处理器
+  const registerHandler = useCallback((
+    type: string,
+    handler: (message: WebViewMessage) => void
+  ) => {
+    handlersRef.current.set(type, handler);
+    
+    // 返回取消注册函数
+    return () => {
+      handlersRef.current.delete(type);
+    };
+  }, []);
+
+  // 统一消息处理
+  const handleMessage = useCallback((message: WebViewMessage) => {
+    // 调用外部监听器
+    if (onMessage) {
+      onMessage(message);
+    }
+
+    // 调用特定类型的处理器
+    const typeHandler = messageHandlers?.[message.type];
+    if (typeHandler) {
+      typeHandler(message);
+    }
+
+    // 调用注册的处理器
+    const registeredHandler = handlersRef.current.get(message.type);
+    if (registeredHandler) {
+      registeredHandler(message);
+    }
+  }, [onMessage, messageHandlers]);
+
+  // 清理函数
+  const cleanup = useCallback(() => {
+    if (bridgeRef.current) {
+      bridgeRef.current.cleanup();
+    }
+  }, []);
+
+  return {
+    bridgeRef,
+    sendMessage,
+    getEnvironment,
+    registerHandler,
+    handleMessage,
+    cleanup,
+  };
+};
+

package/components/WordCloud/README.md

@@ -0,0 +1,308 @@
+# WordCloud 组件
+
+`WordCloud` 是一个多功能词云组件，支持传统词云和气泡词云两种展示模式，用于可视化文本数据的频率或重要性。
+
+## 功能特性
+
+### 🎨 两种展示模式
+
+- **Traditional（传统模式）**：经典的词云布局，文字紧密堆叠，根据权重调整字号
+- **Bubble（气泡模式）**：全新的圆形气泡布局，每个词在独立圆形内显示，更现代化的设计
+
+### 🌐 跨平台支持
+
+- **Web 端**
+  - 传统模式：使用 `react-wordcloud`（基于 D3）
+  - 气泡模式：使用 `d3-hierarchy` 的 pack 布局算法
+- **React Native 端**
+  - 传统模式：自定义 SVG 螺旋布局
+  - 气泡模式：自定义圆形打包算法
+
+### ✨ 核心功能
+
+- ✅ 自动根据数值调整大小（字号或气泡半径）
+- ✅ 支持自定义颜色方案
+- ✅ 文字旋转支持（传统模式）
+- ✅ Hashtag 前缀支持（气泡模式）
+- ✅ 响应式布局
+- ✅ 交互事件支持（点击、悬停）
+- ✅ 空数据状态处理
+
+## 安装依赖
+
+```bash
+# Web 端需要
+npm install react-wordcloud d3-hierarchy
+
+# React Native 端需要
+npm install react-native-svg
+```
+
+## 基本用法
+
+### 传统词云
+
+```tsx
+import { WordCloud } from '@beppla/tapas-ui';
+
+const data = [
+  { text: 'React', value: 100 },
+  { text: 'TypeScript', value: 90 },
+  { text: 'JavaScript', value: 85 },
+  // ... more words
+];
+
+function App() {
+  return (
+    <WordCloud
+      words={data}
+      height={400}
+      colors={['#FF6B00', '#0066CC', '#00B894']}
+    />
+  );
+}
+```
+
+### 气泡词云
+
+```tsx
+import { WordCloud } from '@beppla/tapas-ui';
+
+const data = [
+  { text: 'Antioxidant', value: 100 },
+  { text: 'Vitamin C', value: 85 },
+  { text: 'Healthy', value: 70 },
+  // ... more words
+];
+
+function App() {
+  return (
+    <WordCloud
+      variant="bubble"
+      words={data}
+      height={600}
+      width={800}
+      showHashtag={true}
+      bubbleColors={{
+        primary: '#8B6F47',
+        secondary: '#D4C4B0',
+        text: '#FFFFFF',
+      }}
+      onBubbleClick={(word) => {
+        console.log('Clicked:', word.text);
+      }}
+    />
+  );
+}
+```
+
+## Props
+
+### 公共属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `words` | `WordCloudData[]` | **必填** | 词云数据数组 |
+| `width` | `number` | `undefined` | 宽度（px），不设置则自适应 |
+| `height` | `number` | `400` | 高度（px） |
+| `variant` | `'traditional' \| 'bubble'` | `'traditional'` | 展示模式 |
+| `style` | `ViewStyle` | `undefined` | 容器样式 |
+| `testID` | `string` | `undefined` | 测试 ID |
+
+### 传统模式属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `colors` | `string[]` | 棕色系 | 文字颜色数组 |
+| `fontFamily` | `string` | `'Arial, sans-serif'` | 字体 |
+| `fontSizes` | `[number, number]` | `[14, 60]` | 字号范围 [最小, 最大] |
+| `rotate` | `number` | `0` | 旋转角度（0 表示不旋转） |
+| `spiral` | `'archimedean' \| 'rectangular'` | `'archimedean'` | 螺旋布局算法 |
+| `padding` | `number` | `2` | 词间距 |
+
+### 气泡模式属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `bubbleColors` | `BubbleColors` | 见下方 | 气泡颜色配置 |
+| `showHashtag` | `boolean` | `true` | 是否显示 # 前缀 |
+| `minBubbleSize` | `number` | `30` | 最小气泡半径（px） |
+| `maxBubbleSize` | `number` | `150` | 最大气泡半径（px） |
+| `bubblePadding` | `number` | `4` | 气泡间距（px） |
+| `fontFamily` | `string` | `'Arial, sans-serif'` | 字体 |
+| `onBubbleClick` | `(word: WordCloudData) => void` | `undefined` | 气泡点击回调 |
+
+### 数据类型
+
+```typescript
+interface WordCloudData {
+  text: string;      // 词文本
+  value: number;     // 权重/频率
+  color?: string;    // 自定义颜色（可选）
+}
+
+interface BubbleColors {
+  primary: string;   // 深色气泡（高权重）
+  secondary: string; // 浅色气泡（低权重）
+  text?: string;     // 文字颜色
+}
+```
+
+### 默认气泡颜色
+
+```typescript
+const DEFAULT_BUBBLE_COLORS = {
+  primary: '#8B6F47',    // 深棕色
+  secondary: '#D4C4B0',  // 浅米色
+  text: '#FFFFFF',       // 白色
+};
+```
+
+## 使用场景
+
+### 传统词云适用于
+
+- 📊 热门话题分析
+- 🔍 关键词提取展示
+- 📈 用户反馈词频统计
+- 🏷️ 标签云
+- 📝 文章摘要可视化
+
+### 气泡词云适用于
+
+- 🎯 产品特性展示
+- 💼 品牌关键词
+- 🌟 用户兴趣标签
+- 📱 移动端友好展示
+- 🎨 现代化 Dashboard
+
+## 高级示例
+
+### Figma 设计复刻
+
+完全复刻提供的 Figma 设计：
+
+```tsx
+<WordCloud
+  variant="bubble"
+  words={[
+    { text: 'Antioxidant', value: 100 },
+    { text: 'Anti-inflammatory', value: 95 },
+    { text: 'Vitamin C', value: 88 },
+    { text: 'Boost immune system', value: 85 },
+    { text: 'Dietary', value: 72 },
+    { text: 'Healthy', value: 70 },
+    { text: 'Super food', value: 68 },
+    { text: 'Veggie', value: 65 },
+    { text: 'Kale', value: 62 },
+    { text: 'Organic', value: 50 },
+  ]}
+  height={600}
+  width={1000}
+  showHashtag={true}
+  bubbleColors={{
+    primary: '#8B6F47',
+    secondary: '#D4C4B0',
+    text: '#FFFFFF',
+  }}
+  minBubbleSize={40}
+  maxBubbleSize={180}
+  bubblePadding={8}
+/>
+```
+
+### 自定义颜色方案
+
+```tsx
+<WordCloud
+  variant="bubble"
+  words={techWords}
+  bubbleColors={{
+    primary: '#61DAFB',    // React 蓝
+    secondary: '#3178C6',  // TypeScript 蓝
+    text: '#FFFFFF',
+  }}
+  showHashtag={false}
+/>
+```
+
+### 交互式气泡
+
+```tsx
+<WordCloud
+  variant="bubble"
+  words={words}
+  onBubbleClick={(word) => {
+    // 处理点击事件
+    console.log('Clicked:', word.text, word.value);
+    // 可以触发导航、弹窗等
+  }}
+/>
+```
+
+## 性能优化
+
+### 数据量建议
+
+- **传统模式**：推荐 10-50 个词
+- **气泡模式**：推荐 8-20 个词（更多词会导致气泡变小）
+
+### 优化提示
+
+```tsx
+// 1. 使用 useMemo 缓存数据
+const wordsData = useMemo(() => processWords(rawData), [rawData]);
+
+// 2. 控制数据量
+const topWords = words.slice(0, 20);
+
+// 3. 合理设置尺寸
+<WordCloud
+  words={topWords}
+  height={600}  // 气泡模式建议 >= 500
+  width={800}   // 气泡模式建议 >= 600
+/>
+```
+
+## 注意事项
+
+1. **依赖安装**：确保已安装对应平台的依赖库
+2. **容器尺寸**：气泡模式需要足够的空间（建议 width >= 600, height >= 500）
+3. **文字长度**：过长的文本会自动截断或缩小字号
+4. **浏览器兼容**：Web 端需要支持 SVG 的现代浏览器
+5. **性能考虑**：大数据量时建议只显示 Top N 的词
+
+## 浏览器/平台支持
+
+- ✅ Chrome / Edge (最新版)
+- ✅ Firefox (最新版)
+- ✅ Safari (最新版)
+- ✅ iOS (React Native)
+- ✅ Android (React Native)
+
+## Changelog
+
+### v1.4.32 (Latest)
+
+- ✨ 新增气泡词云（bubble variant）
+- ✨ 支持 Hashtag 前缀显示
+- ✨ 新增气泡点击事件
+- ✨ 支持自定义气泡颜色和大小
+- 📚 新增 6 个气泡词云 Story 示例
+- 🧪 新增气泡模式测试用例
+
+### v1.4.30 之前
+
+- ✅ 传统词云基础功能
+- ✅ Web 和 RN 跨平台支持
+- ✅ 自定义颜色和字号
+
+## 相关链接
+
+- [Storybook 示例](https://your-storybook-url.com)
+- [API 文档](https://your-api-docs-url.com)
+- [GitHub Issues](https://github.com/your-repo/issues)
+
+## License
+
+MIT © Beppla