@kylincloud/flamegraph 0.35.7 → 0.35.8

package/README.md

@@ -1,9 +1,10 @@
 # @kylincloud/flamegraph
 
-一个可复用的 **火焰图 / 差分火焰图 React 组件库**，基于 Pyroscope 的 flamegraph 思路进行了工程化封装，方便在任意前端应用中渲染 CPU / 内存等采样型 Profiling 数据。:contentReference[oaicite:1]{index=1}  
+一个可复用的 **火焰图 / 差分火焰图 React 组件库**，基于 Pyroscope 的 flamegraph 思路进行了工程化封装，方便在任意前端应用中渲染 CPU / 内存等采样型 Profiling 数据。
 
 > ⚠️ 说明  
-> 本仓库主要服务于麒麟内部项目（如性能观测 / 智算平台等），API 在 0.x 阶段可能会有不兼容调整，请以当前版本导出的实际 API 为准。
+> 本仓库主要服务于麒麟内部项目（如性能观测 / 智算平台等），API 在 0.x 阶段可能会有不兼容调整，请以当前版本导出的实际 API 为准。  
+> 从 `0.35.7` 起，构建方式已切换为 **Rollup + PostCSS + Sass**，并支持自动注入样式。
 
 ---
 
@@ -37,18 +38,19 @@ pnpm add @kylincloud/flamegraph
 yarn add @kylincloud/flamegraph
 ````
 
-本库对 React 有 peer 依赖：
+本库对 React 及部分基础库有 peer 依赖，请确保工程中已安装并满足版本要求。例如：
 
 * `"react": ">=16.14.0"`
-* `"react-dom": ">=16.14.0"` 
-
-确保你的工程中 React 版本满足要求。
+* `"react-dom": ">=16.14.0"`
+* `"graphviz-react": "^1.2.5"`
+* `"true-myth": "^5.1.2"`
+* `"zod": "^3.11.6"`
 
 ---
 
 ## 3. 快速上手（React 示例）
 
-当前包的入口文件导出了一些核心组件 / 工具函数 / i18n 能力，形态大致如下：
+当前包的入口文件导出了一些核心组件 / 工具函数 / i18n 能力，大致包括：
 
 * 组件与工具：
 
@@ -58,6 +60,7 @@ yarn add @kylincloud/flamegraph
   * `DefaultPalette`
   * `convertJaegerTraceToProfile`
   * `diffTwoProfiles`
+
 * i18n 导出：
 
   * `flamegraphDefaultMessages`
@@ -65,23 +68,18 @@ yarn add @kylincloud/flamegraph
   * `FlamegraphI18nProvider`
   * 类型 `FlamegraphMessages`
 
-### 3.1 引入样式与组件
+### 3.1 引入组件（样式自动注入）
 
-构建后会输出 ESM / CJS 两套 JS 以及对应的 CSS 文件：
+从 `0.35.7` 起，本库在浏览器入口中会自动导入并注入全局样式：
 
-* `dist/index.esm.js`（ESM，`"module"`）
-* `dist/index.cjs.js`（CJS，`"main"`）
-* `dist/index.esm.css` / `dist/index.cjs.css`（样式）
+* 源码中 `src/index.tsx` 内部已执行：`import './sass/flamegraph.scss'`
+* Rollup 使用 `rollup-plugin-postcss` 将 Sass 编译为 CSS，并在运行时通过 `<style>` 标签自动注入
 
-在业务工程中建议按 ESM 方式引入：
+因此，在业务工程中只需要正常导入组件即可，**无需再单独引入 CSS 文件**：
 
 ```tsx
 import React from 'react'
 
-// 必须：引入打包好的 CSS（推荐使用 ESM 版本）
-import '@kylincloud/flamegraph/dist/index.esm.css'
-
-// 典型用法：只用渲染器
 import {
   FlamegraphRenderer,
   Flamegraph,
@@ -97,15 +95,13 @@ import {
 
 > ✅ 提示：
 >
-> * CSS 路径请使用 `dist/index.esm.css` 或 `dist/index.cjs.css`，与当前打包结果一致。
-> * 若你的打包器不支持从 `exports` 读 CSS 子路径，可使用显式路径
->   `@kylincloud/flamegraph/dist/index.esm.css`。
+> * 对于浏览器端渲染：只要导入任意来自 `@kylincloud/flamegraph` 的组件，样式就会自动注入。
+> * 对于 SSR 场景：Node 侧入口为 `dist/index.node.cjs.js` / `dist/index.node.esm.js`，不会在服务端注入样式，CSS 注入会在浏览器端 hydration 时发生。
 
 ### 3.2 最小可用示例：渲染单个 Flamebearer profile
 
 ```tsx
 import React from 'react'
