@kylincloud/flamegraph 0.35.6 → 0.35.8

package/README.md

@@ -3,61 +3,107 @@
 一个可复用的 **火焰图 / 差分火焰图 React 组件库**，基于 Pyroscope 的 flamegraph 思路进行了工程化封装，方便在任意前端应用中渲染 CPU / 内存等采样型 Profiling 数据。
 
 > ⚠️ 说明  
-> 本仓库主要服务于麒麟内部项目（如性能观测 / 智算平台等），API 在 0.x 阶段可能会有不兼容调整，请结合代码实际导出使用。
+> 本仓库主要服务于麒麟内部项目（如性能观测 / 智算平台等），API 在 0.x 阶段可能会有不兼容调整，请以当前版本导出的实际 API 为准。  
+> 从 `0.35.7` 起，构建方式已切换为 **Rollup + PostCSS + Sass**，并支持自动注入样式。
 
 ---
 
 ## 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"`
+* `"graphviz-react": "^1.2.5"`
+* `"true-myth": "^5.1.2"`
+* `"zod": "^3.11.6"`
+
 ---
 
 ## 3. 快速上手（React 示例）
 
-### 3.1 引入样式与组件
+当前包的入口文件导出了一些核心组件 / 工具函数 / i18n 能力，大致包括：
+
+* 组件与工具：
+
+  * `Flamegraph`
+  * `FlamegraphRenderer`
+  * `Box`
+  * `DefaultPalette`
+  * `convertJaegerTraceToProfile`
+  * `diffTwoProfiles`
+
+* i18n 导出：
+
+  * `flamegraphDefaultMessages`
+  * `flamegraphZhCNMessages`
+  * `FlamegraphI18nProvider`
+  * 类型 `FlamegraphMessages`
+
+### 3.1 引入组件（样式自动注入）
+
+从 `0.35.7` 起，本库在浏览器入口中会自动导入并注入全局样式：
+
+* 源码中 `src/index.tsx` 内部已执行：`import './sass/flamegraph.scss'`
+* Rollup 使用 `rollup-plugin-postcss` 将 Sass 编译为 CSS，并在运行时通过 `<style>` 标签自动注入
+
+因此，在业务工程中只需要正常导入组件即可，**无需再单独引入 CSS 文件**：
 
 ```tsx
 import React from 'react'
 
-// 必须：引入打包好的 CSS
-import '@kylincloud/flamegraph/dist/index.css'
-
-// 组件名称以实际导出为准，如果你改过导出，请相应调整
-import { FlamegraphRenderer } from '@kylincloud/flamegraph'
-// 或：import FlamegraphRenderer from '@kylincloud/flamegraph'
+import {
+  FlamegraphRenderer,
+  Flamegraph,
+  Box,
+  DefaultPalette,
+  convertJaegerTraceToProfile,
+  diffTwoProfiles,
+  FlamegraphI18nProvider,
+  flamegraphDefaultMessages,
+  flamegraphZhCNMessages,
+} from '@kylincloud/flamegraph'
 ```
 
-### 3.2 最小可用示例
+> ✅ 提示：
+>
+> * 对于浏览器端渲染：只要导入任意来自 `@kylincloud/flamegraph` 的组件，样式就会自动注入。
+> * 对于 SSR 场景：Node 侧入口为 `dist/index.node.cjs.js` / `dist/index.node.esm.js`，不会在服务端注入样式，CSS 注入会在浏览器端 hydration 时发生。
+
+### 3.2 最小可用示例：渲染单个 Flamebearer profile
 
 ```tsx
-// 仅为示意，类型 / 字段名请以 src 下实际定义为准
+import React from 'react'
+import { FlamegraphRenderer } from '@kylincloud/flamegraph'
+
 const simpleProfile = {
   version: 1,
   flamebearer: {
@@ -67,12 +113,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 +130,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,16 +141,45 @@ export default function App() {
 }
 ```
 
