@kylincloud/flamegraph 0.35.6 → 0.35.7

package/README.md

@@ -1,63 +1,113 @@
 # @kylincloud/flamegraph
 
-一个可复用的 **火焰图 / 差分火焰图 React 组件库**，基于 Pyroscope 的 flamegraph 思路进行了工程化封装，方便在任意前端应用中渲染 CPU / 内存等采样型 Profiling 数据。
+一个可复用的 **火焰图 / 差分火焰图 React 组件库**，基于 Pyroscope 的 flamegraph 思路进行了工程化封装，方便在任意前端应用中渲染 CPU / 内存等采样型 Profiling 数据。:contentReference[oaicite:1]{index=1}  
 
 > ⚠️ 说明  
-> 本仓库主要服务于麒麟内部项目（如性能观测 / 智算平台等），API 在 0.x 阶段可能会有不兼容调整，请结合代码实际导出使用。
+> 本仓库主要服务于麒麟内部项目（如性能观测 / 智算平台等），API 在 0.x 阶段可能会有不兼容调整，请以当前版本导出的实际 API 为准。
 
 ---
 
 ## 1. 功能特性
 
 - 🔥 支持 **单视图** 与 **Diff 差分视图**
-- 📊 支持 **表格 / 火焰图 / 表格+火焰图 / Sandwich** 等多种布局
+- 📊 支持 **表格 / 火焰图 / 表格+火焰图 / Sandwich** 等多种布局（具体取决于业务侧如何组合封装）
 - 🧭 丰富交互：
   - 鼠标悬停 Tooltip（展示占比、采样数、绝对值等）
   - 点击放大 / 回退、滚轮缩放、拖拽平移
-  - 右键菜单（折叠、重置视图等，视实际实现为准）
+  - 右键菜单（折叠、重置视图等）
 - 🔍 函数名搜索 & 高亮
 - 🎨 多种配色 / Diff 渐变色，适配普通与色弱模式
 - 🧱 基于 **Flamebearer** 数据结构，兼容 Pyroscope / Grafana Pyroscope 的 profile 数据
-- 🧩 以组件的方式独立封装，可作为「黑盒区域」嵌入任意业务页面
+- 🧩 以 React 组件的方式独立封装，可作为「黑盒区域」嵌入任意业务页面
 
 ---
 
 ## 2. 安装
 
-> 具体发布渠道请按你实际使用方式调整（npm / GitLab Registry / 本地 `link` 等）。
+> 发布渠道可按实际情况调整（npm / GitLab Registry / 本地 `link` 等）。
 
 ```bash
 # npm
 npm install @kylincloud/flamegraph
 
-# or pnpm
+# pnpm
 pnpm add @kylincloud/flamegraph
 
-# or yarn
+# yarn
 yarn add @kylincloud/flamegraph
 ````
 
+本库对 React 有 peer 依赖：
+
+* `"react": ">=16.14.0"`
+* `"react-dom": ">=16.14.0"` 
+
+确保你的工程中 React 版本满足要求。
+
 ---
 
 ## 3. 快速上手（React 示例）
 
+当前包的入口文件导出了一些核心组件 / 工具函数 / i18n 能力，形态大致如下：
+
+* 组件与工具：
+
+  * `Flamegraph`
+  * `FlamegraphRenderer`
+  * `Box`
+  * `DefaultPalette`
+  * `convertJaegerTraceToProfile`
+  * `diffTwoProfiles`
+* i18n 导出：
+
+  * `flamegraphDefaultMessages`
+  * `flamegraphZhCNMessages`
+  * `FlamegraphI18nProvider`
+  * 类型 `FlamegraphMessages`
+
 ### 3.1 引入样式与组件
 
+构建后会输出 ESM / CJS 两套 JS 以及对应的 CSS 文件：
+
+* `dist/index.esm.js`（ESM，`"module"`）
+* `dist/index.cjs.js`（CJS，`"main"`）
+* `dist/index.esm.css` / `dist/index.cjs.css`（样式）
+
+在业务工程中建议按 ESM 方式引入：
+
 ```tsx
 import React from 'react'
 