-import '@kylincloud/flamegraph/dist/index.esm.css'
 import { FlamegraphRenderer } from '@kylincloud/flamegraph'
 
 const simpleProfile = {
@@ -149,7 +145,6 @@ export default function App() {
 
 ```tsx
 import React from 'react'
-import '@kylincloud/flamegraph/dist/index.esm.css'
 import {
   FlamegraphRenderer,
   FlamegraphI18nProvider,
@@ -178,13 +173,13 @@ export default function App() {
 > ✅ 建议：
 >
 > * 将容器高度固定（如 400–800px），避免页面滚动条与内部滚动冲突
-> * App 入口处只需引入一次 CSS；组件可在各处复用
+> * App 入口处只需导入一次本库（样式会自动注入）；组件可在任何页面复用
 
 ---
 
 ## 4. 数据格式说明（Flamebearer 简要约定）
 
-组件默认消费的数据结构与 Pyroscope 的 **Flamebearer** 格式保持兼容，整体上可理解为：
+组件默认消费的数据结构与 Pyroscope 的 **Flamebearer** 格式保持兼容，可以理解为：
 
 ```ts
 type FlamebearerProfile = {
@@ -251,11 +246,13 @@ type FlamebearerProfile = {
 
 ## 6. 样式与主题
 
-* 核心样式文件为：`src/sass/flamegraph.scss`，打包后输出为：
+* 核心样式源文件为：`src/sass/flamegraph.scss`
+* 浏览器入口 `src/index.tsx` 中默认会导入该样式文件：
+
+  * `import './sass/flamegraph.scss'`
+* Rollup + PostCSS + Sass 会在构建时将其编译为 CSS，并在运行时自动注入 `<style>` 标签，不再额外生成独立的 `dist/index.css` / `dist/index.esm.css` 等文件。
 
-  * `dist/index.esm.css`
-  * `dist/index.cjs.css` 
-* 打包配置中已将 `*.css` / `*.scss` 标记为 `sideEffects`，确保在使用方构建时不会被错误 Tree-Shaking 掉。
+`package.json` 中已将 `*.css` / `*.scss` 标记为 `sideEffects`，确保在使用方构建时不会被错误 Tree-Shaking 掉。
 
 如需与业务系统整体主题统一，可以：
 
@@ -275,9 +272,10 @@ type FlamebearerProfile = {
 {
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "pnpm run clean && pnpm run build:types && pnpm run build:js",
+    "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": "node scripts/build-esbuild.mjs",
+    "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"
   }
@@ -292,18 +290,31 @@ type FlamebearerProfile = {
 
   输出：`dist/**/*.d.ts`（由 `tsconfig.build.json` 控制）。
 
-* **构建 JS & CSS**
+* **构建 JS & 样式**
 
   ```bash
   pnpm run build:js
   ```
 
-  基于 esbuild + sass 插件，将 TSX + Sass 打包成：
+  基于 **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）
 
-  * `dist/index.esm.js`（ESM 入口，对应 `module`）
-  * `dist/index.cjs.js`（CJS 入口，对应 `main`）
-  * `dist/index.esm.css`
-  * `dist/index.cjs.css`
+* **拷贝静态资源**
+
+  ```bash
+  pnpm run build:assets
+  ```
+
+  将 `src/logo-v3-small.svg` 拷贝到 `dist/`，以便在组件内部引用。
 
 * **完整构建**
 
@@ -311,7 +322,7 @@ type FlamebearerProfile = {
   pnpm run build
   ```
 
-  等价于：清理 `dist` → 生成类型声明 → 生成 JS/CSS。
+  等价于：清理 `dist` → 生成类型声明 → 生成 JS（含样式）→ 拷贝静态资源。
 
 * **类型检查**
 
@@ -325,10 +336,13 @@ type FlamebearerProfile = {
   pnpm run lint
   ```
 
-> ✅ 建议：
+> ✅ 说明：
+>
+> * 旧版本使用的 esbuild 构建脚本已移除，当前仓库仅保留 rollup 方案，避免多套构建链路带来的维护成本。
+> * 若需要在 CI 中校验，可至少执行：
 >
-> * 在 CI 中至少执行 `pnpm run build` 与 `pnpm run type-check`，保证包的构建与类型安全。
-> * 本项目使用 TypeScript 5.x 与 esbuild 进行打包，建议 Node 版本与麒麟内部前端工程保持一致。
+>   * `pnpm run type-check`
+>   * `pnpm run build`
 
 ---
 
@@ -338,7 +352,8 @@ type FlamebearerProfile = {
 * 主要差异点集中在：
 
   * 包名与发布渠道：使用 `@kylincloud/flamegraph`
-  * 构建链路与样式组织适配麒麟内部前端工程（ESM/CJS 双入口、CSS 独立导出）
+  * 构建链路调整为 Rollup + PostCSS + Sass，自动注入样式，兼容 ESM / CJS / Node 侧入口
+  * 在类型声明与 i18n 导出上进行了补充，便于在 TypeScript 环境中使用
   * 后续可能增加针对麒麟项目的定制功能（如与内部监控体系联动）
 
 如需回溯或对比实现细节，可以参考源码中的注释与 commit 记录。