@basic-genomics/hivtrace-viz 1.0.0

package/README.md

@@ -0,0 +1,161 @@
+# @basic-genomics/hivtrace-viz
+
+HIV-TRACE 分子传播网络可视化组件，支持 React 集成和 Vite 开发服务器。
+
+## 功能特性
+
+- 🔬 HIV 分子传播网络可视化
+- ⚛️ React 组件封装
+- 🔌 Vite 插件支持
+- 🌐 国际化支持（中文/英文）
+- 📦 支持 iframe 嵌入模式
+
+## 安装
+
+```bash
+npm install @basic-genomics/hivtrace-viz
+# 或
+yarn add @basic-genomics/hivtrace-viz
+```
+
+## 使用方式
+
+### React 组件
+
+```tsx
+import { HivtraceViz } from '@basic-genomics/hivtrace-viz/react';
+
+function App() {
+  return (
+    <HivtraceViz
+      data={analysisData}
+      options={{
+        enableClusterTracking: true,
+        threshold: 0.015,
+        expand: ['cluster_1']
+      }}
+      onTrackCluster={(clusterInfo, networkInfo) => {
+        console.log('跟踪簇:', clusterInfo);
+      }}
+      onReady={() => console.log('可视化已就绪')}
+      error={fetchError?.message}
+    />
+  );
+}
+```
+
+### Vite 插件
+
+```ts
+// vite.config.ts
+import { hivtraceVizPlugin } from '@basic-genomics/hivtrace-viz/vite';
+
+export default defineConfig({
+  plugins: [
+    hivtraceVizPlugin({
+      base: '/hivtrace-viz' // 可选，默认 '/hivtrace-viz'
+    })
+  ]
+});
+```
+
+### iframe 嵌入
+
+```html
+<iframe 
+  src="/hivtrace-viz/index.html" 
+  style="width: 100%; height: 600px; border: none;">
+</iframe>
+```
+
+## 开发指南
+
+### 环境要求
+
+- Node.js >= 18
+- Yarn 1.22+
+
+### 开发模式
+
+```bash
+# 安装依赖
+yarn install
+
+# 启动开发服务器（热更新 + 预览页面）
+yarn dev
+```
+
+开发服务器启动后：
+- 自动打开 `http://localhost:8080/preview.html`
+- 支持核心库热更新
+- 支持 embed 模板热更新
+
+### 生产构建
+
+```bash
+# 完整构建（推荐）
+yarn build
+
+# 分步构建
+yarn build:core   # 核心可视化库
+yarn build:react  # React 组件
+yarn build:vite   # Vite 插件
+yarn build:embed  # 嵌入资源
+```
+
+### 测试
+
+在宿主应用中测试：
+
+```bash
+# 1. 在 hivtrace-viz 目录构建
+yarn build
+
+# 2. 在宿主应用目录
+yarn add file:../hivtrace-viz-github
+
+# 3. 启动宿主应用
+yarn dev
+```
+
+## 项目结构
+
+```
+hivtrace-viz/
+├── src/
+│   ├── *.js              # 核心可视化逻辑
+│   ├── locales/          # 国际化文件
+│   ├── react/            # React 组件
+│   └── vite-plugin/      # Vite 插件
+├── template/
+│   └── embed.html        # 嵌入模板
+├── dist/                 # 构建产物
+│   ├── hivtrace.js       # 核心库
+│   ├── hivtrace.zh.js    # 中文版本
+│   ├── react/            # React 组件
+│   ├── vite-plugin/      # Vite 插件
+│   └── embed/            # 嵌入资源
+└── preview.html          # 开发预览
+```
+
+## Props API
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `data` | `HivtraceVizData` | 分析数据 |
+| `options` | `HivtraceVizOptions` | 配置选项 |
+| `error` | `string` | 错误信息（API 错误时传入） |
+| `loadingState` | `ReactNode \| null` | 自定义加载态，`null` 禁用 |
+| `onTrackCluster` | `(info, data) => void` | 簇追踪回调 |
+| `onReady` | `() => void` | 渲染完成回调 |
+
+## 国际化
+
+语言在构建时确定。默认生成中文版本。
+
+- `zh-CN` - 简体中文（默认）
+- `en-US` - English
+
+## License
+
+MIT