-// 必须：引入打包好的 CSS
-import '@kylincloud/flamegraph/dist/index.css'
-
-// 组件名称以实际导出为准，如果你改过导出，请相应调整
-import { FlamegraphRenderer } from '@kylincloud/flamegraph'
-// 或：import FlamegraphRenderer from '@kylincloud/flamegraph'
+// 必须：引入打包好的 CSS（推荐使用 ESM 版本）
+import '@kylincloud/flamegraph/dist/index.esm.css'
+
+// 典型用法：只用渲染器
+import {
+  FlamegraphRenderer,
+  Flamegraph,
+  Box,
+  DefaultPalette,
+  convertJaegerTraceToProfile,
+  diffTwoProfiles,
+  FlamegraphI18nProvider,
+  flamegraphDefaultMessages,
+  flamegraphZhCNMessages,
+} from '@kylincloud/flamegraph'
 ```
 
-### 3.2 最小可用示例
+> ✅ 提示：
+>
+> * CSS 路径请使用 `dist/index.esm.css` 或 `dist/index.cjs.css`，与当前打包结果一致。
+> * 若你的打包器不支持从 `exports` 读 CSS 子路径，可使用显式路径
+>   `@kylincloud/flamegraph/dist/index.esm.css`。
+
+### 3.2 最小可用示例：渲染单个 Flamebearer profile
 
 ```tsx
-// 仅为示意，类型 / 字段名请以 src 下实际定义为准
+import React from 'react'
+import '@kylincloud/flamegraph/dist/index.esm.css'
+import { FlamegraphRenderer } from '@kylincloud/flamegraph'
+
 const simpleProfile = {
   version: 1,
   flamebearer: {
@@ -67,12 +117,15 @@ const simpleProfile = {
       [0, 100, 0, 100], // root
       // ...
     ],
-    // 其他字段：numTicks, maxSelf, units, sampleRate 等
+    numTicks: 100,
+    maxSelf: 100,
+    sampleRate: 100,
+    units: 'samples',
   },
   metadata: {
     appName: 'demo',
     spyName: 'cpu',
-    format: 'single', // 或 'double' / 'diff' 等
+    format: 'single',
   },
 }
 
