@kylincloud/flamegraph 0.35.9 → 0.35.10

package/README.md

@@ -11,7 +11,7 @@
 ## 1. 功能特性
 
 - 🔥 支持 **单视图** 与 **Diff 差分视图**
-- 📊 支持 **表格 / 火焰图 / 表格+火焰图 / Sandwich** 等多种布局（具体取决于业务侧如何组合封装）
+- 📊 支持 **表格 / 火焰图 / 表格 + 火焰图 / Sandwich** 等多种布局（具体取决于业务侧如何组合封装）
 - 🧭 丰富交互：
   - 鼠标悬停 Tooltip（展示占比、采样数、绝对值等）
   - 点击放大 / 回退、滚轮缩放、拖拽平移
@@ -24,6 +24,12 @@
   - 支持通过 `i18n` 精细覆盖各项文案
 - 🧱 基于 **Flamebearer** 数据结构，兼容 Pyroscope / Grafana Pyroscope 的 profile 数据
 - 🧩 以 React 组件的方式独立封装，可作为「黑盒区域」嵌入任意业务页面
+- 💠 主题适配：
+  - 支持 `dark / light / kylin` 三种颜色模式（通过 `colorMode` / `Box` 的 `theme` 控制）
+  - `kylin` 主题贴近 Ant Design 白底风格
+- 🧮 Diff 模式表格增强：
+  - **Diff 表格支持独立滚动容器 + 表头 sticky 固定**
+  - 默认最大高度可通过 CSS 变量 `--kylin-flamegraph-table-max-height` 配置（例如 1000px / 2000px）
 
 ---
 
@@ -64,7 +70,6 @@ yarn add @kylincloud/flamegraph
   * `DefaultPalette`
   * `convertJaegerTraceToProfile`
   * `diffTwoProfiles`
-
 * i18n 导出：
 
   * `flamegraphDefaultMessages`
@@ -97,7 +102,7 @@ import {
 } from '@kylincloud/flamegraph'
 ```
 
-> ✅ 提示：
+> 提示：
 >
 > * 对于浏览器端渲染：只要导入任意来自 `@kylincloud/flamegraph` 的组件，样式就会自动注入。
 > * 对于 SSR 场景：Node 侧入口为 `dist/index.node.cjs.js` / `dist/index.node.esm.js`，不会在服务端注入样式，CSS 注入会在浏览器端 hydration 时发生。
@@ -134,7 +139,7 @@ export default function App() {
     <div style={{ height: 600 }}>
       <FlamegraphRenderer
         profile={simpleProfile}
-        // 可选：主题
+        // 可选：颜色模式（inner state 会将它挂到 data-flamegraph-color-mode 上）
         // colorMode="light" | "dark" | "kylin"
       />
     </div>
@@ -142,6 +147,23 @@ export default function App() {
 }
 ```
 
+在麒麟系前端（AntD 白色背景）中，推荐：
+
+```tsx
+<FlamegraphRenderer
+  profile={simpleProfile}
+  colorMode="kylin"
+/>
+```
+
+并在外层使用：
+
+```tsx
+<Box theme="kylin">
+  <FlamegraphRenderer profile={simpleProfile} colorMode="kylin" />
+</Box>
+```
+
 ### 3.3 语言与 i18n 使用方式
 
 `FlamegraphRenderer` 内部已经内置了 i18n 能力，支持两种层级的使用方式。
@@ -173,6 +195,12 @@ type FlamegraphRendererProps = {
    *   不影响 Toolbar 中的视图切换（仍可切换到 Sandwich 视图）
    */
   sandwich?: boolean
+
+  /**
+   * 颜色模式（配合 CSS 变量）
+   * - 'dark' | 'light' | 'kylin'
+   */
+  colorMode?: 'dark' | 'light' | 'kylin'
 }
 ```
 
@@ -230,15 +258,15 @@ function OverrideExample({ profile }: { profile: any }) {
 }
 ```
 