+### 3.3 使用 i18n 包装
+
+```tsx
+import React from 'react'
+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 入口处只需导入一次本库（样式会自动注入）；组件可在任何页面复用
 
 ---
 
 ## 4. 数据格式说明（Flamebearer 简要约定）
 
-组件默认消费的数据结构与 Pyroscope 的 **Flamebearer** 格式保持兼容，整体上可理解为：
+组件默认消费的数据结构与 Pyroscope 的 **Flamebearer** 格式保持兼容，可以理解为：
 
 ```ts
 type FlamebearerProfile = {
@@ -118,8 +196,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 +208,141 @@ 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` 中扩展出：
 
-* 在 `metadata.format` 中标注 diff 格式
-* 在 `flamebearer.levels` 中扩展出左/右两个 profile 的宽度以及差分数值
-* 在前端通过：
+  * 左 profile（基线）的宽度 / 值
+  * 右 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`
+* 浏览器入口 `src/index.tsx` 中默认会导入该样式文件：
 
-  * 字体大小、行高
-  * tooltip 外观
-  * 表格排版
-* 如需与业务系统整体主题统一，可以：
+  * `import './sass/flamegraph.scss'`
+* Rollup + PostCSS + Sass 会在构建时将其编译为 CSS，并在运行时自动注入 `<style>` 标签，不再额外生成独立的 `dist/index.css` / `dist/index.esm.css` 等文件。
 
-  * 在外层容器上控制背景色、边框、圆角
-  * 使用 CSS 变量对颜色进行二次覆盖
+`package.json` 中已将 `*.css` / `*.scss` 标记为 `sideEffects`，确保在使用方构建时不会被错误 Tree-Shaking 掉。
+
+如需与业务系统整体主题统一，可以：
+
+* 在外层容器控制背景色、边框、圆角等
+* 通过 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 && pnpm run build:assets",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build:js": "rollup -c",
+    "build:assets": "cp src/logo-v3-small.svg dist/logo-v3-small.svg || true",
     "type-check": "tsc -p tsconfig.build.json --noEmit",
     "lint": "eslint ./ --cache --fix"
   }
 }
 ```
 
-* **构建库**
+* **构建类型声明**
+
+  ```bash
+  pnpm run build:types
+  ```
+
+  输出：`dist/**/*.d.ts`（由 `tsconfig.build.json` 控制）。
+
+* **构建 JS & 样式**
+
+  ```bash
+  pnpm run build:js
+  ```
+
+  基于 **Rollup + PostCSS + Sass** 构建，生成：
+
+  * 浏览器入口：
+
+    * `dist/index.esm.js`（ESM 入口，对应 `"module"`）
+    * `dist/index.cjs.js`（CJS 入口）
+    * 内部包含自动注入样式逻辑
+  * Node 入口：
+
+    * `dist/index.node.cjs.js`（CJS，给 Node / SSR 使用）
+    * `dist/index.node.esm.js`（ESM）
+
+* **拷贝静态资源**
 
   ```bash
-  pnpm build
+  pnpm run build:assets
   ```
 
-  输出：
+  将 `src/logo-v3-small.svg` 拷贝到 `dist/`，以便在组件内部引用。
+
+* **完整构建**
 
-  * `dist/index.js`        —— 浏览器环境入口（`"browser"`）
-  * `dist/index.node.js`   —— Node / SSR 环境入口（`"main"`）
-  * `dist/index.css`       —— CSS 样式文件
-  * `dist/**/*.d.ts`       —— 类型声明文件
+  ```bash
+  pnpm run build
+  ```
+
+  等价于：清理 `dist` → 生成类型声明 → 生成 JS（含样式）→ 拷贝静态资源。
 
 * **类型检查**
 
   ```bash
-  pnpm type-check
+  pnpm run type-check
   ```
 
 * **代码规范检查**
 
   ```bash
-  pnpm lint
+  pnpm run lint
   ```
 
-> ✅ 建议：
+> ✅ 说明：
 >
-> * 使用 Node 18+（或与你当前前端工程保持一致的版本）
-> * 在 CI 中至少执行 `pnpm build` 与 `pnpm type-check` 保证包的基本可用性
+> * 旧版本使用的 esbuild 构建脚本已移除，当前仓库仅保留 rollup 方案，避免多套构建链路带来的维护成本。
+> * 若需要在 CI 中校验，可至少执行：
+>
+>   * `pnpm run type-check`
+>   * `pnpm run build`
 
 ---
 
@@ -221,10 +352,11 @@ type FlamebearerProfile = {
 * 主要差异点集中在：
 
   * 包名与发布渠道：使用 `@kylincloud/flamegraph`
-  * 构建链路与样式组织适配麒麟内部前端工程
+  * 构建链路调整为 Rollup + PostCSS + Sass，自动注入样式，兼容 ESM / CJS / Node 侧入口
+  * 在类型声明与 i18n 导出上进行了补充，便于在 TypeScript 环境中使用
   * 后续可能增加针对麒麟项目的定制功能（如与内部监控体系联动）
 
-如需回溯或对比实现细节，可以阅读源码中相关注释。
+如需回溯或对比实现细节，可以参考源码中的注释与 commit 记录。
 
 ---
 
@@ -239,13 +371,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 的版权信息。
+