@@ -81,7 +134,7 @@ export default function App() {
     <div style={{ height: 600 }}>
       <FlamegraphRenderer
         profile={simpleProfile}
-        // 以下 props 为常见配置示意，实际以组件实现为准
+        // 典型配置示例（具体以实现为准）
         // viewType="both"           // 'flamegraph' | 'table' | 'both' | 'sandwich'
         // type="single"             // 'single' | 'diff'
         // showToolbar={true}
@@ -92,10 +145,40 @@ export default function App() {
 }
 ```
 
+### 3.3 使用 i18n 包装
+
+```tsx
+import React from 'react'
+import '@kylincloud/flamegraph/dist/index.esm.css'
+import {
+  FlamegraphRenderer,
+  FlamegraphI18nProvider,
+  flamegraphDefaultMessages,
+  flamegraphZhCNMessages,
+} from '@kylincloud/flamegraph'
+
+export default function App() {
+  return (
+    <FlamegraphI18nProvider
+      messages={{
+        // 可按需合并多语言
+        en: flamegraphDefaultMessages,
+        zhCN: flamegraphZhCNMessages,
+      }}
+      locale="zhCN"
+    >
+      <div style={{ height: 600 }}>
+        <FlamegraphRenderer profile={/* your profile */} />
+      </div>
+    </FlamegraphI18nProvider>
+  )
+}
+```
+
 > ✅ 建议：
 >
 > * 将容器高度固定（如 400–800px），避免页面滚动条与内部滚动冲突
-> * 确保在 App 入口只引入一次 `@kylincloud/flamegraph/dist/index.css`
+> * App 入口处只需引入一次 CSS；组件可在各处复用
 
 ---
 
@@ -118,8 +201,9 @@ type FlamebearerProfile = {
   metadata?: {
     appName?: string
     spyName?: string
-    format?: 'single' | 'double' | 'triple' | 'diff' | string
-    // 还可以包含 from / until / query 等字段
+    format?: 'single' | 'double' | 'diff' | string
+    from?: number
+    until?: number
     [key: string]: any
   }
 }
@@ -129,89 +213,122 @@ type FlamebearerProfile = {
 * `levels`：二维数组，每一行对应火焰图中的一层；
 
   * **单视图**：每 4 个数字为一组
-  * **Diff 视图**：每组数字扩展为左/右/差值等信息（通常 7 个）
+  * **Diff 视图**：每组数字扩展为左/右 profile 的宽度及差分值（通常 7 个）
 * `units` / `sampleRate`：用于 Tooltip 和表格中做单位换算、展示总时间等
 
-在麒麟内部项目中，你也可以在后端将自定义的树型数据转换为上述格式，再传递给组件。
+在麒麟内部项目中，也可以在后端将自定义的树型数据转换为上述格式，再传递给组件。
 
 ---
 
 ## 5. Diff 差分火焰图
 
-如果 profile 为 Diff 格式（如比较「基线」与「当前」两段 profile），通常会：
+如果 profile 为 Diff 格式（用于比较「基线」与「当前」两段 profile），通常会：
+
+* 在 `metadata.format` 中标注 diff 格式（例如 `'diff'`）
+* 在 `flamebearer.levels` 中扩展出：
+
+  * 左 profile（基线）的宽度 / 值
+  * 右 profile（比较）的宽度 / 值
+  * 差分值（正负表示变慢 / 变快）
 
-* 在 `metadata.format` 中标注 diff 格式
-* 在 `flamebearer.levels` 中扩展出左/右两个 profile 的宽度以及差分数值
-* 在前端通过：
+前端典型表现：
 
-  * 渐变色 / 红绿配色展示「变慢 / 变快」
-  * 表格中展示 `Baseline / Comparison / Diff` 三列
-  * Tooltip 中展示百分比、绝对值、样本数等
+* 火焰图区域：
 
-具体字段与含义请以项目中实际的 `DiffProfile` / `DiffNode` 类型定义为准。
+  * 使用渐变或红/绿配色展示「变慢 / 变快」
+  * 支持针对 diff 值的高亮与过滤
+* 表格区域：
+
+  * 展示 `Symbol / Baseline / Comparison / Diff` 列
+  * 百分比 + 绝对值组合展示（例如 `12.3% (12 ms)`）
+* Tooltip：
+
+  * 展示 `% of total / value / samples` 等信息
+
+具体字段与含义请以实际 `DiffProfile` / `DiffNode` 类型定义及实现为准。
 
 ---
 
 ## 6. 样式与主题
 
-* 本项目的核心样式文件为 `src/sass/flamegraph.scss`，构建后输出到 `dist/index.css`
-* 支持通过 Sass 变量、CSS 变量覆盖部分样式：
+* 核心样式文件为：`src/sass/flamegraph.scss`，打包后输出为：
 
-  * 字体大小、行高
-  * tooltip 外观
-  * 表格排版
-* 如需与业务系统整体主题统一，可以：
+  * `dist/index.esm.css`
+  * `dist/index.cjs.css` 
+* 打包配置中已将 `*.css` / `*.scss` 标记为 `sideEffects`，确保在使用方构建时不会被错误 Tree-Shaking 掉。
 
-  * 在外层容器上控制背景色、边框、圆角
-  * 使用 CSS 变量对颜色进行二次覆盖
+如需与业务系统整体主题统一，可以：
+
+* 在外层容器控制背景色、边框、圆角等
+* 通过 CSS 变量或自定义类名覆盖部分颜色 / 字体
+* 如有必要，可在上层再封装一层组件，对内部 props 进行约束与二次包装
 
 ---
 
 ## 7. 开发与构建
 
-### 7.1 脚本
+### 7.1 脚本说明
+
+当前 `package.json` 中提供的脚本：
 
 ```jsonc
 {
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && pnpm run copy-assets && pnpm run build-css",
-    "copy-assets": "rsync -av --include='*/' --include='*.css' --include='*.scss' --include='*.svg' --exclude='*' src/ dist/",
-    "build-css": "sass src/sass/flamegraph.scss dist/index.css",
+    "clean": "rm -rf dist",
+    "build": "pnpm run clean && pnpm run build:types && pnpm run build:js",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build:js": "node scripts/build-esbuild.mjs",
     "type-check": "tsc -p tsconfig.build.json --noEmit",
     "lint": "eslint ./ --cache --fix"
   }
 }
 ```
 
-* **构建库**
+* **构建类型声明**
 
   ```bash