-> 规则说明：
->
-> * 若 **显式传入 `i18n`**，则以 `i18n` 为准，不再根据 `locale` / 浏览器语言推断。
-> * 若未传入 `i18n`：
->
->   * `locale` 未指定时视为 `"auto"`，组件会读取 `navigator.language` 进行选择：
->
->     * `zh*` → 使用内置中文文案 `flamegraphZhCNMessages`
->     * 其他 → 使用内置英文文案 `flamegraphDefaultMessages`
+规则说明：
+
+* 若 **显式传入 `i18n`**，则以 `i18n` 为准，不再根据 `locale` / 浏览器语言推断。
+* 若未传入 `i18n`：
+
+  * `locale` 未指定时视为 `"auto"`，组件会读取 `navigator.language` 进行选择：
+
+    * `zh*` → 使用内置中文文案 `flamegraphZhCNMessages`
+    * 其他 → 使用内置英文文案 `flamegraphDefaultMessages`
 
 ### 3.4 Sandwich 视图入口开关
 
@@ -259,19 +287,19 @@ function OverrideExample({ profile }: { profile: any }) {
 />
 ```
 
-> 说明：
->
-> * `sandwich` 只控制「右键菜单入口」，不会关闭整个 Sandwich 视图能力。
-> * 当 `sandwich={false}` 时：
->
->   * 右键菜单不再显示 「Open in Sandwich View」
->   * 如 Toolbar 中仍暴露视图切换控件，用户依然可以手动切换到 `Sandwich` 视图。
+说明：
+
+* `sandwich` 只控制「右键菜单入口」，不会关闭整个 Sandwich 视图能力。
+* 当 `sandwich={false}` 时：
+
+  * 右键菜单不再显示 「Open in Sandwich View」
+  * 如 Toolbar 中仍暴露视图切换控件，用户依然可以手动切换到 `Sandwich` 视图。
 
 ### 3.5 高级用法：手动使用 `FlamegraphI18nProvider`
 
 在绝大部分场景，**只使用 `FlamegraphRenderer` 的 `locale` / `i18n` 即可**，它内部已经自动套了一层 `FlamegraphI18nProvider`。
 
-如果希望在**更高层共享同一套翻译配置**（例如一整个页面内的多处 Flamegraph 统一使用某套覆盖文案），也可以手动使用 Provider：
+如果希望在更高层共享同一套翻译配置（例如一整个页面内的多处 Flamegraph 统一使用某套覆盖文案），也可以手动使用 Provider：
 
 ```tsx
 import React from 'react'
@@ -301,10 +329,10 @@ export default function App() {
 }
 ```
 
-> 建议：
->
-> * 简单场景：直接在 `FlamegraphRenderer` 上使用 `locale` / `i18n`。
-> * 多个火焰图共享同一套深度自定义文案时，再考虑使用 `FlamegraphI18nProvider`。
+建议：
+
+* 简单场景：直接在 `FlamegraphRenderer` 上使用 `locale` / `i18n`。
+* 多个火焰图共享同一套深度自定义文案时，再考虑使用 `FlamegraphI18nProvider`。
 
 ---
 
@@ -323,11 +351,14 @@ type FlamebearerProfile = {
     maxSelf?: number
     sampleRate?: number
     units?: 'samples' | 'bytes' | 'ns' | string
+    leftTicks?: number
+    rightTicks?: number
+    format?: 'single' | 'double'
   }
   metadata?: {
     appName?: string
     spyName?: string
-    format?: 'single' | 'double' | 'diff' | string
+    format?: 'single' | 'double' | string
     from?: number
     until?: number
     [key: string]: any
@@ -341,6 +372,7 @@ type FlamebearerProfile = {
   * **单视图**：每 4 个数字为一组
   * **Diff 视图**：每组数字扩展为左/右 profile 的宽度及差分值（通常 7 个）
 * `units` / `sampleRate`：用于 Tooltip 和表格中做单位换算、展示总时间等
+* `leftTicks` / `rightTicks`：Diff 模式下左、右 profile 的总采样数，用于计算百分比
 
 在麒麟内部项目中，也可以在后端将自定义的树型数据转换为上述格式，再传递给组件。
 
@@ -350,12 +382,13 @@ type FlamebearerProfile = {
 
 如果 profile 为 Diff 格式（用于比较「基线」与「当前」两段 profile），通常会：
 
-* 在 `metadata.format` 中标注 diff 格式（例如 `'diff'`）
+* 在 `flamebearer.format` 中标注 `'double'`
 * 在 `flamebearer.levels` 中扩展出：
 
   * 左 profile（基线）的宽度 / 值
   * 右 profile（比较）的宽度 / 值
   * 差分值（正负表示变慢 / 变快）
+* 在 `flamebearer.leftTicks` / `rightTicks` 中提供两端总采样数，用于计算百分比
 
 前端典型表现：
 
@@ -366,10 +399,12 @@ type FlamebearerProfile = {
 * 表格区域：
 
   * 展示 `Symbol / Baseline / Comparison / Diff` 列
-  * 百分比 + 绝对值组合展示（例如 `12.3% (12 ms)`）
+  * Diff 列以百分比形式展示变化：`(+12.34%)` / `(-7.89%)`
+  * 对于只在右侧出现的函数显示 `NEW` 文案（可通过 `messages.diffNew` 定制）
+  * 对于只在左侧出现的函数显示 `REMOVED` 文案（可通过 `messages.diffRemoved` 定制）
 * Tooltip：
 
-  * 展示 `% of total / value / samples` 等信息
+  * 展示 `% of total / value / samples` 等信息，并同时展现左右两侧的数值对比
 
 具体字段与含义请以实际 `DiffProfile` / `DiffNode` 类型定义及实现为准。
 
@@ -377,21 +412,93 @@ type FlamebearerProfile = {
 
 ## 6. 样式与主题
 
+### 6.1 核心样式
+
 * 核心样式源文件为：`src/sass/flamegraph.scss`
 * 浏览器入口 `src/index.tsx` 中默认会导入该样式文件：
 
   * `import './sass/flamegraph.scss'`
-* Rollup + PostCSS + Sass 会在构建时将其编译为 CSS，并在运行时自动注入 `<style>` 标签，不再额外生成独立的 `dist/index.css` / `dist/index.esm.css` 等文件。
+* Rollup + PostCSS + Sass 会在构建时将其编译为 CSS，并在运行时自动注入 `<style>` 标签，不再额外生成独立的 `dist/index.css` 等文件。
 
 `package.json` 中已将 `*.css` / `*.scss` 标记为 `sideEffects`，确保在使用方构建时不会被错误 Tree-Shaking 掉。
 
 默认情况下，组件会包裹在一个自定义元素 `<pyro-flamegraph>` 内部，在 `flamegraph.scss` 中会对该元素设置基础字体、颜色等样式，方便在不同业务系统中保持一致的视觉基线。
 
-如需与业务系统整体主题统一，可以：
+### 6.2 主题与 CSS 变量
+
+主题相关的 CSS 变量主要定义在：
+
+* `src/sass/_css-variables.scss`
+
+关键点：
 
-* 在外层容器控制背景色、边框、圆角等
-* 通过 CSS 变量或自定义类名覆盖部分颜色 / 字体
-* 如有必要，可在上层再封装一层组件，对内部 props 进行约束与二次包装
+* **暗色主题**：由 `:root` / `[data-theme='dark']` / `[data-flamegraph-color-mode='dark']` 控制
+* **浅色基础主题**：`[data-theme='light']` / `[data-theme='kylin']` / `[data-flamegraph-color-mode='light']` / `[data-flamegraph-color-mode='kylin']`
+* **Kylin 主题微调**：`[data-theme='kylin']` / `[data-flamegraph-color-mode='kylin']` 会在浅色基础上做进一步调整（更接近 Ant Design）
+
+`Box` 组件会在自身 `div` 上挂载：
+
+```html
+<div data-theme="dark" | "light" | "kylin">...</div>
+```
+
+`FlamegraphRenderer` 会在内部元素上挂载：
+
+```html
+<div data-flamegraph-color-mode="dark" | "light" | "kylin">...</div>
+```
+
+你可以通过在外层容器覆盖部分变量来自定义主题，例如：
+
+```css
+/* 调整 Kylin 主题下的表格高亮行与 header 底色 */
+.kylin-pyroscope-flamegraph {
+  --ps-table-highlight-row-bg: #e6f4ff;
+  --ps-table-highlight-row-text: #000000;
+  --ps-table-header-bg: #ffffff;
+  --ps-table-header-text: #000000;
+}
+```
+
+### 6.3 Diff 模式表格滚动与表头固定
+
+在差分火焰图（`flamebearer.format === 'double'`）下，内部会给表格容器增加类似结构：
+
+```html
+<div class="flamegraph-table-wrapper flamegraph-table-wrapper--double">
+  <div class="flamegraph-table-scroll">
+    <table class="flamegraph-table"> ... </table>
+  </div>
+</div>
+```
+
+行为说明：
+
+* `.flamegraph-table-scroll`：
+
+  * 具有最大高度与 `overflow-y: auto`，只在 Diff 模式下生效
+  * 默认最大高度通过 CSS 变量控制：
+
+    * `max-height: var(--kylin-flamegraph-table-max-height, 1000px);`
+* `thead`：
+
+  * 使用 `position: sticky; top: 0;` 固定在滚动容器顶部
+  * 使用 `--ps-table-header-bg` / `--ps-table-header-text` 控制表头底色和文字颜色，确保不透明，避免滚动时内容透出
+
+在业务侧可以通过覆盖 CSS 变量调整体验，例如：
+
+```css
+/* 将 Diff 表格最大高度调整为 2000px */
+.kylin-pyroscope-flamegraph {
+  --kylin-flamegraph-table-max-height: 2000px;
+}
+
+/* 自定义浅色主题下的 header 底色 */
+.kylin-pyroscope-flamegraph {
+  --ps-table-header-bg: #fafafa;
+  --ps-table-header-text: #000000;
+}
+```
 
 ---
 
@@ -469,26 +576,27 @@ type FlamebearerProfile = {
   pnpm run lint
   ```
 
-> ✅ 说明：
->
-> * 旧版本使用的 esbuild 构建脚本已移除，当前仓库仅保留 rollup 方案，避免多套构建链路带来的维护成本。
-> * 若需要在 CI 中校验，可至少执行：
->
->   * `pnpm run type-check`
->   * `pnpm run build`
+说明：
+
+* 旧版本使用的 esbuild 构建脚本已移除，当前仓库仅保留 Rollup 方案，避免多套构建链路带来的维护成本。
+* 若需要在 CI 中校验，可至少执行：
+
+  * `pnpm run type-check`
+  * `pnpm run build`
 
 ---
 
 ## 8. 与上游项目的关系
 
-* 本项目在工程结构与数据格式上与 Pyroscope 的 flamegraph 组件保持高度兼容
+* 本项目在工程结构与数据格式上与 Pyroscope 的 flamegraph 组件保持高度兼容。
 * 主要差异点集中在：
 
-  * 包名与发布渠道：使用 `@kylincloud/flamegraph`
-  * 构建链路调整为 Rollup + PostCSS + Sass，自动注入样式，兼容 ESM / CJS / Node 侧入口
-  * 在类型声明、主题适配与 i18n 导出上进行了补充，便于在 TypeScript 环境与多语言环境中使用
-  * 增加了 Sandwich 视图入口开关 `sandwich`，满足不同产品界面对交互复杂度的差异化需求
-  * 后续可能增加针对麒麟项目的定制功能（如与内部监控体系联动）
+  * 包名与发布渠道：使用 `@kylincloud/flamegraph`。
+  * 构建链路调整为 Rollup + PostCSS + Sass，自动注入样式，兼容 ESM / CJS / Node 侧入口。
+  * 在类型声明、主题适配与 i18n 导出上进行了补充，便于在 TypeScript 环境与多语言环境中使用。
+  * 增加了 Sandwich 视图入口开关 `sandwich`，满足不同产品界面对交互复杂度的差异化需求。
+  * 针对麒麟内部项目新增 `kylin` 主题，适配 Ant Design 风格界面，并在 Diff 表格中增加了独立滚动 / sticky 表头等易用性增强。
+  * 后续可能增加更多与内部监控体系 / 智算平台联动的定制功能。
 
 如需回溯或对比实现细节，可以参考源码中的注释与 commit 记录。
 
@@ -505,9 +613,9 @@ type FlamebearerProfile = {
 
 建议遵循：
 
-1. 所有 PR 保持 `pnpm run type-check` 与 `pnpm run lint` 通过
-2. 尽量避免破坏现有公开 API；如有必要，务必在 `CHANGELOG.md` 与本 README 中标注
-3. 对关键交互（如 Diff 视图、搜索、高亮、Sandwich 视图）补充最小可复现示例或 demo 代码
+1. 所有 PR 保持 `pnpm run type-check` 与 `pnpm run lint` 通过。
+2. 尽量避免破坏现有公开 API；如有必要，务必在 `CHANGELOG.md` 与本 README 中标注。
+3. 对关键交互（如 Diff 视图、搜索、高亮、Sandwich 视图、Diff 表格滚动）补充最小可复现示例或 demo 代码。
 
 ---
 
@@ -515,5 +623,5 @@ type FlamebearerProfile = {
 
 本项目使用 **Apache-2.0** 许可证发布。
 
-如在外部开源，请确保保留上游版权与许可证声明，并补充 @kylincloud 的版权信息。
+如在外部开源，请确保保留上游版权与许可证声明，并补充 `@kylincloud` 的版权信息。
 

package/dist/ProfilerTable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProfilerTable.d.ts","sourceRoot":"","sources":["../src/ProfilerTable.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAU,SAAS,EAAiB,MAAM,OAAO,CAAC;AAChE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAsB,WAAW,EAAE,MAAM,UAAU,CAAC;AAe3D,OAAO,EAAoB,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AA2IvF,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,iBAAiB,EAC1B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,YAAY,CAAC,OAAO,KAAK,CAAC,EACjC,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,GACf,KAAK,CAAC,aAAa,CA4BrB;AAqMD,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,QAAQ,CAAC;IAClB,oBAAoB,EAAE,CAAC,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5D,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAE5B,YAAY,EAAE,SAAS,CAAC,uBAAuB,CAAC,CAAC;CAClD;AA2FD,QAAA,MAAM,aAAa,sEA+BjB,CAAC;AAEH,eAAe,aAAa,CAAC"}
+{"version":3,"file":"ProfilerTable.d.ts","sourceRoot":"","sources":["../src/ProfilerTable.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAU,SAAS,EAAiB,MAAM,OAAO,CAAC;AAChE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAsB,WAAW,EAAE,MAAM,UAAU,CAAC;AAe3D,OAAO,EAAoB,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AA2IvF,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,iBAAiB,EAC1B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,YAAY,CAAC,OAAO,KAAK,CAAC,EACjC,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,GACf,KAAK,CAAC,aAAa,CA4BrB;AAqMD,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,QAAQ,CAAC;IAClB,oBAAoB,EAAE,CAAC,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5D,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAE5B,YAAY,EAAE,SAAS,CAAC,uBAAuB,CAAC,CAAC;CAClD;AA2FD,QAAA,MAAM,aAAa,sEA4CjB,CAAC;AAEH,eAAe,aAAa,CAAC"}