-  pnpm build
+  pnpm run build:types
   ```
 
-  输出：
+  输出：`dist/**/*.d.ts`（由 `tsconfig.build.json` 控制）。
 
-  * `dist/index.js`        —— 浏览器环境入口（`"browser"`）
-  * `dist/index.node.js`   —— Node / SSR 环境入口（`"main"`）
-  * `dist/index.css`       —— CSS 样式文件
-  * `dist/**/*.d.ts`       —— 类型声明文件
+* **构建 JS & CSS**
+
+  ```bash
+  pnpm run build:js
+  ```
+
+  基于 esbuild + sass 插件，将 TSX + Sass 打包成：
+
+  * `dist/index.esm.js`（ESM 入口，对应 `module`）
+  * `dist/index.cjs.js`（CJS 入口，对应 `main`）
+  * `dist/index.esm.css`
+  * `dist/index.cjs.css`
+
+* **完整构建**
+
+  ```bash
+  pnpm run build
+  ```
+
+  等价于：清理 `dist` → 生成类型声明 → 生成 JS/CSS。
 
 * **类型检查**
 
   ```bash
-  pnpm type-check
+  pnpm run type-check
   ```
 
 * **代码规范检查**
 
   ```bash
-  pnpm lint
+  pnpm run lint
   ```
 
 > ✅ 建议：
 >
-> * 使用 Node 18+（或与你当前前端工程保持一致的版本）
-> * 在 CI 中至少执行 `pnpm build` 与 `pnpm type-check` 保证包的基本可用性
+> * 在 CI 中至少执行 `pnpm run build` 与 `pnpm run type-check`，保证包的构建与类型安全。
+> * 本项目使用 TypeScript 5.x 与 esbuild 进行打包，建议 Node 版本与麒麟内部前端工程保持一致。
 
 ---
 
@@ -221,10 +338,10 @@ type FlamebearerProfile = {
 * 主要差异点集中在：
 
   * 包名与发布渠道：使用 `@kylincloud/flamegraph`
-  * 构建链路与样式组织适配麒麟内部前端工程
+  * 构建链路与样式组织适配麒麟内部前端工程（ESM/CJS 双入口、CSS 独立导出）
   * 后续可能增加针对麒麟项目的定制功能（如与内部监控体系联动）
 
-如需回溯或对比实现细节，可以阅读源码中相关注释。
+如需回溯或对比实现细节，可以参考源码中的注释与 commit 记录。
 
 ---
 
@@ -239,13 +356,15 @@ type FlamebearerProfile = {
 
 建议遵循：
 
-1. 所有 PR 保持 TypeScript `type-check` 与 ESLint 通过
-2. 尽量避免破坏现有 API；如有必要，务必在 README 中标注
-3. 对关键交互（如 Diff 视图、搜索、高亮）补充最小可复现示例
+1. 所有 PR 保持 `pnpm run type-check` 与 `pnpm run lint` 通过
+2. 尽量避免破坏现有公开 API；如有必要，务必在 `CHANGELOG.md` 与本 README 中标注
+3. 对关键交互（如 Diff 视图、搜索、高亮）补充最小可复现示例或 demo 代码
 
 ---
 
 ## 10. 许可证
 
 本项目使用 **Apache-2.0** 许可证发布。
+
 如在外部开源，请确保保留上游版权与许可证声明，并补充 @kylincloud 的版权信息。
+